@astrasyncai/verification-gateway 4.0.0 → 4.2.0

package/dist/{types-CHKCgDFC.d.ts → types-BLUx92FJ.d.ts}

@@ -1,4 +1,4 @@
-import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-fTQD448H.js';
+import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-sMxBT-nM.js';
 
 /**
  * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.

package/dist/{types-DfnP7JiM.d.mts → types-DqfPU5Bl.d.mts}

@@ -1,4 +1,4 @@
-import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-BcDf9Kk0.mjs';
+import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-r850cOt0.mjs';
 
 /**
  * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.

package/dist/{types-BcDf9Kk0.d.mts → types-r850cOt0.d.mts}

@@ -16,14 +16,13 @@ type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
  * in `access.accessLevel`. SDK reads them verbatim (no client-side remap).
  *
  * For ANONYMOUS / unverified callers, the level is determined by the
- * endpoint's `unverifiedAgentPolicy` per the verify-access canonical flow
- * (see `docs/research/adapter-architecture-technical-requirements.md` §21):
- * - Branch A (deny): `none` — caller is denied + advised to register
- * - Branch B (allow_partial): `restricted` — reduced/browse-only access + advised
- * - Branch C (allow_full): `standard` — unrestricted + advised to register for next time
+ * endpoint's `unverifiedAgentPolicy` per the verify-access canonical flow:
+ * - deny: `none` — caller is denied + advised to register
+ * - allow_partial: `restricted` — reduced/browse-only access + advised
+ * - allow_full: `standard` — unrestricted + advised to register for next time
  * Every branch ALWAYS emits a verification event + queues a blockchain record.
  *
- * For VERIFIED callers (Branch D), the level is resolved server-side from the
+ * For VERIFIED callers, the level is resolved server-side from the
  * agent's live trust score plus the endpoint's `trust_score_requirement`:
  * - none: agent below endpoint gate (denied; access.allowed=false)
  * - restricted: 0–19 trust score (registration-prompt only, no real capability)
@@ -32,17 +31,14 @@ type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
  * - full: 70+ trust score (PDLSS-scoped, high-trust)
  * - internal: same-org membership, regardless of score
  *
- * v2.3.9 (defect #30): renamed `'guidance'` band → `'restricted'`. The old
- * name collided with the `guidance: {registrationUrl, ...}` help-payload
- * object on VerificationResult; in the !apiResponse.access?.allowed branch
- * of verify.ts, hardcoded `accessLevel: 'guidance'` plus colocated
- * `guidance: {...}` read as internally consistent on review while at
- * runtime `hasMinimumAccess('guidance', 'guidance') === true` let denied
- * requests pass any route gated at `'guidance'`. Banded vocabulary stays
- * capability-noun (none / restricted / read-only / standard / full /
- * internal); response-shape descriptors stay nouns (guidance, advisory).
- * Defensive `!result.identityVerified || !result.policyAllowed` short-circuit
- * also added in adapters as belt-and-braces (round-18 G4 split).
+ * v2.3.9 renamed the `'guidance'` band → `'restricted'`. The old name
+ * collided with the `guidance: {registrationUrl, ...}` help-payload object
+ * on VerificationResult, and the collision let denied requests pass any
+ * route gated at `'guidance'` (`hasMinimumAccess('guidance', 'guidance')
+ * === true`). Banded vocabulary stays capability-noun (none / restricted /
+ * read-only / standard / full / internal); response-shape descriptors stay
+ * nouns (guidance, advisory). Adapters additionally short-circuit on
+ * `!result.identityVerified || !result.policyAllowed` as belt-and-braces.
  */
 type AccessLevel = 'none' | 'restricted' | 'read-only' | 'standard' | 'full' | 'internal';
 /**
@@ -136,12 +132,11 @@ interface GatewayConfig {
      */
     disableInitChecks?: boolean;
     /**
-     * Audit F-A6-33: 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.
+     * 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;
     /**
@@ -158,9 +153,9 @@ interface GatewayConfig {
      * tests assert "this endpoint should be gated; if it falls through, fail
      * loudly". Default off; opt-in.
      *
-     * Round-10 (#49, O10): 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
+     * 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;
@@ -168,13 +163,11 @@ interface GatewayConfig {
      * 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 currently resolve —
-     * audit F-PROBE-01).
+     * subdomain referenced in older docs does not resolve).
      */
     dashboardUrl?: string;
     /**
-     * Round-12 (F9, express) / round-13 (R13-5, mcp parity): when true, the
-     * middleware calls verify-access for any request that presents
+     * When true, the middleware calls verify-access for any request that presents
      * AstraSync credentials, even on routes / MCP risk-tiers with
      * `minAccessLevel: 'none'`. Populates `req.agentVerification` and
      * records the verification event for the audit trail. Enforcement
@@ -399,7 +392,7 @@ interface SettlementArtifact {
 /**
  * Single failed gate on a verify-access denial. Aggregated into
  * `VerificationResult.failures[]` so partners can see every blocker in one
- * response. v2.9.8 (defect M1) — pre-fix the response was fail-fast on the
+ * 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.
  *
@@ -417,19 +410,19 @@ interface AccessFailure {
 }
 interface VerificationResult {
     /**
-     * Round-18 (G4): identity-verification status — was the caller successfully
+     * 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 round-17-and-earlier `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.
+     * 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;
     /**
-     * Round-18 (G4): does the endpoint's PDLSS / access policy permit this
+     * 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.
@@ -457,17 +450,15 @@ interface VerificationResult {
      */
     failures?: AccessFailure[];
     /**
-     * Round-10 (#47, O5): correlation handle for tying a partner-visible
-     * denial to a server-side log line. Hoisted here from
-     * `EnhancedVerificationResult` so adapter onDenied handlers can surface
-     * it on the merchant's response body. Present on anonymous server
-     * responses, on synthesised stubs for API-error fallbacks
-     * (`createGuidanceResponse`), and on the new
-     * `verify_access.internal_error` 200-shaped failure shape.
+     * 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 (Trust Record, §33.5 #3): attempt-chain handle, server-echoed on
+     * 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
@@ -528,11 +519,12 @@ interface CallerMetadata {
     agentCardUrl?: string;
     /**
      * The full sanitised view of the agent's inbound request headers + connection
-     * signals (Workstream D — maximal metadata capture). 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.
+     * 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;
 }
@@ -590,7 +582,7 @@ interface VerificationRequest {
         timeoutOverride?: number;
     };
     /**
-     * Round-12 (F19): transport protocol marker. Set by the MCP middleware
+     * 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
@@ -598,26 +590,26 @@ interface VerificationRequest {
      */
     invocationProtocol?: 'rest' | 'mcp' | 'a2a' | 'acp' | 'ap2' | 'mpp' | 'ucp';
     /**
-     * 3.9.0 (§33.5 #1) — raw commerce-protocol artifacts forwarded verbatim
-     * to verify-access, whose Step 0.5 commerce pipeline runs the full
+     * 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
-     * (bridge-is-transport: verify-access is the sole verification sink, so
-     * every decision is recorded once, with events). Shape mirrors the
-     * backend's `commerceArtifacts` schema 1:1.
+     * (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 (Trust Record, §33.5 #3) — attempt-chain handle correlating the
+     * 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 (see `getCacheKey`).
+     * from the verify cache key.
      */
     attemptId?: string;
     /**
-     * 3.12.0 (Trust Record, §33.5 #3) — first-party observational data: the
+     * 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).
@@ -625,7 +617,7 @@ interface VerificationRequest {
     considerationSet?: ConsiderationSet;
 }
 /**
- * One offer the agent evaluated (Trust Record, §33.5 #3). Mirrors the
+ * 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.
  */
@@ -646,8 +638,8 @@ interface ConsiderationItem {
     notChosenReason?: 'price' | 'policy' | 'trust_threshold' | 'stock' | 'other';
 }
 /**
- * The set of offers evaluated at one funnel checkpoint (Trust Record,
- * §33.5 #3). Mirrors the backend's `considerationSetSchema` 1:1.
+ * 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
@@ -665,8 +657,7 @@ interface ConsiderationSet {
 }
 /**
  * Terminal (or notable) outcome of an attempt chain, reported post-hoc via
- * `reportAttempt` (Trust Record, §33.5 #3). Mirrors the backend's
- * `attemptReportSchema.outcome` 1:1.
+ * `reportAttempt`. Mirrors the backend's `attemptReportSchema.outcome` 1:1.
  */
 interface AttemptOutcome {
     kind: 'settled' | 'blocked_step_up' | 'failed' | 'high_value_action';
@@ -684,8 +675,8 @@ interface AttemptOutcome {
     rail?: string;
 }
 /**
- * Body for `POST /agents/verify-access/attempt-report` (Trust Record,
- * §33.5 #3): post-hoc consideration/outcome data for an attempt chain that a
+ * 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`.
@@ -774,7 +765,7 @@ interface RouteAccessConfig {
     /** HTTP method (or * for all) */
     method: string | '*';
     /**
-     * @deprecated 3.2.0 — the access-level band no longer gates (post-3.1.0 #1).
+     * @deprecated 3.2.0 — the access-level band no longer gates.
      * Optional/ignored; retained for back-compat. Use `minTrustScore` to tighten.
      */
     minAccessLevel?: AccessLevel;
@@ -792,13 +783,13 @@ interface RouteAccessConfig {
     /** Maximum transaction value for this route */
     maxTransactionValue?: number;
     /**
-     * Backend-evaluator strict mode (audit F-A1-09): when true AND
+     * 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 (Bug 14, §4.6) — not an allow-list: the PDLSS tokens the
+     * 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
@@ -827,8 +818,8 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
     extractPurpose?: (req: unknown) => string | undefined;
     /**
      * Function to extract the PDLSS action from a request — symmetric with
-     * `extractPurpose` (Bug 14, §4.6: the action axis previously had NO
-     * override and hardwired the HTTP verb). When configured it masks the
+     * `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.
@@ -873,28 +864,39 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
      *
      * 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. SDK 2.4.x reads
-     * the shadow logs across the 1-week observation window; the default
-     * flips to `'closed'` in a follow-up release once <0.1% of throws appear
-     * to be legitimate-traffic regressions.
+     * 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 (audit F-A1-06).
+     * default flip by setting this explicitly.
      */
     failOnError?: 'open' | 'closed';
     /**
-     * When true, route-pattern matching is case-insensitive (audit F-A6-31,
-     * round-18.6.5 Finding #1 from astrasync.shop). Default false in SDK
-     * 2.4.13 for backward compatibility; shadow logs record divergences so
-     * merchants can preview impact before flipping. Follow-up release makes
-     * case-insensitive the default after 1-week observation confirms <5
-     * merchants with divergence-events.
+     * 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;
 }
 /**
  * Next.js middleware options.
@@ -907,9 +909,15 @@ interface NextJsMiddlewareOptions extends GatewayConfig {
     skipPaths?: string[];
     /** Refresh interval (ms) for the remote-fetched route policy. Default: 5 minutes. */
     routesRefreshMs?: number;
-    /** Whether to show Commerce Shield overlay for unverified */
+    /**
+     * 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;
-    /** Commerce Shield configuration */
+    /** Verification interstitial configuration */
     commerceShield?: {
         title?: string;
         message?: string;
@@ -918,6 +926,13 @@ interface NextJsMiddlewareOptions extends GatewayConfig {
     };
     /** 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
@@ -1023,10 +1038,11 @@ interface AstraSyncCredentials {
  */
 type ProtocolTransport = 'http' | 'a2a' | 'mcp';
 /**
- * Commerce Shield UI props
+ * Verification interstitial UI props (the React overlay shown to unverified
+ * agents; user-visible title stays "AstraSync Agent Verification").
  */
-interface CommerceShieldProps {
-    /** Whether the shield is visible */
+interface VerificationInterstitialProps {
+    /** Whether the interstitial is visible */
     visible: boolean;
     /** Verification result (if any) */
     result?: VerificationResult;
@@ -1045,5 +1061,7 @@ interface CommerceShieldProps {
     /** Custom styles */
     className?: string;
 }
+/** @deprecated Renamed VerificationInterstitialProps in 4.1.0; alias removed next major. */
+type CommerceShieldProps = VerificationInterstitialProps;
 
-export type { AccessFailure as A, CallerMetadata as C, EnhancedVerificationResult as E, FiatSettlementBinding as F, GatewayConfig as G, NextJsMiddlewareOptions as N, PDLSSInfo as P, RouteAccessConfig as R, SDKOptions as S, TokenGuidance as T, VerificationRequest as V, AccessLevel as a, AgentCredentials as b, AstraSyncCredentials as c, AttemptOutcome as d, AttemptReport as e, CommerceArtifactsPayload as f, CommerceShieldProps as g, ConsiderationItem as h, ConsiderationSet as i, CounterpartyType as j, ExpressMiddlewareOptions as k, GuidanceInfo as l, ProtocolTransport as m, RuntimeChallengeResult as n, SettlementArtifact as o, SettlementArtifactBinding as p, SettlementArtifactBindingBase as q, StablecoinSettlementBinding as r, StepUpApprovalInfo as s, StepUpApprovalStatus as t, StepUpOutcome as u, TrustLevel as v, VerificationResult as w, VerifiedAgent as x, VerifiedDeveloper as y, VerifiedOrganization as z };
+export type { AccessFailure as A, VerifiedOrganization as B, CallerMetadata as C, EnhancedVerificationResult as E, FiatSettlementBinding as F, GatewayConfig as G, NextJsMiddlewareOptions as N, PDLSSInfo as P, RouteAccessConfig as R, SDKOptions as S, TokenGuidance as T, VerificationInterstitialProps as V, AccessLevel as a, AgentCredentials as b, AstraSyncCredentials as c, AttemptOutcome as d, AttemptReport as e, CommerceArtifactsPayload as f, CommerceShieldProps as g, ConsiderationItem as h, ConsiderationSet as i, CounterpartyType as j, ExpressMiddlewareOptions as k, GuidanceInfo as l, ProtocolTransport as m, RuntimeChallengeResult as n, SettlementArtifact as o, SettlementArtifactBinding as p, SettlementArtifactBindingBase as q, StablecoinSettlementBinding as r, StepUpApprovalInfo as s, StepUpApprovalStatus as t, StepUpOutcome as u, TrustLevel as v, VerificationRequest as w, VerificationResult as x, VerifiedAgent as y, VerifiedDeveloper as z };