@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/index.d.ts

@@ -1,19 +1,1449 @@
-import { G as GatewayConfig, s as StepUpApprovalInfo, u as StepUpOutcome, t as StepUpApprovalStatus, E as EnhancedVerificationResult, A as AccessFailure } from './types-76TB0fxW.js';
-export { a as AgentCredentials, b as AstraSyncCredentials, c as AttemptOutcome, d as AttemptReport, C as CallerMetadata, e as CommerceArtifactsPayload, f as CommerceShieldProps, g as ConsiderationItem, h as ConsiderationSet, i as CounterpartyType, j as ExpressMiddlewareOptions, F as FiatSettlementBinding, k as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, l as ProtocolTransport, R as RouteAccessConfig, m as RuntimeChallengeResult, S as SDKOptions, n as SettlementArtifact, o as SettlementArtifactBinding, p as SettlementArtifactBindingBase, q as SettlementOutcomeInfo, r as StablecoinSettlementBinding, T as TokenGuidance, v as TrustLevel, V as VerificationInterstitialProps, w as VerificationRequest, x as VerificationResult, y as VerifiedAgent, z as VerifiedDeveloper, B as VerifiedOrganization } from './types-76TB0fxW.js';
-export { T as TRUST_LEVEL_RANGES, g as getTrustLevel, s as sdk } from './sdk-C1IOA5LE.js';
-export { VerifyOptions, clearCache, extractCredentials, fetchRoutes, hasCredentials, quickVerify, reportAttempt, reportUnregisteredAttempt, verify } from './verify.js';
-export { e as express } from './express-D3Tf-b23.js';
-export { n as nextjs } from './nextjs-xM-jdNrX.js';
-export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-iJ9_DdLk.js';
-export { M as MCP_VERIFIED_HOP_HEADER, a as MCP_VERIFIED_HOP_MAX_AGE_MS, b as McpMiddlewareOptions, T as ToolGate, c as ToolGateConfig, V as VerifiedHopMarker, d as createMcpMiddleware, i as isVerifiedHopValidFor, f as parseVerifiedHop, s as serializeVerifiedHop } from './mcp-OrVOrH-s.js';
-export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.js';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DaMXZabg.js';
-export { DEFAULT_EDGE_CONFIG, EdgeConfig, EdgeMode, EdgePathRule, EdgeVerificationDepth, FetchEdgeConfigResult, FetchEdgeConfigSuccess, _resetEdgeConfigCache, degradeToObserve, fetchEdgeConfig, getEdgeConfig, isEdgeConfig, matchEdgePathRule } from './edge-config.js';
-export { DynamicPlatformFingerprint, PLATFORM_AGENT_SIGNATURES, PlatformAgentVendor, PlatformDetectionInput, PlatformFingerprint, PlatformSignatureDef, detectPlatformFingerprint, matchPlatformSignature } from './platform-signatures.js';
-export { CAPTURE_SCHEMA_VERSION, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, ObservedMetadata, SanitizeHeadersResult, buildSdkObservedMetadata, deriveConnectionFromHeaders, extractApiKeyFormat, extractPlatformHeaders, sanitizeHeaders } from './metadata-capture.js';
-import 'express';
-import 'next/server';
-import 'jose';
+import { RequestHandler, Request, Response as Response$1 } from 'express';
+import * as next_server from 'next/server';
+import { NextRequest } from 'next/server';
+import { JWK } from 'jose';
+
+/**
+ * Maximal metadata capture — the shared, edge-safe sanitiser.
+ *
+ * AstraSync's thesis is total metadata capture: every header and connection
+ * signal an inbound agent presents is a signal we want to keep. This module is
+ * the ONE place that decides what is safe to store verbatim, what is a secret
+ * to drop, and what credential headers reduce to a safe *format prefix* (a
+ * platform signal, never the secret itself).
+ *
+ * It runs in three places that must agree byte-for-byte:
+ *   - the edge adapter (`@astrasyncai/adapter-lambda`) — the richest capture
+ *     point (full CloudFront header arrays),
+ *   - the SDK adapters (express / nextjs) — for SDK-only merchants with no edge,
+ *   - (indirectly) the backend, which stores whatever the above forward.
+ *
+ * Pure — no Node built-ins, no I/O — so it is safe in Lambda@Edge, the browser
+ * build, and Deno. Capture is cheap: at the edge and SDK it is local string
+ * work, and the backend stores it on a fire-and-forget event insert, so it adds
+ * ZERO verify-access decision latency. Detection (which few signals imply which
+ * vendor) is a separate, curated concern — see `platform-signatures.ts`.
+ */
+/**
+ * Version of the capture semantics (what is kept, dropped, reduced, or
+ * derived — and under which key names).
+ *
+ * Capture semantics are FROZEN within a package major version: a given
+ * `schemaVersion` always means the same field vocabulary and the same
+ * keep/drop/reduce rules. The number bumps only on a SEMANTIC change to
+ * capture (a renamed key, a changed reduction rule) — never for additive
+ * signals, and never merely because the package version moved. To tell
+ * builds apart, use the `sdkVersion` already present on the verify body;
+ * `schemaVersion` answers the different question "how do I interpret this
+ * stored metadata?".
+ */
+declare const CAPTURE_SCHEMA_VERSION = 1;
+/**
+ * The captured, sanitised view of an inbound agent's request metadata. Attached
+ * to verify-access / beacon payloads as `callerMetadata.observedMetadata`.
+ */
+interface ObservedMetadata {
+    /** Header name → value, secrets removed, verbatim otherwise. */
+    headers: Record<string, string>;
+    /**
+     * Safe key-format prefix of a credential header (e.g. `sk-ant-api03`,
+     * `sk-proj`, `AIza`) — a platform signal, NEVER the secret. Absent if no
+     * credential header was present or none matched a known format.
+     */
+    apiKeyFormat?: string;
+    /**
+     * The subset of `headers` that are known platform-signal headers
+     * (`openai-organization`, `x-goog-user-project`, `anthropic-version`, …),
+     * pulled out for convenient detection + display. Values are the same
+     * sanitised strings as in `headers`.
+     */
+    platformHeaders?: Record<string, string>;
+    /**
+     * Connection-layer signals (IP, ASN, country, TLS version, HTTP version,
+     * device class, TLS fingerprint). Edge adapters populate this from the
+     * platform's native connection surface — the authoritative source. SDK
+     * adapters populate it as a fallback via {@link deriveConnectionFromHeaders}
+     * when a CDN in front of the merchant injected the equivalent headers;
+     * absent when neither source had anything.
+     */
+    connection?: Record<string, string>;
+    /**
+     * Number of cookie pairs the caller sent. The `cookie` header VALUE is a
+     * secret and is always dropped; the COUNT is a client-shape signal
+     * (browsers carry cookies, most automation carries none) that would
+     * otherwise be unobservable downstream. Absent when no cookie header
+     * arrived.
+     */
+    cookieCount?: number;
+    /**
+     * Query-string parameter NAMES (deduped, lowercased) — values are NEVER
+     * captured (they routinely carry OAuth codes, tokens, and PII, and no
+     * deny-list is complete). Names alone fingerprint client shape. Populated
+     * by the edge path, which sees the raw query string.
+     */
+    queryKeys?: string[];
+    /**
+     * Version of the capture semantics this object was produced under — see
+     * {@link CAPTURE_SCHEMA_VERSION}. Optional for backward compatibility with
+     * metadata captured before the field existed.
+     */
+    schemaVersion?: number;
+}
+/**
+ * Result of sanitising a raw header map. `headers` is always present (possibly
+ * empty); `apiKeyFormat` / `platformHeaders` only when a signal was found.
+ */
+interface SanitizeHeadersResult {
+    headers: Record<string, string>;
+    apiKeyFormat?: string;
+    platformHeaders?: Record<string, string>;
+    /** Cookie-pair count; the cookie value itself is always dropped. */
+    cookieCount?: number;
+}
+/** Size caps — the only guard against jsonb bloat from a hostile POST. */
+declare const MAX_HEADERS = 64;
+declare const MAX_HEADER_VALUE_BYTES = 1024;
+declare const MAX_TOTAL_BYTES: number;
+/**
+ * Extract the safe key-format prefix from a credential header value. Strips a
+ * leading `Bearer ` / `Basic ` scheme, then returns the longest known prefix
+ * that the (lowercased) value starts with. Returns undefined for opaque values
+ * (e.g. a bare UUID token) so we never guess a format we don't recognise.
+ */
+declare function extractApiKeyFormat(rawValue: string): string | undefined;
+/**
+ * Sanitise a raw header map for storage. Deny-lists genuine secrets, reduces
+ * credential headers to a safe format prefix, keeps everything else verbatim,
+ * and enforces the size caps that bound jsonb growth.
+ *
+ * Accepts any string→(string|string[]|undefined) map (Node's `req.headers`,
+ * CloudFront's flattened headers, a plain object). Multi-value headers are
+ * joined with `, ` per RFC 7230.
+ */
+declare function sanitizeHeaders(raw: Record<string, string | string[] | undefined> | undefined | null): SanitizeHeadersResult;
+/**
+ * Pull the known platform-signal headers out of an ALREADY-sanitised header
+ * map. `sanitizeHeaders` already computes this as a by-product; this standalone
+ * form is exported for call-sites (edge, tests) that hold a sanitised map and
+ * want only the platform subset. Never re-run over raw (unsanitised) headers.
+ */
+declare function extractPlatformHeaders(sanitized: Record<string, string> | undefined | null): Record<string, string>;
+/**
+ * Derive the connection-layer block from CDN-injected request headers.
+ *
+ * When a merchant's SDK-gated origin sits behind a CDN (Cloudflare, Fastly,
+ * Vercel, CloudFront), the CDN has already seen the connection layer and
+ * injected it as headers. This promotes those headers to the same
+ * `connection` keys the edge adapters populate natively, so SDK-only
+ * deployments still get IP / geo / TLS attribution. Precedence per key:
+ *
+ * - `ip`: `cf-connecting-ip` > `fastly-client-ip` > `true-client-ip` >
+ *   `x-real-ip` > `cloudfront-viewer-address` (port stripped) > leftmost
+ *   `x-forwarded-for`
+ * - `country`: `cf-ipcountry` > `x-vercel-ip-country` >
+ *   `cloudfront-viewer-country` > `fastly-geo-country`
+ * - `region` / `city` / `timeZone`: Vercel then CloudFront viewer headers
+ * - `countryRegionName` / `asn` / `tlsVersion` / `httpVersion` /
+ *   `metroCode` / `headerOrder` / `headerCount`: `cloudfront-viewer-*`
+ * - `tlsFingerprint`: `cf-ja3-hash` > `cloudfront-viewer-ja3-fingerprint`
+ * - `ja4`: `cf-ja4` > `cloudfront-viewer-ja4-fingerprint`
+ *
+ * All keys are additive under `schemaVersion` 1 (the frozen-capture doctrine
+ * bumps only for changed semantics, never for additive signals). Values are
+ * truncated to MAX_CONNECTION_VALUE_CHARS — the platform's hard bound.
+ *
+ * Edge adapters keep their richer native collectors — native platform
+ * signals are authoritative; this header derivation is the SDK-level
+ * fallback. Header names are matched case-insensitively. Returns undefined
+ * when no source header is present, so the `connection` key is simply
+ * omitted (matching edge behaviour).
+ */
+declare function deriveConnectionFromHeaders(headers: Record<string, string> | undefined | null): Record<string, string> | undefined;
+/**
+ * The FULL metadata capture for one request at an SDK adapter (express /
+ * nextjs / mcp): sanitised headers, the safe credential format prefix, the
+ * platform-signal subset, the CDN-derived connection block, and the capture
+ * schema version. This is the ONE builder all SDK adapters share, so their
+ * verify-access bodies agree byte-for-byte.
+ *
+ * Connection derivation runs over the RAW header map (pre-cap) — the size
+ * caps guard storage growth and must never hide a geo/IP header that
+ * happened to arrive late in an oversized map.
+ */
+declare function buildSdkObservedMetadata(rawHeaders: Record<string, string | string[] | undefined> | undefined | null): ObservedMetadata;
+
+/**
+ * AstraSync Universal Verification Gateway Types
+ *
+ * TypeScript type definitions for agent verification across all counterparty types.
+ */
+
+/**
+ * Trust levels assigned to agents based on their composite trust score
+ */
+type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
+/**
+ * Types of counterparties that can integrate the gateway
+ */
+type CounterpartyType = 'agent' | 'api' | 'mcp_server' | 'website' | 'other' | 'unknown';
+/**
+ * Agent credentials extracted from request
+ */
+interface AgentCredentials {
+    /** ASTRA-xxx identifier */
+    astraId?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** JWT token */
+    jwt?: string;
+    /** Raw authorization header */
+    authorizationHeader?: string;
+}
+/**
+ * Configuration options for the verification gateway
+ */
+interface GatewayConfig {
+    /** AstraSync API base URL */
+    apiBaseUrl: string;
+    /** API key for authenticating with AstraSync. */
+    apiKey?: string;
+    /**
+     * @deprecated Removed in v2.3.0 — server is the single source of truth for
+     * access decisions (verified ID + runtime challenge + PDLSS + trust score).
+     * Setting this no longer affects access decisions. If you need a higher gate
+     * for an endpoint, configure it server-side via the endpoint's
+     * `trust_score_requirement`.
+     */
+    minTrustScore?: number;
+    /**
+     * @deprecated Removed in v2.3.0 — see `minTrustScore` above.
+     */
+    minTrustScoreForFull?: number;
+    /** Cache verification results (TTL in seconds) */
+    cacheTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom headers to send with verification requests */
+    customHeaders?: Record<string, 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) */
+    counterpartyType?: CounterpartyType;
+    /**
+     * This counterparty's ASTRAE-id (issued at endpoint registration). When set,
+     * the SDK forwards it on verify-access calls so the server attributes traffic
+     * directly to this endpoint rather than resolving by URL. Useful when:
+     *  - The merchant has multiple endpoints under the same origin (each running
+     *    its own SDK instance with its own counterpartyId)
+     *  - The endpoint URL might be served behind a proxy / different host than
+     *    the registered origin
+     */
+    counterpartyId?: string;
+    /**
+     * Step-up hold-and-poll (3.6.0, opt-in). When set, adapters HOLD a request
+     * whose verify() came back step_up_required, poll the approval status, and
+     * on 'approved' re-verify the same request once (cache-bypassed) so the
+     * backend redeems the single-use approval — the MFA model the Java SDK
+     * ships default-on. Values:
+     *  - undefined (default): feature OFF — adapters fail closed immediately,
+     *    exactly as 3.5.0 (a minor release must not silently convert instant
+     *    403s into multi-minute holds).
+     *  - 0: hold until the approval's expiresAt (+5s grace); 5-min fallback
+     *    when expiresAt is missing/unparsable (Java parity).
+     *  - >0: hold at most this many milliseconds.
+     * Next.js edge runtimes enforce ~25s wall-clock budgets — set a small value
+     * there (≤20000) or gate in a Node route handler instead.
+     */
+    stepUpMaxWaitMs?: number;
+    /**
+     * Poll interval for the step-up hold (3.6.0). Default 3000ms, clamped to a
+     * 250ms floor. At the default the backend's 60/min/IP poll rate limit
+     * tolerates ~3 concurrent holds per merchant IP; poll errors are treated as
+     * transient, so limiter hits degrade the hold to 'timeout', never an error.
+     */
+    stepUpPollIntervalMs?: number;
+    /**
+     * Disable the one-time init self-test. The SDK normally fires a HEAD/OPTIONS
+     * to `${apiBaseUrl}/agents/verify-access` on first verify() call and warns
+     * if the response is HTML (indicating apiBaseUrl is pointing at a marketing
+     * site rather than the API). Set true for tests or environments where the
+     * extra request is undesirable.
+     */
+    disableInitChecks?: boolean;
+    /**
+     * When true, the init self-test runs synchronously on the first verify()
+     * call and THROWS on misconfig (apiBaseUrl returning HTML, unreachable,
+     * etc.) instead of warning + continuing. Recommended for production
+     * deploys where you want a fast-fail startup signal rather than silent
+     * verify-access call failures. Default false for backward compatibility.
+     */
+    strictInit?: boolean;
+    /**
+     * 4.0.0: hard timeout (ms) on the outbound verify-access call. Without it
+     * a hanging backend hangs the merchant's middleware — and every inbound
+     * agent request behind it — indefinitely. Timeouts surface as the
+     * fail-closed `verify_access.api_error` result. Default 10_000.
+     */
+    verifyTimeoutMs?: number;
+    /**
+     * v2.3.8: emit `X-Astra-Gateway-Mode: unenforced` (with
+     * `X-Astra-Gateway-Reason: no-policy | no-match`) on responses where the
+     * middleware fell through without consulting verify-access. Lets integration
+     * tests assert "this endpoint should be gated; if it falls through, fail
+     * loudly". Default off; opt-in.
+     *
+     * The header value was renamed from the ambiguous `pass-through` to
+     * `unenforced` so it describes the GATE state only — not whether the
+     * request succeeded end-to-end. The config FLAG name
+     * (`setPassThroughHeader`) is unchanged for backwards compatibility.
+     */
+    setPassThroughHeader?: boolean;
+    /**
+     * v2.3.8: dashboard origin used to construct configuration links in
+     * boot-time warnings (e.g. when no per-route policy is configured).
+     * Defaults to `https://astrasync.ai/dashboard` (the `app.astrasync.ai`
+     * subdomain referenced in older docs does not resolve).
+     */
+    dashboardUrl?: string;
+    /**
+     * When true, the middleware calls verify-access for any request that presents
+     * AstraSync credentials, even on `observe`-marked routes / tools that would
+     * otherwise pass through unevaluated. Populates `req.agentVerification` and
+     * records the verification event for the audit trail. Enforcement still
+     * respects the gate — an `observe` marker still passes through regardless of
+     * the server decision. Default false to preserve existing behaviour.
+     *
+     * Use this when a single endpoint serves both anonymous and verified
+     * traffic with different response shapes (e.g. anonymous catalog vs
+     * verified catalog with agent-only SKUs; anonymous MCP tool listing
+     * vs verified tool-listing with restricted tools surfaced). Without
+     * the flag, anonymous-with-credentials passes are invisible to the
+     * merchant handler and to the AstraSync activity feed.
+     *
+     * Lives on `GatewayConfig` (not adapter-specific) so both express and
+     * MCP middlewares inherit it via their `extends GatewayConfig` chain.
+     */
+    evaluateAlwaysIfCredentialed?: boolean;
+}
+/**
+ * Verified agent information
+ */
+interface VerifiedAgent {
+    /** ASTRA-xxx identifier */
+    astraId: string;
+    /** Agent display name */
+    name: string;
+    /** Composite trust score (0-100) */
+    trustScore: number;
+    /** Trust level tier */
+    trustLevel: TrustLevel;
+    /** Whether agent is blockchain-verified */
+    blockchainVerified: boolean;
+    /** Agent status */
+    status: 'active' | 'inactive' | 'suspended' | 'migrating' | 'terminated' | 'retired';
+}
+/**
+ * Verified developer (KYD) information
+ */
+interface VerifiedDeveloper {
+    /** ASTRAD-xxx identifier */
+    astradId: string;
+    /** Developer name */
+    name?: string;
+    /** Developer trust score */
+    trustScore: number;
+    /** Whether developer identity is verified */
+    verified: boolean;
+}
+/**
+ * Verified organization (KYO) information
+ */
+interface VerifiedOrganization {
+    /** Organization name */
+    name: string;
+    /** Whether organization is verified */
+    verified: boolean;
+    /** Organization trust score */
+    trustScore: number;
+}
+/**
+ * PDLSS policy information returned with verification.
+ *
+ * @deprecated v2.2.4 — verify-access no longer returns the full PDLSS to the
+ * merchant. Read `EnhancedVerificationResult.verificationContext.pdlssCheck`
+ * instead for the merchant-facing summary, and `appliedPolicy` (top-level on
+ * the verification result) for the boundary name + policy version. The full
+ * PDLSS is owner-side only (queryable via `/api/agents/:id` when
+ * authenticated as the agent owner).
+ */
+interface PDLSSInfo {
+    purposeAllowed: boolean;
+    withinDuration: boolean;
+    withinLimits: boolean;
+    scopeAllowed: boolean;
+    selfInstantiationAllowed: boolean;
+    allowedPurposes?: string[];
+    limits?: Record<string, number>;
+    scope?: string[];
+    /** Applied policy details. Boundary/policy UUIDs deliberately not included. */
+    appliedPolicy?: AppliedPolicy;
+}
+/**
+ * Applied policy — merchant-facing identifiers only.
+ *
+ * Boundary and policy UUIDs are deliberately not surfaced; merchants and
+ * agent owners are different tenants and internal join keys are a
+ * cross-tenant correlation primitive. Internal callers that need UUIDs
+ * query the boundary/policy tables directly.
+ */
+interface AppliedPolicy {
+    boundaryName: string;
+    policyVersion: string;
+}
+/**
+ * Structured "why" of a verification decision the merchant receives.
+ *
+ * Tells the merchant whether the agent ID was verified, whether the runtime
+ * challenge succeeded, whether the request was within PDLSS, and the agent's
+ * actual dynamic trust score — without exposing thresholds, scope lists, or
+ * other-tenant counterparty membership.
+ *
+ * `attestations` is empty unless the calling endpoint's access policy
+ * declared `required_attestations`. Each attestation carries a blockchain
+ * proof reference (or, in the future, a full ZKP) so the merchant can verify
+ * the underlying claim without seeing the raw underlying data (e.g. the
+ * Persona/ConnectID transaction).
+ */
+interface VerificationContext {
+    idVerified: boolean;
+    runtimeChallenge: {
+        status: 'passed' | 'skipped' | 'failed' | 'timeout' | 'not_supported';
+        checkedAt: string | null;
+    };
+    pdlssCheck: {
+        /** Outcome only — no thresholds disclosed. */
+        result: 'within' | 'exceeded' | 'denied' | 'not_evaluated';
+        /** Category-level only. */
+        purpose: 'approved' | 'denied';
+        scope: 'approved' | 'denied';
+    };
+    /** Live composite score at decision time (not the stale snapshot column). */
+    dynamicTrustScore: number;
+    attestations: Attestation[];
+}
+/**
+ * Attestation returned in `VerificationContext.attestations`.
+ *
+ * `proofType: 'reference'` (interim) means `proof` is a blockchain txn hash
+ * the merchant CAN verify against on-chain records but doesn't HAVE to.
+ * `proofType: 'zkp'` (future) means `proof` is a zero-knowledge proof.
+ * Wire shape is forward-compatible — clients reading 'reference' today won't
+ * break when it becomes 'zkp'.
+ */
+interface Attestation {
+    /** Attestation kind (e.g. `verified_human_party`). */
+    type: string;
+    status: 'passed' | 'failed';
+    /**
+     * ISO-8601 timestamp of the underlying check (when KYC/IDV/AML actually ran).
+     * Merchants compare this against their `maxAgeDays` requirement on the
+     * endpoint to enforce per-attestation freshness. Distinct from `validUntil`:
+     * `checkedAt` is when the data was sourced; `validUntil` is when the issuer
+     * stops vouching for it.
+     */
+    checkedAt: string;
+    validUntil?: string;
+    proofType: 'reference' | 'zkp';
+    proof: string;
+}
+/**
+ * Guidance information for unverified agents
+ */
+interface GuidanceInfo {
+    /** Human-readable guidance message */
+    message: string;
+    /** URL to register for AstraSync */
+    registrationUrl: string;
+    /** URL to documentation */
+    documentationUrl: string;
+    /** Steps to get verified */
+    steps?: string[];
+    /**
+     * 5.1.0: hosted AstraSync MCP connector — the keyless, human-approved
+     * registration path for agents already operating inside an MCP host.
+     */
+    mcp?: {
+        endpoint: string;
+        discoveryUrl?: string;
+        message?: string;
+    };
+}
+interface StepUpApprovalInfo {
+    approvalId: string;
+    pollUrl: string;
+    expiresAt: string;
+}
+/**
+ * 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';
+/**
+ * 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.
+ */
+type StepUpOutcome = Exclude<StepUpApprovalStatus, 'pending'> | 'timeout';
+/** Fields common to every settlement-artifact binding. */
+interface SettlementArtifactBindingBase {
+    merchantId: string;
+    sessionId: string;
+    singleUse: true;
+    expiresAt: string;
+}
+/**
+ * Fiat/processor artifact binding (Stripe, Skyfire, PayPal) — the processor
+ * is the unit authority, so the binding carries the major-unit pricing amount.
+ */
+interface FiatSettlementBinding extends SettlementArtifactBindingBase {
+    amount: number;
+    currency: string;
+}
+/**
+ * Stablecoin voucher binding — wire format v2. Money is integer minor units
+ * (`amountMinor` scaled by `assetDecimals`, no floats), and the settlement
+ * asset is pinned to a chain + token contract (CAIP-19 `asset`).
+ */
+interface StablecoinSettlementBinding extends SettlementArtifactBindingBase {
+    amountMinor: number;
+    assetDecimals: number;
+    currency: string;
+    chainId: number;
+    tokenContract: string;
+    asset: string;
+}
+type SettlementArtifactBinding = FiatSettlementBinding | StablecoinSettlementBinding;
+/**
+ * Settlement artifact returned on a clean merchant-mediated grant. The JWS
+ * `artifact` is the authoritative, signed object — `binding` mirrors its
+ * claims for display convenience only. Never settle from `binding`; decide
+ * from the server-verified payload at redeem time.
+ */
+interface SettlementArtifact {
+    type: string;
+    artifact: string;
+    binding: SettlementArtifactBinding;
+}
+/**
+ * Complete verification result
+ */
+/**
+ * Single failed gate on a verify-access denial. Aggregated into
+ * `VerificationResult.failures[]` so partners can see every blocker in one
+ * response (v2.9.8+) — previously the response was fail-fast on the
+ * first failed gate, forcing a fix-and-retry cascade through PDLSS
+ * dimensions, counterparty allowlist, trust score, and attestations.
+ *
+ * `dimension` is namespaced so receivers can group by gate family:
+ *   - `agent.<lookup|status>`                  (hard prereqs)
+ *   - `pdlss.<purpose|duration|limits|scope|selfInstantiation>`
+ *   - `counterparty.<allowlist|trust>`
+ *   - `attestation.<type>` (e.g. `attestation.verified_human_party`)
+ *   - `endpoint.<deactivated|trust|policy>`
+ */
+interface AccessFailure {
+    dimension: string;
+    message: string;
+    guidance?: string;
+}
+interface VerificationResult {
+    /**
+     * Identity-verification status — was the caller successfully
+     * resolved to a registered agent (signature/credential check passed)?
+     * Maps to backend `verificationContext.idVerified`. Drives HTTP 401 vs 403
+     * mapping in default adapters: `!identityVerified` → 401 (re-authenticate);
+     * `identityVerified && !policyAllowed` → 403 (re-auth won't help — update
+     * PDLSS scope or step up). Replaces the pre-4.x `verified` field, which
+     * collapsed identity and policy into a single boolean and forced merchants
+     * writing `verified ? 200 : 401` into the wrong HTTP-status recovery path
+     * on PDLSS denials of authenticated agents.
+     */
+    identityVerified: boolean;
+    /**
+     * Does the endpoint's PDLSS / access policy permit this
+     * specific action? Maps to backend `access.allowed`. Distinct from
+     * `identityVerified`: a verified agent can be policy-denied (403); an
+     * unverified caller's policy field is `false` by definition.
+     */
+    policyAllowed: boolean;
+    /** Verified agent info (if verified) */
+    agent?: VerifiedAgent;
+    /** Developer info (if available) */
+    developer?: VerifiedDeveloper;
+    /** Organization info (if available) */
+    organization?: VerifiedOrganization;
+    /** PDLSS policy info (if verified) */
+    pdlss?: PDLSSInfo;
+    /** Guidance for unverified agents */
+    guidance?: GuidanceInfo;
+    /** Reasons for denial (if not allowed) */
+    denialReasons?: string[];
+    /**
+     * All policy / gate failures detected on this verify-access call.
+     * v2.9.8+ — empty when allowed. Iterate this for the full debug picture
+     * instead of consuming `denialReasons` (which only carries the headline
+     * message of each failure).
+     */
+    failures?: AccessFailure[];
+    /**
+     * Correlation handle for tying a partner-visible denial to a server-side
+     * log line, surfaced so adapter onDenied handlers can include it on the
+     * merchant's response body. Present on anonymous server responses, on
+     * synthesised stubs for API-error fallbacks (`createGuidanceResponse`),
+     * and on the `verify_access.internal_error` 200-shaped failure shape.
+     */
+    correlationId?: string;
+    /**
+     * 3.12.0: attempt-chain handle, server-echoed on
+     * every response branch (caller-supplied or server-minted). Disjoint from
+     * `correlationId`/`sessionId` — those identify one verification EVENT; an
+     * attempt CONTAINS events (the whole catalog → intent → settlement funnel
+     * for one shopping attempt). On a cache hit the SDK overwrites this with
+     * the current request's own attemptId (or drops it) so a cached verdict
+     * never leaks a prior attempt's id.
+     */
+    attemptId?: string;
+    /**
+     * 4.0.0: the backend rejected THIS INTEGRATION'S own API key (revoked /
+     * expired / rotated) — a deterministic merchant-side misconfig, distinct
+     * from both an agent denial and a transient `verify_access.api_error`.
+     * Adapters branch on it to answer inbound agents with 503 +
+     * `MERCHANT_VERIFICATION_MISCONFIGURED` instead of a misleading 401.
+     */
+    misconfigured?: boolean;
+    /**
+     * 4.6.0: a TRANSIENT infrastructure failure (`verify_access.api_error` — a
+     * 5xx / timeout / CSRF-403 reaching the verify-access backend), NOT a policy
+     * deny and NOT a deterministic misconfig. Consumers should surface it as an
+     * error-and-retry (recommendation `'error'`), never as a policy denial. Unset
+     * on misconfig (deterministic — retrying will not help) and on real denials.
+     */
+    retryable?: boolean;
+    /** Whether step-up authentication is required */
+    requiresStepUp?: boolean;
+    /** Whether approval is required */
+    requiresApproval?: boolean;
+    /** Step-up approval info (present when transaction is in the human-approval band). */
+    stepUpApproval?: StepUpApprovalInfo;
+    /**
+     * Terminal outcome of an opt-in hold-and-poll wait (3.6.0). Set by adapters
+     * on the result they deny with when the hold ended in denied / expired /
+     * consumed / timeout. Absent when the feature is off or the hold succeeded
+     * (an approved hold re-verifies and the fresh grant result replaces this one).
+     */
+    stepUpOutcome?: StepUpOutcome;
+    /** Settlement voucher (present on clean merchant-mediated grants with a verified wallet). */
+    settlement?: SettlementArtifact;
+    /**
+     * 5.3.0 (astra-pay): sanitized first-party settlement outcome. Present
+     * INSTEAD of `settlement` when the counterparty is an AstraSync-operated
+     * storefront and the request carried `commercePhase: 'confirm'` — the
+     * backend redeemed the voucher and executed the charge server-side
+     * (charge-at-redeem), so there is no artifact to deliver, only the result.
+     * `no_instrument` = policy passed but the owner has no chargeable
+     * instrument on file (steer the user to add one via onboarding).
+     */
+    settlementOutcome?: SettlementOutcomeInfo;
+    /** Timestamp of verification */
+    verifiedAt: Date;
+    /** TTL for this result (seconds) */
+    cacheTtl?: number;
+}
+/**
+ * 5.3.0 (astra-pay): sanitized outcome of first-party charge-at-redeem
+ * settlement. Carries NO voucher/instrument material — the settlement channel
+ * stays merchant-only; this is the result the agent plane is allowed to see.
+ *
+ * 5.4.2: `requires_approval` — the transaction is HELD for human step-up
+ * approval. Not a failure: record the order as pending; after the human
+ * approves, the platform re-drives the confirm with the SAME
+ * checkoutSessionId and that re-drive carries the settling outcome
+ * (one order row per session — the re-drive claims the same row).
+ */
+interface SettlementOutcomeInfo {
+    status: 'settled' | 'failed' | 'requires_action' | 'no_instrument' | 'requires_approval';
+    /** First-party order id — the buyer sees the purchase in their AstraSync
+     * dashboard orders view (no public receipt page). */
+    orderId?: string;
+    /** Decline/failure taxonomy code (card_declined, insufficient_funds, …). */
+    failureCode?: string;
+}
+/**
+ * Request context for verification
+ */
+/**
+ * Caller metadata forwarded from the agent's original HTTP request so the
+ * endpoint owner can see the real agent-side fingerprint in activity views.
+ * Without this, IP/UA recorded on platform_events would be the counterparty
+ * server's (useless for endpoint-side forensics).
+ */
+interface CallerMetadata {
+    /** Agent-side source IP (honours X-Forwarded-For if set). */
+    sourceIp?: string;
+    /** Agent's User-Agent header. */
+    userAgent?: string;
+    /** Referer header (where the agent navigated from, if applicable). */
+    referer?: string;
+    /** Host the agent called (this counterparty's public hostname). */
+    host?: string;
+    /** Raw X-Forwarded-For chain for audit. */
+    forwardedFor?: string;
+    /** Published agent card URL, if the agent advertised one (future: from agent headers). */
+    agentCardUrl?: string;
+    /**
+     * The full sanitised view of the agent's inbound request headers + connection
+     * signals (maximal metadata capture: every signal legitimately visible on
+     * the wire is captured). Produced by `sanitizeHeaders` (genuine secrets
+     * removed, credential headers reduced to a safe format prefix). Forwarded so
+     * the endpoint owner sees every wire signal about the agent, not just IP/UA.
+     * Local string work only — kept OUT of the verify cache key so per-request
+     * maps don't defeat verdict caching.
+     */
+    observedMetadata?: ObservedMetadata;
+}
+interface VerificationRequest {
+    /** Agent credentials */
+    credentials: AgentCredentials;
+    /** Purpose of the access request */
+    purpose?: string;
+    /** Specific action being performed */
+    action?: string;
+    /** Type of resource being accessed */
+    resourceType?: string;
+    /** Specific resource identifier */
+    resource?: string;
+    /** Jurisdiction for the request */
+    jurisdiction?: string;
+    /**
+     * Transaction value in MAJOR units (dollars, euros, native token units —
+     * NOT cents/minor units). Diverges from Stripe (minor units). UCP/ACP
+     * extractors auto-convert from cents (÷100). x402 uses per-token decimals.
+     * See `transport/transaction-value.ts` for per-protocol normalization.
+     */
+    transactionValue?: number;
+    /** ISO-4217 currency code for transactionValue (e.g. 'USD', 'AUD', 'ETH'). Falls back to 'USD' server-side when unset. */
+    currency?: string;
+    /**
+     * 5.3.0 (astra-pay): checkout-leg discriminator. `'confirm'` marks the
+     * completing call of a checkout; first-party settlement (charge-at-redeem
+     * on the owner's saved instrument) fires ONLY on this leg. Quote/browse
+     * legs omit it (or send `'quote'`) — they must never move money.
+     */
+    commercePhase?: 'quote' | 'confirm';
+    /**
+     * 5.3.0 (astra-pay): per-cart idempotency key (the checkout session id),
+     * forwarded on the confirm leg. Two concurrent confirms carrying the same
+     * key charge the owner's card at most once. Omit for raw one-shot confirms.
+     */
+    checkoutSessionId?: string;
+    /**
+     * 5.3.0 (astra-pay): the checkout's authoritative line items, forwarded on
+     * the confirm leg for the ORDER plane (receipts + digital-goods fulfillment
+     * email). Informational — never the money authority (that remains
+     * `transactionValue` bound into the settlement voucher).
+     */
+    checkoutItems?: Array<{
+        sku: string;
+        quantity: number;
+        title?: string;
+        unitPrice?: {
+            amount: string;
+            currency: string;
+        };
+    }>;
+    /** Whether this is a sub-agent request */
+    isSubAgentRequest?: boolean;
+    /** Parent agent ID for sub-agent requests */
+    parentAgentId?: string;
+    /** Depth of sub-agent chain */
+    subAgentDepth?: number;
+    /** Client IP address (deprecated — use callerMetadata.sourceIp) */
+    clientIp?: string;
+    /** User agent string (deprecated — use callerMetadata.userAgent) */
+    userAgent?: string;
+    /**
+     * Forwarded request metadata from the agent's original call.
+     * When the SDK is embedded in a counterparty server, these describe
+     * the agent-side fingerprint — not the counterparty server itself.
+     * The express/nextjs adapters auto-populate these from `req`.
+     */
+    callerMetadata?: CallerMetadata;
+    /** Enable runtime challenge for this request */
+    enableRuntimeChallenge?: boolean;
+    /** Create a verification session (returns sessionId) */
+    createSession?: boolean;
+    /** Counterparty type */
+    counterpartyType?: CounterpartyType;
+    /** Counterparty URL */
+    counterpartyUrl?: string;
+    /** Requested session duration in seconds (from agent's X-Astra-Duration header) */
+    durationRequired?: number;
+    /** Runtime challenge options */
+    runtimeChallengeOptions?: {
+        timeoutOverride?: number;
+    };
+    /**
+     * Transport protocol marker. Set by the MCP middleware
+     * to `'mcp'`; non-MCP callers leave it unset (server treats as `'rest'`).
+     * Separates "how did the call arrive" from "what does the agent want"
+     * (`purpose`). Stored on platform_events.eventData for activity-feed
+     * visibility into transport-vs-intent.
+     */
+    invocationProtocol?: 'rest' | 'mcp' | 'a2a' | 'acp' | 'ap2' | 'mpp' | 'ucp';
+    /**
+     * 3.9.0 — raw commerce-protocol artifacts forwarded verbatim
+     * to verify-access, whose commerce pipeline runs the full
+     * cryptographic verification SERVER-side and persists commerce_context on
+     * the session. Adapters forward artifacts, they never verify them locally
+     * (verify-access is the sole verification sink, so every decision is
+     * recorded once, with events). Shape mirrors the backend's
+     * `commerceArtifacts` schema 1:1.
+     */
+    commerceArtifacts?: CommerceArtifactsPayload;
+    /**
+     * 3.12.0 — attempt-chain handle correlating the
+     * multi-call commerce funnel (catalog → intent → settlement) into ONE
+     * attempt. Format `att_` + 32 lowercase hex. Optional: the server mints one
+     * when absent and echoes it top-level on every response branch either way.
+     * Observational pass-through — never affects the verdict, so it's excluded
+     * from the verify cache key.
+     */
+    attemptId?: string;
+    /**
+     * 3.12.0 — first-party observational data: the
+     * offers the agent evaluated at this checkpoint (catalog browse / intent
+     * selection). Forwarded verbatim to verify-access; never affects the
+     * verdict (also excluded from the cache key).
+     */
+    considerationSet?: ConsiderationSet;
+}
+/**
+ * One offer the agent evaluated. Mirrors the
+ * backend's `considerationItemSchema` 1:1 — first-party observational data
+ * reported by the transport (bridge / adapters), never verified locally.
+ */
+interface ConsiderationItem {
+    /** SKU identifier as the merchant catalog publishes it (1–128 chars). */
+    sku: string;
+    /** Display title (≤256 chars). */
+    name?: string;
+    /** Price in MAJOR units (same convention as `transactionValue`), non-negative. */
+    price?: number;
+    /** ISO-4217 or settlement-asset code (3–6 alphanumeric chars). */
+    currency?: string;
+    /** Stock state as the catalog declared it; omit when the catalog didn't say. */
+    availability?: 'in_stock' | 'out_of_stock' | 'preorder' | 'unknown';
+    /** True when the agent selected this offer (intent/settlement checkpoints). */
+    chosen?: boolean;
+    /** Why an evaluated-but-unchosen offer lost, when the agent can say. */
+    notChosenReason?: 'price' | 'policy' | 'trust_threshold' | 'stock' | 'other';
+}
+/**
+ * The set of offers evaluated at one funnel checkpoint.
+ * Mirrors the backend's `considerationSetSchema` 1:1.
+ *
+ * `items` is capped at 50 server-side — reporters MUST order chosen items
+ * FIRST so purchased counts survive truncation; `totalEvaluated` carries the
+ * true pre-cap count and `truncated` flags that the cap was applied.
+ */
+interface ConsiderationSet {
+    /** Funnel checkpoint this set was observed at. */
+    checkpoint?: 'catalog' | 'intent' | 'settlement';
+    /** Offers evaluated (max 50; chosen-first ordering under the cap). */
+    items: ConsiderationItem[];
+    /** True evaluated count — survives the 50-item cap. */
+    totalEvaluated?: number;
+    /** True when `items` was truncated to the cap. */
+    truncated?: boolean;
+}
+/**
+ * Terminal (or notable) outcome of an attempt chain, reported post-hoc via
+ * `reportAttempt`. Mirrors the backend's `attemptReportSchema.outcome` 1:1.
+ */
+interface AttemptOutcome {
+    kind: 'settled' | 'blocked_step_up' | 'failed' | 'high_value_action';
+    /** Dotted ACTION-axis token for the failure class, e.g. `commerce.catalog.sku_not_found` (≤128 chars). */
+    dimension?: string;
+    /** Human-readable detail (≤512 chars). */
+    reason?: string;
+    /** For `high_value_action`: the non-payment conversion type. */
+    actionType?: 'lead' | 'signup' | 'application' | 'enquiry';
+    /** Value in MAJOR units (settled amount / estimated action value), non-negative. */
+    value?: number;
+    /** ISO-4217 or settlement-asset code (3–6 alphanumeric chars). */
+    currency?: string;
+    /** Settlement rail / mandate type, e.g. `ap2.payment_mandate` (≤64 chars). */
+    rail?: string;
+}
+/**
+ * Body for `POST /agents/verify-access/attempt-report`:
+ * post-hoc consideration/outcome data for an attempt chain that a
+ * verify-access call couldn't carry (e.g. the catalog was served from a local
+ * cache, or the deny happened transport-side). Must carry `considerationSet`
+ * and/or `outcome`.
+ */
+interface AttemptReport {
+    /** Attempt-chain handle — `att_` + 32 lowercase hex. */
+    attemptId: string;
+    /** Merchant/endpoint the attempt targeted; falls back to `config.counterpartyId`. */
+    counterpartyId?: string;
+    /** Canonical ASTRA-* id of the acting agent, when known. */
+    agentId?: string;
+    considerationSet?: ConsiderationSet;
+    outcome?: AttemptOutcome;
+}
+/**
+ * Raw commerce-protocol artifacts as verify-access accepts them (backend
+ * `validation.ts` → `commerceArtifacts`). All optional; send what was
+ * detected on the wire.
+ */
+interface CommerceArtifactsPayload {
+    /** Compact VI SD-JWT. */
+    viSdJwt?: string;
+    /** AP2 mandate triple as compact SD-JWTs. */
+    ap2Mandates?: {
+        intent?: string;
+        cart?: string;
+        payment?: string;
+    };
+    /** RFC 9421 signed request (Agent Pay / TAP / Web Bot Auth). */
+    rfc9421?: {
+        headers: Record<string, string | string[]>;
+        method: string;
+        url: string;
+        body?: string;
+        tag?: string;
+    };
+    /** UCP checkout session request. */
+    ucpRequest?: {
+        method: string;
+        url: string;
+        body?: unknown;
+    };
+    /** ACP request (HMAC-signed webhook or checkout body). */
+    acpRequest?: {
+        method: string;
+        url: string;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+        rawBody?: string;
+    };
+    mppRequest?: {
+        method: string;
+        url: string;
+        headers: Record<string, string | string[]>;
+        body?: unknown;
+        rawBody?: string;
+    };
+    mppResponse?: {
+        status: number;
+        headers: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    x402Request?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    x402Response?: {
+        status?: number;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    stripeWebhook?: {
+        payload: string;
+        signatureHeader: string;
+        secret: string;
+    };
+}
+/**
+ * Route-specific access configuration
+ */
+interface RouteAccessConfig {
+    /** Route pattern (supports wildcards) */
+    pattern: string;
+    /** HTTP method (or * for all) */
+    method: string | '*';
+    /**
+     * Pass this route through unenforced (observe). The middleware skips gating
+     * on the server decision; with `evaluateAlwaysIfCredentialed` set it still
+     * calls verify-access for the audit trail and populates `req.agentVerification`.
+     * Replaces the old `minAccessLevel: 'none'` sentinel (SDK 5.0.0).
+     */
+    observe?: boolean;
+    /** Minimum trust score required (optional) */
+    minTrustScore?: number;
+    /** Required purposes (optional, agent must declare one of these) */
+    requiredPurposes?: string[];
+    /** Counterparty-defined PDLSS maximums — agent requests exceeding these are rejected before calling AstraSync */
+    /** Maximum session duration in seconds the counterparty will allow */
+    maxDuration?: number;
+    /** Whitelist of allowed purposes — agent's declared purpose must be in this list */
+    allowedPurposes?: string[];
+    /** Whitelist of allowed jurisdictions */
+    allowedJurisdictions?: string[];
+    /** Maximum transaction value for this route */
+    maxTransactionValue?: number;
+    /**
+     * Backend-evaluator strict mode: when true AND
+     * `allowedPurposes` is non-empty, verify-access denies requests arriving
+     * WITHOUT a purpose. Configured in the dashboard; passed through here.
+     */
+    requirePurpose?: boolean;
+    /**
+     * SEND-mapping — not an allow-list: the PDLSS tokens the
+     * middleware STAMPS on verify-access calls matching this route, replacing
+     * the generic `data`/`data.*` method-table fallback. `purpose` = bare
+     * category noun (`shopping`, `trading`); `action` = dotted verb
+     * (`shopping.search`, `trading.execute`). Authoritative over agent-supplied
+     * headers — the dashboard is merchant policy, the way MCP toolGates are.
+     */
+    purpose?: string;
+    action?: string;
+}
+/**
+ * Express middleware options.
+ *
+ * v2.9.7 removed the `routes` field — per-route policy now lives in the
+ * AstraSync dashboard (gated by team.role admin auth + audit + alerts).
+ * The middleware fetches routes from the backend via
+ * `GET /endpoints/:counterpartyId/routes` on init and refreshes
+ * periodically (override interval via `routesRefreshMs`). Set
+ * `counterpartyId` on `GatewayConfig` so the middleware knows which
+ * endpoint to fetch policy for; without it, the middleware logs a warning
+ * and falls through (allows all) — useful for local dev only.
+ */
+interface ExpressMiddlewareOptions extends GatewayConfig {
+    /** Function to extract credentials from request */
+    extractCredentials?: (req: unknown) => AgentCredentials;
+    /** Function to extract purpose from request */
+    extractPurpose?: (req: unknown) => string | undefined;
+    /**
+     * Function to extract the PDLSS action from a request — symmetric with
+     * `extractPurpose` (previously the action axis had no override and
+     * hardwired the HTTP verb). When configured it masks the
+     * `X-Astra-Action` header step; returning undefined falls through to the
+     * pinned method→action table (GET→data.read, POST/PUT/PATCH→data.write,
+     * DELETE→data.delete). Dashboard route mapping still outranks it.
+     */
+    extractAction?: (req: unknown) => string | undefined;
+    /**
+     * Optional extractor for the transaction value from the incoming request.
+     * Must return the value in MAJOR units (dollars, euros — NOT cents/minor
+     * units). This diverges from Stripe and most payment rails which use minor
+     * units. If your source is in minor units (cents), divide by 100 before
+     * returning.
+     *
+     * When configured, the extracted value and currency are forwarded to
+     * verify-access so PDLSS limit evaluation runs at middleware time.
+     *
+     * NOTE: this is opt-in upfront enforcement. `authorizeSettlement()` remains
+     * the REQUIRED fail-closed settlement gate at settlement time.
+     */
+    extractTransactionValue?: (req: unknown) => {
+        value: number;
+        currency: string;
+    } | undefined;
+    /** Skip verification for certain paths */
+    skipPaths?: string[];
+    /** Custom response for denied requests */
+    onDenied?: (result: VerificationResult, req: unknown, res: unknown) => void;
+    /** Automatically create sessions and record grant/deny decisions (default: true) */
+    recordDecisions?: boolean;
+    /** Enable runtime challenge for all verify-access calls (default: true) */
+    enableRuntimeChallenge?: boolean;
+    /**
+     * Refresh interval (ms) for the remote-fetched route policy. Default:
+     * 5 minutes. Operators can shorten this to test policy edits faster, or
+     * lengthen it to reduce network chatter.
+     */
+    routesRefreshMs?: number;
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * Small-value demo merchants can keep `'open'` indefinitely after the
+     * default flip by setting this explicitly.
+     */
+    failOnError?: 'open' | 'closed';
+    /**
+     * When true, route-pattern matching is case-insensitive. Default false in
+     * SDK 2.4.13 for backward compatibility; shadow logs record divergences so
+     * merchants can preview impact before flipping. A follow-up release makes
+     * case-insensitive the default once observation confirms merchants are
+     * unaffected.
+     *
+     * Recommended: set to true if your Express install uses the default
+     * (case-insensitive) routing AND your policy entries don't deliberately
+     * use case distinctions.
+     */
+    caseInsensitiveRouteMatch?: boolean;
+    /**
+     * Emit a fire-and-forget beacon for bot- and agent-shaped traffic that
+     * passes through UNGATED (no dashboard route matches the path, or the
+     * matching route is gated at `none`), so the endpoint's dashboard sees
+     * anonymous agent traffic the gate never evaluates. Human traffic and
+     * static assets are never beaconed; platform-fingerprinted agents always
+     * beacon; other non-browser traffic is sampled at the dashboard-configured
+     * `sampling.anonymousBeaconRate` (set the rate to 0 in the dashboard to
+     * stop sampling). The beacon is never awaited on the request path and adds
+     * no latency. Requires `counterpartyId`. Default true; set false to
+     * disable the beacon and its config fetch entirely.
+     */
+    anonymousBeacon?: boolean;
+    /**
+     * Trust a fresh `X-Astra-Verified-Hop` marker from an upstream AstraSync
+     * hop (edge gateway at authenticate/authorize depth, or an MCP outer hop)
+     * and skip the duplicate verify-access call when the marker matches the
+     * presented `X-Astra-Id` and is within the freshness window. The marker is
+     * an UNSIGNED dedupe advisory — enable only when every network path to
+     * this middleware crosses a stripping gateway or equivalent trusted
+     * boundary. Default false. No `req.agentVerification` is populated on a
+     * hop-skip (same contract as the MCP adapter).
+     */
+    trustVerifiedHop?: boolean;
+    /** Acceptable `X-Astra-Verified-Hop` age in ms (default 60 000). */
+    verifiedHopMaxAgeMs?: number;
+}
+/**
+ * Next.js middleware options.
+ *
+ * v2.9.7 removed the `routes` field — see `ExpressMiddlewareOptions` for
+ * the rationale. Same fetch-from-backend model applies here.
+ */
+interface NextJsMiddlewareOptions extends GatewayConfig {
+    /** Paths to skip verification */
+    skipPaths?: string[];
+    /**
+     * Trust a fresh `X-Astra-Verified-Hop` marker from an upstream AstraSync
+     * hop and skip the duplicate verify-access call — see
+     * `ExpressMiddlewareOptions.trustVerifiedHop` for the trust model.
+     * Default false.
+     */
+    trustVerifiedHop?: boolean;
+    /** Acceptable `X-Astra-Verified-Hop` age in ms (default 60 000). */
+    verifiedHopMaxAgeMs?: number;
+    /** Refresh interval (ms) for the remote-fetched route policy. Default: 5 minutes. */
+    routesRefreshMs?: number;
+    /**
+     * Whether to show the verification interstitial (the HTML overlay served to
+     * unverified web-page traffic). Default true. Takes precedence over the
+     * deprecated `showCommerceShield` when both are set.
+     */
+    showInterstitial?: boolean;
+    /** @deprecated Renamed in 4.1.0 — use `showInterstitial`. Alias removed next major. */
+    showCommerceShield?: boolean;
+    /** Verification interstitial configuration */
+    commerceShield?: {
+        title?: string;
+        message?: string;
+        allowGuestAccess?: boolean;
+    };
+    /** Enable runtime challenge for all verify-access calls (default: true) */
+    enableRuntimeChallenge?: boolean;
+    /**
+     * Emit a fire-and-forget beacon for bot- and agent-shaped traffic that
+     * passes through ungated — same semantics as the express option of the
+     * same name (see `ExpressMiddlewareOptions.anonymousBeacon`). Default
+     * true; set false to disable entirely.
+     */
+    anonymousBeacon?: boolean;
+}
+/**
+ * SDK function options
+ */
+interface SDKOptions extends GatewayConfig {
+    /** Timeout for verification requests (ms) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+}
+/**
+ * Token guidance returned from verify-access.
+ *
+ * `recommendedRateLimit` carries `requestsPerMinute` and `currency` only.
+ * `maxTransactionValue` was removed in v2.2.4 — it leaked the agent's
+ * spending headroom to the merchant, which is a price-discrimination signal
+ * (a merchant could see the agent's autonomous threshold and price the
+ * transaction just under it to capture surplus). The agent's SDK receives
+ * its own limits separately for client-side budgeting; the merchant's
+ * decision doesn't need amount info.
+ */
+interface TokenGuidance {
+    recommendedScopes: string[];
+    recommendedTtlSeconds: number;
+    recommendedRateLimit?: {
+        requestsPerMinute: number;
+        currency?: string;
+    };
+    jurisdictionConstraints?: string[];
+    delegationAllowed: boolean;
+    maxDelegationDepth?: number;
+    safetyDefaults: {
+        writePrivilegesRequested: boolean;
+        shortLivedTokenRecommended: boolean;
+        scopeConvention: 'astrasync-canonical';
+    };
+}
+/**
+ * Runtime challenge result
+ */
+interface RuntimeChallengeResult {
+    status: 'passed' | 'failed' | 'skipped' | 'timeout' | 'not_supported';
+    challengeId?: string;
+    challengeSentAt?: string;
+    responseReceivedAt?: string;
+    latencyMs?: number;
+    reason?: string;
+}
+/**
+ * Enhanced verification result (extends existing VerificationResult).
+ *
+ * - `appliedPolicy`: surfaces the boundary name + policy version that drove
+ *   the decision (no UUIDs).
+ * - `verificationContext`: structured "why" for the merchant — see
+ *   `VerificationContext` for the full shape.
+ */
+interface EnhancedVerificationResult extends VerificationResult {
+    sessionId?: string;
+    runtimeChallenge?: RuntimeChallengeResult;
+    tokenGuidance?: TokenGuidance;
+    appliedPolicy?: AppliedPolicy;
+    verificationContext?: VerificationContext;
+    recommendation?: 'grant' | 'deny' | 'step_up_required' | 'audit';
+    recommendationReasons?: string[];
+    /**
+     * v2.3.8: when an endpoint's `unverifiedAgentPolicy` is `'audit'`, the
+     * server returns the warning header to relay to the merchant's response.
+     * The Express + MCP middleware lift this into `res.setHeader(name, value)`
+     * before calling `next()`. Distinct vocabulary from the PDLSS-scope
+     * outbound `unverifiedCounterpartyPolicy: 'warn'` so raw JSON config can't
+     * conflate the two.
+     */
+    warningHeader?: {
+        name: string;
+        value: string;
+    };
+}
+/**
+ * Cross-protocol credential config
+ */
+interface AstraSyncCredentials {
+    agentId: string;
+    verifyUrl?: string;
+    challengeUrl?: string;
+    pdlss?: {
+        purpose?: {
+            category: string;
+            action?: string;
+        };
+        duration?: {
+            maxSessionDuration?: number;
+        };
+        scope?: {
+            jurisdiction?: string;
+        };
+    };
+}
+/**
+ * Protocol transport type
+ */
+type ProtocolTransport = 'http' | 'a2a' | 'mcp';
+/**
+ * Verification interstitial UI props (the React overlay shown to unverified
+ * agents; user-visible title stays "AstraSync Agent Verification").
+ */
+interface VerificationInterstitialProps {
+    /** Whether the interstitial is visible */
+    visible: boolean;
+    /** Verification result (if any) */
+    result?: VerificationResult;
+    /** Callback when user chooses to register */
+    onRegister?: () => void;
+    /** Callback when user chooses guest access */
+    onGuestAccess?: () => void;
+    /** Callback when user dismisses */
+    onDismiss?: () => void;
+    /** Custom title */
+    title?: string;
+    /** Custom message */
+    message?: string;
+    /** Whether guest access is allowed */
+    allowGuestAccess?: boolean;
+    /** Custom styles */
+    className?: string;
+}
+/** @deprecated Renamed VerificationInterstitialProps in 4.1.0; alias removed next major. */
+type CommerceShieldProps = VerificationInterstitialProps;
+
+/**
+ * AstraSync Universal Verification Gateway — Trust Level helpers.
+ *
+ * SDK 5.0.0: the `accessLevel` band (`none`/`restricted`/`read-only`/`standard`/
+ * `full`/`internal`) was removed entirely — it never gated the access decision
+ * (the server does, from a verified ID + runtime challenge + PDLSS match + trust
+ * score). What remains here is the coarse trust-level badge derived from the
+ * numeric trust score, used only for display.
+ */
+
+/**
+ * Trust level score ranges
+ */
+declare const TRUST_LEVEL_RANGES: Record<TrustLevel, {
+    min: number;
+    max: number;
+}>;
+/**
+ * Determine trust level from score
+ */
+declare function getTrustLevel(score: number): TrustLevel;
+
+/**
+ * AstraSync Universal Verification Gateway - Core Verification Logic
+ *
+ * This module handles the core verification logic, calling the AstraSync API
+ * and processing the response into a standardized VerificationResult.
+ */
+
+/**
+ * Clear the verification cache
+ */
+declare function clearCache(): void;
+/**
+ * Extract agent credentials from various sources
+ */
+declare function extractCredentials(headers: Record<string, string | string[] | undefined>, query?: Record<string, string | undefined>): AgentCredentials;
+/**
+ * Check if credentials are present
+ */
+declare function hasCredentials(credentials: AgentCredentials): boolean;
+/**
+ * Options for a single verify() call (as opposed to GatewayConfig, which is
+ * per-gateway). Mirrors the Java SDK's `verify(request, bypassCache)`.
+ */
+interface VerifyOptions {
+    /**
+     * Skip the cache READ for this call so the request is guaranteed to reach
+     * the backend (the result is still written to the cache if cacheable).
+     * Used by the step-up hold-and-poll retry: the re-verify after an approval
+     * must hit the server to redeem the single-use approval.
+     */
+    bypassCache?: boolean;
+}
+/**
+ * Main verification function
+ */
+declare function verify(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Report post-hoc consideration/outcome data for an attempt chain (Trust
+ * Record). Use when the signal never reached verify-access: a
+ * catalog served from a local cache, a transport-side deny (sku not found,
+ * over budget), or a terminal outcome (settled / blocked on step-up).
+ * Authenticated with the same credentials as verify(); the backend responds
+ * 202 and folds the data into the attempt chain keyed by `attemptId`.
+ *
+ * Fire-and-forget — errors are silently swallowed, never throws.
+ */
+declare function reportAttempt(config: GatewayConfig, report: AttemptReport): Promise<void>;
+/**
+ * Fetch the per-route policy for an endpoint from the AstraSync backend.
+ * v2.9.7 moved policy authority into the dashboard — the SDK no longer
+ * accepts `routes` from merchant-side source code, it fetches them from
+ * here on init (and refreshes periodically).
+ *
+ * Returns `null` when the request fails for any reason — the caller decides
+ * how to fall back (the middleware allows-all when no policy is loaded so
+ * a misconfigured init doesn't take down the merchant's API).
+ */
+declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): 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 {
+    pattern: string;
+    method: string;
+    /** Pass through unenforced (observe). Replaces `minAccessLevel: 'none'`. */
+    observe?: boolean;
+    minTrustScore?: number;
+    requiredPurposes?: string[];
+    allowedPurposes?: string[];
+    allowedJurisdictions?: string[];
+    maxDuration?: number;
+    maxTransactionValue?: number;
+    requirePurpose?: boolean;
+    /** Send-mapping — see RouteAccessConfig in types.ts. */
+    purpose?: string;
+    action?: string;
+}
+/**
+ * Report an unregistered agent attempt (no AstraSync credentials).
+ * Called by SDK adapters when an agent is redirected to /docs/agent-access.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function reportUnregisteredAttempt(config: GatewayConfig, data: {
+    /**
+     * 3.6.0: optional — the backend attributes by counterpartyId first (sent
+     * from config below) and requires at least ONE of counterpartyId/URL.
+     * A null/undefined URL is omitted from the body, not sent as null.
+     */
+    counterpartyUrl?: string;
+    counterpartyType?: string;
+    sourceIp?: string;
+    userAgent?: string;
+    requestPath?: string;
+    requestMethod?: string;
+    /**
+     * 3.9.0 — edge-adapter evidence fields, persisted into the
+     * event's eventData by the backend: `protocol` = detected transport/
+     * credential protocol; `evidence` = light crypto-free detection detail.
+     */
+    protocol?: string;
+    evidence?: Record<string, unknown>;
+    /**
+     * Maximal metadata capture — the full sanitised metadata for an
+     * unregistered caller (every signal legitimately visible on the wire).
+     * Persisted into eventData; feeds platform attribution and (via
+     * correlationId) registration auto-fill. Fire-and-forget, so free.
+     */
+    observedMetadata?: ObservedMetadata;
+}): Promise<void>;
+/**
+ * Quick verification — checks credentials and policy in one call.
+ *
+ * The return shape mirrors `VerificationResult`'s split — partners
+ * writing custom handlers around `quickVerify` get the same identity/policy
+ * distinction as those calling `verify()` directly. Map to HTTP status the
+ * same way: `!identityVerified` → 401; `identityVerified && !policyAllowed`
+ * → 403.
+ */
+declare function quickVerify(config: GatewayConfig, credentials: AgentCredentials): Promise<{
+    identityVerified: boolean;
+    policyAllowed: boolean;
+    reason?: string;
+}>;
 
 /**
  * Step-up hold-and-poll (3.6.0) — the synchronous half of the MFA-style gate,
@@ -98,38 +1528,3072 @@ interface SettlementDecision {
 declare function authorizeSettlement(config: GatewayConfig, req: SettlementRequest): Promise<SettlementDecision>;
 
 /**
- * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
+ * AstraSync Universal Verification Gateway - Express Middleware
  *
- * Fire-and-forget pre-fetch at middleware creation; first verify() awaits
- * the in-flight promise if it hasn't resolved. 60-minute TTL with
- * stale-while-revalidate background refresh.
+ * Express.js middleware for verifying AI agents on API endpoints.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createMiddleware } from '@astrasyncai/verification-gateway/express';
+ *
+ * const app = express();
+ *
+ * app.use(createMiddleware({
+ *   apiBaseUrl: 'https://astrasync.ai/api',
+ *   apiKey: process.env.ASTRASYNC_API_KEY,
+ *   counterpartyId: 'ASTRAE-...', // your registered endpoint id
+ * }));
+ * ```
+ *
+ * Per-route policy (which paths are gated, trust floors, PDLSS purposes) is
+ * configured in the AstraSync dashboard, not in code — the middleware
+ * fetches it automatically on init and refreshes periodically. There is no
+ * `routes` option; a `routes` key in the config object is ignored (with a
+ * warning) since v2.9.7.
  */
-interface WellKnownAgenticCommerce {
-    registrationUrl: string;
-    documentationUrl: string;
-    verifyAccessUrl: string;
-    /** 5.1.0: hosted AstraSync MCP bridge endpoint (absent on self-hosted backends). */
-    mcpEndpoint?: string;
-    /** 5.1.0: bridge connector-discovery doc (absent on self-hosted backends). */
-    mcpDiscoveryUrl?: string;
+
+/**
+ * Extend Express Request with verification result
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            agentVerification?: VerificationResult;
+        }
+    }
 }
 /**
- * Start a background fetch. Returns the promise for callers that need
- * to await it (first verify() call).
+ * Extract extended AstraSync credentials (X-Astra-* headers) from Express request.
+ * Returns null if no AstraSync headers are present.
  */
-declare function prefetchWellKnown(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+declare function extractAstraSyncCredentials(req: Request): AstraSyncCredentials | null;
 /**
- * Get cached well-known URLs. If stale, triggers a background refresh
- * and returns stale data (stale-while-revalidate). If no cache exists,
- * awaits the in-flight fetch or starts a new one.
+ * Create Express middleware for agent verification.
+ *
+ * v2.9.7 moved per-route policy authority out of merchant-side source code
+ * into the AstraSync dashboard. `createMiddleware` no longer accepts a
+ * `routes` array — it fetches the endpoint's stored policy via
+ * `GET /endpoints/:counterpartyId/routes` on init and refreshes
+ * periodically. Policy edits in the dashboard take effect on the next
+ * refresh (or sooner if the operator manually restarts the SDK).
+ *
+ * `counterpartyId` is required: the SDK can't know which endpoint's policy
+ * to fetch without it. Local-development workflows that don't have an
+ * AstraSync endpoint registered can omit it — the middleware logs a
+ * one-time warning and falls through (allows all) until a policy is
+ * fetchable.
  */
-declare function getWellKnownUrls(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+declare function createMiddleware$1(options: ExpressMiddlewareOptions): RequestHandler;
+
+declare const express_extractAstraSyncCredentials: typeof extractAstraSyncCredentials;
+declare namespace express {
+  export { createMiddleware$1 as createMiddleware, express_extractAstraSyncCredentials as extractAstraSyncCredentials };
+}
+
 /**
- * Synchronous cache read — returns cached URLs or undefined.
- * Never triggers a fetch. Used by verify() to avoid extra HTTP calls
- * in the hot path; adapters are responsible for prefetching.
+ * Create Next.js middleware for agent verification.
+ *
+ * v2.9.7 moved per-route policy out of merchant-side source code into the
+ * AstraSync dashboard. The middleware fetches its routes from the backend
+ * via `GET /endpoints/:counterpartyId/routes` on init and refreshes
+ * periodically — see `ExpressMiddlewareOptions` for the rationale (a dual
+ * config source silently conflicts with dashboard policy).
  */
-declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCommerce | undefined;
+declare function createMiddleware(options: NextJsMiddlewareOptions): (request: NextRequest) => Promise<next_server.NextResponse<unknown>>;
+/**
+ * Helper to create matcher config
+ */
+declare function createMatcherConfig(paths: string[]): {
+    matcher: string[];
+};
+
+declare const nextjs_createMatcherConfig: typeof createMatcherConfig;
+declare const nextjs_createMiddleware: typeof createMiddleware;
+declare namespace nextjs {
+  export { nextjs_createMatcherConfig as createMatcherConfig, nextjs_createMiddleware as createMiddleware };
+}
+
+/**
+ * AstraSync Universal Verification Gateway - SDK Adapter
+ *
+ * Direct SDK for verifying agents in any JavaScript/TypeScript environment.
+ * Useful for agent-to-agent verification, serverless functions, or custom integrations.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@astrasyncai/verification-gateway/sdk';
+ *
+ * const gateway = createClient({
+ *   apiBaseUrl: 'https://astrasync.ai/api',
+ * });
+ *
+ * // Verify another agent before interacting
+ * const result = await gateway.verify({
+ *   astraId: 'ASTRA-abc123',
+ *   purpose: 'data-exchange',
+ * });
+ *
+ * if (result.identityVerified && result.policyAllowed) {
+ *   // Safe to interact with this agent
+ * }
+ * ```
+ */
+
+/**
+ * Verification Gateway SDK Client
+ */
+declare class VerificationGatewayClient {
+    private config;
+    private timeout;
+    private retryConfig;
+    constructor(options: SDKOptions);
+    /**
+     * Full verification with all details
+     */
+    verify(options: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+        purpose?: string;
+        action?: string;
+        resourceType?: string;
+        resource?: string;
+        jurisdiction?: string;
+        transactionValue?: number;
+        currency?: string;
+        isSubAgentRequest?: boolean;
+        parentAgentId?: string;
+        subAgentDepth?: number;
+        counterpartyUrl?: string;
+        counterpartyType?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
+     * first-party charge-at-redeem (server-side settlement on the owner's saved
+     * instrument). This is the supported public surface for the confirm leg;
+     * `verify()` deliberately does not expose the checkout fields, so settlement
+     * can never fire by accident from a generic verify.
+     *
+     * Sends `commercePhase: 'confirm'` plus the checkout session id (per-cart
+     * idempotency) and line items (order/receipt plane), and identifies the
+     * merchant via `counterpartyUrl`/`counterpartyType` (required — the backend
+     * only settles a merchant-mediated grant against a first-party storefront).
+     * `purpose`/`action` default to the canonical shopping pair.
+     *
+     * Returns the full `VerificationResult`: read `.settlementOutcome` for the
+     * settled/failed/requires_action/no_instrument outcome (+ `orderId`), and the
+     * identity/policy/`failures` fields for a denial. On any non-`confirm`/first-
+     * party path `settlementOutcome` is simply absent — no money moves.
+     */
+    confirmCheckout(options: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+        purpose?: string;
+        action?: string;
+        transactionValue?: number;
+        currency?: string;
+        checkoutSessionId?: string;
+        checkoutItems?: VerificationRequest['checkoutItems'];
+        counterpartyUrl?: string;
+        counterpartyType?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Quick verification — checks credentials and policy in one call.
+     *
+     * The return shape mirrors `VerificationResult`'s identity/policy
+     * split. Map to HTTP status the same way: `!identityVerified` → 401,
+     * `identityVerified && !policyAllowed` → 403.
+     */
+    quickVerify(credentials: {
+        astraId?: string;
+        apiKey?: string;
+        jwt?: string;
+    }): Promise<{
+        identityVerified: boolean;
+        policyAllowed: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Verify a specific ASTRA-ID
+     */
+    verifyAstraId(astraId: string, options?: {
+        purpose?: string;
+        action?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Verify using an API key
+     */
+    verifyApiKey(apiKey: string, options?: {
+        purpose?: string;
+        action?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Clear the verification cache
+     */
+    clearCache(): void;
+    /**
+     * Execute a function with retry logic
+     */
+    private executeWithRetry;
+}
+/**
+ * Create a new SDK client
+ */
+declare function createClient(options: SDKOptions): VerificationGatewayClient;
+/**
+ * One-shot verification without creating a client
+ */
+declare function verifyOnce(options: SDKOptions & {
+    astraId?: string;
+    apiKey?: string;
+    jwt?: string;
+    purpose?: string;
+    action?: string;
+}): Promise<VerificationResult>;
+
+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 };
+}
+
+/**
+ * HTTP Transport Adapter
+ *
+ * Maps AstraSync credentials to/from HTTP headers (X-Astra-* convention).
+ */
+
+/**
+ * Inject AstraSync credentials into HTTP headers.
+ */
+declare function setHttpHeaders(headers: Record<string, string>, credentials: AstraSyncCredentials): Record<string, string>;
+/**
+ * Extract AstraSync credentials from HTTP headers.
+ */
+declare function extractHttpCredentials(headers: Record<string, string | string[] | undefined>): AstraSyncCredentials | null;
+
+/**
+ * A2A (Agent-to-Agent) Transport Adapter
+ *
+ * Maps AstraSync credentials to/from A2A task metadata.astrasync block.
+ */
+
+interface A2ATask {
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Add AstraSync credentials to an A2A task's metadata block.
+ */
+declare function setA2AMetadata(task: A2ATask, credentials: AstraSyncCredentials): A2ATask;
+/**
+ * Extract AstraSync credentials from an A2A task's metadata block.
+ */
+declare function extractA2ACredentials(task: A2ATask): AstraSyncCredentials | null;
+
+/**
+ * MCP (Model Context Protocol) Transport Adapter
+ *
+ * Maps AstraSync credentials to/from MCP params._meta.astrasync block.
+ */
+
+interface McpParams {
+    _meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Add AstraSync credentials to MCP params' _meta block.
+ */
+declare function setMcpMeta(params: McpParams, credentials: AstraSyncCredentials): McpParams;
+/**
+ * Extract AstraSync credentials from MCP params' _meta block.
+ */
+declare function extractMcpCredentials(params: McpParams): AstraSyncCredentials | null;
+
+/**
+ * Protocol request -> AstraSync PDLSS purpose category mapping.
+ *
+ * Commerce purpose mapping table, extended with MPP + x402
+ * entries (April 2026 protocol landscape).
+ */
+type CommercePurpose = 'commerce.checkout.create' | 'commerce.checkout.update' | 'commerce.checkout.confirm' | 'commerce.checkout.cancel' | 'commerce.payment.execute' | 'commerce.payment.stream' | 'commerce.delegation.intent' | 'commerce.delegation.checkout' | 'commerce.delegation.payment' | 'commerce.identity_probe' | 'commerce.browsing';
+declare function mapUCPRequestToPurpose(method: string, path: string): CommercePurpose | null;
+declare function mapACPRequestToPurpose(method: string, path: string): CommercePurpose | null;
+type AP2MandateType = 'intent_mandate' | 'cart_mandate' | 'payment_mandate';
+declare function mapAP2MandateToPurpose(mandateType: AP2MandateType): CommercePurpose;
+type VIMandateType = 'checkout' | 'payment' | 'checkout.open' | 'payment.open';
+declare function mapVIMandateToPurpose(mandateType: VIMandateType): CommercePurpose;
+type RFC9421Tag = 'browse' | 'purchase' | undefined;
+declare function mapRFC9421TagToPurpose(tag: RFC9421Tag): CommercePurpose;
+type MPPIntent = 'charge' | 'session';
+declare function mapMPPRequestToPurpose(intent: MPPIntent | undefined, amount: number | undefined): CommercePurpose;
+declare function mapX402RequestToPurpose(amount: number | undefined): CommercePurpose;
+/**
+ * Informational Stripe webhook events surfaced as trust signals on
+ * `CommerceContext.trustSignals` but NOT routed to a PDLSS purpose.
+ */
+declare const STRIPE_WEBHOOK_INFORMATIONAL_EVENTS: readonly ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.refunded", "checkout.session.completed", "customer.subscription.created"];
+type StripeWebhookInformationalEvent = (typeof STRIPE_WEBHOOK_INFORMATIONAL_EVENTS)[number];
+declare function isStripeWebhookInformational(eventType: string): boolean;
+
+/**
+ * Per-protocol transaction-value normalization.
+ *
+ * Each protocol encodes amount/currency differently. This module produces a
+ * uniform `TransactionValueContext` with `source` recording the extraction
+ * path so trace logs can show where the value came from.
+ *
+ * Amount unit: "major units" (dollars/euros/etc. for fiat; native unit for
+ * tokens — we do NOT convert across currencies). UCP/ACP totals are in
+ * cents, so we divide by 100. MPP/x402/VI pass through as declared.
+ */
+interface TransactionValueContext {
+    protocol: 'vi' | 'ap2' | 'ucp' | 'acp' | 'mpp' | 'x402' | 'agentpay' | 'tap';
+    amount: number;
+    currency: string;
+    source: string;
+    /** When true, the amount is in raw atomic/minor units and could NOT be
+     *  converted to major units (unknown token decimals). The limit engine
+     *  must fail-closed — never compare raw units against major-unit limits. */
+    rawUnits?: boolean;
+}
+declare function extractUCPTransactionValue(input: {
+    totals?: Array<{
+        type?: string;
+        amount?: number;
+        currency?: string;
+    }>;
+}): TransactionValueContext | null;
+declare function extractACPTransactionValue(input: {
+    totals?: Array<{
+        type?: string;
+        amount?: number;
+        currency?: string;
+    }>;
+}): TransactionValueContext | null;
+interface VIClaimsForValue {
+    constraints?: {
+        paymentAmount?: {
+            currency?: string;
+            min?: number;
+            max?: number;
+        };
+    };
+    l3aPaymentAmount?: {
+        currency?: string;
+        amount?: number;
+    };
+}
+declare function extractVITransactionValue(claims: VIClaimsForValue): TransactionValueContext | null;
+interface AP2PaymentMandateForValue {
+    payment_details_total?: {
+        amount?: {
+            value?: string | number;
+            currency?: string;
+        };
+    };
+}
+declare function extractAP2TransactionValue(mandate: AP2PaymentMandateForValue | undefined): TransactionValueContext | null;
+interface MPPChallengeForValue {
+    method?: string;
+    request?: {
+        amount?: number;
+        currency?: string;
+    } & Record<string, unknown>;
+}
+declare function extractMPPTransactionValue(challenge: MPPChallengeForValue): TransactionValueContext | null;
+interface X402RequestForValue {
+    maxAmountRequired?: number;
+    amount?: number;
+    asset?: string;
+    currency?: string;
+}
+declare function extractX402TransactionValue(req: X402RequestForValue): TransactionValueContext | null;
+
+/**
+ * RFC 9421 HTTP Message Signatures parser.
+ *
+ * Wraps `structured-headers` (transitive dep of http-message-signatures) to
+ * parse the Signature-Input and Signature Dictionary headers per RFC 9421
+ * Section 2.
+ *
+ * Produces structured metadata (kid, algorithm, covered components, tag,
+ * created/expires/nonce, signature bytes) without verifying the signature —
+ * verification lives in rfc9421-verify.ts.
+ *
+ * Shared by:
+ *  - Agent Pay (Mastercard) — kid resolves via Mastercard Agent Registry
+ *  - TAP (Visa) — kid resolves via Visa JWKS
+ *  - Web Bot Auth (generic transport substrate) — kid resolves via
+ *    /.well-known/http-message-signatures-directory
+ */
+interface RFC9421SignatureParams {
+    /** The label identifying the signature in the Dictionary header (e.g. "sig1"). */
+    label: string;
+    /** Key ID used to look up the verifying key in the relevant registry. */
+    kid: string;
+    /** Algorithm declared in the Signature-Input params (e.g. "ecdsa-p256-sha256", "ed25519"). */
+    alg?: string;
+    /** Covered components, in order, per RFC 9421 Section 2.1. */
+    covered: string[];
+    /** Base64url-encoded signature bytes extracted from the paired Signature header. */
+    signatureBase64: string;
+    /** Unix seconds when the signature was created. */
+    created?: number;
+    /** Unix seconds when the signature expires. */
+    expires?: number;
+    /** Nonce (opaque string) for replay protection. */
+    nonce?: string;
+    /** Tag parameter. For Agent Pay/TAP this is "browse" or "purchase"; undefined otherwise. */
+    tag?: 'browse' | 'purchase' | string;
+}
+interface ParsedRFC9421 {
+    signatures: RFC9421SignatureParams[];
+}
+/**
+ * Parse the RFC 9421 Signature-Input and Signature headers from a request or response.
+ * Returns all signatures present (a single message may carry multiple labelled signatures).
+ *
+ * Returns null if either header is missing or malformed.
+ */
+declare function parseRFC9421(headers: Record<string, string | string[] | undefined>): ParsedRFC9421 | null;
+
+type RegistryName = 'mastercard' | 'visa' | 'web-bot-auth';
+interface RegistryResolver {
+    readonly name: RegistryName;
+    resolve(kid: string, context?: ResolveContext): Promise<JWK | null>;
+}
+interface ResolveContext {
+    origin?: string;
+    algorithm?: string;
+}
+
+/**
+ * Shared nonce/signature replay-protection store for transport verifiers.
+ *
+ * Rationale: every transport-signature verifier (RFC9421, VI, AP2, ACP,
+ * MPP) validates a created/expires window, but without a seen-nonce
+ * cache any captured signed request can be replayed within the (default
+ * 300s, now tightened to 60s) tolerance window.
+ *
+ * This module ships a bounded in-memory LRU as the default. Production
+ * deployments with multi-pod horizontal scaling SHOULD pass a shared store
+ * (Redis-backed) via the verifier options to make replay protection global
+ * rather than per-pod.
+ *
+ * The store interface is intentionally minimal: a single `seen(key,
+ * expiresAt)` method that returns true iff the key was already recorded
+ * (i.e. caller should reject as a replay). Callers compose the key from
+ * whichever identifiers are unique to the signature (kid + nonce + sig
+ * digest, typically).
+ */
+interface NonceStore {
+    /**
+     * Record `key` as seen. Returns true iff the key was ALREADY present —
+     * i.e. caller should reject the request as a replay. Returns false on
+     * first sighting (caller should proceed).
+     *
+     * `expiresAtMs` is a hint for the store to evict entries that can no
+     * longer cause harm (their signature window has elapsed).
+     */
+    seen(key: string, expiresAtMs: number): boolean;
+}
+
+/**
+ * RFC 9421 HTTP Message Signatures verification.
+ *
+ * Wraps http-message-signatures (dhensby) verifyMessage() with a RegistryResolver
+ * hook for kid → JWK lookup. Library handles canonicalization + ES256/EdDSA/
+ * HMAC/RSA verification; we supply the key-finding callback and policy around
+ * clock skew.
+ *
+ * Shared by:
+ *  - Agent Pay (Mastercard) — resolver = createMastercardRegistry
+ *  - TAP (Visa) — resolver = createVisaRegistry
+ *  - Web Bot Auth (generic) — resolver = createWebBotAuthRegistry
+ */
+
+interface RFC9421VerifyRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[]>;
+    body?: string;
+}
+interface RFC9421VerifyOptions {
+    resolver: RegistryResolver;
+    /** Seconds of tolerance around created/expires. Default 60 (tightened from 300). */
+    clockSkewSec?: number;
+    /** Injectable for deterministic tests. */
+    now?: () => number;
+    /** Optional replay-protection store. Defaults to in-process LRU. */
+    nonceStore?: NonceStore;
+}
+interface RFC9421VerifyResult {
+    ok: boolean;
+    kid?: string;
+    registry?: RegistryResolver['name'];
+    algorithm?: string;
+    error?: string;
+}
+declare function verifyRFC9421(request: RFC9421VerifyRequest, options: RFC9421VerifyOptions): Promise<RFC9421VerifyResult>;
+
+/**
+ * UCP (Universal Commerce Protocol) checkout session extractor.
+ *
+ * Google + Shopify spec (ucp.dev). Extracts checkout session context from
+ * incoming HTTP requests and, at registration time, validates the
+ * `/.well-known/ucp` manifest via AJV against the mirrored JSON schema.
+ */
+
+interface UCPTotal {
+    type?: string;
+    amount?: number;
+    currency?: string;
+}
+interface UCPCheckoutContext {
+    sessionId?: string;
+    endpoint: string;
+    purpose: CommercePurpose | null;
+    merchantDomain?: string;
+    totals?: UCPTotal[];
+    paymentMethod?: string;
+    manifestUrl?: string;
+}
+interface UCPRequestLike {
+    method: string;
+    url: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+declare function extractUCPContext(request: UCPRequestLike): UCPCheckoutContext | null;
+/**
+ * Fetch and parse a UCP manifest at registration time. Returns parsed JSON
+ * on success, null on any failure (network, parse, timeout). Does NOT throw.
+ *
+ * Schema validation is a separate step — see `validateUCPManifest`.
+ */
+declare function fetchUCPManifest(manifestUrl: string, options?: {
+    timeoutMs?: number;
+}): Promise<unknown | null>;
+/**
+ * Validate a UCP manifest against the minimal shape we care about.
+ *
+ * The full UCP manifest schema lives upstream (ucp.dev) and is out of scope
+ * to mirror here exhaustively. This function checks the structural guarantees
+ * we depend on: required top-level fields (version, capabilities, endpoints).
+ *
+ * For full schema validation, consumers can pass their own AJV compiled
+ * validator via `options.validator`.
+ */
+interface UCPManifestValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+declare function validateUCPManifest(manifest: unknown, options?: {
+    validator?: (m: unknown) => {
+        ok: boolean;
+        errors: string[];
+    };
+}): UCPManifestValidationResult;
+
+/**
+ * ACP (Agentic Commerce Protocol) request extractor.
+ *
+ * Co-maintained by OpenAI + Stripe. Spec at agenticcommerce.dev.
+ *
+ * Extracts ACP request context from HTTP requests:
+ *  - Multi-header parsing: Signature, Timestamp, Idempotency-Key,
+ *    Authorization: Bearer, API-Version
+ *  - Endpoint classification: Agentic Checkout (checkout_sessions.*) vs
+ *    Delegate Payment (agentic_commerce/delegate_payment)
+ *  - Payment token detection: spt_* (Stripe SharedPaymentToken),
+ *    vt_* (ACP vault token), unknown
+ *  - Totals + merchant extraction from body
+ *
+ * No signature verification here — see acp-verify.ts.
+ */
+
+type ACPEndpoint = 'checkout_sessions.create' | 'checkout_sessions.update' | 'checkout_sessions.complete' | 'checkout_sessions.cancel' | 'delegate_payment' | 'unknown';
+type ACPPaymentTokenType = 'stripe-spt' | 'acp-vt' | 'other' | null;
+interface ACPTotal {
+    type?: string;
+    amount?: number;
+    currency?: string;
+}
+interface ACPRequestContext {
+    endpoint: ACPEndpoint;
+    purpose: CommercePurpose | null;
+    sessionId?: string;
+    merchantId?: string;
+    apiVersion?: string;
+    bearer?: string;
+    signatureHeader?: string;
+    timestampHeader?: string;
+    idempotencyKey?: string;
+    paymentToken?: {
+        raw?: string;
+        type: ACPPaymentTokenType;
+        provider?: string;
+    };
+    totals?: ACPTotal[];
+    fulfillmentOption?: string;
+    rawBody?: string;
+}
+interface ACPRequestLike {
+    method: string;
+    url: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    rawBody?: string;
+}
+declare function extractACPContext(request: ACPRequestLike): ACPRequestContext | null;
+
+/**
+ * VI (Verifiable Intent) SD-JWT extraction.
+ *
+ * Open-sourced 5 March 2026 by Mastercard + Google (v0.1-draft).
+ * VI is a 3-layer SD-JWT chain:
+ *   L1 — issuer → wallet (credential provider)
+ *   L2 — user → agent (cnf.jwk binding to L3 agent key)
+ *   L3 — agent → merchant (payment or checkout mandate, split into L3a / L3b
+ *        cross-referenced via transaction_id)
+ *
+ * This module does EXTRACTION ONLY — it decodes SD-JWT structure and pulls
+ * out the mandate type, kid, executionMode, 8 constraint types, checkoutHash
+ * (constraint type 8), transactionId, and raw layers for later verification.
+ *
+ * Signature verification lives in vi-verify.ts; this module uses @sd-jwt's
+ * sync decoder with a SHA-256 hasher for structural parsing only.
+ */
+
+type VIExecutionMode = 'Immediate' | 'Autonomous' | 'Both';
+interface VIAllowedParty {
+    id?: string;
+    name?: string;
+    website?: string;
+}
+interface VILineItem {
+    id?: string;
+    acceptableItems?: string[];
+    quantity?: number;
+}
+interface VIPaymentAmount {
+    currency?: string;
+    min?: number;
+    max?: number;
+}
+interface VIBudgetLimit {
+    currency?: string;
+    max?: number;
+}
+interface VIRecurrence {
+    frequency?: string;
+    startDate?: string;
+    endDate?: string;
+    maxOccurrences?: number;
+}
+interface VIConstraints {
+    allowedMerchants?: VIAllowedParty[];
+    allowedPayees?: VIAllowedParty[];
+    lineItems?: VILineItem[];
+    paymentAmount?: VIPaymentAmount;
+    budgetLimit?: VIBudgetLimit;
+    recurrence?: VIRecurrence;
+    agentRecurrence?: VIRecurrence;
+}
+interface VIExtractedClaims {
+    mandateType: VIMandateType;
+    kid?: string;
+    executionMode?: VIExecutionMode;
+    credentialProvider?: string;
+    constraints: VIConstraints;
+    /** VI constraint type 8 — SHA-256 of the paired L2 checkout disclosure. */
+    checkoutHash?: string;
+    transactionId?: string;
+    rawLayers: {
+        l1?: string;
+        l2?: string;
+        l3?: string;
+    };
+}
+/**
+ * Extract VI claims from a compact SD-JWT string.
+ *
+ * Input shape:
+ *   <jwt>~<disclosure1>~<disclosure2>~...~<kbJwt?>
+ *
+ * Returns null if parsing fails at any layer. Does not verify signatures.
+ */
+declare function extractVIClaims(sdJwtCompact: string): VIExtractedClaims | null;
+
+/**
+ * Stripe webhook HMAC-SHA256 verifier (inline).
+ *
+ * Stripe-Signature header format: "t=TIMESTAMP,v1=HEX_SIGNATURE"
+ *   - t: unix seconds when Stripe signed the webhook
+ *   - v1: HMAC-SHA256(webhook_secret, `${t}.${payload}`) as hex
+ *
+ * Multiple v1 signatures can coexist during secret rotation; any match wins.
+ * Default tolerance on timestamp age: 300s (matches Stripe's own default).
+ *
+ * Documented at docs.stripe.com — we intentionally inline ~25 LOC rather
+ * than pull in the full stripe npm package (MIT but 600KB+ with deps).
+ */
+interface VerifyStripeWebhookResult {
+    ok: boolean;
+    timestamp?: number;
+    error?: string;
+}
+interface VerifyStripeWebhookOptions {
+    toleranceSec?: number;
+    /** Injectable for deterministic tests. */
+    now?: () => number;
+}
+declare function verifyStripeWebhook(payload: string, signatureHeader: string | undefined, secret: string, options?: VerifyStripeWebhookOptions): VerifyStripeWebhookResult;
+
+/**
+ * PDLSS constraint evaluation.
+ *
+ * Evaluates VI constraint types 1-4 (merchant/payee allowlists, line items,
+ * payment amount) + MPP/x402 payment-method allowlist + spending-limit
+ * against a transaction context.
+ *
+ * Types 5/6/7 (budget, recurrence, agent_recurrence) extract through but
+ * enforcement is deferred to the cross-merchant budget service.
+ * This module returns per-constraint {ok, reason} results
+ * so a policy layer can decide hard-deny vs trust-signal.
+ */
+
+interface TransactionContext {
+    amount?: number;
+    currency?: string;
+    merchant?: {
+        id?: string;
+        website?: string;
+    };
+    payee?: {
+        id?: string;
+        website?: string;
+    };
+    lineItems?: Array<{
+        id?: string;
+        quantity?: number;
+    }>;
+    /** For MPP / x402 payment-method enforcement. */
+    paymentMethod?: string;
+}
+type ConstraintKey = 'merchant' | 'payee' | 'lineItems' | 'amount' | 'paymentMethod';
+interface ConstraintResult {
+    ok: boolean;
+    reason?: string;
+}
+interface ConstraintEvalResult {
+    ok: boolean;
+    results: Record<string, ConstraintResult>;
+    reasons: string[];
+}
+interface VIConstraintEvalInput {
+    constraints: VIConstraints;
+    transaction: TransactionContext;
+}
+declare function evaluateVIConstraints(input: VIConstraintEvalInput): ConstraintEvalResult;
+interface PaymentMethodAllowlistInput {
+    allowedMethods?: string[];
+    requestedMethod?: string;
+}
+declare function evaluatePaymentMethodAllowlist(input: PaymentMethodAllowlistInput): ConstraintResult;
+interface SpendingLimitInput {
+    limit?: {
+        amount?: number;
+        currency?: string;
+    };
+    requested?: {
+        amount?: number;
+        currency?: string;
+    };
+}
+declare function evaluateSpendingLimit(input: SpendingLimitInput): ConstraintResult;
+
+/**
+ * Cross-protocol agent identity binding.
+ *
+ * Every commerce layer claims an agent identity differently:
+ *   - VI L3 kid (SD-JWT header)
+ *   - AP2 agent_id (mandate payload)
+ *   - ACP Authorization: Bearer token (merchant-issued pre-shared)
+ *   - MPP Credential `source` field (DID or chain-native key)
+ *   - x402 client wallet address
+ *   - RFC 9421 kid (Agent Pay / TAP / Web Bot Auth)
+ *
+ * This module maps any such claim to a single AstraSync agent via a
+ * caller-supplied resolver (typically delegates to the counterparty service),
+ * then flags whether multiple claims on the same request resolve to different
+ * agents (a trust signal for PDLSS).
+ *
+ * This is AstraSync whitespace — no vendor owns multi-protocol identity
+ * unification.
+ */
+interface IdentityClaim {
+    /** Originating protocol label: 'vi' | 'ap2' | 'acp' | 'mpp' | 'x402' | 'agentpay' | 'tap' | 'webbotauth' */
+    protocol: string;
+    /** Claim field name, e.g. 'kid', 'agent_id', 'source', 'bearer'. */
+    field: string;
+    /** Claim value as presented on the wire. */
+    value: string;
+}
+interface IdentityBindingResult {
+    claims: IdentityClaim[];
+    mappedAstraSyncAgentId?: string;
+    /**
+     * True when two or more claims resolve to different AstraSync agents.
+     * Surfaced as a trust signal rather than an auto-deny — legitimate flows
+     * (e.g. delegate payments) can legitimately carry multiple identities.
+     */
+    mismatchAcrossLayers: boolean;
+    /** Per-claim resolution result for audit / debugging. */
+    resolutions: Array<{
+        claim: IdentityClaim;
+        agentId: string | null;
+    }>;
+}
+type IdentityResolver = (claim: IdentityClaim) => Promise<string | null>;
+declare function bindIdentity(claims: IdentityClaim[], resolver: IdentityResolver): Promise<IdentityBindingResult>;
+/**
+ * Helper constructors — keep protocol/field strings consistent across the
+ * codebase and make tests readable.
+ */
+declare const claim: {
+    viKid: (value: string) => IdentityClaim;
+    ap2AgentId: (value: string) => IdentityClaim;
+    acpBearer: (value: string) => IdentityClaim;
+    mppSource: (value: string) => IdentityClaim;
+    x402Wallet: (value: string) => IdentityClaim;
+    agentPayKid: (value: string) => IdentityClaim;
+    tapKid: (value: string) => IdentityClaim;
+    webBotAuthKid: (value: string) => IdentityClaim;
+};
+
+/**
+ * AP2 (Agent Payments Protocol) mandate extraction.
+ *
+ * Google-led, launched 3 April 2026 with 60+ partners (Mastercard, PayPal,
+ * Coinbase, AmEx, Revolut, UnionPay, ...). AP2 ships three mandate types as
+ * SD-JWTs in series:
+ *   - intent_mandate — user declares intent (amount, merchant category, etc.)
+ *   - cart_mandate — user approves a cart (specific items, totals)
+ *   - payment_mandate — authorizes the actual payment rail
+ *
+ * Mandates are cross-referenced via ids; each is an SD-JWT over ES256 (or
+ * equivalent). We decode via @sd-jwt/core and extract the AP2-specific
+ * shape — verification lives in ap2-verify.ts.
+ */
+
+interface AP2PaymentDetailsTotal {
+    amount?: {
+        value?: string | number;
+        currency?: string;
+    };
+    label?: string;
+}
+interface AP2IntentMandateClaims {
+    type: 'intent_mandate';
+    agent_id?: string;
+    user_id?: string;
+    merchant_category?: string;
+    allowedMerchantDomains?: string[];
+    paymentMethods?: string[];
+    expires?: string;
+    payment_details_total?: AP2PaymentDetailsTotal;
+    raw: Record<string, unknown>;
+}
+interface AP2CartMandateClaims {
+    type: 'cart_mandate';
+    agent_id?: string;
+    intent_mandate_id?: string;
+    merchant_id?: string;
+    line_items?: Array<{
+        id?: string;
+        quantity?: number;
+        price?: {
+            value?: string | number;
+            currency?: string;
+        };
+    }>;
+    payment_details_total?: AP2PaymentDetailsTotal;
+    expires?: string;
+    raw: Record<string, unknown>;
+}
+interface AP2PaymentMandateClaims {
+    type: 'payment_mandate';
+    agent_id?: string;
+    cart_mandate_id?: string;
+    payment_method?: string;
+    payment_details_total?: AP2PaymentDetailsTotal;
+    credential_provider?: string;
+    raw: Record<string, unknown>;
+}
+type AP2MandateClaims = AP2IntentMandateClaims | AP2CartMandateClaims | AP2PaymentMandateClaims;
+interface AP2MandateTriple {
+    intent?: AP2IntentMandateClaims;
+    cart?: AP2CartMandateClaims;
+    payment?: AP2PaymentMandateClaims;
+    rawLayers: {
+        intentJwt?: string;
+        cartJwt?: string;
+        paymentJwt?: string;
+    };
+}
+/**
+ * Extract a single AP2 mandate from a compact SD-JWT.
+ * Returns null if the SD-JWT is malformed or lacks a recognized type field.
+ */
+declare function extractAP2Mandate(sdJwtCompact: string): AP2MandateClaims | null;
+interface AP2MandateTripleInput {
+    intent?: string;
+    cart?: string;
+    payment?: string;
+}
+/**
+ * Extract an intent / cart / payment triple, returning whichever are present.
+ * Does NOT enforce cross-reference consistency — that's ap2-verify.ts's job.
+ */
+declare function extractAP2Mandates(input: AP2MandateTripleInput): AP2MandateTriple;
+
+/**
+ * AP2 mandate chain verification.
+ *
+ * Checks the cross-reference consistency of an intent → cart → payment
+ * triple. Does NOT verify cryptographic signatures here (that's a call to
+ * @sd-jwt/core which needs the agent's / CP's public key; expose via a
+ * verifier callback so pipeline can plug in the right resolver).
+ *
+ * Rules (per AP2 spec v0.1-draft):
+ *  - cart.intent_mandate_id must equal the intent mandate's canonical id (if present)
+ *  - payment.cart_mandate_id must equal the cart mandate's canonical id (if present)
+ *  - agent_id must match across all three layers
+ *  - payment_method in payment mandate must be in intent.paymentMethods (if declared)
+ *  - cart totals must not exceed intent totals (if both declared in same currency)
+ *  - no mandate may be expired (beyond clock skew)
+ */
+
+interface AP2VerifyInput {
+    triple: AP2MandateTriple;
+    /**
+     * Clock skew tolerance in seconds for expiry checks. Default 60s
+     * (tightened from the previous 300s default).
+     */
+    clockSkewSec?: number;
+    now?: () => number;
+    /**
+     * Optional replay-protection store. Defaults to in-process LRU. When the
+     * payment mandate carries an id, this verifier registers it as seen so
+     * the same payment mandate replayed within the expiry window is rejected.
+     */
+    nonceStore?: NonceStore;
+}
+interface AP2ChainResult {
+    ok: boolean;
+    checks: {
+        intentPresent: boolean;
+        cartRefOk: boolean;
+        paymentRefOk: boolean;
+        agentIdContinuity: boolean;
+        paymentMethodAllowed: boolean;
+        totalsConsistent: boolean;
+        expiryOk: boolean;
+    };
+    agentId?: string;
+    errors: string[];
+}
+declare function verifyAP2Chain(input: AP2VerifyInput): AP2ChainResult;
+
+/**
+ * ACP detached-JSON-signature verifier.
+ *
+ * ACP (Agentic Commerce Protocol, OpenAI + Stripe) uses detached JSON
+ * signatures over request bodies. The public signature algorithm is NOT
+ * specified in open docs as of April 2026 (docs.stripe.com/agentic-commerce/*
+ * is Private Preview). We implement Ed25519 and ES256 candidates against
+ * whichever public key the caller supplies, and report algorithm-unsupported
+ * as a trust signal rather than a hard fail so policy can weight it.
+ *
+ * Timestamp freshness (>300s default) IS a hard fail — prevents replay.
+ *
+ * Bearer-token → AstraSync agent binding is delegated to caller-supplied
+ * resolver (typically the counterparty service).
+ */
+
+type ACPSignatureAlgorithm = 'ed25519' | 'es256' | 'unsupported';
+interface ACPVerifyInput {
+    /** Raw request body over which the signature was computed. */
+    rawBody: string;
+    /** Value of the Signature header. Expected to be base64 (either standard or url). */
+    signatureHeader?: string;
+    /** Value of the Timestamp header (unix seconds as string, or ISO 8601). */
+    timestampHeader?: string;
+    /** Candidate public keys to try. First matching algorithm wins. */
+    candidateKeys: Array<{
+        jwk: JWK;
+        alg?: ACPSignatureAlgorithm | string;
+    }>;
+    /** Clock skew tolerance in seconds (default 60, tightened from 300). */
+    clockSkewSec?: number;
+    /** Injectable now for tests. */
+    now?: () => number;
+    /** Optional replay-protection store. Defaults to in-process LRU. */
+    nonceStore?: NonceStore;
+}
+interface ACPVerifyResult {
+    ok: boolean;
+    algorithm?: ACPSignatureAlgorithm;
+    error?: string;
+    /** True when timestamp is outside tolerance. */
+    timestampStale?: boolean;
+}
+declare function verifyACPSignature(input: ACPVerifyInput): Promise<ACPVerifyResult>;
+
+/**
+ * MPP (Machine Payments Protocol) extractor.
+ *
+ * Wraps mppx (wevm) — pinned to 0.5.13, wrapped behind this adapter so
+ * upgrades localise here. MPP launched March 18 2026 (Stripe + Tempo +
+ * Paradigm), IETF draft-ryan-httpauth-payment-01.
+ *
+ * Flow:
+ *   Client → GET /resource
+ *   Server → 402 + WWW-Authenticate: Payment id=..., realm=..., method=tempo|stripe|...
+ *   Client → GET /resource with Authorization: Payment <base64url-json credential>
+ *   Server → 200 + Payment-Receipt: <base64url-json receipt>
+ *
+ * What we extract:
+ *  - Challenge: id, realm, method, intent, request{amount,currency,...}, expires, digest
+ *  - Credential: challenge + source (DID/chain-key) + payload (method-specific)
+ *  - Receipt: challengeId, method, reference (tx hash / pi_... ID), settlement
+ *  - Multi-method 402 offers (may be multiple WWW-Authenticate headers)
+ *
+ * What we do NOT verify here (pass-through):
+ *  - HMAC challenge binding (requires merchant's MPP_SECRET_KEY)
+ *  - Payment proof cryptography (Tempo tx sig, Stripe SPT, Lightning preimage)
+ *    — each requires upstream connectivity
+ *
+ * Verification (expiry + BodyDigest + source extraction) in mpp-verify.ts.
+ */
+interface MPPChallengeSummary {
+    id: string;
+    realm: string;
+    method: string;
+    intent: string;
+    /** Method-specific request data (amount, currency, recipient, etc.) */
+    request: Record<string, unknown>;
+    expires?: string;
+    digest?: string;
+    description?: string;
+    opaque?: Record<string, string>;
+}
+interface MPPCredentialSummary {
+    challenge: MPPChallengeSummary;
+    /** DID or chain-native key identifying the payer. */
+    source?: string;
+    /** Method-specific payment proof (Tempo tx, SPT, Lightning preimage, etc.). */
+    payload: unknown;
+}
+interface MPPReceiptSummary {
+    method?: string;
+    reference?: string;
+    externalId?: string;
+    status?: string;
+    timestamp?: string;
+    raw: Record<string, unknown>;
+}
+type MPPKind = 'challenge' | 'credential' | 'receipt' | 'error' | 'unknown';
+interface MPPRequestContext {
+    kind: MPPKind;
+    /** For 402 responses: one or more challenge offers. */
+    challenges?: MPPChallengeSummary[];
+    /** For requests with Authorization: Payment header. */
+    credential?: MPPCredentialSummary;
+    /** For 200 responses with Payment-Receipt header. */
+    receipt?: MPPReceiptSummary;
+    /** For problem+json error responses. */
+    error?: {
+        type?: string;
+        title?: string;
+        detail?: string;
+    };
+    /** Detected payment methods offered (for multi-method 402). */
+    offeredMethods?: string[];
+    /** Raw body captured for BodyDigest verification in mpp-verify.ts. */
+    rawBody?: string;
+}
+interface MPPRequestLike {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    rawBody?: string;
+}
+interface MPPResponseLike {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    rawBody?: string;
+}
+/**
+ * Extract MPP context from an agent → merchant request.
+ * Looks for `Authorization: Payment <credential>` header.
+ */
+declare function extractMPPFromRequest(request: MPPRequestLike): MPPRequestContext | null;
+/**
+ * Extract MPP context from a merchant → agent response.
+ * Handles 402 (challenge offers), 200 (receipt), 4xx (problem+json errors).
+ */
+declare function extractMPPFromResponse(response: MPPResponseLike): MPPRequestContext | null;
+/**
+ * Extract from either a request OR a response, auto-detecting which has MPP
+ * artifacts. Convenience for pipeline callers.
+ */
+declare function extractMPPContext(message: {
+    request: MPPRequestLike;
+} | {
+    response: MPPResponseLike;
+} | (MPPRequestLike & Partial<MPPResponseLike>)): MPPRequestContext | null;
+
+/**
+ * MPP verification — expiry + optional BodyDigest + source extraction.
+ *
+ * We do NOT verify the challenge's HMAC binding (needs merchant's secret)
+ * or the cryptographic payment proof (per-method, requires upstream
+ * connectivity). Those are the merchant's / settlement layer's job.
+ *
+ * Our job: structural correctness, expiry policy, tamper detection via
+ * optional BodyDigest, and identity extraction for PDLSS binding.
+ */
+
+interface MPPVerifyInput {
+    context: MPPRequestContext;
+    /** Raw request body to validate BodyDigest against, if the challenge declares one. */
+    rawBody?: string;
+    /** Seconds of clock-skew tolerance on challenge.expires. Default 60. */
+    clockSkewSec?: number;
+    /** Injectable for deterministic tests. */
+    now?: () => number;
+    /** Optional replay-protection store. Defaults to in-process LRU. */
+    nonceStore?: NonceStore;
+}
+interface MPPVerifyResult {
+    ok: boolean;
+    expiryOk: boolean;
+    bodyDigestOk: boolean | null;
+    source?: string;
+    method?: string;
+    error?: string;
+}
+declare function verifyMPP(input: MPPVerifyInput): MPPVerifyResult;
+
+/**
+ * x402 (Coinbase / Linux Foundation x402 Foundation) extractor.
+ *
+ * Wraps @x402/core's schema parsers. x402 Foundation launched April 2 2026
+ * with v2 adding network-agnostic identifiers + multiple facilitators +
+ * Bazaar discovery. MPP (Machine Payments Protocol) is the IETF-formalised
+ * superset of x402; this module normalizes x402 output to MPP-shape so
+ * downstream pipeline code is uniform.
+ *
+ * Where x402 lives on the wire:
+ *  - 402 response body (v2) OR `X-PAYMENT-REQUIRED` header (v1) — PaymentRequired
+ *  - Request body (v2) OR `X-PAYMENT` header (v1, base64) — PaymentPayload
+ */
+type X402Kind = 'required' | 'payload' | 'error' | 'unknown';
+interface X402RequirementsSummary {
+    scheme: string;
+    network: string;
+    asset: string;
+    /** Normalized to string for v1/v2 compat — v1 uses maxAmountRequired, v2 uses amount. */
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds?: number;
+    resource?: string;
+    description?: string;
+}
+interface X402RequestContext {
+    kind: X402Kind;
+    version: 1 | 2 | null;
+    /** For 402 responses: the PaymentRequired body. */
+    paymentRequired?: {
+        resource: string;
+        accepts: X402RequirementsSummary[];
+        extensions?: Record<string, unknown>;
+        error?: string;
+    };
+    /** For request body (v2) or X-PAYMENT header (v1 base64): the PaymentPayload. */
+    paymentPayload?: {
+        scheme: string;
+        network: string;
+        /** Free-form per-scheme payload (e.g. EIP-3009 authorization, Solana tx). */
+        payload: Record<string, unknown>;
+        extensions?: Record<string, unknown>;
+    };
+    error?: {
+        type: string;
+        detail?: string;
+    };
+    /** Whether this was parsed from a header (v1 back-compat) or body (v2). */
+    source: 'header' | 'body' | null;
+}
+interface X402RequestLike {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+interface X402ResponseLike {
+    status?: number;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+/**
+ * Extract x402 PaymentPayload from an agent → merchant request.
+ * Checks v2 body (if it parses as PaymentPayload) and v1 X-PAYMENT header.
+ */
+declare function extractX402FromRequest(request: X402RequestLike): X402RequestContext | null;
+/**
+ * Extract x402 PaymentRequired from a merchant → agent 402 response.
+ */
+declare function extractX402FromResponse(response: X402ResponseLike): X402RequestContext | null;
+declare function extractX402Context(message: {
+    request: X402RequestLike;
+} | {
+    response: X402ResponseLike;
+} | (X402RequestLike & Partial<X402ResponseLike>)): X402RequestContext | null;
+
+/**
+ * VI (Verifiable Intent) 3-layer SD-JWT chain verification.
+ *
+ * VI chains: L1 (credential provider → wallet) → L2 (user → agent) → L3
+ * (agent → merchant). L3 itself can split into L3a (payment mandate) + L3b
+ * (checkout mandate) cross-referenced via transaction_id, with L3b carrying
+ * a checkout_hash (VI constraint type 8) that must match SHA-256 of the L2
+ * checkout disclosure.
+ *
+ * Signature primitives are delegated to @sd-jwt/core (via our extractor);
+ * cnf.jwk chain-walking + cross-references + checkout_hash binding is
+ * AstraSync-specific composition logic — that's the whitespace here.
+ *
+ * This module does NOT re-verify selective-disclosure hashes (the extractor
+ * already applied them via @sd-jwt/core). It DOES verify:
+ *  - cnf.jwk in L1 payload points to L2's signing key (thumbprint match)
+ *  - cnf.jwk in L2 payload points to L3's signing key
+ *  - L3a.transaction_id === L3b.transaction_id (when both present)
+ *  - L3b.checkout_hash === SHA-256(L2 canonical checkout disclosure) — type 8
+ *  - mandate-level `exp` is not in the past (beyond clock skew)
+ *
+ * Cryptographic signature verification on each layer uses the verifier
+ * callback the caller supplies (e.g. resolves via @sd-jwt/core with the
+ * right JWK from the L1 issuer's JWKS).
+ */
+
+interface VILayer {
+    /** Compact SD-JWT / JWS for this layer. */
+    compact: string;
+    /** Decoded JWT payload (already disclosure-merged). */
+    payload: Record<string, unknown>;
+    /** Decoded JWT header. */
+    header: Record<string, unknown>;
+}
+interface VIVerifyInput {
+    /**
+     * Layers in chain order. L1 is REQUIRED by default —
+     * without L1 there is no chain root and L2 can be verified against any
+     * attacker-supplied key. Callers who have resolved L2's signing key by
+     * a trusted out-of-band mechanism (wallet binding, prior protocol step)
+     * MUST set `allowUnboundChain: true` AND supply `expectedL2Key`.
+     */
+    layers: {
+        l1?: VILayer;
+        l2: VILayer;
+        l3a?: VILayer;
+        l3b?: VILayer;
+    };
+    /**
+     * Verifier callback invoked per layer. Should return true iff the layer's
+     * JWS signature verifies against the resolved public key (for L2 this is
+     * L1's cnf.jwk; for L3 this is L2's cnf.jwk; for L1 this is the issuer's
+     * JWKS per `iss` claim).
+     */
+    verifySignature: (layer: VILayer, expectedKey: JWK | null) => Promise<boolean>;
+    /**
+     * Clock skew tolerance in seconds for expiry checks. Default 60s
+     * (tightened from the previous 300s default).
+     */
+    clockSkewSec?: number;
+    now?: () => number;
+    /**
+     * Explicit opt-in to verify a chain with L1 omitted.
+     * Defaults to false. When true, `expectedL2Key` MUST also be supplied
+     * (used as the expected signing key for L2 verification).
+     */
+    allowUnboundChain?: boolean;
+    /** Required when allowUnboundChain === true. */
+    expectedL2Key?: JWK;
+    /** Optional replay-protection store. Defaults to in-process LRU. */
+    nonceStore?: NonceStore;
+}
+interface VIVerifyResult {
+    ok: boolean;
+    checks: {
+        l1SigOk: boolean | null;
+        l2SigOk: boolean;
+        l3aSigOk: boolean | null;
+        l3bSigOk: boolean | null;
+        l1BindsL2: boolean;
+        l2BindsL3: boolean;
+        l3aL3bTxnIdMatch: boolean | null;
+        checkoutHashOk: boolean | null;
+        expiryOk: boolean;
+    };
+    errors: string[];
+}
+declare function verifyVIChain(input: VIVerifyInput): Promise<VIVerifyResult>;
+
+/**
+ * Commerce pipeline orchestrator.
+ *
+ * Ties together extractors + verifiers + identity binding + constraint
+ * evaluation + trust signals into a single CommerceContext result.
+ *
+ * This is AstraSync whitespace: the orchestration over the library-backed
+ * primitives. The backend verify-access service is the sole per-request
+ * caller — the edge adapters forward raw artifacts to verify-access and
+ * never call this module directly. The admin transport playground also
+ * calls it ad-hoc.
+ *
+ * Policy:
+ *  - Hard-deny (ok=false) on bad signatures, expired mandates, constraint
+ *    failures, identity cannot be bound.
+ *  - Trust signal (ok remains policy-driven) on ACP algorithm unsupported,
+ *    Stripe webhook HMAC fail, payment-token type unknown, cross-layer
+ *    identity mismatch.
+ */
+
+type CommerceProtocol = 'vi' | 'ap2' | 'ucp' | 'acp' | 'agentpay' | 'tap' | 'mpp' | 'x402';
+interface CommercePipelineInput {
+    protocol: CommerceProtocol;
+    vi?: {
+        claims: VIExtractedClaims;
+        verifyInput?: VIVerifyInput;
+    };
+    ap2?: {
+        triple: AP2MandateTriple;
+    };
+    ucp?: UCPCheckoutContext;
+    acp?: {
+        context: ACPRequestContext;
+        verifyInput?: Parameters<typeof verifyACPSignature>[0];
+    };
+    rfc9421?: {
+        request: RFC9421VerifyRequest;
+        tag?: 'browse' | 'purchase' | string;
+        verifyOptions: Parameters<typeof verifyRFC9421>[1];
+    };
+    mpp?: {
+        context: MPPRequestContext;
+        rawBody?: string;
+    };
+    x402?: X402RequestContext;
+    stripeWebhook?: {
+        payload: string;
+        signatureHeader: string;
+        secret: string;
+    };
+    transaction?: TransactionContext;
+    registeredConstraints?: {
+        allowedPaymentMethods?: string[];
+        spendingLimit?: {
+            amount?: number;
+            currency?: string;
+        };
+    };
+    identityResolver?: IdentityResolver;
+    clockSkewSec?: number;
+    now?: () => number;
+}
+interface CommerceSignatureStack {
+    vi?: VIVerifyResult;
+    ap2?: AP2ChainResult;
+    acp?: ACPVerifyResult;
+    rfc9421?: RFC9421VerifyResult;
+    mpp?: MPPVerifyResult;
+    stripeWebhook?: VerifyStripeWebhookResult;
+}
+interface CommerceContext {
+    protocol: CommerceProtocol;
+    purpose: CommercePurpose | null;
+    transactionValue?: TransactionValueContext;
+    signatures: CommerceSignatureStack;
+    identity?: {
+        claims: IdentityClaim[];
+        mappedAstraSyncAgentId?: string;
+        mismatchAcrossLayers: boolean;
+    };
+    paymentToken?: {
+        present: boolean;
+        type: 'stripe-spt' | 'acp-vt' | 'tempo-tx' | 'other' | null;
+    };
+    mppMethodsOffered?: string[];
+    constraints?: ConstraintEvalResult;
+    receipt?: {
+        method?: string;
+        reference?: string;
+        status?: string;
+        timestamp?: string;
+    };
+    trustSignals: string[];
+    timings: {
+        extractMs: number;
+        verifyMs: number;
+        evalMs: number;
+    };
+    /** False when any hard-deny rule fires. */
+    ok: boolean;
+}
+declare function runCommercePipeline(input: CommercePipelineInput): Promise<CommerceContext>;
+
+/**
+ * Pluggable extractor registry for the Trusted Agent Gateway edge
+ * adapters and other callers that need a curated extractor set.
+ *
+ * Built-in extractors (VI, UCP, ACP, RFC 9421, MPP, x402, Stripe webhook)
+ * are NOT auto-registered. A caller imports this module, picks the set
+ * it wants, and calls registerTransportExtractor() for each.
+ *
+ * Re-registering by name replaces the prior extractor (idempotent).
+ */
+interface ExtractorRequestLike {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+interface TransportExtractor<T = unknown> {
+    readonly name: string;
+    match(request: ExtractorRequestLike): boolean;
+    extract(request: ExtractorRequestLike): T | Promise<T> | null;
+}
+declare function registerTransportExtractor<T>(extractor: TransportExtractor<T>): void;
+declare function getTransportExtractors(): ReadonlyArray<TransportExtractor>;
+declare function getTransportExtractor(name: string): TransportExtractor | undefined;
+declare function clearTransportExtractors(): void;
+/**
+ * Helper: run all matching extractors against a request and return their
+ * extracted contexts keyed by extractor name. Skips extractors whose
+ * `match()` returns false.
+ */
+declare function runMatchingExtractors(request: ExtractorRequestLike): Promise<Record<string, unknown>>;
+
+/**
+ * Visa JWKS registry resolver.
+ *
+ * Default endpoint: https://mcp.visa.com/.well-known/jwks (per Visa TAP spec).
+ * Wraps jose.createRemoteJWKSet which handles caching + rotation natively.
+ */
+
+interface VisaRegistryOptions {
+    jwksUrl?: string;
+    cacheMaxAge?: number;
+    cooldownDuration?: number;
+}
+declare function createVisaRegistry(options?: VisaRegistryOptions): RegistryResolver;
+
+/**
+ * Mastercard Agent Registry resolver — STUB.
+ *
+ * Mastercard Agent Pay is behind partnership (pilots Feb 2026, GA Q2 2026).
+ * No public Agent Registry URL or open-source resolver exists as of April
+ * 2026. This resolver accepts an optional `registryUrl` and, when absent,
+ * returns null with a single one-time console.warn so callers can plumb
+ * the flow end-to-end without a live registry.
+ *
+ * When Mastercard ships a public resolver or when a commercial relationship
+ * provides a registry URL, pass it via `MastercardRegistryOptions.registryUrl`.
+ * Response shape expected: { keys: JWK[] } (JWKS-style).
+ */
+
+interface MastercardRegistryOptions {
+    /** Partnership-provided registry URL. Without it, the resolver is inert. */
+    registryUrl?: string;
+    /** Cache TTL in seconds. Default 3600. */
+    cacheTtlSec?: number;
+    /** Fetch fn override for testing. */
+    fetch?: typeof fetch;
+    /** Silence the one-time warn (testing only). */
+    silent?: boolean;
+}
+declare function createMastercardRegistry(options?: MastercardRegistryOptions): RegistryResolver;
+
+/**
+ * Web Bot Auth registry resolver.
+ *
+ * IETF draft-meunier-web-bot-auth-architecture-05 + draft-meunier-http-
+ * message-signatures-directory-01. Shared transport substrate under TAP,
+ * Agent Pay, and Cloudflare Pay Per Crawl.
+ *
+ * Fetches a Web Bot Auth signature directory
+ * (default: `<origin>/.well-known/http-message-signatures-directory`).
+ * Shape per spec is a JWKS with Ed25519 keys.
+ *
+ * Wraps Cloudflare's `web-bot-auth` npm package where feasible; for raw
+ * directory fetch + kid matching we use fetch + JSON since web-bot-auth's
+ * higher-level API assumes a full request to verify.
+ */
+
+interface WebBotAuthRegistryOptions {
+    /**
+     * Optional explicit directory URL. When omitted, the resolver derives one
+     * from `ResolveContext.origin` (e.g. the request URL's origin at verify time).
+     */
+    directoryUrl?: string;
+    cacheTtlSec?: number;
+    fetch?: typeof fetch;
+}
+declare function createWebBotAuthRegistry(options?: WebBotAuthRegistryOptions): RegistryResolver;
+
+/**
+ * Cross-Protocol Transport Module
+ *
+ * Provides adapters for injecting/extracting AstraSync credentials
+ * across HTTP, A2A, and MCP protocols.
+ */
+
+/**
+ * Auto-detect protocol from request/context shape.
+ */
+declare function detectProtocol(context: Record<string, unknown>): ProtocolTransport;
+/**
+ * Apply credentials to any protocol target.
+ */
+declare function applyCredentials(protocol: ProtocolTransport, target: Record<string, unknown>, credentials: AstraSyncCredentials): Record<string, unknown>;
+/**
+ * Extract credentials from any protocol context.
+ */
+declare function extractCredentialsFromProtocol(protocol: ProtocolTransport, context: Record<string, unknown>): AstraSyncCredentials | null;
+
+type index$1_ACPEndpoint = ACPEndpoint;
+type index$1_ACPPaymentTokenType = ACPPaymentTokenType;
+type index$1_ACPRequestContext = ACPRequestContext;
+type index$1_ACPRequestLike = ACPRequestLike;
+type index$1_ACPSignatureAlgorithm = ACPSignatureAlgorithm;
+type index$1_ACPTotal = ACPTotal;
+type index$1_ACPVerifyInput = ACPVerifyInput;
+type index$1_ACPVerifyResult = ACPVerifyResult;
+type index$1_AP2CartMandateClaims = AP2CartMandateClaims;
+type index$1_AP2ChainResult = AP2ChainResult;
+type index$1_AP2IntentMandateClaims = AP2IntentMandateClaims;
+type index$1_AP2MandateClaims = AP2MandateClaims;
+type index$1_AP2MandateTriple = AP2MandateTriple;
+type index$1_AP2MandateTripleInput = AP2MandateTripleInput;
+type index$1_AP2MandateType = AP2MandateType;
+type index$1_AP2PaymentDetailsTotal = AP2PaymentDetailsTotal;
+type index$1_AP2PaymentMandateClaims = AP2PaymentMandateClaims;
+type index$1_AP2PaymentMandateForValue = AP2PaymentMandateForValue;
+type index$1_AP2VerifyInput = AP2VerifyInput;
+type index$1_CommerceContext = CommerceContext;
+type index$1_CommercePipelineInput = CommercePipelineInput;
+type index$1_CommerceProtocol = CommerceProtocol;
+type index$1_CommercePurpose = CommercePurpose;
+type index$1_CommerceSignatureStack = CommerceSignatureStack;
+type index$1_ConstraintEvalResult = ConstraintEvalResult;
+type index$1_ConstraintKey = ConstraintKey;
+type index$1_ConstraintResult = ConstraintResult;
+type index$1_ExtractorRequestLike = ExtractorRequestLike;
+type index$1_IdentityBindingResult = IdentityBindingResult;
+type index$1_IdentityClaim = IdentityClaim;
+type index$1_IdentityResolver = IdentityResolver;
+type index$1_MPPChallengeForValue = MPPChallengeForValue;
+type index$1_MPPChallengeSummary = MPPChallengeSummary;
+type index$1_MPPCredentialSummary = MPPCredentialSummary;
+type index$1_MPPIntent = MPPIntent;
+type index$1_MPPKind = MPPKind;
+type index$1_MPPReceiptSummary = MPPReceiptSummary;
+type index$1_MPPRequestContext = MPPRequestContext;
+type index$1_MPPRequestLike = MPPRequestLike;
+type index$1_MPPResponseLike = MPPResponseLike;
+type index$1_MPPVerifyInput = MPPVerifyInput;
+type index$1_MPPVerifyResult = MPPVerifyResult;
+type index$1_ParsedRFC9421 = ParsedRFC9421;
+type index$1_PaymentMethodAllowlistInput = PaymentMethodAllowlistInput;
+type index$1_RFC9421SignatureParams = RFC9421SignatureParams;
+type index$1_RFC9421Tag = RFC9421Tag;
+type index$1_RFC9421VerifyOptions = RFC9421VerifyOptions;
+type index$1_RFC9421VerifyRequest = RFC9421VerifyRequest;
+type index$1_RFC9421VerifyResult = RFC9421VerifyResult;
+type index$1_RegistryName = RegistryName;
+type index$1_RegistryResolver = RegistryResolver;
+type index$1_ResolveContext = ResolveContext;
+declare const index$1_STRIPE_WEBHOOK_INFORMATIONAL_EVENTS: typeof STRIPE_WEBHOOK_INFORMATIONAL_EVENTS;
+type index$1_SpendingLimitInput = SpendingLimitInput;
+type index$1_StripeWebhookInformationalEvent = StripeWebhookInformationalEvent;
+type index$1_TransactionContext = TransactionContext;
+type index$1_TransactionValueContext = TransactionValueContext;
+type index$1_TransportExtractor<T = unknown> = TransportExtractor<T>;
+type index$1_UCPCheckoutContext = UCPCheckoutContext;
+type index$1_UCPManifestValidationResult = UCPManifestValidationResult;
+type index$1_UCPRequestLike = UCPRequestLike;
+type index$1_UCPTotal = UCPTotal;
+type index$1_VIAllowedParty = VIAllowedParty;
+type index$1_VIBudgetLimit = VIBudgetLimit;
+type index$1_VIClaimsForValue = VIClaimsForValue;
+type index$1_VIConstraintEvalInput = VIConstraintEvalInput;
+type index$1_VIConstraints = VIConstraints;
+type index$1_VIExecutionMode = VIExecutionMode;
+type index$1_VIExtractedClaims = VIExtractedClaims;
+type index$1_VILayer = VILayer;
+type index$1_VILineItem = VILineItem;
+type index$1_VIMandateType = VIMandateType;
+type index$1_VIPaymentAmount = VIPaymentAmount;
+type index$1_VIRecurrence = VIRecurrence;
+type index$1_VIVerifyInput = VIVerifyInput;
+type index$1_VIVerifyResult = VIVerifyResult;
+type index$1_VerifyStripeWebhookOptions = VerifyStripeWebhookOptions;
+type index$1_VerifyStripeWebhookResult = VerifyStripeWebhookResult;
+type index$1_X402Kind = X402Kind;
+type index$1_X402RequestContext = X402RequestContext;
+type index$1_X402RequestForValue = X402RequestForValue;
+type index$1_X402RequestLike = X402RequestLike;
+type index$1_X402RequirementsSummary = X402RequirementsSummary;
+type index$1_X402ResponseLike = X402ResponseLike;
+declare const index$1_applyCredentials: typeof applyCredentials;
+declare const index$1_bindIdentity: typeof bindIdentity;
+declare const index$1_claim: typeof claim;
+declare const index$1_clearTransportExtractors: typeof clearTransportExtractors;
+declare const index$1_createMastercardRegistry: typeof createMastercardRegistry;
+declare const index$1_createVisaRegistry: typeof createVisaRegistry;
+declare const index$1_createWebBotAuthRegistry: typeof createWebBotAuthRegistry;
+declare const index$1_detectProtocol: typeof detectProtocol;
+declare const index$1_evaluatePaymentMethodAllowlist: typeof evaluatePaymentMethodAllowlist;
+declare const index$1_evaluateSpendingLimit: typeof evaluateSpendingLimit;
+declare const index$1_evaluateVIConstraints: typeof evaluateVIConstraints;
+declare const index$1_extractA2ACredentials: typeof extractA2ACredentials;
+declare const index$1_extractACPContext: typeof extractACPContext;
+declare const index$1_extractACPTransactionValue: typeof extractACPTransactionValue;
+declare const index$1_extractAP2Mandate: typeof extractAP2Mandate;
+declare const index$1_extractAP2Mandates: typeof extractAP2Mandates;
+declare const index$1_extractAP2TransactionValue: typeof extractAP2TransactionValue;
+declare const index$1_extractCredentialsFromProtocol: typeof extractCredentialsFromProtocol;
+declare const index$1_extractHttpCredentials: typeof extractHttpCredentials;
+declare const index$1_extractMPPContext: typeof extractMPPContext;
+declare const index$1_extractMPPFromRequest: typeof extractMPPFromRequest;
+declare const index$1_extractMPPFromResponse: typeof extractMPPFromResponse;
+declare const index$1_extractMPPTransactionValue: typeof extractMPPTransactionValue;
+declare const index$1_extractMcpCredentials: typeof extractMcpCredentials;
+declare const index$1_extractUCPContext: typeof extractUCPContext;
+declare const index$1_extractUCPTransactionValue: typeof extractUCPTransactionValue;
+declare const index$1_extractVIClaims: typeof extractVIClaims;
+declare const index$1_extractVITransactionValue: typeof extractVITransactionValue;
+declare const index$1_extractX402Context: typeof extractX402Context;
+declare const index$1_extractX402FromRequest: typeof extractX402FromRequest;
+declare const index$1_extractX402FromResponse: typeof extractX402FromResponse;
+declare const index$1_extractX402TransactionValue: typeof extractX402TransactionValue;
+declare const index$1_fetchUCPManifest: typeof fetchUCPManifest;
+declare const index$1_getTransportExtractor: typeof getTransportExtractor;
+declare const index$1_getTransportExtractors: typeof getTransportExtractors;
+declare const index$1_isStripeWebhookInformational: typeof isStripeWebhookInformational;
+declare const index$1_mapACPRequestToPurpose: typeof mapACPRequestToPurpose;
+declare const index$1_mapAP2MandateToPurpose: typeof mapAP2MandateToPurpose;
+declare const index$1_mapMPPRequestToPurpose: typeof mapMPPRequestToPurpose;
+declare const index$1_mapRFC9421TagToPurpose: typeof mapRFC9421TagToPurpose;
+declare const index$1_mapUCPRequestToPurpose: typeof mapUCPRequestToPurpose;
+declare const index$1_mapVIMandateToPurpose: typeof mapVIMandateToPurpose;
+declare const index$1_mapX402RequestToPurpose: typeof mapX402RequestToPurpose;
+declare const index$1_parseRFC9421: typeof parseRFC9421;
+declare const index$1_registerTransportExtractor: typeof registerTransportExtractor;
+declare const index$1_runCommercePipeline: typeof runCommercePipeline;
+declare const index$1_runMatchingExtractors: typeof runMatchingExtractors;
+declare const index$1_setA2AMetadata: typeof setA2AMetadata;
+declare const index$1_setHttpHeaders: typeof setHttpHeaders;
+declare const index$1_setMcpMeta: typeof setMcpMeta;
+declare const index$1_validateUCPManifest: typeof validateUCPManifest;
+declare const index$1_verifyACPSignature: typeof verifyACPSignature;
+declare const index$1_verifyAP2Chain: typeof verifyAP2Chain;
+declare const index$1_verifyMPP: typeof verifyMPP;
+declare const index$1_verifyRFC9421: typeof verifyRFC9421;
+declare const index$1_verifyStripeWebhook: typeof verifyStripeWebhook;
+declare const index$1_verifyVIChain: typeof verifyVIChain;
+declare namespace index$1 {
+  export { type index$1_ACPEndpoint as ACPEndpoint, type index$1_ACPPaymentTokenType as ACPPaymentTokenType, type index$1_ACPRequestContext as ACPRequestContext, type index$1_ACPRequestLike as ACPRequestLike, type index$1_ACPSignatureAlgorithm as ACPSignatureAlgorithm, type index$1_ACPTotal as ACPTotal, type index$1_ACPVerifyInput as ACPVerifyInput, type index$1_ACPVerifyResult as ACPVerifyResult, type index$1_AP2CartMandateClaims as AP2CartMandateClaims, type index$1_AP2ChainResult as AP2ChainResult, type index$1_AP2IntentMandateClaims as AP2IntentMandateClaims, type index$1_AP2MandateClaims as AP2MandateClaims, type index$1_AP2MandateTriple as AP2MandateTriple, type index$1_AP2MandateTripleInput as AP2MandateTripleInput, type index$1_AP2MandateType as AP2MandateType, type index$1_AP2PaymentDetailsTotal as AP2PaymentDetailsTotal, type index$1_AP2PaymentMandateClaims as AP2PaymentMandateClaims, type index$1_AP2PaymentMandateForValue as AP2PaymentMandateForValue, type index$1_AP2VerifyInput as AP2VerifyInput, type index$1_CommerceContext as CommerceContext, type index$1_CommercePipelineInput as CommercePipelineInput, type index$1_CommerceProtocol as CommerceProtocol, type index$1_CommercePurpose as CommercePurpose, type index$1_CommerceSignatureStack as CommerceSignatureStack, type index$1_ConstraintEvalResult as ConstraintEvalResult, type index$1_ConstraintKey as ConstraintKey, type index$1_ConstraintResult as ConstraintResult, type index$1_ExtractorRequestLike as ExtractorRequestLike, type index$1_IdentityBindingResult as IdentityBindingResult, type index$1_IdentityClaim as IdentityClaim, type index$1_IdentityResolver as IdentityResolver, type index$1_MPPChallengeForValue as MPPChallengeForValue, type index$1_MPPChallengeSummary as MPPChallengeSummary, type index$1_MPPCredentialSummary as MPPCredentialSummary, type index$1_MPPIntent as MPPIntent, type index$1_MPPKind as MPPKind, type index$1_MPPReceiptSummary as MPPReceiptSummary, type index$1_MPPRequestContext as MPPRequestContext, type index$1_MPPRequestLike as MPPRequestLike, type index$1_MPPResponseLike as MPPResponseLike, type index$1_MPPVerifyInput as MPPVerifyInput, type index$1_MPPVerifyResult as MPPVerifyResult, type index$1_ParsedRFC9421 as ParsedRFC9421, type index$1_PaymentMethodAllowlistInput as PaymentMethodAllowlistInput, type index$1_RFC9421SignatureParams as RFC9421SignatureParams, type index$1_RFC9421Tag as RFC9421Tag, type index$1_RFC9421VerifyOptions as RFC9421VerifyOptions, type index$1_RFC9421VerifyRequest as RFC9421VerifyRequest, type index$1_RFC9421VerifyResult as RFC9421VerifyResult, type index$1_RegistryName as RegistryName, type index$1_RegistryResolver as RegistryResolver, type index$1_ResolveContext as ResolveContext, index$1_STRIPE_WEBHOOK_INFORMATIONAL_EVENTS as STRIPE_WEBHOOK_INFORMATIONAL_EVENTS, type index$1_SpendingLimitInput as SpendingLimitInput, type index$1_StripeWebhookInformationalEvent as StripeWebhookInformationalEvent, type index$1_TransactionContext as TransactionContext, type index$1_TransactionValueContext as TransactionValueContext, type index$1_TransportExtractor as TransportExtractor, type index$1_UCPCheckoutContext as UCPCheckoutContext, type index$1_UCPManifestValidationResult as UCPManifestValidationResult, type index$1_UCPRequestLike as UCPRequestLike, type index$1_UCPTotal as UCPTotal, type index$1_VIAllowedParty as VIAllowedParty, type index$1_VIBudgetLimit as VIBudgetLimit, type index$1_VIClaimsForValue as VIClaimsForValue, type index$1_VIConstraintEvalInput as VIConstraintEvalInput, type index$1_VIConstraints as VIConstraints, type index$1_VIExecutionMode as VIExecutionMode, type index$1_VIExtractedClaims as VIExtractedClaims, type index$1_VILayer as VILayer, type index$1_VILineItem as VILineItem, type index$1_VIMandateType as VIMandateType, type index$1_VIPaymentAmount as VIPaymentAmount, type index$1_VIRecurrence as VIRecurrence, type index$1_VIVerifyInput as VIVerifyInput, type index$1_VIVerifyResult as VIVerifyResult, type index$1_VerifyStripeWebhookOptions as VerifyStripeWebhookOptions, type index$1_VerifyStripeWebhookResult as VerifyStripeWebhookResult, type index$1_X402Kind as X402Kind, type index$1_X402RequestContext as X402RequestContext, type index$1_X402RequestForValue as X402RequestForValue, type index$1_X402RequestLike as X402RequestLike, type index$1_X402RequirementsSummary as X402RequirementsSummary, type index$1_X402ResponseLike as X402ResponseLike, index$1_applyCredentials as applyCredentials, index$1_bindIdentity as bindIdentity, index$1_claim as claim, index$1_clearTransportExtractors as clearTransportExtractors, index$1_createMastercardRegistry as createMastercardRegistry, index$1_createVisaRegistry as createVisaRegistry, index$1_createWebBotAuthRegistry as createWebBotAuthRegistry, index$1_detectProtocol as detectProtocol, index$1_evaluatePaymentMethodAllowlist as evaluatePaymentMethodAllowlist, index$1_evaluateSpendingLimit as evaluateSpendingLimit, index$1_evaluateVIConstraints as evaluateVIConstraints, index$1_extractA2ACredentials as extractA2ACredentials, index$1_extractACPContext as extractACPContext, index$1_extractACPTransactionValue as extractACPTransactionValue, index$1_extractAP2Mandate as extractAP2Mandate, index$1_extractAP2Mandates as extractAP2Mandates, index$1_extractAP2TransactionValue as extractAP2TransactionValue, index$1_extractCredentialsFromProtocol as extractCredentialsFromProtocol, index$1_extractHttpCredentials as extractHttpCredentials, index$1_extractMPPContext as extractMPPContext, index$1_extractMPPFromRequest as extractMPPFromRequest, index$1_extractMPPFromResponse as extractMPPFromResponse, index$1_extractMPPTransactionValue as extractMPPTransactionValue, index$1_extractMcpCredentials as extractMcpCredentials, index$1_extractUCPContext as extractUCPContext, index$1_extractUCPTransactionValue as extractUCPTransactionValue, index$1_extractVIClaims as extractVIClaims, index$1_extractVITransactionValue as extractVITransactionValue, index$1_extractX402Context as extractX402Context, index$1_extractX402FromRequest as extractX402FromRequest, index$1_extractX402FromResponse as extractX402FromResponse, index$1_extractX402TransactionValue as extractX402TransactionValue, index$1_fetchUCPManifest as fetchUCPManifest, index$1_getTransportExtractor as getTransportExtractor, index$1_getTransportExtractors as getTransportExtractors, index$1_isStripeWebhookInformational as isStripeWebhookInformational, index$1_mapACPRequestToPurpose as mapACPRequestToPurpose, index$1_mapAP2MandateToPurpose as mapAP2MandateToPurpose, index$1_mapMPPRequestToPurpose as mapMPPRequestToPurpose, index$1_mapRFC9421TagToPurpose as mapRFC9421TagToPurpose, index$1_mapUCPRequestToPurpose as mapUCPRequestToPurpose, index$1_mapVIMandateToPurpose as mapVIMandateToPurpose, index$1_mapX402RequestToPurpose as mapX402RequestToPurpose, index$1_parseRFC9421 as parseRFC9421, index$1_registerTransportExtractor as registerTransportExtractor, index$1_runCommercePipeline as runCommercePipeline, index$1_runMatchingExtractors as runMatchingExtractors, index$1_setA2AMetadata as setA2AMetadata, index$1_setHttpHeaders as setHttpHeaders, index$1_setMcpMeta as setMcpMeta, index$1_validateUCPManifest as validateUCPManifest, index$1_verifyACPSignature as verifyACPSignature, index$1_verifyAP2Chain as verifyAP2Chain, index$1_verifyMPP as verifyMPP, index$1_verifyRFC9421 as verifyRFC9421, index$1_verifyStripeWebhook as verifyStripeWebhook, index$1_verifyVIChain as verifyVIChain };
+}
+
+/**
+ * X-Astra-Verified-Hop — cross-hop verify-access dedupe marker.
+ *
+ * Header carrying upstream verify-access proof so an inner-hop endpoint can
+ * dedupe (skip verify-access when the same ASTRA-id was already verified a
+ * few ms earlier). Emitted by the MCP adapter toward tool fetches and by the
+ * edge gateway toward the origin at authenticate/authorize depth. Value
+ * format:
+ *
+ *   {astraId};{sessionId};{checkedAt-ms}
+ *
+ * Receivers MUST validate that `checkedAt` is recent (≤ 60s window
+ * recommended) and that `astraId` matches the agent identity claimed on the
+ * inner hop. The header alone is NOT proof-of-identity — it's an UNSIGNED
+ * dedupe advisory: trust it (`trustVerifiedHop`) only where every network
+ * path to the inner hop crosses a stripping gateway or an equivalent trusted
+ * boundary, exactly like the unsigned X-AstraSync-* attestation headers.
+ * Pair with the existing X-Astra-Id auth.
+ */
+declare const MCP_VERIFIED_HOP_HEADER = "X-Astra-Verified-Hop";
+/** Default acceptable age (ms) for an X-Astra-Verified-Hop header. */
+declare const MCP_VERIFIED_HOP_MAX_AGE_MS = 60000;
+interface VerifiedHopMarker {
+    astraId: string;
+    sessionId?: string;
+    checkedAt: number;
+}
+declare function serializeVerifiedHop(marker: VerifiedHopMarker): string;
+declare function parseVerifiedHop(value: string | undefined | null): VerifiedHopMarker | null;
+/**
+ * Returns true when `marker.astraId` matches the inner-hop's claimed
+ * ASTRA-id AND the marker is recent enough. Inner-hop middleware uses this
+ * to skip a duplicate verify-access call.
+ */
+declare function isVerifiedHopValidFor(marker: VerifiedHopMarker | null, expectedAstraId: string, opts?: {
+    maxAgeMs?: number;
+    now?: number;
+}): boolean;
+
+/**
+ * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
+ * agent-side `_meta.astrasync` block).
+ *
+ * Surfaces a body-aware policy hook the existing `createMiddleware` couldn't
+ * provide — MCP traffic is JSON-RPC over a single endpoint (`/mcp`), so the
+ * default route-pattern gating is too coarse: every request looks the same
+ * URL-wise, but `initialize` is low-risk handshake while `tools/call` of a
+ * payment tool is high-risk. Cohort-3 beta merchants flagged this 🟡 in the
+ * v2.9.5 round.
+ *
+ * What lives here:
+ *   - `parseMcpJsonRpc(body)`    — peels JSON-RPC method + tool name + agent
+ *                                   id without committing to a particular MCP
+ *                                   server framework.
+ *   - `mcpToPdlss(parsed)`       — canonical mapping JSON-RPC method → PDLSS
+ *                                   purpose / action / resource. Doc-stable
+ *                                   so audits can correlate.
+ *   - `mcpDefaultEnforced(parsed)` — whether a method is enforced by default
+ *                                   so a single MCP middleware can split
+ *                                   `initialize` / `tools/list` (pass-through)
+ *                                   from `tools/call` (enforced).
+ *   - `MCP_VERIFIED_HOP_HEADER`   — header convention for the dedupe pattern
+ *                                   when an MCP tool calls an inner REST hop.
+ *   - `serialize/parseVerifiedHop` helpers.
+ *
+ * The Express MCP adapter is in `adapters/mcp.ts` and consumes these.
+ */
+
+/**
+ * Output of `parseMcpJsonRpc`. Self-describing so the middleware doesn't have
+ * to re-introspect the body to figure out gating.
+ */
+interface ParsedMcpRequest {
+    /** JSON-RPC method (e.g. `tools/call`, `initialize`, `tools/list`). */
+    method: string;
+    /** Set when method === 'tools/call'; the tool name from `params.name`. */
+    toolName?: string;
+    /** Initialize-specific protocolVersion handshake info, when present. */
+    protocolVersion?: string;
+    /**
+     * Agent id read from the body, in priority order:
+     *   1. `params._meta.astrasync.agentId` (the canonical SDK location, see
+     *      `transport/mcp.ts → setMcpMeta`)
+     *   2. `params.arguments.agent_id` (legacy / hand-written tool callers)
+     * Header-supplied id (X-Astra-Id) is read separately by the adapter and
+     * compared to this for the mismatch check.
+     */
+    agentIdFromBody?: string;
+    /**
+     * Purpose extracted from the MCP body
+     * with the symmetric precedence chain. Sourced from `_meta.astrasync.purpose`
+     * (canonical SDK location) OR `params.arguments.purpose` (legacy /
+     * conventional callers). The discriminator is on `purposeSourceFromBody`.
+     * Adapter combines this with the `X-Astra-Purpose` header (header wins)
+     * before mapping; final fallback at `mcpToPdlss` is `undefined`.
+     */
+    purposeFromBody?: string;
+    /** Which body location resolved `purposeFromBody`. */
+    purposeSourceFromBody?: 'meta' | 'tool_argument';
+    /**
+     * Action extracted from the MCP body with the same
+     * symmetric chain as purpose. Sourced from `_meta.astrasync.action`
+     * (canonical) OR `params.arguments.action` (legacy). Adapter combines
+     * with the `X-Astra-Action` header (header wins) before mapping; final
+     * fallback at `mcpToPdlss` is the transport-layer default
+     * (`tools/call:<toolname>` or just `<method>`).
+     */
+    actionFromBody?: string;
+    /** Which body location resolved `actionFromBody`. */
+    actionSourceFromBody?: 'meta' | 'tool_argument';
+    /** True for handshake methods that must succeed before any tool call. */
+    isInitialize: boolean;
+    /** True for `tools/call`. */
+    isToolCall: boolean;
+    /** True for low-risk introspection (`tools/list`, `prompts/list`, etc.). */
+    isIntrospection: boolean;
+}
+
+/**
+ * AstraSync Universal Verification Gateway — MCP middleware
+ *
+ * Express-shaped middleware tailored to the JSON-RPC body of an MCP
+ * (Model Context Protocol) endpoint. Closes the cohort-3 gaps the default
+ * `createMiddleware` couldn't:
+ *
+ *   (a) **Body-aware gating**.  All MCP traffic targets the same `/mcp` URL.
+ *       The default route-pattern matcher can't tell `initialize` (low risk)
+ *       from `tools/call start_checkout` (high risk). This middleware peels
+ *       the JSON-RPC body and applies a per-method risk tier.
+ *
+ *   (b) **PDLSS mapping**.  Derives purpose, action, and resource from
+ *       `toolGates` config and request context. See `transport/mcp-server.ts`
+ *       `mcpToPdlss()` for the exact mapping.
+ *
+ *   (c) **Inner-hop dedupe**.  Outbound responses set
+ *       `X-Astra-Verified-Hop` so a downstream REST endpoint that the tool
+ *       calls can skip a duplicate verify-access. The receiving REST
+ *       middleware checks `parseVerifiedHop` and skips when valid.
+ *
+ *   (d) **Header-vs-body identity precedence**.  Reads ASTRA-id from
+ *       `X-Astra-Id` first, body second. If both are present and disagree,
+ *       returns a structured 400 by default (configurable). Pre-fix,
+ *       integrators had to re-discover this on their own.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import express from 'express';
+ * import { createMcpMiddleware } from '@astrasyncai/verification-gateway/mcp';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * app.post(
+ *   '/mcp',
+ *   createMcpMiddleware({
+ *     apiBaseUrl: 'https://astrasync.ai/api',
+ *     apiKey: process.env.ASTRASYNC_API_KEY,
+ *     // Per-tool gates — `tools/call` is enforced by default; introspection /
+ *     // handshake pass through. A gated tool needs a PDLSS purpose (and ideally
+ *     // an action). Set a tool/method to `'observe'` to pass it through
+ *     // unenforced (still evaluated when `evaluateAlwaysIfCredentialed`).
+ *     toolGates: {
+ *       browse_catalog: { purpose: 'shopping', action: 'shopping.search' },
+ *       start_checkout: { purpose: 'shopping', action: 'shopping.purchase' },
+ *       health_check: 'observe',
+ *     },
+ *   }),
+ *   yourMcpServerHandler,
+ * );
+ * ```
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            mcpRequest?: ParsedMcpRequest;
+            agentVerification?: VerificationResult;
+        }
+    }
+}
+/**
+ * Extended per-tool gate with optional PDLSS purpose + action + resource
+ * overrides.
+ *
+ * When `purpose` is set, it is authoritative for that tool — the agent's
+ * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
+ * semantic purpose each tool fulfils rather than trusting agent self-declaration.
+ *
+ * When `action` is set (symmetric with `purpose`), it is
+ * authoritative over `X-Astra-Action` / body declarations, letting the
+ * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
+ * whose callers would otherwise leave the action undeclared (purpose-only
+ * evaluation — raw tool names never travel as PDLSS actions).
+ *
+ * When `resource` is set, it overrides the default (`req.path`) for that
+ * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
+ */
+interface ToolGateConfig {
+    purpose?: string;
+    action?: string;
+    resource?: string;
+}
+/**
+ * A tool/method gate is either a {@link ToolGateConfig} (enforced — calls
+ * verify-access and gates on the server decision, using the declared PDLSS
+ * purpose/action) or the literal `'observe'` (passed through unenforced;
+ * still evaluated when `evaluateAlwaysIfCredentialed` is set). SDK 5.0.0
+ * removed the access-level band, so a gate no longer carries a tier — its
+ * only decision is enforce vs observe.
+ */
+type ToolGate = ToolGateConfig | 'observe';
+interface McpMiddlewareOptions extends GatewayConfig {
+    /**
+     * Per-tool gating for `tools/call` invocations. Tools not listed are
+     * enforced by default (`tools/call` calls verify-access and gates on the
+     * server decision).
+     *
+     * A gated tool declares its PDLSS `purpose` (required: the backend rejects
+     * gated calls with no resolvable purpose) and ideally a dotted-verb
+     * `action`:
+     * ```typescript
+     * toolGates: {
+     *   list_products:  { purpose: 'shopping',
+     *                     action: 'shopping.search',
+     *                     resource: '/api/catalog' },
+     *   start_checkout: { purpose: 'shopping',
+     *                     action: 'shopping.purchase',
+     *                     resource: '/api/checkout/*' },
+     *   health_check:   'observe',   // pass through unenforced
+     * }
+     * ```
+     *
+     * Set a tool to `'observe'` to pass it through without enforcement (it is
+     * still evaluated for the audit trail when `evaluateAlwaysIfCredentialed`
+     * is set). A gated object form with no resolvable purpose fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400 (the SDK never sends the raw tool name as
+     * the PDLSS action).
+     *
+     * The action axis for non-tools/call MCP methods (`tools/list`,
+     * `resources/list`, `prompts/list`, etc.) is the literal JSON-RPC method
+     * name (e.g. `'tools/list'`). Merchants gating MCP traffic by action should
+     * declare per-tool gates in `toolGates`, not endpoint-level `allowedActions`
+     * — the latter applies to REST-style action values, not MCP method strings.
+     */
+    toolGates?: Record<string, ToolGate>;
+    /**
+     * Per-method override. By default introspection / handshake methods
+     * (`tools/list`, `initialize`, `ping`, …) pass through and `tools/call` is
+     * enforced; declare a method here to enforce it (object form, with a PDLSS
+     * purpose) or set it to `'observe'` to pass it through. Matches by exact
+     * JSON-RPC method string.
+     */
+    methodGates?: Record<string, ToolGate>;
+    /**
+     * What to do when the agent id supplied in the X-Astra-Id header
+     * disagrees with the agent id in the JSON-RPC body
+     * (`params._meta.astrasync.agentId` or `params.arguments.agent_id`).
+     *
+     *   - `'reject'` (default) — return 400 `AGENT_ID_MISMATCH`. Safest.
+     *   - `'prefer-header'` — log + verify against the header value. Keeps
+     *     bodies that were authored before X-Astra-Id was the canonical
+     *     identity slot working.
+     *   - `'prefer-body'` — log + verify against the body value. Useful in
+     *     reverse-proxy setups that strip auth headers.
+     */
+    onAgentIdMismatch?: 'reject' | 'prefer-header' | 'prefer-body';
+    /** Skip verification + dedupe entirely. For testing. */
+    skip?: boolean;
+    /** Custom denied handler. Defaults to a structured JSON-RPC error response. */
+    onDenied?: (result: VerificationResult, req: Request, res: Response$1) => void;
+    /**
+     * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
+     * verify-access when it carries a recent marker for the resolved agent.
+     *
+     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13.** The marker
+     * is plaintext semicolon-delimited with no HMAC, so any client that sets
+     * the header (with the right format + fresh timestamp + matching ASTRA-id)
+     * skipped verify-access entirely. The per-process verify-access result
+     * cache already dedupes legitimate repeat calls — this optimization
+     * provided no additional savings, only a bypass surface.
+     *
+     * Set this to `true` ONLY if you control every upstream MCP hop that sets
+     * the header AND you trust the network path between hops (mTLS, internal
+     * VPC, etc.). For most installs, leave at the safe default.
+     *
+     * A future SDK release will either remove this option entirely OR add
+     * HMAC signing to the marker.
+     */
+    trustVerifiedHop?: boolean;
+    /** Window for accepting an upstream verified-hop marker. Default 60_000ms. */
+    verifiedHopMaxAgeMs?: number;
+    /**
+     * Automatically record grant/deny decisions for every MCP call. Default
+     * `true` — matches the express adapter.
+     */
+    recordDecisions?: boolean;
+    /** Forward runtime challenge (default `true`). */
+    enableRuntimeChallenge?: boolean;
+    /**
+     * 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.
+     */
+    failOnError?: 'open' | 'closed';
+}
+/**
+ * Create the MCP middleware. Attach AFTER `express.json()` — the body must
+ * already be a parsed object.
+ */
+declare function createMcpMiddleware(options: McpMiddlewareOptions): RequestHandler;
+
+/**
+ * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
+ *
+ * Fire-and-forget pre-fetch at middleware creation; first verify() awaits
+ * the in-flight promise if it hasn't resolved. 60-minute TTL with
+ * stale-while-revalidate background refresh.
+ */
+interface WellKnownAgenticCommerce {
+    registrationUrl: string;
+    documentationUrl: string;
+    verifyAccessUrl: string;
+    /** 5.1.0: hosted AstraSync MCP bridge endpoint (absent on self-hosted backends). */
+    mcpEndpoint?: string;
+    /** 5.1.0: bridge connector-discovery doc (absent on self-hosted backends). */
+    mcpDiscoveryUrl?: string;
+}
+/**
+ * Start a background fetch. Returns the promise for callers that need
+ * to await it (first verify() call).
+ */
+declare function prefetchWellKnown(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Get cached well-known URLs. If stale, triggers a background refresh
+ * and returns stale data (stale-while-revalidate). If no cache exists,
+ * awaits the in-flight fetch or starts a new one.
+ */
+declare function getWellKnownUrls(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Synchronous cache read — returns cached URLs or undefined.
+ * Never triggers a fetch. Used by verify() to avoid extra HTTP calls
+ * in the hot path; adapters are responsible for prefetching.
+ */
+declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCommerce | undefined;
+
+/** Configuration for the AstraSync SDK client. */
+interface AstraSyncConfig {
+    /** API key (kya_ prefixed). Used as Bearer token. */
+    apiKey?: string;
+    /** Email for email+password authentication. */
+    email?: string;
+    /** Password for email+password authentication. */
+    password?: string;
+    /** secp256k1 private key for crypto signing. Used WITH apiKey or email+password. */
+    privateKey?: string;
+    /**
+     * Base URL for the AstraSync API. Pass the bare ORIGIN — the SDK appends
+     * `/api/agents/...` for each call.
+     *
+     * - Production: `https://astrasync.ai` (default)
+     * - Staging: `https://staging.astrasync.ai`
+     *
+     * A trailing `/api` is tolerated for compatibility with the
+     * `GatewayConfig.apiBaseUrl` convention used by the verification gateway
+     * — if you pass `https://astrasync.ai/api` the SDK strips the suffix and
+     * emits a one-time console.warn so you can fix the source.
+     *
+     * Defaults to the `ASTRASYNC_API_URL` env var, then production.
+     */
+    baseUrl?: string;
+    /**
+     * Suppress the one-time console.warn emitted on baseUrl normalization,
+     * deprecation, or other non-fatal SDK conditions. Default: `false`
+     * (warnings emit). Set `true` in test runners or where logs are
+     * structured.
+     */
+    silent?: boolean;
+    /**
+     * When `true`, the SDK does NOT fall back to `process.env.ASTRASYNC_API_KEY`
+     * if `apiKey` is omitted. Set this when constructing the SDK inside a
+     * per-request handler (MCP tool, gateway adapter) where the host process
+     * has its own platform-attribution `ASTRASYNC_API_KEY` in env that must
+     * not silently substitute for user-supplied credentials. Without this
+     * flag, a no-credentials call from such a wrapper will silently
+     * authenticate as the host process and attribute the request to the
+     * wrong account.
+     *
+     * Default: `false` (backward compat — CLIs and scripts continue to
+     * pick up `ASTRASYNC_API_KEY` from env as before).
+     */
+    disableEnvFallback?: boolean;
+}
+/**
+ * Multi-protocol declarations the agent participates in.
+ * Promoted from `metadata.protocols[]` to a first-class field in agent-registration v1.0.0.
+ */
+type AgentProtocol = 'a2a' | 'acp' | 'ap2' | 'ucp' | 'mpp' | 'x402' | 'erc8004' | 'vi' | 'agentpay' | 'tap' | 'other';
+/** PDLSS purpose configuration. */
+interface PDLSSPurpose {
+    categories: string[];
+    allowedActions?: string[];
+    deniedActions?: string[];
+}
+/** PDLSS duration configuration. */
+interface PDLSSDuration {
+    startTime?: string | null;
+    endTime?: string | null;
+    timezone?: string | null;
+    maxSessionDuration?: number | null;
+    ttl?: number | null;
+    allowedDays?: number[] | null;
+    allowedHours?: {
+        start: number;
+        end: number;
+    } | null;
+}
+/** PDLSS limits configuration. */
+interface PDLSSLimits {
+    /** Autonomous Limit — spend up to this without asking; above it → step-up. */
+    autonomousThreshold?: number | null;
+    /** Hard Limit — above it the transaction is denied outright. (Wire key stays
+     * `approvalThreshold` because it is hashed on-chain; see adapter spec F3.) The
+     * old middle `stepUpThreshold` tier was enforcement-dead and has been removed —
+     * there are exactly two limits. */
+    approvalThreshold?: number | null;
+    maxTransactionsPerDay?: number | null;
+    maxTransactionsPerHour?: number | null;
+    maxTotalValue?: number | null;
+    currency?: string;
+}
+/** PDLSS scope configuration. */
+interface PDLSSScope {
+    resources?: string[];
+    resourceTypes?: string[];
+    jurisdictions?: string[];
+    excludedResources?: string[];
+    counterparties?: string[];
+    excludedCounterparties?: string[];
+}
+/** PDLSS self-instantiation configuration. */
+interface PDLSSSelfInstantiation {
+    allowed: boolean;
+    maxSubAgents?: number | null;
+    inheritPermissions?: boolean | null;
+    allowedPurposes?: string[] | null;
+    requireApproval?: boolean | null;
+    maxDepth?: number | null;
+}
+/** Full PDLSS configuration. */
+interface PDLSSConfig$1 {
+    purpose: PDLSSPurpose;
+    duration?: PDLSSDuration;
+    limits?: PDLSSLimits;
+    scope?: PDLSSScope;
+    selfInstantiation?: PDLSSSelfInstantiation;
+}
+/** Model metadata for registration. */
+interface ModelConfig {
+    modelName: string;
+    modelProvider: string;
+    modelType?: 'llm' | 'embedding' | 'image' | 'audio' | 'multimodal' | 'code' | 'other';
+    contextWindow?: number;
+    maxTokens?: number;
+}
+/** Framework metadata for registration. */
+interface FrameworkConfig {
+    frameworkName: string;
+    frameworkVersion: string;
+}
+/** Options for agent registration. */
+interface RegisterOptions {
+    name: string;
+    description?: string;
+    agentType?: string;
+    /**
+     * URL where your agent's verification-gateway SDK is mounted for runtime
+     * challenges. Optional — if omitted, your agent declares no runtime-challenge
+     * support and some counterparties may decline access requests. Mirrors the
+     * webUI "API endpoint" field.
+     */
+    apiEndpoint?: string;
+    model?: ModelConfig;
+    framework?: FrameworkConfig;
+    /** Multi-protocol declarations (e.g. ['acp', 'ap2', 'a2a']). First-class as of v1.0.0. */
+    protocols?: AgentProtocol[];
+    metadata?: Record<string, unknown>;
+    pdlss?: PDLSSConfig$1;
+}
+/**
+ * Optional blocking-mode flags for `register()`. When `waitForApproval` is
+ * true and the backend returns 202 pending, the SDK polls until the request
+ * resolves (approved → returns Agent; denied/expired → throws; timeout →
+ * throws). The default is non-blocking: the SDK returns the pending result
+ * immediately and the caller handles polling itself.
+ */
+interface WaitForApprovalOptions {
+    /** Block until the request resolves. Default: false. */
+    waitForApproval?: boolean;
+    /** How long to wait in blocking mode. Default: 600_000ms (10 min). */
+    timeoutMs?: number;
+    /** Poll cadence in blocking mode. Default: 5000ms. */
+    pollIntervalMs?: number;
+    /** Called once per poll while still pending; useful for progress UX. */
+    onPending?: (event: {
+        requestId: string;
+        ageMs: number;
+    }) => void;
+}
+/**
+ * Discriminated registration result.
+ *
+ * - `active`: synchronous path (crypto-keypair signature verified, or
+ *   email+password auth). `agent` is the live record.
+ * - `pending_approval`: API-key auth path. The owner has been notified by
+ *   email and a dashboard alert. Poll `pollUrl` or call
+ *   `sdk.pollRegistration(requestId)` to track progress, or re-call
+ *   `register` with `waitForApproval: true` to block.
+ */
+type RegisterResult = {
+    status: 'active';
+    agent: AgentRecord;
+    /** Backend advisories surfaced verbatim. */
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+} | {
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+    /** Backend advisories surfaced verbatim. */
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+/**
+ * Response shape from `pollRegistration(requestId)` and the internal poll
+ * loop. State `pending` means still awaiting owner; the others are terminal.
+ *
+ * On `state: 'approved'`, the response also carries the
+ * canonical `astraId` — the partner-facing public agent identity that all
+ * verify-access / verify/{id} surfaces accept. The `agent` (UUID) field
+ * stays owner-private and is kept for backward compat.
+ */
+interface PollRegistrationResult {
+    state: 'pending' | 'approved' | 'denied' | 'expired';
+    /**
+     * Canonical `ASTRA-…` id. Populated when `state === 'approved'`; `null`
+     * (or absent) otherwise. This is the identifier to pass to public
+     * verification surfaces — UUIDs from the register response are owner-
+     * private request handles and are rejected by verify-access in v2.4.3+.
+     */
+    astraId?: string | null;
+    agent?: AgentRecord;
+    reason?: string;
+}
+/**
+ * Response from agent registration (raw 201 body). Use {@link RegisterResult}
+ * for the consumer-facing shape returned from `sdk.register()`.
+ */
+interface RegistrationResponse {
+    success: boolean;
+    message: string;
+    data: {
+        agent: AgentRecord;
+    };
+    /**
+     * Backend-emitted advisories (e.g. `no_callback_endpoint`
+     * when apiEndpoint is omitted). Previously the SDK whitelisted five
+     * fields on the way out and dropped this. Surface verbatim on both 201
+     * and 202 register paths.
+     */
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+/** Raw 202 body — internal type, exposed via {@link RegisterResult}. */
+interface PendingRegistrationResponse {
+    success: true;
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+    /** Same advisories as 201 path. */
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+/** Agent record from the API. */
+interface AgentRecord {
+    kyaAgentId: string;
+    name: string;
+    description?: string;
+    agentType: string;
+    agentStatus: string;
+    trustScore: number;
+    astrasyncIdLevel1?: string | null;
+    tempId?: string | null;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Public agent verification response. */
+interface VerifyResponse {
+    success: boolean;
+    data: {
+        agentUuid: string;
+        agentName: string;
+        agentDescription: string;
+        agentTrustScore: number;
+        agentStatus: string;
+        ownerName?: string;
+    };
+}
+/** Health check response. */
+interface HealthResponse {
+    status: string;
+    service: string;
+    version: string;
+}
+/** Error response from the API. */
+interface ApiErrorResponse {
+    success: false;
+    error: string;
+    code?: string;
+    kydUrl?: string;
+    ownerNotified?: boolean;
+}
+
+/**
+ * AstraSync SDK client for registering and managing AI agents.
+ *
+ * @example
+ * ```typescript
+ * const client = new AstraSync({ apiKey: 'kya_your_api_key' });
+ * const result = await client.register({
+ *   name: 'My Agent',
+ *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },
+ * });
+ * ```
+ *
+ * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.
+ */
+declare class AstraSync {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly email?;
+    private readonly password?;
+    private readonly privateKey?;
+    private cachedJwt?;
+    private jwtExpiresAt?;
+    constructor(config?: AstraSyncConfig);
+    /**
+     * Register a new AI agent on the AstraSync KYA Platform.
+     *
+     * The backend response depends on auth context:
+     * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+     *   returns `{ status: 'active', agent }`.
+     * - **API-key only** (no signature): 202 pending, returns
+     *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+     *   owner is notified by email and a dashboard alert is emitted; the agent
+     *   becomes active only after the owner approves.
+     *
+     * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+     * request until it resolves, then return the live agent record. The promise
+     * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+     * `RegistrationTimeoutError` on the corresponding terminal states.
+     *
+     * @example Non-blocking (default — best for serverless / scheduled agents):
+     * ```typescript
+     * const result = await sdk.register({ name, pdlss });
+     * if (result.status === 'pending_approval') {
+     *   storeRequestId(result.requestId);
+     *   return; // function exits; resume later via pollRegistration()
+     * }
+     * ```
+     *
+     * @example Blocking (best for long-running services + CLI):
+     * ```typescript
+     * const agent = await sdk.register({
+     *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+     *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+     * });
+     * ```
+     */
+    register(options: RegisterOptions & WaitForApprovalOptions): Promise<RegisterResult | AgentRecord>;
+    /**
+     * Poll the current state of a pending-approval registration request.
+     *
+     * Useful for caller-driven polling when `waitForApproval: false` (the
+     * default). The endpoint is unauthenticated — pass the `requestId` that
+     * was returned from the 202 response.
+     *
+     * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+     *          minted agent in `agent`; `'denied'` may carry the owner's
+     *          `reason`; `'expired'` is terminal after 14 days.
+     */
+    pollRegistration(requestId: string): Promise<PollRegistrationResult>;
+    /**
+     * Block until a pending registration request resolves to a terminal state.
+     * Resolves to the live `AgentRecord` on approval; rejects with the matching
+     * Registration*Error on deny/expire/timeout. Usually called via
+     * `register({ waitForApproval: true })`, but exposed for callers that want
+     * to fire-and-forget the initial register call and resume waiting later
+     * (e.g. after restoring a stored `requestId` on cold start).
+     */
+    waitForApproval(requestId: string, options?: WaitForApprovalOptions): Promise<AgentRecord>;
+    /**
+     * Look up an agent's public profile by ASTRA ID or UUID.
+     */
+    verify(agentId: string): Promise<VerifyResponse>;
+    /**
+     * Check API health.
+     */
+    health(): Promise<HealthResponse>;
+    private request;
+    /**
+     * Variant of {@link request} that also returns the HTTP status code, so
+     * callers can branch on 201 vs 202 (or other success codes) without losing
+     * type information about the response body.
+     */
+    private requestWithStatus;
+    private getAuthToken;
+    /**
+     * Sign a request using secp256k1 (ethers.js).
+     * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY
+     * Must match apps/backend/src/services/signature-verify.service.ts exactly.
+     */
+    private signRequest;
+    /** Recursively sort object keys for canonical JSON representation. */
+    private sortObjectKeys;
+}
+
+/** Base error class for AstraSync SDK errors. */
+declare class AstraSyncError extends Error {
+    readonly code?: string;
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number, code?: string);
+}
+/** Thrown when KYD verification is required before agent registration. */
+declare class KYDRequiredError extends AstraSyncError {
+    readonly kydUrl: string;
+    readonly ownerNotified: boolean;
+    constructor(response: ApiErrorResponse);
+}
+/** Thrown when authentication fails. */
+declare class AuthenticationError extends AstraSyncError {
+    constructor(message: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the owner denies the
+ * pending registration request. The `reason` field, when present, mirrors the
+ * deny note the owner left in the dashboard.
+ */
+declare class RegistrationDeniedError extends AstraSyncError {
+    readonly requestId: string;
+    readonly reason?: string;
+    constructor(requestId: string, reason?: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the pending request
+ * passes its 14-day TTL with no owner decision. The agent must re-submit.
+ */
+declare class RegistrationExpiredError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the caller's local
+ * `timeoutMs` elapses before the owner makes a decision. The request is still
+ * live server-side — poll `pollRegistration(requestId)` to resume waiting, or
+ * call `waitForApproval` again with a longer timeout.
+ */
+declare class RegistrationTimeoutError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+
+/**
+ * Guidance envelope for credentials-required cases.
+ *
+ * A single shared source of truth so partners writing their own wrappers
+ * (custom MCP servers, Express middleware around registration, gateway
+ * adapters) consume a single source of truth instead of re-implementing the
+ * five-step boilerplate.
+ *
+ * The envelope is what an agent (or wrapping MCP client) sees when it calls
+ * `register_agent` with no AstraSync credentials. It tells the calling agent
+ * (a) what failed (`status: 'credentials_required'`), (b) the keyless
+ * registration ACTION endpoint (`registrationUrl` — POST-able, not the human
+ * dashboard), (c) where the relevant docs are (`documentationUrl`), and (d) the
+ * ordered next-actions (`steps`).
+ */
+interface GuidanceEnvelope {
+    /**
+     * Single-literal today. Expand to a union (e.g.
+     * `'credentials_required' | 'kyd_required' | …`) when a second guidance
+     * status emerges. Don't pre-emptively widen — the literal pins the shape.
+     */
+    status: 'credentials_required';
+    message: string;
+    guidance: {
+        message: string;
+        registrationUrl: string;
+        documentationUrl: string;
+        steps: string[];
+    };
+}
+interface BuildGuidanceParams {
+    /**
+     * Bare origin of the AstraSync deployment the caller should register at,
+     * e.g. `https://astrasync.ai` or `https://staging.astrasync.ai`. No
+     * trailing slash, no `/api` suffix — registrationUrl and documentationUrl
+     * are templated relative to this origin.
+     */
+    origin: string;
+    /**
+     * Overrides the top-level `message` (the short summary the agent sees).
+     * Defaults to the error message from the SDK's `AuthenticationError`
+     * when present, else a generic "credentials required" line.
+     */
+    message?: string;
+    /**
+     * Overrides the documentation path. Defaults to `/docs/agent-access`.
+     */
+    documentationPath?: string;
+}
+/**
+ * Build the credentials-required guidance envelope.
+ *
+ * This is the canonical builder — MCP wrappers (`agent-registration.ts`),
+ * Express middleware in custom integrations, and any other partner-side
+ * wrapper that needs to surface "you need to register" should call this
+ * rather than reconstructing the shape inline. Inline reconstruction
+ * historically led to drift between wrappers; this consolidates it.
+ *
+ * @example
+ * ```ts
+ * import { buildGuidance } from '@astrasyncai/verification-gateway';
+ *
+ * try {
+ *   const sdk = new AstraSync({ apiKey: callerApiKey, disableEnvFallback: true });
+ *   // ...
+ * } catch (err) {
+ *   if (err instanceof AuthenticationError) {
+ *     return buildGuidance({ origin: 'https://astrasync.ai', message: err.message });
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare function buildGuidance(params: BuildGuidanceParams): GuidanceEnvelope;
+
+/**
+ * AgentClient — Credential Presentation
+ *
+ * Agent-side SDK for automatically injecting AstraSync credentials
+ * into outgoing requests across all supported protocols.
+ */
+
+interface AgentClientConfig {
+    agentId: string;
+    verifyUrl?: string;
+    challengeUrl?: string;
+    pdlss?: AstraSyncCredentials['pdlss'];
+    /** Base URL for AstraSync API (used for ownership check). Defaults to https://astrasync.ai/api */
+    apiBaseUrl?: string;
+    /** API key used to authenticate ownership check + other authenticated calls. */
+    apiKey?: string;
+}
+interface FetchOptions extends RequestInit {
+    purpose?: string;
+    action?: string;
+}
+declare class AgentClient {
+    private credentials;
+    private apiBaseUrl;
+    private apiKey;
+    constructor(config: AgentClientConfig);
+    /**
+     * Async factory that validates the API key's account owns the configured
+     * ASTRA-id before returning a usable client. Refuses to initialise on
+     * mismatch so a stolen ASTRA-id cannot be paired with a valid (different)
+     * API key.
+     *
+     * Set env `ASTRASYNC_SKIP_OWNERSHIP_CHECK=true` to bypass — intended for
+     * test environments only.
+     */
+    static create(config: AgentClientConfig): Promise<AgentClient>;
+    /**
+     * Calls GET /api/agents/:astraId/ownership with the configured API key.
+     * Returns true only when the backend confirms this API key's account
+     * owns the configured agent.
+     */
+    private verifyOwnership;
+    /**
+     * Make an HTTP request with AstraSync headers automatically injected.
+     */
+    fetch(url: string, options?: FetchOptions): Promise<Response>;
+    /**
+     * Prepare A2A task metadata with AstraSync credentials.
+     */
+    prepareA2AMetadata(task: Record<string, unknown>, overrides?: {
+        purpose?: string;
+        action?: string;
+    }): Record<string, unknown>;
+    /**
+     * Prepare MCP params with AstraSync _meta.
+     */
+    prepareMcpMeta(params: Record<string, unknown>, overrides?: {
+        purpose?: string;
+        action?: string;
+    }): Record<string, unknown>;
+    /**
+     * Generic: apply credentials to any protocol.
+     */
+    applyCredentials(protocol: ProtocolTransport, target: Record<string, unknown>, overrides?: {
+        purpose?: string;
+        action?: string;
+    }): Record<string, unknown>;
+    private buildCredentials;
+}
+
+/**
+ * ChallengeHandler — Agent-Side Runtime Challenge Responder
+ *
+ * Handles incoming runtime challenges from AstraSync's verification service.
+ * Agents register pending counterparties before initiating contact,
+ * then this handler validates and responds to challenges.
+ */
+interface ChallengeResponse {
+    status: number;
+    body: {
+        challengeId: string;
+        acknowledged: boolean;
+        pendingCounterparties: string[];
+        respondedAt: string;
+        error?: string;
+    };
+}
+interface ChallengeHandlerConfig {
+    agentId: string;
+}
+declare class ChallengeHandler {
+    private agentId;
+    private pendingCounterparties;
+    constructor(config: ChallengeHandlerConfig);
+    /**
+     * Register a counterparty as pending (before initiating contact).
+     */
+    registerPending(counterpartyId: string): void;
+    /**
+     * Remove a counterparty from pending list (after interaction complete).
+     */
+    removePending(counterpartyId: string): void;
+    /**
+     * Get current pending counterparties list.
+     */
+    getPendingList(): string[];
+    /**
+     * Express middleware for the challenge endpoint.
+     * Mount at: app.post('/astrasync/challenge', handler.expressMiddleware())
+     */
+    expressMiddleware(): (req: {
+        body: unknown;
+    }, res: {
+        status: (code: number) => {
+            json: (body: unknown) => void;
+        };
+    }) => void;
+    /**
+     * Generic handler (framework-agnostic).
+     * Returns { status, body } for the caller to send.
+     */
+    handleChallenge(body: unknown): ChallengeResponse;
+}
+
+/**
+ * PDLSS Formatter — Transport Format Conversion
+ *
+ * Converts between full PDLSS boundaries and compact transport format
+ * used in HTTP headers, A2A metadata, and MCP _meta blocks.
+ */
+
+/**
+ * Full PDLSS configuration (as returned by the backend).
+ */
+interface PDLSSConfig {
+    purpose?: {
+        categories?: string[];
+        allowedActions?: string[];
+        deniedActions?: string[];
+    };
+    duration?: {
+        maxSessionDuration?: number;
+        ttl?: number;
+        allowedDays?: number[];
+        allowedHours?: {
+            start: number;
+            end: number;
+        };
+    };
+    limits?: {
+        autonomousThreshold?: number;
+        approvalThreshold?: number;
+        currency?: string;
+    };
+    scope?: {
+        jurisdictions?: string[];
+        resources?: string[];
+        resourceTypes?: string[];
+    };
+    selfInstantiation?: {
+        allowed: boolean;
+        maxDepth?: number;
+        maxSubAgents?: number;
+    };
+}
+/**
+ * Compact transport format (embedded in headers/metadata).
+ */
+type TransportPDLSS = NonNullable<AstraSyncCredentials['pdlss']>;
+/**
+ * Convert full PDLSS boundaries into compact transport format.
+ * Used by AgentClient when building credential headers/metadata.
+ */
+declare function formatPDLSSForTransport(pdlss: PDLSSConfig): TransportPDLSS;
+/**
+ * Parse transport format back into full PDLSS config.
+ * Used by counterparty-side when receiving credentials.
+ */
+declare function parsePDLSSFromTransport(transport: TransportPDLSS): PDLSSConfig;
+
+/**
+ * Decision Client — Counterparty-Side Decision Recording
+ *
+ * Helper for counterparties to record their grant/deny decisions
+ * back to AstraSync after receiving a verification result.
+ */
+
+interface RecordDecisionParams {
+    sessionId: string;
+    decision: 'granted' | 'denied';
+    reason?: string;
+    tokenIssued?: boolean;
+    auditId?: string;
+}
+interface RecordDecisionResult {
+    recorded: boolean;
+    blockchainTxHash?: string;
+}
+/**
+ * Record a counterparty's grant/deny decision for a verification session.
+ * POST to /agents/verify-access/:sessionId/decision
+ */
+declare function recordDecision(config: GatewayConfig, params: RecordDecisionParams): Promise<RecordDecisionResult>;
+
+/**
+ * Agent-side SDK errors.
+ */
+declare class AstraSyncSdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when the API key used to initialise AgentClient is not owned by
+ * the same account that registered the configured ASTRA-id. Blocks the
+ * client from doing anything under a mismatched identity.
+ */
+declare class OwnershipMismatchError extends AstraSyncSdkError {
+    readonly astraId: string;
+    constructor(astraId: string);
+}
+
+/**
+ * Agent-Side SDK Module
+ *
+ * Tools for AI agents to present credentials, handle challenges,
+ * and interact with the AstraSync verification protocol.
+ */
+
+type index_AgentClient = AgentClient;
+declare const index_AgentClient: typeof AgentClient;
+type index_AstraSyncSdkError = AstraSyncSdkError;
+declare const index_AstraSyncSdkError: typeof AstraSyncSdkError;
+type index_ChallengeHandler = ChallengeHandler;
+declare const index_ChallengeHandler: typeof ChallengeHandler;
+type index_OwnershipMismatchError = OwnershipMismatchError;
+declare const index_OwnershipMismatchError: typeof OwnershipMismatchError;
+type index_PDLSSConfig = PDLSSConfig;
+type index_TransportPDLSS = TransportPDLSS;
+declare const index_formatPDLSSForTransport: typeof formatPDLSSForTransport;
+declare const index_parsePDLSSFromTransport: typeof parsePDLSSFromTransport;
+declare const index_recordDecision: typeof recordDecision;
+declare namespace index {
+  export { index_AgentClient as AgentClient, index_AstraSyncSdkError as AstraSyncSdkError, index_ChallengeHandler as ChallengeHandler, index_OwnershipMismatchError as OwnershipMismatchError, type index_PDLSSConfig as PDLSSConfig, type index_TransportPDLSS as TransportPDLSS, index_formatPDLSSForTransport as formatPDLSSForTransport, index_parsePDLSSFromTransport as parsePDLSSFromTransport, index_recordDecision as recordDecision };
+}
+
+/**
+ * Edge verification config — the per-endpoint policy the Trusted Agent
+ * Gateway edge adapters (e.g. `@astrasyncai/adapter-lambda`) fetch from the
+ * AstraSync dashboard to decide how much verification friction to apply
+ * to inbound traffic, and where.
+ *
+ * Fetch pattern mirrors `well-known.ts`: TTL cache + stale-while-revalidate
+ * + in-flight dedupe, with a `_reset*` hook for tests. Fail posture is
+ * deliberately asymmetric: this module can NEVER put a site into enforce
+ * mode on its own — enforce only ever originates from a successfully
+ * fetched config, and a config that has gone stale past `maxStaleMs`
+ * degrades back to observe.
+ *
+ * Which EdgeConfig fields each integration consumes:
+ *
+ * | Field                          | Edge adapters | SDK adapters (express/nextjs/mcp) |
+ * | ------------------------------ | ------------- | --------------------------------- |
+ * | `mode` (observe/enforce)       | yes           | —                                 |
+ * | `depth`                        | yes           | —                                 |
+ * | `pathRules`                    | yes           | —                                 |
+ * | `sampling.anonymousBeaconRate` | yes           | yes — the SDK anonymous beacon    |
+ * | `failurePosture`               | yes           | —                                 |
+ *
+ * The observe/enforce × depth posture is EDGE-ONLY by design: SDK adapters
+ * enforce via the dashboard route policy (`fetchRoutes`), not via this
+ * config, and consume only the `sampling` block for their anonymous
+ * traffic beacon.
+ */
+
+/**
+ * Edge posture. Canonical Trusted Agent Gateway vocabulary:
+ * `observe` ≈ the gateway's `passive` posture (verify +
+ * record, enforce nothing), `enforce` ≈ `active`. New value set on a new
+ * field name — do NOT reuse `GatewayPosture`'s `active`/`passive` here
+ * (different field, different meaning: posture governs an agent-side
+ * gateway; mode governs counterparty-side edge interception).
+ */
+type EdgeMode = 'observe' | 'enforce';
+/**
+ * How deep the edge checks each request — what is it → who is it → are
+ * they allowed:
+ * - `classify`     — UA / platform-fingerprint classification only; no
+ *                    credential handling.
+ * - `authenticate` — establish who is calling: detect and parse agent
+ *                    credentials (X-Astra-*, VI SD-JWT, RFC 9421, ACP,
+ *                    UCP, AP2…) and verify presented AstraSync identities.
+ * - `authorize`    — full policy decision: credentials cryptographically
+ *                    proven and PDLSS-evaluated via a verify-access round
+ *                    trip. (US spelling on the wire, matching
+ *                    `authorizeSettlement` and HTTP `Authorization`.)
+ */
+type EdgeVerificationDepth = 'classify' | 'authenticate' | 'authorize';
+interface EdgePathRule {
+    /**
+     * `*`-wildcard glob matched against the request path. Matching is
+     * case-INsensitive and all regex metacharacters except `*` are
+     * escaped. (Deliberately diverges from the express adapter's
+     * `matchRoute`, which is historically case-sensitive by default —
+     * new surface ships case-insensitive matching as the default.)
+     */
+    pattern: string;
+    /** Pass the request through untouched (static assets); mode/depth ignored. */
+    skip?: boolean;
+    /** Override the top-level mode for this path. */
+    mode?: EdgeMode;
+    /** Override the top-level depth for this path. */
+    depth?: EdgeVerificationDepth;
+}
+interface EdgeConfig {
+    /** Shape version — bump on breaking changes. */
+    version: 1;
+    /** Default posture for paths no rule matches. */
+    mode: EdgeMode;
+    /** Default check depth for paths no rule matches. */
+    depth: EdgeVerificationDepth;
+    /** Ordered, first-match-wins. */
+    pathRules: EdgePathRule[];
+    sampling: {
+        /** Fraction (0..1) of anonymous-bot requests that emit a beacon. */
+        anonymousBeaconRate: number;
+    };
+    /**
+     * 4.5.0: the EFFECTIVE failure posture is derived from the effective
+     * mode — fail posture follows success posture. Observe fails open
+     * (unreachable backend = pass-through, site never breaks); enforce fails
+     * closed on verification-infrastructure failure (503
+     * `VERIFICATION_UNAVAILABLE`, retry-later — see edge-core/pipeline). This
+     * field is retained on the wire for adapter compatibility and as a future
+     * explicit override; it is not consulted by the 4.5.x pipeline. Note the
+     * distinction from CONFIG staleness: a config stale past 24h still has
+     * enforce degraded to observe (`degradeToObserve`) — that is config-trust
+     * hygiene, independent of runtime verification availability.
+     */
+    failurePosture: 'open' | 'closed';
+}
+/**
+ * The safe default: observe-only, classification depth, nothing enforced.
+ * Served by the backend when an endpoint has never been configured, and
+ * used by `getEdgeConfig` whenever no config can be fetched.
+ */
+declare const DEFAULT_EDGE_CONFIG: EdgeConfig;
+/** Structural guard for configs arriving over the wire. */
+declare function isEdgeConfig(value: unknown): value is EdgeConfig;
+interface FetchEdgeConfigSuccess {
+    edgeConfig: EdgeConfig;
+    etag?: string;
+}
+type FetchEdgeConfigResult = FetchEdgeConfigSuccess | {
+    notModified: true;
+} | null;
+/**
+ * Fetch the edge config for an endpoint from the AstraSync backend.
+ * `GET {apiBaseUrl}/endpoints/:counterpartyId/edge-config` with the same
+ * auth headers as `fetchRoutes`. Pass the cached `etag` to get a cheap
+ * `{ notModified: true }` on 304. Returns `null` on any failure —
+ * the caller decides how to fall back.
+ */
+declare function fetchEdgeConfig(config: Pick<GatewayConfig, 'apiBaseUrl' | 'apiKey'>, counterpartyId: string, opts?: {
+    etag?: string;
+    timeoutMs?: number;
+}): Promise<FetchEdgeConfigResult>;
+/** Copy of `config` with every enforce (top-level and per-rule) degraded to observe. */
+declare function degradeToObserve(config: EdgeConfig): EdgeConfig;
+/**
+ * Get the edge config for an endpoint, cached. Never throws, never blocks
+ * longer than one fetch.
+ *
+ * - Fresh cache (within `ttlMs`) → cached config, no network.
+ * - Stale cache → cached config immediately + background revalidate
+ *   (stale-while-revalidate). If the last successful fetch is older than
+ *   `maxStaleMs` (default 24h), any enforce is degraded to observe — a
+ *   long-dead backend can never keep a site enforcing.
+ * - No cache → await one fetch; on failure return `DEFAULT_EDGE_CONFIG`
+ *   (observe-only). Defaults never enforce.
+ */
+declare function getEdgeConfig(config: Pick<GatewayConfig, 'apiBaseUrl' | 'apiKey'>, counterpartyId: string, opts?: {
+    ttlMs?: number;
+    maxStaleMs?: number;
+}): Promise<EdgeConfig>;
+/**
+ * First-match-wins path-rule lookup. Case-insensitive `*` globs with all
+ * other regex metacharacters escaped (a literal `.` in a pattern matches
+ * only `.`). Returns `undefined` when no rule matches — the caller applies
+ * the config's top-level mode/depth.
+ */
+declare function matchEdgePathRule(rules: EdgePathRule[], path: string): EdgePathRule | undefined;
+/** Reset cache — for testing only. */
+declare function _resetEdgeConfigCache(): void;
+
+/**
+ * Platform-agent fingerprint signatures — the shared registry of known
+ * platform-agent UA / agent-card patterns (Claude / ChatGPT / Gemini /
+ * Cursor / Goose).
+ *
+ * Single source of truth, lifted verbatim from the backend's
+ * `platform-agent-detector.service` (which now imports detection from
+ * here): the backend's verify-access anonymous handler and the edge
+ * adapter (`@astrasyncai/adapter-lambda`) must classify identically or
+ * the three-tier visibility numbers drift between capture points.
+ *
+ * Pure regex — no Node built-ins, edge-safe. Detection is regex-only for
+ * v2.9 — TLS fingerprinting / behavioural signatures are deferred.
+ */
+type PlatformAgentVendor = 'claude' | 'chatgpt' | 'gemini' | 'cursor' | 'goose' | 'perplexity' | 'chatgpt-atlas' | 'perplexity-comet' | 'astrasync-sdk' | 'unknown';
+interface PlatformFingerprint {
+    vendor: PlatformAgentVendor;
+    /** A stable identifier used as the orphan-agent dedup key. */
+    fingerprintKey: string;
+    /** Human-readable name surfaced in the admin panel. */
+    displayName: string;
+}
+interface PlatformDetectionInput {
+    userAgent?: string;
+    agentCardUrl?: string;
+    /**
+     * A safe API-key format prefix observed on the caller's
+     * credential header (e.g. `sk-ant-api03`, `sk-proj`, `aiza`). A strong
+     * platform signal; never the secret. Matched against `apiKeyFormatPatterns`.
+     */
+    apiKeyFormat?: string;
+    /**
+     * The sanitised platform-signal headers (lowercased names →
+     * values), e.g. `openai-organization`, `x-goog-user-project`. Matched
+     * against `headerPatterns` (which test on `name` and `name: value`).
+     */
+    platformHeaders?: Record<string, string>;
+    /**
+     * The caller's JA4 TLS-client fingerprint (from the connection capture).
+     * Matched against `ja4Patterns`. A JA4 identifies the client TLS stack,
+     * so signatures should pair it with other evidence when attributing a
+     * vendor.
+     */
+    ja4?: string;
+    /**
+     * The caller's origin ASN (from the connection capture). Matched against
+     * `asnList` by exact membership. An ASN alone attributes an entire cloud
+     * provider — registry validation rejects ASN-only signatures.
+     */
+    asn?: string;
+}
+/**
+ * A signature definition, generic over the vendor key. The seed constant
+ * below uses the closed `PlatformAgentVendor` union; DB-promoted signatures
+ * (backend dynamic registry, console round) carry arbitrary string vendors —
+ * `matchPlatformSignature` accepts both.
+ */
+interface PlatformSignatureDef<V extends string = string> {
+    vendor: V;
+    displayName: string;
+    uaPatterns?: RegExp[];
+    agentCardPatterns?: RegExp[];
+    /**
+     * Patterns tested against an observed API-key format prefix
+     * (e.g. `/^sk-ant/i` → claude). A credential-header format is a stronger
+     * platform signal than a spoofable User-Agent.
+     */
+    apiKeyFormatPatterns?: RegExp[];
+    /**
+     * Patterns tested against each observed platform-signal
+     * header, as both `name` and `name: value` (so `/openai-organization/i` and
+     * `/x-goog-user-project/i` match on presence).
+     */
+    headerPatterns?: RegExp[];
+    /** Patterns tested against the observed JA4 TLS-client fingerprint. */
+    ja4Patterns?: RegExp[];
+    /** Exact ASN strings this signature matches (never regex). */
+    asnList?: string[];
+}
+/**
+ * A fingerprint whose vendor may be a dynamically-promoted (non-seed) key.
+ * Structurally a superset of `PlatformFingerprint`.
+ */
+interface DynamicPlatformFingerprint {
+    vendor: string;
+    fingerprintKey: string;
+    displayName: string;
+}
+/**
+ * Registry of known platform-agent signatures. Order matters — first match wins.
+ *
+ * Patterns are intentionally permissive (case-insensitive substring match) since
+ * platform UA strings drift between versions. False positives are tolerable —
+ * the orphan record is informational, not enforcement.
+ */
+declare const PLATFORM_AGENT_SIGNATURES: ReadonlyArray<PlatformSignatureDef<PlatformAgentVendor>>;
+/**
+ * Generic first-match-wins matcher over an arbitrary signature set. The
+ * backend's dynamic registry merges the seed constant with DB-promoted
+ * signatures and calls this — ONE matching implementation everywhere
+ * (fingerprint-key rule included: vendor + lowercased UA basename before
+ * the first space/slash, falling back to the agent-card host).
+ */
+declare function matchPlatformSignature(signatures: ReadonlyArray<PlatformSignatureDef>, input: PlatformDetectionInput): DynamicPlatformFingerprint | undefined;
+/**
+ * Inspect caller metadata for a known SEED platform-agent fingerprint.
+ * Returns undefined if no signature matches. (Backends with the dynamic
+ * registry should call `matchPlatformSignature` over their merged set
+ * instead — same semantics, live signature additions included.)
+ */
+declare function detectPlatformFingerprint(input: PlatformDetectionInput): PlatformFingerprint | undefined;
 
 /**
  * HTTP-client RUNTIME signatures — a display-only vocabulary, disjoint from
@@ -177,7 +4641,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.4.0";
+declare const SDK_USER_AGENT = "astrasync-sdk/5.4.1";
 declare const sdkFetch: typeof fetch;
 
 /**
@@ -198,6 +4662,6 @@ declare const sdkFetch: typeof fetch;
  * is fine — bumping both in the release-ceremony commit keeps them
  * lockstep.
  */
-declare const SDK_VERSION = "5.4.0";
+declare const SDK_VERSION = "5.4.1";
 
-export { EnhancedVerificationResult, GatewayConfig, RUNTIME_SIGNATURES, type RuntimeSignature, SDK_USER_AGENT, type SettlementDecision, type SettlementRequest, StepUpApprovalInfo, StepUpApprovalStatus, StepUpOutcome, SDK_VERSION as VERSION, type WellKnownAgenticCommerce, authorizeSettlement, awaitStepUpApproval, detectRuntime, getCachedWellKnownUrls, getWellKnownUrls, pollStepUpStatus, prefetchWellKnown, sdkFetch };
+export { AgentClient, type AgentCredentials, type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, type AstraSyncCredentials, AstraSyncError, 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, DEFAULT_EDGE_CONFIG, type DynamicPlatformFingerprint, type EdgeConfig, type EdgeMode, type EdgePathRule, type EdgeVerificationDepth, type EnhancedVerificationResult, type ExpressMiddlewareOptions, type FetchEdgeConfigResult, type FetchEdgeConfigSuccess, type FiatSettlementBinding, type FrameworkConfig, type GatewayConfig, type GuidanceEnvelope, type GuidanceInfo, type HealthResponse, KYDRequiredError, MAX_HEADERS, MAX_HEADER_VALUE_BYTES, MAX_TOTAL_BYTES, MCP_VERIFIED_HOP_HEADER, MCP_VERIFIED_HOP_MAX_AGE_MS, type McpMiddlewareOptions, type ModelConfig, 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 PlatformAgentVendor, type PlatformDetectionInput, type PlatformFingerprint, type PlatformSignatureDef, type PollRegistrationResult, type ProtocolTransport, RUNTIME_SIGNATURES, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type RouteAccessConfig, type RuntimeChallengeResult, type RuntimeSignature, type SDKOptions, SDK_USER_AGENT, type SanitizeHeadersResult, type SettlementArtifact, type SettlementArtifactBinding, type SettlementArtifactBindingBase, type SettlementDecision, type SettlementOutcomeInfo, type SettlementRequest, type StablecoinSettlementBinding, type StepUpApprovalInfo, type StepUpApprovalStatus, type StepUpOutcome, TRUST_LEVEL_RANGES, type TokenGuidance, type ToolGate, type ToolGateConfig, type TrustLevel, SDK_VERSION as VERSION, type VerificationInterstitialProps, type VerificationRequest, type VerificationResult, type VerifiedAgent, type VerifiedDeveloper, type VerifiedHopMarker, type VerifiedOrganization, type VerifyOptions, type VerifyResponse, type WaitForApprovalOptions, type WellKnownAgenticCommerce, _resetEdgeConfigCache, index as agent, authorizeSettlement, awaitStepUpApproval, buildGuidance, buildSdkObservedMetadata, clearCache, createMcpMiddleware, degradeToObserve, deriveConnectionFromHeaders, detectPlatformFingerprint, detectRuntime, express, extractApiKeyFormat, extractCredentials, extractMcpCredentials, extractPlatformHeaders, fetchEdgeConfig, fetchRoutes, getCachedWellKnownUrls, getEdgeConfig, getTrustLevel, getWellKnownUrls, hasCredentials, isEdgeConfig, isVerifiedHopValidFor, matchEdgePathRule, matchPlatformSignature, nextjs, parseVerifiedHop, pollStepUpStatus, prefetchWellKnown, quickVerify, recordDecision, reportAttempt, reportUnregisteredAttempt, sanitizeHeaders, sdk, sdkFetch, serializeVerifiedHop, setMcpMeta, index$1 as transport, verify };