@agent-score/commerce 1.3.3 → 1.5.0

package/dist/index.mjs

@@ -330,6 +330,13 @@ function readX402PaymentHeader(request) {
 }
 
 // src/identity/a2a.ts
+var UCP_A2A_EXTENSION_URI = "https://ucp.dev/2026-04-08/specification/reference";
+function ucpA2AExtension(capabilities = {}) {
+  return {
+    uri: UCP_A2A_EXTENSION_URI,
+    params: { capabilities }
+  };
+}
 var PROTOCOL_VERSION = "1.0";
 var CARD_VERSION = 1;
 function buildA2AAgentCard(input) {
@@ -361,17 +368,62 @@ function buildA2AAgentCard(input) {
   if (input.description !== void 0) card.description = input.description;
   if (input.url !== void 0) card.url = input.url;
   if (input.capabilities !== void 0) card.capabilities = input.capabilities;
+  if (input.extensions && input.extensions.length > 0) card.extensions = input.extensions;
   if (input.extras !== void 0) card.extras = input.extras;
   return card;
 }
 
 // src/identity/ucp.ts
+function ucpSigningKeyFromJWK(jwk) {
+  if (!jwk || typeof jwk !== "object") {
+    throw new Error(`ucpSigningKeyFromJWK expected a non-null object; got ${typeof jwk}.`);
+  }
+  if (typeof jwk.kid !== "string" || !jwk.kid) {
+    throw new Error("ucpSigningKeyFromJWK: JWK missing required field `kid` (or non-string).");
+  }
+  if (typeof jwk.kty !== "string" || !jwk.kty) {
+    throw new Error("ucpSigningKeyFromJWK: JWK missing required field `kty` (or non-string).");
+  }
+  if (jwk.kty !== "OKP" && jwk.kty !== "EC" && jwk.kty !== "RSA") {
+    throw new Error(
+      `ucpSigningKeyFromJWK: kty=${JSON.stringify(jwk.kty)} is not a supported asymmetric key type (expected OKP, EC, or RSA). Symmetric \`oct\` keys are rejected because they cannot publicly verify a JWS in the trust-mode UCP flow.`
+    );
+  }
+  if ((jwk.kty === "EC" || jwk.kty === "OKP") && (typeof jwk.crv !== "string" || !jwk.crv)) {
+    throw new Error(`ucpSigningKeyFromJWK: kty=${jwk.kty} requires a non-empty \`crv\` field (e.g., "P-256" for EC, "Ed25519" for OKP).`);
+  }
+  return jwk;
+}
 var DEFAULT_VERSION = "2026-04-17";
-var SPEC_URL = "https://ucp.dev/";
-var AGENTSCORE_CAPABILITY_NAME = "agentscore-identity";
+var AGENTSCORE_CAPABILITY_NAME = "sh.agentscore.identity";
 var AGENTSCORE_CAPABILITY_VERSION = "1";
+var AGENTSCORE_DEFAULT_SPEC_URL = "https://agentscore.sh/specification/identity";
+var AGENTSCORE_DEFAULT_SCHEMA_URL = "https://agentscore.sh/schemas/ucp/sh-agentscore-identity-v1.json";
+var AGENTSCORE_EXTENDS = ["dev.ucp.shopping.checkout", "dev.ucp.shopping.cart"];
+var RESERVED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "ucp",
+  "signing_keys",
+  "signature",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+var RESERVED_UCP_FIELDS = /* @__PURE__ */ new Set([
+  "version",
+  "name",
+  "services",
+  "capabilities",
+  "payment_handlers",
+  "supported_versions",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
 function buildUCPProfile(input) {
-  const baseCapabilities = [...input.capabilities ?? []];
+  const capabilities = {};
+  for (const [name, bindings] of Object.entries(input.capabilities ?? {})) {
+    capabilities[name] = [...bindings];
+  }
   if (input.data) {
     const operatorId = input.data.resolved_operator;
     if (operatorId) {
@@ -379,36 +431,332 @@ function buildUCPProfile(input) {
       const accountVerification = input.data.account_verification;
       const claims = {
         operator_id: operatorId,
-        kyc_level: accountVerification?.kyc_level ?? operatorVerification?.level ?? "none",
+        kyc_level: accountVerification?.kyc_level || operatorVerification?.level || "none",
         sanctions_clear: accountVerification?.sanctions_clear === true,
-        age_bracket: accountVerification?.age_bracket ?? "unknown",
-        jurisdiction: accountVerification?.jurisdiction ?? "",
-        verified_at: accountVerification?.verified_at ?? operatorVerification?.verified_at ?? null,
+        age_bracket: accountVerification?.age_bracket || "unknown",
+        jurisdiction: accountVerification?.jurisdiction || "",
+        verified_at: accountVerification?.verified_at || operatorVerification?.verified_at || null,
         verify_url: input.data.verify_url ?? null,
         issuer: "https://agentscore.sh"
       };
-      baseCapabilities.push({
-        name: AGENTSCORE_CAPABILITY_NAME,
+      const agentscoreBinding = {
         version: AGENTSCORE_CAPABILITY_VERSION,
-        schema: input.agentscoreSchemaUrl ?? "https://agentscore.sh/schemas/ucp/agentscore-identity.v1.json",
+        spec: input.agentscore_spec_url ?? AGENTSCORE_DEFAULT_SPEC_URL,
+        schema: input.agentscore_schema_url ?? AGENTSCORE_DEFAULT_SCHEMA_URL,
+        extends: AGENTSCORE_EXTENDS,
+        // `claims` is our vendor extra on the binding; allowed per spec via the
+        // `[k: string]: unknown` index signature on UCPCapabilityBinding.
         claims
-      });
+      };
+      const existing = capabilities[AGENTSCORE_CAPABILITY_NAME];
+      if (existing) existing.push(agentscoreBinding);
+      else capabilities[AGENTSCORE_CAPABILITY_NAME] = [agentscoreBinding];
     }
   }
-  const profile = {
+  const ucp = {
     version: input.version ?? DEFAULT_VERSION,
-    spec: SPEC_URL,
-    services: input.services,
-    capabilities: baseCapabilities,
-    payment_handlers: input.payment_handlers ?? [],
+    services: input.services ?? {},
+    capabilities,
+    payment_handlers: input.payment_handlers ?? {}
+  };
+  if (input.name !== void 0) ucp.name = input.name;
+  if (input.supported_versions !== void 0) ucp.supported_versions = input.supported_versions;
+  if (input.ucp_extras) {
+    for (const k of Object.keys(input.ucp_extras)) {
+      if (RESERVED_UCP_FIELDS.has(k)) {
+        throw new Error(`buildUCPProfile: ucp_extras key "${k}" collides with a reserved \`ucp\` field; rejected.`);
+      }
+    }
+    Object.assign(ucp, input.ucp_extras);
+  }
+  const profile = {
+    ucp,
     signing_keys: input.signing_keys
   };
-  if (input.name !== void 0) profile.name = input.name;
-  if (input.extras) Object.assign(profile, input.extras);
+  if (input.extras) {
+    for (const k of Object.keys(input.extras)) {
+      if (RESERVED_TOP_LEVEL.has(k)) {
+        throw new Error(`buildUCPProfile: extras key "${k}" collides with a reserved profile field; rejected.`);
+      }
+    }
+    Object.assign(profile, input.extras);
+  }
   return profile;
 }
 var AGENTSCORE_UCP_CAPABILITY = AGENTSCORE_CAPABILITY_NAME;
 
+// src/identity/ucp-jwks.ts
+var JOSE_INSTALL_HINT = "Install the optional peer dependency: `npm install jose@^6` (or `bun add jose`). Tested against jose v6.x.";
+var ALLOWED_ALGS = ["EdDSA", "ES256"];
+var PROFILE_TYP = "agentscore-profile+jws";
+var UCPVerificationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "UCPVerificationError";
+  }
+  code;
+};
+async function loadJose() {
+  try {
+    return await import("jose");
+  } catch (err) {
+    throw new Error(
+      `UCP signing requires the \`jose\` library, which is an optional peer dependency. ${JOSE_INSTALL_HINT}
+Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function canonicalizeProfile(profile) {
+  const stripped = { ...profile };
+  delete stripped.signature;
+  return stableStringify(stripped);
+}
+function stableStringify(value) {
+  if (value === void 0) {
+    throw new Error(
+      "stableStringify: undefined values are not allowed in canonicalized JSON. Object fields with no value must be omitted."
+    );
+  }
+  if (typeof value === "function" || typeof value === "symbol") {
+    throw new Error(`stableStringify: ${typeof value} values are not allowed in canonicalized JSON.`);
+  }
+  if (typeof value === "bigint") {
+    throw new Error("stableStringify: BigInt values are not allowed; use a decimal string.");
+  }
+  if (value instanceof Date) {
+    throw new Error(
+      "stableStringify: Date instances are not allowed; serialize to an ISO string before passing."
+    );
+  }
+  if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
+    throw new Error(
+      `stableStringify: ${value.constructor.name} values are not allowed; convert to a plain object/array first.`
+    );
+  }
+  if (ArrayBuffer.isView(value)) {
+    throw new Error("stableStringify: typed arrays are not allowed; convert to a plain array first.");
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `UCP profile canonicalization rejects non-finite Number ${value}. Use a decimal string for any value that may be NaN/Infinity.`
+      );
+    }
+    if (!Number.isInteger(value)) {
+      throw new Error(
+        `UCP profile canonicalization rejects non-integer Number ${value}. Use a decimal string (e.g. "9.99") for monetary or fractional fields to preserve cross-language byte-parity.`
+      );
+    }
+    if (!Number.isSafeInteger(value)) {
+      throw new Error(
+        `stableStringify: integer ${value} exceeds Number.MAX_SAFE_INTEGER. For values >2^53, use a decimal string to preserve cross-language byte parity.`
+      );
+    }
+  }
+  if (typeof value === "string") {
+    if (value.includes("\u2028") || value.includes("\u2029")) {
+      throw new Error(
+        "stableStringify: strings containing U+2028 (LINE SEPARATOR) or U+2029 (PARAGRAPH SEPARATOR) are not allowed; cross-language byte parity requires neither be present (Node JSON.stringify on older V8 escapes them; Python json.dumps with ensure_ascii=False does not)."
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).sort((a, b) => {
+    const aPoints = [...a].map((c) => c.codePointAt(0));
+    const bPoints = [...b].map((c) => c.codePointAt(0));
+    const len = Math.min(aPoints.length, bPoints.length);
+    for (let i = 0; i < len; i += 1) {
+      if (aPoints[i] !== bPoints[i]) return aPoints[i] - bPoints[i];
+    }
+    return aPoints.length - bPoints.length;
+  });
+  for (const k of keys) {
+    if (k.includes("\u2028") || k.includes("\u2029")) {
+      throw new Error(
+        "stableStringify: object keys containing U+2028 (LINE SEPARATOR) or U+2029 (PARAGRAPH SEPARATOR) are not allowed; cross-language byte parity (Node JSON.stringify on older V8 escapes them; Python json.dumps with ensure_ascii=False does not)."
+      );
+    }
+  }
+  const pairs = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+  return `{${pairs.join(",")}}`;
+}
+async function generateUCPSigningKey(opts) {
+  const jose = await loadJose();
+  const alg = opts.alg ?? "EdDSA";
+  const { privateKey, publicKey } = await jose.generateKeyPair(alg, { extractable: true });
+  const exportedJwk = await jose.exportJWK(publicKey);
+  const publicJWK = {
+    kid: opts.kid,
+    alg,
+    use: "sig",
+    ...exportedJwk
+  };
+  return { privateKey, publicJWK };
+}
+async function signUCPProfile(profile, opts) {
+  const jose = await loadJose();
+  const alg = opts.alg ?? "EdDSA";
+  if (!ALLOWED_ALGS.includes(alg)) {
+    throw new Error(
+      `signUCPProfile: alg ${JSON.stringify(opts.alg)} is not in the supported set [${ALLOWED_ALGS.join(", ")}].`
+    );
+  }
+  if (typeof opts.kid !== "string" || !opts.kid) {
+    throw new Error("signUCPProfile: opts.kid must be a non-empty string.");
+  }
+  const kids = (profile.signing_keys ?? []).map((k) => k.kid);
+  if (!kids.includes(opts.kid)) {
+    throw new Error(
+      `signUCPProfile: kid ${JSON.stringify(opts.kid)} is not present in profile.signing_keys[] (declared kids: ${JSON.stringify(kids)}). Verifiers will not find the key.`
+    );
+  }
+  const canonicalBody = canonicalizeProfile(profile);
+  const payloadBytes = new TextEncoder().encode(canonicalBody);
+  const signature = await new jose.CompactSign(payloadBytes).setProtectedHeader({ alg, kid: opts.kid, typ: PROFILE_TYP }).sign(opts.signingKey);
+  return { ...profile, signature };
+}
+async function verifyUCPProfile(profile, jwks) {
+  if (profile === null || typeof profile !== "object" || Array.isArray(profile)) {
+    throw new UCPVerificationError(
+      "no_signature",
+      `UCP profile must be a JSON object; got ${profile === null ? "null" : Array.isArray(profile) ? "array" : typeof profile}.`
+    );
+  }
+  const jose = await loadJose();
+  if (!jwks || typeof jwks !== "object" || !Array.isArray(jwks.keys)) {
+    throw new UCPVerificationError(
+      "malformed_jwks",
+      `UCP verifier expected JWKS shape { keys: [...] }; got ${jwks === null ? "null" : typeof jwks === "object" ? "object without keys[] array" : typeof jwks}.`
+    );
+  }
+  const stripped = { ...profile };
+  const sig = stripped.signature;
+  delete stripped.signature;
+  if (typeof sig !== "string" || !sig) {
+    throw new UCPVerificationError(
+      "no_signature",
+      `UCP profile signature must be a non-empty string; got ${sig === void 0 ? "undefined" : typeof sig}.`
+    );
+  }
+  let header;
+  try {
+    const protectedB64 = sig.split(".")[0];
+    if (!protectedB64) throw new Error("JWS protected header segment is empty.");
+    const headerJson = new TextDecoder().decode(jose.base64url.decode(protectedB64));
+    const parsed = JSON.parse(headerJson);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("JWS protected header is not a JSON object.");
+    }
+    header = parsed;
+  } catch (err) {
+    throw new UCPVerificationError(
+      "malformed_jws",
+      `JWS protected header is not valid base64url-encoded JSON: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (header.typ !== PROFILE_TYP) {
+    throw new UCPVerificationError("wrong_typ", `UCP signature typ must be "${PROFILE_TYP}"; got ${String(header.typ)}.`);
+  }
+  if (!ALLOWED_ALGS.includes(header.alg)) {
+    throw new UCPVerificationError("unsupported_alg", `UCP signing alg must be one of ${ALLOWED_ALGS.join(", ")}; got ${String(header.alg)}.`);
+  }
+  if (typeof header.kid !== "string" || !header.kid) {
+    throw new UCPVerificationError(
+      "missing_kid",
+      `UCP signature header kid must be a non-empty string; got ${header.kid === void 0 ? "undefined" : typeof header.kid}.`
+    );
+  }
+  if ("crit" in header) {
+    const crit = header.crit;
+    if (!Array.isArray(crit) || crit.length === 0 || !crit.every((c) => typeof c === "string")) {
+      throw new UCPVerificationError(
+        "malformed_jws",
+        `JWS protected header crit must be a non-empty array of strings; got ${JSON.stringify(crit)}.`
+      );
+    }
+    throw new UCPVerificationError(
+      "unrecognized_critical_header",
+      `JWS protected header advertises unrecognized crit headers: ${JSON.stringify(crit)}.`
+    );
+  }
+  let signedPayload;
+  try {
+    const verified = await jose.compactVerify(
+      sig,
+      async (h) => {
+        const kid = h.kid;
+        if (typeof kid !== "string" || !kid) {
+          throw new UCPVerificationError(
+            "missing_kid",
+            `UCP signature header kid must be a non-empty string; got ${kid === void 0 ? "undefined" : typeof kid}.`
+          );
+        }
+        const matches = jwks.keys.filter(
+          (k) => k != null && typeof k === "object" && k.kid === kid
+        );
+        if (matches.length === 0) throw new UCPVerificationError("kid_not_found", `No JWK in JWKS matching kid=${JSON.stringify(kid)}.`);
+        if (matches.length > 1) throw new UCPVerificationError("duplicate_kid", `JWKS contains ${matches.length} keys with kid=${JSON.stringify(kid)}; expected exactly one.`);
+        const matchedKey = matches[0];
+        if (matchedKey.use != null && matchedKey.use !== "sig") {
+          throw new UCPVerificationError("unusable_key", `JWK with kid=${kid} has use=${JSON.stringify(matchedKey.use)}; expected "sig".`);
+        }
+        if (matchedKey.alg != null && matchedKey.alg !== h.alg) {
+          throw new UCPVerificationError(
+            "unusable_key",
+            `JWK alg ${JSON.stringify(matchedKey.alg)} does not match JWS header alg ${JSON.stringify(h.alg)}.`
+          );
+        }
+        return jose.importJWK(matches[0], h.alg);
+      }
+    );
+    signedPayload = verified.payload;
+  } catch (err) {
+    if (err instanceof UCPVerificationError) throw err;
+    if (err instanceof Error && err.name === "JOSEAlgNotAllowed") {
+      throw new UCPVerificationError("unsupported_alg", `UCP signing alg not allowed: ${err.message}`);
+    }
+    if (err instanceof Error && err.name === "JWSSignatureVerificationFailed") {
+      throw new UCPVerificationError("signature_invalid", `UCP signature verification failed: ${err.message}`);
+    }
+    if (err instanceof Error && err.name === "JWSInvalid") {
+      throw new UCPVerificationError("malformed_jws", `Malformed JWS: ${err.message}`);
+    }
+    if (err instanceof Error && err.name === "JOSENotSupported") {
+      throw new UCPVerificationError("unrecognized_critical_header", `UCP signing rejected unrecognized critical header: ${err.message}`);
+    }
+    throw err;
+  }
+  let canonicalBody;
+  try {
+    canonicalBody = canonicalizeProfile(stripped);
+  } catch (err) {
+    throw new UCPVerificationError(
+      "body_mismatch",
+      `Failed to canonicalize received profile for verification: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const expectedPayload = new TextEncoder().encode(canonicalBody);
+  if (!constantTimeEqual(signedPayload, expectedPayload)) {
+    throw new UCPVerificationError("body_mismatch", "UCP profile body does not match the signed payload (tampered or non-canonical).");
+  }
+  return true;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+function buildJWKSResponse(keys) {
+  return { keys };
+}
+
 // src/identity/policy.ts
 function policyToGateOptions(policy, base) {
   if (!policy || !policy.enforcement) return null;
@@ -458,21 +806,29 @@ function shippingStateAllowed(state, country, policy) {
 export {
   AGENTSCORE_UCP_CAPABILITY,
   FIXABLE_DENIAL_REASONS,
+  UCPVerificationError,
+  UCP_A2A_EXTENSION_URI,
   buildA2AAgentCard,
   buildAgentMemoryHint,
   buildContactSupportNextSteps,
+  buildJWKSResponse,
   buildSignerMismatchBody,
   buildUCPProfile,
   denialReasonStatus,
   denialReasonToBody,
   extractPaymentSigner,
   extractPaymentSignerAddress,
+  generateUCPSigningKey,
   isFixableDenial,
   policyToGateOptions,
   readX402PaymentHeader,
   runGateWithEnforcement,
   shippingCountryAllowed,
   shippingStateAllowed,
-  verificationAgentInstructions
+  signUCPProfile,
+  ucpA2AExtension,
+  ucpSigningKeyFromJWK,
+  verificationAgentInstructions,
+  verifyUCPProfile
 };
 //# sourceMappingURL=index.mjs.map