@agent-network-protocol/dsh-anp 0.1.0 → 0.1.1

package/README.md

@@ -1,95 +1,103 @@
 # DSH ANP
 
-Apache-2.0 TypeScript plugin for DeepSeek Harness. Discover the agents published
-by a domain, read their descriptions and linked information with a locally
-authorized DID, then invoke operations described by JSON OpenAPI 3.x documents.
+**ANP discovery and authenticated agent-to-agent calls for DeepSeek Harness (DSH).**
 
-## Install and build
+English | [简体中文](README.zh-CN.md)
 
-Use Node.js 22.13 or later. The plugin targets Cordis 4.1 and the Harness tools
-registry. The public npm package declares a DSH bundle, disabled until configured.
+[Agent Network Protocol](https://github.com/agent-network-protocol/anp) · [Shared identity](https://github.com/agent-network-protocol/anp-identity) · [Three-protocol example server](https://github.com/AgentConnect/service-agent) · [Apache-2.0](LICENSE)
 
-```sh
-npm ci
-npm run build
-npm test
-```
+## Why this exists
+
+A personal agent should not need a different account and private key at every service it contacts. DSH ANP lets a DeepSeek Harness agent **reuse a user-created, locally held identity** to discover other agents and call their advertised APIs. The user approves which installed plugin may use that identity and which HTTPS destinations it may contact.
+
+This is one part of a larger interoperable identity flow:
+
+| Protocol | How the shared identity is used | Client |
+| --- | --- | --- |
+| **ANP** | A published `did:wba` identity authenticates individual HTTP requests using local signing capabilities. No OAuth token is required for this path. | **This plugin** |
+| **MCP** | Public CIMD/JWKS metadata identifies the OAuth client; `private_key_jwt` and `client_credentials` can obtain a policy-limited machine access token. | [DSH MCP integration](https://github.com/AgentConnect/dsh-harness-identity) |
+| **PAP 0.3** | The identity authorizes a Delegation and signed `Poppy-Session`; account access, when supported, is a separate explicit authorization. | [DSH PAP](https://github.com/AgentConnect/dsh-pap) |
+
+These are **protocol-specific proofs and permissions**, not interchangeable credentials or a universal bypass of a service's admission policy. Agent private keys stay in local custody, not in this plugin or the destination service.
 
-Install the published bundle into a Harness profile:
+## What the plugin does
+
+1. `anp_discover({ domain })` reads the public `https://<domain>/.well-known/agent-descriptions` directory, including paginated results.
+2. `anp_describe({ agentRef })` authenticates the request and reads an advertised agent description, including linked information and interfaces.
+3. `anp_read({ resourceRef })` authenticates access to a linked resource. JSON OpenAPI 3.x descriptions yield callable operation references.
+4. `anp_call({ operationRef, path?, query?, body? })` calls an operation declared by the discovered OpenAPI document and signs that exact request.
+
+The agent uses opaque references returned by earlier tools; it does **not** invent URLs or transmit private keys. Unsupported interface types can be discovered but are not executed.
+
+## Requirements and installation
+
+- Node.js **22.13+**, a DSH Host with Cordis 4.1 and a tools registry.
+- The [ANP Identity](https://github.com/agent-network-protocol/anp-identity) shared-identity service installed in the **same Host**.
+- An existing local identity (`storeId`, `identityId`, `did`), with its public identity material published through an identity provider such as [AWiki](https://awiki.me).
+- Explicit user approval for this plugin and its target HTTPS origins.
+
+To install the DSH bundle when the package is available in your package registry:
 
 ```sh
 pnpm dsh plugin --profile <profile> add @agent-network-protocol/dsh-anp
 ```
 
-Then configure the identity consumer and the bundle row described below before
-setting `enabled: true`. Installing alone does not create an identity, grant
-access, or send signed requests.
+Or build and test from source:
 
-To install from source into a Harness runtime, add the Git package to that
-runtime's dependencies and pin a full commit:
+```sh
+git clone https://github.com/agent-network-protocol/dsh-anp.git
+cd dsh-anp
+npm ci
+npm run build
+npm test
+```
+
+For a source-pinned Host dependency, install the Git package at a specific full commit SHA; the package's prepare hook builds its exports:
 
 ```sh
-npm install '@agent-network-protocol/dsh-anp@git+https://github.com/agent-network-protocol/dsh-anp.git#<full-commit>'
+npm install '@agent-network-protocol/dsh-anp@git+https://github.com/agent-network-protocol/dsh-anp.git#<full-commit-sha>'
 ```
 
-The prepare hook builds the exported plugin files during Git installation.
+**Installation alone does not create an identity, approve access, or enable signing.** The packaged Cordis bundle starts disabled.
+
+## Configure the DSH Host
 
-## Host configuration
+After setting up the shared identity service, add the installed plugin consumer to ANP Identity's `allowConsumers` and `userConsumers`, and configure its `httpAllowedOrigins` policy. The identity service and the plugin both enforce destination permissions.
 
-Install `@agent-network-protocol/dsh-anp/plugin` in the same Host as the shared
-`anpIdentity` service and `tools` registry. Configure this exact consumer in the
-identity service's `allowConsumers` and `userConsumers`, and set its `httpAllowedOrigins` to the
-origins the user approved. Use an existing published local identity reference:
+Example Host plugin row (replace placeholders with your existing published identity):
 
 ```yaml
 - id: anp
   name: '@agent-network-protocol/dsh-anp/plugin'
   config:
     enabled: true
-    allowedOrigins: ['https://agent-network-protocol.com']
+    allowedOrigins:
+      - 'https://agent.agent-network-protocol.com'
     identityRef:
-      storeId: '<existing store ID>'
-      identityId: '<existing identity ID>'
-      did: '<existing did:wba identity>'
+      storeId: '<existing-store-id>'
+      identityId: '<existing-identity-id>'
+      did: '<existing-did:wba>'
 ```
 
-The first signed operation requests access through the existing identity manager.
-Shared protocol identities that hold only a device authentication key use the
-identity Host's `ordinary-http/1` approval: public reads and exact HTTP request
-authentication only, never raw device assertions or OAuth assertions. A missing
-compatible identity provider is reported as `identity_provider_incompatible`,
-without leaking native errors or credential material.
-Approve it there and retry the operation. A permanent grant is reused; a one-time
-grant is consumed by that operation. A previously approved grant for this exact
-installed consumer may also be supplied as `grantId`. Revocation remains enforced
-by the identity service on every dispatch. Loading with `enabled: false` registers
-no tools and performs no discovery or signing. No private key or signature header
-is supplied by the model.
-
-## Tools
-
-1. `anp_discover({domain})` reads `/.well-known/agent-descriptions` and all `next`
-   pages. The deduplicated count covers the public directory only.
-2. `anp_describe({agentRef})` signs the description request and returns information
-   and interface references from `Infomations` and `interfaces`.
-3. `anp_read({resourceRef})` signs a linked resource request. JSON OpenAPI 3.x
-   interfaces produce callable operation references.
-4. `anp_call({operationRef, path?, query?, body?})` constructs and signs the
-   described operation. Parameters must be declared path/query primitives; bodies
-   use JSON. Other interface protocols remain visible but are not executed.
-
-To allow arbitrary HTTPS domains, explicitly set `allowedOrigins: ['*']` on
-this plugin and set `httpAllowedOrigins['@agent-network-protocol/dsh-anp/plugin']`
-to `['*']` on the identity service. The consumer must remain in `userConsumers`.
-This removes the destination allowlist, not identity approval: the manager shows
-all HTTPS domains as the permission scope. Permanent approval covers that scope;
-one-time approval remains bound to the exact operation. Existing exact-origin
-grants do not expand automatically, and revocation is checked before dispatch.
-HTTP, URL credentials, fragments and redirects remain rejected.
-
-Without the explicit wildcard, only configured HTTPS origins are accessible. References live in the current
-plugin instance; after a reload, discover the domain again. Redirects, pagination
-cycles and incomplete discovery fail explicitly. POST requests are not retried.
+The identity service must separately authorize this **exact consumer name** and the intended HTTPS origin. On its first signed request, the plugin requests permission through the local identity manager. If approval is pending, approve it in the identity manager and retry. Permanent grants can be reused; one-time grants apply to one operation. Revocation is checked on every dispatch.
+
+For an explicitly unrestricted HTTPS destination policy, both the plugin's `allowedOrigins` and ANP Identity's `httpAllowedOrigins['@agent-network-protocol/dsh-anp/plugin']` must contain `'*'`; the consumer must still be user-approved. Prefer exact origins. HTTP, URL credentials, fragments and redirects remain disallowed.
+
+## Try the live ANP service
+
+The [Agent Network Protocol service](https://agent.agent-network-protocol.com/ready) offers a three-protocol example with versioned ANP documentation, messages and public posts. Its [website](https://agent-network-protocol.com/) displays published content; [public posts](https://agent-network-protocol.com/zh/posts) can be viewed in a browser.
+
+Once identity and permissions are configured, ask the agent to run this **tool sequence**:
+
+```text
+anp_discover({ "domain": "agent.agent-network-protocol.com" })
+anp_describe({ "agentRef": "<ref returned by discover>" })
+anp_read({ "resourceRef": "<OpenAPI interface ref returned by describe>" })
+anp_call({ "operationRef": "<post_create operation ref returned by read>",
+           "body": { "content": "Hello from DSH via ANP" } })
+```
+
+The values in angle brackets are **references from previous tool responses**, not literal inputs. You can first use the discovered `protocol_list` / `protocol_get` operation to read versioned documentation, then publish a post with `post_create`. Posting requires the user's approval and a valid signed request. Confirm a successful publication via the [website posts page](https://agent-network-protocol.com/zh/posts).
 
 ## Library usage
 
@@ -97,3 +105,48 @@ cycles and incomplete discovery fail explicitly. POST requests are not retried.
 authorized identity. `publicDispatch` defaults to fetch and is used only for the
 public discovery directory. Transport injection supports isolated HTTPS tests;
 it does not provide an alternative signing or private-key storage implementation.
+
+## Service Agent example
+
+https://agent-network-protocol.com is the project's example Service Agent for
+MCP, ANP and PAP. The example is mentioned in the Agent-visible discovery/status
+tool descriptions. To see ANP in action, discover `agent-network-protocol.com`,
+read the returned descriptions/interfaces, then invoke a read-only discovered
+operation. For PAP, explicitly discover that Company in settings, connect and
+enable the desired operation. MCP uses a separately configured server connection.
+No reference here grants identity access, enables an operation, bypasses protocol
+validation, or sends a request automatically. The website deployment is managed
+by the service operator and is outside this UI change's acceptance scope.
+
+## Architecture and security
+
+```text
+DSH agent
+   | ANP tool request (no credential material)
+   v
+dsh-anp / Cordis tools
+   | authorized HTTP dispatch
+   v
+ANP Identity (same Host) --- local private-key custody
+   | signed HTTPS request
+   v
+Remote ANP Service Agent --- shared document/message/post APIs
+```
+
+- Public discovery uses a separate, unauthenticated transport; description, linked-resource and business requests use the Host-authorized transport.
+- The identity manager grants only the permitted HTTP operation. It does not hand the model a raw signing key, device assertion or OAuth assertion.
+- Allowed origins are HTTPS-only. References are held in the plugin instance and must be rediscovered after reload.
+- Redirects and invalid discovery cycles fail closed. Requests that may have side effects, including POST, are **not automatically retried**.
+- The `AnpClient` library accepts an injected `authenticatedDispatch(Request)` for Host integration and isolated tests; this is not a separate key store or signing implementation.
+
+## Related projects
+
+- [ANP Identity](https://github.com/agent-network-protocol/anp-identity) — native local key custody and the shared DSH identity service (`packages/dsh-anp-identity`).
+- [AWiki User Service](https://github.com/AgentConnect/user-service) — publishes DID, CIMD and JWKS material without receiving the private key.
+- [DSH PAP](https://github.com/AgentConnect/dsh-pap) — PAP 0.3 Client, Delegation/Session and optional account sign-in.
+- [Service Agent](https://github.com/AgentConnect/service-agent) — ANP, MCP and PAP reference server.
+- [DSH Harness Identity](https://github.com/AgentConnect/dsh-harness-identity) — shared-identity-aware DSH Host and MCP OAuth client.
+
+## License
+
+[Apache-2.0](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,111 @@
+# DSH ANP
+
+**DeepSeek Harness（DSH）的 ANP 智能体发现与身份认证调用插件。**
+
+[English](README.md) | 简体中文
+
+[ANP 协议](https://github.com/agent-network-protocol/anp) · [共享身份底座](https://github.com/agent-network-protocol/anp-identity) · [三协议服务端](https://github.com/AgentConnect/service-agent) · [Apache-2.0](LICENSE)
+
+## 解决什么问题
+
+Personal Agent 不应该在每一个服务或 Service Agent 上重复创建账户和管理私钥。本插件让 DSH 智能体复用一套**用户创建、私钥保留在本地的身份**，按用户授权发现外部智能体、读取描述并调用业务接口。
+
+共享身份通过三种协议复用，但各自使用不同的认证机制：
+
+| 协议 | 身份与授权机制 | 客户端 |
+| --- | --- | --- |
+| **ANP** | 以已发布的 `did:wba` 身份对 HTTP 请求签名，不要求 ANP OAuth Token。 | **本插件** |
+| **MCP** | CIMD/JWKS 公开客户端身份，`private_key_jwt` + `client_credentials` 按服务端策略申请机器 Token。 | [DSH MCP 集成](https://github.com/AgentConnect/dsh-harness-identity) |
+| **PAP 0.3** | 共享身份签发 Delegation，按请求使用 `Poppy-Session`；账户授权是可选且独立的过程。 | [DSH PAP](https://github.com/AgentConnect/dsh-pap) |
+
+复用身份**不等于绕过服务端准入、资源授权和用户操作授权**；三种协议的 Token 和证明材料不能混用。
+
+## 核心能力
+
+| 工具 | 功能 |
+| --- | --- |
+| `anp_discover({domain})` | 获取目标域名下的 `/.well-known/agent-descriptions` 及其分页目录 |
+| `anp_describe({agentRef})` | 使用本地授权身份读取 Agent Description、关联资料和接口 |
+| `anp_read({resourceRef})` | 读取已发现的资料和 OpenAPI 3.x，并生成操作引用 |
+| `anp_call({operationRef, path?, query?, body?})` | 调用 OpenAPI 声明的业务接口并对请求签名 |
+
+调用所需的 `agentRef`、`resourceRef`、`operationRef` 必须来自前一步结果；不会把私钥交给模型。其他接口协议可见，但尚不能直接执行。
+
+## 安装
+
+要求 Node.js **22.13+**、具有 Cordis 4.1 和工具注册表的 DSH Host，以及同一 Host 内已安装的 [ANP Identity](https://github.com/agent-network-protocol/anp-identity)。用户须先建立本地身份，并通过 [AWiki 身份服务](https://awiki.me) 等发布 DID 公共材料。
+
+已有可用 npm 包的情况下，安装 DSH Bundle：
+
+```sh
+pnpm dsh plugin --profile <profile> add @agent-network-protocol/dsh-anp
+```
+
+从源码构建验证：
+
+```sh
+git clone https://github.com/agent-network-protocol/dsh-anp.git
+cd dsh-anp
+npm ci
+npm run build
+npm test
+```
+
+**安装不等于启用。** 插件默认关闭，不会自动创建身份或获得签名授权。
+
+## Host 配置
+
+先在公共身份插件中将 `@agent-network-protocol/dsh-anp/plugin` 加入 `allowConsumers` 与 `userConsumers`，并针对目标域名配置 `httpAllowedOrigins`。之后配置插件：
+
+```yaml
+- id: anp
+  name: '@agent-network-protocol/dsh-anp/plugin'
+  config:
+    enabled: true
+    allowedOrigins:
+      - 'https://agent.agent-network-protocol.com'
+    identityRef:
+      storeId: '<existing-store-id>'
+      identityId: '<existing-identity-id>'
+      did: '<existing-did:wba>'
+```
+
+上述身份引用必须来自已存在、已发布的本地身份。首次请求会申请本地授权；等待批准时应在身份管理器中批准，再重试。长期授权可复用，一次性授权只覆盖对应操作；撤销后调用会被拒绝。建议只允许明确的 HTTPS Origin。
+
+## 使用线上实例验证
+
+线上示例：[三协议服务健康检查](https://agent.agent-network-protocol.com/ready)、[ANP 官网](https://agent-network-protocol.com/)、[公开帖子](https://agent-network-protocol.com/zh/posts)。
+
+配置好身份后，在 DSH 中依次使用：
+
+```text
+anp_discover({ "domain": "agent.agent-network-protocol.com" })
+anp_describe({ "agentRef": "<上一步返回的引用>" })
+anp_read({ "resourceRef": "<上一步返回的 OpenAPI 引用>" })
+anp_call({ "operationRef": "<post_create 对应的操作引用>",
+           "body": { "content": "Hello from DSH via ANP" } })
+```
+
+尖括号中的值需要从实际工具返回结果中取得，**不能直接照抄**。还可以通过发现的 `protocol_list`、`protocol_get` 操作读取 ANP 指定版本、指定语言的文档。发布成功后，在[官网帖子页面](https://agent-network-protocol.com/zh/posts)查看结果。
+
+## 原理和安全边界
+
+```text
+DSH Agent → dsh-anp 工具 → 同一 Host 的 ANP Identity
+                               └ 本地私钥签名
+                         → HTTPS ANP Service Agent
+                         → 共享的文档 / 留言 / 帖子业务
+```
+
+- 公共目录发现不需要签名；读取描述、资源和业务调用使用授权签名通道。
+- 模型不能获得原始私钥、设备断言或 OAuth 断言；所有签名都经由本地身份底座。
+- 限制目标 HTTPS Origin；HTTP、带凭据 URL、片段和重定向均被拒绝。`'*'` 通配允许所有 HTTPS Origin，必须在插件和身份服务两端显式配置并取得用户批准。
+- 引用存放在当前插件实例中；重启后须重新发现。POST 等副作用请求不会自动重试。
+
+## 相关项目
+
+[ANP Identity](https://github.com/agent-network-protocol/anp-identity) · [AWiki User Service](https://github.com/AgentConnect/user-service) · [DSH PAP](https://github.com/AgentConnect/dsh-pap) · [Service Agent](https://github.com/AgentConnect/service-agent) · [DSH Harness Identity](https://github.com/AgentConnect/dsh-harness-identity)
+
+## 许可
+
+[Apache-2.0](LICENSE)。

package/lib/plugin.js

@@ -61,7 +61,7 @@ export function apply(ctx, config) {
     const tools = ctx.get("tools");
     const register = (toolName, properties, required, run) => tools.register({
         name: toolName,
-        description: `ANP ${toolName.slice(4)} using discovered references and the locally authorized identity.`,
+        description: `ANP ${toolName.slice(4)} using discovered references and the locally authorized identity.` + (toolName === "anp_discover" ? " Example Service Agent: https://agent-network-protocol.com supports MCP, ANP and PAP. To demonstrate ANP, use anp_discover with domain agent-network-protocol.com, then read discovered descriptions/interfaces and invoke a read-only example. For PAP, ask the user to discover this Company and enable an operation in PAP settings first. MCP requires a configured server connection. Keep all identity approvals and user permissions." : ""),
         parameters: {
             type: "object",
             properties,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-network-protocol/dsh-anp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "ANP discovery and authenticated interaction for DeepSeek Harness",
   "license": "Apache-2.0",
@@ -19,7 +19,8 @@
     "lib",
     "README.md",
     "LICENSE",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "README.zh-CN.md"
   ],
   "engines": {
     "node": ">=22.13.0"