@adcp/sdk 15.0.0 → 15.2.1

package/dist/lib/server/a2a-adapter.mjs

@@ -9,12 +9,22 @@ import { AgentCard, Role, TaskState } from "@a2a-js/sdk";
 import { duplicateInterfacesForLegacy } from "@a2a-js/sdk/compat/v0_3";
 import { randomUUID } from "node:crypto";
 import { redactSecrets } from "../utils/redact-secrets.mjs";
+import {
+  describeUnresolvable,
+  resolveRequestOperation,
+  isUnresolvableOperation
+} from "../signing/operation-resolution.mjs";
 import {
   getSdkServer,
   isToolAvailableForVersion,
   listRegisteredToolNames,
   resolveDiscoveryVersion
 } from "./adcp-server.mjs";
+import {
+  ADCP_PRE_TRANSPORT,
+  ADCP_SIGNED_REQUESTS_STATE
+} from "./create-adcp-server.mjs";
+import { ADCP_SERVE_REQUEST_CONTEXT } from "./auth.mjs";
 class RedactingA2ATaskStore {
   constructor(delegate) {
     this.delegate = delegate;
@@ -30,7 +40,7 @@ class RedactingA2ATaskStore {
     return this.delegate.list(params, context);
   }
 }
-function buildAuthenticatedUser(authInfo) {
+function buildAuthenticatedUser(authInfo, gate) {
   const clientId = authInfo.clientId;
   return {
     get isAuthenticated() {
@@ -39,23 +49,29 @@ function buildAuthenticatedUser(authInfo) {
     get userName() {
       return clientId;
     },
-    adcpAuthInfo: authInfo
+    adcpAuthInfo: authInfo,
+    ...gate && { adcpGate: gate }
   };
 }
-function buildAnonymousUser() {
+function buildAnonymousUser(gate) {
   return {
     get isAuthenticated() {
       return false;
     },
     get userName() {
       return "anonymous";
-    }
+    },
+    ...gate && { adcpGate: gate }
   };
 }
 function getAdcpAuthInfo(context) {
   const user = context?.user;
   return user?.adcpAuthInfo;
 }
+function getGateState(context) {
+  const user = context?.user;
+  return user?.adcpGate;
+}
 function extractInvocation(message, allowLegacyParameters = false) {
   if (!Array.isArray(message.parts) || message.parts.length === 0) {
     throw new A2AInvocationError("Message must carry at least one part with a `data` kind.");
@@ -92,6 +108,15 @@ function extractInvocation(message, allowLegacyParameters = false) {
   }
   return { skill, input };
 }
+function operationTaskWasCreatedFor(task) {
+  const first = task.history?.[0];
+  if (!first) return void 0;
+  try {
+    return extractInvocation(first, true).skill;
+  } catch {
+    return void 0;
+  }
+}
 class A2AInvocationError extends Error {
   constructor(message) {
     super(message);
@@ -163,6 +188,28 @@ class AdcpA2AAgentExecutor {
         });
         return;
       }
+      const gate = getGateState(requestContext.context);
+      if (gate && gate.operation !== invocation.skill) {
+        this.logger.error("A2A adapter: dispatcher operation differs from the signature gate", {
+          gateOperation: gate.operation === void 0 ? void 0 : JSON.stringify(gate.operation.slice(0, 64)),
+          requestedToolName: JSON.stringify(invocation.skill.slice(0, 64))
+        });
+        this.emitFailure(eventBus, taskId, contextId, {
+          reason: "INVALID_REQUEST",
+          message: "The request does not resolve to a single AdCP operation."
+        });
+        return;
+      }
+      if (requestContext.task) {
+        const createdFor = operationTaskWasCreatedFor(requestContext.task);
+        if (createdFor !== invocation.skill) {
+          this.emitFailure(eventBus, taskId, contextId, {
+            reason: "INVALID_REQUEST",
+            message: "A task continuation must use the operation the task was created for."
+          });
+          return;
+        }
+      }
       let response;
       const toolNames = a2aSkillToServerToolNames(invocation.skill);
       let invokedToolName;
@@ -563,6 +610,157 @@ function validateAgentCard(card) {
     );
   }
 }
+const MAX_GATED_BODY_BYTES = 100 * 1024;
+class BodyTooLargeError extends Error {
+}
+function captureRawBody(req, _res, buf) {
+  req.rawBody = buf.toString("utf8");
+}
+function resolveSignatureGate(options) {
+  const symbols = options.server;
+  const attached = symbols[ADCP_PRE_TRANSPORT];
+  const gate = options.preTransport ?? (typeof attached === "function" ? attached : void 0);
+  if (gate) return gate;
+  const state = symbols[ADCP_SIGNED_REQUESTS_STATE];
+  if ((state?.specialismClaimed || state?.capabilitySupported) && !options.allowUnenforcedSignedRequests) {
+    throw new Error(
+      "createA2AAdapter: the server advertises request signing (`signed-requests` / `request_signing.supported`) but no signature verifier is wired for A2A, so `required_for` would not be enforced over A2A. Configure `createAdcpServer({ signedRequests })`, pass the same verifier as `preTransport`, or set `allowUnenforcedSignedRequests: true` if a gateway in front of this adapter enforces it."
+    );
+  }
+  return void 0;
+}
+class InvalidRequestTargetError extends Error {
+}
+function signedRequestTargetUrl(req, agentUrl, override) {
+  if (override) return new URL(override(req));
+  const raw = req.originalUrl || req.url;
+  if (!raw.startsWith("/") || raw.startsWith("//")) throw new InvalidRequestTargetError();
+  const requested = new URL(raw, "http://placeholder.invalid");
+  return new URL(requested.pathname + requested.search, new URL(agentUrl).origin);
+}
+function createSignatureGate(opts) {
+  const { gate, next: sdkHandler, gateStates, targetUrl, logger } = opts;
+  const reject = (res, code, message) => {
+    res.status(401).set("WWW-Authenticate", `Signature error="${code}"`).json({ error: code, message });
+  };
+  const run = async (req, res) => {
+    const gated = req;
+    if (gated.rawBody === void 0) {
+      const encoding = req.headers["content-encoding"];
+      if (encoding !== void 0 && encoding.trim().toLowerCase() !== "identity") {
+        res.status(415).json({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32600, message: "Content-Encoding is not supported on a signed-requests endpoint." }
+        });
+        return false;
+      }
+      try {
+        const body = await readBody(req);
+        if (body !== void 0) {
+          gated.rawBody = body;
+          try {
+            gated.body = JSON.parse(body);
+            gated._body = true;
+          } catch {
+          }
+        }
+      } catch (err) {
+        if (!(err instanceof BodyTooLargeError)) throw err;
+        res.status(413).json({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Request body too large." } });
+        return false;
+      }
+    }
+    const captured = gated.rawBody;
+    const rawBody = typeof captured === "string" ? captured : captured?.toString("utf8");
+    if (rawBody === void 0) {
+      logger.error(
+        "A2A adapter: the raw request body is unavailable, so the signature gate cannot verify it. Mount the adapter ahead of any body parser, or capture the bytes with `express.json({ verify: adapter.rawBodyVerify })`."
+      );
+      res.status(500).json({ error: "raw_body_unavailable" });
+      return false;
+    }
+    gated.rawBody = rawBody;
+    let target;
+    try {
+      target = targetUrl(req);
+    } catch (err) {
+      if (!(err instanceof InvalidRequestTargetError)) throw err;
+      res.status(400).json({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid request target." } });
+      return false;
+    }
+    const targetPath = target.pathname + target.search;
+    const input = { rawBody, method: req.method, url: targetPath };
+    const operation = resolveRequestOperation(input);
+    if (isUnresolvableOperation(operation)) {
+      logger.error("A2A adapter: request body does not resolve to one operation", {
+        reason: describeUnresolvable(input) ?? "unknown"
+      });
+      reject(res, "request_body_malformed", "Request body does not resolve to exactly one AdCP operation");
+      return false;
+    }
+    const originalUrl = req.url;
+    const stamped = req;
+    const previousContext = stamped[ADCP_SERVE_REQUEST_CONTEXT];
+    stamped[ADCP_SERVE_REQUEST_CONTEXT] = { host: target.host.toLowerCase(), publicUrl: target.origin };
+    req.url = targetPath;
+    const slots = req;
+    const previousAuth = slots.auth;
+    const previousSigner = slots.verifiedSigner;
+    slots.auth = void 0;
+    slots.verifiedSigner = void 0;
+    let handled;
+    let signedAuth;
+    try {
+      handled = await gate(req, res);
+      if (slots.verifiedSigner !== void 0) signedAuth = slots.auth;
+    } finally {
+      req.url = originalUrl;
+      stamped[ADCP_SERVE_REQUEST_CONTEXT] = previousContext;
+      slots.auth = previousAuth;
+      slots.verifiedSigner = previousSigner;
+    }
+    if (handled || res.headersSent) return false;
+    gated.body = JSON.parse(rawBody);
+    gated._body = true;
+    gateStates.set(req, { operation, ...signedAuth && { signedAuth } });
+    return true;
+  };
+  return (req, res, next) => {
+    if (req.method !== "POST") {
+      sdkHandler(req, res, next);
+      return;
+    }
+    run(req, res).then(
+      (proceed) => {
+        if (proceed) sdkHandler(req, res, next);
+      },
+      (err) => {
+        logger.error("A2A adapter: signature gate failed", { error: err?.name || "Error" });
+        if (!res.headersSent) res.status(500).json({ error: "verifier_error" });
+      }
+    );
+  };
+}
+function readBody(req) {
+  if (req.readableEnded || req.complete && !req.readable) return Promise.resolve(void 0);
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_GATED_BODY_BYTES) {
+        req.removeAllListeners("data");
+        req.resume();
+        reject(new BodyTooLargeError());
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
 const DEFAULT_LOGGER = {
   debug: (m, d) => console.debug(m, d ?? ""),
   info: (m, d) => console.info(m, d ?? ""),
@@ -573,6 +771,16 @@ function createA2AAdapter(options) {
   const logger = options.logger ?? DEFAULT_LOGGER;
   const legacyCompat = { enabled: options.legacyCompat?.enabled !== false };
   const card = buildAgentCard(options.server, options.agentCard, legacyCompat);
+  const signatureGate = resolveSignatureGate(options);
+  if (signatureGate && !options.signedRequestsUrl) {
+    try {
+      new URL(card.supportedInterfaces[0].url);
+    } catch {
+      throw new Error(
+        "createA2AAdapter: request signing needs an absolute `agentCard.url` (the URL buyers sign), or a `signedRequestsUrl` callback that returns it."
+      );
+    }
+  }
   const handlerCard = structuredClone(card);
   if (handlerCard.capabilities?.extensions) {
     handlerCard.capabilities.extensions = handlerCard.capabilities.extensions.map(
@@ -589,15 +797,36 @@ function createA2AAdapter(options) {
   const executor = new AdcpA2AAgentExecutor(options.server, logger);
   const eventBusManager = new DefaultExecutionEventBusManager();
   const requestHandler = new DefaultRequestHandler(handlerCard, taskStore, executor, eventBusManager);
+  const gateStates = /* @__PURE__ */ new WeakMap();
   const userBuilder = async (req) => {
-    if (!options.authenticate) return buildAnonymousUser();
+    const gate = gateStates.get(req);
+    const signed = gate?.signedAuth;
+    if (!options.authenticate) {
+      return signed ? buildAuthenticatedUser(signed, gate) : buildAnonymousUser(gate);
+    }
     const authInfo = await options.authenticate(req);
     if (authInfo == null) {
       throw new Error("A2A authentication failed");
     }
-    return buildAuthenticatedUser(authInfo);
+    if (signed) {
+      if (authInfo.clientId !== signed.clientId) {
+        logger.error(
+          `A2A adapter: \`authenticate\` returned a principal that differs from the verified signer (${signed.clientId}). Map the signer in \`authenticate\` (read \`req.verifiedSigner\`) or use makePrincipal.`
+        );
+        throw new Error("A2A authentication failed");
+      }
+      return buildAuthenticatedUser({ ...authInfo, extra: { ...authInfo.extra, ...signed.extra } }, gate);
+    }
+    return buildAuthenticatedUser(authInfo, gate);
   };
-  const jsonRpc = jsonRpcHandler({ requestHandler, userBuilder, legacyCompat });
+  const sdkJsonRpc = jsonRpcHandler({ requestHandler, userBuilder, legacyCompat });
+  const jsonRpc = signatureGate ? createSignatureGate({
+    gate: signatureGate,
+    next: sdkJsonRpc,
+    gateStates,
+    targetUrl: (req) => signedRequestTargetUrl(req, card.supportedInterfaces[0].url, options.signedRequestsUrl),
+    logger
+  }) : sdkJsonRpc;
   const nativeAgentCardMiddleware = agentCardHandler({ agentCardProvider: async () => card });
   const legacyAgentCardMiddleware = agentCardHandler({ agentCardProvider: async () => handlerCard, legacyCompat });
   const agentCardMiddleware = (req, res, next) => {
@@ -629,6 +858,7 @@ function createA2AAdapter(options) {
     async getAgentCard() {
       return card;
     },
+    rawBodyVerify: captureRawBody,
     mount
   };
 }

package/dist/lib/server/auth-signature.d.mts

@@ -19,7 +19,7 @@
  *   verifyApiKey,
  *   anyOf,
  *   verifySignatureAsAuthenticator,
- *   mcpToolNameResolver,
+ *   adcpOperationResolver,
  * } from '@adcp/sdk/server';
  *
  * serve(createAgent, {
@@ -28,7 +28,7 @@
  *     verifySignatureAsAuthenticator({
  *       jwks, replayStore, revocationStore,
  *       capability: { supported: true, required_for: [], covers_content_digest: 'either' },
- *       resolveOperation: mcpToolNameResolver,
+ *       resolveOperation: adcpOperationResolver,
  *     }),
  *   ),
  * });
@@ -42,6 +42,7 @@ import type { JwksResolver } from '../signing/jwks.mjs';
 import { type ReplayStore } from '../signing/replay.mjs';
 import { type RevocationStore } from '../signing/revocation.mjs';
 import type { VerifiedSigner, VerifierCapability } from '../signing/types.mjs';
+import { type OperationResolutionInput, type ResolvedOperation } from '../signing/operation-resolution.mjs';
 import { type AuthPrincipal, type Authenticator } from './auth.mjs';
 export interface VerifySignatureAsAuthenticatorOptions {
     /** Verifier capability block. `required_for` is not enforced here — unsigned
@@ -82,17 +83,22 @@ export interface VerifySignatureAsAuthenticatorOptions {
      * before this runs. Same semantics as
      * `ExpressMiddlewareOptions.resolveOperation` on {@link createExpressVerifier}.
      *
+     * Pass {@link adcpOperationResolver}: it resolves MCP `tools/call` and A2A
+     * `SendMessage` / `message/send` requests, and reports a body that does not
+     * resolve to exactly one operation as unresolvable, which the verifier
+     * rejects with `request_body_malformed`.
+     *
      * SECURITY: a resolver that always returns `undefined` disables
-     * `capability.required_for` enforcement for this authenticator. Since the
-     * bypass here is intentional (this adapter is for composition with other
-     * authenticators — see the module docstring), the fall-through still
-     * happens when the resolver returns `undefined`, so `required_for`
-     * enforcement should live in a separate `preTransport`-mounted verifier
-     * when composition is active.
+     * `capability.required_for` enforcement for this authenticator. This adapter
+     * is for composition with other authenticators (see the module docstring),
+     * so unsigned requests fall through to the next authenticator regardless;
+     * `required_for` enforcement on the unsigned path belongs to
+     * {@link requireSignatureWhenPresent}, which fails closed on an
+     * unresolvable body.
      */
     resolveOperation: (req: IncomingMessage & {
         rawBody?: string;
-    }) => string | undefined;
+    }) => ResolvedOperation;
     /**
      * Override how the request's full URL is reconstructed. Use when the
      * server sits behind a TLS-terminating or path-rewriting load balancer
@@ -202,21 +208,37 @@ export interface RequireSignatureWhenPresentOptions {
      */
     requiredFor?: readonly string[];
     /**
-     * Extract the AdCP operation name (or any identifier that can be
-     * matched against `requiredFor`) from the incoming request.
+     * JSON-RPC protocol methods (e.g. `CancelTask`, `tasks/cancel`) that MUST be
+     * signed, matching `capability.protocol_methods_required_for`. Matched
+     * against the JSON-RPC `method` only, never against the resolved operation.
+     * Like {@link requiredFor}, a valid fallback credential satisfies it.
+     */
+    protocolMethodsRequiredFor?: readonly string[];
+    /**
+     * Resolve the AdCP operation a request carries. Defaults to
+     * {@link adcpOperationResolver}, which understands MCP `tools/call` and A2A
+     * `SendMessage` / `SendStreamingMessage` / `message/send` / `message/stream`.
      *
-     * For MCP agents, pass the exported {@link mcpToolNameResolver} — it
-     * implements the standard `tools/call` → `params.name` parse. For A2A
-     * agents (or other non-JSON-RPC envelopes), supply a bespoke resolver.
+     * A resolver may return:
+     * - an operation name, matched against {@link requiredFor};
+     * - `undefined` for a request that carries no AdCP operation (discovery
+     *   probes, `tasks/*`) — the request is not subject to {@link requiredFor};
+     * - {@link UNRESOLVABLE_OPERATION} for a body that does not resolve to
+     *   exactly one operation. The gate rejects it with `request_body_malformed`
+     *   before it looks at any signature header or credential, whether or not
+     *   the request is signed. An ambiguous body is never treated as "an
+     *   operation that is not in `requiredFor`".
      *
-     * When `requiredFor` is set but `resolveOperation` is omitted OR
-     * returns `undefined`, the pre-check is skipped — better to let the
-     * downstream handler produce a precise `INVALID_REQUEST` than to
-     * reject every unsigned call as signature-required.
+     * Omitting this option no longer disables the pre-check: a gate with
+     * `requiredFor` set and no resolver used to skip enforcement for every
+     * request. The default resolver is used instead. `requiredFor` and the
+     * resolver are only as good as each other — a resolver that returns
+     * `undefined` for A2A messages (such as {@link mcpToolNameResolver}) leaves
+     * `requiredFor` unenforced over A2A.
      */
     resolveOperation?: (req: IncomingMessage & {
         rawBody?: string;
-    }) => string | undefined;
+    }) => ResolvedOperation;
 }
 /**
  * Compose a signature authenticator with a fallback under presence-gated
@@ -252,10 +274,12 @@ export interface RequireAuthenticatedOrSignedOptions {
      * declaration in `capabilities.request_signing.required_for`.
      */
     requiredFor?: readonly string[];
+    /** See {@link RequireSignatureWhenPresentOptions.protocolMethodsRequiredFor}. */
+    protocolMethodsRequiredFor?: readonly string[];
     /** See {@link RequireSignatureWhenPresentOptions.resolveOperation}. */
     resolveOperation?: (req: IncomingMessage & {
         rawBody?: string;
-    }) => string | undefined;
+    }) => ResolvedOperation;
 }
 /**
  * Bundled composition of {@link requireSignatureWhenPresent} with an
@@ -279,7 +303,7 @@ export interface RequireAuthenticatedOrSignedOptions {
  *   anyOf,
  *   verifySignatureAsAuthenticator,
  *   requireAuthenticatedOrSigned,
- *   mcpToolNameResolver,
+ *   adcpOperationResolver,
  *   MUTATING_TASKS,
  * } from '@adcp/sdk/server';
  *
@@ -287,43 +311,57 @@ export interface RequireAuthenticatedOrSignedOptions {
  *   authenticate: requireAuthenticatedOrSigned({
  *     signature: verifySignatureAsAuthenticator({
  *       jwks, replayStore, revocationStore, capability,
- *       resolveOperation: mcpToolNameResolver,
+ *       resolveOperation: adcpOperationResolver,
  *     }),
  *     fallback: anyOf(verifyApiKey({ keys }), verifyBearer({ jwksUri, issuer, audience })),
  *     requiredFor: [...MUTATING_TASKS],
- *     resolveOperation: mcpToolNameResolver,
+ *     resolveOperation: adcpOperationResolver,
  *   }),
  * });
  * ```
  */
 export declare function requireAuthenticatedOrSigned(options: RequireAuthenticatedOrSignedOptions): Authenticator;
 /**
- * Default `resolveOperation` for MCP agents. Parses the buffered JSON-RPC
- * body on `req.rawBody` and returns `params.name` when `method === 'tools/call'`.
- * Returns `undefined` for non-`tools/call` methods, a missing body, or
- * malformed JSON — the same "skip the pre-check and let the handler produce
- * a precise error" semantics every other `resolveOperation` in the SDK
- * uses.
+ * Resolve the AdCP operation a request carries, for MCP and A2A alike
+ * (adcp#7945, "Operation resolution over A2A"). Pass it as `resolveOperation`
+ * on {@link verifySignatureAsAuthenticator}, {@link requireSignatureWhenPresent},
+ * {@link requireAuthenticatedOrSigned}, or `createExpressVerifier` from
+ * `@adcp/sdk/signing`; it is the default for the composers.
  *
- * Pass directly as `resolveOperation` on {@link verifySignatureAsAuthenticator},
- * {@link requireSignatureWhenPresent}, {@link requireAuthenticatedOrSigned},
- * or `createExpressVerifier` from `@adcp/sdk/signing`:
+ * | Request                                                                 | Result                         |
+ * |-------------------------------------------------------------------------|--------------------------------|
+ * | MCP `tools/call`                                                        | `params.name`                  |
+ * | A2A `SendMessage`, `SendStreamingMessage`, `message/send`, `message/stream` | `skill` of the sole DataPart |
+ * | any other JSON-RPC method (`tasks/*`, `CancelTask`, `initialize`, …)    | `undefined` (no operation)     |
+ * | non-`POST` request                                                      | `undefined`                    |
+ * | anything ambiguous                                                      | {@link UNRESOLVABLE_OPERATION} |
  *
- * ```ts
- * serve(createAgent, {
- *   authenticate: requireAuthenticatedOrSigned({
- *     signature: verifySignatureAsAuthenticator({
- *       jwks, replayStore, revocationStore, capability,
- *       resolveOperation: mcpToolNameResolver,
- *     }),
- *     fallback: anyOf(verifyApiKey({ keys }), verifyBearer({ jwksUri, issuer, audience })),
- *     requiredFor: [...MUTATING_TASKS],
- *     resolveOperation: mcpToolNameResolver,
- *   }),
- * });
- * ```
+ * Ambiguous means: an empty or non-JSON body on a `POST`, a JSON-RPC batch or
+ * non-object body, a missing `method`, duplicate object keys (compared after
+ * JSON string decoding), a case variant of a recognized member name (`Skill`,
+ * `Parts`), zero or more than one DataPart, a FilePart (`raw`, `url`, `file`),
+ * a Part with other than one content member or a `kind` that disagrees with
+ * it, `data` that is not an object, or a `skill` / `params.name` that is not a
+ * non-empty string. Matching is exact and case-sensitive.
+ *
+ * The consumers reject {@link UNRESOLVABLE_OPERATION} with
+ * `request_body_malformed`, never as "an operation that is not in
+ * `required_for`". `req.rawBody` must hold the exact bytes the client sent.
+ */
+export declare function adcpOperationResolver(req: OperationResolutionInput | (IncomingMessage & {
+    rawBody?: string | Buffer;
+})): ResolvedOperation;
+/**
+ * Resolver for MCP agents. Parses the buffered JSON-RPC body on `req.rawBody`
+ * and returns `params.name` when `method === 'tools/call'`; returns
+ * `undefined` for every other method, a missing body, or malformed JSON.
  *
- * A2A agents use a different envelope — write a bespoke resolver there.
+ * **MCP only, and lenient.** It does not understand A2A: an A2A
+ * `SendMessage` resolves to `undefined`, so a `requiredFor` list guarded by
+ * this resolver is NOT enforced over A2A. It also treats an ambiguous body as
+ * "no operation". Prefer {@link adcpOperationResolver}, which resolves A2A and
+ * reports ambiguity as {@link UNRESOLVABLE_OPERATION}. Kept for callers that
+ * pin the previous behavior.
  */
 export declare function mcpToolNameResolver(req: {
     rawBody?: string;