From 2cc00da9e005d2c82848d7bab3ea403a4683a10c Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 13 Oct 2026 09:30:34 +0000 Subject: [PATCH] Define the I1 permission and public extension contract Why: separate protected system actions from project authority and freeze the approved identity and resource boundaries. Evidence: SELF document check recorded by Dev evidence; approved plan digest retained and fixed-base core rules preserved. Impact: contract and navigation only; provider implementations, multi-role migration and deployment remain later increments. Refs: IAM plan r1 U1; Agent-System-Dev feature/iam-i1-permission-boundaries --- .../2026-10-13-iam-i1-permission-contract.md | 163 ++++++++++++++++++ docs/proposals/INDEX.md | 5 + 2 files changed, 168 insertions(+) create mode 100644 docs/proposals/2026-10-13-iam-i1-permission-contract.md diff --git a/docs/proposals/2026-10-13-iam-i1-permission-contract.md b/docs/proposals/2026-10-13-iam-i1-permission-contract.md new file mode 100644 index 0000000..2a43a91 --- /dev/null +++ b/docs/proposals/2026-10-13-iam-i1-permission-contract.md @@ -0,0 +1,163 @@ +# IAM I1 权限边界与公开扩展合同 r1 + +负责人：weichen；编制：Codex；更新时间：2026-10-13。 +依据：[用户、职位角色与分层权限统一方案 r1](2026-10-13-identity-role-permission-plan.md) +（Documents `a088809`，原文 SHA256 `39b8e9a6e078dc509bd80118c1807ce6ed23e4466e5902b51f4bfa255d55c0a1`）。 +用户已批准该方案并授权 I1＝U1–U2；本次终点为本地实施与验证后人工评审，未授权推送、PR、合入、迁移或部署。 +本合同为 U1 产物，冻结已批准语义与提供者／消费者责任；新增公开接口仍须对应模块实现、固定版本及合同验证，不能据此宣称能力已提供。 +源码、业务测试及运行验收结果以 I1 任务卡的工具收据为准；本文不复制测试结果。 + +## 1. 当前增量与最终目标 + +最新用户裁定取代旧“管理员拥有全部业务权限”“创建者不受职位 cap”“每人仅一个生效职位”的现行解释。 +历史会议、原方案、旧批准记录和 `.tmp` 原件保留；旧结论只用于解释历史行为。 +系统管理员管理系统与授权主数据；读取他人业务内容必须有具体项目和资源授权。 +职位支持一职多人、一人多职，项目明确选用有效职位绑定；新任命不自动增加既有项目权限。 +通用职位、绑定、默认／上限与系统授权迁至 Backend 是已批准设计；RDM 保留项目成员、项目选用绑定、项目覆盖、资源及文档职责／状态。 + +| 层 | I1 范围 | 后续范围 | +|---|---|---| +| 文档 U1 | 需求裁定、动作目录、角色 cap、隐私、公开扩展申请与验收合同 | 按固定公开版本补提供者／消费者验证 | +| 执行端 U2 | 在现有 RDM 单绑定和旧管理台账上收口可达越权路径；实际结果另见任务卡 | 账号有效态、受控目录及恢复能力 U3；通用职位与多绑定 U4；项目明确选用 U5 | +| UI／Agent／迁移 | 不以文档保存证明能力已就位 | 矩阵、统一工具、完整撤权与数据迁移分别按 U7–U9 授权实施 | + +I1 的 legacy 单绑定适配不是最终多职模型：旧账号至多一个专业角色，项目尚无显式 bindingId 集合。 +已有绑定必须先检查角色有效态、动作定义与 cap，再计算默认／项目覆盖；停用或失效不能回落为无绑定成员默认。 +未绑定旧会员的关系默认只能作为已登记的 legacy 兼容来源，仍受平台 cap、项目关系和资源限制；不能伪装成新的职位绑定或最终模型的资格证明。 +U4/U5 迁移后无有效选用绑定的业务动作默认拒绝；迁移差异须单独评审，不在 I1 静默改造数据。 +旧 RDM 管理台账在 I1 仅为明确系统管理动作的兼容来源，不能生成项目成员关系、业务 grant 或资源 bypass；`Host.IsAdmin()` 同样不能代替业务授权。 +I1 还将当前分发 Host 的平台管理员身份显式适配为上述四项受保护系统动作；必须同时满足认证 actor 与 Host.Owner 一致，不接受 body 的管理员声明，也不把该适配扩展到其他未知动作或业务动作。细粒度系统 grant 的通用权威仍属 U4。 + +## 2. 动作目录与配置主体 + +scope 由受信 `ActionMeta`／权限注册表确定，不接受请求自报 scope，不按字符串前缀推断。 +系统动作只消费系统来源；项目动作限定实际项目；资源读取还须匹配实际资源、分类与读取动作。 +下表为 I1 稳定动作合同。“后续”项仅冻结目录，当前尚未提供相关接口。 + +| actionId | scope | 配置／执行主体 | 附加边界 | +|---|---|---|---| +| `system.roles.manage` | system | 受保护系统管理者 | 角色创建／编辑／停用／读取；不能经项目覆盖获取 | +| `system.roles.assign` | system | 受保护任命者 | 任命在可委派上限内；不能间接授予受保护系统权限 | +| `system.policy.manage` | system | 受保护策略管理者 | 平台 cap 与权限政策；保护最后有效管理者 | +| `system.admin.transfer` | system | 当前有移交资格的系统管理者 | 明确移交目标；旧 `rdm.perm.transfer` 映射此门禁 | +| `project.create` | system | 有明确系统／职位建项 grant 的有效用户 | 创建者管理 cap 资格见 §3；不接受项目 allow | +| `project.archive` | project | 目标项目的合法管理者 | 保留稳定 ID；纠正旧目录误标的 system scope | +| `project.settings` | project | 目标项目创建者／委任管理者或合法获授者 | 仅本项目设置与覆盖；不能进入全局角色、cap 或管理员移交 | +| `member.manage` | project | 本项目合法管理者 | 成员及选用角色管理；不得替他人做本人受限重选 | +| `duty.assign` | project | 本项目合法分配者 | 候选有效成员＋对应资格 cap＋三权异人；分配不代签 | +| `stage.advance` | project | 有阶段推进 grant 的成员 | 阶段准入准出、当前状态 | +| `doc.read` | project | 有读取 grant 的成员 | 文档阶段范围＋受控正文职责／明确资源授权 | +| `doc.write` | project | 有编制资格的指定编制人 | 具体文档、当前状态、冻结版本；不因管理权取得 | +| `doc.publish` | project | 有发布资格及对应职责的成员 | 固定整文版本及已批准状态，不替代批准签字 | +| `review.participate` | project | 有评审资格的指定审核／批准人 | 按具体职责决定可执行动作；只能批注及通过／驳回 | +| `trace.edit` | project | 有追溯编辑 grant 的成员 | 文档层／项目层裁定范围与状态分别检查 | +| `knowledge.publish` | project | 有发布 grant 的成员 | 明确提交／发布；不能借发布读取私人原件 | +| `audit.read` | project | 有明确业务审计 grant 的当前成员 | 独立于正文读取；当前角色动作 cap、平台 cap 与范围均满足 | +| `system.settings.read`／`system.settings.write`及设置子项 | system，后续目录 | 对应系统管理者 | 模型、插件、Agent、检索等设置分项授权 | +| `system.users.view`／`create`／`edit`／`disable`、`credential.recover` | system，后续目录 | 对应账号管理者／恢复提案者 | 编辑资料不能改管理员资格；恢复见 §6 | +| `permission.manage`、`knowledge.read`、`trace.read`、`document.read`／`export`、业务审计导出 | 后续目录，project | 按注册元数据和当前业务关系 | 当前 `doc.*` 等 ID 不静默重命名；新增需公开版本映射 | + +`audit.read` 是 I1 新独立项目动作：必须由合法项目管理者在上限内明确授予，或来自明确配置的角色默认 grant；管理身份本身不提供审计 grant。 +非成员 admin、仅持 `Host.IsAdmin()` 的主体、无审计 grant 的创建者、cap 已收紧的旧获授者均拒绝。 +系统安全日志只披露必要安全动作、结果及不透明对象标识，不能包含业务正文、文件名、项目名、内容摘要或完整业务差异；业务审计仍走 `audit.read`。 + +| 旧入口／元数据 | I1 兼容规则 | +|---|---| +| `rdm.role.create`／`action`／`disable`／`list` | 命令 ID 保留，系统门禁改为 `system.roles.manage` | +| `rdm.role.assign` | 命令 ID 保留，系统门禁改为 `system.roles.assign` | +| `rdm.perm.cap` | 命令 ID 保留，系统门禁改为 `system.policy.manage` | +| `rdm.perm.transfer` | 命令 ID 保留，系统门禁改为 `system.admin.transfer` | +| 旧 `project.archive` scope=system | 目录版本标记改为 project；具体项目重验；旧系统覆盖写法不继续接受 | +| `project.settings` 作为全局门禁 | 不兼容保留；项目 grant 不被翻译成系统 grant | +| 未登记 ID、旧示例 `admin.transfer`／`business-audit.read` | 不是隐式别名；拒绝执行／写入，采用上表稳定 ID 或显式版本映射 | + +## 3. cap、创建者资格与撤权 + +最终系统动作路径为：有效账号 ∩ 受信系统动作 ∩ 平台允许范围 ∩ 受保护规则 ∩ 明确系统 grant 或完整系统职位默认路径；项目覆盖不能参与。 +最终项目动作对每个有效且本项目选用的 binding 建立完整路径： + +`有效成员／管理关系 ∩ 已定义动作 ∩ 平台 cap ∩ 本职位 cap（含范围） ∩ 项目覆盖／当前默认 ∩ 资源关系 ∩ 阶段／状态 ∩ 文档职责`。 + +至少一条完整路径允许才放行，不拼接不同职位的 grant 与资源范围；平台禁止、项目明确 deny 和资源禁止对所有路径生效。 +`allow` 只能替换默认 grant，不能创造未配置动作或越 cap；`deny` 阻断该成员该项目该动作的全部路径；`inherit` 使用当前默认。 +停用、解绑、换岗、cap 收紧、账号停用和成员移除后重验当前资格；遗留 allow 不能复活旧权。 +创建者关系只提供本项目管理默认，其有效角色 cap 与平台 cap 仍先验；A 创建者不能管理 B，不能读取私人资源或代签。 + +建项前校验创建者角色组合具备 `project.settings`、`member.manage`、`duty.assign` cap 资格；这些角色 default 可关闭，由创建者关系提供项目内管理默认。 +最终创建项目、创建者成员关系及所选 binding 在同一领域事务落地；宿主绑定以可恢复状态和幂等对账处理。 +已有项目遇 cap 收紧保留 `createdBy` 与历史归属，阻断受影响动作并说明等待重新任命；不能扩大 cap 恢复管理。 + +受限“重新选择本人项目职位”是后续独立动作，不复用 `project.settings`：仅当前有效负责人本人，从账号当前有效任命中明确选取具备管理 cap 的 binding，按项目当前版本确认。 +仅此动作可使用尚未被本项目选用的任命；它不改变负责人、不恢复遗留 allow、不清除 deny、不授予资源读取或三权。 +系统任命者不能代选；无合格任命时保持等待。项目内移除最后负责人须保护实际可操作管理资格；系统必要撤权不因这一保护而被阻止。 + +## 4. 资源、正文与审计读取合同 + +认证 actor、资源真实 owner／projectId／resourceId／分类来自执行端受信上下文；客户端标识只能定位对象，不能授予访问。 +本人的私聊、私人原件和个人草稿属于私人资源；在当前账号有效且资源确属本人时按自有资源规则读取，不因放在项目下变为受控正文。 +受控文档正文即使物理由本人生成，也须具体文档职责或明确资源授权、当前项目资格及当前 cap；真实 owner 相等不绕过受控规则。 +审核／批准职责仅开放送审正文与明确关联材料，不开放未分享原件、私聊或私人草稿；分享只授予指定资源的只读能力，不授予编写或签字。 +项目知识只由明确提交／发布产生；成员身份不意味着私人资源或所有受控正文全量可读。 +历史签字、职责与事件保留；历史内容读取依旧使用当前授权，时间点重建不恢复当时权限。 +读取、下载、列表、搜索、stream、模型上下文均遵循同一分类和当前判定；裁剪列表后再返回数量／分页，拒绝不得泄露存在性。 +I1 现有项目聚合审计 DTO 含正文预览，故除 `audit.read` 外还必须具备当前完整项目 `doc.read`；阶段范围受限者不能通过全项目聚合审计取得范围外正文，按资源裁剪的细粒度审计由 U5 完善。具体文档导出检查该文档的 `doc.read` 和阶段范围，不把审计 grant 当成导出 grant。 +I1 私人 pending/rejected 草稿仅提案人可读与决定；知道 proposalId、拥有项目管理权或文档职责都不能采纳／拒绝他人私稿。已采纳正文仍按当前文档读取授权逐项过滤。原件批次确认只限上传者本人，管理台账可披露经当前管理授权限定的业务元数据，不能因此读取或确认私人原件。 + +## 5. 公开扩展：现有能力与四要素申请 + +现有公开面参考 Backend `pkg/extension/extension.go`、`host.go` 与 `surface.txt`，不导入 Backend internal。 +当前 `SurfaceVersion=2.11.0-experimental` 的源码声明不是部署或消费者可用性证明；组合必须核对提供者及消费者实际固定版本。 + +| 现有能力 | 提供者／消费者 | 足够性与边界 | +|---|---|---| +| EXT-18 `AdminProvider.IsAdmin()`／`Request.HostProjectID` | Backend 分发 Host → RDM | 平台管理身份与宿主项目定位；不能证明系统分项授权、账号有效态、RDM 项目关系或业务访问 | +| EXT-19 `AccountLister.ListAccounts(cursor, limit)`，`AccountEntry{Owner,Valid}` | Backend → 授权目录消费者 | 最小身份目录，非资料页；不提供姓名、联系方式、多职绑定或写权；缺能力不允许新增产品路径无校验继续 | +| EXT-8b `ResourceAuthzQuery`／`ResourceAuthorizerV2`／注册口 | Backend 构造受信查询 → RDM 提供策略 → Backend 执行 | 现有六要素为 actor/action/resourceType/resourceId/owner/projectId；读取专用，V2 对域内读权威（含自有命中）；未注册的 V1 回落不能替代 I1 必需的资源限制 | + +以下是 U1 冻结的公开扩展申请四要素，符号为合同草案，I1 不新增导出实现、不更改 surface 版本。 + +| 申请 | 场景 | 希望的公开符号／路径 | 现有注册点为何不足 | 兼容方式 | +|---|---|---|---|---| +| IAM-P 政策与动作目录 | UI／命令／工具需查询 scope、cap、有效绑定、权限解释与版本；角色通用权威迁移后供 RDM 同源判定 | 可选 `PermissionCatalogProvider`、`AuthorizationProvider`；公开目录／判定／解释与授权管理预览提交服务 | `IsAdmin` 只有布尔身份；`ActionMeta` 在 RDM 内部；EXT-8b 仅资源读，无法供系统管理或管理写入事务使用 | 新可选接口及版本化 DTO；旧 Host 不加必实现方法；RDM legacy 适配与新权威切换分别固定版本 | +| IAM-D 受控人员目录 | 项目选人需要稳定身份、有效态和最小辨识字段，系统资料管理需独立授权 | 可选 `AccountDirectoryProvider` 与版本化查询／投影 DTO；既有 EXT-19 保留 | `AccountEntry` 仅 owner+valid，没有字段权限、搜索模式、可披露辨识资料及多职；私自扩展所有账号资料会扩大披露 | 新可选接口；旧 `ListAccounts` 不改变返回隐私范围；不得向旧消费者塞入联系方式 | +| IAM-R 资源与当前政策上下文 | 跨原件／草稿／正文／审计分类，查询当前 policy／duty epoch，撤权影响读面与后台提交 | 新版资源查询／决策 DTO 及可选政策上下文提供者；保留 `ResourceAuthorizerV2` | 六要素无分类、职责／版本／epoch；bool 返回不能携带可披露原因与版本，读适配器不能承担写入事务 | 新版本资源接口或明确 DTO 增补；禁止未知字段零值放行，必需提供者缺失即拒绝；版本协商与双读仅作诊断 | +| IAM-C 账号本人恢复 | 管理者只能提出恢复，账号本人经独立证明才能取得可兑换设密能力 | 公开恢复提案／本人确认／兑换回执合同，隔离恢复凭据与业务会话 | `IsAdmin`、目录、资源授权均不提供本人证明或安全凭据交付，不能用个人资料代替 | 新路径／可选能力，不向普通管理员交付目标账户可兑换 Key；旧不满足证明的线上路径明确拒绝 | + +| DTO | 必须冻结的字段与版本语义 | +|---|---| +| `PermissionDescriptor` | `actionId`、`label`、`description`、`scope`、`resourceTypes`、`group`、`conditions`、`delegationLevel`、`risk`、`descriptorVersion`；稳定 ID 不随改名变化，新增项默认拒绝 | +| 授权查询／解释 | 受信 actor、actionId、资源定位与实际归属、当前状态／版本、选用 binding；输出 allow/deny、可披露 reason、来源链、`authorityEpoch`；解释只限本人或有权管理对象 | +| 目录查询／投影 | 稳定 userId／owner、valid、获授权姓名／登录名／工号／职位投影、cursor/limit、精确／模糊模式及字段／状态过滤、`directoryVersion`；未授权字段不返回、不参与匹配；电话、邮箱、部门、备注只在独立授权资料面披露 | +| 管理 patch／预览 | 固定对象 ID、expectedVersion、authorityEpoch、patch 摘要、幂等键；预览不代替提交授权，非法对象／越 cap／冲突整体拒绝；跨模块写入不冒充单库事务 | +| 资源决策扩展 | 受信分类（私人／发布知识／受控正文／业务审计）、resourceVersion、policyVersion、dutyVersion、authorityEpoch 与决策原因；缺失或不认识分类拒绝，禁止请求自报归属 | + +目录 r1 的 scope 修订不能只改显示标签；执行端必须同时拒绝错误作用域写入。公开版本须同时登记导出面快照、版本号、变更表、提供者／消费者合同及固定组合。 +缺必需能力、未知动作／字段／状态、政策读取失败、归属不一致、过期版本、失效绑定均 fail-closed；不能用 `Host.IsAdmin()`、缓存 allow、V1 粗粒度授权或手填 owner 兜底。 +通用迁移前 legacy 台账只在其声明范围使用；迁移时保留 userId／owner／roleId／projectId／createdBy，禁止双主写入，不生成旧管理员的永久业务 grant，回滚不复活旧越权。 + +## 6. 账号恢复证明与交付 + +普通管理员仅发起恢复提案；本人须使用管理员不能单方改写或取得的既有有效会话确认，或预先建立的本人恢复证明，才取得可兑换设密能力。 +姓名、电话、邮箱、工号均为可选资料，不自动成为恢复证明；新证明建立或更换不能由恢复提案管理员单独完成。 +无独立本人验证条件时拒绝线上恢复，不向普通管理员签发可兑换的目标账户 Key；异常人工恢复由另行批准的 owner 操作处理。 +恢复能力限制为一次消费、目标账号、设密用途与有效期，不生成业务会话；消费后本人使用正式凭证重新认证。 +本合同不证明恢复实现已具备；U3须验证“管理员提出恢复后自行设密接管业务身份”负例，旧路径未收口前 R7 不得闭合。 + +## 7. 验收矩阵与证据边界 + +R1–R20 到 RDM 原 UR／SR 的映射由 RDM `docs/proposals/2026-10-13-iam-i1-contract-adoption.md` 维护，原需求 ID 不重新编号。 + +| 判据 | I1 文档核对 | 行为验收归属 | +|---|---|---| +| 系统动作不可由项目 override 或 `project.settings` 获取 | §2逐动作 scope／旧命令映射 | U2：普通成员合法本项目设置成功，全局角色／cap／移交拒绝 | +| 创建者仍受有效角色 cap，遗留覆盖不越界 | §1／§3 | U2：创建者 cap=false、角色动作未定义、停用／换岗及旧 allow 负例 | +| 管理员无业务身份旁路，审计独立授权 | §2／§4 | U2：admin／Host.IsAdmin 非成员及无 audit grant 拒绝；合法成员 audit grant∩cap 正例 | +| 私人资源与受控正文分开 | §4／EXT-8b 消费边界 | U2 可达路径；U5/U6 统一资源及职责、当前版本完整验收 | +| 一职多人、一人多职、项目明确选用 | §1／§3／IAM-P | U4/U5：新任命不扩既有项目、解绑再任命不复活、完整路径不拼接 | +| 账号目录敏感投影与本人恢复 | §5／§6 | U3：未授权字段不匹配／不返回；管理员不能取得本人兑换凭据 | +| 冻结文档轮次、撤权与迟到事件 | §3／§4／IAM-R | U6/U8：当前职责与 cap 重验；旧卡／Surface／SSE／后台最终提交拒旧 | +| 单权威迁移、版本兼容、完整组合 | §1／§5 | U4/U9：旧→新差异、双主拒绝、当前固定提供者／消费者和制品验收 | + +U1 只检查文档差异、链接、动作与 scope 一致性、R1–R20 追溯及原方案摘要保持；无行为变更，不运行业务测试。 +本地检查来源为 SELF；审核与正式验收须按任务规则同步对象、独立重放并核验 GATE／REPLAY 身份及 SHA。 +公开实现、业务测试、浏览器、真实模型、数据库迁移、服务运行、部署与正式验收均不能用本合同的保存结果代替。 diff --git a/docs/proposals/INDEX.md b/docs/proposals/INDEX.md index fca9033..cd89d1c 100644 --- a/docs/proposals/INDEX.md +++ b/docs/proposals/INDEX.md @@ -6,6 +6,11 @@ ## 先看哪一份 +- [IAM I1 权限边界与公开扩展合同 r1](2026-10-13-iam-i1-permission-contract.md)： + 依据已批准的[用户、职位角色与分层权限统一方案 r1](2026-10-13-identity-role-permission-plan.md) + （Documents `a088809`）冻结系统／项目／资源边界、管理员无业务 bypass、创建者 cap、独立 `audit.read` 与公开扩展四要素。 + 2026-10-13 已授权 I1（U1–U2），终点为本地实施与验证后人工评审；多职、通用角色迁移、资料目录、矩阵及完整运行验收仍按后续单元推进，不以合同保存宣称已交付。 + - [快慢通道展示与动态工作摘要方案 r1.1](2026-10-12-fast-slow-channel-display.md)： 运行卡呈现状态、已完成工作、当前发现与剩余项；四层阅读、阶段成果、来源、异常恢复及 U1–U4。 2026-10-12 方案设计已批准（阶段 1–4）；首批仅 U1；[U1 实施计划 r1](2026-10-12-fast-slow-channel-display-u1-plan.md) 待阶段 5 批准；业务实施和运行验收 NOT_RUN。