@adcp/sdk 15.9.1 → 16.0.0-beta.2

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

@@ -1,4 +1,15 @@
+import { getWebBotAuthLegacyOriginGate } from "../signing/web-bot-auth.mjs";
 import { RequestSignatureError } from "../signing/errors.mjs";
+import {
+  selectSignatureProfile,
+  verifyWebBotAuth,
+  isWebBotAuthRevocationChecked,
+  webBotAuthUnavailableResponse,
+  WebBotAuthUnavailableError,
+  deferWebBotAuthPrincipalFailure,
+  webBotAuthPrincipalFailureError,
+  WebBotAuthError
+} from "../signing/web-bot-auth.mjs";
 import { InMemoryReplayStore } from "../signing/replay.mjs";
 import { InMemoryRevocationStore } from "../signing/revocation.mjs";
 import {
@@ -23,6 +34,15 @@ import {
 } from "./auth.mjs";
 function verifySignatureAsAuthenticator(options) {
   const replayStore = options.replayStore ?? new InMemoryReplayStore();
+  const legacyOriginGate = options.assertLegacyOriginAllowed ?? getWebBotAuthLegacyOriginGate(options.webBotAuth?.resolvePrincipal);
+  if (options.webBotAuth && !legacyOriginGate)
+    throw new TypeError(
+      "Web Bot Auth requires an origin-binding migration fence; use createIdentity33PrincipalResolver or supply assertLegacyOriginAllowed"
+    );
+  if (options.webBotAuth && !options.webBotAuth.isRevoked && !isWebBotAuthRevocationChecked(options.webBotAuth.resolvePrincipal))
+    throw new TypeError(
+      "Web Bot Auth requires origin revocation: use createIdentity33PrincipalResolver({ revocation }) or supply isRevoked"
+    );
   const revocationStore = options.revocationStore ?? new InMemoryRevocationStore();
   const authenticator = async (req) => {
     if (!hasSignatureHeader(req)) return null;
@@ -36,6 +56,49 @@ function verifySignatureAsAuthenticator(options) {
     };
     let result;
     try {
+      if (selectSignatureProfile(requestLike) === "web-bot-auth") {
+        if (!options.getUrl && !getServeRequestContext(req)?.publicUrl || !options.webBotAuth || !options.capability.profiles?.includes("web-bot-auth"))
+          throw new WebBotAuthError(403, "profile_disabled");
+        if (req.method !== "GET" && req.rawBody === void 0)
+          throw new WebBotAuthError(403, "raw_body_missing");
+        const signers = await verifyWebBotAuth(requestLike, {
+          directory: options.webBotAuth.directory,
+          replayStore,
+          now: options.now,
+          ...options.webBotAuth.isRevoked && { isRevoked: options.webBotAuth.isRevoked }
+        });
+        const operation = options.resolveOperation(req);
+        let principal2;
+        let deferredFailure;
+        try {
+          principal2 = await options.webBotAuth.resolvePrincipal(signers, operation);
+        } catch (error) {
+          if (error instanceof WebBotAuthError || error instanceof WebBotAuthUnavailableError) throw error;
+          if (typeof operation !== "string") throw webBotAuthPrincipalFailureError(error);
+          const deferred = deferWebBotAuthPrincipalFailure(signers, error);
+          principal2 = { principal: deferred.principal };
+          deferredFailure = deferred.authorizationFailure;
+        }
+        const signer2 = signers[signers.length - 1];
+        req.verifiedSigner = {
+          keyid: signer2.keyid,
+          agent_url: signer2.origin,
+          verified_at: signer2.verified_at
+        };
+        const failed = signers.find((s) => s.authorizationFailure);
+        return {
+          ...principal2,
+          extra: {
+            ...principal2.extra,
+            webBotAuthAuthorization: {
+              signer: failed ?? signer2,
+              ...(failed?.authorizationFailure ?? deferredFailure) && {
+                authorizationFailure: failed?.authorizationFailure ?? deferredFailure
+              }
+            }
+          }
+        };
+      }
       result = await verifyRequestSignature(requestLike, {
         capability: options.capability,
         jwks: options.jwks,
@@ -46,7 +109,22 @@ function verifySignatureAsAuthenticator(options) {
         operation: options.resolveOperation(req),
         agentUrlForKeyid: options.agentUrlForKeyid
       });
+      if (result.status === "verified" && legacyOriginGate) {
+        if (!result.agent_url)
+          throw new RequestSignatureError(
+            "request_signature_key_unknown",
+            7,
+            "Legacy signer must resolve an agent origin when migration fencing is enabled"
+          );
+        await legacyOriginGate(result.agent_url);
+      }
     } catch (err) {
+      if (err instanceof WebBotAuthError)
+        throw new AuthError(err.message, { cause: err, status: err.status, headers: err.headers, body: err.body });
+      if (err instanceof WebBotAuthUnavailableError) {
+        const outage = webBotAuthUnavailableResponse();
+        throw new AuthError(err.message, { cause: err, ...outage });
+      }
       if (err instanceof RequestSignatureError) {
         throw new AuthError(`Signature rejected (${err.code}).`, { cause: err });
       }
@@ -67,7 +145,8 @@ function verifySignatureAsAuthenticator(options) {
     req.verifiedSigner = signer;
     return principal;
   };
-  return tagAuthenticatorNeedsRawBody(authenticator);
+  const tagged = tagAuthenticatorNeedsRawBody(authenticator);
+  return options.webBotAuth ? tagAuthenticatorPresenceGated(tagged) : tagged;
 }
 function principalForVerifiedSigner(signer, makePrincipal) {
   if (!SAFE_KEYID.test(signer.keyid)) {
@@ -194,7 +273,7 @@ function logUnresolvable(req) {
 }
 const SAFE_KEYID = /^[A-Za-z0-9._-]{1,256}$/;
 function hasSignatureHeader(req) {
-  return nonEmptyHeader(req.headers["signature-input"]) || nonEmptyHeader(req.headers["signature"]);
+  return req.headers["signature-agent"] !== void 0 || nonEmptyHeader(req.headers["signature-input"]) || nonEmptyHeader(req.headers["signature"]);
 }
 function nonEmptyHeader(v) {
   if (typeof v === "string") return v.length > 0;

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

@@ -145,8 +145,14 @@ export type Authenticator = (req: IncomingMessage) => AuthResult | Promise<AuthR
  */
 export declare class AuthError extends Error {
     readonly publicMessage: string;
+    readonly status?: 400 | 403 | 429 | 503;
+    readonly body?: Record<string, unknown>;
+    readonly headers?: Record<string, string>;
     constructor(publicMessage: string, options?: {
         cause?: unknown;
+        status?: 400 | 403 | 429 | 503;
+        headers?: Record<string, string>;
+        body?: Record<string, unknown>;
     });
 }
 /**

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

@@ -145,8 +145,14 @@ export type Authenticator = (req: IncomingMessage) => AuthResult | Promise<AuthR
  */
 export declare class AuthError extends Error {
     readonly publicMessage: string;
+    readonly status?: 400 | 403 | 429 | 503;
+    readonly body?: Record<string, unknown>;
+    readonly headers?: Record<string, string>;
     constructor(publicMessage: string, options?: {
         cause?: unknown;
+        status?: 400 | 403 | 429 | 503;
+        headers?: Record<string, string>;
+        body?: Record<string, unknown>;
     });
 }
 /**

package/dist/lib/server/auth.js

@@ -56,10 +56,16 @@ const DEFAULT_JWT_ALGORITHMS = Object.freeze([
 const DEFAULT_JWT_CLOCK_TOLERANCE_SECONDS = 30;
 class AuthError extends Error {
   publicMessage;
+  status;
+  body;
+  headers;
   constructor(publicMessage, options) {
     super(publicMessage);
     this.name = "AuthError";
     this.publicMessage = publicMessage;
+    this.body = options?.body;
+    this.status = options?.status;
+    this.headers = options?.headers;
     if (options?.cause !== void 0) this.cause = options.cause;
   }
 }

package/dist/lib/server/auth.mjs

@@ -17,10 +17,16 @@ const DEFAULT_JWT_ALGORITHMS = Object.freeze([
 const DEFAULT_JWT_CLOCK_TOLERANCE_SECONDS = 30;
 class AuthError extends Error {
   publicMessage;
+  status;
+  body;
+  headers;
   constructor(publicMessage, options) {
     super(publicMessage);
     this.name = "AuthError";
     this.publicMessage = publicMessage;
+    this.body = options?.body;
+    this.status = options?.status;
+    this.headers = options?.headers;
     if (options?.cause !== void 0) this.cause = options.cause;
   }
 }

package/dist/lib/server/create-adcp-server.d.mts

@@ -795,7 +795,9 @@ export interface AdcpCapabilitiesConfig {
      */
     supported_versions?: string[];
     features?: Partial<MediaBuyFeatures>;
-    account?: Partial<AccountCapabilities>;
+    account?: Partial<AccountCapabilities> & {
+        agent_onboarding?: import('../identity-3.3/types.mjs').AgentOnboarding;
+    };
     creative?: Partial<CreativeCapabilities>;
     extensions_supported?: readonly string[];
     /**
@@ -812,7 +814,9 @@ export interface AdcpCapabilitiesConfig {
      * claim without a working verifier is graded as FAIL by the conformance
      * runner (see `@adcp/sdk/testing/storyboard/request-signing`).
      */
-    request_signing?: NonNullable<GetAdCPCapabilitiesResponse['request_signing']>;
+    request_signing?: NonNullable<GetAdCPCapabilitiesResponse['request_signing']> & {
+        profiles?: ('adcp/request-signing/v1' | 'web-bot-auth')[];
+    };
     /**
      * Specialism claims the agent supports. Each entry maps to a storyboard
      * bundle under `/compliance/{version}/specialisms/{id}/`; the AAO
@@ -884,9 +888,13 @@ export interface AdcpCapabilitiesOverrides {
     experimental_features?: GetAdCPCapabilitiesResponse['experimental_features'] | null;
     account?: Partial<NonNullable<GetAdCPCapabilitiesResponse['account']>> | null;
     compliance_testing?: GetAdCPCapabilitiesResponse['compliance_testing'] | null;
-    webhook_signing?: GetAdCPCapabilitiesResponse['webhook_signing'] | null;
+    webhook_signing?: (NonNullable<GetAdCPCapabilitiesResponse['webhook_signing']> & {
+        profiles?: ('adcp/webhook-signing/v1' | 'web-bot-auth')[];
+    }) | null;
     identity?: GetAdCPCapabilitiesResponse['identity'] | null;
-    request_signing?: GetAdCPCapabilitiesResponse['request_signing'] | null;
+    request_signing?: (NonNullable<GetAdCPCapabilitiesResponse['request_signing']> & {
+        profiles?: ('adcp/request-signing/v1' | 'web-bot-auth')[];
+    }) | null;
 }
 /**
  * Inputs for the auto-wired RFC 9421 request-signature verifier. When set on
@@ -923,6 +931,8 @@ export interface AdcpCapabilitiesOverrides {
  * abuse / replay-detection guards would be per-request (i.e. broken).
  */
 export interface SignedRequestsConfig {
+    webBotAuth?: import('./auth-signature.mjs').VerifySignatureAsAuthenticatorOptions['webBotAuth'];
+    assertLegacyOriginAllowed?: (agentUrl: string) => Promise<void>;
     /** Resolves verification keys by `keyid`. */
     jwks: JwksResolver;
     /** Stores `(keyid, signature-bytes, expires)` tuples for replay detection. */
@@ -1176,7 +1186,7 @@ export interface AdcpCustomToolConfig<InputArgs extends undefined | ZodRawShapeC
  *
  * @public
  */
-export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerProvider' | 'retries' | 'deliveryStore' | 'idempotencyKeyStore' | 'deliveryRetryHorizonSeconds' | 'deliveryRecovery' | 'generateIdempotencyKey' | 'authorizeAttempt' | 'fetch' | 'userAgent' | 'tag'> & {
+export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerProvider' | 'webBotAuth' | 'signingProfile' | 'retries' | 'deliveryStore' | 'idempotencyKeyStore' | 'deliveryRetryHorizonSeconds' | 'deliveryRecovery' | 'generateIdempotencyKey' | 'authorizeAttempt' | 'fetch' | 'userAgent' | 'tag'> & {
     /** Stable publisher namespace for shared delivery-store keys. Defaults to the trusted server name. */
     publisherScope?: string;
     /** Trusted fallback namespace for a genuinely single-tenant server. */
@@ -1189,6 +1199,10 @@ export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerPr
     onAttemptObserverError?: WebhookEmitterOptions['onAttemptObserverError'];
 };
 export interface AdcpServerConfig<TAccount = unknown> {
+    /** Experimental 3.3 authorization, invoked before idempotency and handler side effects. */
+    identity33?: {
+        authorize: (ctx: HandlerContext<TAccount>, tool: string, params: unknown) => Promise<void>;
+    };
     name: string;
     version: string;
     /**

package/dist/lib/server/create-adcp-server.d.ts

@@ -795,7 +795,9 @@ export interface AdcpCapabilitiesConfig {
      */
     supported_versions?: string[];
     features?: Partial<MediaBuyFeatures>;
-    account?: Partial<AccountCapabilities>;
+    account?: Partial<AccountCapabilities> & {
+        agent_onboarding?: import('../identity-3.3/types').AgentOnboarding;
+    };
     creative?: Partial<CreativeCapabilities>;
     extensions_supported?: readonly string[];
     /**
@@ -812,7 +814,9 @@ export interface AdcpCapabilitiesConfig {
      * claim without a working verifier is graded as FAIL by the conformance
      * runner (see `@adcp/sdk/testing/storyboard/request-signing`).
      */
-    request_signing?: NonNullable<GetAdCPCapabilitiesResponse['request_signing']>;
+    request_signing?: NonNullable<GetAdCPCapabilitiesResponse['request_signing']> & {
+        profiles?: ('adcp/request-signing/v1' | 'web-bot-auth')[];
+    };
     /**
      * Specialism claims the agent supports. Each entry maps to a storyboard
      * bundle under `/compliance/{version}/specialisms/{id}/`; the AAO
@@ -884,9 +888,13 @@ export interface AdcpCapabilitiesOverrides {
     experimental_features?: GetAdCPCapabilitiesResponse['experimental_features'] | null;
     account?: Partial<NonNullable<GetAdCPCapabilitiesResponse['account']>> | null;
     compliance_testing?: GetAdCPCapabilitiesResponse['compliance_testing'] | null;
-    webhook_signing?: GetAdCPCapabilitiesResponse['webhook_signing'] | null;
+    webhook_signing?: (NonNullable<GetAdCPCapabilitiesResponse['webhook_signing']> & {
+        profiles?: ('adcp/webhook-signing/v1' | 'web-bot-auth')[];
+    }) | null;
     identity?: GetAdCPCapabilitiesResponse['identity'] | null;
-    request_signing?: GetAdCPCapabilitiesResponse['request_signing'] | null;
+    request_signing?: (NonNullable<GetAdCPCapabilitiesResponse['request_signing']> & {
+        profiles?: ('adcp/request-signing/v1' | 'web-bot-auth')[];
+    }) | null;
 }
 /**
  * Inputs for the auto-wired RFC 9421 request-signature verifier. When set on
@@ -923,6 +931,8 @@ export interface AdcpCapabilitiesOverrides {
  * abuse / replay-detection guards would be per-request (i.e. broken).
  */
 export interface SignedRequestsConfig {
+    webBotAuth?: import('./auth-signature').VerifySignatureAsAuthenticatorOptions['webBotAuth'];
+    assertLegacyOriginAllowed?: (agentUrl: string) => Promise<void>;
     /** Resolves verification keys by `keyid`. */
     jwks: JwksResolver;
     /** Stores `(keyid, signature-bytes, expires)` tuples for replay detection. */
@@ -1176,7 +1186,7 @@ export interface AdcpCustomToolConfig<InputArgs extends undefined | ZodRawShapeC
  *
  * @public
  */
-export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerProvider' | 'retries' | 'deliveryStore' | 'idempotencyKeyStore' | 'deliveryRetryHorizonSeconds' | 'deliveryRecovery' | 'generateIdempotencyKey' | 'authorizeAttempt' | 'fetch' | 'userAgent' | 'tag'> & {
+export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerProvider' | 'webBotAuth' | 'signingProfile' | 'retries' | 'deliveryStore' | 'idempotencyKeyStore' | 'deliveryRetryHorizonSeconds' | 'deliveryRecovery' | 'generateIdempotencyKey' | 'authorizeAttempt' | 'fetch' | 'userAgent' | 'tag'> & {
     /** Stable publisher namespace for shared delivery-store keys. Defaults to the trusted server name. */
     publisherScope?: string;
     /** Trusted fallback namespace for a genuinely single-tenant server. */
@@ -1189,6 +1199,10 @@ export type WebhooksConfig = Pick<WebhookEmitterOptions, 'signerKey' | 'signerPr
     onAttemptObserverError?: WebhookEmitterOptions['onAttemptObserverError'];
 };
 export interface AdcpServerConfig<TAccount = unknown> {
+    /** Experimental 3.3 authorization, invoked before idempotency and handler side effects. */
+    identity33?: {
+        authorize: (ctx: HandlerContext<TAccount>, tool: string, params: unknown) => Promise<void>;
+    };
     name: string;
     version: string;
     /**