@devlab.group/agent-commerce 1.4.1 → 1.6.0

package/dist/ap2.d.ts

@@ -1,11 +1,11 @@
-import { E as EnabledAp2Config } from './types-CJtwLu1c.js';
-export { A as AP2_CHECKOUT_MANDATE_VCT, a as AP2_CHECKOUT_PROFILE, b as AP2_DEFAULT_CLOCK_SKEW_SECONDS, c as AP2_MAX_CLOCK_SKEW_SECONDS, d as AP2_SIGNING_ALGORITHM, e as AP2_SPEC_VERSION, f as Ap2AuthorizationConfig, g as Ap2Mode, h as Ap2TrustedIssuer, i as Ap2TrustedKey } from './types-CJtwLu1c.js';
-import { A as AuthorizationProvider } from './authorization-CPDcpJVa.js';
-import { C as Clock, L as Logger } from './runtime-CKq3d_3K.js';
+import { E as EnabledAp2Config } from './types-O6lg3Q5V.js';
+export { A as AP2_CHECKOUT_MANDATE_VCT, a as AP2_CHECKOUT_PROFILE, b as AP2_DEFAULT_CLOCK_SKEW_SECONDS, c as AP2_MAX_CLOCK_SKEW_SECONDS, d as AP2_SIGNING_ALGORITHM, e as AP2_SPEC_VERSION, f as Ap2AuthorizationConfig, g as Ap2Mode, h as Ap2TrustedIssuer, i as Ap2TrustedKey } from './types-O6lg3Q5V.js';
+import { A as AuthorizationProvider } from './authorization-BpbWGGrf.js';
+import { C as Clock, L as Logger } from './runtime-CiYbgGpi.js';
 
 /**
  * A private ES256 key: either a private JWK (the pair of the public one in the
- * gateway's `checkoutIssuers`) or a PKCS#8 PEM, as `openssl` emits it.
+ * gateway's `checkoutIssuers`) or a PKCS#8 PEM, as `openssl` emits it
  */
 type Ap2SigningKey = Readonly<Record<string, unknown>> | string;
 interface CreateCheckoutJwtOptions {
@@ -19,12 +19,12 @@ interface CreateCheckoutJwtOptions {
     readonly resourceId: string;
     /**
      * The resource input this purchase is for, exactly as the buyer will send
-     * it: no reserved fields, no request id, no transport metadata.
+     * it: no reserved fields, no request id, no transport metadata
      */
     readonly input: unknown;
     /**
      * Decimal string, never a number, and compared as a string: `0.10` and `0.1`
-     * are different mandates. Take it from your own catalogue rather than from
+     * are different mandates. Take it from your own catalog rather than from
      * whatever the agent asked for.
      */
     readonly amount: string;
@@ -39,7 +39,7 @@ interface CreateCheckoutJwtOptions {
     readonly destination?: string;
     readonly network?: string;
     readonly asset?: string;
-    /** Defaults to a random UUID. Recorded on the receipt and used for replay defence */
+    /** Defaults to a random UUID. Recorded on the receipt and used for replay defense */
     readonly jwtId?: string;
     /** Defaults to 900: a human approval sits inside this window */
     readonly expiresInSeconds?: number;
@@ -48,7 +48,7 @@ interface CreateCheckoutJwtOptions {
 }
 /**
  * Returns the compact JWT to hand to the agent, which wraps it in the Checkout
- * Mandate the buyer signs.
+ * Mandate the buyer signs
  */
 declare function createCheckoutJwt(options: CreateCheckoutJwtOptions): Promise<string>;
 
@@ -62,9 +62,9 @@ declare function createCheckoutJwt(options: CreateCheckoutJwtOptions): Promise<s
 /** What this provider actually verifies */
 declare const AP2_CAPABILITIES: readonly string[];
 /**
- * Everything an AP2 client may reasonably expect and will not get here.
- * Complete on purpose: a short list reads as "mostly compatible", which is the
- * blanket claim alpha honesty forbids.
+ * Major AP2 features this provider does not support, published in its
+ * descriptor and printed by `doctor`, so no client assumes full protocol
+ * support
  */
 declare const AP2_UNSUPPORTED: readonly string[];
 
@@ -74,7 +74,7 @@ declare const AP2_UNSUPPORTED: readonly string[];
  * `CommerceError.message` reaches the client, and a mandate carries the
  * buyer's purchase and often personal data, so messages are fixed phrases from
  * the list below. The machine-readable code goes in `details.reason` and the
- * original exception on `cause`, which is never serialised.
+ * original exception on `cause`, which is never serialized.
  *
  * Three codes: AUTHORIZATION_INVALID when the buyer's mandate is bad,
  * AUTHORIZATION_REPLAYED when it is good but spent, and
@@ -84,9 +84,11 @@ declare const AP2_UNSUPPORTED: readonly string[];
 
 /**
  * Coarse on purpose: a client learns roughly where its mandate was refused,
- * not which check failed. Finer detail is an oracle for probing trust policy.
+ * not which check failed. Finer detail is an oracle for probing trust policy,
+ * so a mandate signed with a disallowed algorithm reports `invalid_signature`
+ * and one declaring a digest other than sha-256 `malformed_presentation`.
  */
-declare const AP2_REJECTION_REASONS: readonly ["malformed_presentation", "untrusted_issuer", "unknown_key", "invalid_signature", "unsupported_algorithm", "invalid_claims", "expired", "wrong_audience", "unsupported_mandate_type", "checkout_binding_failed", "purchase_mismatch"];
+declare const AP2_REJECTION_REASONS: readonly ["malformed_presentation", "untrusted_issuer", "unknown_key", "invalid_signature", "invalid_claims", "expired", "wrong_audience", "unsupported_mandate_type", "checkout_binding_failed", "purchase_mismatch"];
 type Ap2RejectionReason = (typeof AP2_REJECTION_REASONS)[number];
 
 /**
@@ -96,7 +98,7 @@ type Ap2RejectionReason = (typeof AP2_REJECTION_REASONS)[number];
  */
 type Ap2AuthorizationState = 'reserved' | 'consumed' | 'released' | 'uncertain';
 /**
- * A digest and a few identifiers: everything replay defence needs, and nothing
+ * A digest and a few identifiers: everything replay defense needs, and nothing
  * a leaked database would hand an attacker
  */
 interface Ap2ReservationRequest {
@@ -139,8 +141,8 @@ interface Ap2ReplayStore {
  * The AP2 authorization provider: the seam between core's generic contract and
  * the mandate machinery.
  *
- * Owns the replay database, so the gateway owns this object's lifetime and
- * closes it on shutdown.
+ * It owns its replay store, so whoever creates it must call `close()`:
+ * `createGateway` does not close authorization providers.
  */
 
 interface Ap2AuthorizationProviderOptions {
@@ -151,14 +153,9 @@ interface Ap2AuthorizationProviderOptions {
     readonly replayStore?: Ap2ReplayStore;
 }
 interface Ap2AuthorizationProvider extends AuthorizationProvider {
-    /** Closes the replay database */
+    /** Closes the replay store */
     close(): void;
 }
-/**
- * A reservation is keyed by the mandate reference, so the handle and the
- * receipt's identity are the same digest. Kept as one name rather than two
- * fields that must never disagree.
- */
 declare function createAp2AuthorizationProvider(options: Ap2AuthorizationProviderOptions): Ap2AuthorizationProvider;
 
 export { AP2_CAPABILITIES, AP2_REJECTION_REASONS, AP2_UNSUPPORTED, type Ap2AuthorizationProvider, type Ap2AuthorizationProviderOptions, type Ap2RejectionReason, type Ap2SigningKey, type CreateCheckoutJwtOptions, EnabledAp2Config, createAp2AuthorizationProvider as ap2, createAp2AuthorizationProvider, createCheckoutJwt };

package/dist/ap2.js

@@ -1,8 +1,9 @@
-import { AP2_CHECKOUT_MANDATE_VCT, AP2_SIGNING_ALGORITHM, AP2_DIGEST_ALGORITHM, AP2_CHECKOUT_PROFILE, AP2_SPEC_VERSION, AP2_KEY_TYPE, AP2_JWK_CURVE, openSqliteDatabase } from './chunk-GF6KHHKL.js';
-export { AP2_CHECKOUT_MANDATE_VCT, AP2_CHECKOUT_PROFILE, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_MAX_CLOCK_SKEW_SECONDS, AP2_SIGNING_ALGORITHM, AP2_SPEC_VERSION } from './chunk-GF6KHHKL.js';
-import { systemClock, NOOP_LOGGER, CommerceError, PACKAGE_VERSION } from './chunk-ZEGFLRGV.js';
-import { SignJWT, importPKCS8, importJWK, jwtVerify } from 'jose';
+import { AP2_CHECKOUT_MANDATE_VCT, AP2_SIGNING_ALGORITHM, AP2_DIGEST_ALGORITHM, AP2_CHECKOUT_PROFILE, AP2_SPEC_VERSION, AP2_KEY_TYPE, AP2_JWK_CURVE, openSqliteDatabase } from './chunk-RAJGPGJG.js';
+export { AP2_CHECKOUT_MANDATE_VCT, AP2_CHECKOUT_PROFILE, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_MAX_CLOCK_SKEW_SECONDS, AP2_SIGNING_ALGORITHM, AP2_SPEC_VERSION } from './chunk-RAJGPGJG.js';
+import { systemClock, NOOP_LOGGER, CommerceError, isRecord, PACKAGE_VERSION } from './chunk-IVJC5YLE.js';
+import { SignJWT, importPKCS8, importJWK, jwtVerify, decodeProtectedHeader, decodeJwt } from 'jose';
 import canonicalize from 'canonicalize';
+import { createHash } from 'crypto';
 import { decodeSdJwt, splitSdJwt, getClaims } from '@sd-jwt/core';
 
 // src/authorization/ap2/errors.ts
@@ -11,7 +12,6 @@ var AP2_REJECTION_REASONS = [
   "untrusted_issuer",
   "unknown_key",
   "invalid_signature",
-  "unsupported_algorithm",
   "invalid_claims",
   "expired",
   "wrong_audience",
@@ -24,7 +24,6 @@ var MESSAGES = {
   untrusted_issuer: "The mandate was issued by a party this merchant does not trust.",
   unknown_key: "The mandate names a signing key this merchant does not trust.",
   invalid_signature: "The mandate signature did not verify.",
-  unsupported_algorithm: "The mandate uses a signature or digest algorithm that is not accepted.",
   invalid_claims: "The mandate is missing required claims or they are malformed.",
   expired: "The mandate is expired or not yet valid.",
   wrong_audience: "The mandate is addressed to a different audience.",
@@ -63,6 +62,9 @@ function ap2Unavailable(detail, context = {}) {
     }
   );
 }
+function sha256(data) {
+  return createHash("sha256").update(data).digest();
+}
 
 // src/authorization/ap2/profile.ts
 var REQUIRED_PROFILE_CLAIMS = [
@@ -73,20 +75,25 @@ var REQUIRED_PROFILE_CLAIMS = [
   "currency",
   "payment_method"
 ];
-async function computeInputHash(input) {
+function computeInputHash(input) {
   const canonical = canonicalize(input ?? {});
   if (canonical === void 0) {
-    throw new TypeError("resource input is not canonicalizable JSON");
+    throw new CommerceError("INTERNAL_ERROR", "resource input is not canonicalizable JSON");
   }
-  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
-  return Buffer.from(digest).toString("base64url");
+  return sha256(canonical).toString("base64url");
 }
-function asRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+var EVM_ADDRESS = /^0x[0-9a-f]{40}$/i;
+function sameCoordinate(declared, expected) {
+  if (typeof declared === "string" && expected !== void 0) {
+    if (EVM_ADDRESS.test(declared) && EVM_ADDRESS.test(expected)) {
+      return declared.toLowerCase() === expected.toLowerCase();
+    }
+  }
+  return declared === expected;
 }
 async function bindMandateToPurchase(mandate, context, errorContext) {
-  const profile = asRecord(mandate.checkoutClaims["agent_commerce"]);
-  if (profile === void 0) throw ap2Rejected("purchase_mismatch", errorContext);
+  const profile = mandate.checkoutClaims["agent_commerce"];
+  if (!isRecord(profile)) throw ap2Rejected("purchase_mismatch", errorContext);
   for (const claim of REQUIRED_PROFILE_CLAIMS) {
     const value = profile[claim];
     if (typeof value !== "string" || value.length === 0) {
@@ -94,7 +101,7 @@ async function bindMandateToPurchase(mandate, context, errorContext) {
     }
   }
   const requirement = context.requirement;
-  const expectedInputHash = await computeInputHash(context.input);
+  const expectedInputHash = computeInputHash(context.input);
   const mustMatch = [
     ["profile", AP2_CHECKOUT_PROFILE],
     ["resource_id", context.resourceId],
@@ -115,14 +122,8 @@ async function bindMandateToPurchase(mandate, context, errorContext) {
   ]) {
     const declared = profile[claim];
     if (declared === void 0 && expected === void 0) continue;
-    if (declared !== expected) throw ap2Rejected("purchase_mismatch", errorContext);
+    if (!sameCoordinate(declared, expected)) throw ap2Rejected("purchase_mismatch", errorContext);
   }
-  return {
-    resourceId: profile["resource_id"],
-    amount: profile["amount"],
-    currency: profile["currency"],
-    paymentMethod: profile["payment_method"]
-  };
 }
 
 // src/authorization/ap2/checkout-signer.ts
@@ -184,7 +185,7 @@ async function createCheckoutJwt(options) {
   const agentCommerce = {
     profile: AP2_CHECKOUT_PROFILE,
     resource_id: resourceId,
-    input_hash: await computeInputHash(options.input),
+    input_hash: computeInputHash(options.input),
     amount,
     currency,
     payment_method: paymentMethod,
@@ -209,8 +210,7 @@ var AP2_CAPABILITIES = [
   "replay-defence"
 ];
 var AP2_UNSUPPORTED = [
-  // Mandate kinds. Open mandates carry spending constraints nothing here
-  // evaluates, so accepting one would tell a buyer their limits were checked.
+  // Mandate kinds. Open mandates are refused: see AP2_CHECKOUT_MANDATE_VCT
   "autonomous mode",
   "open checkout mandates (mandate.checkout.open.1)",
   "intent mandates",
@@ -226,7 +226,6 @@ var AP2_UNSUPPORTED = [
   "digest algorithms other than sha-256",
   // Roles this gateway does not play
   "mandate issuance",
-  "merchant checkout JWT issuance",
   "AP2 over the ACP checkout adapter"
 ];
 function buildAp2Descriptor(implementationVersion) {
@@ -277,17 +276,17 @@ function createAp2ReplayStore(options) {
   const reserveTx = db.transaction((request) => {
     const at = new Date(now()).toISOString();
     const existing = selectByReference.get(request.reference);
-    if (existing !== void 0) {
-      if (existing.state !== "released") {
-        return { kind: "replayed", state: existing.state };
-      }
-      reReserve.run({ reference: request.reference, request_id: request.requestId, at });
-      return { kind: "reserved" };
+    if (existing !== void 0 && existing.state !== "released") {
+      return { kind: "replayed", state: existing.state };
     }
     const sameCheckout = selectLiveByJti.get(request.checkoutJti, request.reference);
     if (sameCheckout !== void 0) {
       return { kind: "replayed", state: sameCheckout.state };
     }
+    if (existing !== void 0) {
+      reReserve.run({ reference: request.reference, request_id: request.requestId, at });
+      return { kind: "reserved" };
+    }
     insert.run({
       reference: request.reference,
       checkout_jti: request.checkoutJti,
@@ -350,16 +349,6 @@ function migrate(db) {
   });
   apply();
 }
-function decodeSegment(jwt, index) {
-  const segment = jwt.split(".")[index];
-  if (segment === void 0) return void 0;
-  try {
-    const parsed = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
-    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
-  } catch {
-    return void 0;
-  }
-}
 async function verifyCheckoutJwt(mandateClaims, deps, context) {
   const compact = mandateClaims["checkout_jwt"];
   const expectedHash = mandateClaims["checkout_hash"];
@@ -369,17 +358,16 @@ async function verifyCheckoutJwt(mandateClaims, deps, context) {
   if (typeof expectedHash !== "string" || expectedHash.length === 0) {
     throw ap2Rejected("invalid_claims", context);
   }
-  await requireMatchingHash(compact, expectedHash, context);
-  const header = decodeSegment(compact, 0);
-  const unverifiedPayload = decodeSegment(compact, 1);
-  if (header === void 0 || unverifiedPayload === void 0) {
-    throw ap2Rejected("checkout_binding_failed", context);
+  requireMatchingHash(compact, expectedHash, context);
+  let header;
+  let unverifiedPayload;
+  try {
+    header = decodeProtectedHeader(compact);
+    unverifiedPayload = decodeJwt(compact);
+  } catch (cause) {
+    throw ap2Rejected("checkout_binding_failed", { ...context, cause });
   }
-  const { issuer, key } = await deps.trust.resolve(
-    unverifiedPayload["iss"],
-    header["kid"],
-    context
-  );
+  const { issuer, key } = await deps.trust.resolve(unverifiedPayload.iss, header.kid, context);
   const options = {
     algorithms: [AP2_SIGNING_ALGORITHM],
     issuer: issuer.issuer,
@@ -407,20 +395,15 @@ async function verifyCheckoutJwt(mandateClaims, deps, context) {
   if (iat > nowSeconds + deps.clockSkewSeconds) throw ap2Rejected("expired", context);
   return { issuer: issuer.issuer, jwtId: jti, claims };
 }
-async function requireMatchingHash(compact, expected, context) {
-  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(compact));
-  const actual = Buffer.from(digest).toString("base64url");
+function requireMatchingHash(compact, expected, context) {
+  const actual = sha256(compact).toString("base64url");
   if (actual !== expected) throw ap2Rejected("checkout_binding_failed", context);
 }
-async function hasher(data, algorithm) {
+function hasher(data, algorithm) {
   if (algorithm.toLowerCase() !== AP2_DIGEST_ALGORITHM) {
-    throw new Error(`unsupported digest algorithm ${algorithm}`);
+    throw ap2Rejected("malformed_presentation");
   }
-  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
-  return new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
-}
-function asRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+  return sha256(typeof data === "string" ? data : new Uint8Array(data));
 }
 async function verifyMandate(presentation, deps, context) {
   let decoded;
@@ -434,26 +417,25 @@ async function verifyMandate(presentation, deps, context) {
   if (decoded.kbJwt !== void 0) {
     throw ap2Rejected("unsupported_mandate_type", context);
   }
-  const rawPayload = asRecord2(decoded.jwt.payload);
-  const header = asRecord2(decoded.jwt.header);
-  if (rawPayload === void 0 || header === void 0) {
+  const rawPayload = decoded.jwt.payload;
+  const header = decoded.jwt.header;
+  if (!isRecord(rawPayload) || !isRecord(header)) {
     throw ap2Rejected("malformed_presentation", context);
   }
   const { issuer, key } = await deps.trust.resolve(rawPayload["iss"], header["kid"], context);
   const options = {
-    // Redundant today (the key is EC, so jose already refuses `alg: none` and
-    // a forged HMAC) and kept for the day this resolves a key set instead of
-    // one key, where the header would get to pick
+    // Redundant with one resolved EC key, which already refuses `alg: none` and
+    // a forged HMAC. It stops the header picking the algorithm if a key set is
+    // ever resolved instead.
     algorithms: [AP2_SIGNING_ALGORITHM],
-    // Also redundant, and for the same reason: the key was resolved *from*
-    // `iss` against the configured allowlist, so nothing reaching here can
-    // carry a different one. It backstops a future resolver that matches on
-    // something else. `audience` below is not redundant - `aud` is the
-    // presenter's claim, checked against what the operator configured.
+    // Also redundant, since the key was resolved *from* `iss`, and kept as a
+    // backstop for a resolver that matches on something else. `audience` is
+    // not redundant: `aud` is the presenter's claim, checked against the
+    // configured value.
     issuer: issuer.issuer,
     audience: issuer.audience,
     clockTolerance: deps.clockSkewSeconds,
-    // Injected clock, not jose's `Date.now()`, so expiry tests are tests
+    // Injected clock, not jose's `Date.now()`, so expiry is testable
     currentDate: deps.clock.now()
   };
   let verifiedPayload;
@@ -536,9 +518,8 @@ function createTrustStore(issuers) {
 }
 
 // src/authorization/ap2/verifier.ts
-async function mandateReference(signedToken) {
-  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(signedToken));
-  return `sha256:${Buffer.from(digest).toString("base64url")}`;
+function mandateReference(signedToken) {
+  return `sha256:${sha256(signedToken).toString("base64url")}`;
 }
 function createAp2MandateVerifier(options) {
   const mandateTrust = createTrustStore(options.config.trust.mandateIssuers);
@@ -556,12 +537,11 @@ function createAp2MandateVerifier(options) {
         context
       );
       return {
-        reference: await mandateReference(mandate.signedToken),
+        reference: mandateReference(mandate.signedToken),
         mandateIssuer: mandate.issuer,
         checkoutIssuer: checkout.issuer,
         checkoutJwtId: checkout.jwtId,
-        checkoutClaims: checkout.claims,
-        mandateClaims: mandate.claims
+        checkoutClaims: checkout.claims
       };
     },
     trustedIssuers() {
@@ -608,6 +588,8 @@ function createAp2AuthorizationProvider(options) {
       status: "verified",
       method: "ap2",
       reference: mandate.reference,
+      // The reservation handle is the reference itself, so the two can never
+      // name different mandates
       reservationId: mandate.reference,
       // Opaque identifiers an operator can reconcile with. Never a claim from
       // the mandate: those carry the buyer's purchase and their personal data.
@@ -643,14 +625,18 @@ function createAp2AuthorizationProvider(options) {
     },
     async health() {
       const startedAt = clock.monotonicMs();
-      const trusted = verifier.trustedIssuers();
       const checkedAt = clock.nowIso();
-      const durationMs = Math.round(clock.monotonicMs() - startedAt);
+      let available = true;
       try {
         replay.stateOf("health-probe");
       } catch {
+        available = false;
+      }
+      const durationMs = Math.round(clock.monotonicMs() - startedAt);
+      if (!available) {
         return { status: "fail", checkedAt, durationMs, detail: "replay-store-unavailable" };
       }
+      const trusted = verifier.trustedIssuers();
       return {
         status: "pass",
         checkedAt,