# HETA User Center 身份接入路由契约

- Contract Version：3.0
- Audience：负责选择或实施身份接入的编程 Agent
- Scope：选择身份域、取得实施契约并报告验证结果；本文不替代具体身份域的协议契约
- Repository Source：`apps/user-center-portal/docs/integration/identity-routing.md`
- 人类指南：`https://user-center.staging.hetapet.com/guide`
- 门户：`https://user-center.staging.hetapet.com/`

本文中的 `{{...}}` 在门户发布时注入当前部署链接。直接读取仓库源文件时，从目标部署配置或管理员交接包取得这些值，不把占位符当作真实配置。

## 1. Route：逐条调用链选择身份域

先读取目标仓库的协作规则，并调查现有认证、会话、调用方和受保护资源。一个应用包含多种调用链时，分别记录，不把不同主体合并为一个“用户”。

| 可观察场景 | `selected_route` |
| --- | --- |
| 企业成员通过浏览器登录内部应用 | `workforce` |
| 后台系统调用其他受保护资源 | `external-system-governance` |
| 服务调用普通受保护应用或服务 | `external-system-governance` |
| Agent 以自身凭证执行，并需要父级与 Execution 身份 | `agent` |
| 企业外部客户登录外部应用 | `customer` |
| 只需要打开用户管理门户、进入领域管理页或阅读文档 | `none` |

无法从代码、配置或现有文档判断主体和目标资源时，先取得这两个输入；不要依据技术栈、应用名称或显示名称猜测 route。

完成条件：每条需要认证的调用链都记录了发起主体、目标资源、`selected_route` 和选择依据。

## 2. Handoff：取得所选 route 的输入

### `workforce`

适用于企业成员登录内部应用。实施前必须取得：

```text
deployment_environment
contract_url
issuer
client_id
redirect_uri
approved_scopes
```

管理员交付时必须把登记结果映射为下游应用的精确配置，不由接入方自行猜测 Scope：

```text
WORKFORCE_IDENTITY_OIDC_ISSUER=<issuer>
WORKFORCE_IDENTITY_OIDC_CLIENT_ID=<client_id>
WORKFORCE_IDENTITY_OIDC_REDIRECT_URI=<redirect_uri>
WORKFORCE_IDENTITY_OIDC_SCOPES=<approved_scopes>
```

当前门户配置的 Workforce 部署契约：

```text
https://workforce-id.staging.hetapet.com/docs/oidc-agent-guide.md
```

截至 2026-09-02，Workforce 公网契约返回 Contract 3.0，Discovery 精确能力断言已经通过，此前的能力公告冲突已经解除。该结果只证明仿真身份服务的公开契约一致性，不代表具体应用的真实企业微信登录或业务端到端已经完成；精确发布证据只以根 ADR-0011 的最新日期记录为准。

完整读取该契约，再从 `issuer` 读取 OIDC Discovery。具体 Flow、Claims、错误处理和验证矩阵以两者为准。身份映射使用 `(issuer, sub)`；应用内角色、菜单、数据范围和业务操作权限继续由目标应用拥有。

完成条件：六项输入齐全，部署契约与 Discovery 的 Issuer 一致，并已记录目标应用现有认证与会话 seam。

### `external-system-governance`

机器主体、系统身份和后台系统调用不在 User Center 当前身份域内提供新的身份或授权契约；User Center 当前不提供、也不接受新增通用机器身份或系统调用授权。它们属于待建立的独立系统治理控制面；当前承接仓库、负责人和公开接入契约尚未确定。

实施方必须停止 User Center 接入，并记录：

```text
calling_system
target_resource
deployment_environment
audience
minimum_operations
principal_owner
credential_lifecycle
business_owner
```

不得扩展 Workforce Identity、Agent Identity 或 Portal 承载机器身份，不得创建临时系统 Client、伪造 Token 或绕过目标资源验证。

旧机器身份实现已经退役，仓库源码和内部环境实例均已移除。历史退役信息只用于审计，不是可恢复或可复用的接入能力；不得重新创建或复用历史 Issuer、Client Registry、Client ID、Scope、Audience、Realm 或部署入口。证据以根 ADR-0007 为准。

完成条件：明确报告 `selected_route=external-system-governance` 与“当前无可实施契约”，并把上述输入交给系统治理负责人；没有在 User Center 中新增机器身份或系统调用授权能力。

### `agent`

Agent Identity 的 Workforce 父级仿真实例已公开运行，配置 Issuer 为 `https://agent-id.staging.hetapet.com`。父级 Workforce Discovery、Agent HTTPS TLS、公开 Metadata/JWKS/接入指南、管理来源限制和真实 active Workforce 父级登录均已验收。当前部署契约：

```text
https://agent-id.staging.hetapet.com/docs/agent-identity-agent-guide.md
```

完整读取该契约，并从实例 Metadata 的 `service_documentation` 复核同一 URL。当前状态为：

```text
runtime_deployed=true
deployment_available=true
deployment_environment=simulation
identity_verification_mode=live
real_end_to_end_verified=false
```

`deployment_available=true` 只证明 Agent 仿真身份服务可供接入，不表示固定目标业务已经接入或完成端到端验收。产线环境和 Customer 父级实例继续延期；部署证据见根 ADR-0011。

第一期目标只支持 Workforce 企业成员作为唯一父级、父级先授予固定视频脚本工作台 `AgentTargetGrant`、本人当次显式触发和目标资源明确列入白名单的低风险 Agent 操作。Grant 只表示允许接入固定目标，不代表 action、resource 或数据权限。System Principal 父级及定时、事件驱动和后台规则触发的无人值守执行仍延期。

实施方必须从当前部署契约取得精确 Issuer、Metadata URL、Audience、父级 Issuer、Agent 登记和 Execution 输入。Agent 运行方与父级必须完成可核对 public JWK 的 bootstrap handoff；目标业务必须提供 authenticated Execution dispatch seam，把 `agent_id`、`execution_id`、Audience、到期时间和不透明业务关联绑定后交给正确 Agent。Agent Identity 不保存任务内容，该 dispatch seam 属于目标业务。不得恢复或复制已退役内部环境的数据库、Client Registry、签名密钥、会话或 mock 主体。

完成条件：报告 `selected_route=agent`、上述五项部署状态和读取的当前部署契约；`remaining_blocks` 只保留尚未完成的 bootstrap handoff、authenticated Execution dispatch、真实 Agent 私钥断言换证、目标验签、父级业务权限与低风险白名单交集、双端审计和业务端到端验收，没有把已经通过的 TLS/Caddy、公开契约、来源限制或真实父级登录继续列为阻塞。

### `customer`

Customer Identity 当前延期，没有运行时、Issuer 或接入契约。不得使用 Workforce Identity 代替外部客户身份。

完成条件：停止接入实施，记录首批外部应用、客户群体、登录渠道、历史账号映射、恢复、会话、风控和合规需求。

### `none`

门户可以引导人类进入身份域自有管理页面，也提供导航和文档发现，但不参与任何认证调用或管理写操作。

完成条件：没有为目标应用配置门户 URL 作为 Issuer，也没有向门户添加 Client、令牌、登录会话或身份数据。

## 3. Implement：只实现所选身份域的职责

- 每个身份域分别验证自己的 Issuer、主体和凭证。
- 跨域关系只使用经过验证的类型化权威键。
- 目标应用继续判断业务角色、数据范围、资源所有权和业务规则。
- Secret、私钥、授权码和原始 Token 只留在相应安全运行边界，不进入仓库、日志或错误响应。
- 部署环境使用“内部环境”“仿真环境”“产线环境”；身份核验模式单独记录，二者不互相推断。
- 具体部署契约、Discovery 与本文冲突时停止实施并报告冲突，不自行放宽校验。

完成条件：代码没有跨入其他身份域职责，配置没有混用不同 Issuer 的主体、Client Registry、令牌或会话。

## 4. Verify：从目标系统公开 seam 验证

至少验证：

- 合法身份或凭证可以完成预期流程；
- 签名、Issuer、Audience、过期和重放等失败路径被拒绝；
- 身份认证成功不会自动授予应用业务权限；
- 日志、错误响应和持久化数据不包含原始凭证；
- 只有具备真实部署、登记信息和测试主体时，才把端到端联调标为已验证。

完成条件：已运行所选身份域契约要求的测试矩阵，并区分自动化验证、真实端到端验证和未验证项。

## 5. Report：交付可复核结果

最终报告必须包含：

```text
selected_routes
routing_evidence
deployment_environment
identity_verification_mode
contracts_read
inputs_received
files_changed
checks_run
real_end_to_end_verified
administrator_actions_required
remaining_blocks
```

## 共同约束

- 门户不是 Issuer：`https://user-center.staging.hetapet.com/` 不发布 OIDC Discovery、Authorization、Token 或 JWKS。
- 身份域之间不得共享 Issuer、主体 ID、Client Registry、令牌、会话或故障域；尚未实现或不需要的能力不得虚构。
- 不按姓名、邮箱、手机号或显示名称推断跨身份域关联。
- 门户页面链接由显式部署 Origin 生成；仓库实现或页面可访问不代表身份域或目标业务已通过端到端验收。部署证据只以根 ADR-0011 的最新日期记录为准。