@agentsbloom/sdk 0.4.0 → 0.5.0

package/index.d.ts

@@ -1,217 +1,355 @@
-export type Protocol = 'WEBMCP' | 'UCP' | 'ACP' | 'AP2' | 'AGENTSBLOOM_REST';
-
-export type AgentActionHandler = (
-  params: Record<string, unknown>,
-  req: unknown,
-  res: unknown
-) => unknown | Promise<unknown>;
-
-export interface AgentAction {
-  method?: string;
-  description?: string;
-  params?: Record<string, string>;
-  handler: AgentActionHandler;
-}
-
-export interface AgentsBloomConfig {
-  apiKey?: string | null;
-  agentSecret?: string | null;
-  /**
-   * Previous shared secret, kept verify-live during AGENTSBLOOM_SECRET
-   * rotation so in-flight signed requests survive the window. Falls back
-   * to the AGENTSBLOOM_SECRET_PREVIOUS environment variable.
-   */
-  agentSecretPrevious?: string | null;
-  name?: string;
-  description?: string;
-  actions?: Record<string, AgentAction>;
-  llmsDoc?: string;
-  baseUrl?: string;
-  /**
-   * v4: when set, only requests whose Host header matches one of these
-   * values get Host-derived discovery URLs; any other Host falls back to
-   * `baseUrl`. Prevents Host-header poisoning of discovery documents.
-   */
-  allowedHosts?: string[];
-  /**
-   * v4 medium pass: string behaves as before; an ARRAY is an exact-match
-   * allow-list - matching Origins are reflected (Vary: Origin), everything
-   * else receives no Access-Control-Allow-Origin at all.
-   */
-  corsOrigin?: string | string[];
-  /** v4 medium pass (V10): body-size cap in bytes, enforced against the
-   *  received bytes as well as Content-Length (default 1 MiB). */
-  maxBodyBytes?: number;
-  /**
-   * v4 medium pass (V11): per-agent legacy-HMAC secrets keyed by
-   * X-Agent-Identifier. Checked before the shared `agentSecret` fallback.
-   */
-  agentKeys?: Record<string, string>;
-  /** v4 medium pass (V11): identifiers rejected outright before verification. */
-  revokedIdentifiers?: string[];
-  /**
-   * v4 medium pass (V12): per-action authorization. 'authenticated'
-   * requires a verified RFC/legacy signature identity even for reads.
-   */
-  actionAccess?: Record<string, 'anonymous' | 'authenticated'>;
-  /**
-   * v4 medium pass (V12): per-action identity allow-lists. Entries match
-   * exactly (`rfc:key-1`) or by prefix when ending with ':' (`legacy:`).
-   */
-  actionIdentities?: Record<string, string[]>;
-  merchantJwks?: Record<string, unknown>;
-  /**
-   * v4: RFC 9421 verification now FAILS CLOSED - one of `agentJwks` or
-   * `agentJwksUrl` must be configured for Signature-header writes to verify.
-   */
-  agentJwks?: {
-    keys: Array<Record<string, unknown>>;
-  };
-  agentJwksUrl?: string;
-  signature?: {
-    maxAgeMs?: number;
-    /** v4 medium pass (V14): require the @authority covered component. */
-    requireAuthority?: boolean;
-  };
-  ap2PublicKey?: unknown;
-  ap2?: {
-    expectedAudience?: string;
-    maxMandateLifetimeSec?: number;
-    requireJti?: boolean;
-    requestedCategories?: string[];
-    /**
-     * v4: reject self-certifying did:key mandates (anyone can mint those
-     * with an arbitrary maxBudget) and accept only mandates signed by the
-     * merchant-configured trusted key.
-     */
-    trustedIssuersOnly?: boolean;
-    /** v4 medium pass (V17): pin the currency budgets are denominated in. */
-    expectedCurrency?: string;
-  };
-  rateLimit?: {
-    max?: number;
-    windowMs?: number;
-  };
-  mcp?: {
-    /** v4: cap on concurrent MCP SSE sessions (default 100). */
-    maxSessions?: number;
-  };
-  idempotency?: {
-    ttlMs?: number;
-    /** v4 medium pass (V18): bound on cached entries (default 10,000). */
-    maxEntries?: number;
-  };
-  demoMode?: boolean;
-  disableSignatureAuth?: boolean;
-  disableHtmlInjection?: boolean;
-}
-
-export type AgentsBloomMiddleware = (
-  req: unknown,
-  res: unknown,
-  next: (error?: unknown) => void
-) => unknown;
-
-export interface TelemetryOptions {
-  otlpEndpoint?: string;
-  serviceName?: string;
-  samplingRatio?: number;
-  apiKey?: string;
-}
-
-export interface TelemetryConfig {
-  otlpEndpoint: string;
-  serviceName: string;
-  samplingRatio: number;
-}
-
-export interface Ap2VerificationResult {
-  valid: boolean;
-  /**
-   * True only when a presented mandate cryptographically verified. When a
-   * shared replay store (UPSTASH_REDIS_REST_URL/TOKEN) is configured,
-   * verification may resolve asynchronously - the return type becomes
-   * Promise<Ap2VerificationResult>; callers should await it either way.
-   */
-  verified?: boolean;
-  protocol: 'AP2';
-  reason?: string;
-  note?: string;
-  selfCertifying?: boolean;
-  mandates?: Record<string, unknown>;
-}
-
-export interface Ap2VerifyOptions {
-  trustedPublicKey?: unknown;
-  expectedAudience?: string;
-  maxMandateLifetimeSec?: number;
-  requireJti?: boolean;
-  requestedCategories?: string[];
-  /** v4: when false, self-certifying did:key issuers are rejected. */
-  allowSelfCertifying?: boolean;
-}
-
-export interface CreateAp2MandateOptions {
-  audience: string;
-  maxBudget: number;
-  currency?: string;
-  allowedCategories?: string[];
-  merchantScope?: string;
-  lifetimeSec?: number;
-  paymentMethod?: string;
-  subject?: string;
-  privateKey?: unknown;
-}
-
-export interface Ap2Mandate {
-  token: string;
-  did: string;
-  publicKey: unknown;
-  privateKey: unknown;
-}
-
-export function agentsbloom(config?: AgentsBloomConfig): AgentsBloomMiddleware;
-export function setupTelemetry(options?: TelemetryOptions): Promise<TelemetryConfig>;
-export function shutdown(): Promise<void>;
-export function resolveProtocol(req: {
-  headers?: Record<string, string | undefined>;
-  path?: string;
-  url?: string;
-}): Protocol;
-export function verifyAP2Mandates(
-  headers?: Record<string, string | undefined>,
-  body?: Record<string, unknown>,
-  publicKeyOrOptions?: unknown | Ap2VerifyOptions
-): Ap2VerificationResult | Promise<Ap2VerificationResult>;
-export function createAp2Mandate(options: CreateAp2MandateOptions): Ap2Mandate;
-export function didKeyFromEd25519PublicKey(publicKey: unknown): string;
-export function ed25519PublicKeyFromDidKey(didKey: string): unknown | null;
-export function resetAp2ReplayCache(): void;
-/**
- * Normalizes an audience/merchantScope value (URL-parsed: lowercased host,
- * trailing slashes stripped) so mandates built via new URL().href compare
- * equal to slash-free configured audiences.
- */
-export function normalizeAudience(value: string): string;
-
-export interface OutcomeReport {
-  orderRef: string;
-  status: 'paid' | 'declined' | 'refunded' | 'chargeback' | 'disputed' | 'canceled';
-  gateway?: 'stripe' | 'razorpay' | 'paddle' | 'other';
-  reason?: string | null;
-  amount?: number | null;
-  currency?: string | null;
-  identityKey?: string | null;
-  occurredAt?: string;
-}
-
-export interface OutcomeReporter {
-  report(body: OutcomeReport): Promise<{ ok: boolean; recorded: string; orderRef: string }>;
-  captureStripeOutcome(event: unknown): Promise<{ skipped: boolean } | { ok: boolean }>;
-}
-export function stripeEventToOutcome(event: unknown): OutcomeReport | null;
-export function createOutcomeReporter(options: {
-  apiKey: string;
-  collectorUrl?: string;
-  fetchImpl?: (url: string, init: object) => Promise<Response>;
+export type Protocol = 'WEBMCP' | 'UCP' | 'ACP' | 'AP2' | 'AGENTSBLOOM_REST';
+
+export type AgentActionHandler = (
+  params: Record<string, unknown>,
+  req: unknown,
+  res: unknown
+) => unknown | Promise<unknown>;
+
+export interface AgentAction {
+  method?: string;
+  description?: string;
+  params?: Record<string, string>;
+  handler: AgentActionHandler;
+}
+
+export interface AgentsBloomConfig {
+  apiKey?: string | null;
+  agentSecret?: string | null;
+  /**
+   * Previous shared secret, kept verify-live during AGENTSBLOOM_SECRET
+   * rotation so in-flight signed requests survive the window. Falls back
+   * to the AGENTSBLOOM_SECRET_PREVIOUS environment variable.
+   */
+  agentSecretPrevious?: string | null;
+  name?: string;
+  description?: string;
+  actions?: Record<string, AgentAction>;
+  llmsDoc?: string;
+  baseUrl?: string;
+  /**
+   * v4: when set, only requests whose Host header matches one of these
+   * values get Host-derived discovery URLs; any other Host falls back to
+   * `baseUrl`. Prevents Host-header poisoning of discovery documents.
+   */
+  allowedHosts?: string[];
+  /**
+   * v4 medium pass: string behaves as before; an ARRAY is an exact-match
+   * allow-list - matching Origins are reflected (Vary: Origin), everything
+   * else receives no Access-Control-Allow-Origin at all.
+   */
+  corsOrigin?: string | string[];
+  /** v4 medium pass (V10): body-size cap in bytes, enforced against the
+   *  received bytes as well as Content-Length (default 1 MiB). */
+  maxBodyBytes?: number;
+  /**
+   * v4 medium pass (V11): per-agent legacy-HMAC secrets keyed by
+   * X-Agent-Identifier. Checked before the shared `agentSecret` fallback.
+   */
+  agentKeys?: Record<string, string>;
+  /** v4 medium pass (V11): identifiers rejected outright before verification. */
+  revokedIdentifiers?: string[];
+  /**
+   * v4 medium pass (V12): per-action authorization. 'authenticated'
+   * requires a verified RFC/legacy signature identity even for reads.
+   */
+  actionAccess?: Record<string, 'anonymous' | 'authenticated'>;
+  /**
+   * v4 medium pass (V12): per-action identity allow-lists. Entries match
+   * exactly (`rfc:key-1`) or by prefix when ending with ':' (`legacy:`).
+   */
+  actionIdentities?: Record<string, string[]>;
+  merchantJwks?: Record<string, unknown>;
+  /**
+   * v4: RFC 9421 verification now FAILS CLOSED - one of `agentJwks` or
+   * `agentJwksUrl` must be configured for Signature-header writes to verify.
+   */
+  agentJwks?: {
+    keys: Array<Record<string, unknown>>;
+  };
+  agentJwksUrl?: string;
+  signature?: {
+    maxAgeMs?: number;
+    /**
+     * Require the `@authority` covered component. DEFAULTS TO TRUE.
+     *
+     * Without it, a signature captured at store A is structurally valid at
+     * store B for the same path whenever both trust the same JWKS. Set
+     * `baseUrl` (or `allowedHosts`) too: `@authority` canonicalizes the
+     * request's own Host header, so binding is only effective when the store
+     * also knows which authorities are its own.
+     */
+    requireAuthority?: boolean;
+    /**
+     * Accept the pre-0.6 (non-conformant) signature base as a fallback:
+     * lowercased `@method`, query folded into `@path`, missing covered headers
+     * canonicalized to the empty string. Off by default; enable only for a
+     * migration window.
+     */
+    acceptLegacyProfile?: boolean;
+    /**
+     * Compute `Content-Digest` from a re-serialized body when `req.rawBody` is
+     * unavailable. Off by default, because a digest over a re-serialization
+     * does not prove what the client actually sent. Prefer
+     * `express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } })`.
+     */
+    allowReserializedBody?: boolean;
+  };
+  /**
+   * Prefix for replay-cache and idempotency keys. Derived from `baseUrl` when
+   * omitted. Set it explicitly only when several distinct stores share one
+   * replay store (UPSTASH_REDIS_REST_URL).
+   */
+  cacheNamespace?: string;
+  /** Bounds the HTML-injection response buffer (default 2 MiB). */
+  htmlInjection?: {
+    maxBytes?: number;
+  };
+  ap2PublicKey?: unknown;
+  ap2?: {
+    expectedAudience?: string;
+    maxMandateLifetimeSec?: number;
+    requireJti?: boolean;
+    requestedCategories?: string[];
+    /**
+     * v4: reject self-certifying did:key mandates (anyone can mint those
+     * with an arbitrary maxBudget) and accept only mandates signed by the
+     * merchant-configured trusted key.
+     */
+    trustedIssuersOnly?: boolean;
+    /** v4 medium pass (V17): pin the currency budgets are denominated in. */
+    expectedCurrency?: string;
+    /**
+     * Reject a mandate that declares a `maxBudget` with no `currency`.
+     * DEFAULTS TO TRUE: an amount without a unit cannot be enforced, and
+     * every currency check is otherwise skipped.
+     */
+    requireCurrency?: boolean;
+    /** Tolerance in seconds for `iat`/`exp` clock drift (default 60). */
+    clockSkewSec?: number;
+    /**
+     * Require the checkout handler to return an authoritative `total` /
+     * `totalPrice`. DEFAULTS TO TRUE: without a store-computed total the
+     * mandate budget cannot be enforced at all, so checkout fails closed
+     * rather than issuing an unenforced payment link.
+     */
+    requireHandlerTotal?: boolean;
+    /**
+     * Include the detailed internal rejection reason in AP2 error responses.
+     * Off by default: reasons can reveal the store's expected audience and
+     * currency, which is exactly what a forged mandate needs.
+     */
+    exposeReasons?: boolean;
+    /** Allow a cart-bound mandate through when the session cart cannot be verified. */
+    allowUnverifiedCartMandates?: boolean;
+    /** AP2 Cart Mandate binding: derive expected cart hash from the session request. */
+    computeCartHash?: (req: unknown) => string | null;
+  };
+  rateLimit?: {
+    max?: number;
+    windowMs?: number;
+  };
+  mcp?: {
+    /** v4: cap on concurrent MCP SSE sessions (default 100). */
+    maxSessions?: number;
+  };
+  idempotency?: {
+    ttlMs?: number;
+    /** v4 medium pass (V18): bound on cached entries (default 10,000). */
+    maxEntries?: number;
+  };
+  demoMode?: boolean;
+  disableSignatureAuth?: boolean;
+  disableHtmlInjection?: boolean;
+}
+
+export type AgentsBloomMiddleware = (
+  req: unknown,
+  res: unknown,
+  next: (error?: unknown) => void
+) => unknown;
+
+export interface TelemetryOptions {
+  otlpEndpoint?: string;
+  serviceName?: string;
+  samplingRatio?: number;
+  apiKey?: string;
+}
+
+export interface TelemetryConfig {
+  otlpEndpoint: string;
+  serviceName: string;
+  samplingRatio: number;
+}
+
+export type Ap2RejectionCode =
+  | 'mandate_malformed'
+  | 'sd_jwt_disclosures_unsupported'
+  | 'typ_unsupported'
+  | 'crit_unsupported'
+  | 'alg_missing'
+  | 'alg_unsupported'
+  | 'alg_key_mismatch'
+  | 'claim_missing'
+  | 'jti_invalid'
+  | 'expired'
+  | 'future'
+  | 'not_yet_valid'
+  | 'lifetime_exceeded'
+  | 'self_certifying_disabled'
+  | 'trusted_key_invalid'
+  | 'didkey_alg'
+  | 'didkey_invalid'
+  | 'unverifiable'
+  | 'signature_invalid'
+  | 'signature_error'
+  | 'audience_mismatch'
+  | 'merchant_scope_mismatch'
+  | 'cart_binding_mismatch'
+  | 'category_denied'
+  | 'currency_invalid'
+  | 'currency_missing'
+  | 'store_currency_invalid'
+  | 'currency_mismatch_store'
+  | 'order_currency_invalid'
+  | 'currency_mismatch_order'
+  | 'budget_invalid'
+  | 'order_total_invalid'
+  | 'budget_exceeded'
+  | 'replay';
+
+export interface Ap2VerificationResult {
+  valid: boolean;
+  /** Stable machine-readable rejection identifier. */
+  code?: Ap2RejectionCode;
+  /**
+   * True when `reason` is safe to return to the caller. False for rejections
+   * whose detail would reveal store configuration (expected audience,
+   * expected currency) or verifier internals (raw crypto error text) — use
+   * `publicReason` in that case.
+   */
+  disclose?: boolean;
+  /** Caller-safe rendering of `reason`. */
+  publicReason?: string;
+  /** Mandate currency, normalized to an uppercase ISO 4217 code. */
+  currency?: string | null;
+  /** The JWS algorithm the mandate was verified with. */
+  algorithm?: string;
+  cartBinding?: 'verified' | 'unverified' | 'unbound';
+  /**
+   * True only when a presented mandate cryptographically verified. When a
+   * shared replay store (UPSTASH_REDIS_REST_URL/TOKEN) is configured,
+   * verification may resolve asynchronously - the return type becomes
+   * Promise<Ap2VerificationResult>; callers should await it either way.
+   */
+  verified?: boolean;
+  protocol: 'AP2';
+  reason?: string;
+  note?: string;
+  selfCertifying?: boolean;
+  mandates?: Record<string, unknown>;
+}
+
+export interface Ap2VerifyOptions {
+  trustedPublicKey?: unknown;
+  expectedAudience?: string;
+  maxMandateLifetimeSec?: number;
+  requireJti?: boolean;
+  requestedCategories?: string[];
+  /** v4: when false, self-certifying did:key issuers are rejected. */
+  allowSelfCertifying?: boolean;
+  expectedCartHash?: string;
+  expectedCurrency?: string;
+  /** Reject a `maxBudget` with no `currency` (default true). */
+  requireCurrency?: boolean;
+  /** Tolerance in seconds for `iat`/`exp` clock drift (default 60). */
+  clockSkewSec?: number;
+  /** When false, a valid mandate is verified WITHOUT consuming its jti. */
+  consumeJti?: boolean;
+  /** Injectable clock for tests. */
+  nowMs?: number;
+}
+
+export interface CreateAp2MandateOptions {
+  audience: string;
+  maxBudget: number;
+  currency?: string;
+  allowedCategories?: string[];
+  merchantScope?: string;
+  lifetimeSec?: number;
+  paymentMethod?: string;
+  subject?: string;
+  privateKey?: unknown;
+  agentInitiated?: boolean;
+  cart?: { items: Array<unknown> };
+  cartHash?: string;
+}
+
+export interface Ap2Mandate {
+  token: string;
+  did: string;
+  publicKey: unknown;
+  privateKey: unknown;
+  cartHash?: string | null;
+}
+
+export function agentsbloom(config?: AgentsBloomConfig): AgentsBloomMiddleware;
+export function setupTelemetry(options?: TelemetryOptions): Promise<TelemetryConfig>;
+export function shutdown(): Promise<void>;
+export function resolveProtocol(req: {
+  headers?: Record<string, string | undefined>;
+  path?: string;
+  url?: string;
+}): Protocol;
+export function verifyAP2Mandates(
+  headers?: Record<string, string | undefined>,
+  body?: Record<string, unknown>,
+  publicKeyOrOptions?: unknown | Ap2VerifyOptions
+): Ap2VerificationResult | Promise<Ap2VerificationResult>;
+export function createAp2Mandate(options: CreateAp2MandateOptions): Ap2Mandate;
+export function didKeyFromEd25519PublicKey(publicKey: unknown): string;
+export function ed25519PublicKeyFromDidKey(didKey: string): unknown | null;
+export function resetAp2ReplayCache(): void;
+export function canonicalCartHash(cart: unknown): { cartHash: string; [key: string]: unknown };
+export function stableStringify(value: unknown): string;
+/**
+ * Normalizes an audience/merchantScope value (URL-parsed: lowercased host,
+ * trailing slashes stripped) so mandates built via new URL().href compare
+ * equal to slash-free configured audiences.
+ */
+export function normalizeAudience(value: string): string;
+
+/** Marks quota exceeded process-wide until the given epoch-ms timestamp. */
+export function setQuotaExceededUntil(untilEpochMs: number): void;
+/** Clears the process-wide quota-exceeded state immediately. */
+export function clearQuotaExceeded(): void;
+
+/**
+ * RFC 9421 `alg` values this SDK verifies. Both the RFC 9421 registry names
+ * (`ecdsa-p256-sha256`) and the JOSE spellings (`ES256`) are accepted.
+ */
+export const SUPPORTED_SIGNATURE_ALGORITHMS: readonly string[];
+/** JWS algorithms accepted for AP2 mandates signed by a merchant-trusted key. */
+export const SUPPORTED_MANDATE_ALGORITHMS: readonly string[];
+
+export interface OutcomeReport {
+  orderRef: string;
+  status: 'paid' | 'declined' | 'refunded' | 'chargeback' | 'disputed' | 'canceled';
+  gateway?: 'stripe' | 'razorpay' | 'paddle' | 'other';
+  reason?: string | null;
+  amount?: number | null;
+  currency?: string | null;
+  identityKey?: string | null;
+  occurredAt?: string;
+}
+
+export interface OutcomeReporter {
+  report(body: OutcomeReport): Promise<{ ok: boolean; recorded: string; orderRef: string }>;
+  captureStripeOutcome(event: unknown): Promise<{ skipped: boolean } | { ok: boolean }>;
+}
+export function stripeEventToOutcome(event: unknown): OutcomeReport | null;
+export function createOutcomeReporter(options: {
+  apiKey: string;
+  collectorUrl?: string;
+  fetchImpl?: (url: string, init: object) => Promise<Response>;
 }): OutcomeReporter;