@agentsbloom/sdk 0.4.0 → 0.5.0

package/lib/structured-fields.js

@@ -0,0 +1,398 @@
+/**
+ * RFC 8941 Structured Field Values — the subset RFC 9421 actually needs.
+ *
+ * Why this file exists
+ * --------------------
+ * The previous verifier parsed `Signature-Input` with a handful of
+ * unanchored regexes:
+ *
+ *     rfcSignatureInput.match(/keyid="([^"]+)"/)
+ *     rfcSignatureInput.match(/\(([^)]+)\)/)
+ *     rfcSignatureInput.match(/(?:^|;)created=(\d+)(?:;|$)/)
+ *
+ * That is not a parser, and the gap between "what the regex extracted" and
+ * "what the client actually signed" is exploitable:
+ *
+ *   1. `keyid` was taken from the FIRST match anywhere in the header. A
+ *      covered-component name is a quoted string, so a component list
+ *      containing `"keyid=\"attacker\""`-shaped text could surface a keyid
+ *      that was never a signature parameter — the key used to verify and
+ *      the key named in the signed parameters could disagree.
+ *   2. Component *parameters* (`;sf`, `;bs`, `;req`, `;key`, `;name`) were
+ *      silently discarded. `"content-digest";sf` and `"content-digest"` are
+ *      DIFFERENT components with different canonical values, but both
+ *      collapsed to the same base line, so a signature over one verified
+ *      against the other.
+ *   3. Duplicate components, unbalanced quotes, and trailing garbage were
+ *      all accepted.
+ *
+ * A conformant parser removes the whole class. Everything below fails
+ * closed: anything that is not unambiguously well-formed throws.
+ *
+ * Scope: Dictionaries (`Signature`, `Signature-Input`), Inner Lists, Items,
+ * Parameters, and the bare-item types those use. List and Date/Display-String
+ * types are not needed by RFC 9421 and are deliberately absent.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8941
+ */
+
+/** Hard cap so a hostile header cannot drive superlinear work. */
+const MAX_FIELD_LENGTH = 16 * 1024;
+/** Hard cap on dictionary members / inner-list entries / parameters. */
+const MAX_MEMBERS = 64;
+
+export class StructuredFieldError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StructuredFieldError';
+  }
+}
+
+function fail(message) {
+  throw new StructuredFieldError(message);
+}
+
+/** Marker for a Byte Sequence bare item (`:b64:`). */
+export class ByteSequence {
+  /** @param {Buffer} bytes */
+  constructor(bytes) {
+    this.bytes = bytes;
+  }
+}
+
+/** Marker for a Token bare item (distinguishes `foo` from `"foo"`). */
+export class Token {
+  /** @param {string} value */
+  constructor(value) {
+    this.value = value;
+  }
+  toString() {
+    return this.value;
+  }
+}
+
+class Parser {
+  /** @param {string} input */
+  constructor(input) {
+    this.input = input;
+    this.pos = 0;
+  }
+
+  get done() {
+    return this.pos >= this.input.length;
+  }
+
+  peek() {
+    return this.input[this.pos];
+  }
+
+  /** RFC 8941 §4.2: discard leading SP characters only. */
+  skipSp() {
+    while (this.input[this.pos] === ' ') this.pos += 1;
+  }
+
+  /** RFC 8941 §4.2: OWS is SP / HTAB. */
+  skipOws() {
+    while (this.input[this.pos] === ' ' || this.input[this.pos] === '\t') this.pos += 1;
+  }
+
+  expect(char) {
+    if (this.input[this.pos] !== char) {
+      fail(`expected "${char}" at offset ${this.pos}`);
+    }
+    this.pos += 1;
+  }
+
+  /** RFC 8941 §4.2.3.3 — parse a parameter/dictionary key. */
+  parseKey() {
+    const char = this.peek();
+    if (char !== '*' && !isLcAlpha(char)) {
+      fail(`invalid key start "${char ?? '(end of input)'}" at offset ${this.pos}`);
+    }
+    const start = this.pos;
+    while (!this.done) {
+      const c = this.input[this.pos];
+      if (isLcAlpha(c) || isDigit(c) || c === '_' || c === '-' || c === '.' || c === '*') {
+        this.pos += 1;
+      } else {
+        break;
+      }
+    }
+    return this.input.slice(start, this.pos);
+  }
+
+  /** RFC 8941 §4.2.3.2 — parse zero or more `;key[=value]` parameters. */
+  parseParameters() {
+    const params = new Map();
+    while (!this.done && this.peek() === ';') {
+      this.pos += 1;
+      this.skipSp();
+      const key = this.parseKey();
+      let value = true;
+      if (!this.done && this.peek() === '=') {
+        this.pos += 1;
+        value = this.parseBareItem();
+      }
+      if (params.size >= MAX_MEMBERS) fail('too many parameters');
+      // RFC 8941: a duplicate key overwrites. We reject instead — a
+      // duplicate in a signature parameter set is never legitimate and
+      // "last one wins" is exactly the kind of ambiguity that lets a
+      // verifier and a signer disagree about what was signed.
+      if (params.has(key)) fail(`duplicate parameter "${key}"`);
+      params.set(key, value);
+    }
+    return params;
+  }
+
+  /** RFC 8941 §4.2.3 — parse an Item (bare item plus parameters). */
+  parseItem() {
+    const value = this.parseBareItem();
+    const params = this.parseParameters();
+    return { value, params };
+  }
+
+  /** RFC 8941 §4.2.1.1 — parse an Inner List `( item item ... )`. */
+  parseInnerList() {
+    this.expect('(');
+    const items = [];
+    for (;;) {
+      this.skipSp();
+      if (this.done) fail('unterminated inner list');
+      if (this.peek() === ')') {
+        this.pos += 1;
+        const params = this.parseParameters();
+        return { items, params };
+      }
+      if (items.length >= MAX_MEMBERS) fail('too many inner-list members');
+      items.push(this.parseItem());
+      const next = this.peek();
+      if (next !== ' ' && next !== ')') {
+        fail(`expected SP or ")" after inner-list member at offset ${this.pos}`);
+      }
+    }
+  }
+
+  /** RFC 8941 §4.2.1 — Item or Inner List. */
+  parseItemOrInnerList() {
+    return this.peek() === '(' ? this.parseInnerList() : this.parseItem();
+  }
+
+  /** RFC 8941 §4.2.3.1 — parse a bare Item. */
+  parseBareItem() {
+    if (this.done) fail('unexpected end of input while reading a bare item');
+    const char = this.peek();
+    if (char === '-' || isDigit(char)) return this.parseNumber();
+    if (char === '"') return this.parseString();
+    if (char === ':') return this.parseByteSequence();
+    if (char === '?') return this.parseBoolean();
+    if (char === '*' || isAlpha(char)) return this.parseToken();
+    fail(`invalid bare-item start "${char}" at offset ${this.pos}`);
+  }
+
+  /** RFC 8941 §4.2.4 — Integer or Decimal. */
+  parseNumber() {
+    let sign = 1n;
+    if (this.peek() === '-') {
+      sign = -1n;
+      this.pos += 1;
+    }
+    if (this.done || !isDigit(this.peek())) fail('number must contain at least one digit');
+    const start = this.pos;
+    let isDecimal = false;
+    let integerDigits = 0;
+    let fractionDigits = 0;
+    while (!this.done) {
+      const c = this.input[this.pos];
+      if (isDigit(c)) {
+        this.pos += 1;
+        if (isDecimal) fractionDigits += 1;
+        else integerDigits += 1;
+      } else if (c === '.' && !isDecimal) {
+        if (integerDigits > 12) fail('decimal has more than 12 integer digits');
+        isDecimal = true;
+        this.pos += 1;
+      } else {
+        break;
+      }
+    }
+    const text = this.input.slice(start, this.pos);
+    if (isDecimal) {
+      if (fractionDigits === 0) fail('decimal must have digits after the "."');
+      if (fractionDigits > 3) fail('decimal has more than 3 fractional digits');
+      return Number(sign === -1n ? `-${text}` : text);
+    }
+    if (integerDigits > 15) fail('integer has more than 15 digits');
+    // Integers stay exact: RFC 8941 bounds them to +/-999,999,999,999,999
+    // which fits a double, but BigInt keeps `created`/`expires` handling
+    // honest and lets callers decide how to narrow.
+    return Number(sign * BigInt(text));
+  }
+
+  /** RFC 8941 §4.2.5 — String (`"..."`, backslash escapes for `\` and `"`). */
+  parseString() {
+    this.expect('"');
+    let out = '';
+    while (!this.done) {
+      const char = this.input[this.pos];
+      this.pos += 1;
+      if (char === '\\') {
+        if (this.done) fail('string ends with a trailing backslash');
+        const escaped = this.input[this.pos];
+        this.pos += 1;
+        if (escaped !== '"' && escaped !== '\\') {
+          fail(`invalid string escape "\\${escaped}"`);
+        }
+        out += escaped;
+      } else if (char === '"') {
+        return out;
+      } else {
+        const code = char.charCodeAt(0);
+        // Only printable ASCII is legal inside a Structured Field string.
+        if (code < 0x20 || code >= 0x7f) fail('string contains a non-printable character');
+        out += char;
+      }
+    }
+    fail('unterminated string');
+  }
+
+  /** RFC 8941 §4.2.6 — Token. */
+  parseToken() {
+    const start = this.pos;
+    this.pos += 1; // first char already validated as ALPHA / "*"
+    while (!this.done) {
+      const c = this.input[this.pos];
+      if (isTokenChar(c)) this.pos += 1;
+      else break;
+    }
+    return new Token(this.input.slice(start, this.pos));
+  }
+
+  /** RFC 8941 §4.2.7 — Byte Sequence (`:<base64>:`). */
+  parseByteSequence() {
+    this.expect(':');
+    const end = this.input.indexOf(':', this.pos);
+    if (end === -1) fail('unterminated byte sequence');
+    const encoded = this.input.slice(this.pos, end);
+    this.pos = end + 1;
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
+      fail('byte sequence is not valid base64');
+    }
+    // Reject non-canonical base64 rather than letting Node silently skip
+    // invalid characters: `Buffer.from` is famously lenient, which would let
+    // two different header strings decode to the same signature bytes.
+    const bytes = Buffer.from(encoded, 'base64');
+    if (bytes.toString('base64') !== encoded) {
+      fail('byte sequence is not canonically encoded base64');
+    }
+    return new ByteSequence(bytes);
+  }
+
+  /** RFC 8941 §4.2.8 — Boolean (`?0` / `?1`). */
+  parseBoolean() {
+    this.expect('?');
+    const char = this.peek();
+    if (char === '0') {
+      this.pos += 1;
+      return false;
+    }
+    if (char === '1') {
+      this.pos += 1;
+      return true;
+    }
+    fail('boolean must be ?0 or ?1');
+  }
+}
+
+function isDigit(char) {
+  return char >= '0' && char <= '9';
+}
+function isLcAlpha(char) {
+  return char >= 'a' && char <= 'z';
+}
+function isAlpha(char) {
+  return (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z');
+}
+function isTokenChar(char) {
+  if (char === undefined) return false;
+  if (isAlpha(char) || isDigit(char)) return true;
+  return "!#$%&'*+-.^_`|~:/".includes(char);
+}
+
+/**
+ * Parses a Structured Field Dictionary (RFC 8941 §4.2.2).
+ *
+ * Each member's `raw` property is the EXACT source substring of that
+ * member's value. RFC 9421 §2.5 requires the `@signature-params` line of the
+ * signature base to reproduce the signature parameters as they were
+ * received, so re-serializing from the parse tree would be wrong: a signer
+ * that emitted, say, `alg="ed25519"` before `keyid=...` must still verify.
+ * We parse to validate and to read parameters; we use `raw` for the base.
+ *
+ * @param {string} input - raw header field value
+ * @returns {Map<string, { value: unknown, params: Map<string, unknown>, items?: Array<{value: unknown, params: Map<string, unknown>}>, isInnerList: boolean, raw: string }>}
+ */
+export function parseDictionary(input) {
+  if (typeof input !== 'string') fail('structured field value must be a string');
+  if (input.length > MAX_FIELD_LENGTH) fail('structured field value is too long');
+
+  const parser = new Parser(input);
+  const dictionary = new Map();
+
+  parser.skipSp();
+  while (!parser.done) {
+    const key = parser.parseKey();
+    let member;
+    const valueStart = parser.pos;
+    if (!parser.done && parser.peek() === '=') {
+      parser.pos += 1;
+      const parsed = parser.parseItemOrInnerList();
+      member = Array.isArray(parsed.items)
+        ? { value: parsed.items, items: parsed.items, params: parsed.params, isInnerList: true }
+        : { value: parsed.value, params: parsed.params, isInnerList: false };
+    } else {
+      // Bare key => boolean true with parameters (RFC 8941 §4.2.2).
+      member = { value: true, params: parser.parseParameters(), isInnerList: false };
+    }
+    // `raw` intentionally starts AFTER the "=" so it is exactly the value.
+    member.raw = input.slice(
+      parser.input[valueStart] === '=' ? valueStart + 1 : valueStart,
+      parser.pos,
+    );
+
+    if (dictionary.size >= MAX_MEMBERS) fail('too many dictionary members');
+    if (dictionary.has(key)) fail(`duplicate dictionary key "${key}"`);
+    dictionary.set(key, member);
+
+    parser.skipOws();
+    if (parser.done) return dictionary;
+    parser.expect(',');
+    parser.skipOws();
+    if (parser.done) fail('dictionary ends with a trailing comma');
+  }
+
+  return dictionary;
+}
+
+/**
+ * Parses a `Content-Digest` / `Content-Encoding`-style dictionary of byte
+ * sequences and returns a plain `algorithm -> Buffer` map.
+ *
+ * @param {string} input
+ * @returns {Map<string, Buffer>}
+ */
+export function parseByteSequenceDictionary(input) {
+  const dictionary = parseDictionary(input);
+  const out = new Map();
+  for (const [key, member] of dictionary) {
+    if (member.isInnerList || !(member.value instanceof ByteSequence)) {
+      fail(`dictionary member "${key}" must be a byte sequence`);
+    }
+    out.set(key.toLowerCase(), member.value.bytes);
+  }
+  return out;
+}
+
+/** Serializes bytes as an RFC 8941 Byte Sequence (`:base64:`). */
+export function serializeByteSequence(bytes) {
+  return `:${Buffer.from(bytes).toString('base64')}:`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsbloom/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Universal Node.js/Express SDK to convert any e-commerce store into an Agent-Ready API (UCP, ACP, AP2, WebMCP, Web Bot Auth).",
   "type": "module",
   "main": "./index.js",
@@ -10,6 +10,11 @@
       "types": "./index.d.ts",
       "import": "./index.js",
       "default": "./index.js"
+    },
+    "./protocol": {
+      "types": "./lib/protocol.d.ts",
+      "import": "./lib/protocol.js",
+      "default": "./lib/protocol.js"
     }
   },
   "files": [
@@ -17,8 +22,14 @@
     "index.d.ts",
     "telemetry.js",
     "lib/ap2.js",
+    "lib/http-signatures.js",
+    "lib/money.js",
     "lib/outcomes.js",
+    "lib/protocol.js",
+    "lib/protocol.d.ts",
     "lib/shared-store.js",
+    "lib/signature-base.js",
+    "lib/structured-fields.js",
     "README.md",
     "LICENSE",
     "SECURITY.md"
@@ -37,12 +48,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/insane-lotus/agentsbloom-cloud.git",
-    "directory": "packages/sdk"
+    "url": "https://github.com/AgentsBloom/sdk.git"
   },
-  "homepage": "https://github.com/insane-lotus/agentsbloom-cloud/tree/v2/packages/sdk#readme",
+  "homepage": "https://github.com/AgentsBloom/sdk#readme",
   "bugs": {
-    "url": "https://github.com/insane-lotus/agentsbloom-cloud/issues"
+    "url": "https://github.com/AgentsBloom/sdk/issues"
   },
   "engines": {
     "node": ">=20"
@@ -76,7 +86,7 @@
   },
   "scripts": {
     "test": "node --test \"test/*.test.js\"",
-    "lint": "node --check index.js && node --check telemetry.js && node --check lib/ap2.js && node --check scripts/check-package.mjs && node --check scripts/verify-consumer.mjs",
+    "lint": "node scripts/lint.mjs",
     "check:package": "node scripts/check-package.mjs",
     "verify:consumer": "node scripts/verify-consumer.mjs",
     "release:check": "npm run lint && npm test && npm run check:package && npm run verify:consumer && npm pack --dry-run --ignore-scripts",

package/telemetry.js

@@ -1,57 +1,77 @@
-/**
- * OTLP trace exporter initialization for the AgentsBloom SDK.
- *
- * The OpenTelemetry SDK packages required to actually export spans
- * (@opentelemetry/sdk-trace-node, sdk-trace-base, exporter-trace-otlp-http,
- * resources, semantic-conventions) are loaded via dynamic import() so that
- * a merchant application that never calls setupTelemetry() is never forced
- * to install them. They are declared as optionalDependencies in
- * package.json rather than dependencies.
- *
- * Dependency-audit note (2026-08): upgraded to the OpenTelemetry JS 2.x line
- * (sdk-trace-*@2.10, resources@2.10, exporter-trace-otlp-http@0.221) which
- * fixes GHSA-8988-4f7v-96qf and friends. The 2.x API differences this file
- * absorbs:
- *   - `Resource` class is gone -> `resourceFromAttributes()`
- *   - `SemanticResourceAttributes.SERVICE_NAME` is gone ->
- *       `ATTR_SERVICE_NAME` from @opentelemetry/semantic-conventions
- *   - `provider.register()` no longer accepts a global logger/meter; plain
- *     registration is still supported.
- */
-
-let optionalDependencyWarningLogged = false;
-
-export async function initExporter({ otlpEndpoint, serviceName, samplingRatio, apiKey } = {}) {
-  try {
-    const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');
-    const { BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-base');
-    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
-    const { resourceFromAttributes } = await import('@opentelemetry/resources');
-    let serviceNameKey;
-    try {
-      ({ ATTR_SERVICE_NAME: serviceNameKey } = await import('@opentelemetry/semantic-conventions'));
-    } catch {
-      // Very new/old semantic-conventions layouts fall back to the literal.
-      serviceNameKey = 'service.name';
-    }
-
-    const exporter = new OTLPTraceExporter({
-      url: `${otlpEndpoint}/v1/traces`,
-      headers: { Authorization: `Bearer ${apiKey}` },
-    });
-    // 2.x: span processors are passed at construction via `spanProcessors`
-    // (addSpanProcessor was removed from the public provider API).
-    const provider = new NodeTracerProvider({
-      resource: resourceFromAttributes({ [serviceNameKey || 'service.name']: serviceName }),
-      spanProcessors: [new BatchSpanProcessor(exporter)],
-    });
-    provider.register();
-    return { provider, exporter };
-  } catch (err) {
-    if (!optionalDependencyWarningLogged) {
-      optionalDependencyWarningLogged = true;
-      console.warn(`🌸 AgentsBloom: OTel SDK packages unavailable, continuing without export. (${err?.message || 'unknown reason'})`);
-    }
-    return null;
-  }
-}
+/**
+ * OTLP trace exporter initialization for the AgentsBloom SDK.
+ *
+ * The OpenTelemetry SDK packages required to actually export spans
+ * (@opentelemetry/sdk-trace-node, sdk-trace-base, exporter-trace-otlp-http,
+ * resources, semantic-conventions) are loaded via dynamic import() so that
+ * a merchant application that never calls setupTelemetry() is never forced
+ * to install them. They are declared as optionalDependencies in
+ * package.json rather than dependencies.
+ *
+ * Dependency-audit note (2026-08): upgraded to the OpenTelemetry JS 2.x line
+ * (sdk-trace-*@2.10, resources@2.10, exporter-trace-otlp-http@0.221) which
+ * fixes GHSA-8988-4f7v-96qf and friends. The 2.x API differences this file
+ * absorbs:
+ *   - `Resource` class is gone -> `resourceFromAttributes()`
+ *   - `SemanticResourceAttributes.SERVICE_NAME` is gone ->
+ *       `ATTR_SERVICE_NAME` from @opentelemetry/semantic-conventions
+ *   - `provider.register()` no longer accepts a global logger/meter; plain
+ *     registration is still supported.
+ */
+
+let optionalDependencyWarningLogged = false;
+
+export async function initExporter({ otlpEndpoint, serviceName, samplingRatio, apiKey } = {}) {
+  try {
+    const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');
+    const { BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-base');
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
+    const { resourceFromAttributes } = await import('@opentelemetry/resources');
+    let serviceNameKey;
+    try {
+      ({ ATTR_SERVICE_NAME: serviceNameKey } = await import('@opentelemetry/semantic-conventions'));
+    } catch {
+      // Very new/old semantic-conventions layouts fall back to the literal.
+      serviceNameKey = 'service.name';
+    }
+
+    const exporter = new OTLPTraceExporter({
+      url: `${otlpEndpoint}/v1/traces`,
+      // Only send an Authorization header when there is actually a credential;
+      // `Bearer ` with an empty value is a malformed header, not "no auth".
+      ...(apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {}),
+    });
+
+    // `samplingRatio` was accepted, logged as "sampling: N%", and then never
+    // used — every deployment exported 100% of spans regardless of the value,
+    // which is a cost and a data-volume surprise rather than a security bug,
+    // but it made the option a lie. Wire it up for real.
+    const ratio = Number.isFinite(samplingRatio) ? Math.min(1, Math.max(0, samplingRatio)) : 1;
+    let sampler;
+    if (ratio < 1) {
+      try {
+        const { TraceIdRatioBasedSampler, ParentBasedSampler } = await import('@opentelemetry/sdk-trace-base');
+        // Parent-based so a sampled distributed trace stays intact end to end.
+        sampler = new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) });
+      } catch {
+        sampler = undefined;
+      }
+    }
+
+    // 2.x: span processors are passed at construction via `spanProcessors`
+    // (addSpanProcessor was removed from the public provider API).
+    const provider = new NodeTracerProvider({
+      resource: resourceFromAttributes({ [serviceNameKey || 'service.name']: serviceName }),
+      spanProcessors: [new BatchSpanProcessor(exporter)],
+      ...(sampler ? { sampler } : {}),
+    });
+    provider.register();
+    return { provider, exporter };
+  } catch (err) {
+    if (!optionalDependencyWarningLogged) {
+      optionalDependencyWarningLogged = true;
+      console.warn(`🌸 AgentsBloom: OTel SDK packages unavailable, continuing without export. (${err?.message || 'unknown reason'})`);
+    }
+    return null;
+  }
+}