@agentsbloom/sdk 0.2.0 → 0.5.0

package/lib/signature-base.js

@@ -0,0 +1,436 @@
+/**
+ * RFC 9421 signature-base construction — the canonical, conformant version.
+ *
+ * This is the single source of truth for "what bytes did the agent sign".
+ * Every AgentsBloom verifier (this SDK, `@agentsbloom/next`, and any port to
+ * another language) must reproduce these bytes exactly, and the signer in
+ * `@agentsbloom/agent` must produce them.
+ *
+ * ---------------------------------------------------------------------------
+ * Two profiles
+ * ---------------------------------------------------------------------------
+ *
+ * `ab2` (default, RFC 9421 conformant)
+ *   "@method":    UPPERCASE, as RFC 9421 §2.2.1 requires.
+ *   "@authority": lowercased host with the scheme's default port removed
+ *                 (§2.2.3). Binding the authority is what stops a signature
+ *                 captured at store A from replaying at store B.
+ *   "@path":      the absolute path ONLY (§2.2.6) — never the query.
+ *   "@query":     "?" + query string, or a bare "?" when absent (§2.2.7).
+ *   Headers:      obs-fold collapsed, trimmed, multiple values joined with
+ *                 ", "; a covered header that is ABSENT is a hard failure.
+ *
+ * `ab1` (legacy, opt-in via `signature.acceptLegacyProfile`)
+ *   Byte-for-byte reproduction of the pre-hardening base that shipped in
+ *   `@agentsbloom/sdk` <= 0.5.0: lowercased `@method`, `@path` carrying the
+ *   query, raw Host header for `@authority`, and a missing covered header
+ *   silently canonicalized to the empty string. It exists only so a
+ *   deployment can keep older agents working during a migration window. It
+ *   is NOT enabled by default, and it cannot bind the authority reliably.
+ *
+ * Why the old base was wrong (all three are real interop/security defects):
+ *   - lowercased `@method` meant no standards-conformant client could ever
+ *     verify against us, and vice versa;
+ *   - `@path` built from `req.originalUrl` silently included the query, so a
+ *     conformant client signing `@path` per spec failed on any URL with a
+ *     query string;
+ *   - `req.headers[comp] || ''` meant a covered header the client signed but
+ *     an intermediary stripped verified against an empty value instead of
+ *     erroring.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9421
+ */
+
+import crypto from 'crypto';
+import { parseByteSequenceDictionary } from './structured-fields.js';
+
+export const PROFILE_STRICT = 'ab2';
+export const PROFILE_LEGACY = 'ab1';
+
+/** Derived components this implementation knows how to canonicalize. */
+const SUPPORTED_DERIVED = new Set([
+  '@method',
+  '@target-uri',
+  '@authority',
+  '@scheme',
+  '@request-target',
+  '@path',
+  '@query',
+  '@query-param',
+]);
+
+/**
+ * Component parameters we deliberately refuse.
+ *
+ * `sf`/`bs`/`key`/`tr` change the canonical value of a component; `req`
+ * re-targets it at a different message. Accepting the parameter name while
+ * ignoring its meaning — which the old regex parser did — means the signer
+ * and the verifier canonicalize different bytes while both believe the
+ * signature covered the same thing. Refusing is the only safe option until
+ * each is actually implemented.
+ */
+const REJECTED_COMPONENT_PARAMS = new Set(['sf', 'bs', 'key', 'req', 'tr']);
+
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' };
+
+export class SignatureBaseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SignatureBaseError';
+  }
+}
+
+function fail(message) {
+  throw new SignatureBaseError(message);
+}
+
+/**
+ * Normalizes an HTTP authority per RFC 9421 §2.2.3: lowercase host, drop the
+ * scheme's default port. IPv6 literals keep their brackets.
+ *
+ * @param {string} rawAuthority
+ * @param {string} scheme - e.g. 'https:'
+ * @returns {string}
+ */
+export function normalizeAuthority(rawAuthority, scheme) {
+  const authority = String(rawAuthority || '').trim().toLowerCase();
+  if (!authority) return '';
+  const defaultPort = DEFAULT_PORTS[scheme];
+  if (!defaultPort) return authority;
+  // Only strip a trailing :port, never a colon inside an IPv6 literal.
+  const lastColon = authority.lastIndexOf(':');
+  if (lastColon === -1) return authority;
+  const closingBracket = authority.lastIndexOf(']');
+  if (lastColon < closingBracket) return authority;
+  const port = authority.slice(lastColon + 1);
+  if (port === defaultPort) return authority.slice(0, lastColon);
+  return authority;
+}
+
+/**
+ * Canonicalizes one header field value for the signature base
+ * (RFC 9421 §2.1): obs-fold collapsed to a single space, leading/trailing
+ * whitespace removed, repeated fields joined with ", ".
+ *
+ * @param {string|string[]|undefined} value
+ * @returns {string|undefined} undefined when the header is absent
+ */
+function canonicalizeHeaderValue(value) {
+  if (value === undefined || value === null) return undefined;
+  const values = Array.isArray(value) ? value : [value];
+  if (values.length === 0) return undefined;
+  return values
+    .map((entry) => String(entry).replace(/[\r\n]+[ \t]+/g, ' ').replace(/[\r\n]/g, '').trim())
+    .join(', ');
+}
+
+/**
+ * A runtime-neutral view of the request being verified. Keeping the shape
+ * explicit (rather than passing an Express `req` around) is what lets the
+ * Edge/WebCrypto port in `@agentsbloom/next` share these exact rules.
+ *
+ * @typedef {object} SignatureRequestContext
+ * @property {string} method
+ * @property {string} scheme        - 'http:' or 'https:'
+ * @property {string} authority     - raw Host/:authority value
+ * @property {string} path          - absolute path, no query
+ * @property {string} query         - query string WITHOUT the leading '?'
+ * @property {(name: string) => string|string[]|undefined} header
+ * @property {string} [legacyTarget] - `req.originalUrl` equivalent, ab1 only
+ */
+
+/**
+ * Builds a {@link SignatureRequestContext} from an Express request.
+ *
+ * @param {object} req
+ * @param {object} [options]
+ * @param {string} [options.forwardedProto] - already-validated proto ('http'|'https'|'')
+ * @returns {SignatureRequestContext}
+ */
+export function requestContextFromExpress(req, options = {}) {
+  const rawTarget = req.originalUrl || req.url || req.path || '/';
+  const queryIndex = rawTarget.indexOf('?');
+  const path = queryIndex === -1 ? rawTarget : rawTarget.slice(0, queryIndex);
+  const query = queryIndex === -1 ? '' : rawTarget.slice(queryIndex + 1);
+  const proto = options.forwardedProto || req.protocol || 'http';
+  return {
+    method: String(req.method || ''),
+    scheme: `${proto}:`,
+    authority: Array.isArray(req.headers?.host) ? req.headers.host[0] : req.headers?.host || '',
+    path: path || '/',
+    query,
+    header: (name) => req.headers?.[name],
+    legacyTarget: rawTarget,
+  };
+}
+
+/**
+ * Canonical value of a derived (`@`-prefixed) component.
+ *
+ * @param {string} name
+ * @param {Map<string, unknown>} params
+ * @param {SignatureRequestContext} request
+ * @param {string} profile
+ * @returns {string}
+ */
+function derivedComponentValue(name, params, request, profile) {
+  const legacy = profile === PROFILE_LEGACY;
+  switch (name) {
+    case '@method':
+      // RFC 9421 §2.2.1: the method, uppercase. ab1 lowercased it.
+      return legacy ? String(request.method).toLowerCase() : String(request.method).toUpperCase();
+    case '@authority':
+      return legacy
+        ? String(request.authority ?? '')
+        : normalizeAuthority(request.authority, request.scheme);
+    case '@scheme':
+      return String(request.scheme || '').replace(/:$/, '').toLowerCase();
+    case '@path':
+      // RFC 9421 §2.2.6: absolute path only. ab1 used path+query.
+      if (legacy) return String(request.legacyTarget ?? request.path ?? '/');
+      return request.path && request.path.length > 0 ? request.path : '/';
+    case '@query':
+      // RFC 9421 §2.2.7: "?" + query; a bare "?" when the query is absent.
+      return request.query ? `?${request.query}` : '?';
+    case '@request-target':
+      return request.query ? `${request.path}?${request.query}` : request.path;
+    case '@target-uri': {
+      const authority = normalizeAuthority(request.authority, request.scheme);
+      if (!authority) fail('@target-uri cannot be derived without an authority');
+      const scheme = String(request.scheme || '').replace(/:$/, '');
+      return `${scheme}://${authority}${request.path}${request.query ? `?${request.query}` : ''}`;
+    }
+    case '@query-param': {
+      const paramName = params.get('name');
+      if (typeof paramName !== 'string') {
+        fail('@query-param requires a string "name" parameter');
+      }
+      const search = new URLSearchParams(request.query || '');
+      const values = search.getAll(paramName);
+      if (values.length === 0) fail(`@query-param "${paramName}" is not present in the request`);
+      if (values.length > 1) fail(`@query-param "${paramName}" appears more than once`);
+      // RFC 9421 §2.2.8 canonicalizes the param name and value
+      // percent-encoded; URLSearchParams has already decoded, so re-encode.
+      return encodeURIComponent(values[0]);
+    }
+    default:
+      return fail(`unsupported derived component "${name}"`);
+  }
+}
+
+/**
+ * Builds the RFC 9421 signature base.
+ *
+ * @param {object} options
+ * @param {Array<{ name: string, params: Map<string, unknown> }>} options.components
+ *   Covered component identifiers in the order the client listed them.
+ * @param {string} options.signatureParamsRaw
+ *   The EXACT `Signature-Input` dictionary-member value as received. Per
+ *   RFC 9421 §2.5 the `@signature-params` line reproduces what was sent;
+ *   re-serializing from a parse tree would reject signers whose parameter
+ *   ordering or spelling differs from ours.
+ * @param {SignatureRequestContext} options.request
+ * @param {string} [options.profile]
+ * @returns {string}
+ */
+export function buildSignatureBase({ components, signatureParamsRaw, request, profile = PROFILE_STRICT }) {
+  if (!Array.isArray(components) || components.length === 0) {
+    fail('the covered component list is empty');
+  }
+  if (typeof signatureParamsRaw !== 'string' || signatureParamsRaw.length === 0) {
+    fail('the signature parameters are missing');
+  }
+
+  const seen = new Set();
+  let base = '';
+
+  for (const component of components) {
+    const rawName = component.name;
+    if (typeof rawName !== 'string' || rawName.length === 0) {
+      fail('a covered component identifier is not a string');
+    }
+    // RFC 9421 §2.1: component names are lowercase. Reject rather than
+    // silently fold, so a signer that sent `Content-Digest` learns why.
+    if (rawName !== rawName.toLowerCase()) {
+      fail(`covered component "${rawName}" must be lowercase`);
+    }
+
+    const params = component.params instanceof Map ? component.params : new Map();
+    for (const paramName of params.keys()) {
+      if (REJECTED_COMPONENT_PARAMS.has(paramName)) {
+        fail(`covered component parameter ";${paramName}" is not supported`);
+      }
+      if (paramName === 'name' && rawName !== '@query-param') {
+        fail('the ";name" parameter is only valid on @query-param');
+      }
+      if (paramName !== 'name') {
+        fail(`unknown covered component parameter ";${paramName}"`);
+      }
+    }
+
+    // A component may repeat only when its parameters differ (RFC 9421 §2.1).
+    const identity = params.has('name') ? `${rawName};name=${params.get('name')}` : rawName;
+    if (seen.has(identity)) fail(`covered component ${identity} appears more than once`);
+    seen.add(identity);
+
+    let value;
+    if (rawName.startsWith('@')) {
+      if (!SUPPORTED_DERIVED.has(rawName)) fail(`unsupported derived component "${rawName}"`);
+      if (rawName === '@signature-params') fail('@signature-params cannot be listed explicitly');
+      value = derivedComponentValue(rawName, params, request, profile);
+    } else {
+      if (!/^[!#$%&'*+\-.^_`|~0-9a-z]+$/.test(rawName)) {
+        fail(`covered component "${rawName}" is not a valid header field name`);
+      }
+      const canonical = canonicalizeHeaderValue(request.header(rawName));
+      if (canonical === undefined) {
+        if (profile === PROFILE_LEGACY) {
+          // ab1 bug-compatibility: absent headers canonicalized to ''.
+          value = '';
+        } else {
+          fail(`covered header "${rawName}" is missing from the request`);
+        }
+      } else {
+        value = canonical;
+      }
+    }
+
+    // Serialize the component identifier the way the client did, including
+    // its parameters, so the base line matches byte-for-byte.
+    const serializedName = params.has('name')
+      ? `"${rawName}";name="${String(params.get('name')).replace(/(["\\])/g, '\\$1')}"`
+      : `"${rawName}"`;
+    base += `${serializedName}: ${value}\n`;
+  }
+
+  base += `"@signature-params": ${signatureParamsRaw}`;
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Content-Digest
+// ---------------------------------------------------------------------------
+
+/** Digest algorithms we compute and accept, per RFC 9530. */
+const DIGEST_ALGORITHMS = {
+  'sha-256': 'sha256',
+  'sha-512': 'sha512',
+};
+
+/**
+ * Computes the `Content-Digest` header value for a body.
+ *
+ * @param {Buffer} bodyBytes
+ * @param {string} [algorithm='sha-256']
+ * @returns {string} e.g. `sha-256=:<base64>:`
+ */
+export function contentDigestHeader(bodyBytes, algorithm = 'sha-256') {
+  const nodeAlg = DIGEST_ALGORITHMS[algorithm];
+  if (!nodeAlg) fail(`unsupported content-digest algorithm "${algorithm}"`);
+  const digest = crypto.createHash(nodeAlg).update(bodyBytes).digest('base64');
+  return `${algorithm}=:${digest}:`;
+}
+
+/**
+ * Verifies a received `Content-Digest` header against the actual body bytes.
+ *
+ * Rules:
+ *   - the header must parse as a Structured Field dictionary of byte
+ *     sequences (`sha-256=:...:, sha-512=:...:`);
+ *   - at least one entry must use an algorithm we support;
+ *   - EVERY supported entry must match. Accepting a request because one of
+ *     two digests matched would let a caller pin a weak algorithm alongside
+ *     a bogus strong one.
+ *   - unknown algorithms are ignored (RFC 9530 allows extension), but they
+ *     cannot satisfy the "at least one supported" requirement.
+ *
+ * @param {string|string[]|undefined} headerValue
+ * @param {Buffer} bodyBytes
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function verifyContentDigest(headerValue, bodyBytes) {
+  const canonical = canonicalizeHeaderValue(headerValue);
+  if (canonical === undefined || canonical === '') {
+    return { ok: false, reason: 'content-digest header is missing' };
+  }
+  let entries;
+  try {
+    entries = parseByteSequenceDictionary(canonical);
+  } catch (err) {
+    return { ok: false, reason: `content-digest header is malformed: ${err.message}` };
+  }
+  let matchedSupported = 0;
+  for (const [algorithm, provided] of entries) {
+    const nodeAlg = DIGEST_ALGORITHMS[algorithm];
+    if (!nodeAlg) continue;
+    const expected = crypto.createHash(nodeAlg).update(bodyBytes).digest();
+    if (provided.length !== expected.length || !crypto.timingSafeEqual(provided, expected)) {
+      return { ok: false, reason: `content-digest ${algorithm} does not match the request body` };
+    }
+    matchedSupported += 1;
+  }
+  if (matchedSupported === 0) {
+    return { ok: false, reason: 'content-digest header contains no supported algorithm' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Resolves the exact body bytes a digest must be computed over.
+ *
+ * The digest guarantee is "this is what the client sent". That is only true
+ * when we hash the RECEIVED BYTES. Re-serializing `req.body` with
+ * `JSON.stringify` — which the previous implementation fell back to — turns
+ * the guarantee into "this matches our re-serialization of what our parser
+ * produced", which an agent computing its digest the same way satisfies even
+ * when the bytes on the wire differed (key order, number formatting,
+ * duplicate keys, unicode escapes).
+ *
+ * So: when a signed request has a body, `req.rawBody` is REQUIRED. Merchants
+ * wire it up with one line:
+ *
+ *     app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
+ *
+ * @param {object} req
+ * @param {object} [options]
+ * @param {boolean} [options.allowReserializedBody=false] - legacy escape hatch
+ * @returns {Buffer}
+ */
+export function resolveBodyBytes(req, options = {}) {
+  const { allowReserializedBody = false } = options;
+
+  if (Buffer.isBuffer(req.rawBody)) return req.rawBody;
+  if (typeof req.rawBody === 'string') return Buffer.from(req.rawBody, 'utf8');
+  if (Buffer.isBuffer(req.body)) return req.body;
+
+  const declaredLength = Number(
+    (Array.isArray(req.headers?.['content-length'])
+      ? req.headers['content-length'][0]
+      : req.headers?.['content-length']) || 0,
+  );
+  const hasBody =
+    (Number.isFinite(declaredLength) && declaredLength > 0) ||
+    String(req.headers?.['transfer-encoding'] || '').toLowerCase().includes('chunked') ||
+    (req.body !== undefined && req.body !== null && !isEmptyObject(req.body));
+
+  if (!hasBody) return Buffer.alloc(0);
+
+  if (allowReserializedBody && req.body !== undefined) {
+    return Buffer.from(JSON.stringify(req.body ?? null), 'utf8');
+  }
+
+  fail(
+    'Signed requests with a body require the raw bytes. Capture them with '
+    + 'express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }) — '
+    + 'hashing a re-serialized body would not prove what the client actually sent.',
+  );
+}
+
+function isEmptyObject(value) {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && Object.keys(value).length === 0
+  );
+}