@agenticprimitives/payments 0.0.0-alpha.4 → 0.0.0-alpha.40

package/README.md

@@ -1,5 +1,7 @@
 # @agenticprimitives/payments
 
+> Part of **[Agentic Primitives](https://agenticprimitives.dev)** — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. [Developer kit](https://github.com/agentictrustlabs/agentic-primitives) · [All packages](https://agenticprimitives.dev/developers)
+
 > **Status: STUB** (Wave 0.5 of the W1 implementation wave). Typed primitives and invariant guards ship today; the EIP-712 mandate signer and the three W1 rails land in Wave 6 per the [w1 implementation wave plan](../../docs/architecture/w1-implementation-wave-plan.md). A recent self-audit flagged this package's docs for overclaiming ([NEW-PMT-1](../../docs/audits/findings.yaml)); this README is written to the actual surface.
 
 Machine payments arrived. x402 made HTTP-native pay-per-request real; Google's AP2 defined mandates for agent-initiated spend. What neither ships — what nobody ships — is machine payments scoped by the *same* delegation, custody, and audit substrate that governs everything else the agent does. "This agent may spend up to this amount, for this task, on this rail, until Friday — signed by a smart account, bound to the work it pays for, receipted into an attestation registry" is the combination the agent economy actually needs, and it only exists when payments are a layer of one system rather than a bolted-on rail.

package/dist/entitlement/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * spec 272 §10 — entitlements: pay-once-then-access.
+ *
+ * A successful settlement mints an `EntitlementRecord`. Later access reads CONSUME
+ * the entitlement (decrement `usesLeft`) with NO new settlement — one access lane
+ * (X402-D8): a request is served against {a fresh charge} OR {a live entitlement},
+ * never both. **Prepaid credits = an entitlement with `maxUses: N`** — same machinery.
+ *
+ * Two bindings:
+ *  - `'sa'`    — held by a specific SA; the presenter MUST be that SA.
+ *  - `'bearer'`— held by whoever presents the matching voucher (tier A3, unlinkable);
+ *                this module gates on `voucherId`, the voucher crypto lives in `./voucher`.
+ *
+ * Fail-closed: an unknown binding, scope mismatch, expiry, or exhausted uses all DENY.
+ * Pure (no store): `consumeEntitlement` returns the decremented record; the app persists — single-writer
+ * only. For a shared/persisted entitlement use `EntitlementStore.claimUse` (atomic conditional decrement,
+ * the ARCH-H3 sibling) so two concurrent redemptions can't double-spend a prepaid credit.
+ */
+import { type Address } from 'viem';
+import type { Hex32 } from '../index.js';
+export * as voucher from './voucher.js';
+export type EntitlementBinding = 'sa' | 'bearer';
+export interface EntitlementRecord {
+    entitlementId: Hex32;
+    binding: EntitlementBinding;
+    /** what this grants access to (e.g. keccak of the resource/skill scope) */
+    scopeHash: Hex32;
+    /** for `'sa'` binding — the SA that may present it */
+    subject?: Address;
+    /** for `'bearer'` binding — the voucher this entitlement is tied to */
+    voucherId?: Hex32;
+    /** expiry (unix seconds) */
+    ttl: number;
+    maxUses: number;
+    usesLeft: number;
+    provenance: {
+        mandateId: Hex32;
+        settlementHash: Hex32;
+    };
+}
+export interface MintEntitlementInput {
+    binding: EntitlementBinding;
+    scopeHash: Hex32;
+    ttl: number;
+    maxUses: number;
+    mandateId: Hex32;
+    settlementHash: Hex32;
+    /** required for `'sa'` binding */
+    subject?: Address;
+    /** required for `'bearer'` binding */
+    voucherId?: Hex32;
+}
+/** Mint an entitlement from a settled payment. Throws if the binding's required handle is missing. */
+export declare function mintEntitlementOnPayment(input: MintEntitlementInput): EntitlementRecord;
+/** Prepaid credit pack = an SA-bound entitlement with `maxUses = count`. */
+export declare function mintCredits(input: Omit<MintEntitlementInput, 'binding' | 'maxUses'> & {
+    subject: Address;
+    count: number;
+}): EntitlementRecord;
+export interface EntitlementContext {
+    scopeHash: Hex32;
+    now: number;
+    /** the SA presenting (required to match an `'sa'` binding) */
+    presenter?: Address;
+    /** the voucher id presented (required to match a `'bearer'` binding) */
+    voucherId?: Hex32;
+}
+export type EntitlementCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Fail-closed validity check (does NOT consume). */
+export declare function checkEntitlement(record: EntitlementRecord, ctx: EntitlementContext): EntitlementCheck;
+export interface ConsumptionReceipt {
+    entitlementId: Hex32;
+    scopeHash: Hex32;
+    usesLeftAfter: number;
+    at: number;
+}
+export type ConsumeResult = {
+    ok: true;
+    record: EntitlementRecord;
+    consumption: ConsumptionReceipt;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate + decrement (PURE — returns the updated record; does NOT persist).
+ *
+ * entitlement-consume-toctou-no-atomic-claim (2026-07-04 self-audit): on its own this is a TOCTOU seam.
+ * A caller that does `checkEntitlement()` (or `consumeEntitlement()`) and THEN persists `record.usesLeft`
+ * has a read→decrement→write window: two concurrent redemptions of a prepaid `usesLeft:1` credit can both
+ * read 1 and both write 0, double-spending a money-equivalent pack. Use this only in-process/single-writer.
+ * For a shared/persisted entitlement, go through {@link EntitlementStore.claimUse}, whose atomic conditional
+ * decrement is the ARCH-H3 sibling of `SpentSet.claim`.
+ */
+export declare function consumeEntitlement(record: EntitlementRecord, ctx: EntitlementContext): ConsumeResult;
+export interface EntitlementStore {
+    /**
+     * entitlement-consume-toctou / ARCH-H3 sibling: ATOMIC validate + single-use decrement of a STORED
+     * entitlement. Returns ok ONLY if this call claimed a use — the record exists, matches `ctx` (scope +
+     * binding + presenter/voucher), is unexpired, and had `usesLeft > 0` at the instant of decrement. Two
+     * concurrent redemptions of a `usesLeft:1` credit: exactly one gets ok, the other `entitlement exhausted`.
+     * A distributed backend MUST implement the decrement as a conditional write so atomicity lives in the
+     * interface, not each caller: D1 `UPDATE … SET usesLeft = usesLeft - 1 WHERE entitlementId = ? AND
+     * usesLeft > 0 RETURNING usesLeft` (rows-affected == 1 is the claim), a Durable Object transaction, or a
+     * conditional put. Mirrors `SpentSet.claim` / x402 `NonceReservationStore.reserve`.
+     */
+    claimUse(entitlementId: Hex32, ctx: EntitlementContext): ConsumeResult | Promise<ConsumeResult>;
+}
+/**
+ * Reference in-memory {@link EntitlementStore}. In-process JS is single-threaded, so the validate +
+ * decrement below is naturally atomic — the interface demands the same guarantee of every (distributed)
+ * implementer. Seed it with the minted records; `claimUse` mutates `usesLeft` in place under the claim.
+ */
+export declare function createMemoryEntitlementStore(records?: Iterable<EntitlementRecord>): EntitlementStore & {
+    put(record: EntitlementRecord): void;
+    get(id: Hex32): EntitlementRecord | undefined;
+};
+/** Convenience: keccak of a resource/skill scope string → `scopeHash`. */
+export declare function scopeHashOf(scope: string): Hex32;
+//# sourceMappingURL=index.d.ts.map

package/dist/entitlement/index.d.ts.map

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

package/dist/entitlement/index.js

@@ -0,0 +1,128 @@
+/**
+ * spec 272 §10 — entitlements: pay-once-then-access.
+ *
+ * A successful settlement mints an `EntitlementRecord`. Later access reads CONSUME
+ * the entitlement (decrement `usesLeft`) with NO new settlement — one access lane
+ * (X402-D8): a request is served against {a fresh charge} OR {a live entitlement},
+ * never both. **Prepaid credits = an entitlement with `maxUses: N`** — same machinery.
+ *
+ * Two bindings:
+ *  - `'sa'`    — held by a specific SA; the presenter MUST be that SA.
+ *  - `'bearer'`— held by whoever presents the matching voucher (tier A3, unlinkable);
+ *                this module gates on `voucherId`, the voucher crypto lives in `./voucher`.
+ *
+ * Fail-closed: an unknown binding, scope mismatch, expiry, or exhausted uses all DENY.
+ * Pure (no store): `consumeEntitlement` returns the decremented record; the app persists — single-writer
+ * only. For a shared/persisted entitlement use `EntitlementStore.claimUse` (atomic conditional decrement,
+ * the ARCH-H3 sibling) so two concurrent redemptions can't double-spend a prepaid credit.
+ */
+import { keccak256, encodeAbiParameters, toBytes } from 'viem';
+// tier A3 — blind bearer vouchers (Privacy Pass / VOPRF).
+export * as voucher from './voucher.js';
+const ZERO32 = ('0x' + '00'.repeat(32));
+function entitlementId(args) {
+    return keccak256(encodeAbiParameters([{ type: 'string' }, { type: 'bytes32' }, { type: 'bytes32' }, { type: 'bytes32' }], [
+        args.binding,
+        args.scopeHash,
+        args.binding === 'sa'
+            ? keccak256(toBytes(args.subject ?? '0x'))
+            : (args.voucherId ?? ZERO32),
+        args.mandateId,
+    ]));
+}
+/** Mint an entitlement from a settled payment. Throws if the binding's required handle is missing. */
+export function mintEntitlementOnPayment(input) {
+    if (input.binding === 'sa' && !input.subject)
+        throw new Error("[entitlement] 'sa' binding requires subject");
+    if (input.binding === 'bearer' && !input.voucherId)
+        throw new Error("[entitlement] 'bearer' binding requires voucherId");
+    if (input.maxUses < 1)
+        throw new Error('[entitlement] maxUses must be >= 1');
+    return {
+        entitlementId: entitlementId(input),
+        binding: input.binding,
+        scopeHash: input.scopeHash,
+        subject: input.subject,
+        voucherId: input.voucherId,
+        ttl: input.ttl,
+        maxUses: input.maxUses,
+        usesLeft: input.maxUses,
+        provenance: { mandateId: input.mandateId, settlementHash: input.settlementHash },
+    };
+}
+/** Prepaid credit pack = an SA-bound entitlement with `maxUses = count`. */
+export function mintCredits(input) {
+    return mintEntitlementOnPayment({ ...input, binding: 'sa', maxUses: input.count });
+}
+/** Fail-closed validity check (does NOT consume). */
+export function checkEntitlement(record, ctx) {
+    if (record.binding !== 'sa' && record.binding !== 'bearer')
+        return { ok: false, reason: 'unknown entitlement binding' };
+    if (record.scopeHash.toLowerCase() !== ctx.scopeHash.toLowerCase())
+        return { ok: false, reason: 'scope mismatch' };
+    if (ctx.now >= record.ttl)
+        return { ok: false, reason: 'entitlement expired' };
+    if (record.usesLeft <= 0)
+        return { ok: false, reason: 'entitlement exhausted' };
+    if (record.binding === 'sa') {
+        if (!ctx.presenter || !record.subject || ctx.presenter.toLowerCase() !== record.subject.toLowerCase()) {
+            return { ok: false, reason: 'presenter is not the entitlement subject' };
+        }
+    }
+    else {
+        if (!ctx.voucherId || !record.voucherId || ctx.voucherId.toLowerCase() !== record.voucherId.toLowerCase()) {
+            return { ok: false, reason: 'voucher mismatch' };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Validate + decrement (PURE — returns the updated record; does NOT persist).
+ *
+ * entitlement-consume-toctou-no-atomic-claim (2026-07-04 self-audit): on its own this is a TOCTOU seam.
+ * A caller that does `checkEntitlement()` (or `consumeEntitlement()`) and THEN persists `record.usesLeft`
+ * has a read→decrement→write window: two concurrent redemptions of a prepaid `usesLeft:1` credit can both
+ * read 1 and both write 0, double-spending a money-equivalent pack. Use this only in-process/single-writer.
+ * For a shared/persisted entitlement, go through {@link EntitlementStore.claimUse}, whose atomic conditional
+ * decrement is the ARCH-H3 sibling of `SpentSet.claim`.
+ */
+export function consumeEntitlement(record, ctx) {
+    const v = checkEntitlement(record, ctx);
+    if (!v.ok)
+        return v;
+    const updated = { ...record, usesLeft: record.usesLeft - 1 };
+    return {
+        ok: true,
+        record: updated,
+        consumption: { entitlementId: record.entitlementId, scopeHash: record.scopeHash, usesLeftAfter: updated.usesLeft, at: ctx.now },
+    };
+}
+/**
+ * Reference in-memory {@link EntitlementStore}. In-process JS is single-threaded, so the validate +
+ * decrement below is naturally atomic — the interface demands the same guarantee of every (distributed)
+ * implementer. Seed it with the minted records; `claimUse` mutates `usesLeft` in place under the claim.
+ */
+export function createMemoryEntitlementStore(records = []) {
+    const byId = new Map();
+    for (const r of records)
+        byId.set(r.entitlementId.toLowerCase(), { ...r });
+    return {
+        put: (r) => byId.set(r.entitlementId.toLowerCase(), { ...r }),
+        get: (id) => byId.get(id.toLowerCase()),
+        claimUse: (id, ctx) => {
+            const record = byId.get(id.toLowerCase());
+            if (!record)
+                return { ok: false, reason: 'entitlement not found' };
+            const result = consumeEntitlement(record, ctx);
+            if (!result.ok)
+                return result;
+            byId.set(id.toLowerCase(), result.record); // commit the decrement under the same synchronous claim
+            return result;
+        },
+    };
+}
+/** Convenience: keccak of a resource/skill scope string → `scopeHash`. */
+export function scopeHashOf(scope) {
+    return keccak256(toBytes(`entitlement-scope:${scope}`));
+}
+//# sourceMappingURL=index.js.map

package/dist/entitlement/index.js.map

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

package/dist/entitlement/voucher.d.ts

@@ -0,0 +1,85 @@
+/**
+ * spec 272 §10 tier A3 — blind bearer vouchers (Privacy Pass / RFC 9497 VOPRF).
+ *
+ * Pay once → receive a pack of UNLINKABLE one-use vouchers → redeem each from a
+ * separate context with no link back to the purchase. Built on ristretto255 VOPRF
+ * (`@noble/curves`) — the issuer never sees the unblinded token at issuance, so the
+ * blinded request it signs and the token presented at redemption cannot be linked.
+ *
+ * Flow:
+ *   client  blindVoucherRequest()  → { request(blinded), secret(tokenId,blind,blinded) }
+ *   issuer  issueVoucher(key, request) → { evaluated, proof }            (VOPRF blind-evaluate)
+ *   client  unblindVoucher(secret, issued, pubKey) → Voucher            (verifies the issuer proof)
+ *   issuer  redeemVoucher(key, voucher, spentSet) → ok | reason         (VOPRF verify + double-spend)
+ *
+ * One-use is enforced by the spent-set keyed on `voucherId = keccak(tokenId)`.
+ */
+import type { Hex } from '@agenticprimitives/types';
+import type { Hex32 } from '../index.js';
+export interface VoucherIssuerKey {
+    secretKey: Hex;
+    publicKey: Hex;
+}
+export interface BlindedVoucherRequest {
+    blinded: Hex;
+}
+/** The client's unblinding state — kept private until `unblindVoucher`. */
+export interface VoucherSecret {
+    tokenId: Hex;
+    blind: Hex;
+    blinded: Hex;
+}
+export interface IssuedVoucher {
+    evaluated: Hex;
+    proof: Hex;
+}
+/** A redeemable one-use bearer token. */
+export interface Voucher {
+    voucherId: Hex32;
+    tokenId: Hex;
+    output: Hex;
+}
+export declare function generateVoucherIssuerKey(): VoucherIssuerKey;
+/** Deterministic issuer key from a 32-byte seed (stable across processes). */
+export declare function deriveVoucherIssuerKey(seed: Hex, info?: string): VoucherIssuerKey;
+/** `voucherId` — the public, spent-set key derived from the token (no link to the blinded request). */
+export declare function voucherIdOf(tokenId: Hex): Hex32;
+/** Client: blind a fresh random token (or a supplied one) for issuance. */
+export declare function blindVoucherRequest(tokenId?: Hex): {
+    request: BlindedVoucherRequest;
+    secret: VoucherSecret;
+};
+/** Issuer: blind-evaluate one request (VOPRF — issuer learns nothing about the token). */
+export declare function issueVoucher(key: VoucherIssuerKey, request: BlindedVoucherRequest): IssuedVoucher;
+/** Issuer: issue a whole pack. */
+export declare function issueVouchers(key: VoucherIssuerKey, requests: BlindedVoucherRequest[]): IssuedVoucher[];
+/**
+ * Client: unblind into a finished voucher. Throws if the issuer's VOPRF proof fails
+ * (a malicious issuer using the wrong key is detected here — verifiability).
+ */
+export declare function unblindVoucher(secret: VoucherSecret, issued: IssuedVoucher, issuerPublicKey: Hex): Voucher;
+/** Issuer: VOPRF validity of a presented voucher (does NOT check double-spend). Fail-closed. */
+export declare function verifyVoucher(key: VoucherIssuerKey, voucher: Voucher): {
+    ok: boolean;
+    reason?: string;
+};
+export interface SpentSet {
+    /**
+     * ARCH-H3 (seam audit): ATOMIC claim of a one-use id. Returns `true` if THIS call claimed the id
+     * (it was fresh), `false` if it was already spent. Replaces the former TOCTOU `has()` + `add()` pair —
+     * a check-then-add across an `await` let two concurrent redemptions of a money-equivalent one-use
+     * voucher BOTH succeed. A distributed backend MUST implement this as an insert-if-absent (D1 `INSERT
+     * ... ON CONFLICT DO NOTHING` + rows-affected, a Durable Object transaction, or a conditional put) so
+     * the atomicity lives in the interface, not in each caller. Mirrors x402 `NonceReservationStore.reserve`.
+     */
+    claim(id: Hex32): boolean | Promise<boolean>;
+}
+export declare function createMemorySpentSet(): SpentSet & {
+    size(): number;
+};
+/** Issuer: verify + one-shot redeem. Rejects an invalid voucher and a replayed one. */
+export declare function redeemVoucher(key: VoucherIssuerKey, voucher: Voucher, spent: SpentSet): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+//# sourceMappingURL=voucher.d.ts.map

package/dist/entitlement/voucher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voucher.d.ts","sourceRoot":"","sources":["../../src/entitlement/voucher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAezC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,GAAG,CAAC;IACf,SAAS,EAAE,GAAG,CAAC;CAChB;AACD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,GAAG,CAAC;CACd;AACD,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,OAAO,EAAE,GAAG,CAAC;CACd;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,GAAG,CAAC;IACf,KAAK,EAAE,GAAG,CAAC;CACZ;AACD,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,GAAG,CAAC;IACb,MAAM,EAAE,GAAG,CAAC;CACb;AAED,wBAAgB,wBAAwB,IAAI,gBAAgB,CAG3D;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,SAA2B,GAAG,gBAAgB,CAGnG;AAED,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,GAAG,KAAK,CAE/C;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG;IAAE,OAAO,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAO5G;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAGjG;AAED,kCAAkC;AAClC,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,qBAAqB,EAAE,GAAG,aAAa,EAAE,CAEvG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,GAAG,OAAO,CAU1G;AASD,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAUvG;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C;AAED,wBAAgB,oBAAoB,IAAI,QAAQ,GAAG;IAAE,IAAI,IAAI,MAAM,CAAA;CAAE,CAapE;AAED,uFAAuF;AACvF,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAMvI"}

package/dist/entitlement/voucher.js

@@ -0,0 +1,109 @@
+/**
+ * spec 272 §10 tier A3 — blind bearer vouchers (Privacy Pass / RFC 9497 VOPRF).
+ *
+ * Pay once → receive a pack of UNLINKABLE one-use vouchers → redeem each from a
+ * separate context with no link back to the purchase. Built on ristretto255 VOPRF
+ * (`@noble/curves`) — the issuer never sees the unblinded token at issuance, so the
+ * blinded request it signs and the token presented at redemption cannot be linked.
+ *
+ * Flow:
+ *   client  blindVoucherRequest()  → { request(blinded), secret(tokenId,blind,blinded) }
+ *   issuer  issueVoucher(key, request) → { evaluated, proof }            (VOPRF blind-evaluate)
+ *   client  unblindVoucher(secret, issued, pubKey) → Voucher            (verifies the issuer proof)
+ *   issuer  redeemVoucher(key, voucher, spentSet) → ok | reason         (VOPRF verify + double-spend)
+ *
+ * One-use is enforced by the spent-set keyed on `voucherId = keccak(tokenId)`.
+ */
+import { ristretto255_oprf } from '@noble/curves/ed25519.js';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import { keccak256 } from 'viem';
+const voprf = ristretto255_oprf.voprf;
+const enc = new TextEncoder();
+// @noble bytesToHex returns NO `0x` prefix; add it so values are real `Hex` and `.slice(2)` strips it.
+const hx = (b) => ('0x' + bytesToHex(b));
+export function generateVoucherIssuerKey() {
+    const kp = voprf.generateKeyPair();
+    return { secretKey: hx(kp.secretKey), publicKey: hx(kp.publicKey) };
+}
+/** Deterministic issuer key from a 32-byte seed (stable across processes). */
+export function deriveVoucherIssuerKey(seed, info = 'agentic-voucher-issuer') {
+    const kp = voprf.deriveKeyPair(hexToBytes(seed.slice(2)), enc.encode(info));
+    return { secretKey: hx(kp.secretKey), publicKey: hx(kp.publicKey) };
+}
+/** `voucherId` — the public, spent-set key derived from the token (no link to the blinded request). */
+export function voucherIdOf(tokenId) {
+    return keccak256(tokenId);
+}
+/** Client: blind a fresh random token (or a supplied one) for issuance. */
+export function blindVoucherRequest(tokenId) {
+    const tok = tokenId ? hexToBytes(tokenId.slice(2)) : globalThis.crypto.getRandomValues(new Uint8Array(32));
+    const { blind, blinded } = voprf.blind(tok);
+    return {
+        request: { blinded: hx(blinded) },
+        secret: { tokenId: hx(tok), blind: hx(blind), blinded: hx(blinded) },
+    };
+}
+/** Issuer: blind-evaluate one request (VOPRF — issuer learns nothing about the token). */
+export function issueVoucher(key, request) {
+    const be = voprf.blindEvaluate(hexToBytes(key.secretKey.slice(2)), hexToBytes(key.publicKey.slice(2)), hexToBytes(request.blinded.slice(2)));
+    return { evaluated: hx(be.evaluated), proof: hx(be.proof) };
+}
+/** Issuer: issue a whole pack. */
+export function issueVouchers(key, requests) {
+    return requests.map((r) => issueVoucher(key, r));
+}
+/**
+ * Client: unblind into a finished voucher. Throws if the issuer's VOPRF proof fails
+ * (a malicious issuer using the wrong key is detected here — verifiability).
+ */
+export function unblindVoucher(secret, issued, issuerPublicKey) {
+    const output = voprf.finalize(hexToBytes(secret.tokenId.slice(2)), hexToBytes(secret.blind.slice(2)), hexToBytes(issued.evaluated.slice(2)), hexToBytes(secret.blinded.slice(2)), hexToBytes(issuerPublicKey.slice(2)), hexToBytes(issued.proof.slice(2)));
+    return { voucherId: voucherIdOf(secret.tokenId), tokenId: secret.tokenId, output: hx(output) };
+}
+function ctEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+/** Issuer: VOPRF validity of a presented voucher (does NOT check double-spend). Fail-closed. */
+export function verifyVoucher(key, voucher) {
+    try {
+        if (voucher.voucherId.toLowerCase() !== voucherIdOf(voucher.tokenId).toLowerCase()) {
+            return { ok: false, reason: 'voucherId does not match tokenId' };
+        }
+        const expected = voprf.evaluate(hexToBytes(key.secretKey.slice(2)), hexToBytes(voucher.tokenId.slice(2)));
+        return ctEqual(expected, hexToBytes(voucher.output.slice(2))) ? { ok: true } : { ok: false, reason: 'invalid voucher' };
+    }
+    catch {
+        return { ok: false, reason: 'malformed voucher' };
+    }
+}
+export function createMemorySpentSet() {
+    const set = new Set();
+    return {
+        // In-process JS is single-threaded, so test-and-set here is naturally atomic; the interface demands
+        // the same guarantee of every (distributed) implementer.
+        claim: (id) => {
+            const k = id.toLowerCase();
+            if (set.has(k))
+                return false;
+            set.add(k);
+            return true;
+        },
+        size: () => set.size,
+    };
+}
+/** Issuer: verify + one-shot redeem. Rejects an invalid voucher and a replayed one. */
+export async function redeemVoucher(key, voucher, spent) {
+    const v = verifyVoucher(key, voucher);
+    if (!v.ok)
+        return v;
+    // ARCH-H3: atomic claim — no check-then-add window. Two concurrent redemptions can't both win.
+    if (!(await spent.claim(voucher.voucherId)))
+        return { ok: false, reason: 'voucher already spent' };
+    return { ok: true };
+}
+//# sourceMappingURL=voucher.js.map

package/dist/entitlement/voucher.js.map

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

package/dist/external-checkout.d.ts

@@ -0,0 +1,40 @@
+import type { Hex32 } from './index.js';
+/** A payment credential a company or PSP issued for ONE operation — held by REFERENCE, bound by digest, expiring. */
+export interface ExternalPaymentCredentialRefV1 {
+    type: 'ap.external-payment-credential.v1';
+    /** Who issued it: the PSP / credential provider, as an https origin. */
+    provider: string;
+    /** An opaque reference to the credential sealed in the vault or held by the provider — never the token itself. */
+    credentialRef: string;
+    /** The external operation this credential may settle (`externalOperationIntentDigest`); any other is refused. */
+    boundToIntentDigest: Hex32;
+    /** Unix seconds; short by design. */
+    expiresAt: number;
+    singleUse: true;
+}
+export type Ap2MandateKind = 'intent' | 'cart' | 'payment';
+/** OUR mandate in THEIR envelope: a VC-JWS the Smart Agent signed, carrying the spec 336 mandate by digest. */
+export interface Ap2MandateEnvelopeRefV1 {
+    type: 'ap.ap2-mandate-envelope.v1';
+    kind: Ap2MandateKind;
+    /** The spec 336 mandate (delegation + intent-digest caveat) this envelope carries, by digest. The authority is there, not here. */
+    mandateDigest: Hex32;
+    /** The Smart Agent that signed the VC-JWS (CAIP-10); verified through ERC-1271, never a bare key. */
+    subject: string;
+    envelope: 'vc-jws';
+    /** The compact JWS, when rendered. Absent in a record that only names the mandate. */
+    jws?: string;
+    expiresAt: number;
+}
+/** A JWT, a PAN or a long bare token where a REFERENCE belongs. */
+export declare function looksLikeRawPaymentCredential(s: string): boolean;
+export declare function validateExternalPaymentCredentialRef(c: unknown): string[];
+export declare function validateAp2MandateEnvelopeRef(e: unknown): string[];
+/** May this credential settle THIS operation now? Bound by digest, expiring, single-use — nothing else is asked here. */
+export declare function paymentCredentialCovers(c: ExternalPaymentCredentialRefV1, intentDigest: Hex32, now: number): {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'CREDENTIAL_MALFORMED' | 'CREDENTIAL_NOT_BOUND_TO_OPERATION' | 'CREDENTIAL_EXPIRED';
+};
+//# sourceMappingURL=external-checkout.d.ts.map

package/dist/external-checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-checkout.d.ts","sourceRoot":"","sources":["../src/external-checkout.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,qHAAqH;AACrH,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,mCAAmC,CAAC;IAC1C,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,kHAAkH;IAClH,aAAa,EAAE,MAAM,CAAC;IACtB,iHAAiH;IACjH,mBAAmB,EAAE,KAAK,CAAC;IAC3B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,4BAA4B,CAAC;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,mIAAmI;IACnI,aAAa,EAAE,KAAK,CAAC;IACrB,qGAAqG;IACrG,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,mEAAmE;AACnE,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,wBAAgB,oCAAoC,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAYzE;AAED,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAYlE;AAED,yHAAyH;AACzH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,8BAA8B,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,sBAAsB,GAAG,mCAAmC,GAAG,oBAAoB,CAAA;CAAE,CAKtO"}

package/dist/external-checkout.js

@@ -0,0 +1,70 @@
+// PAYMENTS AT THE COMPANY'S DOOR — types only (spec 442 §10; spec 337 §4.3).
+//
+// ACP's Shared Payment Token and UCP's payment-token-exchange output are the `apeng:ExecutionCredential` discipline:
+// the agent never sees raw credentials; the credential is short-lived and bound to ONE checkout. AP2's three
+// mandates (intent · cart · payment) are W3C VCs; ours is the spec 336 mandate, and when a UCP checkout wants
+// "AP2 mandate JWTs in the body" it carries OUR mandate in THEIR envelope — a VC-JWS the Smart Agent signs
+// (ERC-1271 through `verifiable-credentials`). Fiat rails (cards, PAR, PSP exchange) stay Ring 1 (442 §14).
+//
+// Nothing here moves value or signs; these are the reference shapes the ap-federation projections render, and the
+// validators refuse the one thing that must never be in a record: a raw credential.
+const HEX32 = /^0x[0-9a-f]{64}$/;
+const HTTPS_ORIGIN = /^https:\/\/[^\s/?#]+$/;
+const CAIP10_EVM = /^eip155:\d+:0x[0-9a-fA-F]{40}$/;
+/** A JWT, a PAN or a long bare token where a REFERENCE belongs. */
+export function looksLikeRawPaymentCredential(s) {
+    return /^ey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./.test(s) || /^\d{13,19}$/.test(s) || /^(tok|pm|spt)_[A-Za-z0-9]{16,}$/.test(s);
+}
+export function validateExternalPaymentCredentialRef(c) {
+    const issues = [];
+    if (typeof c !== 'object' || c === null || Array.isArray(c))
+        return ['credential: must be an object'];
+    const x = c;
+    if (x.type !== 'ap.external-payment-credential.v1')
+        issues.push('credential.type: must be ap.external-payment-credential.v1');
+    if (typeof x.provider !== 'string' || !HTTPS_ORIGIN.test(x.provider))
+        issues.push('credential.provider: must be an https origin');
+    if (typeof x.credentialRef !== 'string' || !x.credentialRef)
+        issues.push('credential.credentialRef: required');
+    else if (looksLikeRawPaymentCredential(x.credentialRef))
+        issues.push('credential.credentialRef: looks like a raw payment credential — the agent never holds one; a reference only');
+    if (typeof x.boundToIntentDigest !== 'string' || !HEX32.test(x.boundToIntentDigest))
+        issues.push('credential.boundToIntentDigest: must be 0x + 64 lowercase hex');
+    if (!Number.isInteger(x.expiresAt) || x.expiresAt <= 0)
+        issues.push('credential.expiresAt: must be a positive integer');
+    if (x.singleUse !== true)
+        issues.push('credential.singleUse: must be true — a reusable payment credential is a card on file, which is Ring 1');
+    return issues;
+}
+export function validateAp2MandateEnvelopeRef(e) {
+    const issues = [];
+    if (typeof e !== 'object' || e === null || Array.isArray(e))
+        return ['envelope: must be an object'];
+    const x = e;
+    if (x.type !== 'ap.ap2-mandate-envelope.v1')
+        issues.push('envelope.type: must be ap.ap2-mandate-envelope.v1');
+    if (x.kind !== 'intent' && x.kind !== 'cart' && x.kind !== 'payment')
+        issues.push('envelope.kind: must be intent | cart | payment');
+    if (typeof x.mandateDigest !== 'string' || !HEX32.test(x.mandateDigest))
+        issues.push('envelope.mandateDigest: must be 0x + 64 lowercase hex');
+    if (typeof x.subject !== 'string' || !CAIP10_EVM.test(x.subject))
+        issues.push('envelope.subject: must be a CAIP-10 Smart Agent');
+    if (x.envelope !== 'vc-jws')
+        issues.push('envelope.envelope: must be vc-jws');
+    if (x.jws !== undefined && (typeof x.jws !== 'string' || x.jws.split('.').length !== 3))
+        issues.push('envelope.jws: must be a compact JWS');
+    if (!Number.isInteger(x.expiresAt) || x.expiresAt <= 0)
+        issues.push('envelope.expiresAt: must be a positive integer');
+    return issues;
+}
+/** May this credential settle THIS operation now? Bound by digest, expiring, single-use — nothing else is asked here. */
+export function paymentCredentialCovers(c, intentDigest, now) {
+    if (validateExternalPaymentCredentialRef(c).length)
+        return { ok: false, reason: 'CREDENTIAL_MALFORMED' };
+    if (c.boundToIntentDigest.toLowerCase() !== intentDigest.toLowerCase())
+        return { ok: false, reason: 'CREDENTIAL_NOT_BOUND_TO_OPERATION' };
+    if (c.expiresAt <= now)
+        return { ok: false, reason: 'CREDENTIAL_EXPIRED' };
+    return { ok: true };
+}
+//# sourceMappingURL=external-checkout.js.map

package/dist/external-checkout.js.map

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