@agentsbloom/sdk 0.4.0 → 0.5.0

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';