@awiki/dsh-pap 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,198 +1,185 @@
1
- # DSH PAP 0.3
1
+ # DSH PAP
2
2
 
3
- Apache-2.0-licensed DSH Host plugin and PAP client. The protocol baseline is
4
- [the fixed 0.3 spec](https://github.com/personal-agent-protocol/personal-agent-protocol/blob/6fb46d381ac1b94265795132af13848ec442b6f6/content/versions/0.3/spec.mdx),
5
- Git blob `01e9dc34bacb73ef0a740cc3bae77d82f0be0d37`.
3
+ **A PAP 0.3 client for DeepSeek Harness (DSH), powered by a reusable, locally held agent identity.**
6
4
 
7
- 源码以 [Apache-2.0](LICENSE) 公开。包名为 `@awiki/dsh-pap`,声明 DSH bundle;发布必须经过显式授权和发布前验证。安装 bundle 默认不启用签名或网络请求,仍需配置身份、用途策略和秘密后端。
5
+ English | [简体中文](README.zh-CN.md)
8
6
 
9
- ## 已实现路径
7
+ [PAP 0.3 specification](https://github.com/personal-agent-protocol/personal-agent-protocol/blob/6fb46d381ac1b94265795132af13848ec442b6f6/content/versions/0.3/spec.mdx) · [Shared identity](https://github.com/agent-network-protocol/anp-identity) · [Service Agent demo](https://github.com/AgentConnect/service-agent) · [Apache-2.0](LICENSE)
10
8
 
11
- - Company discovery:HTTPS 受限重定向,DNS 解析与实际连接绑定,地址、大小、时间、请求数限制;根 PRM 与精确 issuer 双向关联;无 AS、账户和 disabled 分开。网络错误保留已知 issuer,Company Identifier 改变后隔离原命名空间。
12
- - 随机且私有的 Company User/Agent ID、独立匿名身份、sid 和加密事务状态。匿名 Session 禁止账户 Token。Agent ID 不改变 User ID。新账户 slot 使用新 Session。
13
- - 通过 C 的 `./protocol-client` 调用 A 本地 custody:临时 P-256 key、身份 Delegation、逐请求 Session、独立 DPoP key、客户端断言和重启后 handle 恢复。F 不打开 NativeStore,不持有或导出这些私钥,不调用远程 signer。
14
- - 每个实际资源请求重新签 `Poppy-Session`,绑定实际 htm/htu,带账户 Token 时才有 ath。发现、描述和 OAuth 请求不携 Session;禁止调用者注入认证 Header;凭据重定向停止。
15
- - Direct Sign-In:显式用户入口、state、issuer、43 字符 S256 PKCE verifier、已发布 callback 校验、标准账户 Token、可选 RFC 9449 DPoP 和按 AS/资源分离的 nonce。
16
- - 独立 PAP account store:scope/resource 约束、refresh single-flight/CAS、轮换 Token 原子替换、丢回执标为 uncertain、退出撤销及 revocation_pending。持久 account slot epoch 同时约束登录事务、refresh 和发送前检查;退出取消 pending/exchanging 登录,迟到 Token 只保留撤销信息。并发资源调用会等待同一刷新代次。
17
- - `invalid_session` 停止,`session_ended` 新 sid 后最多重发一次,仅 GET/HEAD/OPTIONS 的 Token 错误可刷新后最多重发一次;副作用 API 的认证 challenge 不自动重放。网络超时或丢回执不自动重发副作用请求。429 持久保存 Retry-After fence,原请求不重放,后续显式请求在窗口前不签名或发送。
9
+ ## The problem
18
10
 
19
- Device 为后续独立阶段,当前返回 `unsupported_sign_in` 并且不广告。Browser Join、Mediated Sign-In、PS384、Web Bot Auth operator signature、自动账户合并均未实现。PAP 不复用 MCP machineToken、Mcp-Session-Id 或 0.2 Session grant。
11
+ A personal agent should be able to connect to independent service agents without registering a fresh identity and handling another private key at every service. This plugin lets a DSH agent **reuse an existing, user-authorized identity** for PAP Company discovery, Delegation, signed Sessions and approved business operations.
20
12
 
21
- ## Host 接入
13
+ PAP is one of three complementary paths in the shared-identity system:
22
14
 
23
- `@awiki/dsh-pap/plugin` 提供实际 Cordis `pap` 服务;bundle 同时挂载用户管理 `./management-remote`、模型工具 `./tools` 和根 package 的 client declaration marker。根 `@awiki/dsh-pap` 保留 Host 库 exports,作为 Cordis row 时仅是无能力 marker;不提供第二个 pap 服务、不注入 C 或 credentials。真实 consumer 始终是唯一的 `@awiki/dsh-pap/plugin`。默认 `enabled: false`,没有 Company、identity 或 policy 时不执行网络发现、创建凭据或签名。用户仍可读取 disabled/unconfigured 状态。启用需要 Host 的明确 profile 配置,不再读取 `DSH_PAP_*` 环境变量或接受自报 binding:
15
+ | Protocol | Identity and authentication | Integration |
16
+ | --- | --- | --- |
17
+ | **ANP** | Published `did:wba` identity; per-request HTTP signatures | [dsh-anp](https://github.com/agent-network-protocol/dsh-anp) |
18
+ | **MCP** | CIMD/JWKS client metadata; `private_key_jwt` and policy-approved `client_credentials` OAuth | [DSH MCP Host](https://github.com/AgentConnect/dsh-harness-identity) |
19
+ | **PAP 0.3** | Identity-signed Delegation and per-request `Poppy-Session`, with optional separate account authorization | **This plugin** |
24
20
 
25
- ```yaml
26
- - id: pap
27
- name: '@awiki/dsh-pap/plugin'
28
- config:
29
- enabled: true
30
- stateRoot: /absolute/profile/pap
31
- policyRef: approved-c-policy-id
32
- keyringService: org.agentconnect.dsh-pap
33
- ```
21
+ One local identity anchors these protocol-specific credentials. **A PAP Session is not an MCP access token, and neither bypasses Company policy or account permissions.** Private signing keys stay with the local [ANP Identity](https://github.com/agent-network-protocol/anp-identity) Host, not with dsh-pap or a remote Company.
34
22
 
35
- C 的真实 Loader consumer 必须是精确 `@awiki/dsh-pap/plugin`。Host 在 C 管理面预批准相应身份、profile、target 和 scopes;Remote 只选择 `{storeId, identityId, did}`,不能提交 owner、client_id、policy、verified metadata 或 targetRef。F 捕获插件构造时的真实 Context;不会将随 Cordis Service 调用关联变化的 `this.ctx` 当作签名调用者。
23
+ ## Features
36
24
 
37
- C 服务需实现 `bindProtocolConsumer(actualInstalledContext)` 与 `bindPapHostConsumer(actualInstalledContext)`。后者返回同进程 capability,`resolveBinding(identityRef, policyRef, profile)` 从当前已发布身份与政策得出 binding,`callbackManagementFor({identityRef,policyRef,targetRef})` 只返回 register/claim 两个受限操作。F 的 `ProtocolIdentityHost` 通过 C 真实 `registerValidatedTarget` 得到 opaque target,callback adapter 从加密事务重建相同 issuer/resource/scope 后取得该目标;不接受用户或模型提交的 opaque 引用。C factory 不可用时拒绝操作,不以组件 fixture 补位。失效 capability 永不复活;status/工具不会自动重绑,仅用户显式 identity/select 或插件重载从实际 Context 重新取得当前许可。
25
+ - Discover PAP Companies and advertised OpenAPI operations over constrained HTTPS.
26
+ - Create regular or anonymous signed-out Sessions and generate fresh PAP Delegation/Session proofs through the local identity Host.
27
+ - Enable only explicitly user-approved operations; the agent cannot choose arbitrary endpoints, methods, headers, tokens or scopes.
28
+ - Support **Direct Sign-In** when a Company requires an account: user-initiated OAuth authorization, PKCE, optional DPoP, protected token storage, refresh and sign-out.
29
+ - Store per-identity/Company Session and account state in encrypted local storage, using a Host secret provider, OS keyring or an explicitly selected protected local-file key store.
30
+ - Expose a DSH settings interface and narrowly scoped model tools.
38
31
 
39
- 用户管理 namespace 为 `papManager`:`status()`、`operations()`、`manage(request)`。仅安装的 `@awiki/dsh-pap/management-remote` Context 可以取得管理 facade,部署必须把该 namespace 留在已认证的用户管理 Gateway,不接入 Agent 的 Remote/MCP 通用工具。闭合管理动作如下:
32
+ The reference [ANP website Service Agent](https://agent.agent-network-protocol.com/ready) supports **signed-out PAP Sessions without an account or browser login**. A separate Company (for example a suitably configured Frontvia integration) is required to test account sign-in. The plugin does not automatically grant account access.
40
33
 
41
- | action | 作用 |
42
- |---|---|
43
- | `identity/select` | 选择 C 已批准的已发布 identity reference |
44
- | `company/discover` | 按用户指定域执行安全发现;Company 不由包预造 |
45
- | `session/connect` / `session/disconnect` | 建立 signed-out 或明确 account slot 的 Session/断开 |
46
- | `operation/enable` / `operation/disable` | 将已发现 operation 绑定到用户选定的 Session 与 scope,或撤销 |
47
- | `account/sign-in` | 选定 operation/resource 和 scopes,使用实际已发布的 HTTPS callback 发起 Direct |
48
- | `account/collect` / `account/refresh` / `account/sign-out` | 原设备一次领取后换码/显式刷新或退出指定账户 slot;不接受 grantRef、resource、scope 或 Token |
34
+ ## Architecture
49
35
 
50
- `account/sign-in` 的授权 URL 只返回给上述用户管理调用,需由真实用户 UI 打开。state、code、PKCE、callbackRef、claim secret、Token、key handle 不进入模型工具。包内 `./client` 现提供最小 settings.section“PAP 连接”:只从 C 的公开 listIdentities/publicationStatus 选择已发布且支持 PAP Session 的 reference,发现 Company、建立连接、明确批准操作及其账户权限、显式发起浏览器登录/领取、刷新、退出和断开。登录链接只由用户点击,带 noopener/noreferrer,不由模型自动打开。默认 disabled、C 未 ready、缺秘密后端和 legacy history 门禁均有安全状态,不切 fallback。UI 只调用用户 Remote,不持有 Host secret、C signer capability、DeviceAccess 或 callback proof。Desktop owner 负责最终正式 profile/renderer 装入和产品验证。
51
-
52
- `package.dsh.client` 使用现有 Web/Settings/Remote 依赖,`./client` 指向独立 `lib/browser-client.js`。Host 核心仍在 `lib/client.js`,不被 browser build 覆盖;实际 client-modules 通过根 marker 找到并服务 browser export。
53
-
54
- 模型只有 `pap_status`、`pap_operations`、`pap_request` 三个工具。`pap_request` 输入只含本地 `operationRef`、已声明 path/query 参数及可选 JSON body,不接受 URL、method、Header、resource、scopes、account slot 或认证 metadata。method/destination/resource/session 来自本地已发现描述与用户授权。每次启用产生新的持久授权 generation,撤销后重新启用也不能让旧的在途调用越过发送前 fence。操作输出只给有界业务 JSON/状态,不透传响应 Header。除凭据字段和 JWT 模式外,实际发送前只在 Host 内存捕获本次 Session/DPoP/access/refresh 等值,任意 JSON key/value 或嵌入消息中的同值也遮盖;自动 refresh 后即使 sign-out 清空 Store,迟到 response 也不能回显新凭据。当前工具是 HTTP operation adapter;MCP 描述不会被当成已经实现的 PAP MCP transport,机器 MCP 不作 PAP 回退。
55
-
56
- 状态 key 的 namespace 包含 PAP purpose、规范化 profile stateRoot 摘要以及 identity/owner/client binding 摘要;不同 profile 不复用同一 item。移动 profile 目录需要受控迁移其 protected item,不能只拷密文后创建新 key。状态根密钥默认使用 Linux Secret Service,也可显式选择下面的跨平台文件存储。受信 Host 仍可通过同进程 `papHost.secrets` 提供 `HostSecretStore`;显式指定 `secretStore` 时,以插件配置为准。密钥后端之间不会自动回退或迁移。
57
-
58
- ### 跨平台文件密钥存储
59
-
60
- ```yaml
61
- - id: pap
62
- name: '@awiki/dsh-pap/plugin'
63
- config:
64
- enabled: true
65
- stateRoot: /Users/your-name/.dsh/profiles/pap-test/pap
66
- policyRef: approved-c-policy-id
67
- secretStore: local-file
68
- secretsRoot: /Users/your-name/.dsh/secrets/pap
36
+ ```text
37
+ DSH user / settings UI DSH Agent
38
+ | identity + Company | approved operation only
39
+ | selection / consent v
40
+ v pap_status / pap_operations / pap_request
41
+ PAP management Remote ---------> dsh-pap Host plugin
42
+ |
43
+ limited identity capability
44
+ |
45
+ ANP Identity (same Host)
46
+ local Delegation / Session / DPoP signing
47
+ |
48
+ signed HTTPS request
49
+ v
50
+ PAP Company
51
+ OpenAPI / business resources
69
52
  ```
70
53
 
71
- 两个路径都使用本机绝对路径;Windows 可用 `C:/Users/your-name/...`。`secretsRoot` 与 `stateRoot` 必须是彼此独立、互不包含的目录。不同 profile 和身份通过 namespace 派生各自的密钥文件名。
72
-
73
- 文件后端保存随机 32 字节的 PAP 状态加密密钥:macOS/Linux 设置目录 `0700`、文件 `0600` 并检查当前用户所有权;Windows 使用系统 PowerShell 设置当前用户 SID 的 DACL、移除继承权限,不依赖 chmod。临时文件写入并刷盘后,通过不覆盖已有目标的原子 hard link 发布;并发创建复用胜出的文件。需要支持这些文件权限和 hard link 的本地文件系统(例如 APFS、NTFS)。Windows 刷新文件,不尝试打开目录执行 fsync。
74
-
75
- PAP 状态继续加密保存,Agent/Delegation/DPoP 私钥仍由 ANP Identity 托管。文件权限保护边界是当前 OS 用户账户;同用户进程和管理员仍可能访问。已有密文找不到对应密钥或密钥文件损坏时返回 `credential_unavailable`,不会为已有密文生成替代密钥。备份及迁移需同时保留匹配的状态与密钥,并在目标系统重设权限。
76
-
77
- 独立 Host 集成也可从根包或 `./file-secrets` 导入 `FileSecretStore`;`./host-secrets` provider 同样接受 `secretStore: local-file` 和 `secretsRoot`。保留 keyring 时,Linux 仍需要可用的 `secret-tool`。本次未改变默认后端。
54
+ The shared identity can publish DID, CIMD and JWKS material through an identity service such as [AWiki](https://awiki.me); its private keys remain on the client. The PAP plugin owns protocol state and account-token handling, but **does not load or export the Agent/Delegation/DPoP private keys**.
78
55
 
56
+ ## Requirements and installation
79
57
 
80
- 生产网络默认 `SafeHttpsTransport`。受信 Host 的 `papHost.transport` 仅用于显式部署连接策略和组件验证,Remote/Tools 不能覆盖。`privateOrigins`、`portOverrides` 和自定义 DNS 仅适用于明确配置的隔离部署/组件;TLS 始终验证,连接映射只改变 TCP 端口,Host 与 Session htu 保持逻辑 URL。
58
+ - Node.js **^22.19.0 or >=24.0.0**.
59
+ - Compatible DSH Host (current integration targets DSH `0.2.2-rc.1`, Cordis `4.1.0`).
60
+ - [ANP Identity](https://github.com/agent-network-protocol/anp-identity) in the same Host, with a previously created and published identity and approved PAP consumer policy.
61
+ - A writable, private absolute `stateRoot` and working secret backend. The default is the Linux Secret Service / keyring; an explicit `local-file` backend supports additional platforms.
81
62
 
82
- 账户 callback 固定为当前实际发布 CIMD 中的 HTTPS URI。F 不取得管理 DeviceAccess,C 保留 exact-device credential/checkpoint/proof;只提交 state/claim 的独立 SHA-256 摘要与一次领取 secret。verifier、PAP User/Agent ID、sid、第三方 Token 均不交给 callback 服务,完整领取引用只在加密 Store。C 逐次检查当前调用者、政策、publication、provider、manager 以及目标 issuer/resource。
63
+ Install the bundle when its package is available in your registry:
83
64
 
84
- 底层 Host engine 保留显式独立 loopback lane(127.0.0.1 或 [::1] literal、合法显式 port、固定 path、无 query/fragment/userinfo/dot segment),它与默认 HTTPS handoff 分开,不能作为后者失败后的回退。本产品管理 adapter 首先只提供默认 HTTPS handoff,其他 lane 不广告为可用 UI。
85
-
86
- ## 本地状态与生命周期
87
-
88
- 产品将 Company/Session/operation 授权保存在每个 identity binding 独立目录;`selected-identity.json` 仅保存三字段公开 reference(0600、原子替换),每次恢复仍需 C 重新批准 binding。`pap-state.enc` 以 AES-256-GCM 加密,AAD 绑定 schema 和 identity/owner/client 命名空间;目录 0700、文件 0600。跨进程锁内使用 fsync + rename 原子提交;公开映射、Delegation、Token、PKCE 和 callback 领取状态均不明文落盘。状态目录备份与 Host secret store 备份应分别保管。Cordis Context disposer 会关闭 engine、取消在途资源请求并 dispose C facade;输出前仍检查原 engine/selection 与调用 Context,忽略 abort 的旧 transport 也不能交出迟到结果。Keyring provider 的 locksRoot 须使用独立目录,不能与 PAP stateRoot 使用同一个锁目录。
89
-
90
- 恢复后重新经 C 获取目标许可并复核 key handle;持久 handle 本身不授予签名权。中断的 refresh 标为 uncertain,换码中断要求重新授权。委托默认一小时且校验最大二十四小时;自动/显式轮换保持 User ID/sid,并保存旧 key 的停用重试引用。每次 key 创建先持久预留 attempt;创建回执未知时复用原幂等 operation,已停用的失败 attempt 则不会再用;退休未确认时先完成清理再创建下一把 key。外部 Company 可缓存 Delegation 到 exp,本地停止签名不等于立即全网撤销。
91
-
92
- 元数据五分钟过期后自动重新发现;发现失败直接停止,不降级无 AS。没有 expires_in 的 Token 保持未知远端寿命,仅施加本地二十四小时使用上限,不猜测 opaque Token 内容。账户 sign-out 停止本地 Token 使用;未确认撤销保留最小加密重试信息。普通 `disconnectPap` 停止该连接,不隐式退出其他共用账户 Session。
93
-
94
- ## 构建、测试和依赖来源
65
+ ```sh
66
+ pnpm dsh plugin --profile <profile> add @awiki/dsh-pap@0.1.1
67
+ ```
95
68
 
96
- 当前插件面向 Harness `0.2.2-rc.1`,使用 Cordis `4.1.0` 与 Loader `1.1.0`。Remote 描述符使用该版本的延迟 `create()` codec 接口;不再声明兼容 Harness `0.1.5`。
69
+ Build and run unit/component checks from source:
97
70
 
98
- ```bash
71
+ ```sh
72
+ git clone https://github.com/AgentConnect/dsh-pap.git
73
+ cd dsh-pap
99
74
  npm ci --ignore-scripts
100
75
  npm run typecheck
101
- npm test
102
76
  npm run build
103
- npm pack --ignore-scripts --pack-destination .artifacts
104
- ```
105
-
106
- 生产依赖固定 `proper-lockfile@4.1.2` 和 `zod@4.6.2`(严格管理 DTO);JOSE 验证使用 Node crypto。Cordis 固定 `4.1.0`,可选 Host peer 为 typert/tools `0.2.2-rc.1`;依赖 integrity 在 package-lock.json 固定。C/A 的新 PAP API 尚未发布到 registry,因此本阶段依赖实际 Host capability 结构绑定,不能宣称已通过新 API 的 registry 安装验证或正式发行门槛。此阶段不将未发布本地源码写作正式 SDK lock 来源。
107
-
108
- `npm test` 是本仓库单位/隔离组件检查,不启动产品 E2E、System Test 或远程部署。`tests/fixture.ts` 的 in-memory ECDSA custody 仅供测试,和生产 C/A 路径分开。`tests/vectors/local-signer-v2.json` 来自 A 的真实本地 native 公有测试向量,独立 Node 验签;没有私钥。它证明 wire 兼容,不替代实际 C/A Host 接入。
109
-
110
- G 在隔离 HTTPS/PG 环境提供合成用户和 fixture CIMD 时,可执行:
111
-
112
- ```bash
113
- npx tsx scripts/frontvia-component.ts /absolute/path/to/handoff.json --account
77
+ npm test
114
78
  ```
115
79
 
116
- 此 driver 验证 F→G 的真实 Rust Session/对象/账户路径,显式读取 G 的合成 fixture identity key;不用于运行时,不打包进产品,不把该 custody 计为 A/C 原生验收。`--account` 仅在 G 明确开启测试 OTP/consent 模式时运行,受其 OTP 冷却限制。
80
+ The package exposes separate Host service, management Remote, tool and web-client entries. The bundled [Cordis patch](cordis.patch.yml) registers them **disabled by default**; installing the bundle alone does not sign requests or discover Companies. Ensure the installed package version is compatible with your ANP Identity Host API. Source/component verification is not a claim of completed production end-to-end acceptance.
117
81
 
118
- 详细边界和本轮实际证据见 [安全与验收记录](docs/verification.md)。
82
+ ## Configure the Host
119
83
 
120
- ## 新增真实模块链入口
84
+ Configure the **exact** installed identity consumer `@awiki/dsh-pap/plugin` in ANP Identity. The Host must approve the selected identity, purpose/policy, Company targets and scopes. The model cannot change these bindings.
121
85
 
122
- 默认 fixed HTTPS relay 的 F/C/B 链:
86
+ Example Host plugin row:
123
87
 
124
- ```bash
125
- npm run test:callback-component -- /absolute/C/test/helpers/managed-callback-fixture.ts /absolute/user-service /absolute/venv/bin/python
88
+ ```yaml
89
+ - id: pap
90
+ name: '@awiki/dsh-pap/plugin'
91
+ config:
92
+ enabled: true
93
+ stateRoot: /absolute/private/dsh/profile/pap
94
+ policyRef: approved-c-policy-id
95
+ keyringService: org.agentconnect.dsh-pap
126
96
  ```
127
97
 
128
- 该入口使用 C 的真实批准创建/A native 设备 proof、B 实际 factor 注册/Registry/SQL/PAP 发布和生产 ASGI callback handlers,验证 F handoff 登记、公共 callback、原设备一次领取及拒绝路径。B 使用隔离临时 MySQL,邮件投递是 capture;URL 是逻辑 HTTPS 的 ASGI 模块调用,不计远程 TLS 部署。
129
-
130
- C/A 本地 custody 与 G 实际账户组合链:
98
+ If the default keyring is unavailable, **explicitly** select file-backed key storage. The two directories must be distinct, non-overlapping absolute paths:
131
99
 
132
- ```bash
133
- npm run test:native-account-component -- /absolute/C/test/helpers/native-protocol-fixture.ts /absolute/public-materials.json https://agent.test:29443
100
+ ```yaml
101
+ - id: pap
102
+ name: '@awiki/dsh-pap/plugin'
103
+ config:
104
+ enabled: true
105
+ stateRoot: /absolute/private/dsh/profile/pap
106
+ policyRef: approved-c-policy-id
107
+ secretStore: local-file
108
+ secretsRoot: /absolute/private/dsh/secrets/pap
134
109
  ```
135
110
 
136
- 进程打印 `public_materials_ready` 后保持存活;将文件交给 G 的 `--materials-file` public-only fixture,用同一端口开启 fresh OTP 窗口,再在该进程 stdin 输入 G handoff.json 的绝对路径。输入通道应保持打开。它只导出 C 确认的原始 CIMD/JWKS 字节,G 不接收 Agent private key;F 不读 `identity_key`,不使用 FixtureHost,所有 Agent identity/delegated/DPoP 签名均通过真实 C/A。实际 loopback listener 接收 callback,并验证 Direct、DPoP 重启恢复、委托轮换、refresh、revoke 与 signed-out。完成后双方精确清理。
137
-
138
- 上述两条独立链保留其历史边界;后续默认 HTTPS relay 与同一 native 账户已通过下面的新联合入口。宿主 keyring 配置、产品 UI/E2E、System Test 和 registry 发行仍不因此自动通过。
111
+ On Windows use appropriate absolute paths (for example `C:/Users/...`). Never point both settings at the same directory. There is **no automatic fallback or migration** between secret backends. Preserve state and its matching encryption keys during backups or migrations. Old unpublished `@agentconnect/dsh-pap` consumer approvals do not automatically authorize the current `@awiki/dsh-pap/plugin` consumer.
139
112
 
140
- ## 实际 Secret Service 模块验证
113
+ ## Try the live three-protocol service
141
114
 
142
- `npm run test:keyring-container` 在唯一任务镜像中安装 libsecret-tools/gnome-keyring/dbus,使用真实 F 私有包,不安装宿主软件。运行阶段 network none、根文件系统只读、非 root、有限 tmpfs/资源和独立 DBus/XDG/control;密码只在 stdin/内存。已验证创建/读取、PapStore 加密、新 Node 进程恢复、daemon 重启、锁定拒绝、删除 item 后不重建/不改写既有密文,以及无明文回退。详见 `scripts/keyring-container/README.md`(源码内) 和 [验证记录](docs/verification.md)。
115
+ After installation, shared identity publication and Host approval:
143
116
 
144
- 这关闭了隔离容器内真实 Secret Service 的模块证据缺口;宿主仍没有配置该后端,原 `real_missing_backend_only` 结果保持。它不代表宿主 keyring 部署就绪,也不补齐产品 UI/E2E 或 registry 门槛。
117
+ 1. Open the DSH **PAP Company** settings and select an existing published identity.
118
+ 2. Discover the Company at `agent.agent-network-protocol.com`. Its public metadata is at `https://agent.agent-network-protocol.com/.well-known/poppy.json`.
119
+ 3. Connect a **signed-out** Session. Explicitly enable the discovered read operation (`protocol_list` or `protocol_get`) for the agent; optionally enable `post_create` for a deliberate posting test.
120
+ 4. Ask the DSH agent to invoke `pap_status` and `pap_operations`. Use the returned operation reference in `pap_request`:
145
121
 
146
- ## HTTP 认证错误与持久冷却
147
-
148
- 资源冷却按当前本地身份/owner Store 内的 Company+resource 隔离,OAuth endpoint 冷却按 Company+精确 AS issuer 隔离,二者即使同 origin 也不共用窗口。Retry-After 支持 delta-seconds 和 HTTP-date;绝对截止时间以精确整数字符串保存在加密状态中,不截短到 300 秒。缺失/非法值使用本地一秒 fence,不伪造远端 TTL。较短窗口可等待,较长窗口返回 `PapError.retryAfterSeconds` 并保持 fence;超大整数用十进制字符串返回。Host engine 的 `inlineCooldownWaitMs` 为 0–5000ms,默认1500ms,只约束本次愿意等待多久,不缩短服务器窗口。
149
-
150
- close、断开和账户退出可取消等待;这些动作不清除共享 fence。等待后重新检查当前 scope、账户 epoch、连接、generation 和 C lease。实际发送的持锁 callback 在等待 Store 锁/secret resolver 后再次检查真实 C Session/DPoP lease,随后同步完成本地 CAS 并启动 HTTP,不能使用撤销后的旧签名发出请求。
151
-
152
- 401/403 优先解析标准 Bearer/DPoP WWW-Authenticate,支持多 challenge、quoted comma/escape,重复或歧义参数拒绝。`PapError.authHint` 只可能包含固定 scheme、当前 Company 已广告的合法 scope 和当前 resource 的精确标准 PRM URL;realm、error_description、任意 URL/query 或远端秘密不会进入提示/日志。提示不触发 metadata fetch、resource 切换、Token 请求或扩权。非标准 Session/旧登录错误不能通过 OAuth challenge 触发新 sid 或副作用重放。
153
-
154
- 定向回归入口:`npm run test:p22`。该入口仅 owning client/storage/HTTP 检查,不运行 System Test 或产品 E2E。
155
-
156
- ## 默认 HTTPS relay 与同一 native 账户联合入口
157
-
158
- ```bash
159
- npm run test:relay-native-account-component -- /absolute/C/test/helpers/managed-callback-fixture.ts /absolute/user-service /absolute/venv/bin/python /absolute/public-materials.json https://agent.test:29443
122
+ ```text
123
+ pap_status()
124
+ pap_operations()
125
+ pap_request({
126
+ "operationRef": "<enabled post_create reference>",
127
+ "body": { "content": "Hello from DSH via PAP" }
128
+ })
160
129
  ```
161
130
 
162
- 脚本以真实 C 批准/A native/B 注册、Registry 和 PAP 发布建立同一身份,重新打开相同 native Store 安装显式 PAP consumer policy,导出原始 B CIMD/JWKS 公材料;不导出 provider、lease、Token 或 Agent private key。它打印 `public_materials_ready` 和精确的 `callbackForward` 后等待 stdin。G 使用 `--materials-file <file> --fixture-port 29443 --callback-forward <listener URL> --handoff-only` 开启独立 fresh 账户窗口,再将其 handoff.json 的绝对路径输入该进程。
131
+ The placeholder must be replaced by the **actual enabled operationRef**; the model cannot manufacture one. Read the published result on the [ANP website posts page](https://agent-network-protocol.com/zh/posts). Documentation can be read using the appropriate discovered read operation and its declared parameters.
132
+
133
+ **No user-account OAuth login is needed for this signed-out demo.** For Companies requiring an account, a user must explicitly start Direct Sign-In through the management UI, complete the Company's authorization, and enable the relevant account-bound operation. The agent cannot initiate a browser login or collect authorization codes.
163
134
 
164
- 该 lane 始终注册 `https://agent.test:29443/user-service/v1/pap-callback` 并使用显式 `handoff`。G 只对这个精确 HTTPS GET 转发原 query 到 Node 的 127 listener,不转 caller auth/cookie/DPoP/Session,也不记录 query/code;Node 只转发到 `helper.fetch` 的真实 B public callback,不自行保存或领取 code。随后 F `DeviceCallbackHandoff` 经真实 C 原设备 proof 领取,由原本地 PKCE verifier 兑换 G 的实际 code。没有 fake callback、没有以 RFC8252 loopback URI 替代默认 relay。内部 127 HTTP 仅为隔离 HTTPS publisher 到 B ASGI 的测试转发路径。
135
+ ## Tools and user controls
165
136
 
166
- 实际同一链已通过真实 HTTPS 公材料/AS code→B receive→C device claim→PKCE/DPoP account→restart key restore→delegation rotation→refresh→revoke→signed-out。生产执行 lineage 为 `7325b80`,测试脚本之后单独入库;双方精确清理,只有隔离 master 和外部邮件投递 capture 的已声明边界。它是源级真实模块证据,不是已安装 DSH 产品、外部短信/邮件投递、宿主 keyring 配置或 registry 发布 gate。
137
+ | Interface | Available operations |
138
+ | --- | --- |
139
+ | **Agent tools** | `pap_status`, `pap_operations`, `pap_request` only |
140
+ | **User management** | `identity/select`, `company/discover`, `session/connect`, `session/disconnect`, `operation/enable`, `operation/disable` |
141
+ | **Account management** | `account/sign-in`, `account/collect`, `account/refresh`, `account/sign-out` |
167
142
 
168
- ## S15 凭据历史与 legacy 门禁
143
+ The management Remote must be exposed only through an authenticated **user** gateway, never as a general model tool. Agent calls accept a previously authorized `operationRef` plus declared path/query fields and an optional JSON body; they do not accept arbitrary URL/method/headers, raw authorization tokens or resource changes.
169
144
 
170
- AT/RT 的脱敏不限于一次请求或当前 grant:有效 AS response 在返回解析前先归档到现有 AES-GCM PapStore 的私有 credentialVault,替换、刷新和清除前也在同一事务保存旧值。vault 与协议授权分离,只用于防止已知凭据从任意业务 JSON key/value、Company 名称、operation 路径、公开状态或错误字段回显;它不构成 grant 或恢复签名权。运行内已知寿命使用单调时钟并 pin 在途响应;重启后的私有 tombstone 保守按未知剩余寿命保留,不凭本地24h使用上限猜测 AS/RT 期限。上限4096值/4MiB,容量不足锁闭输出,不驱逐仍可能有效值。不能把旧 AT 从当前 grant 消失当作脱敏完成。
145
+ ## Service Agent example
171
146
 
172
- 当前 state/verifier/claim/sid 等映射与本次真正发送的材料也会过滤;只有明确用户 account/sign-in 的 authorizationUrl 字段保留正常 OAuth state/challenge。跨请求及跨重启的持久历史承诺专指已观察 AT/RT,不宣称无限重构已删除的旧协议 nonce 或未知过去值。
147
+ https://agent-network-protocol.com is the project's example Service Agent for
148
+ MCP, ANP and PAP. The example is mentioned in the Agent-visible discovery/status
149
+ tool descriptions. To see ANP in action, discover `agent-network-protocol.com`,
150
+ read the returned descriptions/interfaces, then invoke a read-only discovered
151
+ operation. For PAP, explicitly discover that Company in settings, connect and
152
+ enable the desired operation. MCP uses a separately configured server connection.
153
+ No reference here grants identity access, enables an operation, bypasses protocol
154
+ validation, or sends a request automatically. The website deployment is managed
155
+ by the service operator and is outside this UI change's acceptance scope.
173
156
 
174
- 新 vault 有完整性标记。老加密状态没有 vault,但存在任意 grant、account slot、登录事务(包括 cancelled/failed)、AS nonce 或 DPoP retirement 迹象时,迁移为 legacy_incomplete;seed 当前已知 Token 不等于补全历史。Agent 请求及动态 Company/catalog/status 输出停止,只有固定迁移码。用户只见 Host 产生的账户引用与封闭状态,可尝试正常撤销当前账户;退出/latest revoke 不会自动把历史标为完整。旧纯 NoAS 状态仅在无账户处理迹象时可迁移 complete。加密数据、epoch、cooldown fence 都保留,不自动 wipe、新建 key 或放开权限。
157
+ ## Basic and advanced settings
175
158
 
176
- 本轮没有“confirmed:true”、重置按钮或普通 Remote 恢复入口。处理 legacy 需要独立受信 Host 运维证据:对应 issuer/client/resource 的全部旧凭据已撤销事实,并保留审计来源;不能让模型或普通业务请求声明已确认。既有未知旧值无法重构,不把它们写成已覆盖。
159
+ The normal PAP page shows the active published identity, Company discovery,
160
+ one regular connection and explicit operation permission. Existing regular
161
+ connections are reused by the UI rather than creating duplicates. Connection
162
+ IDs/cleanup, per-operation connection changes, scopes and optional account
163
+ management are collapsed by default. NoAS companies do not show account-login
164
+ controls. Existing sessions are never deleted automatically, accounts/scopes are
165
+ never selected implicitly, and saving a different operation connection remains
166
+ an explicit user action.
177
167
 
178
- ## 实际产品模块与默认秘密后端组件
168
+ ## Security and current limits
179
169
 
180
- `scripts/product-native-component.ts` 使用真实 fresh C approval/B strict 注册发布→同 store C Host 重开→实际 F plugin/manager/tools 与实际 DSH ToolRuntime,向独立 HTTPS NoAS verifier 发送2条实际 Delegation/Session;批准前0请求、卸载后0后续请求、Company Token0。F 只注入隔离网络 transport,秘密存储走默认 KeyringSecretStore。Host 进程中的私有 secret-tool shim 固定本地 Docker socket 和 inspected container ID,访问任务专属容器真实 DBus/gnome-keyring;不装宿主软件、不读用户 keyring、不改 HOME,所有 key/password 仅 stdin/内存。此为实际 factory/default backend 模块证据,不是 GUI 产品 E2E。
170
+ - PAP state is AES-256-GCM encrypted and partitioned by identity/profile. Missing or mismatched secret keys fail closed.
171
+ - Local identity custody provides scoped, revocable signing capabilities; this plugin does not expose the private keys or a remote signing endpoint.
172
+ - Signed-out PAP makes no account-authority claim; account OAuth is explicit and separate from MCP machine tokens.
173
+ - Side-effecting requests are not blindly replayed after ambiguous failures. Token rotation, disconnect and sign-out enforce state and authorization fences.
174
+ - Browser Join, Mediated Sign-In, Device Sign-In, PS384, automatic account merging and a PAP-over-MCP transport are **not implemented** in this client.
175
+ - Existing legacy account state may require a controlled migration/revocation review; do not reset encrypted state or silently create replacement encryption keys.
181
176
 
182
- 侧车入口 `scripts/secret-service-sidecar-component.ts` 单独验证当前加密 vault 的真实 backend create/get、daemon 重启、新 Host Node 进程恢复和无明文;镜像复用已核验 fea7c2…,不是把整个 C/Python 仓库搬入容器。原始宿主缺后端记录仍成立,容器后端不代表宿主已配置。
177
+ For detailed API, storage, verification and recovery notes see the [Chinese technical README](README.zh-CN.md), [verification log](docs/verification.md) and [source code](src/).
183
178
 
184
- 新实际账户入口 `scripts/product-account-component.ts` 已实际通过:使用新 C factory 与 user Remote、固定 B HTTPS relay、G 实际 OAuth/DPoP 及默认 backend;显式当前 A runtime aliases,并核实际加载冻结 native FFB。它不是旧直接 PapClient/managed-callback helper 的替代计数,完整来源见验证记录。
179
+ ## Related projects
185
180
 
186
- ## npm scope and existing source profiles
181
+ [ANP Identity](https://github.com/agent-network-protocol/anp-identity) · [dsh-anp](https://github.com/agent-network-protocol/dsh-anp) · [service-agent](https://github.com/AgentConnect/service-agent) · [DSH Harness Identity](https://github.com/AgentConnect/dsh-harness-identity) · [AWiki User Service](https://github.com/AgentConnect/user-service)
187
182
 
188
- The published package is `@awiki/dsh-pap`. Its identity consumer is
189
- `@awiki/dsh-pap/plugin`; manager and tool entries use the same package scope.
190
- Install with `pnpm dsh plugin --profile <profile> add @awiki/dsh-pap@0.1.0`.
183
+ ## License
191
184
 
192
- Earlier unpublished source profiles used `@agentconnect/dsh-pap`. They are not
193
- silently aliased or granted access under the new consumer. Configure the new
194
- installed consumer explicitly in ANP Identity's allow list and protocol policy,
195
- then approve it. Keep the existing identity Store and keys unchanged. Start the
196
- new PAP consumer with its own empty state root and matching secret namespace;
197
- retain old encrypted PAP state and its keys separately rather than editing its
198
- binding, overwriting keys, or attempting an unauthenticated in-place migration.
185
+ [Apache-2.0](LICENSE).