ajanaku1/policydiff-relay

# PolicyDiff Relay：针对既有指导意见的策略变更事件响应 PolicyDiff Relay 旨在找出因策略更新而变得不安全的解答，将每项发现路由给人工审核人员，并跟踪修正进度，直到接收人确认收到。 [](https://www.typescriptlang.org/) [](https://react.dev/) [](https://base44.com/) [](#testing) [](LICENSE)  ## 目录 - [PolicyDiff Relay 的功能](#what-policydiff-relay-does) - [在线演示](#live-demo) - [演示流程](#demo-journey) - [功能特性](#features) - [界面截图](#screenshots) - [技术栈](#technology) - [系统架构](#architecture) - [安全模型](#security-model) - [本地运行](#running-locally) - [Base44 配置](#base44-setup) - [测试](#testing) - [项目结构](#project-structure) - [已知限制](#known-limitations) - [许可证](#license) ## PolicyDiff Relay 的功能 在员工已经根据某份源文档回答了问题之后，该文档的内容可能会发生变化。文档有了新版本，但基于旧版本的解答依然存在于邮件、工单或案件记录中。 PolicyDiff Relay 会针对确切的策略版本及其引用的条款记录每一次解答。当加入白名单的 Google Doc 发生更改时，应用会导出新内容，存储去重后的版本，比较条款，并仅对可能受该变更影响的指导意见进行重放。模型会提出结构化的发现，而修正则由人工进行审批。 目前的 MVP 使用一份 Google Doc、一个共享的 Gmail 发件人、一个组织以及虚构的接收人数据。 ## 在线演示 [在 Base44 上打开 PolicyDiff Relay](https://policydiff-relay-8292a74a.base44.app)。 使用分配的审核人员或策略管理员账户登录以打开控制室。 ## 演示流程 面向法官的流程大约可在 90 秒内完成： 1. 以策略审核人员的身份登录。 2. 打开从 v4 到 v5 的资格策略对比。 3. 在影响范围图中选择受影响的红色节点。 4. 阅读先前的解答、已更改的条款、原因说明以及修正草案。 5. 批准该修正。后端将重新验证该发现，并创建一个锁定的交付记录。 6. 通过已连接的 Gmail 账户发送修正。 7. 打开接收人链接并确认收到。 8. 通过 Base44 实时功能查看补救账本的更新。 9. 询问 Policy Ops 为什么不确定的发现被阻止了。 10. 导出私有审计包。 绿色的发现依然有效，因为其引用的条款没有改变。琥珀色的发现保持不确定状态，因为策略未定义裁定该发现所需的工作人员分类。 ## 功能特性 - 以源文件和内容哈希为键的不可变策略版本 - 条款级别的标准化与实质性变更候选 - 在模型推理之前进行确定性的重放过滤 - 带有引用证据的受影响、仍然有效和不确定的审核状态 - 由审核人员拥有的审批和服务器端的修正重新验证 - 防止重复 Gmail 交付的发送租约 - 经过哈希处理、过期且仅限一次使用的确认 token - 关于发现、审批、交付、任务和确认的实时更新 - 受限的员工 Agent，可以解释发现或创建审核人员的任务 - 通过五分钟有效期的签名 URL 暴露的私有审计文件 ## 界面截图 | 桌面端控制室 | 移动端审核 | |---|---| |  |  | 该界面采用了选定的证据制图方向。变更后的条款位于轨道中心。先前的解答按分类显示在周围，而证据面板和补救账本则保留了审核痕迹。 ## 技术栈 | 层级 | 技术 | |---|---| | 前端 | React 19, TypeScript, Vite | | 后端 | Base44 Deno functions | | 数据与访问 | Base44 entities, RLS 和字段级规则 | | 身份验证 | Base44 Auth 和 User extensions | | 源连接器 | Base44 共享 Google Drive 连接器 | | 交付连接器 | Base44 共享 Gmail 连接器 | | 模型调用 | Base44 `InvokeLLM` 结构化输出 | | 实时通信 | Base44 entity subscriptions | | Agent | 具有两个白名单工具的 Base44 `policy_ops` agent | | 审计存储 | Base44 私有文件和签名 URL | | 托管 | Base44 站点托管 | | 测试 | Node test runner 和严格的 TypeScript | ## 系统架构 ``` Google Doc file.update | v ingestPolicyVersion export -> canonicalize -> hash -> deduplicate | v extractPolicyClauses -> comparePolicyVersions | v policy admin activates version | v createReplayJob -> deterministic filters -> replayGuidance | v Finding: affected | still_valid | uncertain | v human approval -> locked Delivery -> shared Gmail | v single-use acknowledgement -> realtime remediation ledger | +----> private audit packet | +----> restricted Policy Ops agent ``` Base44 是系统的记录源和执行边界。浏览器可以读取 RLS 允许的记录并调用指定的函数。它不能直接批准发现、创建交付记录、发送邮件、确认 token 或创建审计包。 ### 数据图 ``` Organization +-- User +-- Policy +-- PolicyVersion +-- PolicyClause +-- PolicyDelta +-- ReplayJob +-- ReplayItem +-- Finding +-- ReviewTask +-- Approval +-- Delivery +-- DeliverySecret +-- Acknowledgement +-- Guidance +-- AuditPacket +-- OperationEvent ``` ### 受信任的函数 | 函数 | 职责 | |---|---| | `seedDemoWorkspace` | 配备一个幂等的 v4 基准和三个虚构的引用解答 | | `seedDemoIncident` | 当连接器自动化不可用时，构建确定性的 v5 事件 | | `loadControlRoomData` | 返回按角色过滤的控制室记录集 | | `ingestPolicyVersion` | 接收 Drive 事件，导出白名单内的 Doc，并对内容进行去重 | | `extractPolicyClauses` | 生成经过 schema 验证的条款并保存其证据 | | `comparePolicyVersions` | 构建一个明确的旧/新版本增量 | | `activatePolicyVersion` | 移动策略指针并开始重放 | | `createReplayJob` | 创建一个持久的重放任务 | | `replayGuidance` | 应用确定性范围并存储结构化的候选发现 | | `createGuidance` | 根据活动版本和有效引用记录一个解答 | | `approveFinding` | 强制执行审核人员角色，认领该发现，并将一个交付任务排入队列 | | `sendCorrection` | 重新验证聚合对象，认领发送任务，并调用 Gmail 一次 | | `reconcileDeliveries` | 处理到期工作，并将有歧义的发送租约隔离 | | `acknowledgeDelivery` | 验证 token 并仅记录一次确认 | | `createAuditPacket` | 将组织记录轨迹写入私有文件 | | `explainFinding` | 返回经过脱敏处理、受证据约束的解释 | | `createReviewerTask` | 创建一个去重的人工任务 | ## 安全模型 每个工作流实体都包含 `organization_id`。RLS 会将其与经过身份验证的用户的组织进行比较，然后检查用户的策略角色。 受信任的工作流记录拒绝客户端直接创建、更新和删除。 字段级规则会隐藏： - 策略版本源文本 - 接收人姓名和电子邮件地址 - Gmail 消息标识符 - 确认指纹和 token 哈希 - 连接器详细信息和私有文件 URI UI 显示的是虚构的指导意见标签，而不是接收人的真实身份。发送函数仅在其重新加载已批准的交付聚合对象之后，才通过其服务角色读取接收人信息。 ### 交付安全 交付的幂等键将审批、指导意见和修正版本绑定在一起。 比较并设置（compare-and-set）状态转换会将 `queued` 或 `retry_wait` 认领为 `sending`。并发调用者无法同时拥有该认领。有歧义的网络结果将保持被认领状态以进行对账，而不是触发盲目的重新发送。 ### 确认安全 公共 token 是通过服务器密钥派生的。只存储其哈希值。Token 会过期，只能使用一次，并绑定到一个交付记录上。重放尝试将被拒绝。 ## 本地运行 ### 前置条件 - Node.js 22 或更高版本 - npm - 用于后端身份验证工作的 Base44 账户 - 用于连接器流程的 Google Workspace 访问权限 ### 安装与启动 ``` npm install npm run dev ``` 打开 [http://localhost:5173](http://localhost:5173)。 当没有可用的 Base44 会话时，本地开发环境会回退到带有清晰标签的虚构数据快照。生产构建绝不会使用该模拟数据。 ### 可用命令 | 命令 | 用途 | |---|---| | `npm run dev` | 启动 Vite 开发服务器 | | `npm run build` | 在 `dist/` 中创建生产站点 | | `npm run package:base44` | 打包独立的 Base44 function 部署构建产物 | | `npm run deploy:base44` | 打包并部署已链接的 Base44 应用 | | `npm run preview` | 在本地提供生产构建的服务 | | `npm test` | 运行单元、集成、授权和契约测试 | | `npm run typecheck` | 检查后端和前端的 TypeScript 项目 | | `npx base44 types generate` | 为 SDK 重新生成实体和函数名称 | ## Base44 配置 ### 1. 身份验证并链接应用 ``` npx base44 login npx base44 link npx base44 types generate ``` `base44/.app.jsonc` 包含本地应用链接，并且会被 Git 忽略。 ### 2. 配置身份验证 该代码库启用了 Base44 的用户名和密码登录。用户记录需要这些扩展： ``` organization_id policy_role: policy_admin | reviewer | auditor | staff ``` 这些字段是客户端只读的。请通过管理设置路径分配它们，而不是通过 `auth.updateMe`。 ### 3. 授权连接器 Google Drive 需要只读访问权限。Gmail 需要仅发送权限。 ``` npx base44 connectors initiate \ --integration-type googledrive \ --scopes https://www.googleapis.com/auth/drive.readonly npx base44 connectors initiate \ --integration-type gmail \ --scopes https://www.googleapis.com/auth/gmail.send ``` 在激活之前，将 Drive 自动化的 `resource_id` 设置为确切的 Google Doc 文件 ID。在确认该 ID 之前，请保持 `allowlisted_policy_file_update` 为不活动状态。 ### 4. 配置虚构基准 部署后端资源后，以策略管理员身份登录并运行： ``` printf '%s\n' \ 'console.log(await base44.functions.invoke("seedDemoWorkspace", { source_file_id: "YOUR_GOOGLE_DOC_FILE_ID", recipient_email: "YOUR_DEMO_INBOX" }))' \ | npx base44 exec ``` 该函数可以安全地重复执行。它会创建或重用一个 v4 策略版本、三个条款和三个虚构的指导意见记录。只有受影响的记录会使用提供的演示收件箱。实际的 Drive 事件仍然会创建 v5 并启动比较流水线。 在设置之前，将 [`demo/eligibility-policy-v4.txt`](demo/eligibility-policy-v4.txt) 粘贴到共享的 Google Doc 中。将其更改为 [`demo/eligibility-policy-v5.txt`](demo/eligibility-policy-v5.txt) 即可触发该事件。 ### 5. 设置服务器密钥 ``` npx base44 secrets set \ ACKNOWLEDGEMENT_SECRET="$(openssl rand -hex 32)" \ PUBLIC_APP_URL="https://your-base44-site.example" ``` 这些值属于 Base44 密钥。请勿将它们添加到客户端环境文件中。 ### 6. 创建控制面板 Workflows 从 [`base44/workflows/setup-prompt.md`](base44/workflows/setup-prompt.md) 创建七个控制面板 Workflows（包括 Drive 的 `file.update` Workflow）。在函数、密钥和连接器授权准备就绪之前，请保持它们为不活动状态。 ### 7. 部署前验证 ``` npm test npm run typecheck npm run build npm run package:base44 npx base44 types generate ``` 部署资源或站点会更改已链接的 Base44 应用。在运行以下命令之前，请遵循项目的审批流程： ``` npm run deploy:base44 ``` ## 测试 该套件在 26 个文件中包含 102 个通过的测试。 ``` npm test ``` 测试覆盖范围包括： - 实体 RLS 和字段级规则 - 经过身份验证的角色检查 - Drive 白名单和内容去重 - 条款和重放输出契约 - 明确的版本绑定 - 人工审批 - 过期聚合拒绝 - 并发交付认领 - 有歧义的 Gmail 结果 - 对账 - Token 过期和重放拒绝 - 受限的 Agent 工具 - 私有审计导出 - 前端 Base44 和实时通信边界 - 审核和交付 UI 的状态转换 有关风险矩阵和与每个案例相关的测试文件，请参见[阶段 4 强化证据](reports/phase-4-hardening.md)。 ## 项目结构 ``` . ├── base44/ │ ├── agents/ # Restricted Policy Ops agent │ ├── auth/ # Base44 authentication settings │ ├── connectors/ # Drive and Gmail scope declarations │ ├── entities/ # Schemas, RLS, and field-level rules │ ├── functions/ # Trusted workflow transitions │ └── shared/ # Hashing, policy, delivery, and workflow logic ├── demo/ # Fictional policy source and 90-second runbook ├── docs/images/ # Verified desktop and mobile screenshots ├── reports/ # Architecture, data model, gaps, and hardening notes ├── src/ │ ├── api/ # Base44 client and control-room gateway │ ├── components/ # Evidence Cartography interface │ ├── data/ # Development-only fictional snapshot │ ├── domain/ # Pure frontend workflow decisions │ ├── hooks/ # Data loading, actions, and realtime subscriptions │ └── types/ # Control-room view types ├── tests/ ├── integration/ # Authorization and hosted-boundary tests └── unit/ # Policy, delivery, ingestion, and UI logic tests └── video/ # Demo script, live captures, renderer, and exports ``` ## 已知限制 - Google Drive 和 Gmail 在每个已部署的工作区中都需要经过授权的共享连接。 - Drive Workflow 必须保持绑定到确切的已在白名单中的 Google Doc。 - 审计下载链接将在五分钟后过期。 - 该 MVP 仅涵盖一份源文档、一个发件人和一个组织。 - 模型仅提出审核候选。它不会做出策略决策。 - 当前的证据别名是指导意见标签，而不是接收人的真实身份。 在实施过程中发现的两个 Base44 文档空白记录在 `reports/` 中。这些权宜之计将实体自动化排除在关键路径之外，并显式地解包已记录的连接器 payload。 ## 许可证 [MIT](LICENSE)

标签：MITM代理, React, Syscalls, TypeScript, 人机协同, 安全插件, 工作流管理, 政策合规, 文本差异比对, 自动化攻击