@adcp/sdk 5.23.0

package/bin/adcp-signing.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+const { generateKeyPairSync } = require('node:crypto');
+const { readFileSync, writeFileSync, existsSync } = require('node:fs');
+const path = require('node:path');
+
+const {
+  InMemoryReplayStore,
+  InMemoryRevocationStore,
+  RequestSignatureError,
+  StaticJwksResolver,
+  verifyRequestSignature,
+} = require('../dist/lib/signing/index.js');
+
+function generateKey(argv) {
+  let alg = 'ed25519';
+  let kid;
+  let outPrivate;
+  let outPublic;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--alg') alg = argv[++i];
+    else if (a === '--kid') kid = argv[++i];
+    else if (a === '--out' || a === '--private-out') outPrivate = argv[++i];
+    else if (a === '--public-out' || a === '--jwk-out') outPublic = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      printGenerateHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown flag: ${a}`);
+      printGenerateHelp();
+      process.exit(2);
+    }
+  }
+  if (alg !== 'ed25519' && alg !== 'es256') {
+    console.error(`--alg must be ed25519 or es256 (got ${alg})`);
+    process.exit(2);
+  }
+  if (!kid) {
+    const year = new Date().getUTCFullYear();
+    kid = `adcp-${alg}-${year}`;
+  }
+
+  const { publicKey, privateKey } =
+    alg === 'ed25519' ? generateKeyPairSync('ed25519') : generateKeyPairSync('ec', { namedCurve: 'P-256' });
+
+  const jwkAlg = alg === 'ed25519' ? 'EdDSA' : 'ES256';
+  const privateJwk = privateKey.export({ format: 'jwk' });
+  const publicJwk = publicKey.export({ format: 'jwk' });
+  publicJwk.kid = kid;
+  publicJwk.alg = jwkAlg;
+  publicJwk.use = 'sig';
+  publicJwk.key_ops = ['verify'];
+  publicJwk.adcp_use = 'request-signing';
+
+  const privatePem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+  if (outPrivate) {
+    writeFileSync(outPrivate, privatePem, { mode: 0o600 });
+    console.log(`✔ Private key written: ${outPrivate}`);
+  } else {
+    process.stdout.write(privatePem);
+  }
+
+  const publicJson = JSON.stringify({ keys: [publicJwk] }, null, 2);
+  if (outPublic) {
+    writeFileSync(outPublic, publicJson);
+    console.log(`✔ JWKS written: ${outPublic}`);
+  } else {
+    console.log('\n// Publish this JWKS at the jwks_uri of your agents[] entry:');
+    console.log(publicJson);
+  }
+  // Print the private JWK to stdout ONLY when the user explicitly wants it
+  // rendered (no --private-out). Otherwise the private key has already been
+  // written to a 0600 file and we must not leak it into terminal/shell history.
+  if (!outPrivate) {
+    privateJwk.kid = kid;
+    privateJwk.alg = jwkAlg;
+    privateJwk.use = 'sig';
+    privateJwk.key_ops = ['sign'];
+    privateJwk.adcp_use = 'request-signing';
+    console.log(
+      `\n// Private JWK (keep secret — load via { signing_key, keyid: "${kid}", alg: "${alg === 'ed25519' ? 'ed25519' : 'ecdsa-p256-sha256'}" }):`
+    );
+    console.log(JSON.stringify(privateJwk, null, 2));
+  }
+}
+
+async function verifyVector(argv) {
+  let vectorPath;
+  let keysPath;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--vector') vectorPath = argv[++i];
+    else if (a === '--keys') keysPath = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      printVerifyHelp();
+      process.exit(0);
+    } else if (!vectorPath) vectorPath = a;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      printVerifyHelp();
+      process.exit(2);
+    }
+  }
+  if (!vectorPath) {
+    printVerifyHelp();
+    process.exit(2);
+  }
+  if (!existsSync(vectorPath)) {
+    console.error(`Vector file not found: ${vectorPath}`);
+    process.exit(2);
+  }
+  const defaultKeys = path.join(
+    __dirname,
+    '..',
+    'compliance',
+    'cache',
+    'latest',
+    'test-vectors',
+    'request-signing',
+    'keys.json'
+  );
+  const keysJsonPath = keysPath ?? (existsSync(defaultKeys) ? defaultKeys : null);
+  if (!keysJsonPath) {
+    console.error(
+      'No --keys file provided and no default spec keys.json found. Run `npm run sync-schemas` first, or pass --keys <path>.'
+    );
+    process.exit(2);
+  }
+  const keys = JSON.parse(readFileSync(keysJsonPath, 'utf8')).keys;
+  const keysByKid = new Map(keys.map(k => [k.kid, k]));
+  const vector = JSON.parse(readFileSync(vectorPath, 'utf8'));
+  const now = vector.reference_now ?? Math.floor(Date.now() / 1000);
+
+  const replayStore = new InMemoryReplayStore();
+  const revocationStore = new InMemoryRevocationStore();
+  const state = vector.test_harness_state ?? {};
+  if (state.replay_cache_entries) {
+    for (const entry of state.replay_cache_entries) {
+      replayStore.preload(entry.keyid, entry.nonce, entry.ttl_seconds, now);
+    }
+  }
+  if (state.revocation_list) revocationStore.load(state.revocation_list);
+  if (state.replay_cache_per_keyid_cap_hit) {
+    replayStore.setCapHitForTesting(state.replay_cache_per_keyid_cap_hit.keyid);
+  }
+
+  const jwksEntries = vector.jwks_override
+    ? vector.jwks_override.keys
+    : (vector.jwks_ref ?? []).map(kid => keysByKid.get(kid)).filter(Boolean);
+  const jwks = new StaticJwksResolver(jwksEntries);
+  const operation = new URL(vector.request.url).pathname.split('/').filter(Boolean).pop();
+
+  try {
+    const verified = await verifyRequestSignature(vector.request, {
+      capability: vector.verifier_capability,
+      jwks,
+      replayStore,
+      revocationStore,
+      now: () => now,
+      operation,
+    });
+    console.log(JSON.stringify({ outcome: 'accepted', verified_signer: verified, operation }, null, 2));
+    return { accepted: true };
+  } catch (err) {
+    if (err instanceof RequestSignatureError) {
+      const payload = {
+        outcome: 'rejected',
+        error_code: err.code,
+        failed_step: err.failedStep,
+        message: err.message,
+      };
+      console.log(JSON.stringify(payload, null, 2));
+      return { accepted: false, code: err.code };
+    }
+    throw err;
+  }
+}
+
+function printGenerateHelp() {
+  console.log(`Usage: adcp signing generate-key [options]
+
+Generate an Ed25519 (default) or P-256 keypair for AdCP request signing.
+Writes or prints a PEM-encoded PKCS#8 private key + a one-key JWKS you can
+publish at your agent's jwks_uri.
+
+Options:
+  --alg <ed25519|es256>   Signature algorithm (default: ed25519).
+  --kid <value>           JWK kid. Default: adcp-<alg>-<year>.
+  --private-out <path>    Write private PEM to a file (mode 0600) instead of stdout.
+  --public-out <path>     Write JWKS JSON to a file instead of stdout.
+  -h, --help              Show this help.
+`);
+}
+
+function printVerifyHelp() {
+  console.log(`Usage: adcp signing verify-vector --vector <path> [--keys <keys.json>]
+
+Run a single RFC 9421 test vector through the AdCP verifier. Useful for
+debugging conformance failures against the spec's positive/negative vectors
+at compliance/cache/latest/test-vectors/request-signing/.
+
+If --keys is omitted, defaults to the bundled spec keys.json.
+`);
+}
+
+function printSigningHelp() {
+  console.log(`Usage: adcp signing <subcommand>
+
+Subcommands:
+  generate-key       Generate an Ed25519/P-256 keypair + JWKS for publication.
+  verify-vector      Run one RFC 9421 test vector through the verifier.
+`);
+}
+
+async function handleSigningCommand(argv) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printSigningHelp();
+    process.exit(0);
+  }
+  const [sub, ...rest] = argv;
+  if (sub === 'generate-key') return generateKey(rest);
+  if (sub === 'verify-vector') {
+    const result = await verifyVector(rest);
+    process.exit(result.accepted ? 0 : 1);
+  }
+  console.error(`Unknown signing subcommand: ${sub}`);
+  printSigningHelp();
+  process.exit(2);
+}
+
+module.exports = { handleSigningCommand };

package/bin/adcp-step-hints.js

@@ -0,0 +1,246 @@
+/**
+ * Human-console renderer for `StoryboardStepResult.hints[]` (adcp-client#879).
+ *
+ * Extracted from bin/adcp.js so the formatting logic is unit-testable
+ * without spawning the CLI. The JUnit equivalent lives in
+ * `src/lib/testing/storyboard/junit.ts` — it emits structured XML rather
+ * than console lines, so the two surfaces don't share a helper.
+ *
+ * The runner populates `hints[]` when it can trace a seller rejection
+ * back to a prior-step `$context.*` write (adcp-client#870). Surfacing
+ * them on the CLI collapses "SDK bug vs seller bug" triage to one line.
+ */
+
+const HINT_LABEL = '💡 Hint: ';
+// `💡` renders as a single visible glyph but is a surrogate pair (2 UTF-16
+// code units). For continuation-line alignment we want N visible columns of
+// padding to match the prefix's visible width. Hardcoded rather than
+// computed via grapheme APIs because it's stable.
+const HINT_LABEL_VISIBLE_WIDTH = 9; // "💡 Hint: " = 1 emoji + 8 ASCII chars
+const FALLBACK_WIDTH = 100;
+const MIN_BODY_WIDTH = 40;
+
+/**
+ * Resolve the wrap target. Prefer the live TTY width; fall back to the
+ * `COLUMNS` env var (commonly set by `tput`-aware shells); otherwise 100
+ * (a comfortable read width that doesn't waste space on wide terminals).
+ */
+function resolveWidth() {
+  if (process.stdout.isTTY && typeof process.stdout.columns === 'number' && process.stdout.columns > 0) {
+    return process.stdout.columns;
+  }
+  const env = Number.parseInt(process.env.COLUMNS ?? '', 10);
+  if (Number.isFinite(env) && env > 0) return env;
+  return FALLBACK_WIDTH;
+}
+
+/**
+ * Word-wrap `text` at `bodyWidth` characters. Preserves whitespace runs
+ * and tries to keep `\`code\`` segments on a single line when they fit.
+ * Always honors `bodyWidth` even inside a fenced run — splitting a fence
+ * is unfortunate but bounded; silent overflow is worse.
+ *
+ * Edge cases the algorithm handles explicitly:
+ *  - Stray unmatched backtick → up-front parity check disables fence-
+ *    aware glue entirely so the message can't fall into "openTick forever"
+ *    and produce one runaway line (adcp-client review on #925).
+ *  - Single token longer than `bodyWidth` (e.g. a 200-char URL) →
+ *    hard-break the token into bodyWidth-sized chunks so the wrap
+ *    invariant survives degenerate inputs.
+ *
+ * Returns an array of lines (no leading whitespace; caller adds indent).
+ */
+function wrap(text, bodyWidth) {
+  if (bodyWidth <= 0) return [text];
+
+  // Up-front fence-parity check. If the message has unbalanced backticks,
+  // ignore them entirely for wrapping purposes — otherwise a stray ` puts
+  // the algorithm into permanent glue mode and the line blows past width.
+  const respectFences = (text.match(/`/g) ?? []).length % 2 === 0;
+
+  const words = text.split(/(\s+)/).filter(s => s.length > 0);
+  const lines = [];
+  let line = '';
+  let openTickInLine = false;
+  const flipTickIf = tok => {
+    if (!respectFences) return;
+    if ((tok.match(/`/g) ?? []).length % 2 === 1) openTickInLine = !openTickInLine;
+  };
+  const flushLine = () => {
+    if (line.length > 0) lines.push(line.trimEnd());
+    line = '';
+  };
+
+  for (const tok of words) {
+    const isWS = /^\s+$/.test(tok);
+    if (isWS) {
+      // Whitespace either rides the current line or — if it'd push past
+      // the body width AND we're not mid-fence — forces a wrap.
+      if (!openTickInLine && line.length + tok.length > bodyWidth) {
+        flushLine();
+        continue;
+      }
+      line += tok;
+      continue;
+    }
+    // Hard-break oversized single tokens. A 200-char URL with no internal
+    // whitespace would otherwise sit on one line and overflow regardless
+    // of all other heuristics. Chop it at body-width boundaries.
+    if (tok.length > bodyWidth) {
+      flushLine();
+      let rest = tok;
+      while (rest.length > bodyWidth) {
+        lines.push(rest.slice(0, bodyWidth));
+        rest = rest.slice(bodyWidth);
+      }
+      line = rest;
+      flipTickIf(tok);
+      continue;
+    }
+    if (line.length === 0) {
+      line = tok;
+      flipTickIf(tok);
+      continue;
+    }
+    if (openTickInLine && line.length + tok.length <= bodyWidth) {
+      // Inside a fence and the token fits — glue.
+      line += tok;
+      flipTickIf(tok);
+      continue;
+    }
+    // Either mid-fence-but-overflowing, or normal-mode-but-overflowing —
+    // either way wrap. Splitting a fence is acceptable; silent overflow is
+    // not (the operator's eye depends on the wrap invariant).
+    if (line.length + tok.length > bodyWidth) {
+      flushLine();
+      line = tok;
+      flipTickIf(tok);
+      continue;
+    }
+    line += tok;
+    flipTickIf(tok);
+  }
+  flushLine();
+  return lines;
+}
+
+/**
+ * Build the per-kind structured detail line(s) appended after the prose
+ * `message` so renderers / operators / LLMs see the machine-readable
+ * fields without having to regex-parse the message text. Each detail
+ * is a single short line (`├─ <label>: <value>`) suitable for the
+ * console; dropping into JSON-line / JUnit consumers stays trivial
+ * because the same fields exist on the structured hint object.
+ *
+ * The function returns an array (zero or more lines). An unknown
+ * `kind` returns `[]` so the renderer falls back to the prose-only
+ * surface — issue #935's forward-contract for new hint kinds.
+ */
+function structuredDetailLines(hint) {
+  if (!hint || typeof hint !== 'object') return [];
+  switch (hint.kind) {
+    case 'context_value_rejected':
+      return [
+        `key: $context.${hint.context_key}`,
+        `from step: ${hint.source_step_id}${hint.source_task ? ` (${hint.source_task})` : ''}`,
+        ...(Array.isArray(hint.accepted_values) && hint.accepted_values.length > 0
+          ? [`seller accepted: ${formatList(hint.accepted_values)}`]
+          : []),
+      ];
+    case 'shape_drift':
+      return [
+        `tool: ${hint.tool}`,
+        `observed: ${hint.observed_variant}`,
+        `expected: ${hint.expected_variant}`,
+        ...(hint.instance_path ? [`at: ${hint.instance_path}`] : []),
+      ];
+    case 'missing_required_field':
+      return [
+        `tool: ${hint.tool}`,
+        `at: ${hint.instance_path || '/'}`,
+        `missing: ${formatList(hint.missing_fields ?? [])}`,
+      ];
+    case 'format_mismatch':
+      return [`tool: ${hint.tool}`, `at: ${hint.instance_path || '/'}`, `keyword: ${hint.keyword}`];
+    case 'monotonic_violation':
+      return [
+        `${hint.resource_type} ${hint.resource_id}: ${hint.from_status} → ${hint.to_status}`,
+        `from step: ${hint.from_step_id}`,
+        `legal next states: ${
+          Array.isArray(hint.legal_next_states) && hint.legal_next_states.length > 0
+            ? formatList(hint.legal_next_states)
+            : '(none — terminal state)'
+        }`,
+      ];
+    default:
+      return [];
+  }
+}
+
+function formatList(values) {
+  return values.map(v => (typeof v === 'string' ? v : JSON.stringify(v))).join(', ');
+}
+
+/**
+ * Print each hint on its own block, prefixed with the hint icon. `indent`
+ * should match the caller's `Error:` indent so hints group visually —
+ * 3 spaces for the full storyboard printer (which nests steps under
+ * phases), empty for the single-step printer (`adcp storyboard step`)
+ * that prints error/validation lines at column zero.
+ *
+ * Long messages are word-wrapped to the terminal width (or 100 cols when
+ * stdout isn't a TTY) with continuation lines aligned under the message
+ * text, so a wrapped hint reads as a paragraph rather than a runaway line.
+ * After the prose, structured detail lines for the hint's `kind` (issue
+ * #935) print one-per-line so the operator sees both surfaces:
+ *
+ *   💡 Hint: list_creatives returned a bare array at the top level...
+ *            tool: list_creatives
+ *            observed: bare_array
+ *            expected: { creatives: [...] }
+ */
+function printStepHints(hints, indent = '   ') {
+  if (!Array.isArray(hints) || hints.length === 0) return;
+  const width = resolveWidth();
+  // Body width = total - indent - "💡 Hint: " prefix; clamp so we never
+  // produce a body of 1–2 chars on a freakishly narrow terminal.
+  const bodyWidth = Math.max(MIN_BODY_WIDTH, width - indent.length - HINT_LABEL_VISIBLE_WIDTH);
+  const continuationIndent = indent + ' '.repeat(HINT_LABEL_VISIBLE_WIDTH);
+  for (const h of hints) {
+    const message = typeof h?.message === 'string' ? h.message : '';
+    const lines = wrap(message, bodyWidth);
+    if (lines.length === 0 && structuredDetailLines(h).length === 0) continue;
+    if (lines.length > 0) {
+      console.log(`${indent}${HINT_LABEL}${lines[0]}`);
+      for (let i = 1; i < lines.length; i++) {
+        console.log(`${continuationIndent}${lines[i]}`);
+      }
+    }
+    for (const detail of structuredDetailLines(h)) {
+      // Wrap structured detail too — long accepted-values lists or schema
+      // fragments would otherwise blow past the terminal width.
+      const detailLines = wrap(detail, bodyWidth);
+      for (const dl of detailLines) {
+        console.log(`${continuationIndent}${dl}`);
+      }
+    }
+  }
+}
+
+/**
+ * Count the total hints across every phase × step in a `StoryboardResult`.
+ * Used by the run-summary line so operators see at a glance whether the
+ * runner emitted any diagnostics, without scrolling the per-step output.
+ */
+function countHintsInResult(result) {
+  if (!result || !Array.isArray(result.phases)) return 0;
+  let n = 0;
+  for (const phase of result.phases) {
+    for (const step of phase.steps ?? []) {
+      n += Array.isArray(step.hints) ? step.hints.length : 0;
+    }
+  }
+  return n;
+}
+
+module.exports = { printStepHints, countHintsInResult };

package/bin/adcp-version-check.js

@@ -0,0 +1,150 @@
+/**
+ * CLI startup staleness check.
+ *
+ * Unpinned `npx @adcp/sdk` reuses whatever version is cached in
+ * ~/.npm/_npx/ — users run months-old code without knowing. Doc pins
+ * to `@latest` fix the copy-paste path; this catches every other way
+ * stale code lands (global installs, locked package.json, corporate
+ * forks, pnpm dlx cache).
+ *
+ * Runs once per 24h via a cache file. Fails silent on any network or
+ * filesystem hiccup — a staleness warning must never break a CLI call.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+
+const CONFIG_DIR = path.join(os.homedir(), '.adcp');
+const CACHE_FILE = path.join(CONFIG_DIR, 'version-check.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 800;
+const REGISTRY_URL = 'https://registry.npmjs.org/@adcp/sdk/latest';
+
+function shouldSkipCheck() {
+  if (process.env.ADCP_SKIP_VERSION_CHECK === '1') return true;
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (!process.stderr.isTTY) return true;
+  if (process.argv.includes('--json')) return true;
+  return false;
+}
+
+function readCache() {
+  try {
+    const raw = fs.readFileSync(CACHE_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.latestVersion !== 'string') return null;
+    if (typeof parsed?.checkedAt !== 'number') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(latestVersion) {
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ latestVersion, checkedAt: Date.now() }), 'utf8');
+  } catch {
+    /* fail silent */
+  }
+}
+
+function fetchLatest() {
+  return new Promise(resolve => {
+    const req = https.get(REGISTRY_URL, { headers: { accept: 'application/json' }, timeout: FETCH_TIMEOUT_MS }, res => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        resolve(null);
+        return;
+      }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => {
+        body += chunk;
+        // Abort runaway responses — the registry's `latest` entry is ~2KB.
+        if (body.length > 64 * 1024) req.destroy();
+      });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(body);
+          resolve(typeof parsed.version === 'string' ? parsed.version : null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+// Semver ordering without a dep: compare numeric segments of the leading
+// `x.y.z`. Pre-release suffixes are treated as equal to the base release,
+// which is the right call for a staleness nudge — we don't want to tell a
+// user on 5.13.0 that 5.14.0-next.3 is "newer" and they should upgrade.
+function compareVersions(a, b) {
+  const parse = v =>
+    v
+      .split('-')[0]
+      .split('.')
+      .map(n => parseInt(n, 10));
+  const aa = parse(a);
+  const bb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = aa[i] ?? 0;
+    const y = bb[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function printStaleWarning(current, latest) {
+  process.stderr.write(
+    `\n⚠️  Running @adcp/sdk ${current} — latest is ${latest}.\n` +
+      `   Upgrade with \`npx @adcp/sdk@latest …\` (or clear \`~/.npm/_npx\` if you copy-pasted commands without the @latest pin).\n` +
+      `   Silence this check with ADCP_SKIP_VERSION_CHECK=1.\n\n`
+  );
+}
+
+/**
+ * Schedule a staleness check. Returns immediately — the actual network
+ * fetch (if needed) runs on `process.nextTick` so command dispatch is
+ * never blocked. The warning, if any, prints to stderr before the
+ * process exits naturally.
+ */
+function scheduleVersionCheck(currentVersion) {
+  if (shouldSkipCheck()) return;
+
+  const cache = readCache();
+  const fresh = cache && Date.now() - cache.checkedAt < CACHE_TTL_MS;
+
+  if (fresh) {
+    if (compareVersions(currentVersion, cache.latestVersion) < 0) {
+      printStaleWarning(currentVersion, cache.latestVersion);
+    }
+    return;
+  }
+
+  // Stale cache or no cache — fetch in the background. The command is
+  // already running; we just want to catch the warning before exit if
+  // we can, and otherwise refresh the cache for the next invocation.
+  process.nextTick(async () => {
+    const latest = await fetchLatest();
+    if (!latest) return;
+    writeCache(latest);
+    if (compareVersions(currentVersion, latest) < 0) {
+      printStaleWarning(currentVersion, latest);
+    }
+  });
+}
+
+module.exports = { scheduleVersionCheck };