@adcp/sdk 14.0.0-beta.14 → 14.0.0-beta.15

package/dist/lib/server/webhook-delivery/pg.d.ts

@@ -1,5 +1,5 @@
 import type { PgQueryable } from '../postgres-task-store';
-import type { WebhookDeliveryStore } from '../webhook-emitter';
+import type { WebhookDeliveryKey, WebhookDeliveryStore } from '../webhook-emitter';
 import type { WebhookDeliveryRecoveryBackend } from './recovery';
 export interface PgWebhookDeliveryStoreOptions {
     /** Defaults to `adcp_webhook_deliveries`. */
@@ -12,6 +12,8 @@ export interface PgWebhookDeliveryRecoveryOptions {
     tableName?: string;
     /** Assert that the database/schema is dedicated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
+    /** Restrict recovery leases to this trusted publisher/tenant namespace. */
+    claimScope?: Pick<WebhookDeliveryKey, 'publisherScope' | 'tenantScope'>;
 }
 export declare function getWebhookDeliveryMigration(options?: PgWebhookDeliveryStoreOptions): string;
 export declare const WEBHOOK_DELIVERY_MIGRATION: string;

package/dist/lib/server/webhook-delivery/pg.js

@@ -89,6 +89,9 @@ CREATE TABLE IF NOT EXISTS ${table} (
   CONSTRAINT ${raw}_valid_disposition CHECK (disposition IS NULL OR disposition IN ('delivered', 'terminal'))
 );
 
+ALTER TABLE ${table}
+  ADD COLUMN IF NOT EXISTS intent_fingerprint TEXT;
+
 CREATE INDEX IF NOT EXISTS idx_${raw}_pending
   ON ${table}(next_attempt_at, lease_expires_at) WHERE state = 'pending';
 `.trim();
@@ -169,6 +172,14 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
   const tableName = options.tableName ?? DEFAULT_OUTBOX_TABLE;
   const table = (0, import_common.quoteWebhookTable)(tableName);
   assertPgDeploymentNamespace("pgWebhookDeliveryRecoveryBackend", tableName, DEFAULT_OUTBOX_TABLE, options);
+  if (options.claimScope) {
+    (0, import_common.assertDeliveryKey)({ ...options.claimScope, deliveryId: "claim-scope-validation" });
+  }
+  const assertConfiguredScope = (key) => {
+    if (options.claimScope && (key.publisherScope !== options.claimScope.publisherScope || key.tenantScope !== options.claimScope.tenantScope)) {
+      throw new Error("Webhook recovery key is outside the configured claim scope");
+    }
+  };
   async function query(operation, text, values) {
     try {
       return await db.query(text, values);
@@ -182,7 +193,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
       try {
         await db.query(
           `SELECT publisher_scope, tenant_scope, delivery_id, snapshot, snapshot_fingerprint,
-                  storage_fingerprint, state, disposition, attempt_count, next_attempt_at, lease_owner,
+                  storage_fingerprint, intent_fingerprint, state, disposition, attempt_count, next_attempt_at, lease_owner,
                   lease_claim_id, lease_version, lease_expires_at FROM ${table} LIMIT 0`
         );
       } catch (cause) {
@@ -194,6 +205,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async checkpoint(key, snapshot, snapshotFingerprint, storageFingerprint, initialLease) {
       (0, import_common.assertDeliveryKey)(key);
+      assertConfiguredScope(key);
       (0, import_common.assertLeaseControls)(initialLease.ownerToken, initialLease.leaseMs);
       const leaseClaimId = (0, import_node_crypto.randomUUID)();
       const result = await query(
@@ -259,6 +271,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async settle(key, disposition) {
       (0, import_common.assertDeliveryKey)(key);
+      assertConfiguredScope(key);
       (0, import_common.assertWebhookDisposition)(disposition);
       await query(
         "settle",
@@ -271,12 +284,14 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async claimPending({ ownerToken, leaseMs, limit }) {
       (0, import_common.assertLeaseControls)(ownerToken, leaseMs, limit);
+      const scopePredicate = options.claimScope ? "AND publisher_scope = $4 AND tenant_scope = $5" : "";
       const result = await query(
         "claimPending",
         `WITH candidates AS (
            SELECT publisher_scope, tenant_scope, delivery_id
            FROM ${table}
            WHERE state = 'pending'
+             ${scopePredicate}
              AND next_attempt_at <= clock_timestamp()
              AND (lease_expires_at IS NULL OR lease_expires_at < clock_timestamp())
            ORDER BY next_attempt_at, created_at
@@ -299,12 +314,18 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
            FLOOR(EXTRACT(EPOCH FROM outbox.next_attempt_at) * 1000)::bigint AS next_attempt_at_ms,
            outbox.lease_owner, outbox.lease_version,
            FLOOR(EXTRACT(EPOCH FROM outbox.lease_expires_at) * 1000)::bigint AS lease_expires_at_ms`,
-        [ownerToken, leaseMs, limit]
+        [
+          ownerToken,
+          leaseMs,
+          limit,
+          ...options.claimScope ? [options.claimScope.publisherScope, options.claimScope.tenantScope] : []
+        ]
       );
       return result.rows.map(rowToRecoveryRecord);
     },
     async renew(lease, leaseMs) {
       (0, import_common.assertDeliveryKey)(lease.key);
+      assertConfiguredScope(lease.key);
       (0, import_common.assertLeaseControls)(lease.leaseOwner, leaseMs);
       const result = await query(
         "renew",
@@ -326,6 +347,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async release(lease, retryAfterMs) {
       (0, import_common.assertDeliveryKey)(lease.key);
+      assertConfiguredScope(lease.key);
       (0, import_common.assertLeaseControls)(lease.leaseOwner, 1);
       (0, import_common.assertRetryAfterMs)(retryAfterMs);
       const result = await query(
@@ -349,6 +371,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async settleLease(lease, disposition) {
       (0, import_common.assertDeliveryKey)(lease.key);
+      assertConfiguredScope(lease.key);
       (0, import_common.assertLeaseControls)(lease.leaseOwner, 1);
       (0, import_common.assertWebhookDisposition)(disposition);
       const result = await query(

package/dist/lib/server/webhook-delivery/pg.mjs

@@ -70,6 +70,9 @@ CREATE TABLE IF NOT EXISTS ${table} (
   CONSTRAINT ${raw}_valid_disposition CHECK (disposition IS NULL OR disposition IN ('delivered', 'terminal'))
 );
 
+ALTER TABLE ${table}
+  ADD COLUMN IF NOT EXISTS intent_fingerprint TEXT;
+
 CREATE INDEX IF NOT EXISTS idx_${raw}_pending
   ON ${table}(next_attempt_at, lease_expires_at) WHERE state = 'pending';
 `.trim();
@@ -150,6 +153,14 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
   const tableName = options.tableName ?? DEFAULT_OUTBOX_TABLE;
   const table = quoteWebhookTable(tableName);
   assertPgDeploymentNamespace("pgWebhookDeliveryRecoveryBackend", tableName, DEFAULT_OUTBOX_TABLE, options);
+  if (options.claimScope) {
+    assertDeliveryKey({ ...options.claimScope, deliveryId: "claim-scope-validation" });
+  }
+  const assertConfiguredScope = (key) => {
+    if (options.claimScope && (key.publisherScope !== options.claimScope.publisherScope || key.tenantScope !== options.claimScope.tenantScope)) {
+      throw new Error("Webhook recovery key is outside the configured claim scope");
+    }
+  };
   async function query(operation, text, values) {
     try {
       return await db.query(text, values);
@@ -163,7 +174,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
       try {
         await db.query(
           `SELECT publisher_scope, tenant_scope, delivery_id, snapshot, snapshot_fingerprint,
-                  storage_fingerprint, state, disposition, attempt_count, next_attempt_at, lease_owner,
+                  storage_fingerprint, intent_fingerprint, state, disposition, attempt_count, next_attempt_at, lease_owner,
                   lease_claim_id, lease_version, lease_expires_at FROM ${table} LIMIT 0`
         );
       } catch (cause) {
@@ -175,6 +186,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async checkpoint(key, snapshot, snapshotFingerprint, storageFingerprint, initialLease) {
       assertDeliveryKey(key);
+      assertConfiguredScope(key);
       assertLeaseControls(initialLease.ownerToken, initialLease.leaseMs);
       const leaseClaimId = randomUUID();
       const result = await query(
@@ -240,6 +252,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async settle(key, disposition) {
       assertDeliveryKey(key);
+      assertConfiguredScope(key);
       assertWebhookDisposition(disposition);
       await query(
         "settle",
@@ -252,12 +265,14 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async claimPending({ ownerToken, leaseMs, limit }) {
       assertLeaseControls(ownerToken, leaseMs, limit);
+      const scopePredicate = options.claimScope ? "AND publisher_scope = $4 AND tenant_scope = $5" : "";
       const result = await query(
         "claimPending",
         `WITH candidates AS (
            SELECT publisher_scope, tenant_scope, delivery_id
            FROM ${table}
            WHERE state = 'pending'
+             ${scopePredicate}
              AND next_attempt_at <= clock_timestamp()
              AND (lease_expires_at IS NULL OR lease_expires_at < clock_timestamp())
            ORDER BY next_attempt_at, created_at
@@ -280,12 +295,18 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
            FLOOR(EXTRACT(EPOCH FROM outbox.next_attempt_at) * 1000)::bigint AS next_attempt_at_ms,
            outbox.lease_owner, outbox.lease_version,
            FLOOR(EXTRACT(EPOCH FROM outbox.lease_expires_at) * 1000)::bigint AS lease_expires_at_ms`,
-        [ownerToken, leaseMs, limit]
+        [
+          ownerToken,
+          leaseMs,
+          limit,
+          ...options.claimScope ? [options.claimScope.publisherScope, options.claimScope.tenantScope] : []
+        ]
       );
       return result.rows.map(rowToRecoveryRecord);
     },
     async renew(lease, leaseMs) {
       assertDeliveryKey(lease.key);
+      assertConfiguredScope(lease.key);
       assertLeaseControls(lease.leaseOwner, leaseMs);
       const result = await query(
         "renew",
@@ -307,6 +328,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async release(lease, retryAfterMs) {
       assertDeliveryKey(lease.key);
+      assertConfiguredScope(lease.key);
       assertLeaseControls(lease.leaseOwner, 1);
       assertRetryAfterMs(retryAfterMs);
       const result = await query(
@@ -330,6 +352,7 @@ function pgWebhookDeliveryRecoveryBackend(db, options = {}) {
     },
     async settleLease(lease, disposition) {
       assertDeliveryKey(lease.key);
+      assertConfiguredScope(lease.key);
       assertLeaseControls(lease.leaseOwner, 1);
       assertWebhookDisposition(disposition);
       const result = await query(

package/dist/lib/server/webhook-delivery/recovery.d.mts

@@ -10,9 +10,23 @@ export interface WebhookAuthenticationAdapter {
     protect(authentication: Exclude<WebhookAuthentication, null>, context: Readonly<WebhookAuthenticationContext>): Promise<ProtectedWebhookAuthentication> | ProtectedWebhookAuthentication;
     resolve(protectedValue: unknown, context: Readonly<WebhookAuthenticationContext>): Promise<WebhookAuthentication> | WebhookAuthentication;
 }
+/** Retryable failure while calling an application's KMS/secret adapter. */
+export declare class WebhookAuthenticationProtectionError extends Error {
+    readonly name = "WebhookAuthenticationProtectionError";
+}
+/** Retryable failure while resolving protected authentication for delivery. */
+export declare class WebhookAuthenticationResolutionError extends Error {
+    readonly name = "WebhookAuthenticationResolutionError";
+}
 export interface WebhookAuthenticationContext {
     key: WebhookDeliveryKey;
     url: string;
+    /**
+     * Domain-separates task payload validation tokens. Undefined is the
+     * original transport-authentication context and is intentionally preserved
+     * so pending encrypted snapshots remain decryptable across SDK upgrades.
+     */
+    purpose?: 'payload_token';
     snapshotContextFingerprint: string;
 }
 export interface StoredWebhookDeliverySnapshot {
@@ -25,8 +39,32 @@ export interface StoredWebhookDeliverySnapshot {
         protectedValue: unknown;
         fingerprint: string;
     };
+    /**
+     * A top-level task-webhook `token`, protected independently from transport
+     * authentication. The cleartext is restored only after a recovery lease is
+     * claimed and is never written to the outbox JSON payload.
+     */
+    payloadToken?: {
+        kind: 'protected';
+        protectedValue: unknown;
+        fingerprint: string;
+    };
     retries: WebhookDeliverySnapshot['retries'];
 }
+/** Storage-ready snapshot used by transactional outbox coordinators. */
+export interface PreparedWebhookDeliverySnapshot {
+    snapshot: StoredWebhookDeliverySnapshot;
+    snapshotFingerprint: string;
+    storageFingerprint: string;
+}
+export interface PrepareWebhookDeliveryOptions {
+    /**
+     * Protect and remove the top-level `payload.token` before persistence.
+     * This is opt-in because generic webhook payloads may legitimately use a
+     * non-secret field with that name.
+     */
+    protectPayloadToken?: boolean;
+}
 export interface WebhookRecoveryRecord {
     key: WebhookDeliveryKey;
     snapshot: StoredWebhookDeliverySnapshot;
@@ -71,6 +109,12 @@ export interface WebhookDeliveryRecoveryBackend {
 }
 export interface DurableWebhookDeliveryRecovery extends WebhookDeliveryRecovery {
     probe(): Promise<void>;
+    /**
+     * Protect and fingerprint a snapshot without writing it. This is reserved
+     * for coordinators that insert the returned value in the same database
+     * transaction as their domain mutation.
+     */
+    prepare(key: Readonly<WebhookDeliveryKey>, snapshot: Readonly<WebhookDeliverySnapshot>, options?: Readonly<PrepareWebhookDeliveryOptions>): Promise<PreparedWebhookDeliverySnapshot>;
     claimPending(options: {
         ownerToken?: string;
         leaseMs?: number;

package/dist/lib/server/webhook-delivery/recovery.d.ts

@@ -10,9 +10,23 @@ export interface WebhookAuthenticationAdapter {
     protect(authentication: Exclude<WebhookAuthentication, null>, context: Readonly<WebhookAuthenticationContext>): Promise<ProtectedWebhookAuthentication> | ProtectedWebhookAuthentication;
     resolve(protectedValue: unknown, context: Readonly<WebhookAuthenticationContext>): Promise<WebhookAuthentication> | WebhookAuthentication;
 }
+/** Retryable failure while calling an application's KMS/secret adapter. */
+export declare class WebhookAuthenticationProtectionError extends Error {
+    readonly name = "WebhookAuthenticationProtectionError";
+}
+/** Retryable failure while resolving protected authentication for delivery. */
+export declare class WebhookAuthenticationResolutionError extends Error {
+    readonly name = "WebhookAuthenticationResolutionError";
+}
 export interface WebhookAuthenticationContext {
     key: WebhookDeliveryKey;
     url: string;
+    /**
+     * Domain-separates task payload validation tokens. Undefined is the
+     * original transport-authentication context and is intentionally preserved
+     * so pending encrypted snapshots remain decryptable across SDK upgrades.
+     */
+    purpose?: 'payload_token';
     snapshotContextFingerprint: string;
 }
 export interface StoredWebhookDeliverySnapshot {
@@ -25,8 +39,32 @@ export interface StoredWebhookDeliverySnapshot {
         protectedValue: unknown;
         fingerprint: string;
     };
+    /**
+     * A top-level task-webhook `token`, protected independently from transport
+     * authentication. The cleartext is restored only after a recovery lease is
+     * claimed and is never written to the outbox JSON payload.
+     */
+    payloadToken?: {
+        kind: 'protected';
+        protectedValue: unknown;
+        fingerprint: string;
+    };
     retries: WebhookDeliverySnapshot['retries'];
 }
+/** Storage-ready snapshot used by transactional outbox coordinators. */
+export interface PreparedWebhookDeliverySnapshot {
+    snapshot: StoredWebhookDeliverySnapshot;
+    snapshotFingerprint: string;
+    storageFingerprint: string;
+}
+export interface PrepareWebhookDeliveryOptions {
+    /**
+     * Protect and remove the top-level `payload.token` before persistence.
+     * This is opt-in because generic webhook payloads may legitimately use a
+     * non-secret field with that name.
+     */
+    protectPayloadToken?: boolean;
+}
 export interface WebhookRecoveryRecord {
     key: WebhookDeliveryKey;
     snapshot: StoredWebhookDeliverySnapshot;
@@ -71,6 +109,12 @@ export interface WebhookDeliveryRecoveryBackend {
 }
 export interface DurableWebhookDeliveryRecovery extends WebhookDeliveryRecovery {
     probe(): Promise<void>;
+    /**
+     * Protect and fingerprint a snapshot without writing it. This is reserved
+     * for coordinators that insert the returned value in the same database
+     * transaction as their domain mutation.
+     */
+    prepare(key: Readonly<WebhookDeliveryKey>, snapshot: Readonly<WebhookDeliverySnapshot>, options?: Readonly<PrepareWebhookDeliveryOptions>): Promise<PreparedWebhookDeliverySnapshot>;
     claimPending(options: {
         ownerToken?: string;
         leaseMs?: number;

package/dist/lib/server/webhook-delivery/recovery.js

@@ -18,6 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var recovery_exports = {};
 __export(recovery_exports, {
+  WebhookAuthenticationProtectionError: () => WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError: () => WebhookAuthenticationResolutionError,
   createWebhookDeliveryRecovery: () => createWebhookDeliveryRecovery,
   memoryWebhookDeliveryRecoveryBackend: () => memoryWebhookDeliveryRecoveryBackend,
   pollWebhookDeliveryRecovery: () => pollWebhookDeliveryRecovery
@@ -26,6 +28,12 @@ module.exports = __toCommonJS(recovery_exports);
 var import_node_crypto = require("node:crypto");
 var import_jcs = require('../../utils/jcs.js');
 var import_common = require('./common.js');
+class WebhookAuthenticationProtectionError extends Error {
+  name = "WebhookAuthenticationProtectionError";
+}
+class WebhookAuthenticationResolutionError extends Error {
+  name = "WebhookAuthenticationResolutionError";
+}
 function memoryWebhookDeliveryRecoveryBackend(options = {}) {
   const records = /* @__PURE__ */ new Map();
   const now = options.now ?? Date.now;
@@ -135,13 +143,25 @@ function createWebhookDeliveryRecovery(options) {
   return {
     durability: "durable",
     probe: () => options.backend.probe(),
+    async prepare(key, snapshot, prepareOptions) {
+      (0, import_common.assertDeliveryKey)(key);
+      const stored = await protectSnapshot(
+        snapshot,
+        key,
+        options.authenticationAdapter,
+        prepareOptions?.protectPayloadToken === true
+      );
+      assertStoredSnapshotSize(stored, maxSnapshotBytes);
+      return {
+        snapshot: stored,
+        snapshotFingerprint: snapshotFingerprint(stored),
+        storageFingerprint: (0, import_jcs.canonicalJsonSha256)(stored)
+      };
+    },
     async checkpoint(key, snapshot) {
       (0, import_common.assertDeliveryKey)(key);
-      const stored = await protectSnapshot(snapshot, key, options.authenticationAdapter);
-      const storedBytes = Buffer.byteLength(JSON.stringify(stored));
-      if (storedBytes > maxSnapshotBytes) {
-        throw new TypeError(`Webhook recovery snapshot exceeds maxSnapshotBytes (${maxSnapshotBytes})`);
-      }
+      const stored = await protectSnapshot(snapshot, key, options.authenticationAdapter, false);
+      assertStoredSnapshotSize(stored, maxSnapshotBytes);
       const fingerprint = snapshotFingerprint(stored);
       const storageFingerprint = (0, import_jcs.canonicalJsonSha256)(stored);
       const ownerToken = (0, import_node_crypto.randomUUID)();
@@ -313,59 +333,101 @@ function assertPollOutcome(outcome) {
     throw new TypeError("Webhook recovery deliver() returned an invalid disposition");
   }
 }
-async function protectSnapshot(snapshot, key, adapter) {
+async function protectSnapshot(snapshot, key, adapter, protectPayloadToken) {
+  const payload = structuredClone(snapshot.payload);
+  const cleartextPayloadToken = protectPayloadToken && typeof payload.token === "string" ? payload.token : void 0;
+  if (cleartextPayloadToken !== void 0) delete payload.token;
   const base = {
     url: snapshot.url,
-    payload: structuredClone(snapshot.payload),
+    payload,
     retries: { ...snapshot.retries }
   };
   (0, import_jcs.canonicalJsonSha256)(base);
-  if (snapshot.authentication === null) return { ...base, authentication: { kind: "none" } };
-  if (!adapter) {
+  if ((snapshot.authentication !== null || cleartextPayloadToken !== void 0) && !adapter) {
     throw new TypeError(
-      "Durable webhook recovery requires authenticationAdapter when bearer or HMAC authentication is present"
+      "Durable webhook recovery requires authenticationAdapter when bearer/HMAC authentication or a payload token is present"
     );
   }
-  const context = authenticationContext(key, base);
-  const protectedAuth = await adapter.protect(structuredClone(snapshot.authentication), context);
-  if (!protectedAuth || typeof protectedAuth.fingerprint !== "string" || protectedAuth.fingerprint.length < 16) {
-    throw new TypeError(
-      "WebhookAuthenticationAdapter.protect() must return a stable fingerprint of at least 16 characters"
-    );
-  }
-  (0, import_jcs.canonicalJsonSha256)(protectedAuth.protectedValue);
-  return {
+  const stored = {
     ...base,
-    authentication: {
-      kind: "protected",
-      protectedValue: structuredClone(protectedAuth.protectedValue),
-      fingerprint: protectedAuth.fingerprint
-    }
+    authentication: { kind: "none" }
   };
+  if (snapshot.authentication !== null) {
+    const protectedAuth = await protectAuthentication(
+      adapter,
+      structuredClone(snapshot.authentication),
+      authenticationContext(key, base)
+    );
+    stored.authentication = { kind: "protected", ...protectedAuth };
+  }
+  if (cleartextPayloadToken !== void 0) {
+    const protectedToken = await protectAuthentication(
+      adapter,
+      { type: "bearer", token: cleartextPayloadToken },
+      authenticationContext(key, base, "payload_token")
+    );
+    stored.payloadToken = { kind: "protected", ...protectedToken };
+  }
+  return stored;
 }
 async function resolveSnapshot(snapshot, key, adapter) {
-  let authentication = null;
-  if (snapshot.authentication.kind === "protected") {
-    if (!adapter) throw new Error("Cannot recover protected webhook authentication without authenticationAdapter");
-    authentication = await adapter.resolve(
-      structuredClone(snapshot.authentication.protectedValue),
-      authenticationContext(key, snapshot)
-    );
-    if (authentication === null)
-      throw new Error("WebhookAuthenticationAdapter.resolve() returned null for protected state");
+  try {
+    let authentication = null;
+    if (snapshot.authentication.kind === "protected") {
+      if (!adapter) throw new Error("Cannot recover protected webhook authentication without authenticationAdapter");
+      authentication = await adapter.resolve(
+        structuredClone(snapshot.authentication.protectedValue),
+        authenticationContext(key, snapshot)
+      );
+      if (authentication === null)
+        throw new Error("WebhookAuthenticationAdapter.resolve() returned null for protected state");
+    }
+    const payload = structuredClone(snapshot.payload);
+    if (snapshot.payloadToken) {
+      if (!adapter) throw new Error("Cannot recover protected webhook payload token without authenticationAdapter");
+      const resolved = await adapter.resolve(
+        structuredClone(snapshot.payloadToken.protectedValue),
+        authenticationContext(key, snapshot, "payload_token")
+      );
+      if (resolved?.type !== "bearer" || typeof resolved.token !== "string") {
+        throw new Error("WebhookAuthenticationAdapter.resolve() returned an invalid protected payload token");
+      }
+      payload.token = resolved.token;
+    }
+    return {
+      url: snapshot.url,
+      payload,
+      authentication,
+      retries: { ...snapshot.retries }
+    };
+  } catch (cause) {
+    if (cause instanceof WebhookAuthenticationResolutionError) throw cause;
+    throw new WebhookAuthenticationResolutionError("Webhook authentication resolution failed", { cause });
   }
-  return {
-    url: snapshot.url,
-    payload: structuredClone(snapshot.payload),
-    authentication,
-    retries: { ...snapshot.retries }
-  };
 }
-function authenticationContext(key, snapshot) {
-  return {
+function authenticationContext(key, snapshot, purpose) {
+  const base = {
     key: { ...key },
-    url: snapshot.url,
+    url: snapshot.url
+  };
+  if (purpose === void 0) {
+    return {
+      ...base,
+      // This is the exact pre-payload-token context hash. Do not change it:
+      // applications may bind KMS AAD to this value for pending snapshots.
+      snapshotContextFingerprint: (0, import_jcs.canonicalJsonSha256)({
+        key,
+        url: snapshot.url,
+        payload: snapshot.payload,
+        retries: snapshot.retries
+      })
+    };
+  }
+  return {
+    ...base,
+    purpose,
     snapshotContextFingerprint: (0, import_jcs.canonicalJsonSha256)({
+      purpose,
       key,
       url: snapshot.url,
       payload: snapshot.payload,
@@ -421,9 +483,48 @@ function snapshotFingerprint(snapshot) {
     url: snapshot.url,
     payload: snapshot.payload,
     retries: snapshot.retries,
-    authentication: snapshot.authentication.kind === "none" ? { kind: "none" } : { kind: "protected", fingerprint: snapshot.authentication.fingerprint }
+    authentication: snapshot.authentication.kind === "none" ? { kind: "none" } : { kind: "protected", fingerprint: snapshot.authentication.fingerprint },
+    ...snapshot.payloadToken && { payloadToken: { fingerprint: snapshot.payloadToken.fingerprint } }
   });
 }
+async function protectAuthentication(adapter, authentication, context) {
+  let protectedAuth;
+  try {
+    protectedAuth = await adapter.protect(authentication, context);
+  } catch (cause) {
+    throw new WebhookAuthenticationProtectionError("Webhook authentication protection failed", { cause });
+  }
+  if (!protectedAuth || typeof protectedAuth.fingerprint !== "string" || protectedAuth.fingerprint.length < 16) {
+    throw new TypeError(
+      "WebhookAuthenticationAdapter.protect() must return a stable fingerprint of at least 16 characters"
+    );
+  }
+  (0, import_jcs.canonicalJsonSha256)(protectedAuth.protectedValue);
+  const cleartext = authentication.type === "bearer" ? authentication.token : authentication.secret;
+  if (protectedValueContainsSecret(protectedAuth.protectedValue, cleartext) || protectedAuth.fingerprint.includes(cleartext)) {
+    throw new TypeError("WebhookAuthenticationAdapter.protect() returned durable state containing cleartext");
+  }
+  return {
+    protectedValue: structuredClone(protectedAuth.protectedValue),
+    fingerprint: protectedAuth.fingerprint
+  };
+}
+function protectedValueContainsSecret(value, cleartext) {
+  if (typeof value === "string") return value.includes(cleartext);
+  if (Array.isArray(value)) return value.some((item) => protectedValueContainsSecret(item, cleartext));
+  if (value && typeof value === "object") {
+    return Object.entries(value).some(
+      ([key, item]) => key.includes(cleartext) || protectedValueContainsSecret(item, cleartext)
+    );
+  }
+  return false;
+}
+function assertStoredSnapshotSize(snapshot, maxSnapshotBytes) {
+  const storedBytes = Buffer.byteLength(JSON.stringify(snapshot));
+  if (storedBytes > maxSnapshotBytes) {
+    throw new TypeError(`Webhook recovery snapshot exceeds maxSnapshotBytes (${maxSnapshotBytes})`);
+  }
+}
 function assertLeaseMs(value) {
   if (!Number.isSafeInteger(value) || value < 1e3 || value > 36e5) {
     throw new TypeError("leaseMs must be an integer from 1000 through 3600000");
@@ -431,6 +532,8 @@ function assertLeaseMs(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   createWebhookDeliveryRecovery,
   memoryWebhookDeliveryRecoveryBackend,
   pollWebhookDeliveryRecovery