@adcp/sdk 15.0.0 → 15.2.0

package/dist/lib/server/auth-signature.mjs

@@ -1,7 +1,18 @@
 import { RequestSignatureError } from "../signing/errors.mjs";
 import { InMemoryReplayStore } from "../signing/replay.mjs";
 import { InMemoryRevocationStore } from "../signing/revocation.mjs";
-import { verifyRequestSignature } from "../signing/verifier.mjs";
+import {
+  isUnresolvableOperation,
+  resolveRequestOperation,
+  describeUnresolvable
+} from "../signing/operation-resolution.mjs";
+import {
+  assertUnsignedOperationNotRequired,
+  assertUnsignedProtocolMethodNotRequired,
+  assertUnsignedWebhookAuthenticationAbsent,
+  unresolvableOperationError,
+  verifyRequestSignature
+} from "../signing/verifier.mjs";
 import { markVerifiedHttpSig } from "./decisioning/buyer-agent.mjs";
 import {
   AuthError,
@@ -91,8 +102,18 @@ function principalForVerifiedSigner(signer, makePrincipal) {
 }
 function requireSignatureWhenPresent(signatureAuth, fallbackAuth, options = {}) {
   const requiredFor = new Set(options.requiredFor ?? []);
-  const resolveOperation = options.resolveOperation;
+  const unsignedCapability = {
+    required_for: [...requiredFor],
+    ...options.protocolMethodsRequiredFor ? { protocol_methods_required_for: [...options.protocolMethodsRequiredFor] } : {}
+  };
+  const resolveOperation = options.resolveOperation ?? (requiredFor.size > 0 || unsignedCapability.protocol_methods_required_for ? adcpOperationResolver : void 0);
   const combined = async (req) => {
+    const request = req;
+    const operation = resolveOperation?.(request);
+    if (isUnresolvableOperation(operation)) {
+      logUnresolvable(request);
+      throw signatureAuthError(unresolvableOperationError());
+    }
     if (hasSignatureHeader(req)) {
       const result = await signatureAuth(req);
       if (result === null) {
@@ -100,6 +121,12 @@ function requireSignatureWhenPresent(signatureAuth, fallbackAuth, options = {})
       }
       return result;
     }
+    const body = bodyText(request);
+    try {
+      assertUnsignedWebhookAuthenticationAbsent(body);
+    } catch (err) {
+      throw asSignatureAuthError(err);
+    }
     let fallbackResult = null;
     let fallbackError;
     let fallbackThrew = false;
@@ -110,23 +137,16 @@ function requireSignatureWhenPresent(signatureAuth, fallbackAuth, options = {})
       fallbackError = err;
     }
     if (fallbackResult !== null) return fallbackResult;
-    if (requiredFor.size > 0 && resolveOperation) {
-      const operation = resolveOperation(req);
-      if (operation && requiredFor.has(operation)) {
-        throw new AuthError(`Signature required for ${operation}.`, {
-          cause: new RequestSignatureError(
-            "request_signature_required",
-            0,
-            `Operation ${operation} requires an RFC 9421 request signature when no other credentials are presented.`
-          )
-        });
-      }
+    try {
+      assertUnsignedOperationNotRequired(operation, unsignedCapability);
+      assertUnsignedProtocolMethodNotRequired(body, unsignedCapability);
+    } catch (err) {
+      throw asSignatureAuthError(err);
     }
     if (fallbackThrew) throw fallbackError;
     return null;
   };
-  const anyChildNeedsRawBody = authenticatorNeedsRawBody(signatureAuth) || authenticatorNeedsRawBody(fallbackAuth);
-  if (anyChildNeedsRawBody || resolveOperation) {
+  if (resolveOperation || authenticatorNeedsRawBody(signatureAuth) || authenticatorNeedsRawBody(fallbackAuth)) {
     tagAuthenticatorNeedsRawBody(combined);
   }
   tagAuthenticatorPresenceGated(combined);
@@ -135,9 +155,13 @@ function requireSignatureWhenPresent(signatureAuth, fallbackAuth, options = {})
 function requireAuthenticatedOrSigned(options) {
   return requireSignatureWhenPresent(options.signature, options.fallback, {
     requiredFor: options.requiredFor,
+    protocolMethodsRequiredFor: options.protocolMethodsRequiredFor,
     resolveOperation: options.resolveOperation
   });
 }
+function adcpOperationResolver(req) {
+  return resolveRequestOperation(operationInput(req));
+}
 function mcpToolNameResolver(req) {
   const raw = req.rawBody;
   if (!raw) return void 0;
@@ -150,6 +174,24 @@ function mcpToolNameResolver(req) {
     return void 0;
   }
 }
+function operationInput(req) {
+  const candidate = req;
+  return { rawBody: candidate.rawBody, method: candidate.method, url: candidate.url };
+}
+function bodyText(req) {
+  const raw = req.rawBody;
+  return typeof raw === "string" ? raw : raw?.toString("utf8");
+}
+function signatureAuthError(err) {
+  return new AuthError(`Signature rejected (${err.code}).`, { cause: err });
+}
+function asSignatureAuthError(err) {
+  return err instanceof RequestSignatureError ? signatureAuthError(err) : err;
+}
+function logUnresolvable(req) {
+  const reason = describeUnresolvable(operationInput(req));
+  console.error(`[adcp/auth] request body does not resolve to one operation: ${reason ?? "unknown"}`);
+}
 const SAFE_KEYID = /^[A-Za-z0-9._-]{1,256}$/;
 function hasSignatureHeader(req) {
   return nonEmptyHeader(req.headers["signature-input"]) || nonEmptyHeader(req.headers["signature"]);
@@ -182,6 +224,7 @@ function firstHeader(value) {
   return void 0;
 }
 export {
+  adcpOperationResolver,
   mcpToolNameResolver,
   principalForVerifiedSigner,
   requireAuthenticatedOrSigned,

package/dist/lib/server/create-adcp-server.js

@@ -69,6 +69,7 @@ var import_diagnostic_limits = require('../validation/diagnostic-limits.js');
 var import_idempotency2 = require('./idempotency/index.js');
 var import_webhook_emitter = require('./webhook-emitter.js');
 var import_middleware = require('../signing/middleware.js');
+var import_operation_resolution = require('../signing/operation-resolution.js');
 var import_account_mode = require('./account-mode.js');
 var import_test_controller_bridge = require('./test-controller-bridge.js');
 var import_version2 = require('../version.js');
@@ -1431,22 +1432,10 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
     revocationStore: signedRequests.revocationStore,
     adcpVersion,
     ...signedRequests.agentUrlForKeyid ? { agentUrlForKeyid: signedRequests.agentUrlForKeyid } : {},
-    resolveOperation: (req) => {
-      const raw = req.rawBody;
-      if (!raw) return void 0;
-      try {
-        const parsed = JSON.parse(raw);
-        const messages = Array.isArray(parsed) ? parsed : [parsed];
-        const operations = messages.flatMap((message) => {
-          if (message == null || typeof message !== "object") return [];
-          const candidate = message;
-          return candidate.method === "tools/call" && typeof candidate.params?.name === "string" ? [candidate.params.name] : [];
-        });
-        return operations.find((operation) => requiredFor.includes(operation)) ?? operations[0];
-      } catch {
-      }
-      return void 0;
-    }
+    // One resolver for MCP `tools/call` and A2A message methods; a body that
+    // does not resolve to exactly one operation is rejected by the verifier
+    // (`request_body_malformed`), never treated as "not in required_for".
+    resolveOperation: (req) => (0, import_operation_resolution.resolveRequestOperation)({ rawBody: req.rawBody, method: req.method, url: req.url })
   });
   return async function adcpPreTransport(req, res) {
     const serveContext = (0, import_auth.getServeRequestContext)(req);

package/dist/lib/server/create-adcp-server.mjs

@@ -104,6 +104,7 @@ import {
   createWebhookEmitter
 } from "./webhook-emitter.mjs";
 import { createExpressVerifier } from "../signing/middleware.mjs";
+import { resolveRequestOperation } from "../signing/operation-resolution.mjs";
 import { isSandboxOrMockAccount } from "./account-mode.mjs";
 import {
   isSandboxRequest as isSandboxRequestForSeeding,
@@ -1503,22 +1504,10 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
     revocationStore: signedRequests.revocationStore,
     adcpVersion,
     ...signedRequests.agentUrlForKeyid ? { agentUrlForKeyid: signedRequests.agentUrlForKeyid } : {},
-    resolveOperation: (req) => {
-      const raw = req.rawBody;
-      if (!raw) return void 0;
-      try {
-        const parsed = JSON.parse(raw);
-        const messages = Array.isArray(parsed) ? parsed : [parsed];
-        const operations = messages.flatMap((message) => {
-          if (message == null || typeof message !== "object") return [];
-          const candidate = message;
-          return candidate.method === "tools/call" && typeof candidate.params?.name === "string" ? [candidate.params.name] : [];
-        });
-        return operations.find((operation) => requiredFor.includes(operation)) ?? operations[0];
-      } catch {
-      }
-      return void 0;
-    }
+    // One resolver for MCP `tools/call` and A2A message methods; a body that
+    // does not resolve to exactly one operation is rejected by the verifier
+    // (`request_body_malformed`), never treated as "not in required_for".
+    resolveOperation: (req) => resolveRequestOperation({ rawBody: req.rawBody, method: req.method, url: req.url })
   });
   return async function adcpPreTransport(req, res) {
     const serveContext = getServeRequestContext(req);

package/dist/lib/server/index.d.mts

@@ -49,7 +49,7 @@ export { verifyApiKey, verifyBearer, anyOf, extractBearerToken, respondUnauthori
 export type { Authenticator, AuthPrincipal, AuthResult, VerifyApiKeyOptions, VerifyBearerOptions, RespondUnauthorizedOptions, ServeRequestContext, } from './auth.mjs';
 export { verifyIntrospection } from './auth-introspection.mjs';
 export type { VerifyIntrospectionOptions, IntrospectionCacheOptions, IntrospectionResponse, } from './auth-introspection.mjs';
-export { verifySignatureAsAuthenticator, requireSignatureWhenPresent, requireAuthenticatedOrSigned, mcpToolNameResolver, } from './auth-signature.mjs';
+export { verifySignatureAsAuthenticator, requireSignatureWhenPresent, requireAuthenticatedOrSigned, mcpToolNameResolver, adcpOperationResolver, } from './auth-signature.mjs';
 export type { VerifySignatureAsAuthenticatorOptions, RequireSignatureWhenPresentOptions, RequireAuthenticatedOrSignedOptions, } from './auth-signature.mjs';
 export { InMemoryStateStore, StateError, PatchConflictError, DEFAULT_MAX_DOCUMENT_BYTES, SESSION_KEY_FIELD, createSessionedStore, scopedStore, patchWithRetry, isPutIfMatchConflict, validateCollection, validateId, validatePayloadSize, validateWrite, } from './state-store.mjs';
 export type { AdcpStateStore, InMemoryStateStoreOptions, ListOptions, ListResult, PatchWithRetryOptions, PutIfMatchResult, StateErrorCode, VersionedDocument, } from './state-store.mjs';

package/dist/lib/server/index.d.ts

@@ -49,7 +49,7 @@ export { verifyApiKey, verifyBearer, anyOf, extractBearerToken, respondUnauthori
 export type { Authenticator, AuthPrincipal, AuthResult, VerifyApiKeyOptions, VerifyBearerOptions, RespondUnauthorizedOptions, ServeRequestContext, } from './auth';
 export { verifyIntrospection } from './auth-introspection';
 export type { VerifyIntrospectionOptions, IntrospectionCacheOptions, IntrospectionResponse, } from './auth-introspection';
-export { verifySignatureAsAuthenticator, requireSignatureWhenPresent, requireAuthenticatedOrSigned, mcpToolNameResolver, } from './auth-signature';
+export { verifySignatureAsAuthenticator, requireSignatureWhenPresent, requireAuthenticatedOrSigned, mcpToolNameResolver, adcpOperationResolver, } from './auth-signature';
 export type { VerifySignatureAsAuthenticatorOptions, RequireSignatureWhenPresentOptions, RequireAuthenticatedOrSignedOptions, } from './auth-signature';
 export { InMemoryStateStore, StateError, PatchConflictError, DEFAULT_MAX_DOCUMENT_BYTES, SESSION_KEY_FIELD, createSessionedStore, scopedStore, patchWithRetry, isPutIfMatchConflict, validateCollection, validateId, validatePayloadSize, validateWrite, } from './state-store';
 export type { AdcpStateStore, InMemoryStateStoreOptions, ListOptions, ListResult, PatchWithRetryOptions, PutIfMatchResult, StateErrorCode, VersionedDocument, } from './state-store';

package/dist/lib/server/index.js

@@ -87,6 +87,7 @@ __export(server_exports, {
   WebhookAuthenticationResolutionError: () => import_webhook_delivery.WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError: () => import_webhook_delivery.WebhookDeliveryTerminalError,
   adcpError: () => import_errors.adcpError,
+  adcpOperationResolver: () => import_auth_signature.adcpOperationResolver,
   anyOf: () => import_auth.anyOf,
   applyTargetingInput: () => import_targeting_input.applyTargetingInput,
   assertCreativeTransition: () => import_state_machine.assertCreativeTransition,
@@ -415,6 +416,7 @@ var import_media_buy_action_resolver = require('./media-buy-action-resolver.js')
   WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   adcpError,
+  adcpOperationResolver,
   anyOf,
   applyTargetingInput,
   assertCreativeTransition,

package/dist/lib/server/index.mjs

@@ -119,7 +119,8 @@ import {
   verifySignatureAsAuthenticator,
   requireSignatureWhenPresent,
   requireAuthenticatedOrSigned,
-  mcpToolNameResolver
+  mcpToolNameResolver,
+  adcpOperationResolver
 } from "./auth-signature.mjs";
 import {
   InMemoryStateStore,
@@ -363,6 +364,7 @@ export {
   WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   adcpError,
+  adcpOperationResolver,
   anyOf,
   applyTargetingInput,
   assertCreativeTransition,

package/dist/lib/signing/agent-fetch.js

@@ -35,6 +35,7 @@ var import_capability_cache = require('./capability-cache.js');
 var import_webhook_auth_detection = require('./webhook-auth-detection.js');
 var import_version = require('../version.js');
 var import_content_digest = require('./content-digest.js');
+var import_operation_resolution = require('./operation-resolution.js');
 var import_content_digest2 = require('./content-digest.js');
 const MAX_WEBHOOK_AUTH_INSPECTION_BYTES = 1048576;
 function defaultUpstream() {
@@ -62,42 +63,11 @@ function describeBody(body) {
   }
   return typeof body;
 }
-const A2A_SEND_METHODS = /* @__PURE__ */ new Set([
-  "message/send",
-  "message/stream",
-  "SendMessage",
-  "SendStreamingMessage"
-]);
 function extractAdcpOperation(body) {
   const text = bodyToUtf8(body);
   if (!text) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return void 0;
-  }
-  if (!parsed || typeof parsed !== "object") return void 0;
-  const rpc = parsed;
-  if (rpc.method === "tools/call") {
-    const params = rpc.params;
-    return typeof params?.name === "string" ? params.name : void 0;
-  }
-  if (typeof rpc.method === "string" && A2A_SEND_METHODS.has(rpc.method)) {
-    const params = rpc.params;
-    const parts = params?.message?.parts;
-    if (!Array.isArray(parts)) return void 0;
-    for (const part of parts) {
-      if (part && typeof part === "object") {
-        const p = part;
-        const isDataPart = p.kind === void 0 || p.kind === "data";
-        if (isDataPart && typeof p.data?.skill === "string") {
-          return p.data.skill;
-        }
-      }
-    }
-  }
-  return void 0;
+  const operation = (0, import_operation_resolution.resolveRequestOperation)({ rawBody: text, method: "POST" });
+  return typeof operation === "string" ? operation : void 0;
 }
 function carriesWebhookAuthentication(body) {
   const text = bodyToUtf8(body);

package/dist/lib/signing/agent-fetch.mjs

@@ -7,6 +7,7 @@ import {
 import { containsWebhookAuthentication } from "./webhook-auth-detection.mjs";
 import { ADCP_VERSION } from "../version.mjs";
 import { requestSigningEncodingForVersion } from "./content-digest.mjs";
+import { resolveRequestOperation } from "./operation-resolution.mjs";
 import { requestSigningEncodingForVersion as requestSigningEncodingForVersion2 } from "./content-digest.mjs";
 const MAX_WEBHOOK_AUTH_INSPECTION_BYTES = 1048576;
 function defaultUpstream() {
@@ -34,42 +35,11 @@ function describeBody(body) {
   }
   return typeof body;
 }
-const A2A_SEND_METHODS = /* @__PURE__ */ new Set([
-  "message/send",
-  "message/stream",
-  "SendMessage",
-  "SendStreamingMessage"
-]);
 function extractAdcpOperation(body) {
   const text = bodyToUtf8(body);
   if (!text) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return void 0;
-  }
-  if (!parsed || typeof parsed !== "object") return void 0;
-  const rpc = parsed;
-  if (rpc.method === "tools/call") {
-    const params = rpc.params;
-    return typeof params?.name === "string" ? params.name : void 0;
-  }
-  if (typeof rpc.method === "string" && A2A_SEND_METHODS.has(rpc.method)) {
-    const params = rpc.params;
-    const parts = params?.message?.parts;
-    if (!Array.isArray(parts)) return void 0;
-    for (const part of parts) {
-      if (part && typeof part === "object") {
-        const p = part;
-        const isDataPart = p.kind === void 0 || p.kind === "data";
-        if (isDataPart && typeof p.data?.skill === "string") {
-          return p.data.skill;
-        }
-      }
-    }
-  }
-  return void 0;
+  const operation = resolveRequestOperation({ rawBody: text, method: "POST" });
+  return typeof operation === "string" ? operation : void 0;
 }
 function carriesWebhookAuthentication(body) {
   const text = bodyToUtf8(body);

package/dist/lib/signing/middleware.d.mts

@@ -1,4 +1,5 @@
 import { type VerifyRequestOptions } from './verifier.mjs';
+import type { ResolvedOperation } from './operation-resolution.mjs';
 import type { VerifiedSigner } from './types.mjs';
 declare module 'http' {
     interface IncomingMessage {
@@ -56,6 +57,13 @@ export interface ExpressMiddlewareOptions extends Omit<VerifyRequestOptions, 'op
      * the verifier will then treat the request as "not in any required_for"
      * and accept unsigned traffic rather than rejecting.
      *
+     * Return {@link UNRESOLVABLE_OPERATION} for a body that does not resolve to
+     * exactly one operation; the verifier then rejects it with
+     * `request_body_malformed`, signed or not. `resolveRequestOperation` (and
+     * `adcpOperationResolver` from `@adcp/sdk/server`) implements the MCP and A2A
+     * rules, including that fail-closed result, and is what `createAdcpServer`
+     * auto-wires.
+     *
      * SECURITY: a `resolveOperation` that always returns `undefined` — for
      * example, a routing helper that silently fails to match — disables
      * `required_for` enforcement globally. Unsigned requests on signed-only
@@ -64,7 +72,7 @@ export interface ExpressMiddlewareOptions extends Omit<VerifyRequestOptions, 'op
      * asserting `resolveOperation(req)` is non-undefined for sample signed
      * requests is the simplest guard.
      */
-    resolveOperation: (req: ExpressLike) => string | undefined;
+    resolveOperation: (req: ExpressLike) => ResolvedOperation;
     /**
      * Override how the request's full URL is reconstructed. Use when the server
      * sits behind a TLS-terminating or path-rewriting load balancer, since

package/dist/lib/signing/middleware.d.ts

@@ -1,4 +1,5 @@
 import { type VerifyRequestOptions } from './verifier';
+import type { ResolvedOperation } from './operation-resolution';
 import type { VerifiedSigner } from './types';
 declare module 'http' {
     interface IncomingMessage {
@@ -56,6 +57,13 @@ export interface ExpressMiddlewareOptions extends Omit<VerifyRequestOptions, 'op
      * the verifier will then treat the request as "not in any required_for"
      * and accept unsigned traffic rather than rejecting.
      *
+     * Return {@link UNRESOLVABLE_OPERATION} for a body that does not resolve to
+     * exactly one operation; the verifier then rejects it with
+     * `request_body_malformed`, signed or not. `resolveRequestOperation` (and
+     * `adcpOperationResolver` from `@adcp/sdk/server`) implements the MCP and A2A
+     * rules, including that fail-closed result, and is what `createAdcpServer`
+     * auto-wires.
+     *
      * SECURITY: a `resolveOperation` that always returns `undefined` — for
      * example, a routing helper that silently fails to match — disables
      * `required_for` enforcement globally. Unsigned requests on signed-only
@@ -64,7 +72,7 @@ export interface ExpressMiddlewareOptions extends Omit<VerifyRequestOptions, 'op
      * asserting `resolveOperation(req)` is non-undefined for sample signed
      * requests is the simplest guard.
      */
-    resolveOperation: (req: ExpressLike) => string | undefined;
+    resolveOperation: (req: ExpressLike) => ResolvedOperation;
     /**
      * Override how the request's full URL is reconstructed. Use when the server
      * sits behind a TLS-terminating or path-rewriting load balancer, since

package/dist/lib/signing/operation-resolution.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Distinguished "this body does not resolve to exactly one operation" result.
+ * A `Symbol.for` key so it survives duplicate copies of the SDK in one process.
+ */
+export declare const UNRESOLVABLE_OPERATION: unique symbol;
+export type UnresolvableOperation = typeof UNRESOLVABLE_OPERATION;
+/** What a `resolveOperation` callback may return. */
+export type ResolvedOperation = string | undefined | UnresolvableOperation;
+export declare function isUnresolvableOperation(value: unknown): value is UnresolvableOperation;
+/** JSON-RPC methods that carry an A2A Message and therefore an invocation DataPart. */
+export declare const A2A_MESSAGE_METHODS: ReadonlySet<string>;
+export interface OperationResolutionInput {
+    /** The exact request body bytes, decoded as UTF-8. */
+    rawBody?: string | Buffer;
+    /** HTTP method. When present and not `POST`, the request carries no operation. */
+    method?: string;
+    /** Request URL (path may be relative). Selects the A2A HTTP+JSON binding. */
+    url?: string;
+}
+export type OperationResolution = {
+    kind: 'operation';
+    operation: string;
+} | {
+    kind: 'none';
+} | {
+    kind: 'unresolvable';
+    reason: string;
+};
+/**
+ * Resolve the operation a request carries, with a diagnostic reason when it
+ * cannot be resolved. Pure and synchronous; never throws.
+ */
+export declare function resolveRequestOperationDetailed(input: OperationResolutionInput): OperationResolution;
+/** {@link resolveRequestOperationDetailed} collapsed to the `resolveOperation` return shape. */
+export declare function resolveRequestOperation(input: OperationResolutionInput): ResolvedOperation;
+/** Diagnostic reason for an unresolvable body. Server-side logs only. */
+export declare function describeUnresolvable(input: OperationResolutionInput): string | undefined;

package/dist/lib/signing/operation-resolution.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Distinguished "this body does not resolve to exactly one operation" result.
+ * A `Symbol.for` key so it survives duplicate copies of the SDK in one process.
+ */
+export declare const UNRESOLVABLE_OPERATION: unique symbol;
+export type UnresolvableOperation = typeof UNRESOLVABLE_OPERATION;
+/** What a `resolveOperation` callback may return. */
+export type ResolvedOperation = string | undefined | UnresolvableOperation;
+export declare function isUnresolvableOperation(value: unknown): value is UnresolvableOperation;
+/** JSON-RPC methods that carry an A2A Message and therefore an invocation DataPart. */
+export declare const A2A_MESSAGE_METHODS: ReadonlySet<string>;
+export interface OperationResolutionInput {
+    /** The exact request body bytes, decoded as UTF-8. */
+    rawBody?: string | Buffer;
+    /** HTTP method. When present and not `POST`, the request carries no operation. */
+    method?: string;
+    /** Request URL (path may be relative). Selects the A2A HTTP+JSON binding. */
+    url?: string;
+}
+export type OperationResolution = {
+    kind: 'operation';
+    operation: string;
+} | {
+    kind: 'none';
+} | {
+    kind: 'unresolvable';
+    reason: string;
+};
+/**
+ * Resolve the operation a request carries, with a diagnostic reason when it
+ * cannot be resolved. Pure and synchronous; never throws.
+ */
+export declare function resolveRequestOperationDetailed(input: OperationResolutionInput): OperationResolution;
+/** {@link resolveRequestOperationDetailed} collapsed to the `resolveOperation` return shape. */
+export declare function resolveRequestOperation(input: OperationResolutionInput): ResolvedOperation;
+/** Diagnostic reason for an unresolvable body. Server-side logs only. */
+export declare function describeUnresolvable(input: OperationResolutionInput): string | undefined;

package/dist/lib/signing/operation-resolution.js

@@ -0,0 +1,154 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var operation_resolution_exports = {};
+__export(operation_resolution_exports, {
+  A2A_MESSAGE_METHODS: () => A2A_MESSAGE_METHODS,
+  UNRESOLVABLE_OPERATION: () => UNRESOLVABLE_OPERATION,
+  describeUnresolvable: () => describeUnresolvable,
+  isUnresolvableOperation: () => isUnresolvableOperation,
+  resolveRequestOperation: () => resolveRequestOperation,
+  resolveRequestOperationDetailed: () => resolveRequestOperationDetailed
+});
+module.exports = __toCommonJS(operation_resolution_exports);
+var import_strict_json = require('./agent-resolver/strict-json.js');
+const UNRESOLVABLE_OPERATION = /* @__PURE__ */ Symbol.for("@adcp/client.signing.unresolvableOperation");
+function isUnresolvableOperation(value) {
+  return value === UNRESOLVABLE_OPERATION;
+}
+const A2A_MESSAGE_METHODS = /* @__PURE__ */ new Set([
+  "SendMessage",
+  "SendStreamingMessage",
+  "message/send",
+  "message/stream"
+]);
+const CONTENT_MEMBERS = ["text", "data", "raw", "url", "file"];
+const FILE_MEMBERS = /* @__PURE__ */ new Set(["raw", "url", "file"]);
+const HTTP_JSON_MESSAGE_PATH = /(?:^|\/)message:(?:send|stream)$/;
+const ENVELOPE_MEMBERS = ["method", "params"];
+const TOOLS_CALL_PARAMS_MEMBERS = ["name"];
+const CARRIER_MEMBERS = ["message"];
+const MESSAGE_MEMBERS = ["parts", "taskId"];
+const PART_MEMBERS = [...CONTENT_MEMBERS, "kind"];
+const DATA_MEMBERS = ["skill"];
+function resolveRequestOperationDetailed(input) {
+  if (input.method !== void 0 && input.method.toUpperCase() !== "POST") return { kind: "none" };
+  const raw = typeof input.rawBody === "string" ? input.rawBody : input.rawBody?.toString("utf8");
+  if (raw === void 0 || raw.trim() === "") return unresolvable("request body is empty");
+  if (raw.charCodeAt(0) === 65279) return unresolvable("body starts with a byte order mark");
+  let body;
+  try {
+    body = (0, import_strict_json.parseStrictJson)(raw);
+  } catch (err) {
+    return unresolvable(err instanceof import_strict_json.StrictJsonError ? `body is not strict JSON (${err.code})` : "body is not JSON");
+  }
+  if (!isPlainObject(body)) {
+    return unresolvable(Array.isArray(body) ? "JSON-RPC batches are not supported" : "body is not a JSON object");
+  }
+  if (isHttpJsonMessagePath(input.url)) {
+    return resolveMessageCarrier(body);
+  }
+  if (hasCaseVariantMember(body, ENVELOPE_MEMBERS)) return unresolvable("case variant of an envelope member");
+  const method = body.method;
+  if (method === void 0 && isJsonRpcResponse(body)) {
+    return { kind: "none" };
+  }
+  if (typeof method !== "string") return unresolvable("JSON-RPC request has no string method");
+  if (method === "tools/call") {
+    const params = body.params;
+    if (!isPlainObject(params)) return unresolvable("tools/call params is not an object");
+    if (hasCaseVariantMember(params, TOOLS_CALL_PARAMS_MEMBERS)) return unresolvable("case variant of a params member");
+    const name = params.name;
+    if (typeof name !== "string" || name.length === 0) return unresolvable("tools/call params.name is not a string");
+    return { kind: "operation", operation: name };
+  }
+  if (A2A_MESSAGE_METHODS.has(method)) {
+    const params = body.params;
+    if (!isPlainObject(params)) return unresolvable("message method params is not an object");
+    return resolveMessageCarrier(params);
+  }
+  return { kind: "none" };
+}
+function resolveRequestOperation(input) {
+  const resolution = resolveRequestOperationDetailed(input);
+  if (resolution.kind === "operation") return resolution.operation;
+  return resolution.kind === "none" ? void 0 : UNRESOLVABLE_OPERATION;
+}
+function describeUnresolvable(input) {
+  const resolution = resolveRequestOperationDetailed(input);
+  return resolution.kind === "unresolvable" ? resolution.reason : void 0;
+}
+function resolveMessageCarrier(container) {
+  if (hasCaseVariantMember(container, CARRIER_MEMBERS)) return unresolvable("case variant of the message member");
+  const message = container.message;
+  if (!isPlainObject(message)) return unresolvable("request carries no message object");
+  if (hasCaseVariantMember(message, MESSAGE_MEMBERS)) return unresolvable("case variant of a message member");
+  const parts = message.parts;
+  if (!Array.isArray(parts)) return unresolvable("message.parts is not an array");
+  let invocation;
+  for (const part of parts) {
+    if (!isPlainObject(part)) return unresolvable("a Part is not an object");
+    if (hasCaseVariantMember(part, PART_MEMBERS)) return unresolvable("case variant of a Part member");
+    const present = CONTENT_MEMBERS.filter((member2) => Object.prototype.hasOwnProperty.call(part, member2));
+    if (present.length !== 1) return unresolvable("a Part must carry exactly one content member");
+    const member = present[0];
+    if (FILE_MEMBERS.has(member)) return unresolvable("FileParts are not allowed on an AdCP invocation");
+    const kind = part.kind;
+    if (kind !== void 0 && kind !== member) return unresolvable("a Part kind disagrees with its content member");
+    if (member === "data") {
+      if (invocation !== void 0) return unresolvable("message carries more than one DataPart");
+      if (!isPlainObject(part.data)) return unresolvable("DataPart data is not an object");
+      invocation = part.data;
+    }
+  }
+  if (invocation === void 0) return unresolvable("message carries no DataPart");
+  if (hasCaseVariantMember(invocation, DATA_MEMBERS)) return unresolvable("case variant of skill");
+  const skill = invocation.skill;
+  if (typeof skill !== "string" || skill.length === 0) return unresolvable("DataPart skill is not a non-empty string");
+  return { kind: "operation", operation: skill };
+}
+function isJsonRpcResponse(body) {
+  const has = (key) => Object.prototype.hasOwnProperty.call(body, key);
+  return (has("result") || has("error")) && !has("params");
+}
+function unresolvable(reason) {
+  return { kind: "unresolvable", reason };
+}
+function isHttpJsonMessagePath(url) {
+  if (!url) return false;
+  const queryStart = url.search(/[?#]/);
+  return HTTP_JSON_MESSAGE_PATH.test(queryStart === -1 ? url : url.slice(0, queryStart));
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasCaseVariantMember(obj, recognized) {
+  return Object.keys(obj).some((key) => {
+    const lowered = key.toLowerCase();
+    return recognized.some((name) => name.toLowerCase() === lowered && name !== key);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2A_MESSAGE_METHODS,
+  UNRESOLVABLE_OPERATION,
+  describeUnresolvable,
+  isUnresolvableOperation,
+  resolveRequestOperation,
+  resolveRequestOperationDetailed
+});