@xgent-ai/skills 0.7.1 → 0.7.3

package/skills/phoenix-ui/SKILL.md

@@ -6,7 +6,7 @@ license: Apache 2.0
 metadata:
   version: 0.1.0
   source: skills/phoenix-ui/src
-  source_sha256: c5c32748444236a0fe97df5b010904e610a7b919b29ea108b5645167ffd2c301
+  source_sha256: df63c36432c6b47ddc7576171936c06c64e0a572357d4260323f4e2d880f900d
 ---
 
 Phoenix UI provides local design tools for frontend work. Follow the project's product truth, accepted direction, and design rules; use the command references to create complete, accessible interfaces with a clear visual direction.

package/skills/phoenix-ui/scripts/ENGINE.json

@@ -2,38 +2,38 @@
   "schemaVersion": 1,
   "distribution": "release",
   "toolVersion": "0.1.0",
-  "npmPackageVersion": "0.7.1",
-  "sourceCommit": "73d098637bcc07565352c5e94fa1dbcb5322c79f",
-  "sourceTree": "10b498a286bb994433f96a1449704df343979b30",
+  "npmPackageVersion": "0.7.3",
+  "sourceCommit": "2d0c0a2b1f299ae3c67d1e20ed0647fb443ef2c5",
+  "sourceTree": "ca1a69cd0a3e75401ac3ff141203eebd3dc0f3d1",
   "sourceState": "dirty",
-  "sourceInputSha256": "580361999880330995ea867135d295ad49dcdaaeace8936efd37b1a80f7245b1",
+  "sourceInputSha256": "78f9a468d3385300cee2df3f29d3188e927424da76c81045d169ff1916019552",
   "bundleSchema": 1,
-  "bundleSha256": "95bca755477c6864e11eab1104d2147d0d4c80dca24ec15a058c6af4d96e7c30",
+  "bundleSha256": "26ac1c512c9a8ea78902639260cefcb1fb7e05a2deb9f2060757e58be5b6adcb",
   "reviewSchema": 1,
   "engines": {
     "darwin-arm64": {
       "asset": "phoenix-ui-darwin-arm64",
       "sha256": "f3f634a18c6acbf446702394623a8d1e569a42d62dbe6d558174319cc8aa2cab",
       "size": 18284080,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.1/darwin-arm64/phoenix-ui-darwin-arm64"
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.3/darwin-arm64/phoenix-ui-darwin-arm64"
     },
     "darwin-x64": {
       "asset": "phoenix-ui-darwin-x64",
       "sha256": "108b5e02edf8a66723dcd82c00d9ab7cedfbf9c15e4de3ea038ba11d7a798cde",
       "size": 20772536,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.1/darwin-x64/phoenix-ui-darwin-x64"
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.3/darwin-x64/phoenix-ui-darwin-x64"
     },
     "linux-x64": {
       "asset": "phoenix-ui-linux-x64",
       "sha256": "425c300353779498c1954af4c5f6cb87c8f8ab70a55a69dca86e20668ad4a1ce",
       "size": 22855792,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.1/linux-x64/phoenix-ui-linux-x64"
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.3/linux-x64/phoenix-ui-linux-x64"
     },
     "linux-arm64": {
       "asset": "phoenix-ui-linux-arm64",
       "sha256": "fe61b42262cb9409849342e5ea3116c17c6054e13da5c1425580ed73ff242eca",
       "size": 19702656,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.1/linux-arm64/phoenix-ui-linux-arm64"
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.3/linux-arm64/phoenix-ui-linux-arm64"
     }
   }
 }

package/skills/portal-external-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-external-app
-description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖对接契约、manifest、注册、鉴权、原生客户端登录、/svc 路由、健康检查与一盒联调。'
+description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖 manifest、注册、鉴权、成员客户端与终端用户身份、/svc 路由、健康检查与一盒联调。'
 ---
 
 # portal-external-app · 外部镜像服务类应用接入
@@ -20,7 +20,9 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 | 匿名页、后端直出 HTML、公开站点/独立域名、旧链接或 listingKey 迁移 | [references/public-entrypoints.md](references/public-entrypoints.md)：现有 /apps、/svc、Sites 三种通路及各自责任 |
 | 将本 App 的图片/视频/PDF 发布为不过期、可吊销的固定内容 URL | [references/files-stable-links.md](references/files-stable-links.md)：特权 scope 申请、服务态签发、轮询、公开读取与生命周期 |
 | 服务账号写进应用空间的文件，要让作者本人在文件管理里看得到 | [references/files-member-docs.md](references/files-member-docs.md)：`onBehalfOf` 署名、成员只读可见、成员内容隐私开关 |
-| 原生客户端（iOS/Android/桌面）登录与刷新、设备凭证、停用后失效时效、服务端成员查询与事件 | [references/native-clients.md](references/native-clients.md) |
+| 门户成员的原生客户端（iOS/Android/桌面）登录与刷新、设备凭证、停用后失效时效、服务端成员查询与事件 | [references/native-clients.md](references/native-clients.md) |
+| 顾客/学生等终端用户的完整能力、租户用户中心、托管注册登录、账号与隐私治理 | [references/end-users.md](references/end-users.md)：先区分成员与终端身份，再按任务读认证协议或生命周期接口 |
+| 用户以 CLI、MCP、个人自动化调用 App，或接入门户多服务用户密钥与服务发现 | [references/cli-user-keys.md](references/cli-user-keys.md)：受审 `cliAccess` 声明、标准绑定与通用目录；不改门户业务代码 |
 | 为外部服务写/审对接契约文档 | [references/contract-doc-template.md](references/contract-doc-template.md) |
 | 有「每租户最多几个 X」的配额诉求（选模型、数值谁配、已用怎么来） | [references/quota-and-seats.md](references/quota-and-seats.md) |
 | 一个配置项该放哪（环境变量 / 平台级或租户级管理页 / 应用内设置 / 用户偏好），`requiredEnvNotes` 与 `adminPages` 怎么写 | [references/config-placement.md](references/config-placement.md) |
@@ -35,6 +37,7 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
     租户永远勾不到（症状：功能上线了、租户面却没有任何可选项）。判断口径与两条路的差别见
     [integration-contract.md §3.1](references/integration-contract.md)。
 - 它自带认证体系（API-Key/节点 Token/gRPC）？→ 按 integration-contract.md §6 划界：门户面必走 TDT 四道闸；自有节点面保持原认证但**不得**进 `/svc`（`/svc` 只转发 HTTP :8080）。
+- 用户是租户旗下网站/App 的顾客、学生等终端用户？→ 先读 [终端身份](references/end-users.md)。它是 `kind=enduser`，不使用门户成员的 `/oauth/*`、成员角色或席位；不能把普通后台路由一起开放给它。
 
 ## 交付物评审 checklist（收外部团队东西时逐项验）
 
@@ -48,6 +51,7 @@ description: '用于把独立仓库、以 Docker 镜像交付的外部服务接
 8. **配额诉求**：有没有「每租户能建多少」这类上限？有就走平台套餐（见 [references/quota-and-seats.md](references/quota-and-seats.md)），**不接受对方自建**；
    角色本身该由对方在自己的 `app.manifest.json` 里声明 `seatRoles`；`serviceScopes` 里出现 `seats.read` 仍是当场打回的信号，但对方可以在 `privilegedServiceScopes` 里**申请**它（带 reason，进「发布审核」逐条确认批准后授予）；
 9. 对接契约文档：按 [references/contract-doc-template.md](references/contract-doc-template.md) 的结构与精度。**没有这份文档的接入不算完成**——新服务（如任务网关）要先补。
+10. **终端用户**：如有注册、登录、找回、密码管理、注销或个人数据请求，按 [终端用户参考](references/end-users.md) 核对身份 owner、realm、profile/client、服务权限、容量与业务数据分工；区分管理 UI、App API 和本人流程，不把成员 OAuth 当顾客认证。
 
 ## 资源服务器硬契约（外部实现最常炸的四处）
 
@@ -263,6 +267,13 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 | 用户级设置 | `settings.read` / `settings.write` | `/api/v1/settings/me` |
 | Dashboard 卡片 | `widget.write`（**用户态**，服务态令牌推不了） | `PUT /api/v1/dashboard/widgets/:key/data`；清单顶层 `dashboardWidgets` 声明（不是 `dashboard.widgets`）。有用户关心的状态就该暴露至少一个，前端用 SDK 推；完整契约见 portal-micro-app skill 的 Widget 一节 |
 
+### 终端用户身份也是门户能力，但使用专门服务身份
+
+注册、凭据、会话、条款与隐私接口在 `/api/v1/end-users*` 等基座路径，管理入口为「用户中心」。
+它们不走 `/svc/user-center`，也不走成员的交换流程；`endusers.*` 和 `privacy.requests.*`
+是 SERVICE_ONLY scope，按需经 `privilegedServiceScopes` 申请。终端身份不是成员通讯录，
+登录、当前限制和完整分工见 [终端用户参考](references/end-users.md)。
+
 ### B. App 型公共服务 —— 走 `/svc/<key>` + 令牌交换
 
 这些是**独立 App**，不是基座端点：要在清单里声明 `exchangeTargets`，用交换来的
@@ -314,6 +325,9 @@ compose 网络** —— 一份在一盒里能跑的 descriptor，`env` 里写着
 - 两个模型**二选一**，都只有 **backed listing** 可声明：`seatBased`（计门户成员用不用得了这个
   App，门户在 TDT 签发时收口，App 侧零代码）/ `seatRoles`（App 自管账号或资源，门户只发数、
   App 自己在建号路径上收口）。
+- 上面是 App 席位/业务资源模型；平台托管终端身份另用租户共享的 `portal.end_users`，
+  由平台在身份创建/删除时占用/归还，归档仍占额。不要拿成员席位代替或再扣一份身份容量，
+  见 [终端用户容量](references/end-users.md)。
 - **role 由对方在 `app.manifest.json` 里声明**（不需要门户改代码）；**各套餐的数值进不了
   manifest**，只有平台管理员在控制台能写 —— 应用侧一条写路径都没有。
   这是有意的：数值是商务面，改它等于改可售卖档位。

package/skills/portal-external-app/references/cli-user-keys.md

@@ -0,0 +1,104 @@
+# CLI 与用户访问密钥接入
+
+适用于用户以本人身份从 CLI、MCP 或个人自动化调用 App。人在手机、桌面客户端上登录仍走 [原生客户端授权码与 PKCE](native-clients.md)；无人值守的租户程序走服务账号。
+
+## 清单声明
+
+先确认目标门户已部署支持 `cliAccess` 的数据库迁移、API 和授权页。共享包中的类型存在，不表示某个门户环境已启用能力。旧门户批准一个未知字段，也不证明该字段已进入运行时目录。
+
+在 App 自己的唯一 manifest 中声明并 bump version，通过原有发布提案审批到达；不申请修改门户的 `CLI_SERVICES`、权限枚举或授权表单。
+
+```json
+{
+  "listingKey": "my-tool",
+  "scopes": ["my-tool.read", "my-tool.publish"],
+  "scopeLabels": {
+    "my-tool.read": { "zh-CN": "读取本人有权访问的文档", "en": "Read documents available to me" },
+    "my-tool.publish": { "zh-CN": "发布本人有权发布的文档", "en": "Publish authorized documents" }
+  },
+  "cliAccess": {
+    "version": 1,
+    "scopeCeiling": ["my-tool.read", "my-tool.publish"],
+    "requiredScopes": ["my-tool.read"],
+    "defaultScopes": ["my-tool.read"],
+    "maxTtlDays": 90,
+    "bindPath": "/api/v1/user-keys/bind",
+    "endpoints": [
+      {
+        "id": "client",
+        "protocol": "my-tool-v1",
+        "path": "/api/v1/client",
+        "requiredScopes": ["my-tool.read"]
+      }
+    ]
+  }
+}
+```
+
+- `scopeCeiling` 是用户密钥的独立上限，只含本 App 已声明的自有命名空间权限。主 `scopes` 中的 Files 等依赖权限、平台权限不能照搬进来。管理权限也不会自动进入 CLI 上限。
+- `requiredScopes` 为必选项，`defaultScopes` 为初始选择；两者都须是上限的子集，默认选择须包含必选项。实际签发还受安装范围、当前主体资格和用户明确同意限制。
+- `maxTtlDays` 为 1–365 的整数；App 在绑定时仍须检查自己的期限和业务限制。
+- `bindPath`、端点 `path` 是 App 后端内的绝对路径，由门户拼到受信任的 `/svc/<listingKey>` 下。不能填写 URL、双斜线、路径穿越、编码分隔符、查询或片段。
+- `endpoints` 可为空。`id` 在同一 App 内唯一；`protocol` 是稳定的协议标识，可以由多个 App 实现，不是 App 身份。端点必需权限须在 CLI 上限内。
+
+新增、修改、显式 `null` 撤回均属治理变更，pending 时不改变生效目录。省略 `cliAccess` 沿用原值；对象完整替换；`null` 停止新 CLI 授权和服务发现。声明只在 listing 保留一份，不要求逐租户复制。
+
+## 标准绑定协议 v1
+
+门户生成 pending 密钥后，使用仅限该目标及本次所选权限的用户 TDT 调用：
+
+```http
+POST /svc/<listingKey><bindPath>
+Authorization: Bearer <目标绑定 TDT>
+Content-Type: application/json
+
+{"credentialId":"<pending 密钥 UUID>"}
+```
+
+App 不接收密钥明文，也不从 body 接收用户、租户、权限或业务授权。绑定端点只接纳直接用户 TDT，拒绝服务身份、交换身份和用户访问密钥；身份取自门户自省，并执行自己的 scope、PID、租户与业务资格校验。
+
+Bun/TypeScript 使用已配置的 `createPortalUserKeyClient`；配置中的 `userKeysUrl` 为可信门户地址下的 `/api/tokens/user-keys`，不能来自请求。
+
+```ts
+await userKeys.bindExisting(tdt,
+  { userId: actor.userId, tenantId: actor.tenantId, appKey: actor.aud },
+  credentialId,
+  async (key, confirm) => {
+    const binding = await database.transaction(async tx => {
+      // 检查期限、所选权限和业务资格；幂等写入本地绑定。
+      return bindLocalPolicy(tx, actor, key);
+    });
+    await confirm();
+    return binding;
+  });
+```
+
+先提交本地事务，再在事务外确认门户目标。确认失败时保留尚不可用的本地记录，以同一 `credentialId` 重试；重复绑定不得扩大原策略。所有目标绑定结束后，门户只激活成功目标，并向用户一次性展示明文。没有成功目标时不得返回可用密钥。
+
+App 的项目、文件或资源白名单由 App 自己维护；复杂设置放在 App 自己的管理面。清单不包含可执行插件、任意请求模板或业务表单 schema。
+
+## 使用与发现
+
+机器入口须显式接纳 `user_access_key`。每次请求先验证门户自省的当前主体资格，再按 `credential_id` 检查本 App 已提交的绑定、资源范围与业务规则；普通 REST 不因登记 CLI 能力而自动接纳长期密钥。
+
+客户端用密钥调用 `GET /api/access-keys/self`，读取 `endpoints`：
+
+```ts
+const candidates = self.endpoints?.filter(item => item.protocol === "my-tool-v1") ?? [];
+const target = candidates.find(item => item.appKey === configuredAppKey);
+// 多提供方时由用户或客户端配置明确选择。
+```
+
+每项包含安装代次相关的稳定 `id`、实际 `appKey`、`listingKey`、名称、协议、同源 `url` 与有效权限。没有匹配项或字段缺省时，客户端报告能力不可用；不能猜测服务地址。请求携带 bearer 时禁止跟随重定向。
+
+`services.files/spms/llm/skills` 是旧客户端兼容视图；新增 App 不为它新增字段。`xgent-skills-v1` 表示既有 Skills 客户端协议，仅有一个有效提供方时可投影到 `services.skills`；多提供方使用通用目录。能力名与 listingKey 分别演进，不能把旧权限名无条件映射成新权限。
+
+撤回声明不会替用户自动撤销已激活的密钥，也不改变 App 直接委托签发的凭证合同。要停用已有密钥，使用门户撤销或 App 移除目标的既有流程；卸载、主体失格和 consent 撤回继续按当前授权事实生效。
+
+## 联调验收
+
+1. 用未在门户代码登记过的 App key，经 manifest 注册和安装后，它出现在当前用户可授权的目录中；pending 提案不改变生效目录。
+2. 必选和默认权限按声明显示，权限文案来自 `scopeLabels`；未同意、越界、缺必选权限、超过期限时不能签发。
+3. 完成 pending → 目标绑定票据 → 本地提交与确认 → 激活 → 自省与服务发现。验证部分绑定失败和全部失败，失败 App 不可使用密钥。
+4. pending 期间撤回声明、撤回 consent 或卸载 App，后续绑定和激活不得继续授予该目标；既有 App 直接签发密钥不被 CLI 声明撤回误伤。
+5. 实际访问机器入口，验证跨租户、无本地绑定、资源范围越界、撤销密钥及重复绑定。类型和 SDK 单测不代替这条端到端链路。

package/skills/portal-external-app/references/end-user-auth.md

@@ -0,0 +1,206 @@
+# 终端用户托管认证协议（enduser-auth-v1）
+
+> 顾客身份先读 [能力与启用条件](end-users.md)。本文适用于已登记的 Web BFF / iOS 终端认证，
+> 不使用成员的 `/oauth/authorize`、`/oauth/token`、`publicClient` 或 `redirectUrls`。
+> `<auth-origin>` 是 profile 登记的精确 HTTPS 认证源；`<portal-origin>` 是门户 API 公开源。
+
+## 1. 登记与发现
+
+租户在用户中心维护 profile；App 后端持 `endusers.clients` 登记客户端：
+
+```http
+POST <portal-origin>/api/v1/end-users/clients
+Authorization: Bearer <服务态令牌>
+Content-Type: application/json
+
+{
+  "siteKey": "customers",
+  "clientId": "example-web",
+  "kind": "web_bff",
+  "name": "网页客户端",
+  "redirectUris": ["https://app.example.com/auth/callback"],
+  "protocolVersions": ["enduser-auth-v1"],
+  "status": "active",
+  "expectedRevision": 0
+}
+```
+
+租户和 owner 从服务票确定；profile 须已存在。新增 `expectedRevision=0`，更新先回读提交当前
+revision，冲突处理后再试；已有客户端不能改绑 profile 或 kind。成功 data 返回
+`id,kind,name,redirectUris,protocolVersions,status,revision`，持久保存 revision。
+`GET /api/v1/end-users/realm?siteKey=...` 可核对本空间及客户端配置，但当前不返回 revision；
+公开能力发现也不返回它。遇到后台修改引起的 CONFLICT，需由有权操作人从用户中心核验当前修订，
+不能凭空增加服务回读端点、盲猜 revision 或循环覆盖。iOS 使用 `kind:"ios"`，
+可登记反向域名形式的 scheme；Web 必须 HTTPS。回调精确匹配，拒绝通配符、userinfo、fragment、
+以及占用 `code/state/error` 的查询参数；不要套用成员的回环 HTTP 例外。
+
+从认证源获取：
+
+```text
+GET <auth-origin>/api/public/end-user-auth/clients/<clientId>
+```
+
+成功 Envelope 的 data 包含 `protocolVersion`、`clientId`、`authorizationEndpoint`、
+`tokenEndpoint`、`refreshEndpoint`、`logoutEndpoint`、`targetedTicketEndpoint`、`methods`、
+`pkceMethods:["S256"]`、`responseModes:["query"]`、`codeTtlSeconds:60`、`reauthSupported`。
+未知/停用客户端、停用 profile、host 不符回 `200 {ok:true,data:null}`。
+按元数据 methods 判可用方法（password/apple）；不能从协议版本推断供应商已配通，
+也不能从 reauthSupported 推断所有重新认证用途均已上线。
+
+## 2. 普通授权码流程
+
+1. BFF 为本次请求保存随机 state、PKCE verifier、应用浏览器会话、回调和期限。
+   浏览器只持应用会话句柄，Portal access/refresh 与服务账号 secret 留在 BFF；
+   原生端使用系统浏览器与系统安全存储，不把服务账号 secret 放进安装包。
+2. 顶层打开元数据给出的授权地址，不能嵌入 iframe：
+
+```text
+GET <auth-origin>/api/public/end-user-auth/authorize
+  ?client_id=example-web
+  &response_type=code
+  &redirect_uri=<已登记的精确回调，URL编码>
+  &state=<随机state>
+  &code_challenge=<BASE64URL(SHA256(verifier))>
+  &code_challenge_method=S256
+```
+
+以上六项必须各出现一次。state 是 22–512 字符无填充 base64url，由密码学随机源生成；
+verifier 为 43–128 字符 `A-Z a-z 0-9 -._~`，challenge 为 43 字符无填充 base64url。
+拒绝 plain、未知/重复参数及自报 tenant/owner/site/audience/scope/profile/subject；
+authorize 不接受 lang/view，托管页自己提供语言切换。
+
+3. 平台创建最长 600 秒的浏览器绑定 flow，303 到同一认证源 interaction 页面。
+   登录可复用同 profile 的托管浏览器会话，仍要确认账号与目标应用；可换账号或取消。
+   注册走邮箱→验证码→密码及必选条款；找回走已验证邮箱验证码；
+   首登须改密时完成前不给可用会话。Apple 按 provider sub 绑定，不按同邮箱自动合并账号。
+   当前托管 password 表单使用邮箱；不要假定用户名/手机号标识也能直接在此表单登录。
+4. 回调成功带 code/state；取消带 `error=access_denied` 与原 state。BFF 核验本地事务、state、
+   浏览器绑定和期限并单次消费，然后在服务端换码；非法回调不跳转。
+
+```http
+POST <auth-origin>/api/public/end-user-auth/code-token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&client_id=example-web&redirect_uri=<同一回调>&code=<code>&code_verifier=<verifier>
+```
+
+换码 URL 不带查询参数，表单只收这五项，各一次。授权码最多 60 秒、单次使用。
+错误 verifier 不消费码；并发正确请求只有一个成功。丢回包后重新授权，不重放旧码领取 refresh。
+成功 data 的字段名是：
+
+```json
+{
+  "protocolVersion": "enduser-auth-v1",
+  "endUserId": "<主体UUID>",
+  "ownerAppKey": "<身份owner>",
+  "siteKey": "customers",
+  "sessionId": "<设备会话UUID>",
+  "accessToken": "<owner访问票>",
+  "refreshToken": "<刷新凭据>",
+  "expiresIn": 900,
+  "mustChangePassword": false
+}
+```
+
+这是 `{ok:true,data:...}` 内的 data，不是成员 OAuth 的 snake_case token 响应。
+授权码只能交给 code-token，不能交给下面的 token 定向票端点。
+成功或取消后转到不含 code/state 的应用 URL。
+
+## 3. 自省、资源鉴权与脱敏资料
+
+BFF/资源后端用获准 `token.introspect` 的服务账号 Basic 调：
+
+```http
+POST <portal-origin>/api/tokens/introspect
+Authorization: Basic <服务账号clientId:secret的base64>
+Content-Type: application/json
+
+{"token":"<owner访问票>"}
+```
+
+先解 Envelope，再校验 data。owner access 必须同时满足：
+
+- `active=true`、`kind=enduser`、`credential_type=tdt`，且 `exp` 未过期；
+- `end_user_id=principal_id`，与已绑定应用会话的主体相同；`session_id` 有效；
+- `tenant_id/owner_app_key/site_key` 与登记值一致；
+- `aud=listingKey=azp=owner_app_key`，`scopes=[]`；
+- `user_id/role/groups/permissions` 为 null，`bypass/isPlatformAdmin=false`。
+
+HTTP 自省字段为 `end_user_id/session_id/owner_app_key/site_key`；SDK 上下文对应
+`endUserId/sessionId/ownerAppKey/siteKey`。成员票、服务票即使 active 也不能替代。
+files 定向票不能当 owner access 登录。仅解 JWT 或相信浏览器提交的主体都不构成认证。
+
+TS 后端使用 `@xgent/portal-server-sdk`，仅在具名终端用户端点配置
+`acceptedPrincipalKinds:["enduser"]`、`acceptedCredentialTypes:["tdt"]`，再用
+`requireEndUser`、校验目标 audience、登记空间与 App 本地业务权限；SDK 缺省只开放 user/service。
+终端用户没有成员 PID/管理员角色，不能直接套用成员的四道闸或放开所有后台路由。
+自省正缓存上限 **50 秒**，还须受真实 exp 截断；端到端撤销预算 60 秒。
+敏感操作可用 `strictIntrospection:true`。合法 inactive 才是认证失效；超时、坏 JSON、
+失败信封或依赖故障拒绝为服务故障，不降级匿名。
+
+读取资料另用 `endusers.read` 服务 Bearer 调 `GET /api/v1/end-users/<id>`；
+普通 DTO 只有 `identifierMasked/contacts[].addressMasked` 等脱敏字段，
+不提供通用 userinfo 或明文联系方式端点。专门的本人数据导出另有授权与范围。
+
+## 4. 刷新、退出、定向票
+
+| 操作 | 请求 | 语义 |
+| --- | --- | --- |
+| 刷新 | `POST <auth-origin>/api/public/end-user-auth/refresh`，JSON `{"refreshToken":"<当前值>"}` | 返回 accessToken、**新** refreshToken、expiresIn；同会话串行轮换并原子保存，旧值不可重放 |
+| 设备退出 | 同前缀 `POST /logout`，JSON `{"refreshToken":"<当前值>"}` | 撤销当前设备会话；丢弃本地凭据，退出结果不明按应用状态处理 |
+| 定向票 | 同前缀 `POST /token`，Bearer 终端用户 access，JSON `{"target":"owner"}` 或 `{"target":"files"}` | 只能选平台白名单 target；files 仅 files.read，仍需逐文件业务授权 |
+
+access 当前为 15 分钟，refresh 为 30 天滑动并轮换；始终使用实际 expiresIn。
+sessionId 只在设备会话创建时给出，刷新不改变也不再返回。应用设备退出不清认证域的托管
+浏览器会话，因此退出后再登录不能代替重新认证。管理员全部下线会连托管浏览器会话一起失效；
+单会话撤销不影响其他设备。
+
+## 5. 敏感操作重新认证
+
+持**当前 owner 设备会话**的 access（不是成员/服务/files 票或托管 Cookie）在认证源申请：
+
+```http
+POST <auth-origin>/api/public/end-user-auth/reauth/requests
+Authorization: Bearer <当前owner访问票>
+Content-Type: application/json
+
+{"client_id":"example-web","redirect_uri":"https://app.example.com/auth/callback","purpose":"confirm_action","operationKey":"example-web:export:<本次操作号>"}
+```
+
+operationKey 使用字母、数字、`._:-`，1–128 字符；示例的尖括号占位须替换成合法操作号。
+每次尝试新号并与具体业务操作绑定。body 只收这四项，不带查询参数。
+申请回 requestId、expiresIn（≤600）、authorizationEndpoint。建立新的 state/verifier，
+按 §2 六参数额外加 `reauth_request=<requestId>`。平台锁定原主体，要求重新输入密码或完成 Apple
+重新认证，不复用 Cookie 免密。回调仍经 code-token 兑换，但 data **仅**包含：
+
+```json
+{"reauthToken":"<不透明证明>","expiresIn":300,"purpose":"confirm_action","operationKey":"<原操作号>","endUserId":"<当前主体UUID>"}
+```
+
+不含 access/refresh/sessionId，不新建会话。证明 TTL 不超过实际认证时间后 300 秒及 flow 剩余期限。
+
+- `confirm_action`：App 自己消费。可信证据是 BFF 持自己保存的 verifier 直接换码的成功响应，
+  不是浏览器单独提交一个字符串。核对 purpose、主体、原发起 client/应用会话、操作号和原操作内容；
+  本地 TTL 取实际剩余值与 300 秒较小值并扣网络耗时，原子单次消费；执行时再校验会话和业务权限。
+  Portal 没有此证明的验证端点，也不替 App 消费它；不要拿它调用 token introspect。
+- `delete_passport`：只供 [删除命令](end-user-lifecycle.md) 消费，不能替代 confirm_action。
+- `bind_apple/add_password/unlink_apple` 当前返回 `END_USER_AUTH_UNAVAILABLE`，不要做成可用功能。
+
+取消、换账号、退出或放弃操作时清理 App 本地待执行证明。操作号不承载个人资料或业务敏感内容。
+
+## 6. 站点认证的另一条入口
+
+平台 Sites 主域的 `/_xgent/auth/*` 提供 HTML/JSON 认证入口，同样属于终端身份：密码、邮箱数字验证码
+`verify_contact/login/reset_password`、首登改密、退出；首次邮箱验证由所属 App 服务签发
+registration-ticket，不能拿它直接换会话。站点 Cookie 只信反代注入的真实站点上下文，
+不能自报头取得；设备 JSON 密码入口使用 tenantId/ownerAppKey/siteKey 与凭据，仍检查资格。
+这些入口不是 profile 的额外登录方法，也不能把普通站点 Cookie 混作托管认证域的浏览器会话。
+
+已有手机 OTP 绑定/登录/恢复接口，但当前缺生产发送适配；详见 [能力限制](end-users.md)。
+已有用户名等账号的设备 JSON 密码入口为 `POST /api/public/end-user-auth/login`，
+body 含 `tenantId,ownerAppKey,siteKey,identifierKind,identifier,password,deviceId?`；
+成功设备会话字段见 §2，须首改时仅回 changePasswordTicket，不能提前建立应用登录状态。
+新 Web BFF / iOS 集成优先按本文托管协议完成，不能直接套用成员登录或把站点表单当 PKCE 回调。
+
+JSON 成功为 `200 {ok:true,data}`；业务失败为 `200 {ok:false,error}`，按 error.code 处理。
+400/401/403/429 和服务故障另按传输/鉴权语义处理；404 只表示路径不存在。