@awiki/dsh-pap 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# DSH PAP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A PAP 0.3 client for DeepSeek Harness (DSH), powered by a reusable, locally held agent identity.**
+
+English | [简体中文](README.zh-CN.md)
+
+[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)
+
+## The problem
+
+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.
+
+PAP is one of three complementary paths in the shared-identity system:
+
+| Protocol | Identity and authentication | Integration |
+| --- | --- | --- |
+| **ANP** | Published `did:wba` identity; per-request HTTP signatures | [dsh-anp](https://github.com/agent-network-protocol/dsh-anp) |
+| **MCP** | CIMD/JWKS client metadata; `private_key_jwt` and policy-approved `client_credentials` OAuth | [DSH MCP Host](https://github.com/AgentConnect/dsh-harness-identity) |
+| **PAP 0.3** | Identity-signed Delegation and per-request `Poppy-Session`, with optional separate account authorization | **This plugin** |
+
+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.
+
+## Features
+
+- Discover PAP Companies and advertised OpenAPI operations over constrained HTTPS.
+- Create regular or anonymous signed-out Sessions and generate fresh PAP Delegation/Session proofs through the local identity Host.
+- Enable only explicitly user-approved operations; the agent cannot choose arbitrary endpoints, methods, headers, tokens or scopes.
+- Support **Direct Sign-In** when a Company requires an account: user-initiated OAuth authorization, PKCE, optional DPoP, protected token storage, refresh and sign-out.
+- 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.
+- Expose a DSH settings interface and narrowly scoped model tools.
+
+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.
+
+## Architecture
+
+```text
+DSH user / settings UI          DSH Agent
+  | identity + Company            | approved operation only
+  | selection / consent           v
+  v                            pap_status / pap_operations / pap_request
+PAP management Remote ---------> dsh-pap Host plugin
+                                      |
+                            limited identity capability
+                                      |
+                         ANP Identity (same Host)
+                         local Delegation / Session / DPoP signing
+                                      |
+                              signed HTTPS request
+                                      v
+                                PAP Company
+                           OpenAPI / business resources
+```
+
+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**.
+
+## Requirements and installation
+
+- Node.js **^22.19.0 or >=24.0.0**.
+- Compatible DSH Host (current integration targets DSH `0.2.2-rc.1`, Cordis `4.1.0`).
+- [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.
+- 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.
+
+Install the bundle when its package is available in your registry:
+
+```sh
+pnpm dsh plugin --profile <profile> add @awiki/dsh-pap@0.1.1
+```
+
+Build and run unit/component checks from source:
+
+```sh
+git clone https://github.com/AgentConnect/dsh-pap.git
+cd dsh-pap
+npm ci --ignore-scripts
+npm run typecheck
+npm run build
+npm test
+```
+
+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.
+
+## Configure the Host
+
+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.
+
+Example Host plugin row:
+
+```yaml
+- id: pap
+  name: '@awiki/dsh-pap/plugin'
+  config:
+    enabled: true
+    stateRoot: /absolute/private/dsh/profile/pap
+    policyRef: approved-c-policy-id
+    keyringService: org.agentconnect.dsh-pap
+```
+
+If the default keyring is unavailable, **explicitly** select file-backed key storage. The two directories must be distinct, non-overlapping absolute paths:
+
+```yaml
+- id: pap
+  name: '@awiki/dsh-pap/plugin'
+  config:
+    enabled: true
+    stateRoot: /absolute/private/dsh/profile/pap
+    policyRef: approved-c-policy-id
+    secretStore: local-file
+    secretsRoot: /absolute/private/dsh/secrets/pap
+```
+
+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.
+
+## Try the live three-protocol service
+
+After installation, shared identity publication and Host approval:
+
+1. Open the DSH **PAP Company** settings and select an existing published identity.
+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`.
+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.
+4. Ask the DSH agent to invoke `pap_status` and `pap_operations`. Use the returned operation reference in `pap_request`:
+
+```text
+pap_status()
+pap_operations()
+pap_request({
+  "operationRef": "<enabled post_create reference>",
+  "body": { "content": "Hello from DSH via PAP" }
+})
+```
+
+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.
+
+**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.
+
+## Tools and user controls
+
+| Interface | Available operations |
+| --- | --- |
+| **Agent tools** | `pap_status`, `pap_operations`, `pap_request` only |
+| **User management** | `identity/select`, `company/discover`, `session/connect`, `session/disconnect`, `operation/enable`, `operation/disable` |
+| **Account management** | `account/sign-in`, `account/collect`, `account/refresh`, `account/sign-out` |
+
+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.
+
+## 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.
+
+## Basic and advanced settings
+
+The normal PAP page shows the active published identity, Company discovery,
+one regular connection and explicit operation permission. Existing regular
+connections are reused by the UI rather than creating duplicates. Connection
+IDs/cleanup, per-operation connection changes, scopes and optional account
+management are collapsed by default. NoAS companies do not show account-login
+controls. Existing sessions are never deleted automatically, accounts/scopes are
+never selected implicitly, and saving a different operation connection remains
+an explicit user action.
+
+## Security and current limits
+
+- PAP state is AES-256-GCM encrypted and partitioned by identity/profile. Missing or mismatched secret keys fail closed.
+- Local identity custody provides scoped, revocable signing capabilities; this plugin does not expose the private keys or a remote signing endpoint.
+- Signed-out PAP makes no account-authority claim; account OAuth is explicit and separate from MCP machine tokens.
+- Side-effecting requests are not blindly replayed after ambiguous failures. Token rotation, disconnect and sign-out enforce state and authorization fences.
+- Browser Join, Mediated Sign-In, Device Sign-In, PS384, automatic account merging and a PAP-over-MCP transport are **not implemented** in this client.
+- Existing legacy account state may require a controlled migration/revocation review; do not reset encrypted state or silently create replacement encryption keys.
+
+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/).
+
+## Related projects
+
+[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)
+
+## License
+
+[Apache-2.0](LICENSE).