@adcp/sdk 14.0.0-rc.37 → 14.0.0-rc.39

package/dist/lib/testing/storyboard/junit.mjs

@@ -1,8 +1,20 @@
 import { collectDetachedAssertionFailures } from "../compliance/storyboard-tracks.mjs";
 import { randomBytes } from "node:crypto";
 function xmlEscape(s) {
-  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  return xmlSafeText(String(s ?? "")).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
+function xmlSafeText(value) {
+  return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, escapeCodeUnit).replace(/[\uFDD0-\uFDEF\uFFFE\uFFFF]/g, escapeCodeUnit);
+}
+function escapeCodeUnit(char) {
+  return `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}
+const RUNNER_AUTHORED_SKIP_REASONS = /* @__PURE__ */ new Set([
+  "capability_prerequisite_unavailable",
+  "session_probe_ungradable",
+  "fixture_unsatisfied"
+]);
+const MAX_SKIP_DETAIL_CHARS = 400;
 function hintLines(hints) {
   if (!hints || hints.length === 0) return [];
   return hints.map((h) => `Hint (${h.kind}): ${h.message}`);
@@ -18,6 +30,13 @@ function fenceUntrustedText(value, max = 500) {
 function formatAdvisoryFinding(validation) {
   return `[ADVISORY] ${fenceUntrustedText(validation.description)}: ${fenceUntrustedText(validation.error || "failed")}`;
 }
+function stepSkipMessage(step) {
+  const reason = step.skip_reason || "skipped";
+  const raw = step.skip?.detail;
+  if (raw === void 0 || !RUNNER_AUTHORED_SKIP_REASONS.has(step.skip_reason ?? "")) return reason;
+  const clipped = raw.length > MAX_SKIP_DETAIL_CHARS ? `${raw.slice(0, MAX_SKIP_DETAIL_CHARS)}\u2026` : raw;
+  return `${reason}: ${clipped}`;
+}
 function formatStoryboardResultsAsJUnit(results) {
   let totalTests = 0;
   let totalFailures = 0;
@@ -40,7 +59,7 @@ function formatStoryboardResultsAsJUnit(results) {
             totalSkipped += 1;
             suiteCases.push(
               `    <testcase classname="${xmlEscape(sb.storyboard_id)}" name="${xmlEscape(name)}" time="${time}">
-      <skipped message="${xmlEscape(step.skip_reason || "skipped")}"/>
+      <skipped message="${xmlEscape(stepSkipMessage(step))}"/>
     </testcase>`
             );
             continue;

package/dist/lib/testing/storyboard/probes.d.mts

@@ -93,6 +93,136 @@ export declare function rawMcpProbe(options: {
     httpResult: HttpProbeResult;
     taskResult?: TaskResult;
 }>;
+/**
+ * Lifecycle stage a session-probe verdict landed on.
+ *
+ * `tools/list` is deliberately absent: MCP discovery is not an AdCP protected
+ * task — `get_adcp_capabilities` is mandatory-public and the SDK's own
+ * unauthenticated capability path lists tools — so a `tools/list` answer is
+ * never graded evidence about this agent's authentication.
+ */
+export type McpSessionStage = 'initialize' | 'tools/call';
+/**
+ * Whether a credential is available to prove this endpoint accepts one, and
+ * that it is the right *kind* of credential for the mechanism under test.
+ *
+ * Required (not optional) on {@link rawMcpSessionProbe} so no caller can omit
+ * it and silently receive a conclusive verdict:
+ *
+ * - `credential` — drive a control lifecycle with these valid credentials.
+ * - `probe_is_valid_credential` — the credential under test *is* the run's
+ *   valid credential (a positive probe), so its own acceptance is the
+ *   evidence and a separate control would prove nothing.
+ * - `unavailable` — no credential of the required kind is configured. A
+ *   rejection then cannot be distinguished from an endpoint that refuses
+ *   everything, so the probe reports inconclusive. `reason` / `remedy` come
+ *   from the caller, which owns mechanism policy.
+ */
+export type McpSessionProbeControl = {
+    kind: 'credential';
+    headers: Record<string, string>;
+} | {
+    kind: 'probe_is_valid_credential';
+} | {
+    kind: 'unavailable';
+    reason: string;
+    remedy: string;
+};
+/**
+ * Probe an MCP agent's auth enforcement with a complete session lifecycle
+ * driven by the official SDK client — the auth probe for agents that advertise
+ * none of `PROBE_TASK_ALLOWLIST` (adcp-client#2940).
+ *
+ * See {@link runMcpSessionLifecycle} for the request sequence. Per credential
+ * state the probe calls exactly one read-only AdCP tool with empty arguments
+ * and mutates no agent state — mutating tasks are excluded from target
+ * selection — and the session is terminated through the transport's own
+ * `terminateSession()`.
+ *
+ * ## Credential discrimination (fail-closed)
+ *
+ * A rejection is only evidence that the agent validates credentials if a
+ * *valid* credential completes the same lifecycle on the same endpoint — an
+ * endpoint that refuses everything (down, firewalled, wrong tenant, gateway
+ * misconfiguration) is otherwise indistinguishable from one that enforces
+ * credentials correctly. {@link McpSessionProbeControl} is therefore a
+ * required argument, and the probe is conclusive in exactly two shapes:
+ *
+ * - `control.kind === 'credential'` and that control lifecycle is accepted;
+ * - `control.kind === 'probe_is_valid_credential'` whose own lifecycle
+ *   completed.
+ *
+ * Otherwise — control refused, no credential of the required kind configured,
+ * or a positive credential that never completed the protected operation — the
+ * probe returns the graded response as evidence **plus** an `error`, which
+ * fails the step instead of certifying an auth mechanism. Correct metadata
+ * alone can never earn a contribution, and the caller decides what counts as
+ * the right kind of credential so that (for example) a static API key cannot
+ * stand in for an OAuth access token.
+ *
+ * The same refusal applies when the graded attempt is **accepted** under a
+ * discrimination control: an acceptance is never characterised as rejection
+ * evidence. That check lives here rather than in the authored
+ * `http_status_in` validation so a storyboard that omits it — a future
+ * revision, a custom `--file` storyboard, an adopter's own narrative — cannot
+ * mint a contribution off a fail-open endpoint.
+ *
+ * **Credentials in, never out.** Credentials are sent to the agent and never
+ * written back onto the result. `wrapFetchWithCapture` already redacts
+ * credential-bearing response headers and `Bearer` spans; on top of that this
+ * function scrubs the exact values it sent — by value, across body, headers
+ * and error, failing closed at its traversal limits — because an agent that
+ * echoes the `Authorization` header it received into a tool description or a
+ * `WWW-Authenticate` parameter is invisible to name-based redaction, and on a
+ * positive probe that echo is the run's live credential.
+ */
+export declare function rawMcpSessionProbe(options: {
+    agentUrl: string;
+    /** Credentials under test. Empty for the unauthenticated probe. */
+    headers?: Record<string, string>;
+    /**
+     * Canonical AdCP tools to call with `{}` — the graded protected operation, in
+     * the runner's deterministic preference order. When the agent refuses the
+     * *shape* of the first, the next is tried: a shape refusal says nothing
+     * about credentials, and a target that needs arguments would otherwise make
+     * every probe inconclusive. See the runner's `protectedToolCandidates`.
+     */
+    toolName: string | readonly string[];
+    /** Acceptance control. Required — see {@link McpSessionProbeControl}. */
+    control: McpSessionProbeControl;
+    /** Allow http:// and private-IP agent URLs (dev loops). Default false. */
+    allowPrivateIp?: boolean;
+    /** Scoped fetch implementation for every request this probe makes. */
+    fetchFn?: typeof fetch;
+    /**
+     * Run-level cancellation, applied to every graded and control request.
+     *
+     * Best-effort session teardown is deliberately **not** bound to it: a run
+     * cancelled after `initialize` must still send its DELETE, so cleanup runs
+     * detached with its own short deadline.
+     */
+    signal?: AbortSignal;
+    /** Per-request cap handed to the SDK's `RequestOptions.timeout`. */
+    timeoutMs?: number;
+    /**
+     * Extra secret values to scrub from evidence even though this probe never
+     * sent them.
+     *
+     * The runner's other steps *do* forward `options.headers`, so a stateful
+     * agent can echo an adopter's `x-gateway-token` back on a later step even
+     * though the probe deliberately withholds it. Those values are still
+     * credentials, and the evidence seam is where they would get persisted.
+     */
+    redactValues?: readonly string[];
+}): Promise<{
+    httpResult: HttpProbeResult;
+    taskResult?: TaskResult;
+    stage: McpSessionStage;
+    /** Fixed-vocabulary description of the graded verdict. Never agent text. */
+    detail: string;
+    /** The exact canonical tool that was graded, so reports are auditable. */
+    gradedTool: string;
+}>;
 /**
  * POST a JSON-RPC 2.0 request to an A2A agent endpoint with caller-provided
  * headers. Bypasses the A2A SDK so raw HTTP status, headers, and JSON-RPC

package/dist/lib/testing/storyboard/probes.d.ts

@@ -93,6 +93,136 @@ export declare function rawMcpProbe(options: {
     httpResult: HttpProbeResult;
     taskResult?: TaskResult;
 }>;
+/**
+ * Lifecycle stage a session-probe verdict landed on.
+ *
+ * `tools/list` is deliberately absent: MCP discovery is not an AdCP protected
+ * task — `get_adcp_capabilities` is mandatory-public and the SDK's own
+ * unauthenticated capability path lists tools — so a `tools/list` answer is
+ * never graded evidence about this agent's authentication.
+ */
+export type McpSessionStage = 'initialize' | 'tools/call';
+/**
+ * Whether a credential is available to prove this endpoint accepts one, and
+ * that it is the right *kind* of credential for the mechanism under test.
+ *
+ * Required (not optional) on {@link rawMcpSessionProbe} so no caller can omit
+ * it and silently receive a conclusive verdict:
+ *
+ * - `credential` — drive a control lifecycle with these valid credentials.
+ * - `probe_is_valid_credential` — the credential under test *is* the run's
+ *   valid credential (a positive probe), so its own acceptance is the
+ *   evidence and a separate control would prove nothing.
+ * - `unavailable` — no credential of the required kind is configured. A
+ *   rejection then cannot be distinguished from an endpoint that refuses
+ *   everything, so the probe reports inconclusive. `reason` / `remedy` come
+ *   from the caller, which owns mechanism policy.
+ */
+export type McpSessionProbeControl = {
+    kind: 'credential';
+    headers: Record<string, string>;
+} | {
+    kind: 'probe_is_valid_credential';
+} | {
+    kind: 'unavailable';
+    reason: string;
+    remedy: string;
+};
+/**
+ * Probe an MCP agent's auth enforcement with a complete session lifecycle
+ * driven by the official SDK client — the auth probe for agents that advertise
+ * none of `PROBE_TASK_ALLOWLIST` (adcp-client#2940).
+ *
+ * See {@link runMcpSessionLifecycle} for the request sequence. Per credential
+ * state the probe calls exactly one read-only AdCP tool with empty arguments
+ * and mutates no agent state — mutating tasks are excluded from target
+ * selection — and the session is terminated through the transport's own
+ * `terminateSession()`.
+ *
+ * ## Credential discrimination (fail-closed)
+ *
+ * A rejection is only evidence that the agent validates credentials if a
+ * *valid* credential completes the same lifecycle on the same endpoint — an
+ * endpoint that refuses everything (down, firewalled, wrong tenant, gateway
+ * misconfiguration) is otherwise indistinguishable from one that enforces
+ * credentials correctly. {@link McpSessionProbeControl} is therefore a
+ * required argument, and the probe is conclusive in exactly two shapes:
+ *
+ * - `control.kind === 'credential'` and that control lifecycle is accepted;
+ * - `control.kind === 'probe_is_valid_credential'` whose own lifecycle
+ *   completed.
+ *
+ * Otherwise — control refused, no credential of the required kind configured,
+ * or a positive credential that never completed the protected operation — the
+ * probe returns the graded response as evidence **plus** an `error`, which
+ * fails the step instead of certifying an auth mechanism. Correct metadata
+ * alone can never earn a contribution, and the caller decides what counts as
+ * the right kind of credential so that (for example) a static API key cannot
+ * stand in for an OAuth access token.
+ *
+ * The same refusal applies when the graded attempt is **accepted** under a
+ * discrimination control: an acceptance is never characterised as rejection
+ * evidence. That check lives here rather than in the authored
+ * `http_status_in` validation so a storyboard that omits it — a future
+ * revision, a custom `--file` storyboard, an adopter's own narrative — cannot
+ * mint a contribution off a fail-open endpoint.
+ *
+ * **Credentials in, never out.** Credentials are sent to the agent and never
+ * written back onto the result. `wrapFetchWithCapture` already redacts
+ * credential-bearing response headers and `Bearer` spans; on top of that this
+ * function scrubs the exact values it sent — by value, across body, headers
+ * and error, failing closed at its traversal limits — because an agent that
+ * echoes the `Authorization` header it received into a tool description or a
+ * `WWW-Authenticate` parameter is invisible to name-based redaction, and on a
+ * positive probe that echo is the run's live credential.
+ */
+export declare function rawMcpSessionProbe(options: {
+    agentUrl: string;
+    /** Credentials under test. Empty for the unauthenticated probe. */
+    headers?: Record<string, string>;
+    /**
+     * Canonical AdCP tools to call with `{}` — the graded protected operation, in
+     * the runner's deterministic preference order. When the agent refuses the
+     * *shape* of the first, the next is tried: a shape refusal says nothing
+     * about credentials, and a target that needs arguments would otherwise make
+     * every probe inconclusive. See the runner's `protectedToolCandidates`.
+     */
+    toolName: string | readonly string[];
+    /** Acceptance control. Required — see {@link McpSessionProbeControl}. */
+    control: McpSessionProbeControl;
+    /** Allow http:// and private-IP agent URLs (dev loops). Default false. */
+    allowPrivateIp?: boolean;
+    /** Scoped fetch implementation for every request this probe makes. */
+    fetchFn?: typeof fetch;
+    /**
+     * Run-level cancellation, applied to every graded and control request.
+     *
+     * Best-effort session teardown is deliberately **not** bound to it: a run
+     * cancelled after `initialize` must still send its DELETE, so cleanup runs
+     * detached with its own short deadline.
+     */
+    signal?: AbortSignal;
+    /** Per-request cap handed to the SDK's `RequestOptions.timeout`. */
+    timeoutMs?: number;
+    /**
+     * Extra secret values to scrub from evidence even though this probe never
+     * sent them.
+     *
+     * The runner's other steps *do* forward `options.headers`, so a stateful
+     * agent can echo an adopter's `x-gateway-token` back on a later step even
+     * though the probe deliberately withholds it. Those values are still
+     * credentials, and the evidence seam is where they would get persisted.
+     */
+    redactValues?: readonly string[];
+}): Promise<{
+    httpResult: HttpProbeResult;
+    taskResult?: TaskResult;
+    stage: McpSessionStage;
+    /** Fixed-vocabulary description of the graded verdict. Never agent text. */
+    detail: string;
+    /** The exact canonical tool that was graded, so reports are auditable. */
+    gradedTool: string;
+}>;
 /**
  * POST a JSON-RPC 2.0 request to an A2A agent endpoint with caller-provided
  * headers. Bypasses the A2A SDK so raw HTTP status, headers, and JSON-RPC