@agentsbloom/sdk 0.2.0 → 0.5.0

package/lib/money.js

@@ -0,0 +1,283 @@
+/**
+ * Exact money handling for the AgentsBloom SDK.
+ *
+ * Why this file exists
+ * -------------------
+ * Every monetary value in the previous implementation was an IEEE-754
+ * double, and the conversion to minor units was `Math.round(Number(x) * 100)`.
+ * That is wrong in a way that costs real money:
+ *
+ *     1.005 * 100 === 100.49999999999999   ->  Math.round -> 100   ($1.00)
+ *     1.015 * 100 === 101.49999999999999   ->  Math.round -> 101   ($1.01)
+ *     2.675 * 100 === 267.49999999999994   ->  Math.round -> 267   ($2.67)
+ *
+ * A price that a human wrote as $1.005 is silently charged as $1.00, and the
+ * same wrong number is what gets hashed into a Cart Mandate. Budget
+ * comparisons had the same problem from the other direction: `orderTotal >
+ * maxBudget` on doubles can accept a total that is a fraction of a cent over
+ * the authorized cap, and accumulating `sum += q * u` across a large cart can
+ * exceed 2^53 and lose precision entirely.
+ *
+ * The fix is to never multiply a float. Values arrive as decimal strings or
+ * numbers, are converted to their exact shortest decimal representation, and
+ * are then shifted by the required number of places using integer (BigInt)
+ * arithmetic with explicit half-up rounding.
+ *
+ * Everything here is total: nothing throws for bad input, it returns `null`
+ * so callers make a deliberate fail-closed decision.
+ */
+
+/**
+ * ISO 4217 currencies whose minor unit is NOT two decimal places. Anything
+ * absent from this table is treated as exponent 2, which is correct for the
+ * overwhelming majority of codes.
+ */
+const CURRENCY_EXPONENTS = new Map(Object.entries({
+  // Zero-decimal currencies.
+  BIF: 0, CLP: 0, DJF: 0, GNF: 0, ISK: 0, JPY: 0, KMF: 0, KRW: 0, PYG: 0,
+  RWF: 0, UGX: 0, UYI: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
+  // Three-decimal currencies.
+  BHD: 3, IQD: 3, JOD: 3, KWD: 3, LYD: 3, OMR: 3, TND: 3,
+  // Four-decimal currencies.
+  CLF: 4, UYW: 4,
+}));
+
+/**
+ * Internal comparison scale. Six places is more than any real currency needs
+ * (the deepest ISO 4217 minor unit is four), so scaling both sides of a
+ * budget comparison to micros is exact for every currency without needing to
+ * know which currency is in play.
+ */
+export const COMPARISON_SCALE = 6;
+
+/** Longest accepted numeric input; guards BigInt work on hostile input. */
+const MAX_NUMERIC_LENGTH = 32;
+
+/** Hard ceiling on a single monetary amount (1 trillion major units). */
+const MAX_MAJOR_UNITS = 1_000_000_000_000n;
+
+/**
+ * Returns the number of minor-unit decimal places for a currency code.
+ *
+ * @param {unknown} currency
+ * @returns {number}
+ */
+export function currencyExponent(currency) {
+  const code = normalizeCurrencyCode(currency);
+  if (!code) return 2;
+  return CURRENCY_EXPONENTS.has(code) ? CURRENCY_EXPONENTS.get(code) : 2;
+}
+
+/**
+ * Normalizes a currency code to uppercase, or returns null when it is not a
+ * syntactically valid ISO 4217 alphabetic code.
+ *
+ * @param {unknown} currency
+ * @returns {string|null}
+ */
+export function normalizeCurrencyCode(currency) {
+  if (typeof currency !== 'string') return null;
+  const code = currency.trim().toUpperCase();
+  return /^[A-Z]{3}$/.test(code) ? code : null;
+}
+
+/**
+ * Converts a number or numeric string to its exact decimal representation,
+ * expanding exponent notation. Returns null for anything non-finite or
+ * malformed.
+ *
+ * `String(n)` gives JavaScript's shortest round-trip decimal, which is the
+ * value the developer actually wrote for any literal they could have typed —
+ * so this is a faithful, not lossy, starting point.
+ *
+ * @param {unknown} value
+ * @returns {string|null} e.g. '-12.345'
+ */
+export function toDecimalString(value) {
+  let text;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null;
+    text = String(value);
+  } else if (typeof value === 'bigint') {
+    text = value.toString();
+  } else if (typeof value === 'string') {
+    text = value.trim();
+  } else {
+    return null;
+  }
+
+  if (text === '' || text.length > MAX_NUMERIC_LENGTH) return null;
+
+  const match = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d{1,3}))?$/.exec(text);
+  if (!match) return null;
+  const [, rawSign, rawInt = '', rawFrac = '', rawExp] = match;
+  if (rawInt === '' && rawFrac === '') return null;
+
+  const sign = rawSign === '-' ? '-' : '';
+  let digits = `${rawInt}${rawFrac}`;
+  // Decimal point position measured from the left of `digits`.
+  let pointIndex = rawInt.length;
+
+  if (rawExp !== undefined) {
+    pointIndex += Number(rawExp);
+  }
+
+  if (pointIndex <= 0) {
+    digits = '0'.repeat(1 - pointIndex) + digits;
+    pointIndex = 1;
+  }
+  if (pointIndex > digits.length) {
+    digits += '0'.repeat(pointIndex - digits.length);
+  }
+
+  const intPart = digits.slice(0, pointIndex).replace(/^0+(?=\d)/, '');
+  const fracPart = digits.slice(pointIndex).replace(/0+$/, '');
+  return fracPart ? `${sign}${intPart}.${fracPart}` : `${sign}${intPart}`;
+}
+
+/**
+ * Converts a monetary value to an exact integer scaled by 10^scale, rounding
+ * half away from zero. Returns null when the value is not a finite number,
+ * is malformed, or exceeds the sanity ceiling.
+ *
+ * @param {unknown} value
+ * @param {number} scale - number of decimal places to keep
+ * @returns {bigint|null}
+ */
+export function toScaledBigInt(value, scale) {
+  if (!Number.isInteger(scale) || scale < 0 || scale > 12) return null;
+  const decimal = toDecimalString(value);
+  if (decimal === null) return null;
+
+  const negative = decimal.startsWith('-');
+  const unsigned = negative ? decimal.slice(1) : decimal;
+  const [intPart, fracPart = ''] = unsigned.split('.');
+
+  if (intPart.length > 16) return null;
+
+  const kept = fracPart.slice(0, scale).padEnd(scale, '0');
+  const dropped = fracPart.slice(scale);
+
+  let scaled = BigInt(`${intPart}${kept}` || '0');
+  // Half-up rounding on the discarded remainder: '5...' rounds away from zero.
+  if (dropped.length > 0 && dropped.charCodeAt(0) >= 0x35) {
+    scaled += 1n;
+  }
+
+  if (scaled > MAX_MAJOR_UNITS * 10n ** BigInt(scale)) return null;
+  return negative ? -scaled : scaled;
+}
+
+/**
+ * Converts a monetary value to the exact minor units of a currency
+ * (cents for USD, yen for JPY, fils for KWD).
+ *
+ * @param {unknown} value
+ * @param {unknown} currency
+ * @returns {bigint|null}
+ */
+export function toMinorUnits(value, currency) {
+  return toScaledBigInt(value, currencyExponent(currency));
+}
+
+/**
+ * Converts a monetary value to hundredths of the major unit.
+ *
+ * Used by `canonicalCartHash`, whose wire format (`ac1_`, field `u`) is
+ * defined as hundredths regardless of the currency's real minor unit. That
+ * definition is fixed for cross-SDK byte compatibility — the agent SDK, the
+ * PHP core, and every merchant must agree — so this deliberately does NOT
+ * consult `currencyExponent`. Only the ROUNDING is corrected relative to the
+ * old `Math.round(x * 100)`.
+ *
+ * @param {unknown} value
+ * @returns {number|null} an exact integer, or null when unrepresentable
+ */
+export function toHundredths(value) {
+  const scaled = toScaledBigInt(value, 2);
+  if (scaled === null) return null;
+  if (scaled > BigInt(Number.MAX_SAFE_INTEGER) || scaled < -BigInt(Number.MAX_SAFE_INTEGER)) {
+    return null;
+  }
+  return Number(scaled);
+}
+
+/**
+ * Compares two monetary amounts exactly.
+ *
+ * Both sides are converted to micros with half-up rounding, so this is exact
+ * for every ISO 4217 currency and immune to the float artifacts that made
+ * `Number(orderTotal) > Number(maxBudget)` unreliable.
+ *
+ * @param {unknown} left
+ * @param {unknown} right
+ * @returns {-1|0|1|null} null when either side is not a valid amount
+ */
+export function compareAmounts(left, right) {
+  const a = toScaledBigInt(left, COMPARISON_SCALE);
+  const b = toScaledBigInt(right, COMPARISON_SCALE);
+  if (a === null || b === null) return null;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Strict parse of a client- or handler-supplied monetary amount.
+ *
+ * This is the gate that closes the budget-enforcement bypass: the old code
+ * did `Number(orderTotal) > Number(maxBudget)`, and `Number('abc')` is `NaN`,
+ * for which every comparison is false. A malformed total therefore passed the
+ * budget check instead of failing it. Callers must treat `null` as "reject".
+ *
+ * @param {unknown} value
+ * @param {object} [options]
+ * @param {boolean} [options.allowZero=true]
+ * @param {boolean} [options.allowNegative=false]
+ * @returns {{ decimal: string, micros: bigint }|null}
+ */
+export function parseAmount(value, options = {}) {
+  const { allowZero = true, allowNegative = false } = options;
+  // Reject booleans and empty-ish values that Number() would happily coerce.
+  if (typeof value === 'boolean' || value === null || value === undefined) return null;
+  if (typeof value === 'string' && value.trim() === '') return null;
+  if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'bigint') return null;
+
+  const decimal = toDecimalString(value);
+  if (decimal === null) return null;
+  const micros = toScaledBigInt(decimal, COMPARISON_SCALE);
+  if (micros === null) return null;
+  if (!allowNegative && micros < 0n) return null;
+  if (!allowZero && micros === 0n) return null;
+  return { decimal, micros };
+}
+
+/**
+ * Formats a scaled integer back to a decimal string.
+ *
+ * @param {bigint} scaled
+ * @param {number} scale
+ * @returns {string}
+ */
+export function formatScaled(scaled, scale) {
+  const negative = scaled < 0n;
+  const digits = (negative ? -scaled : scaled).toString().padStart(scale + 1, '0');
+  const intPart = digits.slice(0, digits.length - scale);
+  const fracPart = scale > 0 ? digits.slice(digits.length - scale).replace(/0+$/, '') : '';
+  return `${negative ? '-' : ''}${intPart}${fracPart ? `.${fracPart}` : ''}`;
+}
+
+/**
+ * Sums a list of `{ quantity, unitHundredths }` line items exactly.
+ *
+ * @param {Array<{ quantity: number, unitHundredths: number }>} items
+ * @returns {number|null} total in hundredths, or null on overflow
+ */
+export function sumLineItems(items) {
+  let total = 0n;
+  for (const item of items) {
+    total += BigInt(item.quantity) * BigInt(item.unitHundredths);
+    if (total > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+  }
+  return Number(total);
+}

package/lib/outcomes.js

@@ -0,0 +1,108 @@
+/**
+ * Payment-outcome reporting (migration 011 / POST /api/outcomes).
+ *
+ * AgentsBloom is the middleman: the merchant's gateway keys stay on THEIR
+ * servers, inside THEIR webhook handlers. That also means payment outcomes
+ * (paid / declined / chargeback) happen where we cannot see them - so this
+ * module lets the merchant's existing webhook handler report the outcome
+ * with one line. Those reports are what turn risk-core's decline-rate rules
+ * from theory into data, and what powers the dashboard's outcome analytics.
+ *
+ * Keys never leave the merchant: they only ever send order references,
+ * statuses, and optional amounts.
+ */
+
+const DEFAULT_STATUSES = ['paid', 'declined', 'refunded', 'chargeback', 'disputed', 'canceled'];
+
+/**
+ * Maps a Stripe webhook event to an outcome report body. Returns null for
+ * events that carry no outcome signal, so handlers can do:
+ *
+ *   const report = stripeEventToOutcome(event);
+ *   if (report) await reportPaymentOutcome(report);
+ */
+export function stripeEventToOutcome(event) {
+  const type = event?.type;
+  const wrap = (status, extra = {}) => {
+    const obj = event?.data?.object ?? {};
+    return {
+      orderRef:
+        obj.metadata?.orderRef ??
+        obj.client_reference_id ??
+        obj.id,
+      gateway: 'stripe',
+      status,
+      amount: typeof obj.amount_total === 'number'
+        ? obj.amount_total / 100
+        : typeof obj.amount === 'number'
+          ? obj.amount / 100
+          : undefined,
+      currency: typeof obj.currency === 'string' ? obj.currency : undefined,
+      reason: extra.reason ?? obj.failure_message ?? null,
+      occurredAt: event?.created ? new Date(event.created * 1000).toISOString() : undefined,
+    };
+  };
+  switch (type) {
+    case 'checkout.session.completed':
+      return wrap('paid');
+    case 'invoice.payment_failed':
+    case 'charge.failed': {
+      const rep = wrap('declined');
+      rep.reason = event?.data?.object?.failure_message ?? event?.data?.object?.failure_code ?? null;
+      return rep;
+    }
+    case 'charge.refunded':
+      return wrap('refunded');
+    case 'charge.dispute.created':
+      return wrap('chargeback');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Creates a reporter bound to your AgentsBloom account key.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey - partner API key (ag_live_... / ag_test_...)
+ * @param {string} [options.collectorUrl] - backend base URL
+ *   (default https://api.agentsbloom.com)
+ * @param {(url:string, init:object)=>Promise<Response>} [options.fetchImpl]
+ */
+export function createOutcomeReporter({ apiKey, collectorUrl, fetchImpl } = {}) {
+  const base = String(collectorUrl || process.env.AGENTSBLOOM_API_URL || 'https://api.agentsbloom.com').replace(/\/$/, '');
+  const doFetch = fetchImpl ?? fetch;
+
+  async function report(body) {
+    if (!apiKey) throw new Error('createOutcomeReporter requires your AgentsBloom apiKey');
+    if (!body || !body.orderRef || !DEFAULT_STATUSES.includes(body.status)) {
+      throw new Error('reportPaymentOutcome requires orderRef and status (paid|declined|refunded|chargeback|disputed|canceled)');
+    }
+    const res = await doFetch(`${base}/api/outcomes`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        gateway: 'stripe',
+        ...body,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`outcome report failed: HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    return res.json();
+  }
+
+  /** Reports a raw Stripe webhook event (no-op for non-outcome events). */
+  async function captureStripeOutcome(stripeEvent) {
+    const body = stripeEventToOutcome(stripeEvent);
+    if (!body) return { skipped: true };
+    return report(body);
+  }
+
+  return { report, captureStripeOutcome };
+}

package/lib/protocol.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Type declarations for `@agentsbloom/sdk/protocol` — the dependency-free
+ * wire-protocol primitives shared by every Node consumer (this SDK, the hosted
+ * gateway, and any language port checking itself against the reference).
+ */
+
+// ---------------------------------------------------------------------------
+// RFC 8941 structured fields
+// ---------------------------------------------------------------------------
+
+export class StructuredFieldError extends Error {
+  name: 'StructuredFieldError';
+}
+
+/** A Byte Sequence bare item (`:b64:`). */
+export class ByteSequence {
+  constructor(bytes: Buffer);
+  bytes: Buffer;
+}
+
+/** A Token bare item (distinguishes `foo` from `"foo"`). */
+export class Token {
+  constructor(value: string);
+  value: string;
+  toString(): string;
+}
+
+export type BareItem = string | number | boolean | ByteSequence | Token;
+export type Parameters = Map<string, BareItem>;
+
+export interface StructuredItem {
+  value: BareItem;
+  params: Parameters;
+}
+
+export interface DictionaryMember {
+  value: BareItem | StructuredItem[];
+  items?: StructuredItem[];
+  params: Parameters;
+  isInnerList: boolean;
+  /**
+   * The EXACT source substring of this member's value. RFC 9421 §2.5 requires
+   * `@signature-params` to reproduce the parameters as RECEIVED, so
+   * re-serializing from the parse tree would reject signers whose parameter
+   * ordering differs from ours.
+   */
+  raw: string;
+}
+
+export function parseDictionary(input: string): Map<string, DictionaryMember>;
+export function parseByteSequenceDictionary(input: string): Map<string, Buffer>;
+export function serializeByteSequence(bytes: Buffer | Uint8Array): string;
+
+// ---------------------------------------------------------------------------
+// RFC 9421 signature base
+// ---------------------------------------------------------------------------
+
+/** RFC 9421-conformant, host-bound profile. */
+export const PROFILE_STRICT: 'ab2';
+/** Byte-exact reproduction of the pre-0.6 base. Cannot bind the authority. */
+export const PROFILE_LEGACY: 'ab1';
+export type SignatureProfile = 'ab2' | 'ab1';
+
+export class SignatureBaseError extends Error {
+  name: 'SignatureBaseError';
+}
+
+/** A runtime-neutral view of the request being verified. */
+export interface SignatureRequestContext {
+  method: string;
+  /** 'http:' or 'https:' */
+  scheme: string;
+  /** Raw Host / :authority value. */
+  authority: string;
+  /** Absolute path, no query. */
+  path: string;
+  /** Query string WITHOUT the leading '?'. */
+  query: string;
+  header(name: string): string | string[] | undefined;
+  /** `originalUrl` equivalent; used by the `ab1` profile only. */
+  legacyTarget?: string;
+}
+
+export interface CoveredComponent {
+  name: string;
+  params: Parameters;
+}
+
+export function buildSignatureBase(options: {
+  components: CoveredComponent[];
+  /** The EXACT `Signature-Input` dictionary-member value as received. */
+  signatureParamsRaw: string;
+  request: SignatureRequestContext;
+  profile?: SignatureProfile;
+}): string;
+
+export function requestContextFromExpress(
+  req: unknown,
+  options?: { forwardedProto?: string },
+): SignatureRequestContext;
+
+/** RFC 9421 §2.2.3: lowercase host, scheme's default port removed. */
+export function normalizeAuthority(rawAuthority: string, scheme: string): string;
+
+export function contentDigestHeader(
+  bodyBytes: Buffer,
+  algorithm?: 'sha-256' | 'sha-512',
+): string;
+
+export function verifyContentDigest(
+  headerValue: string | string[] | undefined,
+  bodyBytes: Buffer,
+): { ok: true } | { ok: false; reason: string };
+
+/**
+ * Resolves the exact body bytes a digest must cover. Throws when a signed
+ * request has a body but `req.rawBody` was not captured — hashing a
+ * re-serialization proves nothing about what the client sent.
+ */
+export function resolveBodyBytes(
+  req: unknown,
+  options?: { allowReserializedBody?: boolean },
+): Buffer;
+
+// ---------------------------------------------------------------------------
+// RFC 9421 verification (JWKS-backed)
+// ---------------------------------------------------------------------------
+
+export const SUPPORTED_SIGNATURE_ALGORITHMS: readonly string[];
+export const STRICT_REQUIRED_COMPONENTS: readonly string[];
+export const LEGACY_REQUIRED_COMPONENTS: readonly string[];
+
+export interface JwksCache {
+  get(cacheKey: string): unknown;
+  put(cacheKey: string, entry: unknown): void;
+  clear(): void;
+  readonly size: number;
+}
+
+export function createJwksCache(options?: { maxEntries?: number }): JwksCache;
+
+/** True for loopback, RFC 1918, link-local, CGNAT and reserved addresses. */
+export function isBlockedSsrfHostname(hostname: string): boolean;
+
+export type HttpSignatureVerification =
+  | { ok: true; keyid: string; identity: string; profile: SignatureProfile }
+  | { ok: false; status: number; code: string; publicMessage: string; detail: string };
+
+export function verifyHttpMessageSignature(options: {
+  req: unknown;
+  requestContext: SignatureRequestContext;
+  signatureHeader: string;
+  signatureInputHeader: string;
+  jwks?: { keys: Array<Record<string, unknown>> } | null;
+  jwksUrl?: string | null;
+  jwksCache: JwksCache;
+  nonceCache: { claim(key: string, expiresAtMs: number): boolean | Promise<boolean> };
+  nonceNamespace: string;
+  maxAgeMs: number;
+  clockSkewMs: number;
+  requireAuthority?: boolean;
+  expectedAuthorities?: Set<string> | null;
+  acceptLegacyProfile?: boolean;
+  allowReserializedBody?: boolean;
+  fetchImpl?: typeof fetch;
+  nowMs?: number;
+}): Promise<HttpSignatureVerification>;
+
+// ---------------------------------------------------------------------------
+// Exact-decimal money
+// ---------------------------------------------------------------------------
+
+export const COMPARISON_SCALE: 6;
+
+/**
+ * Strict parse of a monetary amount. Returns null for everything `Number()`
+ * would silently coerce (`'abc'` -> NaN, `''` -> 0, booleans, arrays) — the
+ * exact inputs that let a malformed order total PASS a budget comparison.
+ */
+export function parseAmount(
+  value: unknown,
+  options?: { allowZero?: boolean; allowNegative?: boolean },
+): { decimal: string; micros: bigint } | null;
+
+/** Exact comparison. Returns null when either side is not a valid amount. */
+export function compareAmounts(left: unknown, right: unknown): -1 | 0 | 1 | null;
+
+export function toDecimalString(value: unknown): string | null;
+export function toScaledBigInt(value: unknown, scale: number): bigint | null;
+export function toMinorUnits(value: unknown, currency: unknown): bigint | null;
+/** Hundredths of the major unit — the cart-hash wire format. */
+export function toHundredths(value: unknown): number | null;
+export function formatScaled(scaled: bigint, scale: number): string;
+export function sumLineItems(
+  items: Array<{ quantity: number; unitHundredths: number }>,
+): number | null;
+export function currencyExponent(currency: unknown): number;
+export function normalizeCurrencyCode(currency: unknown): string | null;
+
+// ---------------------------------------------------------------------------
+// Replay cache
+// ---------------------------------------------------------------------------
+
+export interface ReplayCache {
+  /**
+   * Atomic check-and-set. True when this caller won the key (first use), false
+   * on replay OR when a configured shared store is unreachable and
+   * `AGENTSBLOOM_REPLAY_FAIL_OPEN` is not set.
+   */
+  claim(key: string, expiresAtMs: number): boolean | Promise<boolean>;
+  /** Advisory only; never gate a decision on it. */
+  has(key: string): boolean | Promise<boolean>;
+  set(key: string, expiresAtMs: number): void;
+  clear(): void;
+  stats(): {
+    localSize: number;
+    maxLocalSize: number;
+    capacityEvictions: number;
+    sharedFailures: number;
+    shared: boolean;
+    failOpen: boolean;
+  };
+}
+
+export function createReplayCache(namespace: string, maxLocalSize?: number): ReplayCache;
+export function isSharedStoreConfigured(): boolean;
+export function isReplayFailOpenEnabled(): boolean;
+export function sharedStoreOutageCount(): number;
+export function resetSharedStoreDiagnostics(): void;

package/lib/protocol.js

@@ -0,0 +1,85 @@
+/**
+ * `@agentsbloom/sdk/protocol` — the wire-protocol primitives, published as a
+ * dependency-free subpath.
+ *
+ * Why this entry point exists
+ * --------------------------
+ *
+ * The RFC 9421 signature base, the RFC 8941 parser and the exact-decimal money
+ * helpers had been reimplemented per consumer: once in this SDK, once in
+ * `@agentsbloom/next`, once in `@agentsbloom/agent`, and once in the hosted
+ * gateway (`apps/backend-api/lib/rfc9421.js`). Every copy drifted, and the
+ * drift was not cosmetic — the gateway lowercased `@method`, folded the query
+ * into `@path`, and never covered `@authority`, so an agent signing the
+ * conformant base could not authenticate against it at all.
+ *
+ * Any Node consumer can now import the ONE implementation:
+ *
+ *     import { buildSignatureBase, parseDictionary } from '@agentsbloom/sdk/protocol';
+ *
+ * The gateway deliberately avoided importing `@agentsbloom/sdk` because the
+ * main entry point pulls in OpenTelemetry and the MCP SDK. That concern does
+ * not apply here: every module re-exported below imports nothing but
+ * `node:crypto`, so this subpath adds no transitive dependencies and no
+ * startup cost.
+ *
+ * Runtimes without `node:crypto` (Edge, workers, browsers) should use the
+ * WebCrypto ports in `@agentsbloom/next`, which are kept byte-identical.
+ */
+
+// --- RFC 8941 structured fields -------------------------------------------
+export {
+  parseDictionary,
+  parseByteSequenceDictionary,
+  serializeByteSequence,
+  ByteSequence,
+  Token,
+  StructuredFieldError,
+} from './structured-fields.js';
+
+// --- RFC 9421 signature base ----------------------------------------------
+export {
+  buildSignatureBase,
+  requestContextFromExpress,
+  normalizeAuthority,
+  contentDigestHeader,
+  verifyContentDigest,
+  resolveBodyBytes,
+  SignatureBaseError,
+  PROFILE_STRICT,
+  PROFILE_LEGACY,
+} from './signature-base.js';
+
+// --- RFC 9421 verification (JWKS-backed) ----------------------------------
+export {
+  verifyHttpMessageSignature,
+  createJwksCache,
+  isBlockedSsrfHostname,
+  SUPPORTED_SIGNATURE_ALGORITHMS,
+  STRICT_REQUIRED_COMPONENTS,
+  LEGACY_REQUIRED_COMPONENTS,
+} from './http-signatures.js';
+
+// --- Exact-decimal money --------------------------------------------------
+export {
+  parseAmount,
+  compareAmounts,
+  toDecimalString,
+  toScaledBigInt,
+  toMinorUnits,
+  toHundredths,
+  formatScaled,
+  sumLineItems,
+  currencyExponent,
+  normalizeCurrencyCode,
+  COMPARISON_SCALE,
+} from './money.js';
+
+// --- Bounded / cluster-wide replay cache ----------------------------------
+export {
+  createReplayCache,
+  isSharedStoreConfigured,
+  isReplayFailOpenEnabled,
+  sharedStoreOutageCount,
+  resetSharedStoreDiagnostics,
+} from './shared-store.js';