@agenticprimitives/delegation 1.0.0-alpha.42 → 1.0.0-alpha.44

package/README.md

@@ -61,3 +61,58 @@ The closest neighbors are MetaMask's Delegation Toolkit and the session-key feat
 ## Status
 
 **Alpha track — testnet-only.** Spec + API stable; do not deploy to production until the gates listed in the root [`README.md` Status section](../../README.md#status) are cleared — including third-party contract audit and governance key rotation. Track every security finding live in [`docs/audits/findings.yaml`](../../docs/audits/findings.yaml).
+
+## Delegated presentation
+
+A person's credential is presented by her agent, never held by it. She signs one standing `credential.present` wire
+(`PRESENTATION_CAPABILITY`) naming the audiences, predicate programs and issuer facets it covers;
+`createPresentationRelease` derives the child mandate for one statement and judges it inside the device key's signing
+callback — a statement for another venue signs nothing. `createEs256EvidenceMinter` and `boundEvidenceFrom` turn that
+judgement into the bound evidence the key service requires before a P-256 device key signs: the judge attests what it
+judged. The same minter serves an issuing runtime, whose issuance evidence names the digest, the facet and the type.
+
+## Reference
+
+**Exports.** Caveats: `ROOT_AUTHORITY`, `buildCaveat`, `buildMcpToolScopeCaveat`, `buildDataScopeCaveat`,
+`buildVaultKeyUseCaveat` + `decodeVaultKeyUseTerms` + `VAULT_KEY_USE_ENFORCER` (spec 278), `buildVaultRecordScopeCaveat` +
+`vaultRecordScopeAllows` + `decodeVaultRecordScopeTerms` + `VAULT_RECORD_SCOPE_ENFORCER` (spec 317, the one canonical
+record/op matcher), `buildDelegateBindingCaveat`, `buildQuorumCaveat`, `encodeTimestampTerms`, `encodeValueTerms`,
+`encodeAllowedTargetsTerms`, `encodeAllowedMethodsTerms`, `encodeCallDataHashTerms`. Hashing: `hashDelegation`,
+`hashCaveats`, `evaluateCaveats`. Browser: `DelegationClient`. Sessions: `SessionManager`, `SessionStore`. Token:
+`mintDelegationToken`, `verifyDelegationToken` (with `requireQuorumForTier`). On chain: `isRevoked`, `revokeDelegation`.
+Method authorization: `authorizeMethodDelegation`, `methodSelector`. Mandates: `intentDigest`, `deriveMandate`,
+`readMandate`, `verifyMandateForStep`, `registerSubsetHandler`, `registerDefaultSubsetHandlers`,
+`buildDigestBindingCaveat`, `readDigestBindings`. Presentation: `PRESENTATION_RAR_TYPE`, `presentationHandler`,
+`buildStandingWire`, `deriveFromStanding`, `presentationIntent`, `createPresentationRelease`,
+`parseAudienceBoundChallenge`, `createEs256EvidenceMinter`, `boundEvidenceFrom`. Types: `Delegation`, `Caveat`,
+`DataScopeGrant`, `VaultRecordScopeGrant`, `DelegationTokenClaims`, `EnforcerAddressMap`, `JtiStore`, `CaveatContext`,
+`VerifyOpts`, `VerifyError`, `SessionRow`, `SessionPackage`, `SessionMeta`.
+
+**Mandates (spec 350 §2, spec 336 E4).** A mandate is a delegation with a reason: a `DigestBindingEnforcer` caveat binding it
+to an intent digest (JCS, then keccak). `MandateRequirementV1` is RAR-shaped; subset handlers are registered per `type`
+(RFC 9396 defines no universal "narrower than"); `deriveMandate` makes a chain (the child's `authority` is the parent's
+hash); `verifyMandateForStep` is the per-step check, never once at admission. `src/mandate-handlers.ts` ships the
+capability and payment handlers.
+
+**Delegated presentation (spec 305 W2, zkID Z2).** `credential.present` bounds which verifiers, which predicate programs (by
+digest) and which issuer facets a delegate key may cause the person's P-256 device key to sign a `Show` challenge for, through
+the `PRESENTATION_SCOPE_ENFORCER` sentinel judged off chain. `deriveFromStanding` gives the child for one statement;
+`createPresentationRelease` is the only road to the device signature: it runs `verifyMandateForStep` per signature, requires
+the challenge (`<scheme>:<audience>:<nonce>`) to be bound to the audience the mandate covers, and with an `evidence` port
+attests what it judged (digest · venue · predicate program · actor) as the key's sign context. Issuance evidence (spec 444)
+is minted by the issuing runtime's own key with the same minter. The port of smart-agent's `SessionGrantV1` +
+`WalletAction` + `evaluateProofPolicy`, with the delegate moved to a custodied key.
+
+**Method authorization.** `authorizeMethodDelegation` + `methodSelector` answer "may this delegate perform METHOD for
+TARGET?" without an A2A message (publishing for another agent, issuing discovery grants). `a2a`'s `skillSelector` is
+`methodSelector` plus the any-skill sentinel.
+
+**Common tasks.** A new caveat type: builder and encoder in `src/caveats.ts`, dispatch in `src/evaluator.ts`, export in
+`src/index.ts`, a golden test. A token envelope change: `src/token.ts`, coordinated with `mcp-runtime`. A session lifecycle
+method: `src/sessions.ts` with an integration test.
+
+**Cross-cutting.** Audit events: `delegation.mint`, `delegation.verify.accept`, `delegation.verify.reject` (spec 206). DTK
+interop: the off-chain `Caveat` + `EnforcerAddressMap` mirror the on-chain registry; the signed caveat hash matches
+`DelegationManager` CAVEAT_TYPEHASH (enforcer + terms, no args) — [spec 208](../../specs/208-argument-level-caveats.md).
+Relying sites (spec 229, [ADR-0019](../../docs/architecture/decisions/0019-relying-site-authority-is-a-scoped-delegation.md),
+`docs/relying-site-delegation.md`): a relying site is a scoped delegate of the person, never a custodian.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/delegation",
-  "version": "1.0.0-alpha.42",
+  "version": "1.0.0-alpha.44",
   "description": "EIP-712 smart-account delegations with caveats; web→agent→MCP token flow; session lifecycle.",
   "homepage": "https://agenticprimitives.dev",
   "bugs": {
@@ -40,11 +40,11 @@
   },
   "peerDependencies": {
     "viem": "^2.52.2",
-    "@agenticprimitives/agent-account": "^1.0.0-alpha.42",
-    "@agenticprimitives/audit": "^1.0.0-alpha.42",
-    "@agenticprimitives/connect-auth": "^1.0.0-alpha.42",
-    "@agenticprimitives/key-custody": "^1.0.0-alpha.42",
-    "@agenticprimitives/types": "^1.0.0-alpha.42"
+    "@agenticprimitives/agent-account": "^1.0.0-alpha.44",
+    "@agenticprimitives/audit": "^1.0.0-alpha.44",
+    "@agenticprimitives/connect-auth": "^1.0.0-alpha.44",
+    "@agenticprimitives/key-custody": "^1.0.0-alpha.44",
+    "@agenticprimitives/types": "^1.0.0-alpha.44"
   },
   "devDependencies": {
     "vitest": "^4.1.11"