@agent-score/commerce 1.3.2 → 1.5.0

package/dist/index.d.ts

@@ -30,6 +30,30 @@ interface A2AAgentCardCapabilities {
     /** Free-form skill tags — `["product-purchase", "regulated-commerce", ...]`. */
     skills?: string[];
 }
+/** Per A2A v1.0: an entry in the card's top-level `extensions` array. UCP support
+ *  is declared this way (UCP §A2A binding requires `https://ucp.dev/2026-04-08/specification/reference`). */
+interface A2AAgentCardExtension {
+    /** Canonical extension URI — for UCP, `https://ucp.dev/2026-04-08/specification/reference`. */
+    uri: string;
+    /** Extension-specific params. UCP places `{ capabilities: { "<reverse-dns>": [{ version: "..." }, ...] } }` here. */
+    params?: Record<string, unknown>;
+}
+/** Canonical UCP A2A extension URI — verifiers look for this exact URI in `extensions[]`
+ *  to detect UCP support on the agent card. Pinned to the 2026-04-08 spec snapshot. */
+declare const UCP_A2A_EXTENSION_URI = "https://ucp.dev/2026-04-08/specification/reference";
+/** Build the canonical UCP entry for an A2A agent card's `extensions[]` array.
+ *
+ *  Per UCP §A2A binding: "Businesses supporting UCP must advertise the extension and
+ *  any optional capabilities in their A2A Agent Card to allow platforms to activate
+ *  the extension." Pass the `capabilities` map keyed by reverse-DNS service/capability
+ *  name (e.g. `dev.ucp.shopping.checkout`), each value a list of `{ version }` records.
+ *  Pass `{}` (or omit) when you serve UCP at the discovery layer but have no formal
+ *  capability bindings yet — vendors that haven't implemented checkout/cart/etc. should
+ *  declare the extension URI without claiming capabilities they don't service.
+ */
+declare function ucpA2AExtension(capabilities?: Record<string, Array<{
+    version: string;
+}>>): A2AAgentCardExtension;
 interface A2AAgentCardIdentity {
     /** Issuer of the identity claims — always `"https://agentscore.sh"` for the AgentScore-issued card. */
     issuer: string;
@@ -61,6 +85,8 @@ interface A2AAgentCard {
     url?: string;
     /** Agent capabilities — endpoints + skills. */
     capabilities?: A2AAgentCardCapabilities;
+    /** A2A v1.0 extensions array. Use `ucpA2AExtension()` to add the UCP entry. */
+    extensions?: A2AAgentCardExtension[];
     /** AgentScore identity claims. Empty `null` when no identity is available (pre-KYC). */
     identity: A2AAgentCardIdentity | null;
     /** Vendor-specific extras merged at the top level. */
@@ -75,6 +101,9 @@ interface BuildA2AAgentCardInput {
     url?: string;
     /** Capabilities — endpoints exposed + skill tags. */
     capabilities?: A2AAgentCardCapabilities;
+    /** A2A v1.0 extensions to declare on the card. Build the UCP entry with
+     *  `ucpA2AExtension()`. Other A2A extensions can be added the same way. */
+    extensions?: A2AAgentCardExtension[];
     /** AgentScore assess data — what `getAgentScoreData(c)` returns or what `assess()` returned directly.
      *  Pass `null` to emit a card with no identity claims (publishable but unverified). */
     data?: AgentScoreData | null;
@@ -120,133 +149,353 @@ declare function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard;
 /**
  * UCP (Universal Commerce Protocol) profile builder.
  *
- * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec, with
- * AgentScore identity claims attached as a capability. Returned object is the unsigned
- * profile body — the merchant signs it (or wraps it in their JWKS-backed envelope)
- * before publishing.
+ * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec.
+ * Output shape matches the spec example: top-level `{ ucp: {...}, signing_keys: [...] }`
+ * envelope, with `services` / `capabilities` / `payment_handlers` as MAPs keyed by
+ * reverse-DNS service / capability / handler name.
  *
- * Why publish: UCP is the Google-led cross-vendor standard (announced Jan 2026 at NRF
- * with Shopify, Etsy, Wayfair, Target, Walmart, Adyen, Mastercard, Stripe, Visa, Amex,
- * etc.). Every UCP-aware platform discovers a merchant via `/.well-known/ucp`, so
- * shipping this profile means AgentScore-gated merchants are discoverable through the
- * same surface every other UCP merchant uses.
+ * AgentScore identity claims layer over UCP via the `sh.agentscore.identity` capability
+ * (vendor-namespaced; UCP doesn't define KYC/sanctions/age/jurisdiction natively). The
+ * capability extends `dev.ucp.shopping.checkout` AND `dev.ucp.shopping.cart` (multi-parent,
+ * the standard pattern UCP allows for capabilities that compose multiple parents).
  *
- * Spec reference: https://ucp.dev/
+ * The unsigned profile body returned here is what merchants publish; pass it through
+ * `signUCPProfile` to attach the `agentscore-profile+jws` signature for trust-mode
+ * verifiers (vendor extension; UCP itself doesn't mandate profile-body signing).
  *
- * UCP profiles do NOT carry KYC / sanctions / age / jurisdiction claims natively —
- * identity in the UCP spec is "who signed this" (JWKS-backed). AgentScore claims layer
- * over UCP via a custom capability so consumers who care about verified-buyer identity
- * can read them; consumers who don't care just see a normal UCP profile.
+ * Spec reference: https://ucp.dev/
  */
 
+/**
+ * UCP per-element shape note: each binding interface (`UCPServiceBinding`,
+ * `UCPCapabilityBinding`, `UCPPaymentHandlerBinding`) carries the canonical UCP fields
+ * plus arbitrary vendor extras flat on the same object via `[k: string]: unknown`. The
+ * python sibling models these as dataclasses with an explicit `extras: dict` field. Both
+ * designs offer equivalent guarantees through different mechanisms.
+ */
 interface UCPSigningKey {
     /** JWK kid (key id). */
     kid: string;
-    /** JWK kty (key type) — typically `EC`, `RSA`, or `OKP`. */
+    /** JWK kty (key type) — `EC`, `RSA`, or `OKP`. */
     kty: string;
-    /** JWK alg (signing algorithm) — typically `ES256`, `RS256`, or `EdDSA`. */
+    /** JWK alg (signing algorithm) — `ES256`, `RS256`, or `EdDSA`. */
     alg?: string;
-    /** JWK use — typically `sig`. */
+    /** JWK use, typically `sig`. */
     use?: string;
     /** JWK crv (curve) for EC / OKP keys. */
     crv?: string;
     /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */
     [k: string]: unknown;
 }
-interface UCPService {
-    /** Transport binding — `rest` / `mcp` / `a2a` / `embedded`. */
-    type: string;
-    /** Service URL (or path for embedded). */
-    url?: string;
-    /** Optional version pin. */
-    version?: string;
-    /** Vendor-specific extras for the binding. */
-    [k: string]: unknown;
-}
-interface UCPCapability {
-    /** Capability name — `checkout`, `catalog`, `agentscore-identity`, etc. */
-    name: string;
-    /** URL of the JSON Schema describing this capability's payload. */
+/**
+ * Construct a UCPSigningKey from a public JWK dict (e.g. the `publicJWK` returned by
+ * `generateUCPSigningKey()`). Validates required fields and rejects symmetric keys that
+ * can't publicly verify a JWS in trust-mode UCP. Symmetric to Python's
+ * `UCPSigningKey.from_jwk(public_jwk)` classmethod.
+ */
+declare function ucpSigningKeyFromJWK(jwk: Record<string, unknown>): UCPSigningKey;
+/** Transport binding — keyed under a service name (e.g., `dev.ucp.shopping`). */
+interface UCPServiceBinding {
+    /** Spec version, YYYY-MM-DD per UCP convention. REQUIRED. */
+    version: string;
+    /** URL to human-readable specification. REQUIRED. */
+    spec: string;
+    /** Transport — `rest` / `mcp` / `a2a` / `embedded`. REQUIRED. */
+    transport: 'rest' | 'mcp' | 'a2a' | 'embedded';
+    /** Endpoint URL — required for rest/mcp; A2A points at the agent-card.json URL. */
+    endpoint?: string;
+    /** URL to JSON Schema — required for rest/mcp/embedded per spec. */
     schema?: string;
-    /** Capability version — semver or date-stamp per UCP convention. */
-    version?: string;
-    /** Vendor-specific extras for the capability. */
+    /** Optional id for entity-instance disambiguation. */
+    id?: string;
+    /** Entity-specific config. */
+    config?: Record<string, unknown>;
+    /** Vendor-specific extras. */
     [k: string]: unknown;
 }
-interface UCPPaymentHandler {
-    /** Handler name — `stripe`, `tempo`, `x402-base`, `solana`, etc. */
-    name: string;
-    /** Handler config — recipient address, profile id, etc. */
+/** Capability binding — keyed under a capability name (e.g., `dev.ucp.shopping.checkout`). */
+interface UCPCapabilityBinding {
+    /** Capability version, YYYY-MM-DD. REQUIRED. */
+    version: string;
+    /** URL to human-readable specification. REQUIRED. */
+    spec: string;
+    /** URL to JSON Schema. REQUIRED. */
+    schema: string;
+    /** Optional id for entity-instance disambiguation. */
+    id?: string;
+    /** Entity-specific config (feature flags, callback URLs, etc). */
     config?: Record<string, unknown>;
+    /** Parent capability(ies) extended — single string or array for multi-parent. */
+    extends?: string | string[];
+    /** Optional version requirements per UCP §6.5. */
+    requires?: {
+        protocol?: {
+            min: string;
+            max?: string;
+        };
+        capabilities?: Record<string, {
+            min: string;
+            max?: string;
+        }>;
+    };
+    /** Vendor-specific extras (e.g., AgentScore claims block on `sh.agentscore.identity`). */
+    [k: string]: unknown;
 }
-interface UCPProfile {
-    /** UCP spec version (date-stamped). */
+/** Payment handler binding — keyed under a handler reverse-DNS name (e.g., `com.google.pay`). */
+interface UCPPaymentHandlerBinding {
+    /** Handler instance id (short, human-readable, e.g., `gpay`, `tempo`, `x402`). REQUIRED. */
+    id: string;
+    /** Handler spec version, YYYY-MM-DD. REQUIRED. */
     version: string;
-    /** URL of the UCP spec. */
+    /** URL to handler spec. REQUIRED. */
     spec: string;
-    /** URL of this profile's JSON schema. */
-    schema?: string;
-    /** Display name of the merchant / agent surface. */
+    /** URL to handler config schema. REQUIRED. */
+    schema: string;
+    /** Available instruments — type + per-type constraints (cards, wallets, etc.). */
+    available_instruments?: Array<{
+        type: string;
+        constraints?: Record<string, unknown>;
+        [k: string]: unknown;
+    }>;
+    /** Handler config — gateway IDs, merchant IDs, public keys, etc. */
+    config?: Record<string, unknown>;
+    /** Vendor-specific extras. */
+    [k: string]: unknown;
+}
+/** UCP body — nested under the `ucp` key of the published profile. */
+interface UCPProfileBody {
+    /** UCP spec version (YYYY-MM-DD). */
+    version: string;
+    /** Display name for the merchant / agent surface. */
     name?: string;
-    /** Service bindings — REST, MCP, A2A, embedded transports. */
-    services: UCPService[];
-    /** Capabilities offered (with schema URLs). */
-    capabilities: UCPCapability[];
-    /** Payment handlers offered — typically the rails the merchant accepts. */
-    payment_handlers: UCPPaymentHandler[];
-    /** JWKS — REQUIRED by spec. The merchant signs requests with a private key whose
-     *  public counterpart is listed here. Verifiers fetch this profile, find the kid, and
-     *  validate signatures. */
+    /** Services — keyed by service name (e.g., `dev.ucp.shopping`). Each value is an
+     *  array of transport bindings (one merchant typically advertises multiple transports
+     *  under one service name). */
+    services: Record<string, UCPServiceBinding[]>;
+    /** Capabilities — keyed by capability name (e.g., `dev.ucp.shopping.checkout`). */
+    capabilities: Record<string, UCPCapabilityBinding[]>;
+    /** Payment handlers — keyed by handler reverse-DNS name (e.g., `com.google.pay`). */
+    payment_handlers: Record<string, UCPPaymentHandlerBinding[]>;
+    /** Optional `supported_versions` map linking historical version-specific profile URLs.
+     *  Pattern: `{ "2026-01-23": "https://merchant/.well-known/ucp/2026-01-23", ... }`. */
+    supported_versions?: Record<string, string>;
+    /** Vendor-specific extras inside the `ucp` envelope. */
+    [k: string]: unknown;
+}
+/** Full UCP profile body as published at `/.well-known/ucp`. Top-level shape:
+ *  `{ ucp: {...}, signing_keys: [...], signature?: "..." }`. */
+interface UCPProfile {
+    /** UCP body. ALL UCP-spec fields nest here per spec. */
+    ucp: UCPProfileBody;
+    /** JWKS — public keys at the OUTER level per UCP spec. Verifiers fetch this profile,
+     *  match the kid from a JWS / RFC 9421 signature header against this list, and validate. */
     signing_keys: UCPSigningKey[];
-    /** Vendor-specific extras at the top level. */
+    /** Set when JWS-signed via `signUCPProfile` — JWS Compact Serialization with detached
+     *  payload (header..signature; payload is the canonicalized body minus this field). */
+    signature?: string;
+    /** Top-level vendor-specific extras (outside the `ucp` envelope). */
     [k: string]: unknown;
 }
 interface BuildUCPProfileInput {
-    /** UCP spec version. Default `"2026-04-17"` (current at time of writing). */
+    /** UCP spec version. Default `'2026-04-17'`. */
     version?: string;
     /** Display name for the merchant / agent surface. */
     name?: string;
-    /** Service transport bindings. At minimum, the agent's primary REST endpoint. */
-    services: UCPService[];
-    /** Capabilities offered. AgentScore identity is auto-added as a capability when `data` is provided. */
-    capabilities?: UCPCapability[];
-    /** Payment handlers — rails the merchant accepts. */
-    payment_handlers?: UCPPaymentHandler[];
-    /** JWKS — public keys the merchant signs requests with. REQUIRED by spec. */
+    /** Services map, keyed by service name. UCP-shopping merchants typically advertise
+     *  bindings under `'dev.ucp.shopping'`. */
+    services?: Record<string, UCPServiceBinding[]>;
+    /** Capabilities map, keyed by capability name. The `sh.agentscore.identity` capability
+     *  is auto-added when `data` is provided. */
+    capabilities?: Record<string, UCPCapabilityBinding[]>;
+    /** Payment handlers map, keyed by handler reverse-DNS name. */
+    payment_handlers?: Record<string, UCPPaymentHandlerBinding[]>;
+    /** JWKS — public keys the merchant signs with. REQUIRED by spec. */
     signing_keys: UCPSigningKey[];
-    /** AgentScore assess data — adds an `agentscore-identity` capability + claims block when present. */
+    /** AgentScore assess data — adds an `sh.agentscore.identity` capability + claims
+     *  block when present. */
     data?: AgentScoreData | null;
-    /** Optional override for the AgentScore capability schema URL. */
-    agentscoreSchemaUrl?: string;
-    /** Vendor-specific extras at the top level. */
+    /** Optional override for the AgentScore capability schema URL. Field is snake_cased
+     *  for cross-language parity with the Python sibling. */
+    agentscore_schema_url?: string;
+    /** Optional override for the AgentScore capability spec URL. */
+    agentscore_spec_url?: string;
+    /** `supported_versions` map at the profile root for backwards-compat across
+     *  spec dates. Pattern: `{ "<date>": "<base>/.well-known/ucp/<date>" }`. */
+    supported_versions?: Record<string, string>;
+    /** Vendor-specific extras at the OUTER level (alongside `ucp` + `signing_keys`). */
     extras?: Record<string, unknown>;
+    /** Vendor-specific extras INSIDE the `ucp` envelope (alongside `version`, `services`, etc.). */
+    ucp_extras?: Record<string, unknown>;
 }
 /**
- * Compose a UCP profile body for `/.well-known/ucp` publication. Merges AgentScore
- * identity claims into the `capabilities` array as an `agentscore-identity` capability
- * so UCP-aware consumers can discover verified-buyer claims alongside the standard
- * UCP transport metadata.
+ * Compose a UCP profile body for `/.well-known/ucp` publication. Returns the spec-
+ * compliant shape: `{ ucp: { version, services, capabilities, payment_handlers, ... },
+ * signing_keys: [...] }`. Pass through `signUCPProfile` to attach a JWS signature for
+ * trust-mode verifiers.
+ *
+ * Auto-injects `sh.agentscore.identity` as a vendor capability extending both
+ * `dev.ucp.shopping.checkout` and `dev.ucp.shopping.cart` when `data` carries a
+ * resolved operator. Verifiers that recognize the AgentScore namespace can parse
+ * the `claims` block; vanilla UCP agents see a normal extension capability.
  *
  * Example:
  * ```ts
- * import { buildUCPProfile } from '@agent-score/commerce/identity/hono';
+ * import { buildUCPProfile } from '@agent-score/commerce';
  *
- * app.get('/.well-known/ucp', async (c) => {
- *   const data = getAgentScoreData(c);
- *   return c.json(buildUCPProfile({
- *     name: 'Example Merchant',
- *     services: [{ type: 'rest', url: 'https://agents.example.com' }],
- *     payment_handlers: [
- *       { name: 'tempo', config: { recipient: TEMPO_ADDR } },
- *       { name: 'stripe', config: { profile_id: STRIPE_PROFILE_ID } },
+ * const profile = buildUCPProfile({
+ *   name: 'Example Merchant',
+ *   services: {
+ *     'dev.ucp.shopping': [
+ *       { version: '2026-04-08', spec: 'https://ucp.dev/2026-04-08/specification/overview',
+ *         transport: 'mcp', endpoint: 'https://merchant.example/api/ucp/mcp',
+ *         schema: 'https://ucp.dev/services/shopping/openrpc.json' },
  *     ],
- *     signing_keys: [{ kid: 'merchant-2026-04', kty: 'EC', alg: 'ES256', crv: 'P-256', x: '...', y: '...' }],
- *     data,
- *   }));
+ *   },
+ *   payment_handlers: {
+ *     'sh.agentscore.payment.tempo': [{
+ *       id: 'tempo',
+ *       version: '2026-04-08',
+ *       spec: 'https://agentscore.sh/specification/payment-handlers/tempo',
+ *       schema: 'https://agentscore.sh/schemas/payment-handlers/tempo.json',
+ *       config: { recipient: TEMPO_ADDR },
+ *     }],
+ *   },
+ *   signing_keys: [signingKey],
  * });
  * ```
  */
 declare function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile;
-declare const AGENTSCORE_UCP_CAPABILITY = "agentscore-identity";
+declare const AGENTSCORE_UCP_CAPABILITY = "sh.agentscore.identity";
+
+/**
+ * UCP profile signing helpers (JWKS + JWS).
+ *
+ * UCP §6 (https://ucp.dev/latest/specification/signatures/) requires that profiles
+ * published at `/.well-known/ucp` carry a JWKS-backed signature for trust-mode clients
+ * (Google AI Mode, Gemini commerce, future ChatGPT app shells). Without a signature,
+ * trust-mode clients reject the profile.
+ *
+ * This module provides:
+ *   - `generateUCPSigningKey()` — generate an Ed25519 keypair for signing
+ *   - `signUCPProfile()` — sign a UCP profile body, returning a JWS-attached envelope
+ *   - `verifyUCPProfile()` — verify a signed profile against a JWKS
+ *   - `buildJWKSResponse()` — assemble a JWKS document for `/.well-known/jwks.json`
+ *
+ * Implementation rides on `jose` (peer-dep, optional). Merchants who don't sign their
+ * profile (development) skip this module entirely; the unsigned `buildUCPProfile()`
+ * path still works.
+ *
+ * Why Ed25519: smaller signatures (64 bytes vs 256+ for RSA), faster verification, no
+ * curve-parameter ceremony. UCP also accepts ES256 (P-256 ECDSA) — pass `alg: 'ES256'`
+ * to `signUCPProfile()` if your existing payment signing key is P-256.
+ */
+
+/** Output of `generateUCPSigningKey()`. The private key is what you sign with; the
+ *  public JWK is what you publish at `/.well-known/jwks.json` and reference in the
+ *  UCP profile's `signing_keys[]`.
+ */
+interface GeneratedUCPKey {
+    /** Private key (KeyLike, opaque) — pass to `signUCPProfile()`. Never publish. */
+    privateKey: unknown;
+    /** Public key as JWK — publish at `/.well-known/jwks.json` and inline in UCP `signing_keys[]`. */
+    publicJWK: UCPSigningKey;
+}
+/** A JWKS document — `{ keys: [...] }` per RFC 7517. Serve at `/.well-known/jwks.json`. */
+interface JWKSResponse {
+    keys: UCPSigningKey[];
+}
+/** Options for `signUCPProfile()`. */
+interface SignUCPProfileOptions {
+    /** Private signing key — opaque KeyLike from `generateUCPSigningKey()` or `importJWK()`. */
+    signingKey: unknown;
+    /** Key ID (must match a `kid` in the profile's `signing_keys[]`). */
+    kid: string;
+    /** Signing algorithm — `EdDSA` (default) or `ES256`. */
+    alg?: 'EdDSA' | 'ES256';
+}
+/** A signed UCP profile envelope. Same shape as `UCPProfile` plus the `signature` field
+ *  carrying the JWS Compact Serialization over the canonicalized profile body. */
+interface SignedUCPProfile extends UCPProfile {
+    /** JWS Compact Serialization (`<header>.<payload>.<signature>`) over the profile body
+     *  with `signature` removed and keys sorted. Verifiers reconstruct the canonical body
+     *  and validate against the JWK identified by `kid` in the JWS protected header. */
+    signature: string;
+}
+/** Discriminated error class so consumers can branch on failure mode without
+ *  parsing message strings or importing jose internals. */
+declare class UCPVerificationError extends Error {
+    readonly code: 'no_signature' | 'missing_kid' | 'kid_not_found' | 'duplicate_kid' | 'unsupported_alg' | 'wrong_typ' | 'signature_invalid' | 'body_mismatch' | 'malformed_jws' | 'malformed_jwks' | 'unrecognized_critical_header' | 'unusable_key';
+    constructor(code: 'no_signature' | 'missing_kid' | 'kid_not_found' | 'duplicate_kid' | 'unsupported_alg' | 'wrong_typ' | 'signature_invalid' | 'body_mismatch' | 'malformed_jws' | 'malformed_jwks' | 'unrecognized_critical_header' | 'unusable_key', message: string);
+}
+/**
+ * Generate a fresh Ed25519 (default) or ES256 keypair for signing UCP profiles.
+ *
+ * The `privateKey` is an opaque KeyLike — store it server-side and pass to
+ * `signUCPProfile()`. Never log or transmit the private key.
+ *
+ * The `publicJWK` is what you publish at `/.well-known/jwks.json` and inline in the
+ * UCP profile's `signing_keys[]` array.
+ *
+ * Example:
+ * ```ts
+ * import { generateUCPSigningKey } from '@agent-score/commerce';
+ *
+ * const { privateKey, publicJWK } = await generateUCPSigningKey({ kid: 'merchant-2026-05' });
+ * // Persist privateKey securely (env var, KMS, secret manager).
+ * // Publish publicJWK at /.well-known/jwks.json and reference it in your UCP profile.
+ * ```
+ */
+declare function generateUCPSigningKey(opts: {
+    /** Key ID (kid). Must be unique per key; you'll reference this in the UCP profile's `signing_keys[]`. */
+    kid: string;
+    /** Signing algorithm. Default `EdDSA`. */
+    alg?: 'EdDSA' | 'ES256';
+}): Promise<GeneratedUCPKey>;
+/**
+ * Sign a UCP profile, returning a new envelope with the JWS attached as `signature`.
+ *
+ * The signature covers the canonicalized profile body (everything except `signature`
+ * itself, with keys sorted at every level). Trust-mode UCP verifiers reconstruct the
+ * canonical body, look up the key referenced by the JWS header's `kid`, and validate.
+ *
+ * The profile's `signing_keys[]` MUST already include a JWK with the matching `kid`
+ * — otherwise verifiers can't find the public key. Add the `publicJWK` from
+ * `generateUCPSigningKey()` to your `signing_keys[]` before calling this.
+ *
+ * Example:
+ * ```ts
+ * const profile = buildUCPProfile({ ..., signing_keys: [publicJWK] });
+ * const signed = await signUCPProfile(profile, { signingKey: privateKey, kid: 'merchant-2026-05' });
+ * c.json(signed);
+ * ```
+ */
+declare function signUCPProfile(profile: UCPProfile, opts: SignUCPProfileOptions): Promise<SignedUCPProfile>;
+/**
+ * Verify a signed UCP profile against a JWKS. Returns `true` when the JWS validates
+ * against a matching key in `jwks`; throws on signature mismatch, missing key, or
+ * canonicalization drift.
+ *
+ * Round-trip helper for tests and for cross-merchant verification flows. Trust-mode
+ * UCP clients use the same algorithm.
+ *
+ * Example:
+ * ```ts
+ * const ok = await verifyUCPProfile(signedProfile, { keys: [publicJWK] });
+ * ```
+ */
+declare function verifyUCPProfile(profile: SignedUCPProfile, jwks: JWKSResponse): Promise<boolean>;
+/**
+ * Build a JWKS document for `/.well-known/jwks.json`.
+ *
+ * Example:
+ * ```ts
+ * import { buildJWKSResponse } from '@agent-score/commerce';
+ *
+ * app.get('/.well-known/jwks.json', (c) =>
+ *   c.json(buildJWKSResponse([publicJWK]))
+ * );
+ * ```
+ */
+declare function buildJWKSResponse(keys: UCPSigningKey[]): JWKSResponse;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardIdentity, AGENTSCORE_UCP_CAPABILITY, AgentScoreData, type BuildA2AAgentCardInput, type BuildUCPProfileInput, type UCPCapability, type UCPPaymentHandler, type UCPProfile, type UCPService, type UCPSigningKey, buildA2AAgentCard, buildUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardIdentity, AGENTSCORE_UCP_CAPABILITY, AgentScoreData, type BuildA2AAgentCardInput, type BuildUCPProfileInput, type GeneratedUCPKey, type JWKSResponse, type SignUCPProfileOptions, type SignedUCPProfile, type UCPCapabilityBinding, type UCPPaymentHandlerBinding, type UCPProfile, type UCPProfileBody, type UCPServiceBinding, type UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, buildA2AAgentCard, buildJWKSResponse, buildUCPProfile, generateUCPSigningKey, signUCPProfile, ucpA2AExtension, ucpSigningKeyFromJWK, verifyUCPProfile };