@contextvm/sdk 0.12.5 → 0.13.1

package/dist/esm/core/constants.d.ts

@@ -99,6 +99,8 @@ export declare const NOSTR_TAGS: {
      * Support CEP-41 open-ended stream transfer via notifications/progress framing.
      */
     readonly SUPPORT_OPEN_STREAM: "support_open_stream";
+    /** CEP-8 payment interaction negotiation tag. */
+    readonly PAYMENT_INTERACTION: "payment_interaction";
 };
 export declare const DEFAULT_LRU_SIZE = 5000;
 /**

package/dist/esm/core/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,wJAO/B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU;;;IAGrB;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEK,CAAC;AAEX,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,mBAKxB,CAAC;AAEX,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,gCAAgC,8BAA8B,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,4BAA4B,+BAA+B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,wJAO/B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU;;;IAGrB;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH,iDAAiD;;CAEzC,CAAC;AAEX,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,mBAKxB,CAAC;AAEX,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,gCAAgC,8BAA8B,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,4BAA4B,+BAA+B,CAAC"}

package/dist/esm/core/constants.js

@@ -105,6 +105,8 @@ export const NOSTR_TAGS = {
      * Support CEP-41 open-ended stream transfer via notifications/progress framing.
      */
     SUPPORT_OPEN_STREAM: 'support_open_stream',
+    /** CEP-8 payment interaction negotiation tag. */
+    PAYMENT_INTERACTION: 'payment_interaction',
 };
 export const DEFAULT_LRU_SIZE = 5000;
 /**

package/dist/esm/core/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,sBAAsB;IACtB,wBAAwB;IACxB,eAAe;IACf,2BAA2B;IAC3B,kBAAkB;IAClB,uBAAuB;CACf,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,GAAG;IACX,KAAK,EAAE,GAAG;IACV;;OAEG;IACH,QAAQ,EAAE,GAAG;IACb;;OAEG;IACH,UAAU,EAAE,KAAK;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM;IACZ;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,KAAK,EAAE,OAAO;IACd;;OAEG;IACH,kBAAkB,EAAE,oBAAoB;IAExC;;OAEG;IACH,4BAA4B,EAAE,8BAA8B;IAE5D;;OAEG;IACH,0BAA0B,EAAE,4BAA4B;IAExD;;OAEG;IACH,mBAAmB,EAAE,qBAAqB;CAClC,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAM,CAAC;AAEzC,MAAM,CAAC,MAAM,mBAAmB,GAAwB;IACtD,KAAK,EAAE,YAAY;IACnB,SAAS,EAAE,gBAAgB;IAC3B,iBAAiB,EAAE,0BAA0B;IAC7C,OAAO,EAAE,cAAc;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,gCAAgC,GAAG,2BAA2B,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,4BAA4B,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,sBAAsB;IACtB,wBAAwB;IACxB,eAAe;IACf,2BAA2B;IAC3B,kBAAkB;IAClB,uBAAuB;CACf,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,GAAG;IACX,KAAK,EAAE,GAAG;IACV;;OAEG;IACH,QAAQ,EAAE,GAAG;IACb;;OAEG;IACH,UAAU,EAAE,KAAK;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM;IACZ;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,KAAK,EAAE,OAAO;IACd;;OAEG;IACH,kBAAkB,EAAE,oBAAoB;IAExC;;OAEG;IACH,4BAA4B,EAAE,8BAA8B;IAE5D;;OAEG;IACH,0BAA0B,EAAE,4BAA4B;IAExD;;OAEG;IACH,mBAAmB,EAAE,qBAAqB;IAE1C,iDAAiD;IACjD,mBAAmB,EAAE,qBAAqB;CAClC,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAM,CAAC;AAEzC,MAAM,CAAC,MAAM,mBAAmB,GAAwB;IACtD,KAAK,EAAE,YAAY;IACnB,SAAS,EAAE,gBAAgB;IAC3B,iBAAiB,EAAE,0BAA0B;IAC7C,OAAO,EAAE,cAAc;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,gCAAgC,GAAG,2BAA2B,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,4BAA4B,CAAC"}

package/dist/esm/payments/authorization-store.d.ts

@@ -0,0 +1,55 @@
+import type { CanonicalInvocationIdentity } from './types.js';
+/**
+ * A bounded, TTL-aware store for explicit gating authorizations.
+ * It manages both the pending state (waiting for payment verification)
+ * and the granted state (paid and ready to consume).
+ *
+ * NOTE: The atomicity provided by `trySetPending` relies on in-memory maps,
+ * meaning it is strictly single-process. For multi-process horizontal scaling,
+ * implementers should use a distributed lock (e.g. Redis Redlock) keyed by
+ * the canonical invocation identity to prevent duplicate payments.
+ */
+export declare class AuthorizationStore {
+    private readonly authorizations;
+    private readonly pending;
+    private readonly logger;
+    constructor(opts?: {
+        maxEntries?: number;
+    });
+    private getKey;
+    /**
+     * Records a paid authorization. Each grant authorizes exactly one future
+     * execution (CEP-8: "each successful payment SHOULD authorize one future
+     * execution unless server policy explicitly grants a different number").
+     */
+    grant(identity: CanonicalInvocationIdentity, ttlMs: number): void;
+    /**
+     * Atomically claims the single execution authorization.
+     * Returns true if claimed, false if none available or expired.
+     */
+    claim(identity: CanonicalInvocationIdentity): boolean;
+    /**
+     * Atomically checks whether a payment is already pending for this identity
+     * and, if not, marks it as pending. Returns `true` if this call transitioned
+     * the identity to pending (caller should emit -32042). Returns `false` if
+     * already pending (caller should emit -32043).
+     *
+     * This atomic check-and-set prevents concurrent requests from both receiving
+     * -32042 and triggering duplicate payment flows.
+     * NOTE: This is single-process only. Distributed setups must use an external lock.
+     */
+    trySetPending(identity: CanonicalInvocationIdentity, ttlMs: number): boolean;
+    /**
+     * Updates the TTL of an already pending authorization. No-op if not pending.
+     *
+     * @param identity The canonical invocation identity.
+     * @param ttlMs The new TTL in milliseconds to apply from now.
+     * @returns void
+     */
+    updatePendingTtl(identity: CanonicalInvocationIdentity, ttlMs: number): void;
+    /** Gets the remaining TTL in milliseconds for a pending authorization, or 0 if not pending. */
+    getPendingRemainingMs(identity: CanonicalInvocationIdentity): number;
+    /** Clears pending state (e.g. on verification failure or expiry). */
+    clearPending(identity: CanonicalInvocationIdentity): void;
+}
+//# sourceMappingURL=authorization-store.d.ts.map

package/dist/esm/payments/authorization-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-store.d.ts","sourceRoot":"","sources":["../../../src/payments/authorization-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAU9D;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAElD,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAM1C,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACI,KAAK,CAAC,QAAQ,EAAE,2BAA2B,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAYxE;;;OAGG;IACI,KAAK,CAAC,QAAQ,EAAE,2BAA2B,GAAG,OAAO;IAmB5D;;;;;;;;;OASG;IACI,aAAa,CAClB,QAAQ,EAAE,2BAA2B,EACrC,KAAK,EAAE,MAAM,GACZ,OAAO;IAoBV;;;;;;OAMG;IACI,gBAAgB,CACrB,QAAQ,EAAE,2BAA2B,EACrC,KAAK,EAAE,MAAM,GACZ,IAAI;IASP,+FAA+F;IACxF,qBAAqB,CAAC,QAAQ,EAAE,2BAA2B,GAAG,MAAM;IAQ3E,qEAAqE;IAC9D,YAAY,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI;CAKjE"}

package/dist/esm/payments/authorization-store.js

@@ -0,0 +1,115 @@
+import { LruCache } from '../core/utils/lru-cache.js';
+import { createLogger } from '../core/utils/logger.js';
+/**
+ * A bounded, TTL-aware store for explicit gating authorizations.
+ * It manages both the pending state (waiting for payment verification)
+ * and the granted state (paid and ready to consume).
+ *
+ * NOTE: The atomicity provided by `trySetPending` relies on in-memory maps,
+ * meaning it is strictly single-process. For multi-process horizontal scaling,
+ * implementers should use a distributed lock (e.g. Redis Redlock) keyed by
+ * the canonical invocation identity to prevent duplicate payments.
+ */
+export class AuthorizationStore {
+    constructor(opts) {
+        var _a;
+        this.logger = createLogger('authorization-store');
+        const maxEntries = (_a = opts === null || opts === void 0 ? void 0 : opts.maxEntries) !== null && _a !== void 0 ? _a : 5000;
+        this.authorizations = new LruCache(maxEntries);
+        this.pending = new LruCache(maxEntries);
+    }
+    getKey(identity) {
+        return `${identity.clientPubkey}:${identity.invocationHash}`;
+    }
+    /**
+     * Records a paid authorization. Each grant authorizes exactly one future
+     * execution (CEP-8: "each successful payment SHOULD authorize one future
+     * execution unless server policy explicitly grants a different number").
+     */
+    grant(identity, ttlMs) {
+        const key = this.getKey(identity);
+        const expiresAtMs = Date.now() + ttlMs;
+        this.authorizations.set(key, { key, expiresAtMs });
+        // Once granted, it's no longer pending
+        this.pending.delete(key);
+        this.logger.debug('authorization granted', { key, ttlMs });
+    }
+    /**
+     * Atomically claims the single execution authorization.
+     * Returns true if claimed, false if none available or expired.
+     */
+    claim(identity) {
+        const key = this.getKey(identity);
+        const auth = this.authorizations.get(key);
+        if (!auth) {
+            return false;
+        }
+        if (Date.now() > auth.expiresAtMs) {
+            this.authorizations.delete(key);
+            return false;
+        }
+        // Single-use: consume the authorization atomically.
+        this.authorizations.delete(key);
+        this.logger.debug('authorization claimed', { key });
+        return true;
+    }
+    /**
+     * Atomically checks whether a payment is already pending for this identity
+     * and, if not, marks it as pending. Returns `true` if this call transitioned
+     * the identity to pending (caller should emit -32042). Returns `false` if
+     * already pending (caller should emit -32043).
+     *
+     * This atomic check-and-set prevents concurrent requests from both receiving
+     * -32042 and triggering duplicate payment flows.
+     * NOTE: This is single-process only. Distributed setups must use an external lock.
+     */
+    trySetPending(identity, ttlMs) {
+        const key = this.getKey(identity);
+        const now = Date.now();
+        const existingExpiry = this.pending.get(key);
+        if (existingExpiry !== undefined) {
+            if (now > existingExpiry) {
+                // Expired pending state, we can overwrite it
+                this.pending.delete(key);
+            }
+            else {
+                // Already pending and active
+                return false;
+            }
+        }
+        this.pending.set(key, now + ttlMs);
+        this.logger.debug('authorization marked pending', { key, ttlMs });
+        return true;
+    }
+    /**
+     * Updates the TTL of an already pending authorization. No-op if not pending.
+     *
+     * @param identity The canonical invocation identity.
+     * @param ttlMs The new TTL in milliseconds to apply from now.
+     * @returns void
+     */
+    updatePendingTtl(identity, ttlMs) {
+        const key = this.getKey(identity);
+        const existingExpiry = this.pending.get(key);
+        if (existingExpiry !== undefined && Date.now() <= existingExpiry) {
+            this.pending.set(key, Date.now() + ttlMs);
+            this.logger.debug('authorization pending TTL updated', { key, ttlMs });
+        }
+    }
+    /** Gets the remaining TTL in milliseconds for a pending authorization, or 0 if not pending. */
+    getPendingRemainingMs(identity) {
+        const key = this.getKey(identity);
+        const expiry = this.pending.get(key);
+        if (expiry === undefined)
+            return 0;
+        const remaining = expiry - Date.now();
+        return remaining > 0 ? remaining : 0;
+    }
+    /** Clears pending state (e.g. on verification failure or expiry). */
+    clearPending(identity) {
+        const key = this.getKey(identity);
+        this.pending.delete(key);
+        this.logger.debug('authorization pending state cleared', { key });
+    }
+}
+//# sourceMappingURL=authorization-store.js.map

package/dist/esm/payments/authorization-store.js.map

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

package/dist/esm/payments/canonical-identity.d.ts

@@ -0,0 +1,20 @@
+import type { CanonicalInvocationIdentity } from './types.js';
+/**
+ * Computes a deterministic SHA-256 hash of an invocation's `method` and
+ * semantic `params` (RFC 8785 JCS, key-order independent). `params._meta`
+ * (MCP's reserved per-request extension namespace: progressToken, stream, ...)
+ * is excluded so retries/re-invocations match a paid authorization regardless
+ * of per-request transport metadata. The full `params` (incl. `_meta`) are
+ * still forwarded to the handler at execution time.
+ */
+export declare function computeCanonicalInvocationHash(method: string, params: unknown): string;
+/**
+ * Computes the canonical invocation identity for explicit-gating authorization matching.
+ *
+ * @param clientPubkey - The client's public key
+ * @param method - The JSON-RPC method
+ * @param params - The JSON-RPC parameters
+ * @returns The computed identity
+ */
+export declare function computeCanonicalInvocationIdentity(clientPubkey: string, method: string, params: unknown): CanonicalInvocationIdentity;
+//# sourceMappingURL=canonical-identity.d.ts.map

package/dist/esm/payments/canonical-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-identity.d.ts","sourceRoot":"","sources":["../../../src/payments/canonical-identity.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GACd,MAAM,CAoCR;AAED;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GACd,2BAA2B,CAK7B"}

package/dist/esm/payments/canonical-identity.js

@@ -0,0 +1,59 @@
+import canonicalizePackage from 'canonicalize';
+const canonicalize = canonicalizePackage;
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+/**
+ * Computes a deterministic SHA-256 hash of an invocation's `method` and
+ * semantic `params` (RFC 8785 JCS, key-order independent). `params._meta`
+ * (MCP's reserved per-request extension namespace: progressToken, stream, ...)
+ * is excluded so retries/re-invocations match a paid authorization regardless
+ * of per-request transport metadata. The full `params` (incl. `_meta`) are
+ * still forwarded to the handler at execution time.
+ */
+export function computeCanonicalInvocationHash(method, params) {
+    // Only object params carry a reserved `_meta`; arrays/primitives pass through.
+    let semanticParams = params;
+    if (params && typeof params === 'object' && !Array.isArray(params)) {
+        const { _meta: _omit, ...rest } = params;
+        semanticParams = rest;
+    }
+    const payload = { method, params: semanticParams };
+    let canonicalString;
+    try {
+        // Pre-validate that all values are strictly JSON-serializable.
+        // canonicalize() might ignore functions/symbols or throw stack overflows,
+        // so we use JSON.stringify as a strict validator first.
+        JSON.stringify(payload, (_key, value) => {
+            if (typeof value === 'function' ||
+                typeof value === 'symbol' ||
+                typeof value === 'bigint') {
+                throw new Error('Invalid type');
+            }
+            return value;
+        });
+        canonicalString = canonicalize(payload);
+    }
+    catch (_a) {
+        canonicalString = undefined;
+    }
+    if (canonicalString === undefined) {
+        throw new Error(`Failed to canonicalize invocation payload for method '${method}'. ` +
+            'Ensure params contain only JSON-serializable values (no circular references, functions, symbols, or BigInt).');
+    }
+    return bytesToHex(sha256(new TextEncoder().encode(canonicalString)));
+}
+/**
+ * Computes the canonical invocation identity for explicit-gating authorization matching.
+ *
+ * @param clientPubkey - The client's public key
+ * @param method - The JSON-RPC method
+ * @param params - The JSON-RPC parameters
+ * @returns The computed identity
+ */
+export function computeCanonicalInvocationIdentity(clientPubkey, method, params) {
+    return {
+        clientPubkey,
+        invocationHash: computeCanonicalInvocationHash(method, params),
+    };
+}
+//# sourceMappingURL=canonical-identity.js.map

package/dist/esm/payments/canonical-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-identity.js","sourceRoot":"","sources":["../../../src/payments/canonical-identity.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAmB,MAAM,cAAc,CAAC;AAE/C,MAAM,YAAY,GAAG,mBAAgD,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAc,EACd,MAAe;IAEf,+EAA+E;IAC/E,IAAI,cAAc,GAAG,MAAM,CAAC;IAC5B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAiC,CAAC;QACpE,cAAc,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACnD,IAAI,eAAmC,CAAC;IACxC,IAAI,CAAC;QACH,+DAA+D;QAC/D,0EAA0E;QAC1E,wDAAwD;QACxD,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACtC,IACE,OAAO,KAAK,KAAK,UAAU;gBAC3B,OAAO,KAAK,KAAK,QAAQ;gBACzB,OAAO,KAAK,KAAK,QAAQ,EACzB,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;QACH,eAAe,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAAC,WAAM,CAAC;QACP,eAAe,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,yDAAyD,MAAM,KAAK;YAClE,8GAA8G,CACjH,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kCAAkC,CAChD,YAAoB,EACpB,MAAc,EACd,MAAe;IAEf,OAAO;QACL,YAAY;QACZ,cAAc,EAAE,8BAA8B,CAAC,MAAM,EAAE,MAAM,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/esm/payments/client-payments.d.ts

@@ -1,6 +1,8 @@
 import type { Transport } from '@contextvm/mcp-sdk/shared/transport';
+import { type JSONRPCRequest } from '@contextvm/mcp-sdk/types.js';
 import { PaymentHandler, PaymentHandlerRequest } from './types.js';
 import type { OriginalRequestContext } from '../transport/nostr-client/correlation-store.js';
+import type { PaymentInteractionMode, PaymentOption } from './types.js';
 export interface ClientPaymentsOptions {
     handlers: readonly PaymentHandler[];
     /**
@@ -30,6 +32,47 @@ export interface ClientPaymentsOptions {
      * triggered the payment.
      */
     paymentPolicy?: (req: PaymentHandlerRequest, originalRequestContext?: OriginalRequestContext) => boolean | Promise<boolean>;
+    /** Requested payment interaction mode. @default 'transparent' */
+    paymentInteraction?: PaymentInteractionMode;
+    /**
+     * Maximum number of -32043 (Payment Pending) retries before giving up.
+     *
+     * With retry_after=2 and 1.5× exponential backoff capped at 10s, the default
+     * of 10 retries gives ~45s of cumulative wait — enough for typical verification
+     * flows. Increase for slow payment processors (e.g. on-chain confirmation).
+     * @default 10
+     */
+    maxPendingRetries?: number;
+    /**
+     * Handler for explicit-gating -32042 errors.
+     * Called when a priced invocation returns Payment Required.
+     * The handler should pay one option and signal completion.
+     *
+     * **Error handling contract**:
+     * - If the promise resolves with `{ paid: true }`, the wrapper auto-retries the
+     *   original request with the same `method` and `params`.
+     * - If the promise resolves with `{ paid: false, reason }`, the wrapper synthesizes
+     *   a JSON-RPC error to the caller with code `-32042` and `data: { reason }`.
+     *   Use `reason: 'user_cancelled'` for user-initiated cancellations.
+     * - If the promise **rejects**, the wrapper MUST NOT silently fall back.
+     *   It synthesizes a JSON-RPC error with code `-32042` and
+     *   `data: { reason: error.message, type: 'payment_handler_error' }`.
+     * - Transient payment-provider failures should reject with an Error whose
+     *   `message` contains the provider error details.
+     *
+     * **Verify-timeout window**: if the server's verification times out or fails
+     * after the client paid, its pending state is cleared and the client's retry
+     * receives a fresh `-32042` with a new invoice (CEP-8-compliant). The wrapper
+     * does not dedup across distinct `pay_req` values.
+     */
+    onPaymentRequired?: (params: {
+        options: PaymentOption[];
+        instructions?: string;
+        originalRequest: JSONRPCRequest;
+    }) => Promise<{
+        paid: boolean;
+        reason?: string;
+    }>;
 }
 /**
  * Wraps a transport to automatically handle CEP-8 payment requests.

package/dist/esm/payments/client-payments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-payments.d.ts","sourceRoot":"","sources":["../../../src/payments/client-payments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AASrE,OAAO,EACL,cAAc,EAGd,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AAS7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,CACd,GAAG,EAAE,qBAAqB,EAC1B,sBAAsB,CAAC,EAAE,sBAAsB,KAC5C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,qBAAqB,GAC7B,SAAS,CA6ZX"}
+{"version":3,"file":"client-payments.d.ts","sourceRoot":"","sources":["../../../src/payments/client-payments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,cAAc,EAGd,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EAGd,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,CACd,GAAG,EAAE,qBAAqB,EAC1B,sBAAsB,CAAC,EAAE,sBAAsB,KAC5C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;IAE5C;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE;QAC3B,OAAO,EAAE,aAAa,EAAE,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,cAAc,CAAC;KACjC,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AA6DD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,qBAAqB,GAC7B,SAAS,CAqpBX"}