@agenticprimitives/delegation 0.1.0-alpha.2

package/dist/hash.js

@@ -0,0 +1,80 @@
+// EIP-712 hashing for Delegation + Caveat[].
+//
+// Domain MUST match what AgentDelegationManager computes on-chain:
+//   EIP712Domain(string name, string version, uint256 chainId, address verifyingContract)
+//   name = "AgentDelegationManager"
+//   version = "1"
+import { hashTypedData, keccak256, encodeAbiParameters } from 'viem';
+const DOMAIN_NAME = 'AgentDelegationManager';
+const DOMAIN_VERSION = '1';
+export const DELEGATION_EIP712_TYPES = {
+    Delegation: [
+        { name: 'delegator', type: 'address' },
+        { name: 'delegate', type: 'address' },
+        { name: 'authority', type: 'bytes32' },
+        { name: 'caveats', type: 'Caveat[]' },
+        { name: 'salt', type: 'uint256' },
+    ],
+    // `args` (redeemer-supplied runtime data) is DELIBERATELY excluded from
+    // the signed hash — it must match AgentDelegationManager's
+    // CAVEAT_TYPEHASH = keccak256("Caveat(address enforcer,bytes terms)")
+    // (DelegationManager.sol:55). Including args here made every delegation
+    // carrying a caveat fail on-chain ERC-1271 redeem AND let a redeemer's
+    // chosen args ride inside the delegator's signature. (audit F-1)
+    Caveat: [
+        { name: 'enforcer', type: 'address' },
+        { name: 'terms', type: 'bytes' },
+    ],
+};
+export function delegationDomain(chainId, delegationManager) {
+    return {
+        name: DOMAIN_NAME,
+        version: DOMAIN_VERSION,
+        chainId,
+        verifyingContract: delegationManager,
+    };
+}
+function caveatMessage(c) {
+    // Only the signed fields (enforcer, terms). `args` is runtime-only and
+    // never part of the delegation hash — see DELEGATION_EIP712_TYPES.Caveat.
+    return {
+        enforcer: c.enforcer,
+        terms: c.terms,
+    };
+}
+/**
+ * EIP-712 hash of a Delegation. This is the value the smart-account owner
+ * signs (via signTypedData / personal_sign of the digest) and the value
+ * AgentDelegationManager validates via ERC-1271.
+ */
+export function hashDelegation(d, chainId, delegationManager) {
+    return hashTypedData({
+        domain: delegationDomain(chainId, delegationManager),
+        types: DELEGATION_EIP712_TYPES,
+        primaryType: 'Delegation',
+        message: {
+            delegator: d.delegator,
+            delegate: d.delegate,
+            authority: d.authority,
+            caveats: d.caveats.map(caveatMessage),
+            salt: d.salt,
+        },
+    });
+}
+/**
+ * keccak256 of the ABI-encoded caveat array. Mirrors what
+ * AgentDelegationManager computes for caveat enforcement bookkeeping.
+ */
+export function hashCaveats(caveats) {
+    const encoded = encodeAbiParameters([
+        {
+            type: 'tuple[]',
+            components: [
+                { name: 'enforcer', type: 'address' },
+                { name: 'terms', type: 'bytes' },
+            ],
+        },
+    ], [caveats.map(caveatMessage)]);
+    return keccak256(encoded);
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,mEAAmE;AACnE,0FAA0F;AAC1F,oCAAoC;AACpC,kBAAkB;AAElB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,mBAAmB,EAA0B,MAAM,MAAM,CAAC;AAG7F,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAC7C,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;QACtC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACrC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;QACtC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE;QACrC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;KAClC;IACD,wEAAwE;IACxE,2DAA2D;IAC3D,sEAAsE;IACtE,wEAAwE;IACxE,uEAAuE;IACvE,iEAAiE;IACjE,MAAM,EAAE;QACN,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACrC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE;KACjC;CACO,CAAC;AAEX,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,iBAA0B;IAC1E,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;QACvB,OAAO;QACP,iBAAiB,EAAE,iBAAiB;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,CAAS;IAC9B,uEAAuE;IACvE,0EAA0E;IAC1E,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,CAAa,EAAE,OAAe,EAAE,iBAA0B;IACvF,OAAO,aAAa,CAAC;QACnB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC;QACpD,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,YAAY;QACzB,OAAO,EAAE;YACP,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;YACrC,IAAI,EAAE,CAAC,CAAC,IAAI;SACb;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAiB;IAC3C,MAAM,OAAO,GAAG,mBAAmB,CACjC;QACE;YACE,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACV,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;gBACrC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE;aACjC;SACF;KACF,EACD,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAC7B,CAAC;IACF,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { ROOT_AUTHORITY } from './types';
+export { buildCaveat, buildMcpToolScopeCaveat, buildDataScopeCaveat, buildDelegateBindingCaveat, buildQuorumCaveat, encodeTimestampTerms, encodeValueTerms, encodeAllowedTargetsTerms, encodeAllowedMethodsTerms, MCP_TOOL_SCOPE_ENFORCER, DATA_SCOPE_ENFORCER, DELEGATE_BINDING_ENFORCER, } from './caveats';
+export type { QuorumCaveatOpts } from './caveats';
+export { hashDelegation, hashCaveats, DELEGATION_EIP712_TYPES, delegationDomain } from './hash';
+export { evaluateCaveats } from './evaluator';
+export { DelegationClient } from './client';
+export { SessionManager, createMemorySessionStore } from './session-manager';
+export { mintDelegationToken, verifyDelegationToken } from './token';
+export { isRevoked, revokeDelegation } from './onchain';
+export type { Address, Hex, Caveat, CaveatContext, CaveatVerdict, Delegation, DataScopeGrant, DelegationClientOpts, DelegationTokenClaims, EnforcerAddressMap, EvaluateOpts, JtiStore, SessionMeta, SessionPackage, SessionRow, SessionStore, TxContext, VerifyError, VerifyOpts, } from './types';
+export type { VerifyOptsExt } from './token';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7E,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAExD,YAAY,EACV,OAAO,EACP,GAAG,EACH,MAAM,EACN,aAAa,EACb,aAAa,EACb,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,YAAY,EACZ,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AAKjB,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// @agenticprimitives/delegation — public API
+//
+// See ../../specs/202-delegation.md for the full contract.
+export { ROOT_AUTHORITY } from './types';
+export { buildCaveat, buildMcpToolScopeCaveat, buildDataScopeCaveat, buildDelegateBindingCaveat, buildQuorumCaveat, encodeTimestampTerms, encodeValueTerms, encodeAllowedTargetsTerms, encodeAllowedMethodsTerms, MCP_TOOL_SCOPE_ENFORCER, DATA_SCOPE_ENFORCER, DELEGATE_BINDING_ENFORCER, } from './caveats';
+export { hashDelegation, hashCaveats, DELEGATION_EIP712_TYPES, delegationDomain } from './hash';
+export { evaluateCaveats } from './evaluator';
+export { DelegationClient } from './client';
+export { SessionManager, createMemorySessionStore } from './session-manager';
+// H7-B.8: `verifyCrossDelegation` removed from the public surface (XPKG-002 /
+// EXT-024 closure). The stub unconditionally returned a "not implemented"
+// error string — a public symbol that lies about runtime capability. When the
+// work resumes it lands behind `./experimental` per spec 100 §6.
+export { mintDelegationToken, verifyDelegationToken } from './token';
+export { isRevoked, revokeDelegation } from './onchain';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,2DAA2D;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,iEAAiE;AACjE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/onchain.d.ts

@@ -0,0 +1,8 @@
+import type { Hex, Address } from '@agenticprimitives/types';
+import type { TxContext } from './types';
+export declare function isRevoked(_hash: Hex, _opts: {
+    delegationManager: Address;
+    rpcUrl: string;
+}): Promise<boolean>;
+export declare function revokeDelegation(_hash: Hex, _ctx: TxContext): Promise<Hex>;
+//# sourceMappingURL=onchain.d.ts.map

package/dist/onchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onchain.d.ts","sourceRoot":"","sources":["../src/onchain.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,wBAAsB,SAAS,CAC7B,KAAK,EAAE,GAAG,EACV,KAAK,EAAE;IAAE,iBAAiB,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAIhF"}

package/dist/onchain.js

@@ -0,0 +1,9 @@
+// On-chain revocation helpers. v0 demo doesn't exercise revocation (step 2
+// just packages a session). Stubs preserve the public-export surface.
+export async function isRevoked(_hash, _opts) {
+    throw new Error('isRevoked: not implemented in v0 demo step 2 (lands with demo step 3 / mcp-runtime commit).');
+}
+export async function revokeDelegation(_hash, _ctx) {
+    throw new Error('revokeDelegation: not implemented in v0 demo step 2 (lands with on-chain redeem path).');
+}
+//# sourceMappingURL=onchain.js.map

package/dist/onchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onchain.js","sourceRoot":"","sources":["../src/onchain.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,sEAAsE;AAKtE,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAAU,EACV,KAAqD;IAErD,MAAM,IAAI,KAAK,CACb,6FAA6F,CAC9F,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAU,EAAE,IAAe;IAChE,MAAM,IAAI,KAAK,CACb,wFAAwF,CACzF,CAAC;AACJ,CAAC"}

package/dist/session-manager.d.ts

@@ -0,0 +1,51 @@
+import { keccak256, type Address, type Hex } from 'viem';
+import type { A2AKeyProvider } from '@agenticprimitives/key-custody';
+import type { Delegation, SessionMeta, SessionStore } from './types';
+export interface SessionResolveResult {
+    meta: SessionMeta;
+    delegation: Delegation | null;
+    signer: {
+        address: Address;
+        privateKey: Hex;
+        signMessage(msg: string | {
+            raw: Hex;
+        }): Promise<Hex>;
+    };
+}
+export declare class SessionManager {
+    private readonly opts;
+    constructor(opts: {
+        keyCustody: A2AKeyProvider;
+        store: SessionStore;
+        ttlSeconds?: number;
+        /** Allow tests/clock injection. Default: Date.now() */
+        now?: () => number;
+    });
+    private nowMs;
+    /**
+     * Generate a fresh session keypair, encrypt {sessionPrivateKey} (no
+     * delegation yet) at rest, persist as pending. Returns the sessionId and
+     * sessionKeyAddress to hand back to the user/web app.
+     */
+    init(accountAddress: Address, chainId: number): Promise<{
+        sessionId: string;
+        sessionKeyAddress: Address;
+    }>;
+    /**
+     * Receive a fully-signed Delegation, unwrap the pending session, re-encrypt
+     * the full {sessionPrivateKey, delegation} package, mark active.
+     */
+    package(sessionId: string, delegation: Delegation): Promise<void>;
+    /**
+     * Decrypt an active session and return the session signer + delegation.
+     * Refuses pending/revoked/expired rows. Signer never holds the private
+     * key longer than this call; callers should mint tokens with it
+     * immediately and drop the reference.
+     */
+    resolve(sessionId: string): Promise<SessionResolveResult>;
+    revoke(sessionId: string): Promise<void>;
+    private requirePending;
+}
+export declare function createMemorySessionStore(): SessionStore;
+export { keccak256 };
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,SAAS,EAET,KAAK,OAAO,EACZ,KAAK,GAAG,EACT,MAAM,MAAM,CAAC;AACd,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EAGX,YAAY,EACb,MAAM,SAAS,CAAC;AA2EjB,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,GAAG,CAAC;QAChB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;YAAE,GAAG,EAAE,GAAG,CAAA;SAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;KACvD,CAAC;CACH;AAED,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE;QACrB,UAAU,EAAE,cAAc,CAAC;QAC3B,KAAK,EAAE,YAAY,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,uDAAuD;QACvD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;KACpB;IAGH,OAAO,CAAC,KAAK;IAIb;;;;OAIG;IACG,IAAI,CACR,cAAc,EAAE,OAAO,EACvB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC;IA4C7D;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCvE;;;;;OAKG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA4DzD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIhC,cAAc;CAQ7B;AAID,wBAAgB,wBAAwB,IAAI,YAAY,CAkBvD;AAeD,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/session-manager.js

@@ -0,0 +1,259 @@
+// SessionManager — owns the session lifecycle per spec 202 §5.
+//
+// Lifecycle: init → package → resolve → revoke / expired.
+//   init     generates a fresh session keypair, persists encrypted-pending
+//            row via the SessionStore (data key generated through the
+//            A2AKeyProvider from @agenticprimitives/key-custody).
+//   package  caller submits a user-signed Delegation; SessionManager
+//            re-encrypts {sessionPrivateKey, delegation} as the full
+//            package, marks the row active.
+//   resolve  decrypts the package, hands back a viem-compatible signer
+//            over the session private key, plus the bound delegation.
+//   revoke   marks the row revoked; callers must mint a new session.
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { bytesToHex, hexToBytes, keccak256, toBytes, } from 'viem';
+import { canonicalContextBytes } from '@agenticprimitives/key-custody';
+function randomBytes(n) {
+    const out = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+}
+function generateSessionId() {
+    const buf = randomBytes(16);
+    let s = 'sa_';
+    for (const b of buf)
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}
+function publicKeyToAddress(pub) {
+    const raw = pub.length === 65 ? pub.slice(1) : pub;
+    const hash = keccak_256(raw);
+    return bytesToHex(hash.slice(12));
+}
+function sessionIdHash(sessionId) {
+    const h = keccak_256(new TextEncoder().encode(sessionId));
+    let s = '';
+    for (const b of h.slice(0, 16))
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}
+function buildAad(meta, keyVersion) {
+    return {
+        session_id_h: sessionIdHash(meta.sessionId),
+        account_address: meta.accountAddress.toLowerCase(),
+        chain_id: String(meta.chainId),
+        expires_at: meta.expiresAt,
+        key_version: keyVersion,
+    };
+}
+// TS strict-mode quirk: Web Crypto types want ArrayBuffer specifically; Uint8Array
+// over a ArrayBufferLike (could be SharedArrayBuffer) doesn't fit. Cast through
+// BufferSource — these are all locally-allocated, never shared.
+function asBufferSource(b) {
+    return b;
+}
+async function aesGcmEncrypt(key, iv, plaintext, aad) {
+    const cryptoKey = await globalThis.crypto.subtle.importKey('raw', asBufferSource(key), 'AES-GCM', false, ['encrypt']);
+    const ct = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: asBufferSource(iv), additionalData: asBufferSource(aad) }, cryptoKey, asBufferSource(plaintext));
+    return new Uint8Array(ct);
+}
+async function aesGcmDecrypt(key, iv, ciphertext, aad) {
+    const cryptoKey = await globalThis.crypto.subtle.importKey('raw', asBufferSource(key), 'AES-GCM', false, ['decrypt']);
+    const pt = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: asBufferSource(iv), additionalData: asBufferSource(aad) }, cryptoKey, asBufferSource(ciphertext));
+    return new Uint8Array(pt);
+}
+export class SessionManager {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    nowMs() {
+        return (this.opts.now ?? Date.now)();
+    }
+    /**
+     * Generate a fresh session keypair, encrypt {sessionPrivateKey} (no
+     * delegation yet) at rest, persist as pending. Returns the sessionId and
+     * sessionKeyAddress to hand back to the user/web app.
+     */
+    async init(accountAddress, chainId) {
+        const sessionId = generateSessionId();
+        const ttl = (this.opts.ttlSeconds ?? 24 * 60 * 60) * 1000;
+        const expiresAt = new Date(this.nowMs() + ttl).toISOString();
+        // Fresh secp256k1 keypair
+        const priv = randomBytes(32);
+        // secp256k1 priv keys MUST be in [1, n-1]. Retry on rare overflow / zero.
+        if (!secp256k1.utils.isValidPrivateKey(priv)) {
+            return this.init(accountAddress, chainId); // recurse — vanishingly rare
+        }
+        const pub = secp256k1.getPublicKey(priv, false);
+        const sessionKeyAddress = publicKeyToAddress(pub);
+        const meta = { sessionId, accountAddress, chainId, expiresAt };
+        // Encrypt the partial package (only sessionPrivateKey for now; delegation
+        // joins at /package).
+        const partialPayload = new TextEncoder().encode(JSON.stringify({ sessionPrivateKey: bytesToHex(priv) }));
+        const aadCtx = buildAad(meta, this.opts.keyCustody.keyVersion);
+        const aadBytes = canonicalContextBytes(aadCtx);
+        const wrap = await this.opts.keyCustody.generateSessionDataKey({ aadContext: aadCtx });
+        const iv = randomBytes(12);
+        const encryptedPackage = await aesGcmEncrypt(wrap.plaintextDataKey, iv, partialPayload, aadBytes);
+        const row = {
+            id: sessionId,
+            accountAddress,
+            chainId,
+            sessionKeyAddress,
+            status: 'pending',
+            encryptedPackage,
+            iv,
+            encryptedDataKey: wrap.encryptedDataKey,
+            keyVersion: wrap.keyVersion,
+            expiresAt,
+            createdAt: new Date(this.nowMs()).toISOString(),
+        };
+        await this.opts.store.save(row);
+        return { sessionId, sessionKeyAddress };
+    }
+    /**
+     * Receive a fully-signed Delegation, unwrap the pending session, re-encrypt
+     * the full {sessionPrivateKey, delegation} package, mark active.
+     */
+    async package(sessionId, delegation) {
+        const row = await this.requirePending(sessionId);
+        const meta = {
+            sessionId,
+            accountAddress: row.accountAddress,
+            chainId: row.chainId,
+            expiresAt: row.expiresAt,
+        };
+        // Decrypt the current partial payload to extract the sessionPrivateKey.
+        const aadCtx = buildAad(meta, row.keyVersion);
+        const aadBytes = canonicalContextBytes(aadCtx);
+        const dk = await this.opts.keyCustody.decryptSessionDataKey({
+            encryptedDataKey: row.encryptedDataKey,
+            aadContext: aadCtx,
+            keyId: 'local-master',
+            keyVersion: row.keyVersion,
+        });
+        const partial = await aesGcmDecrypt(dk, row.iv, row.encryptedPackage, aadBytes);
+        const parsed = JSON.parse(new TextDecoder().decode(partial));
+        // Re-encrypt the full package with a fresh IV (data key stays the same).
+        const fullPayload = new TextEncoder().encode(JSON.stringify({
+            sessionPrivateKey: parsed.sessionPrivateKey,
+            delegation: serializableDelegation(delegation),
+        }));
+        const newIv = randomBytes(12);
+        const encryptedPackage = await aesGcmEncrypt(dk, newIv, fullPayload, aadBytes);
+        const updated = {
+            ...row,
+            status: 'active',
+            encryptedPackage,
+            iv: newIv,
+        };
+        await this.opts.store.save(updated);
+    }
+    /**
+     * Decrypt an active session and return the session signer + delegation.
+     * Refuses pending/revoked/expired rows. Signer never holds the private
+     * key longer than this call; callers should mint tokens with it
+     * immediately and drop the reference.
+     */
+    async resolve(sessionId) {
+        const row = await this.opts.store.get(sessionId);
+        if (!row)
+            throw new Error(`SessionManager.resolve: session "${sessionId}" not found`);
+        if (row.status !== 'active') {
+            throw new Error(`SessionManager.resolve: session is "${row.status}"`);
+        }
+        const now = this.nowMs();
+        if (Date.parse(row.expiresAt) < now) {
+            throw new Error('SessionManager.resolve: session expired');
+        }
+        const meta = {
+            sessionId,
+            accountAddress: row.accountAddress,
+            chainId: row.chainId,
+            expiresAt: row.expiresAt,
+        };
+        const aadCtx = buildAad(meta, row.keyVersion);
+        const aadBytes = canonicalContextBytes(aadCtx);
+        const dk = await this.opts.keyCustody.decryptSessionDataKey({
+            encryptedDataKey: row.encryptedDataKey,
+            aadContext: aadCtx,
+            keyId: 'local-master',
+            keyVersion: row.keyVersion,
+        });
+        const pt = await aesGcmDecrypt(dk, row.iv, row.encryptedPackage, aadBytes);
+        const pkg = JSON.parse(new TextDecoder().decode(pt));
+        const priv = hexToBytes(pkg.sessionPrivateKey);
+        const address = publicKeyToAddress(secp256k1.getPublicKey(priv, false));
+        return {
+            meta,
+            delegation: pkg.delegation ? deserializeDelegation(pkg.delegation) : null,
+            signer: {
+                address,
+                privateKey: pkg.sessionPrivateKey,
+                signMessage: async (msg) => {
+                    let digest;
+                    if (typeof msg === 'string') {
+                        const bytes = new TextEncoder().encode(msg);
+                        const prefix = new TextEncoder().encode(`\x19Ethereum Signed Message:\n${bytes.length}`);
+                        const combined = new Uint8Array(prefix.length + bytes.length);
+                        combined.set(prefix, 0);
+                        combined.set(bytes, prefix.length);
+                        digest = keccak_256(combined);
+                    }
+                    else {
+                        digest = toBytes(msg.raw);
+                    }
+                    const sig = secp256k1.sign(digest, priv);
+                    const r = sig.r.toString(16).padStart(64, '0');
+                    const s = sig.s.toString(16).padStart(64, '0');
+                    const v = (sig.recovery ?? 0) + 27;
+                    return ('0x' + r + s + v.toString(16).padStart(2, '0'));
+                },
+            },
+        };
+    }
+    async revoke(sessionId) {
+        await this.opts.store.revoke(sessionId);
+    }
+    async requirePending(sessionId) {
+        const row = await this.opts.store.get(sessionId);
+        if (!row)
+            throw new Error(`SessionManager: session "${sessionId}" not found`);
+        if (row.status !== 'pending') {
+            throw new Error(`SessionManager.package: session is "${row.status}", expected "pending"`);
+        }
+        return row;
+    }
+}
+// ─── Memory store ─────────────────────────────────────────────────────────
+export function createMemorySessionStore() {
+    const rows = new Map();
+    return {
+        async save(row) {
+            rows.set(row.id, row);
+        },
+        async get(id) {
+            return rows.get(id) ?? null;
+        },
+        async list(accountAddress) {
+            return [...rows.values()].filter((r) => r.accountAddress.toLowerCase() === accountAddress.toLowerCase());
+        },
+        async revoke(id) {
+            const row = rows.get(id);
+            if (!row)
+                return;
+            rows.set(id, { ...row, status: 'revoked', revokedAt: new Date().toISOString() });
+        },
+    };
+}
+function serializableDelegation(d) {
+    return { ...d, salt: d.salt.toString() };
+}
+function deserializeDelegation(d) {
+    return { ...d, salt: BigInt(d.salt) };
+}
+// keccak256 is exported for convenience to keep the contract clean for tests
+export { keccak256 };
+//# sourceMappingURL=session-manager.js.map

package/dist/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}

package/dist/token.d.ts

@@ -0,0 +1,158 @@
+import { type Address, type Hex } from 'viem';
+import type { DelegationTokenClaims, VerifyError, VerifyOpts, DataScopeGrant } from './types';
+import { type AuditSink } from '@agenticprimitives/audit';
+/** Sorted-key JSON; BigInt → numeric string. Both sides must produce the
+ *  exact same bytes for the signature to round-trip.
+ *
+ *  Exported for cross-runtime golden-test fixtures. Stability of this
+ *  function is a SECURITY INVARIANT — any byte-level drift across
+ *  runtimes (Node, Bun, browser, Cloudflare Workers) means the same
+ *  claims hash to different signatures, breaking token verification
+ *  silently. */
+export declare function canonicalJSON(value: unknown): string;
+export declare function mintDelegationToken(claims: Omit<DelegationTokenClaims, 'iat' | 'exp' | 'jti'> & {
+    jti?: string;
+    ttlSeconds?: number;
+}, signMessage: (msg: string) => Promise<Hex>, opts?: {
+    /** Audit sink (C3 pass 3c). Emits `delegation.mint` per call. */
+    auditSink?: AuditSink;
+    correlationId?: string;
+    /**
+     * Production guard — reject mints whose `ttlSeconds` exceeds this.
+     * Defaults to `DEFAULT_MAX_TTL_SECONDS` (1h). Set higher only with
+     * `acceptElevatedRisk: true`.
+     */
+    maxAllowedTtlSeconds?: number;
+    /**
+     * Production guard — reject mints whose `usageLimit` exceeds this.
+     * Defaults to `DEFAULT_MAX_USAGE_LIMIT` (100). Set higher only with
+     * `acceptElevatedRisk: true`.
+     */
+    maxAllowedUsageLimit?: number;
+    /**
+     * Required when caller wants TTL > 1h OR usage > 100. Forces a
+     * deliberate "I know this is a long-lived elevated-blast-radius
+     * token" decision rather than silent permissive defaults.
+     */
+    acceptElevatedRisk?: boolean;
+}): Promise<{
+    token: string;
+    jti: string;
+}>;
+export interface VerifyOptsExt extends VerifyOpts {
+    /** Tool name for mcp-tool-scope caveat evaluation. */
+    toolName?: string;
+    /**
+     * Whether to require the delegator's smart account to be on-chain.
+     * Default: `true` (fail-closed). When the account isn't deployed,
+     * ERC-1271 can't be verified and the security model is broken.
+     *
+     * Demo flows that intentionally use counterfactual addresses without
+     * deploying may pass `false` to tolerate the undeployed state. Production
+     * code MUST keep the default — there's no scenario where an undeployed
+     * delegator should be honored.
+     */
+    requireDeployed?: boolean;
+    /**
+     * Revocation read failure behavior. Audit finding H3.
+     *
+     * - `'closed'` (DEFAULT — H7-B.9 / XPKG-005 closure): if `isRevoked()`
+     *   RPC read throws, the whole verification fails with
+     *   `revocation check unavailable`. Safe under RPC outage: a revoked
+     *   delegation cannot be silently accepted.
+     * - `'open'`: tolerate the RPC failure and continue. Appropriate ONLY
+     *   for explicit demo/dev paths where RPC flakiness is expected. Must
+     *   be set explicitly — the previous NODE_ENV-keyed default could
+     *   silently fall open on Cloudflare Workers / SES runtimes (where
+     *   `process.env.NODE_ENV` is undefined).
+     */
+    revocationFailMode?: 'closed' | 'open';
+    /**
+     * Audit sink (audit C3 pass 3b). When provided, every verify outcome
+     * emits a `delegation.verify.{accept,reject}` event. The principal
+     * goes in `actor`, the delegation hash in `subject`. The token JTI
+     * (claims.jti) is hashed before logging to avoid surfacing the
+     * one-shot identifier in the forensics trail beyond the minimum
+     * needed for correlation.
+     *
+     * Fail-soft: emit failures never break the verify flow.
+     */
+    auditSink?: AuditSink;
+    /** Correlation ID threaded into emitted events. */
+    correlationId?: string;
+    /**
+     * When set, the delegation MUST carry a caveat with an `enforcer`
+     * matching this address. The redeem-time signature check happens
+     * on-chain inside the `QuorumEnforcer.beforeHook` (packages/contracts/
+     * src/enforcers/QuorumEnforcer.sol); this opt's role is to fail
+     * closed at the OFF-CHAIN layer when a delegation was issued
+     * without the required quorum caveat at all. Without this opt set,
+     * delegation does NOT require quorum — backwards-compatible for
+     * T1/T2 tier flows that don't need it.
+     *
+     * Use case (mcp-runtime sets it for T3+ tools):
+     *   evaluateThresholdPolicy(classification).requiresQuorum
+     *     ? { enforcer: deployments.quorumEnforcer }
+     *     : undefined
+     */
+    requireQuorumCaveat?: {
+        enforcer: Address;
+    };
+    /**
+     * Quorum-enforcement proof (audit H3). Required whenever
+     * `requireQuorumCaveat` is set. Picks ONE of two enforcement models:
+     *
+     *   - `{ mode: 'on-chain-redeemed' }` — the caller asserts that the
+     *     authorized call will go through `DelegationManager.redeemDelegation`,
+     *     which invokes `QuorumEnforcer.beforeHook` and verifies the
+     *     packed signatures on chain against the bound execution payload.
+     *     Use this for any flow that actually broadcasts a UserOp /
+     *     transaction that hits the on-chain enforcer.
+     *
+     *   - `{ mode: 'off-chain', payloadHash, packedSignatures }` — for
+     *     MCP-only / data-tool flows that never reach the on-chain
+     *     enforcer. The verifier MUST validate the packed signatures
+     *     off-chain against `payloadHash` (which the caller binds to
+     *     the tool/action context) AND against the signer set encoded
+     *     in the QuorumCaveat terms. This mode currently throws with
+     *     `quorum_off_chain_not_implemented` — wire-format is reserved
+     *     so consumers can plan migration; the verification logic
+     *     ships in a follow-up wave once the bound payload format is
+     *     spec'd in `specs/207-smart-account-threshold-policy.md` §
+     *     "off-chain quorum".
+     *
+     * If `requireQuorumCaveat` is set without a `quorumProof`, the
+     * verifier rejects. This makes the off-chain enforcement gap
+     * structural — a consumer can't silently rely on caveat presence
+     * as a substitute for signature verification.
+     */
+    quorumProof?: {
+        mode: 'on-chain-redeemed';
+    } | {
+        mode: 'off-chain';
+        payloadHash: Hex;
+        packedSignatures: Hex;
+    };
+    /**
+     * When `true`, verify that the delegator's smart account has
+     * pre-blessed this delegation hash on-chain via
+     * `acceptSessionDelegation(hash)`. Spec 207 § 6 high-risk gate —
+     * critical-tier tool calls require an explicit on-chain
+     * authorization so a quorum at issuance isn't sufficient on its
+     * own; the user must additionally commit the specific delegation
+     * hash with a chain-visible transaction.
+     *
+     * Audit emit captures this as `context.acceptedOnChain: true` on
+     * the accept row so forensics can distinguish high-value flows.
+     */
+    requireAcceptedOnChain?: boolean;
+}
+/**
+ * Full verification pipeline. Caller passes `toolName` in opts for tool-scope
+ * caveat evaluation; without it the mcp-tool-scope caveat denies.
+ */
+export declare function verifyDelegationToken(token: string, opts: VerifyOptsExt): Promise<{
+    principal: Address;
+    grants?: DataScopeGrant[];
+} | VerifyError>;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAeA,OAAO,EAA4B,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AACxE,OAAO,KAAK,EAEV,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAwBtE;;;;;;;gBAOgB;AAChB,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsBpD;AAiDD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAClG,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,EAC1C,IAAI,CAAC,EAAE;IACL,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA2EzC;AAuCD,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACvC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IASvB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW,CAAC,EACR;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GAC7B;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,GAAG,CAAC;QAAC,gBAAgB,EAAE,GAAG,CAAA;KAAE,CAAC;IAEnE;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AA+BD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG,WAAW,CAAC,CAgQ1E"}