@tangle-network/agent-gateway 0.7.0 → 0.8.0

package/src/payment-recovery.ts

@@ -0,0 +1,331 @@
+import type { MppChargeOperation } from './mpp-payment'
+import type { PaymentOperation } from './payment-operations'
+import type {
+  PaymentMethod,
+  PaymentSettlementBasis,
+  SandboxExecutionBudget,
+  SandboxUsageReceipt,
+} from './payment-types'
+
+export type { PaymentSettlementBasis } from './payment-types'
+
+export const PAYMENT_RECOVERY_VERSION = 1 as const
+
+export type PaymentRecoveryState =
+  | 'claiming'
+  | 'claimed'
+  | 'executing'
+  | 'retained'
+  | 'settling'
+  | 'releasing'
+  | 'reconciled'
+
+export interface SerializedPaymentOperation {
+  protocolVersion: 2
+  operationId: string
+  acquiredByRequestId: string
+  executionStartedAt?: number
+  retentionReason?: string
+  nonceKey: string
+  authorizationId: string
+  reservedAmount: string
+  settledAmount: string
+  refundAmount: string
+  expiresAt: number
+  state: PaymentOperation['state']
+}
+
+export interface PaymentRecoveryAttribution {
+  requestId: string
+  agentId: string
+  agentSlug: string
+  consumerId: string
+  paymentMethod: PaymentMethod
+  startMs: number
+  pricePerTokenUsd: number
+  platformFeePercent: number
+  requiredAmount: string
+  currencyDecimals: number
+  maxOutputTokens: number
+  executionBudget: SandboxExecutionBudget
+}
+
+export type PaymentRecoveryTarget =
+  | {
+      kind: 'x402'
+      operationId: string
+      operation?: SerializedPaymentOperation
+    }
+  | {
+      kind: 'mpp-charge'
+      method: string
+      operationId: string
+      operation?: MppChargeOperation
+    }
+
+/** Durable outbox row for one payment identity. Rows are never deleted here. */
+export interface PaymentRecoveryRecord {
+  version: typeof PAYMENT_RECOVERY_VERSION
+  id: string
+  revision: number
+  state: PaymentRecoveryState
+  payment: PaymentRecoveryTarget
+  attribution: PaymentRecoveryAttribution
+  workStarted: boolean
+  /** Earliest time a missing receipt may settle at the quoted ceiling. */
+  fallbackAt?: number
+  usage?: SandboxUsageReceipt
+  usageRecorded: boolean
+  settlementBasis?: PaymentSettlementBasis
+  reason?: string
+  attempts: number
+  lastError?: string
+  nextAttemptAt: number
+  lease?: { id: string; expiresAt: number }
+  createdAt: number
+  updatedAt: number
+  reconciledAt?: number
+}
+
+export interface PaymentRecoveryStore {
+  createIfAbsent(record: PaymentRecoveryRecord): Promise<boolean>
+  get(id: string): Promise<PaymentRecoveryRecord | undefined>
+  compareAndSet(
+    expected: PaymentRecoveryRecord,
+    next: PaymentRecoveryRecord,
+  ): Promise<boolean>
+  listDue(now: number, limit: number): Promise<PaymentRecoveryRecord[]>
+}
+
+export interface PaymentRecoveryConfig {
+  store: PaymentRecoveryStore
+  /** Claimed payment with no execution becomes recoverable after this delay. */
+  staleRequestMs?: number
+  /** Work without a final receipt settles at the quoted ceiling after this delay. */
+  receiptTimeoutMs?: number
+  /** Failed provider recovery waits this long before its next attempt. */
+  retryDelayMs?: number
+  /** One recovery worker owns a row for this duration. */
+  leaseMs?: number
+}
+
+export const DEFAULT_STALE_REQUEST_MS = 30_000
+export const DEFAULT_RECEIPT_TIMEOUT_MS = 5 * 60_000
+export const DEFAULT_RECOVERY_RETRY_MS = 30_000
+export const DEFAULT_RECOVERY_LEASE_MS = 30_000
+
+/** Atomic single-process store for tests and explicit local demo mode. */
+export class MemoryPaymentRecoveryStore implements PaymentRecoveryStore {
+  private readonly records = new Map<string, PaymentRecoveryRecord>()
+
+  async createIfAbsent(record: PaymentRecoveryRecord): Promise<boolean> {
+    if (this.records.has(record.id)) return false
+    this.records.set(record.id, clone(record))
+    return true
+  }
+
+  async get(id: string): Promise<PaymentRecoveryRecord | undefined> {
+    const record = this.records.get(id)
+    return record ? clone(record) : undefined
+  }
+
+  async compareAndSet(
+    expected: PaymentRecoveryRecord,
+    next: PaymentRecoveryRecord,
+  ): Promise<boolean> {
+    const current = this.records.get(expected.id)
+    if (!current || current.revision !== expected.revision) return false
+    this.records.set(expected.id, clone(next))
+    return true
+  }
+
+  async listDue(now: number, limit: number): Promise<PaymentRecoveryRecord[]> {
+    return [...this.records.values()]
+      .filter((record) => record.state !== 'reconciled' && record.nextAttemptAt <= now)
+      .sort((left, right) => left.nextAttemptAt - right.nextAttemptAt)
+      .slice(0, limit)
+      .map(clone)
+  }
+}
+
+export class PaymentRecoveryFenceError extends Error {
+  constructor(id: string) {
+    super(`payment recovery fence was lost for ${id}`)
+    this.name = 'PaymentRecoveryFenceError'
+  }
+}
+
+export class PaymentRecoveryReplayError extends Error {
+  constructor(id: string) {
+    super(`payment recovery identity was already reconciled: ${id}`)
+    this.name = 'PaymentRecoveryReplayError'
+  }
+}
+
+/** Update only while the caller still owns the durable row fence. */
+export async function updateOwnedPaymentRecovery(
+  store: PaymentRecoveryStore,
+  id: string,
+  fenceId: string,
+  update: (record: PaymentRecoveryRecord) => PaymentRecoveryRecord,
+  now = Date.now(),
+): Promise<PaymentRecoveryRecord> {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const current = await store.get(id)
+    if (!current) throw new Error(`payment recovery record ${id} was not found`)
+    if (current.state === 'reconciled' || current.lease?.id !== fenceId) {
+      throw new PaymentRecoveryFenceError(id)
+    }
+    const candidate = update(clone(current))
+    assertRecoveryUpdate(current, candidate)
+    const next: PaymentRecoveryRecord = {
+      ...candidate,
+      id: current.id,
+      version: PAYMENT_RECOVERY_VERSION,
+      revision: current.revision + 1,
+      createdAt: current.createdAt,
+      updatedAt: now,
+    }
+    if (await store.compareAndSet(current, next)) return next
+  }
+  throw new Error(`payment recovery record ${id} changed too many times`)
+}
+
+const PAYMENT_RECOVERY_TRANSITIONS: Record<PaymentRecoveryState, ReadonlySet<PaymentRecoveryState>> = {
+  claiming: new Set(['claiming', 'claimed', 'releasing', 'reconciled']),
+  claimed: new Set(['claimed', 'executing', 'releasing', 'reconciled']),
+  executing: new Set(['executing', 'retained', 'settling', 'releasing', 'reconciled']),
+  retained: new Set(['retained', 'settling', 'reconciled']),
+  settling: new Set(['settling', 'reconciled']),
+  releasing: new Set(['releasing', 'reconciled']),
+  reconciled: new Set(['reconciled']),
+}
+
+function assertRecoveryUpdate(
+  current: PaymentRecoveryRecord,
+  candidate: PaymentRecoveryRecord,
+): void {
+  if (!PAYMENT_RECOVERY_TRANSITIONS[current.state].has(candidate.state)) {
+    throw new Error(`invalid payment recovery transition ${current.state} -> ${candidate.state}`)
+  }
+  if (JSON.stringify(current.attribution) !== JSON.stringify(candidate.attribution)) {
+    throw new Error('payment recovery attribution is immutable')
+  }
+  if (
+    current.payment.kind !== candidate.payment.kind ||
+    current.payment.operationId !== candidate.payment.operationId ||
+    (current.payment.kind === 'mpp-charge' &&
+      candidate.payment.kind === 'mpp-charge' &&
+      current.payment.method !== candidate.payment.method)
+  ) {
+    throw new Error('payment recovery identity is immutable')
+  }
+  if (current.workStarted && !candidate.workStarted) {
+    throw new Error('payment recovery cannot forget started work')
+  }
+  if (current.usageRecorded && !candidate.usageRecorded) {
+    throw new Error('payment recovery cannot forget usage attribution')
+  }
+  if (current.usage && (!candidate.usage || !sameRecoveryUsage(current.usage, candidate.usage))) {
+    throw new Error('payment recovery usage receipt is immutable')
+  }
+  if (
+    current.settlementBasis &&
+    current.settlementBasis !== candidate.settlementBasis
+  ) {
+    throw new Error('payment recovery settlement basis is immutable')
+  }
+}
+
+function sameRecoveryUsage(
+  left: SandboxUsageReceipt,
+  right: SandboxUsageReceipt,
+): boolean {
+  return left.inputTokens === right.inputTokens &&
+    left.outputTokens === right.outputTokens &&
+    left.reasoningTokens === right.reasoningTokens &&
+    left.toolTokens === right.toolTokens &&
+    left.toolCallCount === right.toolCallCount &&
+    left.providerCostUsd === right.providerCostUsd &&
+    left.budgetEnforced === right.budgetEnforced
+}
+
+export function serializePaymentOperation(
+  operation: PaymentOperation,
+): SerializedPaymentOperation {
+  return {
+    protocolVersion: 2,
+    operationId: operation.operationId,
+    acquiredByRequestId: operation.acquiredByRequestId,
+    ...(operation.executionStartedAt !== undefined
+      ? { executionStartedAt: operation.executionStartedAt }
+      : {}),
+    ...(operation.retentionReason ? { retentionReason: operation.retentionReason } : {}),
+    nonceKey: operation.nonceKey,
+    authorizationId: operation.authorizationId,
+    reservedAmount: operation.reservedAmount.toString(),
+    settledAmount: operation.settledAmount.toString(),
+    refundAmount: operation.refundAmount.toString(),
+    expiresAt: operation.expiresAt,
+    state: operation.state,
+  }
+}
+
+export function deserializePaymentOperation(
+  value: SerializedPaymentOperation,
+): PaymentOperation {
+  if (value.protocolVersion !== 2) throw new Error('unsupported payment operation version')
+  if (!value.operationId || !value.acquiredByRequestId || !value.nonceKey || !value.authorizationId) {
+    throw new Error('incomplete payment operation recovery record')
+  }
+  return {
+    protocolVersion: 2,
+    operationId: value.operationId,
+    acquiredByRequestId: value.acquiredByRequestId,
+    ...(value.executionStartedAt !== undefined ? { executionStartedAt: value.executionStartedAt } : {}),
+    ...(value.retentionReason ? { retentionReason: value.retentionReason } : {}),
+    nonceKey: value.nonceKey,
+    authorizationId: value.authorizationId,
+    reservedAmount: BigInt(value.reservedAmount),
+    settledAmount: BigInt(value.settledAmount),
+    refundAmount: BigInt(value.refundAmount),
+    expiresAt: value.expiresAt,
+    state: value.state,
+  }
+}
+
+export function recoveryTiming(config: PaymentRecoveryConfig): {
+  staleRequestMs: number
+  receiptTimeoutMs: number
+  retryDelayMs: number
+  leaseMs: number
+} {
+  return {
+    staleRequestMs: config.staleRequestMs ?? DEFAULT_STALE_REQUEST_MS,
+    receiptTimeoutMs: config.receiptTimeoutMs ?? DEFAULT_RECEIPT_TIMEOUT_MS,
+    retryDelayMs: config.retryDelayMs ?? DEFAULT_RECOVERY_RETRY_MS,
+    leaseMs: config.leaseMs ?? DEFAULT_RECOVERY_LEASE_MS,
+  }
+}
+
+export function assertPaymentRecoveryConfig(config: PaymentRecoveryConfig): void {
+  for (const [name, value] of Object.entries(recoveryTiming(config))) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`payment recovery ${name} must be a positive safe integer`)
+    }
+  }
+  const store = config.store
+  if (
+    !store ||
+    typeof store.createIfAbsent !== 'function' ||
+    typeof store.get !== 'function' ||
+    typeof store.compareAndSet !== 'function' ||
+    typeof store.listDue !== 'function'
+  ) {
+    throw new Error('payment recovery store must provide atomic create, compare-and-set, and due scans')
+  }
+}
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}

package/src/payment-types.ts

@@ -0,0 +1,48 @@
+export type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none'
+
+export interface SandboxExecutionBudget {
+  maxInputTokens: number
+  maxOutputTokens: number
+  maxReasoningTokens: number
+  maxToolTokens: number
+  maxToolCalls: number
+  maxProviderCostUsd: number
+}
+
+export interface SandboxUsageReceipt {
+  inputTokens: number
+  outputTokens: number
+  reasoningTokens: number
+  toolTokens: number
+  toolCallCount: number
+  providerCostUsd: number
+  /** True only when the provider/adapter enforced every supplied budget. */
+  budgetEnforced: boolean
+}
+
+export type PaymentSettlementBasis = 'usage-receipt' | 'quoted-ceiling'
+
+export interface GatewayUsageEvent {
+  /** Correlates usage, settlement, and observer records for one request. */
+  requestId: string
+  agentId: string
+  agentSlug: string
+  consumerId: string
+  paymentMethod: PaymentMethod
+  inputTokens: number
+  outputTokens: number
+  /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+  reasoningTokens?: number
+  /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+  toolTokens?: number
+  /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+  toolCallCount?: number
+  /** Optional in 0.7.2 so 0.7.1 event constructors remain source-compatible. */
+  providerCostUsd?: number
+  totalCostUsd: number
+  ownerEarnedUsd: number
+  platformFeeUsd: number
+  durationMs: number
+  /** Exact receipt in normal operation; quoted ceiling only after receipt timeout. */
+  settlementBasis?: PaymentSettlementBasis
+}

package/src/types.ts

@@ -1,3 +1,25 @@
+import type {
+  PaymentAuthorizationContext,
+  PaymentOperation,
+  PaymentOperations,
+} from './payment-operations'
+import type { MppAuthenticatedCredential, MppChargeLifecycle } from './mpp-payment'
+import type { PaymentRecoveryConfig } from './payment-recovery'
+import type { GatewayObserver } from './observer-types'
+import type {
+  GatewayUsageEvent,
+  PaymentMethod,
+  SandboxExecutionBudget,
+  SandboxUsageReceipt,
+} from './payment-types'
+
+export type {
+  GatewayUsageEvent,
+  PaymentMethod,
+  SandboxExecutionBudget,
+  SandboxUsageReceipt,
+} from './payment-types'
+
 // --- Agent resolution ---
 
 export interface AgentMeta {
@@ -71,8 +93,6 @@ export interface AgentMeta {
 
 // --- Payment ---
 
-export type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none'
-
 export interface X402Config {
   /** Ethereum operator address for SpendAuth verification */
   operatorAddress: string
@@ -84,8 +104,35 @@ export interface X402Config {
   rpcUrl?: string
   /** Demo mode: skip signature verification (default: false). NEVER enable in production. */
   demoMode?: boolean
-  /** Production signer verification. Called with the raw SpendAuth payload. Return true if signature is valid. */
-  verifySigner?: (payload: Record<string, unknown>) => Promise<boolean>
+  /** Protocol version for new durable payment operations. Production version 1 is read-only. */
+  paymentProtocolVersion?: 1 | 2
+  /**
+   * Production signature verification. This callback must not reserve, claim,
+   * or mutate payment state.
+   */
+  verifySigner?: (
+    payload: Record<string, unknown>,
+    context?: { protocolVersion: 1 | 2; requestId?: string },
+  ) => Promise<boolean>
+  /**
+   * Claim the verified payment after all request checks pass and immediately
+   * before sandbox work starts. Version 2 returns durable operation ownership.
+   * A boolean return is the version 1 demo-only compatibility path.
+   * Production version 1 must omit this callback because it has no durable
+   * provider operation or recovery identity.
+   */
+  authorizePayment?: (
+    payload: Record<string, unknown>,
+    context: PaymentAuthorizationContext,
+  ) => Promise<boolean | PaymentOperation>
+  /** Version 2 operation store. It owns claim, settle, release, and reclaim. */
+  paymentOperations?: PaymentOperations
+  /**
+   * Number of base-unit decimals used by the payment token. Defaults to 6.
+   * The gateway uses this value to reject a payment that cannot cover the
+   * request's maximum token charge before it calls `verifySigner`.
+   */
+  currencyDecimals?: number
 }
 
 export interface MppConfig {
@@ -93,6 +140,25 @@ export interface MppConfig {
   realm: string
   /** MPP method name (default: "blueprintevm") */
   method?: string
+  /**
+   * Pure credential authentication. Return stable method-owned identity, or null.
+   * This callback must not consume a credential, create a processor object,
+   * reserve funds, confirm payment, or perform any other financial mutation.
+   */
+  authenticateCredential?: (
+    payload: Record<string, unknown>,
+    context: { method: string; credential: string },
+  ) => Promise<MppAuthenticatedCredential | null>
+  /**
+   * @deprecated Use authenticateCredential and return a stable payment identity.
+   * This 0.7.1 callback remains supported through an explicit compatibility adapter.
+   */
+  verifySigner?: (
+    payload: Record<string, unknown>,
+    context: { method: string; credential: string },
+  ) => Promise<string | null>
+  /** Required immediate-charge lifecycle for every non-BlueprinTEVM method. */
+  charge?: MppChargeLifecycle
 }
 
 export interface PaymentResult {
@@ -121,30 +187,6 @@ export interface ApiKeyInfo {
   dailyLimit?: number
 }
 
-// --- Usage tracking ---
-
-export interface GatewayUsageEvent {
-  /**
-   * Per-request id (matches `RequestContext.requestId`). Lets
-   * `recordUsage` correlate the usage row to the same request that
-   * `settlePayment` settles, observability hooks observe, and
-   * `onRequestComplete` reports — without re-deriving from a
-   * synthetic key. Required field as of 0.4.0; the gateway always has
-   * it in scope at the recordUsage call site.
-   */
-  requestId: string
-  agentId: string
-  agentSlug: string
-  consumerId: string
-  paymentMethod: PaymentMethod
-  inputTokens: number
-  outputTokens: number
-  totalCostUsd: number
-  ownerEarnedUsd: number
-  platformFeeUsd: number
-  durationMs: number
-}
-
 // --- Sandbox interface ---
 
 export interface SandboxStreamEvent {
@@ -162,11 +204,25 @@ export interface SandboxStreamEvent {
      * the caller (rendered as the input-required message body).
      */
     inputRequired?: { prompt?: string }
+    /** Provider receipt fields. Version 2 operations require every field. */
+    usage?: Partial<SandboxUsageReceipt>
+    /** Tool or reasoning events may carry hidden usage without visible text. */
+    tool?: { name?: string; inputTokens?: number; outputTokens?: number }
+    reasoning?: { tokens?: number }
   }
 }
 
 export interface SandboxBox {
-  streamPrompt(message: string, opts?: { sessionId?: string; systemPrompt?: string }): AsyncIterable<SandboxStreamEvent>
+  streamPrompt(
+    message: string,
+    opts?: {
+      sessionId?: string
+      systemPrompt?: string
+      maxOutputTokens?: number
+      executionBudget?: SandboxExecutionBudget
+      signal?: AbortSignal
+    },
+  ): AsyncIterable<SandboxStreamEvent>
 }
 
 // --- Gateway config ---
@@ -188,26 +244,39 @@ export interface GatewayConfig {
     consumer: { method: PaymentMethod; consumerId: string; keyId?: string; requestId: string },
   ) => Promise<{ allow: true } | { allow: false; reason: string; code: string }>
 
-  /** Record a usage event after request completes. */
+  /**
+   * Record a usage event after request completes.
+   * The implementation must atomically upsert by requestId and return
+   * success when the row already exists. Recovery may retry after an
+   * acknowledgement is lost, so one request ID must produce one usage row.
+   */
   recordUsage: (event: GatewayUsageEvent) => Promise<void>
 
   /** x402 payment configuration */
   x402: X402Config
 
-  /** MPP (Machine Payments Protocol) configuration. If provided, gateway accepts Authorization: Payment headers. */
+  /** MPP (Machine Payments Protocol) configuration. It is advertised only when a production verifier or explicit demo mode is available. */
   mpp?: MppConfig
 
+  /**
+   * Durable payment recovery outbox. Production payment protocol version 2
+   * and generic MPP charge methods require this configuration.
+   */
+  paymentRecovery?: PaymentRecoveryConfig
+
   /**
    * Verify an API key. Return key info if valid, null if invalid.
-   * Default: accepts any `sk_agent_*` key (demo mode).
+   * In explicit x402 demo mode, the built-in verifier accepts `sk_agent_*` keys.
+   * Production gateways must provide this callback.
    */
   verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>
 
   /**
-   * Settle payment after successful response.
-   * For x402: call ShieldedCredits.claimPayment()
-   * For API key: deduct from spending limit
-   * Default: no-op (demo mode).
+   * Settle a legacy payment after usage attribution is recorded.
+   * Version 2 x402 operations use `x402.paymentOperations` instead.
+   * Production x402 version 1 rejects this callback before nonce claim.
+   * For API keys, deduct from the spending limit.
+   * Default: no-op in explicit demo mode.
    */
   settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>
 
@@ -217,6 +286,29 @@ export interface GatewayConfig {
   /** Max message length in chars (default: 8000) */
   maxMessageLength?: number
 
+  /** Maximum output token request the gateway accepts. Defaults to 4096. */
+  maxOutputTokens?: number
+
+  /** Output token limit used when a request omits `max_tokens`. Defaults to 1024. */
+  defaultOutputTokens?: number
+
+  /**
+   * Return a safe upper bound for the complete provider input.
+   * Include system, chat framing, retained history, tools, harness, and workspace context.
+   */
+  inputTokenBound?: (input: {
+    agent: AgentMeta
+    messages: ChatMessage[]
+  }) => number
+
+  /** Hidden provider spend limits included in the pre-execution payment quote. */
+  executionBudget?: {
+    maxReasoningTokens?: number
+    maxToolTokens?: number
+    maxToolCalls?: number
+    maxProviderCostUsd?: number
+  }
+
   /** Required scope for chat endpoint (default: "chat"). API keys must include this scope. */
   requiredScope?: string
 
@@ -238,19 +330,33 @@ export interface GatewayConfig {
    * and settlement failures. See ./observer.ts for the interface and
    * ConsoleObserver / CompositeObserver implementations.
    */
-  observer?: import('./observer').GatewayObserver
+  observer?: GatewayObserver
 
   /**
-   * A2A protocol configuration. When set, the gateway exposes the A2A
-   * surface alongside its OpenAI-compatible endpoints:
+   * A2A protocol configuration. The gateway exposes A2A with an in-memory
+   * task store by default. Set this object to provide durable storage or push:
    *   GET  /:slug/.well-known/agent.json   — AgentCard discovery
    *   POST /:slug                          — JSON-RPC 2.0 endpoint
    *     methods: message/send, message/stream, tasks/get, tasks/cancel
    * Auth + rate-limit + injection-filter + authorization all share the
    * same pipeline as the OpenAI-compat path. `taskStore` defaults to
    * `InMemoryTaskStore`; swap in D1/postgres/DO for durable deployments.
-   */
+  */
   a2a?: {
+    /**
+     * Authorize reads, cancellation, resubscription, and push configuration
+     * for an existing task. Production control methods fail closed when this
+     * hook is absent; explicit demo mode permits local tests.
+     */
+    authorizeTaskAccess?: (
+      task: import('./a2a/types').Task,
+      context: {
+        method: string
+        agentSlug: string
+        authorization: string
+        paymentSignature: string
+      },
+    ) => Promise<boolean>
     /**
      * Where tasks live. Defaults to `InMemoryTaskStore`; swap in
      * `SqlTaskStore` (D1, postgres, sqlite, libSQL) for durability across
@@ -269,8 +375,8 @@ export interface GatewayConfig {
      * Shared HMAC secret used to sign webhook deliveries (`X-A2A-Signature:
      * sha256=<hex>`). The consumer's webhook verifies the body against this
      * secret to confirm the call originated from this gateway. Required when
-     * `pushStore` is set; without it, deliveries fire unsigned and a
-     * malicious party that knows the webhook URL can forge deliveries.
+     * `pushStore` is set in production. Explicit demo mode may omit it for
+     * local tests; production deliveries never run unsigned.
      */
     webhookSecret?: string
     /**
@@ -278,6 +384,11 @@ export interface GatewayConfig {
      * `fetch`. Override for tests or to wire a queue-backed sender.
      */
     pushFetcher?: typeof fetch
+    /**
+     * DNS-aware policy for push destinations. Required when production
+     * push delivery is enabled so private DNS names cannot receive task data.
+     */
+    pushUrlValidator?: (url: URL) => boolean | Promise<boolean>
   }
 }