@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/types-Bd2O3eX1.d.mts

@@ -0,0 +1,769 @@
+import { ObservedMetadata } from './metadata-capture.mjs';
+
+/**
+ * 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;
+}
+/**
+ * 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;
+    };
+}
+/**
+ * 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';
+    };
+}
+
+export type { AgentCredentials as A, CommerceArtifactsPayload as C, GatewayConfig as G, TokenGuidance as T, VerificationRequest as V, AttemptReport as a, CounterpartyType as b, VerificationResult as c };