agent-passport-system 2.6.0-alpha.8 → 2.6.0-alpha.9

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/agent-passport-system)](https://www.npmjs.com/package/agent-passport-system)
 [![license](https://img.shields.io/npm/l/agent-passport-system)](https://github.com/aeoess/agent-passport-system/blob/main/LICENSE)
-[![tests](https://img.shields.io/badge/tests-2536%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
+[![tests](https://img.shields.io/badge/tests-3113%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18749779.svg)](https://doi.org/10.5281/zenodo.18749779)
 
 > **For AI agents:** visit [aeoess.com/llms.txt](https://aeoess.com/llms.txt) for machine-readable docs.
@@ -19,7 +19,7 @@ npm install agent-passport-system
 
 ## Quick Start
 
-Lead with the curated essentials. `agent-passport-system/core` exposes the ~25 functions that 90% of integrations need — identity, delegation, enforcement, commerce, reputation, key management. The full `agent-passport-system` root import is unchanged and backward compatible: pull from it when Core does not cover your case.
+Lead with the curated essentials. `agent-passport-system/core` exposes the ~25 functions that 90% of integrations need: identity, delegation, enforcement, commerce, reputation, key management. The full `agent-passport-system` root import is unchanged and backward compatible: pull from it when Core does not cover your case.
 
 ```typescript
 import {
@@ -27,12 +27,22 @@ import {
   evaluateIntent, commercePreflight, generateKeyPair
 } from 'agent-passport-system/core'
 
-// Full 936-export API still available — use when Core does not cover your case.
+// Full 936-export API still available. Use when Core does not cover your case.
 // import { ... } from 'agent-passport-system'
 ```
 
+## Status labels
+
+Every primitive in this README carries one of three labels so you know how much weight it can bear today.
+
+- **Canonical** -- stable, signed-bytes frozen, covered by conformance fixtures. Breaking these would break cross-implementation verification. Build on them.
+- **Production-Extension** -- shipped and tested, optional, additive to the canonical core. Safe in production; the surface may still grow.
+- **Experimental** -- published for review and tested, but the shape may change. Pin a version before depending on it.
+
 ## Core Protocol
 
+*Status: Canonical.*
+
 What ships in every deployment.
 
 **Identity** -- Ed25519 passports, passport grades 0-3, key rotation, did:aps identifiers.
@@ -47,10 +57,57 @@ What ships in every deployment.
 
 ## Receipt graph
 
-APS receipts are graph-composable. Each claim links to the authority, policy, action, observation, or evidence it depends on, so a verifier can walk from any receipt back to its supporting facts and stop at the boundary it cares about. This is documentation of existing structure, not a new primitive — the linkage already lives in the existing receipt envelopes (`delegation_chain_root`, `policy_ref`, `action_ref`, `evidence_id`, `bound_to`); the graph view is just how those edges compose.
+APS receipts are graph-composable. Each claim links to the authority, policy, action, observation, or evidence it depends on, so a verifier can walk from any receipt back to its supporting facts and stop at the boundary it cares about. This is documentation of existing structure, not a new primitive. The linkage already lives in the existing receipt envelopes (`delegation_chain_root`, `policy_ref`, `action_ref`, `evidence_id`, `bound_to`); the graph view is just how those edges compose.
+
+## Receipt semantics: what each receipt proves
+
+Every APS receipt is a signed declaration about what the system observed. It is not a causal proof of agent cognition, and it is not a proof that an off-protocol side effect actually happened. Each receipt type carries an explicit `scope_of_claim` with `asserts` and `does_not_assert` fields, so the boundary travels with the receipt. The boxes below state that boundary in one place. The same shape is enforced in code by the `ScopeOfClaim` type (`src/v2/accountability/types/base.ts`), re-exported from the package root.
+
+**ActionReceipt** (`aps:action:v1`)
+- Proves: the gateway observed the agent issue this action under the cited delegation chain, and the signed body has not changed since signing.
+- Does not prove: that the side effect completed, that the agent understood the consequences, or that the business outcome was correct.
+
+**AuthorityBoundaryReceipt** (`aps:authority_boundary:v1`)
+- Proves: an authority check ran and returned this verdict against this scope at this time.
+- Does not prove: that the scope itself was correctly configured, or that no other path around the boundary exists.
+
+**CustodyReceipt** (`aps:custody:v1`)
+- Proves: custody of the named artifact passed from one holder to another, signed by the releasing party.
+- Does not prove: that the artifact contents are correct, or that the receiving party will handle it well.
+
+**ContestabilityReceipt** (`aps:contestability:v1`)
+- Proves: a contest was opened or resolved against a prior receipt, with the cited grounds.
+- Does not prove: that the contest is meritorious, only that it was raised and recorded.
+
+**APSBundle** (`aps:bundle:v1`)
+- Proves: the bundled receipts were collected together and each member verifies on its own.
+- Does not prove: anything the member receipts do not already prove. A bundle is an envelope, not a new claim.
+
+**PaymentReceipt** (`aps:payment_receipt:v1`)
+- Proves: a payment instruction was authorized on the named rail for this amount, currency, and recipient, under the cited delegation.
+- Does not prove: that the goods or services were delivered, or that the recipient address was the intended one beyond what the matched intent declared.
+
+Across all of them: a `self_attested` receipt (where the agent signed without independent attestation) carries lower evidentiary weight than a `gateway_observed` or `runtime_attested` one. A verifier should treat the `capture_mode` and `self_attested` fields as part of the claim, not metadata.
+
+## Receipt misuse: what a verifier must reject
+
+A valid signature is not a valid claim. The cases below are receipts that are cryptographically sound yet must still be refused, because they are being used outside the envelope they were issued for. The conformance package under [`tests/conformance/`](tests/conformance/README.md) ships a golden fixture for each one, and a test asserts the rejection reason.
+
+- **Valid receipt, wrong claim.** A sound `aps:action:v1` receipt presented as proof of payment. The signature checks out; the receipt simply does not make that claim. Reject (`WRONG_CLAIM`).
+- **Expired delegation.** A receipt issued after its delegation chain expired. The body verifies; the authority behind it had already lapsed. Reject (`DELEGATION_EXPIRED`).
+- **Stale revocation.** A receipt whose delegation root was revoked. A verifier that does not consult current revocation state would wrongly accept it. Reject (`DELEGATION_REVOKED`).
+- **Unverified external evidence.** A self-attested oracle read presented as gateway-observed evidence. `self_attested` evidence must not be promoted to observed evidence. Reject (`WRONG_CLAIM`).
+- **Replayed receipt.** A previously accepted receipt re-submitted. The verifier must reject a `receipt_id` it has already honored in the window. Reject (`REPLAYED`).
+- **Policy evaluated but execution never happened.** A policy decision exists with no execution attestation. A permit is not a proof that the action ran. Reject (`POLICY_NOT_EXECUTED`).
+
+A conformant verifier runs the crypto layer first (claim type, `receipt_id` match, signature) and then the context layer (delegation state, budget, principal, policy version, replay window). A receipt that fails either layer is not authoritative.
+
+> **Proof box.** These docs and fixtures specify what each receipt proves and the negatives a conformant verifier must reject. They do not change protocol behavior. No signing path, canonical preimage, or `action_ref` computation is altered by anything in this section.
 
 ## Wallet Binding
 
+*Status: Production-Extension.* Optional and additive: passports without `bound_wallets` canonicalize unchanged, and actions without a `walletRef` skip the gate.
+
 Two layers, designed to compose.
 
 **Structural (agent-attested).** The agent's own passport private key signs `{ passport_id, chain, address, bound_at }` and appends the result to the passport's `bound_wallets` field. Verifiable offline with just the passport public key. Chain-agnostic: Nano is the native APS wallet, but the primitive accepts any chain identifier with an address.
@@ -68,16 +125,18 @@ const bound = bindWallet({
 verifyBoundWallet(bound, 'nano', 'nano_3jb1...') // true
 ```
 
-**Behavioral (issuer-attested).** Independent issuers (the [insumer-examples](https://github.com/douglasborthwick-crypto/insumer-examples) ecosystem and friends — skyemeta/skyeprofile and 8 others) sign attestations about wallet behavior, sybil signals, and on-chain history. Their signatures stand alone.
+**Behavioral (issuer-attested).** Independent issuers (the [insumer-examples](https://github.com/douglasborthwick-crypto/insumer-examples) ecosystem and friends, skyemeta/skyeprofile and 8 others) sign attestations about wallet behavior, sybil signals, and on-chain history. Their signatures stand alone.
 
 The two layers compose: a verifier accepting both gets cryptographic proof that **this passport holder controls this address** (structural) **and** that **this address has these behavioral properties** (behavioral). Neither layer claims what the other proves. Multi-attestation envelopes carry both.
 
-`commercePreflight()` enforces the structural layer at gate 5: when the action references a `walletRef`, the gate denies with `WALLET_NOT_BOUND` unless the wallet is currently bound to the acting passport. The check is opt-in — actions without a `walletRef` skip it, so existing 5-gate flows are unaffected.
+`commercePreflight()` enforces the structural layer at gate 5: when the action references a `walletRef`, the gate denies with `WALLET_NOT_BOUND` unless the wallet is currently bound to the acting passport. The check is opt-in. Actions without a `walletRef` skip it, so existing 5-gate flows are unaffected.
 
 `unbindWallet()` produces a separately signed unbind event so the bind/unbind history can be reconstructed independent of the passport's current `bound_wallets` snapshot.
 
 ## Credential Check Policy
 
+*Status: Production-Extension.* Delegations without an explicit `credentialCheckPolicy` keep the existing recheck-on-execute behavior unchanged.
+
 A credential needs to declare WHEN it should be re-verified. Different credential types have different trust decay profiles. APS lets the issuer set this on the delegation itself via `credentialCheckPolicy`.
 
 ```typescript
@@ -111,12 +170,16 @@ Proposed by [@piiiico](https://github.com/piiiico) on the a2aproject/A2A governa
 
 ## Extended Modules
 
+*Status: Production-Extension.*
+
 Pick what you need. `import from 'agent-passport-system'` for the full API.
 
 Coordination (task lifecycle with 9-state machine), EU AI Act compliance (signed evidence packets), framework adapters (CrewAI, LangChain, Google ADK, A2A, MCP), bilateral receipts, execution attestation, DID resolution, data lifecycle (access receipts, derivation tracking, consent revocation).
 
 ## Research Primitives
 
+*Status: Experimental*, except where noted. The Wave 1 accountability primitives below are **Canonical**: their signed bytes are frozen and pinned by the conformance fixtures.
+
 Forward-looking governance. Published, tested, available.
 
 26 v2 constitutional modules: approval fatigue detection, epistemic isolation, blind evaluation, separation of powers, affected-party standing, circuit breakers, constitutional amendment, authority laundering audit, emergence detection.
@@ -143,7 +206,9 @@ The composition contract specifies how a verifier MUST cross-check per-request s
 
 ## Numbers
 
-3,079 tests. 8 protocol layers. Framework adapters for CrewAI, LangChain, ADK, A2A, MCP, OpenShell, IBAC, Gonka. Gateway evaluation under 2ms. Zero heavy dependencies. Apache-2.0.
+3,113 tests. 8 protocol layers. Framework adapters for CrewAI, LangChain, ADK, A2A, MCP, OpenShell, IBAC, Gonka. Gateway evaluation under 2ms. Zero heavy dependencies. Apache-2.0.
+
+The test count is one number derived from the suite, not three guesses. The badge above, this section, and the `package.json` description all carry the same `3,113`, which is the `tests` total reported by `npm test`. When the suite grows, re-run `npm test`, read the `tests` line, and update all three to match.
 
 ## Papers
 
@@ -157,6 +222,12 @@ The composition contract specifies how a verifier MUST cross-check per-request s
 - [The Evidence-Safety Gap](https://doi.org/10.5281/zenodo.19914628)
 - IETF Internet-Draft: `draft-pidlisnyi-aps-01`
 
+## Security and conformance
+
+- [Threat model](/THREAT_MODEL.md) -- actors, assets, trust boundaries, what APS prevents and what it does not, verifier responsibilities.
+- [Conformance fixtures](tests/conformance/README.md) -- golden valid and negative receipt fixtures every verifier must agree on.
+- [Payment Safety Profile](docs/PAYMENT-SAFETY-PROFILE.md) -- the mandatory profile for agent-initiated payments.
+
 ## Contributing
 
 - [Contribution path](/CONTRIBUTION_PATH.md)

package/dist/src/adapters/oauth-rfc8693/index.d.ts

@@ -0,0 +1,144 @@
+import type { ScopeOfClaim } from '../../v2/accountability/types/base.js';
+import type { MayActClaim, TokenExchangeClaims, DelegationChainView, RecoveredChain, JwtSvidView, SpiffeIdentityInput } from './types.js';
+export * from './types.js';
+/**
+ * The scope-of-claim this bridge attaches to any receipt that records a mapping.
+ * Mirrors the proof box. Callers that mint a receipt around a bridge operation
+ * SHOULD use this so the receipt does not over-claim.
+ */
+export declare function bridgeScopeOfClaim(): ScopeOfClaim;
+/**
+ * Returns true if `child` authority is no broader than `parent` (subset).
+ * A wildcard '*' in the parent matches any child scope. This is the monotonic
+ * narrowing invariant: authority may only decrease across a transfer point.
+ */
+export declare function isNarrowing(parent: string[], child: string[]): boolean;
+/**
+ * Validate that a chain narrows monotonically from root grant to current actor.
+ * Each hop's scope must be a subset of the previous hop's scope. Throws on the
+ * first hop that widens authority.
+ */
+export declare function assertChainNarrows(chain: DelegationChainView): void;
+/**
+ * Effective authority of a chain: the intersection of every hop's scope. This is
+ * the narrowest set that survives all transfer points, i.e. what the current
+ * actor may actually do. RFC 8693 transports this as the token `scope` member.
+ */
+export declare function effectiveScope(chain: DelegationChainView): string[];
+/**
+ * Express an APS delegation chain as RFC 8693 token-exchange claims.
+ *
+ * - top-level `sub` = the principal (party being acted upon).
+ * - `act` = nested actor chain (current actor outermost, prior actors nested).
+ * - `may_act` = the party permitted to become the NEXT actor, when supplied. This
+ *   is a forward authorization, distinct from `act` which records who IS acting.
+ * - `scope` = the chain's effective (narrowed) authority, space-delimited.
+ *
+ * This emits a delegation token (it carries `act`), never an impersonation token.
+ * Authority is bounded by the narrowed effective scope. The chain MUST narrow
+ * monotonically; this is asserted before mapping.
+ */
+export declare function chainToTokenExchangeClaims(chain: DelegationChainView, options?: {
+    /** Party permitted to become the next actor → emitted as `may_act`. */
+    mayActBecome?: {
+        sub: string;
+        iss?: string;
+    };
+    /** Logical target audience. */
+    audience?: string | string[];
+    /** Absolute resource URI (no fragment). */
+    resource?: string;
+    /** Issuer of the exchanged token. */
+    iss?: string;
+    /** exp (NumericDate). */
+    exp?: number;
+    /** nbf (NumericDate). */
+    nbf?: number;
+}): TokenExchangeClaims;
+/**
+ * Recover an APS delegation chain from RFC 8693 token-exchange claims.
+ *
+ * The principal is the top-level `sub`. Actors are read from the nested `act`
+ * chain, reversed to root-first order. Each recovered hop is delegated FROM the
+ * prior actor (or the principal, for the first actor) TO the actor. The token
+ * `scope` member is recovered as the chain's effective scope, and each hop is
+ * assigned that effective scope as a ceiling, so the recovered chain is provably
+ * no broader than the original effective authority.
+ *
+ * Per RFC 8693 security rules, authorization MUST derive only from the top-level
+ * claims plus the OUTERMOST actor. Nested (prior) actors and `may_act` are
+ * informational here; the recovered chain carries them for audit but the
+ * effective scope is the authorization ceiling.
+ */
+export declare function tokenExchangeClaimsToChain(claims: TokenExchangeClaims): RecoveredChain;
+/** Parse a space-delimited, case-sensitive scope string into a set list. */
+export declare function parseScope(scope?: string): string[];
+/**
+ * Validate that mapping an APS chain to RFC 8693 claims and back does not widen
+ * authority. Compares the original chain's effective scope against the recovered
+ * chain's effective scope and asserts the recovered set is a subset (no broader).
+ * Returns the recovered chain on success; throws if the round-trip widened.
+ */
+export declare function assertRoundTripNarrows(original: DelegationChainView, recovered: RecoveredChain): void;
+/**
+ * RFC 8693 Section 4.4: before minting a delegated token, the authorization
+ * server SHOULD verify that the presented actor satisfies the subject token's
+ * `may_act` constraint. This checks that `actor` matches `may_act`.
+ *
+ * `may_act` is permission, not proof: a positive result here only means the
+ * actor is PERMITTED to act, never that the actor's token was itself valid.
+ */
+export declare function actorSatisfiesMayAct(mayAct: MayActClaim | undefined, actor: {
+    sub: string;
+    iss?: string;
+}): boolean;
+/**
+ * Read the current (authorizing) actor from a token's claims. Per RFC 8693, only
+ * the OUTERMOST `act` is the current actor and the sole actor that authorization
+ * may consider. Returns undefined for an impersonation-shaped token (no `act`).
+ */
+export declare function currentActor(claims: TokenExchangeClaims): {
+    sub: string;
+    iss?: string;
+} | undefined;
+/**
+ * Validate a SPIFFE ID against the structural rules of the SPIFFE-ID spec and
+ * split it into DID-mappable parts. Reuses parseSPIFFEID for the scheme/authority
+ * split, then enforces charset, segment, length, and forbidden-component rules.
+ *
+ * Rejects: query, fragment, userinfo, port, percent-encoding, empty / '.' / '..'
+ * segments, trailing slash, oversized identifiers, and out-of-charset characters.
+ */
+export declare function validateSpiffeId(spiffeId: string): {
+    trustDomain: string;
+    pathSegments: string[];
+};
+/**
+ * Resolve a SPIFFE ID string to a DID-method identity input. The only transform
+ * is `spiffe://` → `did:<method>:` plus segment delimiting (default ':'). Because
+ * SPIFFE forbids userinfo, port, query, and fragment and constrains the charset
+ * to a DID-safe subset, the mapping is lossless and needs no escaping.
+ *
+ * Optionally enforces a trust-domain match against an expected root of trust;
+ * a mismatch is rejected before any DID is produced.
+ */
+export declare function spiffeIdToDidInput(spiffeId: string, options?: {
+    method?: string;
+    expectedTrustDomain?: string;
+    delimiter?: string;
+}): SpiffeIdentityInput;
+/**
+ * Validate a JWT-SVID's header and claims per the SPIFFE JWT-SVID spec, then map
+ * its `sub` (which MUST equal the workload SPIFFE ID) to a DID-method input.
+ *
+ * Rejects (MUST per spec): missing `exp`; missing `aud`; the validator's own ID
+ * absent from `aud` when an audience to match is supplied; `alg` outside the
+ * approved asymmetric set (no symmetric, no `alg:none`); a `typ` header that is
+ * present but not `JWT`/`JOSE`; a `sub` that is not a valid SPIFFE ID.
+ */
+export declare function jwtSvidToDidInput(svid: JwtSvidView, options?: {
+    method?: string;
+    expectedAudience?: string;
+    expectedTrustDomain?: string;
+}): SpiffeIdentityInput;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/adapters/oauth-rfc8693/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/oauth-rfc8693/index.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AACzE,OAAO,KAAK,EAEV,WAAW,EACX,mBAAmB,EAEnB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,mBAAmB,EACpB,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAI1B;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAcjD;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAItE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAcnE;AAUD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAMnE;AA6BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,CAAC,EAAE;IACR,uEAAuE;IACvE,YAAY,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GACA,mBAAmB,CAwBrB;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,mBAAmB,GAC1B,cAAc,CA2ChB;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAGnD;AAID;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,cAAc,GACxB,IAAI,CA6BN;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,mBAAmB,GAC1B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK3C;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB,CAyDA;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9E,mBAAmB,CAkBrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACrF,mBAAmB,CA0CrB"}