@astrasyncai/verification-gateway 5.18.1 → 5.20.0

package/dist/index.d.mts

@@ -243,6 +243,17 @@ interface GatewayConfig {
     debug?: boolean;
     /** Custom headers to send with verification requests */
     customHeaders?: Record<string, string>;
+    /**
+     * 5.20.0: proof that this caller may act as the agent, sent as
+     * `actingProof` in the verify-access body. Honoured only from a
+     * first-party AstraSync service caller (the bridge): the backend checks the
+     * connector's OAuth access token and records a `connector_owner` proof when
+     * its owner owns the agent. Ignored for any other key. A verify carrying it
+     * is never served from, or written to, the verdict cache.
+     */
+    actingProof?: {
+        connectorToken: string;
+    };
     /** This counterparty's URL (sent with verify-access requests for analytics) */
     counterpartyUrl?: string;
     /** This counterparty's type (sent with verify-access requests for analytics) */
@@ -351,9 +362,15 @@ interface VerifiedAgent {
     astraId: string;
     /** Agent display name */
     name: string;
-    /** Composite trust score (0-100) */
+    /**
+     * Composite trust score (0-100). 5.19.0: verify-access returns it to an
+     * authenticated counterparty (your API key) — counterparties may see an
+     * agent's score; the agent itself never does, so never relay it to the
+     * agent. It is withheld (undefined at runtime) for a keyless caller and when
+     * the caller is the agent itself; a route `minTrustScore` then fails closed.
+     */
     trustScore: number;
-    /** Trust level tier */
+    /** Trust level tier (derived from `trustScore`) */
     trustLevel: TrustLevel;
     /** Whether the agent's identity record is anchored on-chain (5.9.0: was `blockchainVerified`) */
     blockchainAnchored: boolean;
@@ -543,7 +560,9 @@ interface StepUpApprovalInfo {
  * Lifecycle states of a step-up approval row (mirrors the backend's
  * step_up_approval_status_check constraint).
  */
-type StepUpApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'consumed';
+type StepUpApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'consumed'
+/** 5.20.0: approved but never redeemed inside the redemption window. */
+ | 'lapsed';
 /**
  * Terminal outcome of a hold-and-poll wait: any non-pending status, or
  * 'timeout' when the hold budget ran out while the approval was still pending.
@@ -605,6 +624,20 @@ interface SettlementArtifact {
  *   - `counterparty.<allowlist|trust>`
  *   - `attestation.<type>` (e.g. `attestation.verified_human_party`)
  *   - `endpoint.<deactivated|trust|policy>`
+ *   - `behaviour.<limit_probing|unattributed_limit_check>` (5.19.0) — the
+ *     call is part of a sweep of unfinished attempts at rising values (quotes,
+ *     held/denied confirms, orders that never settled) that maps the agent's
+ *     spending limit. Completed purchases never count.
+ *     - `behaviour.limit_probing`: the sweep is provably the agent's own
+ *       (signed agent request, first-party bridge hop, runtime challenge or
+ *       the agent's key). Denied with no new step-up approval; the agent's
+ *       trust drops and its owner is alerted.
+ *     - `behaviour.unattributed_limit_check`: the sweep can't be attributed
+ *       to the agent (unsigned or direct merchant calls). Denied — it "needs
+ *       a signed agent request" — with no agent trust penalty; owners are
+ *       alerted with the evidence. A repeat of the merchant's own direct
+ *       calls, or the same pattern across agents of two or more owners,
+ *       reduces the endpoint owner's trust score.
  */
 interface AccessFailure {
     dimension: string;
@@ -721,6 +754,12 @@ interface VerificationResult {
      * (steer the user to add one via onboarding).
      */
     settlementOutcome?: SettlementOutcomeInfo;
+    /**
+     * 5.20.0 (round 29.1): non-fatal integration warnings for the caller —
+     * e.g. `events_url_missing` when a kit's held confirm is on an endpoint with
+     * no Events URL (the kit would never hear the owner's decision).
+     */
+    warnings?: VerificationWarning[];
     /**
      * Card settlement token. Present on a card purchase at a first-party
      * storefront (our Stripe tenant) — 5.14.1: always, there is no charge-here
@@ -884,6 +923,46 @@ interface CallerMetadata {
      */
     observedMetadata?: ObservedMetadata;
 }
+/**
+ * 5.19.0 — the inbound agent request behind a kit confirm, forwarded so
+ * verify-access can tell whether the confirm is provably the agent's own
+ * (limit-probing attribution). The kits build it from `handle(req)`.
+ *
+ * - Signed (UCP, RFC 9421): the covered headers (`signature`,
+ *   `signature-input`, `signature-agent`, `ucp-agent`, `content-digest` and
+ *   every other header the signature covers — never `authorization` or
+ *   `cookie`), the method, the PUBLIC request URL (your `publicOrigin` + the
+ *   path and query, so `@target-uri` / `@authority` match what the agent
+ *   signed behind a TLS-terminating proxy) and `contentDigest`, the
+ *   `sha-256=:<base64>:` digest of the exact raw body.
+ * - `{ unsigned: true }`: the inbound request carried no signature, or it
+ *   came over ACP (the ACP `Authorization` bearer is the platform's
+ *   credential to you and is never forwarded, so ACP confirms are
+ *   unattributable). Sent explicitly so the platform can tell a kit relay
+ *   from a direct merchant call.
+ */
+type AgentArtifacts = {
+    unsigned: true;
+    protocol?: 'ucp' | 'acp';
+} | {
+    unsigned?: false;
+    protocol: 'ucp' | 'acp';
+    method: string;
+    /** Absolute public URL of the inbound request. */
+    url: string;
+    /** Lower-cased covered headers. */
+    headers: Record<string, string>;
+    /** `sha-256=:<base64>:` over the raw request body (absent for an empty body). */
+    contentDigest?: string;
+};
+/** 5.19.0 — kit context on a confirm (carried onto the approval and its events). */
+interface CheckoutMetadata {
+    /** The kit's own checkout session id (`chk_…` / `cs_…`). */
+    kitSessionId?: string;
+    protocol?: 'ucp' | 'acp';
+}
+/** 5.19.0 — see {@link VerificationRequest.purposeSource}. */
+type PurposeSource = 'route_config' | 'header' | 'body' | 'default';
 interface VerificationRequest {
     /** Agent credentials */
     credentials: AgentCredentials;
@@ -1015,6 +1094,25 @@ interface VerificationRequest {
      * from the verify cache key.
      */
     attemptId?: string;
+    /**
+     * 5.19.0 — where `purpose` came from: `'route_config'` (a dashboard route
+     * rule matched this request), `'header'` (the agent's X-Astra-Purpose /
+     * legacy header / query), `'body'` (request-derived by your own
+     * extractor), or `'default'` (derived from the action or the transport
+     * default). Set by the express and Next.js adapters. verify-access keeps a
+     * `'route_config'` purpose over a commerce-derived one (e.g. an MPP paid
+     * leg) only when a stored rule on the endpoint matches `requestMethod` +
+     * `requestPath` with the same purpose and action.
+     */
+    purposeSource?: PurposeSource;
+    /** 5.19.0 — the inbound agent request behind a kit confirm (see {@link AgentArtifacts}). */
+    agentArtifacts?: AgentArtifacts;
+    /** 5.19.0 — kit session id + protocol, stored on any approval this confirm creates. */
+    metadata?: CheckoutMetadata;
+    /** 5.19.0 — the inbound request's HTTP method (for the route-rule check above). */
+    requestMethod?: string;
+    /** 5.19.0 — the inbound request's path, without the query (for the route-rule check above). */
+    requestPath?: string;
     /**
      * 3.12.0 — first-party observational data: the
      * offers the agent evaluated at this checkpoint (catalog browse / intent
@@ -1321,17 +1419,16 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
     /**
      * Posture when the middleware itself throws an internal error (header
      * parsing failure, `fetchRoutes` network error, malformed proxy state,
-     * etc.). Default `'open'` for backward compatibility in SDK 2.4.13 —
-     * legitimate traffic continues to pass through during platform outages.
+     * etc.).
      *
-     * In shadow mode (default), the middleware ALWAYS logs a
-     * `[SHADOW] would-have-denied` line on throws including correlationId so
-     * merchants can grep their own logs for impact analysis. The default
-     * flips to `'closed'` in a follow-up release once the shadow logs confirm
-     * legitimate traffic is unaffected.
+     * 5.19.0 (behaviour change): default `'closed'` — the request is refused
+     * with 503 + Retry-After + `VERIFICATION_UNAVAILABLE` (the
+     * `middleware.internal_error` dimension; never an identity-shaped 401) and
+     * your handler is not called. Set `'open'` explicitly to pass the request
+     * through unverified instead (e.g. small-value demo merchants).
      *
-     * Small-value demo merchants can keep `'open'` indefinitely after the
-     * default flip by setting this explicitly.
+     * The middleware always logs a `[SHADOW] would-have-denied` line on throws
+     * including correlationId, whichever posture is set.
      */
     failOnError?: 'open' | 'closed';
     /**
@@ -1580,6 +1677,11 @@ interface AstraSyncAepEvidence {
         platform_countersignature: string;
     }>;
 }
+/** 5.20.0: a non-fatal warning on a verify-access result (see `warnings`). */
+interface VerificationWarning {
+    code: string;
+    message: string;
+}
 
 /**
  * AstraSync Universal Verification Gateway — Trust Level helpers.
@@ -1611,7 +1713,8 @@ declare function getTrustLevel(score: number): TrustLevel;
  */
 
 /**
- * Clear the verification cache
+ * Clear the verification cache, and (5.20.0) forget in-flight single-flight
+ * calls so a later identical request reaches the backend on its own.
  */
 declare function clearCache(): void;
 /**
@@ -1639,6 +1742,24 @@ interface VerifyOptions {
  * Main verification function
  */
 declare function verify(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Whether `result` was served from the verdict cache or shared from a
+ * concurrent identical call (5.20.0). The adapters skip the decision POST for
+ * these: the session already has its decision from the call that created it.
+ */
+declare function isSharedVerdict(result: VerificationResult): boolean;
+type VerificationListener = (result: VerificationResult, request: VerificationRequest) => void;
+/**
+ * 5.20.0: observe every verdict this process fetched from verify-access
+ * (cache hits and single-flight followers are not repeated). Listeners run
+ * synchronously after the result is built and must not throw (a throw is
+ * swallowed). Returns an unsubscribe function.
+ *
+ * The MCP bridge uses it to size its per-agent rate limit from the trust
+ * score its tools' own verifies return, instead of paying for a second
+ * verify-access call in the gate.
+ */
+declare function onVerificationResult(listener: VerificationListener): () => void;
 /**
  * Report post-hoc consideration/outcome data for an attempt chain (Trust
  * Record). Use when the signal never reached verify-access: a
@@ -1665,15 +1786,42 @@ interface ReportAttemptOptions {
         retried: boolean;
     }) => void;
 }
-declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): Promise<RouteAccessConfigShape[] | null>;
+declare function fetchRoutes(config: GatewayConfig, counterpartyId: string, options?: {
+    /**
+     * 5.19.0: tool names the MCP middleware gates in code, sent as
+     * `?codeGates=a,b` so the dashboard can mark them "gated in code — a rule
+     * here can only add checks".
+     */
+    codeGates?: string[];
+    /**
+     * 5.20.0: called with the endpoint's `counterpartyType` when the routes
+     * response carries it (backend round 29.1+). The MCP middleware uses it
+     * to warn when it is pointed at a non-`mcp_server` endpoint.
+     */
+    onEndpointType?: (counterpartyType: string) => void;
+}): Promise<RouteAccessConfigShape[] | null>;
 /**
  * Minimal shape of an EndpointRoute as the SDK consumes it. Mirrors the
  * server's `EndpointRoute` type and the SDK's `RouteAccessConfig` — same
  * JSON moves between server and SDK unchanged.
  */
 interface RouteAccessConfigShape {
+    /** Path pattern (path rules). Absent on an MCP tool rule. */
     pattern: string;
     method: string;
+    /**
+     * 5.19.0: MCP tool rule — the `tools/call` tool name this rule governs
+     * (`mcp_server` endpoints store only tool rules: `{tool, purpose, action,
+     * resource?, observe?}`). Path-rule matchers skip rules carrying it.
+     */
+    tool?: string;
+    /** 5.19.0: a tool rule's resource override. */
+    resource?: string;
+    /**
+     * 5.19.0: a path rule stored on an `mcp_server` endpoint before tool rules
+     * existed. The MCP middleware ignores it (replace it with tool rules).
+     */
+    legacy?: boolean;
     /** Pass through unenforced (observe). Replaces `minAccessLevel: 'none'`. */
     observe?: boolean;
     minTrustScore?: number;
@@ -1929,6 +2077,14 @@ declare global {
     namespace Express {
         interface Request {
             agentVerification?: VerificationResult;
+            /**
+             * 5.19.0 (documented): the exact request bytes, when your JSON parser
+             * keeps them — `express.json({ verify: (req, _res, buf) => { req.rawBody = buf } })`.
+             * The gateway forwards these (not a re-serialised `req.body`) as the
+             * protocol artifacts' raw body, so body digests (MPP, RFC 9421
+             * content-digest) match without mounting `express.raw`.
+             */
+            rawBody?: Buffer | string;
         }
     }
 }
@@ -2036,6 +2192,37 @@ declare class VerificationGatewayClient {
         subAgentDepth?: number;
         counterpartyUrl?: string;
         counterpartyType?: string;
+        /**
+         * 5.19.0: `'quote'` marks a price / limit check (peek only: no order, no
+         * approval redeemed) — prefer `quoteCheckout()`. Omitted with a
+         * `transactionValue`, the call is a PURCHASE leg (see the warning below).
+         */
+        commercePhase?: 'quote';
+    }): Promise<VerificationResult>;
+    /**
+     * 5.19.0: the QUOTE leg of a checkout — a price / limit check before the
+     * purchase. Sends `commercePhase: 'quote'`: verify-access evaluates the
+     * agent's policy at this value and tells you whether a purchase would be
+     * granted, held for the owner's approval, or denied, but records no order,
+     * moves no money and never redeems an approval. Always reaches the backend
+     * (no verdict cache).
+     *
+     * Quotes count toward limit-probing detection: a run of rising quotes is
+     * how an agent (or a merchant) maps a spending limit. Quote what the buyer
+     * asked for, not a ladder of values.
+     */
+    quoteCheckout(options: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+        purpose?: string;
+        action?: string;
+        transactionValue?: number;
+        currency?: string;
+        checkoutSessionId?: string;
+        attemptId?: string;
+        counterpartyUrl?: string;
+        counterpartyType?: string;
     }): Promise<VerificationResult>;
     /**
      * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
@@ -2075,6 +2262,14 @@ declare class VerificationGatewayClient {
      * is matched to — and only to — this confirm. A held cart's approval is
      * bound to its checkout session and exact value; a confirm for any other
      * cart is held for its own approval.
+     *
+     * 5.19.0 checkout kits: pass the kit's `agentArtifacts` (the inbound agent
+     * request — signed RFC 9421 headers with the public URL and raw-body
+     * digest, or `{ unsigned: true }`) and `metadata` (`{ kitSessionId,
+     * protocol }`) from the `verifyPurchase` context. The platform attributes
+     * the confirm to the agent from the artifacts, and stores the metadata on
+     * any approval this confirm creates so the approval event
+     * (`handleApprovalEvents`) can find the kit session.
      */
     confirmCheckout(options: {
         astraId?: string;
@@ -2093,6 +2288,10 @@ declare class VerificationGatewayClient {
         /** 5.6.0: alternate receipt/delivery email (transit-only) — omit to let
          * the platform default `fulfilment.email` to the buyer's account email. */
         buyerEmail?: string;
+        /** 5.19.0: the inbound agent request behind this confirm (from the kit's verifyPurchase ctx). */
+        agentArtifacts?: AgentArtifacts;
+        /** 5.19.0: `{ kitSessionId, protocol }` (from the kit's verifyPurchase ctx). */
+        metadata?: CheckoutMetadata;
         counterpartyUrl?: string;
         counterpartyType?: string;
     }): Promise<VerificationResult>;
@@ -2124,6 +2323,40 @@ declare class VerificationGatewayClient {
         status: string;
         alreadySettled?: boolean;
     }>;
+    /**
+     * 5.20.0 (round 29.1): change an endpoint's OPERATIONAL URLs with this
+     * client's API key — `PATCH /api/endpoints/:id`. Accepts the key of the
+     * endpoint's owner, or a personal key of an individual with an active seat
+     * in the owning organisation. Policy (rules, trust floor, challenge, edge
+     * config) stays dashboard-only. `null` clears a field. The owner is alerted
+     * when `eventsUrl` changes.
+     *
+     * @param endpointId the ASTRAE id (defaults to the client's `counterpartyId`)
+     * @returns the endpoint as stored, plus `changed` (the fields that changed)
+     * @throws AstraSyncError — 400 `UNKNOWN_FIELDS` / validation, 401/403, 404
+     */
+    updateEndpoint(endpointId: string | undefined, patch: EndpointOperationalPatch): Promise<Record<string, unknown> & {
+        changed: Array<keyof EndpointOperationalPatch>;
+    }>;
+    /**
+     * 5.20.0 (round 29.1): ask AstraSync to send ONE signed step-up event to the
+     * endpoint's Events URL now — `POST /api/endpoints/:id/events/test`.
+     * Delivered synchronously, outside the event outbox (random `eventId`, no
+     * retries), signed with the endpoint's webhook secret like a real event.
+     * Without `approvalId` the payload is synthetic (a kit acknowledges and
+     * ignores it). With the id of a held kit approval at this endpoint the
+     * payload is the real one, so your resume path runs: `approved` makes the
+     * kit re-confirm (held again — nothing is charged); `denied` / `expired` /
+     * `lapsed` release the session.
+     *
+     * Resolves even when your endpoint refused the event (`delivered: false`,
+     * with `responseCode` / `error`).
+     */
+    sendTestEvent(endpointId: string | undefined, options: {
+        type: TestEventType;
+        approvalId?: string;
+    }): Promise<TestEventResult>;
+    private endpointCall;
     /**
      * Quick verification — checks credentials and policy in one call.
      *
@@ -2163,6 +2396,28 @@ declare class VerificationGatewayClient {
      */
     private executeWithRetry;
 }
+/** 5.20.0: the operational fields `updateEndpoint` may change (`null` clears). */
+interface EndpointOperationalPatch {
+    eventsUrl?: string | null;
+    healthCheckUrl?: string | null;
+    skillUrl?: string | null;
+    catalogUrl?: string | null;
+    checkoutUrl?: string | null;
+}
+/** 5.20.0: the step-up event types `sendTestEvent` can send. */
+type TestEventType = 'step_up.approved' | 'step_up.denied' | 'step_up.expired' | 'step_up.lapsed';
+/** 5.20.0: what `sendTestEvent` reports. */
+interface TestEventResult {
+    delivered: boolean;
+    /** delivered | failed (bad answer / unreachable) | not_configured (no Events URL or secret). */
+    status: 'delivered' | 'failed' | 'not_configured';
+    /** Your endpoint's HTTP status, or null when nothing answered. */
+    responseCode: number | null;
+    error: string | null;
+    eventId: string;
+    type: TestEventType;
+    approvalId: string | null;
+}
 /**
  * Create a new SDK client
  */
@@ -2178,13 +2433,16 @@ declare function verifyOnce(options: SDKOptions & {
     action?: string;
 }): Promise<VerificationResult>;
 
+type sdk_EndpointOperationalPatch = EndpointOperationalPatch;
+type sdk_TestEventResult = TestEventResult;
+type sdk_TestEventType = TestEventType;
 type sdk_VerificationGatewayClient = VerificationGatewayClient;
 declare const sdk_VerificationGatewayClient: typeof VerificationGatewayClient;
 declare const sdk_createClient: typeof createClient;
 declare const sdk_getTrustLevel: typeof getTrustLevel;
 declare const sdk_verifyOnce: typeof verifyOnce;
 declare namespace sdk {
-  export { sdk_VerificationGatewayClient as VerificationGatewayClient, sdk_createClient as createClient, sdk_getTrustLevel as getTrustLevel, sdk_verifyOnce as verifyOnce };
+  export { type sdk_EndpointOperationalPatch as EndpointOperationalPatch, type sdk_TestEventResult as TestEventResult, type sdk_TestEventType as TestEventType, sdk_VerificationGatewayClient as VerificationGatewayClient, sdk_createClient as createClient, sdk_getTrustLevel as getTrustLevel, sdk_verifyOnce as verifyOnce };
 }
 
 /**
@@ -3954,19 +4212,71 @@ interface McpMiddlewareOptions extends GatewayConfig {
     recordDecisions?: boolean;
     /** Forward runtime challenge (default `true`). */
     enableRuntimeChallenge?: boolean;
+    /**
+     * 5.19.0: how a dashboard tool rule combines with a code `toolGates`
+     * entry for the same tool. With `apiKey` + `counterpartyId` set, the
+     * middleware fetches the endpoint's tool rules (`{tool, purpose, action,
+     * resource?, observe?}`, edited in the AstraSync dashboard; refreshed every
+     * `routesRefreshMs`) and turns each into a gate for that tool.
+     *
+     * - `'code'` (default): a dashboard rule can TIGHTEN a code gate but never
+     *   loosen it. For a tool gated in code (object form), a dashboard
+     *   `observe` rule, or one with no purpose, is ignored; a dashboard rule
+     *   whose purpose or action differs is evaluated IN ADDITION — both must
+     *   pass. Tools with no code gate (or a code `'observe'`) follow the
+     *   dashboard rule.
+     * - `'dashboard'`: the dashboard rule wins outright for every tool it
+     *   names (including `observe`).
+     *
+     * Rules flagged `legacy: true` (path rules stored on an MCP endpoint before
+     * tool rules existed) are ignored. The middleware sends its code-gated tool
+     * names on the policy fetch (`?codeGates=`) so the dashboard can mark them.
+     */
+    toolGatePrecedence?: 'code' | 'dashboard';
+    /** 5.19.0: refresh interval (ms) for the dashboard tool rules. Default 5 minutes. */
+    routesRefreshMs?: number;
+    /**
+     * 5.20.0: tools and JSON-RPC methods that pass through with NO verify-access
+     * call at all — not even the audit evaluation `evaluateAlwaysIfCredentialed`
+     * adds for credentialed callers. Applies only while the call is not
+     * enforced (an `'observe'` gate, or a handshake/introspection method with
+     * no `methodGates` entry); a dashboard rule that enforces a listed tool
+     * still verifies.
+     *
+     * Use it for:
+     *   - `methods`: handshake and introspection (`initialize`, `tools/list`,
+     *     `resources/list`, `resources/read`) — nothing to attribute, and a
+     *     backend round trip slows the host's first card fetch;
+     *   - `tools`: observe tools whose handler calls verify-access itself, so
+     *     the gate's evaluation would be a second backend verify for the same
+     *     call (the MCP bridge measured ~3 backend calls per `verify_agent`).
+     *
+     * Listed calls leave `req.agentVerification` unset.
+     */
+    skipEvaluation?: {
+        tools?: readonly string[];
+        methods?: readonly string[];
+    };
     /**
      * Posture when the MCP middleware itself throws an internal error.
-     * Default `'open'` for backward compatibility in SDK 2.4.13. Shadow logs
-     * record what WOULD be denied with `failOnError: 'closed'` so merchants
-     * can grep correlationId for impact analysis during the observation
-     * window. Default flips to `'closed'` in a follow-up release.
      *
-     * 5.12.0: `'closed'` answers the retryable verification-unavailable
-     * JSON-RPC error (HTTP 503 + Retry-After, code -32003) — never an
-     * identity-shaped 401.
+     * 5.19.0 (behaviour change): default `'closed'` — an internal throw answers
+     * the retryable verification-unavailable JSON-RPC error (HTTP 503 +
+     * Retry-After, code -32003; never an identity-shaped 401) and the tool
+     * handler is not called. `'open'` (pass the call through unverified) is
+     * an explicit opt-in. The `[SHADOW] would-have-denied` log line is still
+     * written on every throw, with the correlationId.
      */
     failOnError?: 'open' | 'closed';
 }
+/** 5.19.0: a dashboard tool rule as the MCP middleware evaluates it. */
+interface DashboardToolRule {
+    tool: string;
+    purpose?: string;
+    action?: string;
+    resource?: string;
+    observe?: boolean;
+}
 /**
  * Create the MCP middleware. Attach AFTER `express.json()` — the body must
  * already be a parsed object.
@@ -4263,7 +4573,12 @@ interface AgentRecord {
     description?: string;
     agentType: string;
     agentStatus: string;
-    trustScore: number;
+    /**
+     * @deprecated Round 29.1: no longer returned. An agent never sees its own
+     * trust score (the register response omits it; counterparties read it
+     * from verify-access).
+     */
+    trustScore?: number;
     astrasyncIdLevel1?: string | null;
     tempId?: string | null;
     metadata?: Record<string, unknown>;
@@ -4277,7 +4592,11 @@ interface VerifyResponse {
         agentUuid: string;
         agentName: string;
         agentDescription: string;
-        agentTrustScore: number;
+        /**
+         * @deprecated Round 29.1: no longer returned by public verification.
+         * Counterparties read the score from verify-access.
+         */
+        agentTrustScore?: number;
         agentStatus: string;
         ownerName?: string;
     };
@@ -5166,7 +5485,7 @@ declare function detectRuntime(userAgent: string | undefined | null): string | u
  * silently (never throwing), so this is a no-op there — which is correct:
  * in a browser the page's real UA is the honest identity.
  */
-declare const SDK_USER_AGENT = "astrasync-sdk/5.18.1";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.20.0";
 declare const sdkFetch: typeof fetch;
 
 interface LocalPolicy {
@@ -5284,7 +5603,7 @@ declare function parseYaml(yamlContent: string): ParseResult;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.18.1";
+declare const SDK_VERSION = "5.20.0";
 
 /**
  * 5.15.0 — the `UCP-Agent` request header (UCP 2026-08-25): an RFC 8941
@@ -5327,6 +5646,9 @@ declare function checkUcpAgentBinding(header: string | string[] | null | undefin
  * `ucp.payment_handlers` are required even when empty; signing keys are the
  * TOP-LEVEL `keys[]` (a JWK Set). Served over HTTPS, never redirected, with
  * `Cache-Control: public, max-age >= 60`.
+ *
+ * 5.20.0: platforms that publish their keys as `signing_keys` are read too —
+ * use {@link ucpProfileKeys} wherever a profile's signing keys are needed.
  */
 
 declare const UCP_VERSION = "2026-08-25";
@@ -5363,7 +5685,14 @@ interface UcpProfile {
         payment_handlers: Record<string, UcpPaymentHandlerEntry[]>;
     };
     keys?: JWK[];
+    /** 5.20.0: accepted alongside `keys[]` (some platforms publish this name). */
+    signing_keys?: JWK[];
 }
+/**
+ * 5.20.0: a profile's signing keys — `keys[]` plus `signing_keys`, skipping
+ * malformed entries and encryption keys (`use: 'enc'`).
+ */
+declare function ucpProfileKeys(profile: Partial<UcpProfile> | null | undefined): JWK[];
 /** AstraSync payment handler declarations (spec pages hosted on astrasync.ai). */
 declare function astrasyncPaymentHandlers(handlers: string[], specBase?: string): Record<string, UcpPaymentHandlerEntry[]>;
 interface BuildProfileOptions {
@@ -5634,6 +5963,15 @@ declare function finishIdempotent(opts: IdempotencyOptions, decision: Extract<Id
     headers: Record<string, string>;
     body: string;
 }): Promise<void>;
+/**
+ * 5.19.0: release a key without storing the response — for a NON-TERMINAL
+ * outcome (e.g. a checkout held for the owner's approval) that a retry with
+ * the same key must re-run rather than replay. The checkout kits use it for
+ * held responses, so a re-drive after the approval reaches the kit.
+ */
+declare function abandonIdempotent(opts: IdempotencyOptions, decision: Extract<IdempotencyDecision, {
+    kind: 'proceed';
+}>): Promise<void>;
 interface ExpressReq {
     method: string;
     originalUrl?: string;
@@ -5664,12 +6002,76 @@ interface KitRequestContext {
      */
     callerId?: string;
 }
+/**
+ * 5.19.0: a cart-level message from your `validateCart` hook. `type`
+ * defaults to `'error'`; any error keeps the session from being completed
+ * (UCP `incomplete`, ACP `not_ready_for_payment`) and `complete` is refused
+ * before AstraSync is called. `path` points at the offending part of the
+ * cart (e.g. `$.line_items[0].quantity`) — UCP `path`, ACP `param`.
+ */
+interface KitMessage {
+    type?: 'error' | 'warning' | 'info';
+    code: string;
+    content: string;
+    path?: string;
+}
+/** 5.19.0: retry policy for settlement reports (`reportRetry` kit option). */
+interface ReportRetryOptions {
+    /** Total attempts. Default 3. */
+    attempts?: number;
+    /** First backoff in ms, doubled per retry. Default 250. */
+    backoffMs?: number;
+}
+/**
+ * 5.19.0: what an approval-event resume did. `terminal` outcomes are final
+ * for the event (the dispatcher answers 2xx and marks the event seen);
+ * non-terminal ones (`busy`, `still_held`) answer 5xx so the platform
+ * retries.
+ */
+type ResumeOutcome = 'completed' | 'pending' | 'payment_failed' | 'cart_invalid' | 'not_authorized' | 'declined' | 'already_completed' | 'canceled' | 'not_held' | 'stale' | 'not_found' | 'busy' | 'still_held';
+interface ResumeResult<S> {
+    outcome: ResumeOutcome;
+    terminal: boolean;
+    session: S | null;
+}
+/** 5.19.0: the approval event AstraSync POSTs to your endpoint's Events URL. */
+interface ApprovalEvent {
+    /** Stable across retries — dedupe on it. */
+    eventId: string;
+    type: 'step_up.approved' | 'step_up.denied' | 'step_up.expired' | 'step_up.lapsed';
+    approvalId: string;
+    /** The cart id the confirm carried (the platform's, else the kit's session id). */
+    checkoutSessionId: string;
+    /** The kit session id the confirm carried in `metadata`. */
+    kitSessionId?: string;
+    protocol?: 'ucp' | 'acp';
+    counterpartyId: string;
+    agentAstraId: string;
+    transactionValue: number;
+    currency: string;
+    decidedAt: string;
+    /** Approved only: the approval can be redeemed until this instant (ISO). */
+    redeemBy?: string;
+}
+/** A kit the approval-event dispatcher can route to (both checkout kits). */
+interface ApprovalEventKit {
+    readonly protocol: 'ucp' | 'acp';
+    /** Apply one verified event to the kit session it names. */
+    applyApprovalEvent(event: ApprovalEvent): Promise<ResumeResult<unknown>>;
+}
 
 interface CatalogItem {
     id: string;
     title: string;
     /** Minor units. */
     price: number;
+    /**
+     * 5.20.0: product image, an absolute http(s) URL. A relative or invalid value is
+     * dropped when the kit prices the line.
+     */
+    image_url?: string;
+    /** 5.20.0: short product description. */
+    description?: string;
 }
 interface CheckoutLine {
     id: string;
@@ -5682,7 +6084,9 @@ interface CheckoutLine {
 }
 interface CheckoutSession {
     id: string;
-    status: 'incomplete' | 'requires_escalation' | 'ready_for_complete' | 'complete_in_progress' | 'completed' | 'canceled';
+    status: 'incomplete' | 'requires_escalation' | 'ready_for_complete' | 'complete_in_progress' | 'completed' | 'canceled'
+    /** 5.19.0: kit-internal — `resolvePending` is finishing it (rendered as `complete_in_progress`). */
+     | 'finishing';
     currency: string;
     line_items: CheckoutLine[];
     totals: Array<{
@@ -5705,6 +6109,8 @@ interface CheckoutSession {
     /** 5.18.0: a settlement the processor hasn't confirmed yet (see `resolvePending`). */
     _pending?: {
         orderId?: string;
+        /** 5.19.0: the confirm's verification session id (report fallback when there is no orderId). */
+        sessionId?: string;
         report: {
             amountMinor: number;
             currency: string;
@@ -5712,6 +6118,25 @@ interface CheckoutSession {
         /** The verification result, minus merchant-lane secrets. */
         result: VerificationResult;
     };
+    /** 5.19.0: the owner approval a held checkout waits for. */
+    _approvalId?: string;
+    /** 5.19.0: the agent behind the held confirm (re-sent when the hold resumes). */
+    _astraId?: string;
+    /**
+     * 5.19.0: what was held — the priced cart and the non-secret payment input
+     * — so an approved hold settles exactly what the owner approved, without
+     * the agent and without re-pricing.
+     */
+    _held?: {
+        line_items: CheckoutLine[];
+        totals: Array<{
+            type: string;
+            amount: number;
+        }>;
+        instrument?: Record<string, unknown>;
+        pollUrl?: string;
+        expiresAt?: string;
+    };
     /** 5.18.0: the platform's order webhook URL from its profile, when it declared one. */
     _webhookUrl?: string;
     _platformProfile?: string;
@@ -5737,6 +6162,15 @@ interface CheckoutStore {
     claim?(id: string, from: CheckoutSession['status'], to: CheckoutSession['status']): Promise<boolean>;
     /** 5.18.0: the session that produced an order (for `GET /orders/{id}`). */
     findByOrderId?(orderId: string): Promise<CheckoutSession | null>;
+    /**
+     * 5.19.0: the session for an AstraSync cart id — the platform's
+     * `X-Astra-Checkout-Session` value, else the session's own id. Approval
+     * events name the cart this way; without it the kit can only use the
+     * event's `kitSessionId`.
+     */
+    findByCheckoutSessionId?(checkoutSessionId: string): Promise<CheckoutSession | null>;
+    /** 5.19.0: sessions held for an owner approval (`pollHeldSessions` with no ids). */
+    listHeld?(): Promise<CheckoutSession[]>;
 }
 declare class MemoryCheckoutStore implements CheckoutStore {
     private m;
@@ -5745,6 +6179,8 @@ declare class MemoryCheckoutStore implements CheckoutStore {
     put(s: CheckoutSession): Promise<void>;
     claim(id: string, from: CheckoutSession['status'], to: CheckoutSession['status']): Promise<boolean>;
     findByOrderId(orderId: string): Promise<CheckoutSession | null>;
+    findByCheckoutSessionId(checkoutSessionId: string): Promise<CheckoutSession | null>;
+    listHeld(): Promise<CheckoutSession[]>;
 }
 /** 5.18.0: a policy link shown with the checkout (part of the signed body). */
 interface UcpLink {
@@ -5816,8 +6252,20 @@ interface UcpCheckoutKitOptions {
     /** Profile inputs (endpoint, keys, paymentHandlers, ap2Mandates). */
     profile: BuildProfileOptions;
     currency: string;
-    /** Your catalog: the item, or null when unknown. */
-    catalog: (itemId: string) => Promise<CatalogItem | null>;
+    /**
+     * Your catalog: the item, or null when unknown. 5.19.0: also receives the
+     * requested quantity (for simple per-line caps — or use `validateCart`).
+     */
+    catalog: (itemId: string, quantity: number) => Promise<CatalogItem | null>;
+    /**
+     * 5.19.0: cart-level validation (stock, per-line or per-cart caps, …). Runs
+     * on create, update and complete — before the session is claimed and
+     * before `verifyPurchase` — and when an approved hold resumes. Any error
+     * message keeps the session `incomplete` (messages are `recoverable`, with
+     * your `path`, e.g. `$.line_items[0].quantity`) and `complete` is refused
+     * without calling AstraSync.
+     */
+    validateCart?: (session: CheckoutSession) => Promise<KitMessage[]>;
     /** AstraSync verification of the purchase (e.g. `client.confirmCheckout`). */
     verifyPurchase: (ctx: {
         session: CheckoutSession;
@@ -5831,6 +6279,18 @@ interface UcpCheckoutKitOptions {
         attemptId?: string;
         checkoutJwt?: string;
         valueMajor: number;
+        /**
+         * 5.19.0: the inbound agent request (pass to `confirmCheckout`). An
+         * approved hold resuming has none (`undefined`) — no agent request is
+         * involved.
+         */
+        agentArtifacts?: AgentArtifacts;
+        /** 5.19.0: `{ kitSessionId, protocol: 'ucp' }` — pass to `confirmCheckout`. */
+        metadata: CheckoutMetadata;
+        /** 5.19.0: set when an approved hold resumes (`resumeApproved`). */
+        resumed?: {
+            approvalId?: string;
+        };
     }) => Promise<VerificationResult>;
     /** Charge / redeem with YOUR processor using the artifact AstraSync handed you. */
     settle: (ctx: {
@@ -5840,14 +6300,36 @@ interface UcpCheckoutKitOptions {
     }) => Promise<SettleResult>;
     /** Report the outcome to AstraSync (e.g. `client.reportSettlement`). */
     reportSettlement?: (r: Parameters<VerificationGatewayClient['reportSettlement']>[0]) => Promise<unknown>;
-    /** Create your order once paid. */
+    /** Create your order once paid. 5.19.0: `settled` is your processor's settled outcome. */
     fulfil: (ctx: {
         session: CheckoutSession;
         result: VerificationResult;
+        settled: Extract<PendingResolution, {
+            status: 'settled';
+        }>;
     }) => Promise<{
         id: string;
         permalink_url?: string;
     }>;
+    /** 5.19.0: settlement-report retries on network / 429 / 5xx (default 3 attempts, 250 ms backoff). */
+    reportRetry?: ReportRetryOptions;
+    /**
+     * 5.19.0: a settlement report or order webhook that still failed after its
+     * retries (default: `console.error`). The order is yours to reconcile.
+     */
+    onReportError?: (err: unknown, ctx: {
+        sessionId: string;
+        orderId?: string;
+        kind?: 'settlement_report' | 'order_webhook';
+    }) => void;
+    /**
+     * 5.19.0: the public origin agents reach this kit at (e.g.
+     * `https://shop.example` behind a TLS-terminating proxy). Used by
+     * `expressHandler` to rebuild the request URL (signature `@target-uri` /
+     * `@authority`) and for the forwarded agent artifacts. Default: the origin
+     * of `profile.endpoint`.
+     */
+    publicOrigin?: string;
     /** Merchant key for ap2.merchant_authorization (when ap2Mandates). */
     signingKey?: {
         privateKey: KeyLike | KeyObject;
@@ -5926,11 +6408,73 @@ declare function createUcpCheckoutKit(opts: UcpCheckoutKitOptions): {
         status: number;
         attempts: number;
     } | null>;
+    /** 5.19.0 */
+    protocol: "ucp";
+    publicOrigin: string;
+    resumeApproved: (sessionId: string, event?: Pick<ApprovalEvent, "approvalId">) => Promise<ResumeResult<CheckoutSession>>;
+    resumeDeclined: (sessionId: string, reason?: "denied" | "expired" | "lapsed" | (string & {}), event?: Pick<ApprovalEvent, "approvalId">) => Promise<ResumeResult<CheckoutSession>>;
+    applyApprovalEvent: (event: ApprovalEvent) => Promise<ResumeResult<CheckoutSession>>;
+    pollHeldSessions: (o?: {
+        sessionIds?: string[];
+        /** Resolves relative poll URLs (your `apiBaseUrl`). */
+        apiBaseUrl?: string;
+    }) => Promise<Array<{
+        sessionId: string;
+        outcome: ResumeResult<CheckoutSession>["outcome"] | "pending";
+    }>>;
 };
 
 /** RFC 8785-style canonical JSON (sorted keys, no whitespace). */
 declare function canonicalJson(value: unknown): string;
 
+/** Where the dispatcher remembers events it finished (dedupe). */
+interface SeenEvents {
+    has(eventId: string): Promise<boolean>;
+    add(eventId: string): Promise<void>;
+}
+/** Process-local {@link SeenEvents} (single instance / tests). Bounded. */
+declare class MemorySeenEvents implements SeenEvents {
+    private max;
+    private ids;
+    constructor(max?: number);
+    has(eventId: string): Promise<boolean>;
+    add(eventId: string): Promise<void>;
+}
+interface HandleApprovalEventsOptions {
+    /** The kits the events can name (e.g. `[ucpKit, acpKit]`). */
+    kits: ApprovalEventKit[];
+    /**
+     * Dedupe store. An object gets `add(eventId)` at a terminal outcome; a
+     * function is a check only (you record seen ids yourself). Default: a
+     * process-local memory set — use a shared store across instances.
+     */
+    seen?: SeenEvents | ((eventId: string) => Promise<boolean>);
+    /** Signature timestamp tolerance (s). Default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (tests). */
+    nowMs?: number;
+    /** Called for every applied event (logging / metrics). */
+    onEvent?: (event: ApprovalEvent, outcome: ResumeOutcome | 'duplicate' | 'ignored') => void;
+}
+interface ApprovalEventsResponse {
+    /** 2xx: done (don't retry). 401/400: refused. 503: retry later. */
+    status: number;
+    body: {
+        ok: boolean;
+        eventId?: string;
+        outcome?: ResumeOutcome | 'duplicate' | 'ignored';
+        error?: string;
+    };
+}
+/**
+ * 5.19.0: verify and apply one approval event. Approved → the kit's
+ * `resumeApproved` (settle, report, fulfil — no agent call); denied /
+ * expired / lapsed → `resumeDeclined`. Routes by `protocol` and
+ * `kitSessionId`, falling back to each kit's cart-id lookup. Never throws:
+ * answer the returned `status` and `body`.
+ */
+declare function handleApprovalEvents(rawBody: string | Buffer | Uint8Array, headers: Record<string, string | string[] | undefined> | Headers, secret: string | readonly string[], opts: HandleApprovalEventsOptions): Promise<ApprovalEventsResponse>;
+
 /**
  * 5.15.0 — x402 v2 (x402 Foundation, specs/transports-v2/http.md) helpers for
  * a MERCHANT. The merchant's own facilitator verifies and settles; AstraSync
@@ -6306,7 +6850,9 @@ declare function aepPublicKeyDocument(keys: Array<{
 declare const ACP_API_VERSION = "2026-04-17";
 /** 5.18.0: `API-Version` values this kit serves. */
 declare const ACP_SUPPORTED_API_VERSIONS: readonly string[];
-type AcpStatus = 'not_ready_for_payment' | 'ready_for_payment' | 'pending_approval' | 'complete_in_progress' | 'completed' | 'canceled';
+type AcpStatus = 'not_ready_for_payment' | 'ready_for_payment' | 'pending_approval' | 'complete_in_progress' | 'completed' | 'canceled'
+/** 5.19.0: kit-internal — `resolvePending` is finishing it (rendered as `complete_in_progress`). */
+ | 'finishing';
 interface AcpMessage {
     type: 'error' | 'info' | 'warning';
     code?: string;
@@ -6325,6 +6871,10 @@ interface AcpCheckoutSession {
             id: string;
             name: string;
             unit_amount: number;
+            /** 5.20.0: absolute http(s) product image from the catalog. */
+            image_url?: string;
+            /** 5.20.0: product description from the catalog. */
+            description?: string;
         };
         quantity: number;
         name: string;
@@ -6347,12 +6897,29 @@ interface AcpCheckoutSession {
     /** 5.18.0: a settlement the processor hasn't confirmed yet (see `resolvePending`). */
     _pending?: {
         orderId?: string;
+        /** 5.19.0: the confirm's verification session id (report fallback). */
+        sessionId?: string;
         report: {
             amountMinor: number;
             currency: string;
         };
         result: VerificationResult;
     };
+    /** 5.19.0: the owner approval a held session waits for, and the held confirm's agent + chain. */
+    _approvalId?: string;
+    _astraId?: string;
+    _attemptId?: string;
+    /** 5.19.0: the held cart and the NON-SECRET `payment_data` fields (see the UCP `_held`). */
+    _held?: {
+        line_items: AcpCheckoutSession['line_items'];
+        totals: Array<{
+            type: string;
+            amount: number;
+        }>;
+        paymentData?: Record<string, unknown>;
+        pollUrl?: string;
+        expiresAt?: string;
+    };
 }
 /** 5.18.0: the ACP kit's session store (`claim` and the memory default as in the UCP kit). */
 interface AcpCheckoutStore {
@@ -6360,13 +6927,24 @@ interface AcpCheckoutStore {
     put(s: AcpCheckoutSession): Promise<void>;
     /** Atomic compare-and-set of `status` (see the UCP `CheckoutStore.claim`). */
     claim?(id: string, from: AcpStatus, to: AcpStatus): Promise<boolean>;
+    /** 5.19.0: the session for an AstraSync cart id (see the UCP `CheckoutStore`). */
+    findByCheckoutSessionId?(checkoutSessionId: string): Promise<AcpCheckoutSession | null>;
+    /** 5.19.0: sessions held for an owner approval (`pollHeldSessions` with no ids). */
+    listHeld?(): Promise<AcpCheckoutSession[]>;
 }
 type AcpCheckoutStatus = AcpStatus;
 interface AcpCheckoutKitOptions {
     currency: string;
     /** Payment handlers you accept (endpoint paymentHandlers), e.g. ['ai.astrasync.voucher']. */
     paymentHandlers: string[];
-    catalog: (itemId: string) => Promise<CatalogItem | null>;
+    /** Your catalog. 5.19.0: also receives the requested quantity. */
+    catalog: (itemId: string, quantity: number) => Promise<CatalogItem | null>;
+    /**
+     * 5.19.0: cart-level validation (see the UCP kit). Any error keeps the
+     * session `not_ready_for_payment` (messages are `invalid`, with your path
+     * as `param`) and `complete` is refused without calling AstraSync.
+     */
+    validateCart?: (session: AcpCheckoutSession) => Promise<KitMessage[]>;
     verifyPurchase: (ctx: {
         session: AcpCheckoutSession;
         /** Pass as `checkoutSessionId` to AstraSync (the platform's cart id when sent). */
@@ -6374,6 +6952,14 @@ interface AcpCheckoutKitOptions {
         astraId?: string;
         attemptId?: string;
         valueMajor: number;
+        /** 5.19.0: always `{ unsigned: true, protocol: 'acp' }` (pass to `confirmCheckout`); absent on a resume. */
+        agentArtifacts?: AgentArtifacts;
+        /** 5.19.0: `{ kitSessionId, protocol: 'acp' }` — pass to `confirmCheckout`. */
+        metadata: CheckoutMetadata;
+        /** 5.19.0: set when an approved hold resumes. */
+        resumed?: {
+            approvalId?: string;
+        };
     }) => Promise<VerificationResult>;
     settle: (ctx: {
         session: AcpCheckoutSession;
@@ -6381,13 +6967,37 @@ interface AcpCheckoutKitOptions {
         paymentData?: Record<string, unknown>;
     }) => Promise<SettleResult>;
     reportSettlement?: (r: Parameters<VerificationGatewayClient['reportSettlement']>[0]) => Promise<unknown>;
+    /** 5.19.0: `settled` is your processor's settled outcome. */
     fulfil: (ctx: {
         session: AcpCheckoutSession;
         result: VerificationResult;
+        settled: Extract<PendingResolution, {
+            status: 'settled';
+        }>;
     }) => Promise<{
         id: string;
         permalink_url?: string;
     }>;
+    /** 5.19.0: settlement-report retries (default 3 attempts, 250 ms backoff). */
+    reportRetry?: ReportRetryOptions;
+    /** 5.19.0: a settlement report that still failed after retries (default `console.error`). */
+    onReportError?: (err: unknown, ctx: {
+        sessionId: string;
+        orderId?: string;
+        kind?: 'settlement_report' | 'order_webhook';
+    }) => void;
+    /**
+     * 5.19.0: the public origin agents reach this kit at; `expressHandler`
+     * rebuilds the request URL from it. Default: Express's own view, using
+     * `X-Forwarded-Proto` / `X-Forwarded-Host` only when `trust proxy` is set.
+     */
+    publicOrigin?: string;
+    /** 5.19.0: policy links (terms of use, privacy, …) returned on every session. */
+    links?: Array<{
+        type: string;
+        url: string;
+        title?: string;
+    }>;
     /** Base path the kit is mounted at (default ''). */
     basePath?: string;
     store?: AcpCheckoutStore;
@@ -6465,6 +7075,19 @@ declare function buildAcpWellKnown(opts: AcpWellKnownOptions): {
 declare function createAcpCheckoutKit(opts: AcpCheckoutKitOptions): {
     handle: (req: Request, reqCtx?: KitRequestContext) => Promise<Response>;
     resolvePending: (sessionId: string, outcome: PendingResolution) => Promise<AcpCheckoutSession | null>;
+    /** 5.19.0 */
+    protocol: "acp";
+    publicOrigin: string | undefined;
+    resumeApproved: (sessionId: string, event?: Pick<ApprovalEvent, "approvalId">) => Promise<ResumeResult<AcpCheckoutSession>>;
+    resumeDeclined: (sessionId: string, reason?: "denied" | "expired" | "lapsed" | (string & {}), event?: Pick<ApprovalEvent, "approvalId">) => Promise<ResumeResult<AcpCheckoutSession>>;
+    applyApprovalEvent: (event: ApprovalEvent) => Promise<ResumeResult<AcpCheckoutSession>>;
+    pollHeldSessions: (o?: {
+        sessionIds?: string[];
+        apiBaseUrl?: string;
+    }) => Promise<Array<{
+        sessionId: string;
+        outcome: ResumeResult<AcpCheckoutSession>["outcome"] | "pending";
+    }>>;
 };
 
 /**
@@ -6483,11 +7106,28 @@ declare function createAcpCheckoutKit(opts: AcpCheckoutKitOptions): {
  * When the AstraSync middleware ran first, the caller's verified ASTRA-id
  * (`req.agentVerification.agent.astraId`) scopes sessions and idempotency
  * keys; override with `callerId`.
+ *
+ * 5.19.0:
+ * - the request URL the kit sees uses the kit's `publicOrigin` (UCP default:
+ *   the origin of `profile.endpoint`), so RFC 9421 `@target-uri` /
+ *   `@authority` and the forwarded agent artifacts match what the agent
+ *   signed behind a TLS-terminating proxy. Without one (ACP default), the
+ *   origin is `X-Forwarded-Proto` / `X-Forwarded-Host` when Express
+ *   `trust proxy` is set, else `req.protocol` + Host.
+ * - `approvalEventsPath` + `webhookSecret` mount the owner-approval events
+ *   receiver on the same handler (`handleApprovalEvents`); or mount
+ *   `approvalEventsHandler({ secret, kits: [ucpKit, acpKit] })` on its own
+ *   path to serve both kits from one Events URL.
  */
 
 /** Anything with a fetch-style `handle` (both checkout kits). */
 interface FetchKit {
     handle(req: Request, ctx?: KitRequestContext): Promise<Response>;
+    /** 5.19.0: the public origin to rebuild request URLs with (both kits expose it). */
+    readonly publicOrigin?: string;
+    /** 5.19.0: present on both kits — makes the kit an approval-event target. */
+    readonly protocol?: 'ucp' | 'acp';
+    applyApprovalEvent?: ApprovalEventKit['applyApprovalEvent'];
 }
 /** The parts of an Express request this adapter reads. */
 interface KitExpressRequest {
@@ -6499,6 +7139,10 @@ interface KitExpressRequest {
     body?: unknown;
     rawBody?: unknown;
     get?(name: string): string | undefined;
+    /** Express app (to read the `trust proxy` setting). */
+    app?: {
+        get(name: string): unknown;
+    };
     agentVerification?: {
         identityVerified?: boolean;
         agent?: {
@@ -6515,7 +7159,35 @@ interface KitExpressResponse {
 interface ExpressHandlerOptions {
     /** The caller's verified ASTRA-id (default: from `req.agentVerification` when identity-verified). */
     callerId?: (req: KitExpressRequest) => string | undefined;
-}
+    /**
+     * 5.19.0: serve owner-approval events on this path (POST; matched against
+     * the full request path or the path under the mount point), e.g.
+     * `'/astrasync/events'`. Set the endpoint's Events URL to it. Needs
+     * `webhookSecret`.
+     */
+    approvalEventsPath?: string;
+    /** 5.19.0: the endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    webhookSecret?: string | readonly string[];
+    /** 5.19.0: the kits events may name (default: this kit). */
+    approvalEventKits?: ApprovalEventKit[];
+    /** 5.19.0: dedupe store for event ids (default: process-local memory). */
+    seenEvents?: SeenEvents | ((eventId: string) => Promise<boolean>);
+}
+interface ApprovalEventsHandlerOptions {
+    /** The endpoint's webhook secret — or `[current, previous]` during a rotation. */
+    secret: string | readonly string[];
+    /** The kits events may name, e.g. `[ucpKit, acpKit]`. */
+    kits: ApprovalEventKit[];
+    /** Dedupe store (default: process-local memory). */
+    seen?: SeenEvents | ((eventId: string) => Promise<boolean>);
+}
+/**
+ * 5.19.0: an Express handler for the endpoint's Events URL, serving both
+ * kits: `app.post('/astrasync/events', express.raw({ type: '*\/*' }),
+ * approvalEventsHandler({ secret, kits: [ucpKit, acpKit] }))`. Answers 2xx
+ * when done, 401 on a bad signature, 503 to have the platform retry.
+ */
+declare function approvalEventsHandler(options: ApprovalEventsHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 /** An Express handler that runs a checkout kit and writes its Response back. */
 declare function expressHandler(kit: FetchKit, options?: ExpressHandlerOptions): (req: KitExpressRequest, res: KitExpressResponse, next: (err?: unknown) => void) => Promise<void>;
 
@@ -6766,4 +7438,4 @@ declare function contentDigest(body: string): string;
  */
 declare function signHttpRequest(req: SignableRequest, opts: SignHttpRequestOptions): Promise<Record<string, string>>;
 
-export { ACP_API_VERSION, ACP_SUPPORTED_API_VERSIONS, AEP_SPEC_VERSION, AP2_VCT, type AcpCheckoutKitOptions, type AcpCheckoutSession, type AcpCheckoutStatus, type AcpCheckoutStore, type AcpWellKnownOptions, type AepActorType, type AepArtifactRecord, type AepArtifactType, AepChain, type AepChainOptions, type AepChainVerification, type AepHashInput, AgentClient, type AgentCredentials, type AgentProtocol, type AgentProtocolIdentities, type AgentRecord, type Ap2Party, type Ap2VerifyResult, AstraSync, type AstraSyncAepEvidence, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AstraSyncMandates, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DECLARED_SOURCE_MAX, DEFAULT_EDGE_CONFIG, DEFAULT_IDEMPOTENCY_TTL_MS, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressHandlerOptions, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FetchKit, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, type HttpSignatureAlgorithm, type IdempotencyOptions, type IdempotencyRecord, type IdempotencyStore, KYDRequiredError, type KitExpressRequest, type KitExpressResponse, type KitRequestContext, type KyaPayIdentity, type KyaPayResult, type KyaPayTokenType, type KyaPayVerifyOptions, type ParseResult as LocalPolicyParseResult, type ValidationError as LocalPolicyValidationError, type ValidationResult as LocalPolicyValidationResult, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, MemoryCheckoutStore, MemoryIdempotencyStore, MemoryMppChallengeStore, type MerchantSettlementToken, type ModelConfig, type MppChallenge, type MppChallengeStore, type MppCredential, type MppReceipt, type MppVerifyOptions, type MppVerifyResult, type NegotiationResult, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PendingResolution, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, RedisIdempotencyStore, type RedisLike, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type ReportAttemptOptions, type RootKeyResolver, type RouteAccessConfig, type RoutePolicy, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, SettlementReportError, type SettlementRequest, type SignHttpRequestOptions, type SignableRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, UCP_ORDER_CAPABILITY, UCP_VERSION, type UcpAgentBinding, type CatalogItem as UcpCatalogItem, type UcpCheckoutKitOptions, type CheckoutSession as UcpCheckoutSession, type CheckoutStore as UcpCheckoutStore, type UcpLink, type UcpMessage, type UcpOrder, type UcpProfile, type UcpProfileResult, type SettleResult as UcpSettleResult, type UcpSeverity, type UcpSignatureResult, VERIFICATION_STATUS_HEADER, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyAp2Options, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, type X402PaymentPayload, type X402PaymentRequired, type X402PaymentRequirements, type X402ResourceInfo, type X402SettlementResponse, _resetEdgeConfigCache, acpPaymentHandlers, aepCanonicalJson, aepHash, aepPrivateKeyFromSeed, aepPublicKeyDocument, aepPublicKeyFromBase64, aepRawPublicKey, aepSign, aepTimestamp, aepVerifySignature, index as agent, astrasyncPaymentHandlers, authorizeSettlement, awaitStepUpApproval, beginIdempotent, buildAcpWellKnown, buildGuidance, buildMpp402Response, buildMppChallenge, buildSdkObservedMetadata, buildUcpOrder, buildUcpProfile, buildVerificationUnavailableBody, buildX402Challenge, canonicalJson, checkUcpAgentBinding, checkoutHash, clearCache, closedCheckoutMandate, closedPaymentMandate, contentDigest, createAcpCheckoutKit, createKbHop, createMcpMiddleware, createUcpCheckoutKit, decodeMppRequest, degradeToObserve, denyStatusFor, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, encodeMppReceipt, encodeX402SettlementResponse, express, expressHandler, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, fetchUcpProfile, finishIdempotent, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, idempotencyMiddleware, isEdgeConfig, isRejectedIdentityClaim, isRetryableSettlementError, isSpecialUseIp, isVerificationUnavailable, isVerifiedHopValidFor, issueDelegateSdJwt, matchEdgePathRule, matchPlatformSignature, matchRoutePattern, mppBodyDigest, negotiateUcp, nextjs, normalizeDeclaredSource, openCheckoutMandate, openPaymentMandate, parseYaml as parseLocalPolicyYaml, parseMppCredential, parseUcpAgentHeader, parseVerifiedHop, parseX402Challenge, parseX402Payment, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, requestFingerprint, rootMandateDigest, routePatternToRegExp, routePolicyOf, sanitizeHeaders, sdk, sdkFetch, sendUcpWebhook, serializeVerifiedHop, setMcpMeta, signHttpRequest, signRootMandate, signUcpRequest, signUcpResponse, index$1 as transport, ucpError, ucpEscalation, ucpFailure, ucpProfileHandler, ucpRequiredComponents, unavailableRetryAfterSeconds, validatePolicy as validateLocalPolicy, verify, verifyAepChain, verifyAp2Mandate, verifyDelegateChain, verifyKyaPayTokens, verifyMppChallenge, verifyUcpRequest, withIdempotency, x402PaymentMatchesOffer };
+export { ACP_API_VERSION, ACP_SUPPORTED_API_VERSIONS, AEP_SPEC_VERSION, AP2_VCT, type AcpCheckoutKitOptions, type AcpCheckoutSession, type AcpCheckoutStatus, type AcpCheckoutStore, type AcpWellKnownOptions, type AepActorType, type AepArtifactRecord, type AepArtifactType, AepChain, type AepChainOptions, type AepChainVerification, type AepHashInput, type AgentArtifacts, AgentClient, type AgentCredentials, type AgentProtocol, type AgentProtocolIdentities, type AgentRecord, type Ap2Party, type Ap2VerifyResult, type ApprovalEvent, type ApprovalEventKit, type ApprovalEventsHandlerOptions, type ApprovalEventsResponse, AstraSync, type AstraSyncAepEvidence, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, type AstraSyncMandates, type AttemptOutcome, type AttemptReport, AuthenticationError, type BuildGuidanceParams, CAPTURE_SCHEMA_VERSION, type CallerMetadata, ChallengeHandler, type CheckoutMetadata, type CommerceArtifactsPayload, type CommerceContext, type CommercePipelineInput, type CommerceShieldProps, type ConsiderationItem, type ConsiderationSet, type CounterpartyType, DECLARED_SOURCE_MAX, DEFAULT_EDGE_CONFIG, DEFAULT_IDEMPOTENCY_TTL_MS, type DashboardToolRule, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EndpointOperationalPatch, type EnhancedVerificationResult, type ExpressHandlerOptions, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FetchKit, type FiatSettlementBinding, type FrameworkConfig, type FulfilmentInfo, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HandleApprovalEventsOptions, type HealthResponse, type HttpSignatureAlgorithm, type IdempotencyOptions, type IdempotencyRecord, type IdempotencyStore, KYDRequiredError, type KitExpressRequest, type KitExpressResponse, type KitMessage, type KitRequestContext, type KyaPayIdentity, type KyaPayResult, type KyaPayTokenType, type KyaPayVerifyOptions, type ParseResult as LocalPolicyParseResult, type ValidationError as LocalPolicyValidationError, type ValidationResult as LocalPolicyValidationResult, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, MemoryCheckoutStore, MemoryIdempotencyStore, MemoryMppChallengeStore, MemorySeenEvents, type MerchantSettlementToken, type ModelConfig, type MppChallenge, type MppChallengeStore, type MppCredential, type MppReceipt, type MppVerifyOptions, type MppVerifyResult, type NegotiationResult, type NextJsMiddlewareOptions, type ObservedMetadata, type PDLSSConfig$1 as PDLSSConfig, type PDLSSDuration, type PDLSSInfo, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, PLATFORM_AGENT_SIGNATURES, type PendingRegistrationResponse, type PendingResolution, type PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, type PurposeSource, RUNTIME_SIGNATURES, RedisIdempotencyStore, type RedisLike, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type ReportAttemptOptions, type ReportRetryOptions, type ResumeOutcome, type ResumeResult, type RootKeyResolver, type RouteAccessConfig, type RoutePolicy, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SeenEvents, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, SettlementReportError, type SettlementRequest, type SignHttpRequestOptions, type SignableRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TestEventResult, type TestEventType, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, UCP_ORDER_CAPABILITY, UCP_VERSION, type UcpAgentBinding, type CatalogItem as UcpCatalogItem, type UcpCheckoutKitOptions, type CheckoutSession as UcpCheckoutSession, type CheckoutStore as UcpCheckoutStore, type UcpLink, type UcpMessage, type UcpOrder, type UcpProfile, type UcpProfileResult, type SettleResult as UcpSettleResult, type UcpSeverity, type UcpSignatureResult, VERIFICATION_STATUS_HEADER, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerificationWarning, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyAp2Options, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, type X402PaymentPayload, type X402PaymentRequired, type X402PaymentRequirements, type X402ResourceInfo, type X402SettlementResponse, _resetEdgeConfigCache, abandonIdempotent, acpPaymentHandlers, aepCanonicalJson, aepHash, aepPrivateKeyFromSeed, aepPublicKeyDocument, aepPublicKeyFromBase64, aepRawPublicKey, aepSign, aepTimestamp, aepVerifySignature, index as agent, approvalEventsHandler, astrasyncPaymentHandlers, authorizeSettlement, awaitStepUpApproval, beginIdempotent, buildAcpWellKnown, buildGuidance, buildMpp402Response, buildMppChallenge, buildSdkObservedMetadata, buildUcpOrder, buildUcpProfile, buildVerificationUnavailableBody, buildX402Challenge, canonicalJson, checkUcpAgentBinding, checkoutHash, clearCache, closedCheckoutMandate, closedPaymentMandate, contentDigest, createAcpCheckoutKit, createKbHop, createMcpMiddleware, createUcpCheckoutKit, decodeMppRequest, degradeToObserve, denyStatusFor, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, encodeMppReceipt, encodeX402SettlementResponse, express, expressHandler, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, fetchUcpProfile, finishIdempotent, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, handleApprovalEvents, hasCredentials, idempotencyMiddleware, isEdgeConfig, isRejectedIdentityClaim, isRetryableSettlementError, isSharedVerdict, isSpecialUseIp, isVerificationUnavailable, isVerifiedHopValidFor, issueDelegateSdJwt, matchEdgePathRule, matchPlatformSignature, matchRoutePattern, mppBodyDigest, negotiateUcp, nextjs, normalizeDeclaredSource, onVerificationResult, openCheckoutMandate, openPaymentMandate, parseYaml as parseLocalPolicyYaml, parseMppCredential, parseUcpAgentHeader, parseVerifiedHop, parseX402Challenge, parseX402Payment, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, requestFingerprint, rootMandateDigest, routePatternToRegExp, routePolicyOf, sanitizeHeaders, sdk, sdkFetch, sendUcpWebhook, serializeVerifiedHop, setMcpMeta, signHttpRequest, signRootMandate, signUcpRequest, signUcpResponse, index$1 as transport, ucpError, ucpEscalation, ucpFailure, ucpProfileHandler, ucpProfileKeys, ucpRequiredComponents, unavailableRetryAfterSeconds, validatePolicy as validateLocalPolicy, verify, verifyAepChain, verifyAp2Mandate, verifyDelegateChain, verifyKyaPayTokens, verifyMppChallenge, verifyUcpRequest, withIdempotency, x402PaymentMatchesOffer };