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

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.mjs

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonSha256 } from "../../../utils/jcs.mjs";
+import { isAdcpVersionAtLeast, isValidAdcpVersion } from "../../../utils/adcp-version-config.mjs";
+import { sanitizeStructuredAdcpError } from "../../errors.mjs";
+import { quoteWebhookTable } from "../../webhook-delivery/common.mjs";
+import {
+  createWebhookDeliveryRecovery,
+  WebhookAuthenticationProtectionError
+} from "../../webhook-delivery/recovery.mjs";
+import { pgWebhookDeliveryRecoveryBackend } from "../../webhook-delivery/pg.mjs";
+import { protocolForTool, SPEC_WEBHOOK_TASK_TYPES } from "./protocol-for-tool.mjs";
+import {
+  _postgresTaskRegistryBinding
+} from "./postgres-task-registry.mjs";
+import { sanitizeTaskResultForWire } from "./task-registry.mjs";
+class TaskPushSettlementConfigurationError extends Error {
+  name = "TaskPushSettlementConfigurationError";
+}
+const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "rejected", "canceled"]);
+const MAX_RESULT_BYTES = 4 * 1024 * 1024;
+const TOKEN_CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+function createPostgresTaskSettlementCoordinator(options) {
+  const binding = _postgresTaskRegistryBinding(options.registry);
+  if (!binding) {
+    throw new TypeError("createPostgresTaskSettlementCoordinator requires a registry from createPostgresTaskRegistry");
+  }
+  const pool = binding.pool;
+  if (typeof pool.connect !== "function") {
+    throw new TypeError(
+      "Crash-safe task settlement requires a pg Pool with connect(); a query-only adapter cannot own a transaction"
+    );
+  }
+  if (typeof options.registry.registryId !== "string" || options.registry.registryId.length === 0) {
+    throw new TypeError("Crash-safe task settlement requires task registry storageId/registryId binding");
+  }
+  if (typeof options.publisherScope !== "string" || options.publisherScope.length === 0) {
+    throw new TypeError("publisherScope must be a non-empty string");
+  }
+  const outboxOptions = options.outbox ?? {};
+  const outboxTable = quoteWebhookTable(outboxOptions.tableName ?? "adcp_webhook_outbox");
+  const claimScope = {
+    publisherScope: options.publisherScope,
+    tenantScope: stableRegistryScope(options.registry.registryId, binding.namespace)
+  };
+  const backend = pgWebhookDeliveryRecoveryBackend(binding.pool, { ...outboxOptions, claimScope });
+  const recovery = createWebhookDeliveryRecovery({
+    ...options.recovery,
+    backend,
+    ...options.authenticationAdapter && { authenticationAdapter: options.authenticationAdapter }
+  });
+  const retries = resolveRetries(options.retries);
+  return {
+    durability: "durable",
+    recovery,
+    async settle(ref, terminal, push) {
+      if (ref.registryId !== options.registry.registryId) {
+        return { outcome: "not_found_in_scope", delivery: "not_applicable" };
+      }
+      let client;
+      try {
+        client = await pool.connect();
+        await client.query("BEGIN");
+        const locked = await client.query(
+          `SELECT tool, status, result, error, has_webhook
+             FROM ${binding.tableName}
+            WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4
+            FOR UPDATE`,
+          [ref.taskId, binding.namespace, ref.accountId, ref.ownerScope]
+        );
+        if (locked.rows.length === 0) {
+          await client.query("ROLLBACK");
+          return { outcome: "not_found_in_scope", delivery: "not_applicable" };
+        }
+        const row = locked.rows[0];
+        validatePush(push);
+        if (row.has_webhook !== true) {
+          throw new TaskPushSettlementConfigurationError(
+            "Crash-safe push settlement requires a task created with hasWebhook: true"
+          );
+        }
+        let result;
+        let error;
+        try {
+          result = terminal.status === "completed" ? sanitizeTaskResultForWire(structuredClone(terminal.result), ref) : terminal.result === void 0 ? { errors: [sanitizeStructuredAdcpError(terminal.error)] } : sanitizeTaskResultForWire(structuredClone(terminal.result), ref);
+          error = terminal.status === "failed" ? sanitizeStructuredAdcpError(terminal.error) : void 0;
+          canonicalJsonSha256({ result, error });
+          assertPayloadSize(result, error);
+        } catch (cause) {
+          if (cause instanceof TaskPushSettlementConfigurationError) throw cause;
+          throw new TaskPushSettlementConfigurationError("Task terminal result/error must be serializable JSON", {
+            cause
+          });
+        }
+        const compatible = terminalMatches(row, terminal.status, result, error);
+        if (TERMINAL.has(row.status) && !compatible) {
+          await client.query("COMMIT");
+          return {
+            outcome: "already_terminal",
+            status: row.status,
+            compatibility: "conflicting",
+            delivery: "not_applicable"
+          };
+        }
+        const deliveryKey = {
+          ...claimScope,
+          deliveryId: stableScope("task-webhook", ref)
+        };
+        const existing = await readOutbox(client, outboxTable, deliveryKey);
+        if (TERMINAL.has(row.status) && !existing) {
+          throw new TaskPushSettlementConfigurationError(
+            "Terminal task has no atomic webhook delivery checkpoint; refusing to create a duplicate notification"
+          );
+        }
+        let inserted = false;
+        let delivery = existing ? deliveryState(existing) : void 0;
+        if (!SPEC_WEBHOOK_TASK_TYPES.has(row.tool)) {
+          throw new TaskPushSettlementConfigurationError(
+            `Task type ${row.tool} cannot be emitted by the closed AdCP task-webhook schema`
+          );
+        }
+        const existingTimestamp = existing?.state === "pending" ? existing.snapshot.payload.timestamp : void 0;
+        const payload = {
+          idempotency_key: `pending.${deliveryKey.deliveryId.slice(-48)}`,
+          operation_id: resolveOperationId(push, row.tool, ref.taskId),
+          task_id: ref.taskId,
+          task_type: row.tool,
+          status: terminal.status,
+          timestamp: typeof existingTimestamp === "string" ? existingTimestamp : (/* @__PURE__ */ new Date()).toISOString(),
+          protocol: protocolForTool(row.tool),
+          result,
+          ...push.token !== void 0 && { token: push.token },
+          ...terminal.status === "failed" && { message: error.message }
+        };
+        let prepared;
+        try {
+          prepared = await recovery.prepare(
+            deliveryKey,
+            {
+              url: push.url,
+              payload,
+              authentication: push.authentication ?? null,
+              retries
+            },
+            { protectPayloadToken: push.token !== void 0 }
+          );
+        } catch (cause) {
+          if (cause instanceof WebhookAuthenticationProtectionError) throw cause;
+          throw new TaskPushSettlementConfigurationError("Terminal webhook delivery configuration is invalid", {
+            cause
+          });
+        }
+        const intentFingerprint = taskPushIntentFingerprint(prepared.snapshot);
+        if (existing?.state === "settled") {
+          if (!TERMINAL.has(row.status)) {
+            throw new Error("Settled webhook outbox row exists for a non-terminal task");
+          }
+          if (existing.intent_fingerprint && existing.intent_fingerprint !== intentFingerprint) {
+            throw new TaskPushSettlementConfigurationError(
+              "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+            );
+          }
+          await client.query("COMMIT");
+          return {
+            outcome: "already_terminal",
+            status: row.status,
+            compatibility: "compatible",
+            delivery: deliveryState(existing)
+          };
+        }
+        if (existing && existing.snapshot_fingerprint !== prepared.snapshotFingerprint) {
+          throw new TaskPushSettlementConfigurationError(
+            "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+          );
+        }
+        if (!existing) {
+          const write = await client.query(
+            `INSERT INTO ${outboxTable} (
+               publisher_scope, tenant_scope, delivery_id, snapshot, snapshot_fingerprint,
+               storage_fingerprint, intent_fingerprint, state, attempt_count, next_attempt_at
+             ) VALUES ($1, $2, $3, $4::jsonb, $5, $6, $7, 'pending', 0, clock_timestamp())
+             ON CONFLICT (publisher_scope, tenant_scope, delivery_id) DO NOTHING`,
+            [
+              deliveryKey.publisherScope,
+              deliveryKey.tenantScope,
+              deliveryKey.deliveryId,
+              JSON.stringify(prepared.snapshot),
+              prepared.snapshotFingerprint,
+              prepared.storageFingerprint,
+              intentFingerprint
+            ]
+          );
+          if ((write.rowCount ?? 0) !== 1) {
+            const raced = await readOutbox(client, outboxTable, deliveryKey);
+            if (!raced || raced.snapshot_fingerprint !== prepared.snapshotFingerprint) {
+              throw new TaskPushSettlementConfigurationError(
+                "Terminal webhook delivery identity is already bound to a conflicting route or payload"
+              );
+            }
+            delivery = deliveryState(raced);
+          } else {
+            inserted = true;
+            delivery = "durably_bound";
+          }
+        }
+        if (!TERMINAL.has(row.status)) {
+          const update = terminal.status === "completed" ? await client.query(
+            `UPDATE ${binding.tableName}
+                      SET status = 'completed', result = $5::jsonb, error = NULL,
+                          status_message = NULL, updated_at = clock_timestamp()
+                    WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
+            [ref.taskId, binding.namespace, ref.accountId, ref.ownerScope, JSON.stringify(result)]
+          ) : await client.query(
+            `UPDATE ${binding.tableName}
+                      SET status = 'failed', result = $5::jsonb, error = $6::jsonb,
+                          status_message = $7, updated_at = clock_timestamp()
+                    WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
+            [
+              ref.taskId,
+              binding.namespace,
+              ref.accountId,
+              ref.ownerScope,
+              JSON.stringify(result),
+              JSON.stringify(error),
+              error.message
+            ]
+          );
+          if ((update.rowCount ?? 0) !== 1) throw new Error("Task disappeared while holding its settlement lock");
+          await client.query("COMMIT");
+          return { outcome: "applied", delivery: "durably_bound" };
+        }
+        await client.query("COMMIT");
+        return {
+          outcome: "already_terminal",
+          status: row.status,
+          compatibility: "compatible",
+          delivery: inserted ? "durably_bound" : delivery ?? "recoverable"
+        };
+      } catch (cause) {
+        if (client) await rollbackQuietly(client);
+        if (cause instanceof TaskPushSettlementConfigurationError) throw cause;
+        throw new Error("PostgresTaskSettlementCoordinator.settle: transaction failed", { cause });
+      } finally {
+        client?.release();
+      }
+    }
+  };
+}
+async function completeScopedPushTask(coordinator, ref, push, result) {
+  return coordinator.settle(ref, { status: "completed", result }, push);
+}
+async function failScopedPushTask(coordinator, ref, push, error, result) {
+  return coordinator.settle(ref, { status: "failed", error, ...result !== void 0 && { result } }, push);
+}
+function terminalMatches(row, status, result, error) {
+  if (row.status !== status) return false;
+  return canonicalJsonSha256(row.result) === canonicalJsonSha256(result) && (status === "completed" || canonicalJsonSha256(row.error) === canonicalJsonSha256(error));
+}
+function stableScope(prefix, ref) {
+  const digest = createHash("sha256").update(JSON.stringify([ref.registryId, ref.accountId, ref.ownerScope, ref.taskId])).digest("hex");
+  return `${prefix}:${digest}`;
+}
+function stableRegistryScope(registryId, namespace) {
+  const digest = createHash("sha256").update(JSON.stringify([registryId, namespace])).digest("hex");
+  return `task-registry:${digest}`;
+}
+function taskPushIntentFingerprint(snapshot) {
+  const { timestamp: _generatedTimestamp, ...payload } = snapshot.payload;
+  return canonicalJsonSha256({
+    url: snapshot.url,
+    payload,
+    retries: snapshot.retries,
+    authentication: snapshot.authentication.kind === "none" ? { kind: "none" } : { kind: "protected", fingerprint: snapshot.authentication.fingerprint },
+    ...snapshot.payloadToken && { payloadToken: { fingerprint: snapshot.payloadToken.fingerprint } }
+  });
+}
+function validatePush(push) {
+  if (!push || typeof push !== "object") {
+    throw new TaskPushSettlementConfigurationError("push settlement config is required");
+  }
+  const allowHttp = process.env.NODE_ENV === "test" || process.env.NODE_ENV === "development" || process.env.ADCP_DECISIONING_ALLOW_HTTP_WEBHOOKS === "1";
+  let parsedUrl;
+  try {
+    parsedUrl = typeof push.url === "string" ? new URL(push.url) : void 0;
+  } catch {
+  }
+  if (parsedUrl === void 0 || parsedUrl.hostname.length === 0 || parsedUrl.username.length > 0 || parsedUrl.password.length > 0 || parsedUrl.protocol !== "https:" && !(allowHttp && parsedUrl.protocol === "http:")) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement url must be a request-validated HTTPS destination (HTTP requires the development allowlist)"
+    );
+  }
+  if (push.operationId !== void 0 && (typeof push.operationId !== "string" || !/^[A-Za-z0-9_.:-]{1,255}$/.test(push.operationId))) {
+    throw new TaskPushSettlementConfigurationError("push settlement operationId must match /^[A-Za-z0-9_.:-]{1,255}$/");
+  }
+  if (push.operationId === void 0 && (!isValidAdcpVersion(push.servedAdcpVersion) || isAdcpVersionAtLeast(push.servedAdcpVersion, "3.2.0-beta.5"))) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement operationId is required unless servedAdcpVersion is an explicit valid pre-3.2.0-beta.5 version"
+    );
+  }
+  if (push.token !== void 0 && (typeof push.token !== "string" || push.token.length < 16 || push.token.length > 4096 || TOKEN_CONTROL_CHAR_RE.test(push.token))) {
+    throw new TaskPushSettlementConfigurationError(
+      "push settlement token must be a string from 16 through 4096 characters"
+    );
+  }
+  if (push.authentication !== void 0 && push.authentication !== null) {
+    const authentication = push.authentication;
+    const validBearer = authentication.type === "bearer" && typeof authentication.token === "string" && authentication.token.length >= 32;
+    const validHmac = authentication.type === "hmac_sha256" && typeof authentication.secret === "string" && authentication.secret.length >= 32;
+    if (!validBearer && !validHmac) {
+      throw new TaskPushSettlementConfigurationError(
+        "push settlement authentication must be a WebhookAuthentication value"
+      );
+    }
+  }
+}
+function resolveOperationId(push, tool, taskId) {
+  return push.operationId ?? `${tool}.${taskId}`;
+}
+function resolveRetries(retries) {
+  const resolved = {
+    maxAttempts: retries?.maxAttempts ?? 5,
+    initialDelayMs: retries?.initialDelayMs ?? 1e3,
+    maxDelayMs: retries?.maxDelayMs ?? 6e4,
+    jitter: retries?.jitter ?? 0.25
+  };
+  if (!Number.isSafeInteger(resolved.maxAttempts) || resolved.maxAttempts < 1) {
+    throw new TypeError("retries.maxAttempts must be an integer of at least 1");
+  }
+  for (const key of ["initialDelayMs", "maxDelayMs"]) {
+    if (!Number.isFinite(resolved[key]) || resolved[key] < 0) {
+      throw new TypeError(`retries.${key} must be a finite non-negative number`);
+    }
+  }
+  if (!Number.isFinite(resolved.jitter) || resolved.jitter < 0 || resolved.jitter > 1) {
+    throw new TypeError("retries.jitter must be a finite number from 0 through 1");
+  }
+  return resolved;
+}
+function assertPayloadSize(result, error) {
+  const bytes = Buffer.byteLength(JSON.stringify({ result, error }), "utf8");
+  if (bytes > MAX_RESULT_BYTES) {
+    throw new TaskPushSettlementConfigurationError(`Task result/error JSON exceeds ${MAX_RESULT_BYTES} bytes`);
+  }
+}
+async function readOutbox(client, table, key) {
+  const found = await client.query(
+    `SELECT snapshot, snapshot_fingerprint, intent_fingerprint, state, disposition
+       FROM ${table}
+      WHERE publisher_scope = $1 AND tenant_scope = $2 AND delivery_id = $3
+      FOR UPDATE`,
+    [key.publisherScope, key.tenantScope, key.deliveryId]
+  );
+  return found.rows[0];
+}
+function deliveryState(row) {
+  if (row.state !== "settled") return "recoverable";
+  return row.disposition === "delivered" ? "delivered" : "terminal";
+}
+async function rollbackQuietly(client) {
+  try {
+    await client.query("ROLLBACK");
+  } catch {
+  }
+}
+export {
+  TaskPushSettlementConfigurationError,
+  completeScopedPushTask,
+  createPostgresTaskSettlementCoordinator,
+  failScopedPushTask
+};

package/dist/lib/server/decisioning/runtime/task-registry.d.mts

@@ -114,6 +114,8 @@ export interface TaskRegistryListResult<TResult = unknown> {
 export interface TaskRegistry {
     /** Confirms that lifecycle methods use the account/principal-scoped v1 signatures. */
     readonly scopeVersion: 1;
+    /** Whether stored rows can be reopened by a different process after restart. */
+    readonly durability?: 'durable' | 'process-local';
     /**
      * Identity bound into every durable task reference issued by this registry.
      * It is stable for the lifetime of stored records and rotates when a

package/dist/lib/server/decisioning/runtime/task-registry.d.ts

@@ -114,6 +114,8 @@ export interface TaskRegistryListResult<TResult = unknown> {
 export interface TaskRegistry {
     /** Confirms that lifecycle methods use the account/principal-scoped v1 signatures. */
     readonly scopeVersion: 1;
+    /** Whether stored rows can be reopened by a different process after restart. */
+    readonly durability?: 'durable' | 'process-local';
     /**
      * Identity bound into every durable task reference issued by this registry.
      * It is stable for the lifetime of stored records and rotates when a

package/dist/lib/server/decisioning/runtime/task-registry.js

@@ -107,6 +107,7 @@ function createInMemoryTaskRegistry() {
   let registryId = `memory:${(0, import_node_crypto.randomUUID)()}`;
   return {
     scopeVersion: 1,
+    durability: "process-local",
     get registryId() {
       return registryId;
     },
@@ -232,7 +233,7 @@ async function ensureWorkerSettlementIsSafe(registry, ref) {
   if (record == null) return { outcome: "not_found_in_scope" };
   if (record.hasWebhook) {
     throw new Error(
-      "Direct scoped worker settlement is unavailable for tasks with push notifications because registry-only writes cannot durably deliver the terminal webhook. Return the result through the live handoff instead."
+      "Registry-only scoped settlement is unavailable for tasks with push notifications. Use createPostgresTaskSettlementCoordinator() with completeScopedPushTask()/failScopedPushTask() for crash-safe PostgreSQL settlement."
     );
   }
   return void 0;

package/dist/lib/server/decisioning/runtime/task-registry.mjs

@@ -77,6 +77,7 @@ function createInMemoryTaskRegistry() {
   let registryId = `memory:${randomUUID()}`;
   return {
     scopeVersion: 1,
+    durability: "process-local",
     get registryId() {
       return registryId;
     },
@@ -202,7 +203,7 @@ async function ensureWorkerSettlementIsSafe(registry, ref) {
   if (record == null) return { outcome: "not_found_in_scope" };
   if (record.hasWebhook) {
     throw new Error(
-      "Direct scoped worker settlement is unavailable for tasks with push notifications because registry-only writes cannot durably deliver the terminal webhook. Return the result through the live handoff instead."
+      "Registry-only scoped settlement is unavailable for tasks with push notifications. Use createPostgresTaskSettlementCoordinator() with completeScopedPushTask()/failScopedPushTask() for crash-safe PostgreSQL settlement."
     );
   }
   return void 0;

package/dist/lib/server/decisioning/runtime/to-context.js

@@ -61,6 +61,20 @@ function buildCtxMetadataAccessor(store, accountId) {
     }
   };
 }
+function createContextTaskHandoff(fn, options) {
+  if (options?.task_id !== void 0) {
+    if (typeof options.task_id !== "string" || options.task_id.length === 0) {
+      throw new Error("handoffToTask options.task_id must be a non-empty string");
+    }
+    if (options.task_id.length > 128) {
+      throw new Error("handoffToTask options.task_id must be \u2264 128 characters");
+    }
+  }
+  if (options != null && "settlement" in options && options.settlement !== "external") {
+    throw new Error("handoffToTask options.settlement must be 'external'");
+  }
+  return (0, import_async_outcome._createTaskHandoff)(fn, options);
+}
 function buildRequestContext(handlerCtx, ctxMetadataStore, input) {
   const account = handlerCtx.account;
   const stubResolver = (name) => async () => {
@@ -91,17 +105,7 @@ function buildRequestContext(handlerCtx, ctxMetadataStore, input) {
       creativeFormat: stubResolver("creativeFormat")
     },
     ctxMetadata,
-    handoffToTask(fn, options) {
-      if (options?.task_id !== void 0) {
-        if (typeof options.task_id !== "string" || options.task_id.length === 0) {
-          throw new Error("handoffToTask options.task_id must be a non-empty string");
-        }
-        if (options.task_id.length > 128) {
-          throw new Error("handoffToTask options.task_id must be \u2264 128 characters");
-        }
-      }
-      return (0, import_async_outcome._createTaskHandoff)(fn, options);
-    }
+    handoffToTask: createContextTaskHandoff
   };
 }
 function buildHandoffContext(taskRegistry, taskRef) {

package/dist/lib/server/decisioning/runtime/to-context.mjs

@@ -39,6 +39,20 @@ function buildCtxMetadataAccessor(store, accountId) {
     }
   };
 }
+function createContextTaskHandoff(fn, options) {
+  if (options?.task_id !== void 0) {
+    if (typeof options.task_id !== "string" || options.task_id.length === 0) {
+      throw new Error("handoffToTask options.task_id must be a non-empty string");
+    }
+    if (options.task_id.length > 128) {
+      throw new Error("handoffToTask options.task_id must be \u2264 128 characters");
+    }
+  }
+  if (options != null && "settlement" in options && options.settlement !== "external") {
+    throw new Error("handoffToTask options.settlement must be 'external'");
+  }
+  return _createTaskHandoff(fn, options);
+}
 function buildRequestContext(handlerCtx, ctxMetadataStore, input) {
   const account = handlerCtx.account;
   const stubResolver = (name) => async () => {
@@ -69,17 +83,7 @@ function buildRequestContext(handlerCtx, ctxMetadataStore, input) {
       creativeFormat: stubResolver("creativeFormat")
     },
     ctxMetadata,
-    handoffToTask(fn, options) {
-      if (options?.task_id !== void 0) {
-        if (typeof options.task_id !== "string" || options.task_id.length === 0) {
-          throw new Error("handoffToTask options.task_id must be a non-empty string");
-        }
-        if (options.task_id.length > 128) {
-          throw new Error("handoffToTask options.task_id must be \u2264 128 characters");
-        }
-      }
-      return _createTaskHandoff(fn, options);
-    }
+    handoffToTask: createContextTaskHandoff
   };
 }
 function buildHandoffContext(taskRegistry, taskRef) {

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

@@ -65,8 +65,8 @@ export type { IdempotencyStore, IdempotencyStoreConfig, IdempotencyBackend, Idem
 export { createA2AAdapter, A2AInvocationError } from './a2a-adapter.mjs';
 export type { A2AAdapter, A2AAdapterOptions, A2AAgentCardOverrides, A2AAgentCapabilitiesOverride, A2AAgentSkillOverride, A2AMountOptions, ExpressAppLike, LegacyHttpSecurityScheme, LegacySecurityScheme, } from './a2a-adapter.mjs';
 export { createWebhookEmitter, memoryWebhookDeliveryStore, memoryWebhookKeyStore } from './webhook-emitter.mjs';
-export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend, getWebhookDeliveryMigration, getWebhookDeliveryRecoveryMigration, WEBHOOK_DELIVERY_MIGRATION, WEBHOOK_DELIVERY_RECOVERY_MIGRATION, createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError, } from './webhook-delivery/index.mjs';
-export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions, RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions, ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './webhook-delivery/index.mjs';
+export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend, getWebhookDeliveryMigration, getWebhookDeliveryRecoveryMigration, WEBHOOK_DELIVERY_MIGRATION, WEBHOOK_DELIVERY_RECOVERY_MIGRATION, createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookAuthenticationProtectionError, WebhookAuthenticationResolutionError, WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError, } from './webhook-delivery/index.mjs';
+export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions, RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions, ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, PreparedWebhookDeliverySnapshot, PrepareWebhookDeliveryOptions, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './webhook-delivery/index.mjs';
 export type { WebhookEmitter, RecoverableWebhookEmitter, WebhookEmitterOptions, WebhookEmitParams, WebhookEmitResult, WebhookRecoveredDelivery, WebhookEmitAttempt, WebhookEmitAttemptResult, WebhookDeliveryBinding, WebhookDeliveryRetired, WebhookDeliveryRecord, WebhookDeliveryKey, WebhookDeliveryProposal, WebhookDeliverySnapshot, WebhookDeliveryRecovery, WebhookDeliveryRecoveryClaim, WebhookDeliveryStore, WebhookIdempotencyKeyStore, WebhookRetryOptions, WebhookAuthentication, } from './webhook-emitter.mjs';
 export type { SigningProvider } from '../signing/provider.mjs';
 export { createPinAndBindFetch, WEBHOOK_SSRF_POLICY, LOOPBACK_OK_WEBHOOK_SSRF_POLICY } from './pin-and-bind-fetch.mjs';

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

@@ -65,8 +65,8 @@ export type { IdempotencyStore, IdempotencyStoreConfig, IdempotencyBackend, Idem
 export { createA2AAdapter, A2AInvocationError } from './a2a-adapter';
 export type { A2AAdapter, A2AAdapterOptions, A2AAgentCardOverrides, A2AAgentCapabilitiesOverride, A2AAgentSkillOverride, A2AMountOptions, ExpressAppLike, LegacyHttpSecurityScheme, LegacySecurityScheme, } from './a2a-adapter';
 export { createWebhookEmitter, memoryWebhookDeliveryStore, memoryWebhookKeyStore } from './webhook-emitter';
-export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend, getWebhookDeliveryMigration, getWebhookDeliveryRecoveryMigration, WEBHOOK_DELIVERY_MIGRATION, WEBHOOK_DELIVERY_RECOVERY_MIGRATION, createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError, } from './webhook-delivery';
-export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions, RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions, ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './webhook-delivery';
+export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend, getWebhookDeliveryMigration, getWebhookDeliveryRecoveryMigration, WEBHOOK_DELIVERY_MIGRATION, WEBHOOK_DELIVERY_RECOVERY_MIGRATION, createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookAuthenticationProtectionError, WebhookAuthenticationResolutionError, WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError, } from './webhook-delivery';
+export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions, RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions, ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, PreparedWebhookDeliverySnapshot, PrepareWebhookDeliveryOptions, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './webhook-delivery';
 export type { WebhookEmitter, RecoverableWebhookEmitter, WebhookEmitterOptions, WebhookEmitParams, WebhookEmitResult, WebhookRecoveredDelivery, WebhookEmitAttempt, WebhookEmitAttemptResult, WebhookDeliveryBinding, WebhookDeliveryRetired, WebhookDeliveryRecord, WebhookDeliveryKey, WebhookDeliveryProposal, WebhookDeliverySnapshot, WebhookDeliveryRecovery, WebhookDeliveryRecoveryClaim, WebhookDeliveryStore, WebhookIdempotencyKeyStore, WebhookRetryOptions, WebhookAuthentication, } from './webhook-emitter';
 export type { SigningProvider } from '../signing/provider';
 export { createPinAndBindFetch, WEBHOOK_SSRF_POLICY, LOOPBACK_OK_WEBHOOK_SSRF_POLICY } from './pin-and-bind-fetch';

package/dist/lib/server/index.js

@@ -77,6 +77,8 @@ __export(server_exports, {
   WEBHOOK_SSRF_POLICY: () => import_pin_and_bind_fetch.WEBHOOK_SSRF_POLICY,
   WIRE_SPEC_FIELDS: () => import_wire_safe.WIRE_SPEC_FIELDS,
   WebSocketTransport: () => import_socket_mode.WebSocketTransport,
+  WebhookAuthenticationProtectionError: () => import_webhook_delivery.WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError: () => import_webhook_delivery.WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError: () => import_webhook_delivery.WebhookDeliveryTerminalError,
   adcpError: () => import_errors.adcpError,
   anyOf: () => import_auth.anyOf,
@@ -373,6 +375,8 @@ var import_socket_mode = require('./socket-mode/index.js');
   WEBHOOK_SSRF_POLICY,
   WIRE_SPEC_FIELDS,
   WebSocketTransport,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   adcpError,
   anyOf,

package/dist/lib/server/index.mjs

@@ -189,6 +189,8 @@ import {
   createWebhookDeliveryRecovery,
   pollWebhookDeliveryRecovery,
   memoryWebhookDeliveryRecoveryBackend,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   isWebhookDeliveryTerminalError
 } from "./webhook-delivery/index.mjs";
@@ -322,6 +324,8 @@ export {
   WEBHOOK_SSRF_POLICY,
   WIRE_SPEC_FIELDS,
   WebSocketTransport,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   adcpError,
   anyOf,

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

@@ -2,6 +2,6 @@ export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, getWebhookDel
 export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions } from './pg.mjs';
 export { redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend } from './redis.mjs';
 export type { RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions } from './redis.mjs';
-export { createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, } from './recovery.mjs';
-export type { ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './recovery.mjs';
+export { createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookAuthenticationProtectionError, WebhookAuthenticationResolutionError, } from './recovery.mjs';
+export type { ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, PreparedWebhookDeliverySnapshot, PrepareWebhookDeliveryOptions, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './recovery.mjs';
 export { WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError } from './common.mjs';

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

@@ -2,6 +2,6 @@ export { pgWebhookDeliveryStore, pgWebhookDeliveryRecoveryBackend, getWebhookDel
 export type { PgWebhookDeliveryStoreOptions, PgWebhookDeliveryRecoveryOptions } from './pg';
 export { redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend } from './redis';
 export type { RedisWebhookDeliveryStoreOptions, RedisWebhookDeliveryRecoveryOptions } from './redis';
-export { createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, } from './recovery';
-export type { ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './recovery';
+export { createWebhookDeliveryRecovery, pollWebhookDeliveryRecovery, memoryWebhookDeliveryRecoveryBackend, WebhookAuthenticationProtectionError, WebhookAuthenticationResolutionError, } from './recovery';
+export type { ProtectedWebhookAuthentication, WebhookAuthenticationAdapter, WebhookAuthenticationContext, StoredWebhookDeliverySnapshot, PreparedWebhookDeliverySnapshot, PrepareWebhookDeliveryOptions, WebhookRecoveryRecord, WebhookRecoveryLease, WebhookRecoveryCheckpointResult, WebhookRecoveryCheckpointOutcome, WebhookDeliveryRecoveryBackend, DurableWebhookDeliveryRecovery, CreateWebhookDeliveryRecoveryOptions, PollWebhookDeliveryRecoveryOptions, } from './recovery';
 export { WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError } from './common';

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

@@ -20,6 +20,8 @@ var webhook_delivery_exports = {};
 __export(webhook_delivery_exports, {
   WEBHOOK_DELIVERY_MIGRATION: () => import_pg.WEBHOOK_DELIVERY_MIGRATION,
   WEBHOOK_DELIVERY_RECOVERY_MIGRATION: () => import_pg.WEBHOOK_DELIVERY_RECOVERY_MIGRATION,
+  WebhookAuthenticationProtectionError: () => import_recovery.WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError: () => import_recovery.WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError: () => import_common.WebhookDeliveryTerminalError,
   createWebhookDeliveryRecovery: () => import_recovery.createWebhookDeliveryRecovery,
   getWebhookDeliveryMigration: () => import_pg.getWebhookDeliveryMigration,
@@ -41,6 +43,8 @@ var import_common = require('./common.js');
 0 && (module.exports = {
   WEBHOOK_DELIVERY_MIGRATION,
   WEBHOOK_DELIVERY_RECOVERY_MIGRATION,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   createWebhookDeliveryRecovery,
   getWebhookDeliveryMigration,

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

@@ -10,12 +10,16 @@ import { redisWebhookDeliveryStore, redisWebhookDeliveryRecoveryBackend } from "
 import {
   createWebhookDeliveryRecovery,
   pollWebhookDeliveryRecovery,
-  memoryWebhookDeliveryRecoveryBackend
+  memoryWebhookDeliveryRecoveryBackend,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError
 } from "./recovery.mjs";
 import { WebhookDeliveryTerminalError, isWebhookDeliveryTerminalError } from "./common.mjs";
 export {
   WEBHOOK_DELIVERY_MIGRATION,
   WEBHOOK_DELIVERY_RECOVERY_MIGRATION,
+  WebhookAuthenticationProtectionError,
+  WebhookAuthenticationResolutionError,
   WebhookDeliveryTerminalError,
   createWebhookDeliveryRecovery,
   getWebhookDeliveryMigration,

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

@@ -1,5 +1,5 @@
 import type { PgQueryable } from '../postgres-task-store.mjs';
-import type { WebhookDeliveryStore } from '../webhook-emitter.mjs';
+import type { WebhookDeliveryKey, WebhookDeliveryStore } from '../webhook-emitter.mjs';
 import type { WebhookDeliveryRecoveryBackend } from './recovery.mjs';
 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;