@astrasyncai/verification-gateway 3.12.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +106 -29
  2. package/dist/adapter-interface/interface.d.mts +2 -2
  3. package/dist/adapter-interface/interface.d.ts +2 -2
  4. package/dist/adapters/express.d.mts +2 -2
  5. package/dist/adapters/express.d.ts +2 -2
  6. package/dist/adapters/express.js +482 -22
  7. package/dist/adapters/express.js.map +1 -1
  8. package/dist/adapters/express.mjs +482 -22
  9. package/dist/adapters/express.mjs.map +1 -1
  10. package/dist/adapters/http-pdlss.d.mts +3 -3
  11. package/dist/adapters/http-pdlss.d.ts +3 -3
  12. package/dist/adapters/http-pdlss.js.map +1 -1
  13. package/dist/adapters/http-pdlss.mjs.map +1 -1
  14. package/dist/adapters/mcp.d.mts +56 -36
  15. package/dist/adapters/mcp.d.ts +56 -36
  16. package/dist/adapters/mcp.js +309 -10
  17. package/dist/adapters/mcp.js.map +1 -1
  18. package/dist/adapters/mcp.mjs +309 -10
  19. package/dist/adapters/mcp.mjs.map +1 -1
  20. package/dist/adapters/nextjs.d.mts +2 -2
  21. package/dist/adapters/nextjs.d.ts +2 -2
  22. package/dist/adapters/nextjs.js +518 -25
  23. package/dist/adapters/nextjs.js.map +1 -1
  24. package/dist/adapters/nextjs.mjs +518 -25
  25. package/dist/adapters/nextjs.mjs.map +1 -1
  26. package/dist/adapters/sdk.d.mts +2 -2
  27. package/dist/adapters/sdk.d.ts +2 -2
  28. package/dist/adapters/sdk.js +72 -9
  29. package/dist/adapters/sdk.js.map +1 -1
  30. package/dist/adapters/sdk.mjs +72 -9
  31. package/dist/adapters/sdk.mjs.map +1 -1
  32. package/dist/agent/index.d.mts +2 -2
  33. package/dist/agent/index.d.ts +2 -2
  34. package/dist/agent/index.js.map +1 -1
  35. package/dist/agent/index.mjs.map +1 -1
  36. package/dist/bin/astrasync-claude-hook.js +83 -20
  37. package/dist/bin/astrasync-codex-hook.js +83 -20
  38. package/dist/bin/astrasync-guard.js +83 -20
  39. package/dist/bin/astrasync.js +150 -33
  40. package/dist/browser/background.js +83 -20
  41. package/dist/browser/background.js.map +1 -1
  42. package/dist/browser/background.mjs +83 -20
  43. package/dist/browser/background.mjs.map +1 -1
  44. package/dist/browser/browser-adapter.d.mts +2 -2
  45. package/dist/browser/browser-adapter.d.ts +2 -2
  46. package/dist/claude-code/claude-code-adapter.d.mts +2 -2
  47. package/dist/claude-code/claude-code-adapter.d.ts +2 -2
  48. package/dist/cli/index.d.mts +2 -2
  49. package/dist/cli/index.d.ts +2 -2
  50. package/dist/codex/index.d.mts +3 -3
  51. package/dist/codex/index.d.ts +3 -3
  52. package/dist/codex/index.js +83 -20
  53. package/dist/codex/index.js.map +1 -1
  54. package/dist/codex/index.mjs +83 -20
  55. package/dist/codex/index.mjs.map +1 -1
  56. package/dist/cursor/cursor-adapter.d.mts +2 -2
  57. package/dist/cursor/cursor-adapter.d.ts +2 -2
  58. package/dist/cursor/extension.d.mts +2 -2
  59. package/dist/cursor/extension.d.ts +2 -2
  60. package/dist/cursor/extension.js +83 -20
  61. package/dist/cursor/extension.js.map +1 -1
  62. package/dist/cursor/extension.mjs +83 -20
  63. package/dist/cursor/extension.mjs.map +1 -1
  64. package/dist/edge-config.d.mts +22 -7
  65. package/dist/edge-config.d.ts +22 -7
  66. package/dist/edge-config.js.map +1 -1
  67. package/dist/edge-config.mjs.map +1 -1
  68. package/dist/edge-core/index.d.mts +425 -0
  69. package/dist/edge-core/index.d.ts +425 -0
  70. package/dist/edge-core/index.js +1482 -0
  71. package/dist/edge-core/index.js.map +1 -0
  72. package/dist/edge-core/index.mjs +1437 -0
  73. package/dist/edge-core/index.mjs.map +1 -0
  74. package/dist/{express-B39o89gf.d.mts → express-BVd1_3FE.d.ts} +9 -7
  75. package/dist/{express-BuxKNO_q.d.ts → express-D_4hTn5Z.d.mts} +9 -7
  76. package/dist/gateway/gateway.d.mts +2 -2
  77. package/dist/gateway/gateway.d.ts +2 -2
  78. package/dist/gateway/gateway.js +83 -20
  79. package/dist/gateway/gateway.js.map +1 -1
  80. package/dist/gateway/gateway.mjs +83 -20
  81. package/dist/gateway/gateway.mjs.map +1 -1
  82. package/dist/git-trigger/git-hooks.d.mts +2 -2
  83. package/dist/git-trigger/git-hooks.d.ts +2 -2
  84. package/dist/{index-CLHdqs2M.d.ts → index-B0YHu_SP.d.ts} +30 -27
  85. package/dist/{index-DME3w3lf.d.mts → index-BPEBlOsE.d.mts} +30 -27
  86. package/dist/{index-CqydB4ks.d.mts → index-DQb5-_1X.d.mts} +1 -1
  87. package/dist/{index-BG62SXso.d.ts → index-T1aBoUcc.d.ts} +1 -1
  88. package/dist/index.d.mts +11 -11
  89. package/dist/index.d.ts +11 -11
  90. package/dist/index.js +595 -272
  91. package/dist/index.js.map +1 -1
  92. package/dist/index.mjs +592 -272
  93. package/dist/index.mjs.map +1 -1
  94. package/dist/local-evaluator/evaluator.d.mts +2 -2
  95. package/dist/local-evaluator/evaluator.d.ts +2 -2
  96. package/dist/metadata-capture.d.mts +63 -4
  97. package/dist/metadata-capture.d.ts +63 -4
  98. package/dist/metadata-capture.js +67 -0
  99. package/dist/metadata-capture.js.map +1 -1
  100. package/dist/metadata-capture.mjs +64 -0
  101. package/dist/metadata-capture.mjs.map +1 -1
  102. package/dist/{nextjs-D74W7wt-.d.mts → nextjs-WyeVr2Kp.d.mts} +3 -3
  103. package/dist/{nextjs-Ddlw_J1J.d.ts → nextjs-w7RTbP1P.d.ts} +3 -3
  104. package/dist/platform-signatures.d.mts +5 -6
  105. package/dist/platform-signatures.d.ts +5 -6
  106. package/dist/platform-signatures.js.map +1 -1
  107. package/dist/platform-signatures.mjs.map +1 -1
  108. package/dist/registration/index.d.mts +10 -11
  109. package/dist/registration/index.d.ts +10 -11
  110. package/dist/registration/index.js.map +1 -1
  111. package/dist/registration/index.mjs.map +1 -1
  112. package/dist/{sdk-CT7gdkfR.d.ts → sdk-CbTNIkAa.d.mts} +4 -4
  113. package/dist/{sdk-Bn6bj7kt.d.mts → sdk-QeX0Z8Ho.d.ts} +4 -4
  114. package/dist/transport/index.d.mts +2 -2
  115. package/dist/transport/index.d.ts +2 -2
  116. package/dist/transport/index.js.map +1 -1
  117. package/dist/transport/index.mjs.map +1 -1
  118. package/dist/{types-DHu7m9HI.d.ts → types-BLUx92FJ.d.ts} +1 -1
  119. package/dist/{types-Djw4GLtz.d.mts → types-DqfPU5Bl.d.mts} +1 -1
  120. package/dist/{types-BntuzEEn.d.mts → types-r850cOt0.d.mts} +121 -88
  121. package/dist/{types-SDu4Llbe.d.ts → types-sMxBT-nM.d.ts} +121 -88
  122. package/dist/ui/index.d.mts +11 -7
  123. package/dist/ui/index.d.ts +11 -7
  124. package/dist/ui/index.js +13 -9
  125. package/dist/ui/index.js.map +1 -1
  126. package/dist/ui/index.mjs +10 -8
  127. package/dist/ui/index.mjs.map +1 -1
  128. package/dist/verify.d.mts +11 -8
  129. package/dist/verify.d.ts +11 -8
  130. package/dist/verify.js +76 -8
  131. package/dist/verify.js.map +1 -1
  132. package/dist/verify.mjs +75 -8
  133. package/dist/verify.mjs.map +1 -1
  134. package/package.json +8 -2
@@ -1,4 +1,4 @@
1
- import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-SDu4Llbe.js';
1
+ import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-sMxBT-nM.js';
2
2
 
3
3
  /**
4
4
  * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.
@@ -1,4 +1,4 @@
1
- import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-BntuzEEn.mjs';
1
+ import { a as AccessLevel, j as CounterpartyType, T as TokenGuidance } from './types-r850cOt0.mjs';
2
2
 
3
3
  /**
4
4
  * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.
@@ -16,14 +16,13 @@ type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
16
16
  * in `access.accessLevel`. SDK reads them verbatim (no client-side remap).
17
17
  *
18
18
  * For ANONYMOUS / unverified callers, the level is determined by the
19
- * endpoint's `unverifiedAgentPolicy` per the verify-access canonical flow
20
- * (see `docs/research/adapter-architecture-technical-requirements.md` §21):
21
- * - Branch A (deny): `none` — caller is denied + advised to register
22
- * - Branch B (allow_partial): `restricted` — reduced/browse-only access + advised
23
- * - Branch C (allow_full): `standard` — unrestricted + advised to register for next time
19
+ * endpoint's `unverifiedAgentPolicy` per the verify-access canonical flow:
20
+ * - deny: `none` — caller is denied + advised to register
21
+ * - allow_partial: `restricted` — reduced/browse-only access + advised
22
+ * - allow_full: `standard` — unrestricted + advised to register for next time
24
23
  * Every branch ALWAYS emits a verification event + queues a blockchain record.
25
24
  *
26
- * For VERIFIED callers (Branch D), the level is resolved server-side from the
25
+ * For VERIFIED callers, the level is resolved server-side from the
27
26
  * agent's live trust score plus the endpoint's `trust_score_requirement`:
28
27
  * - none: agent below endpoint gate (denied; access.allowed=false)
29
28
  * - restricted: 0–19 trust score (registration-prompt only, no real capability)
@@ -32,17 +31,14 @@ type TrustLevel = 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM';
32
31
  * - full: 70+ trust score (PDLSS-scoped, high-trust)
33
32
  * - internal: same-org membership, regardless of score
34
33
  *
35
- * v2.3.9 (defect #30): renamed `'guidance'` band → `'restricted'`. The old
36
- * name collided with the `guidance: {registrationUrl, ...}` help-payload
37
- * object on VerificationResult; in the !apiResponse.access?.allowed branch
38
- * of verify.ts, hardcoded `accessLevel: 'guidance'` plus colocated
39
- * `guidance: {...}` read as internally consistent on review while at
40
- * runtime `hasMinimumAccess('guidance', 'guidance') === true` let denied
41
- * requests pass any route gated at `'guidance'`. Banded vocabulary stays
42
- * capability-noun (none / restricted / read-only / standard / full /
43
- * internal); response-shape descriptors stay nouns (guidance, advisory).
44
- * Defensive `!result.identityVerified || !result.policyAllowed` short-circuit
45
- * also added in adapters as belt-and-braces (round-18 G4 split).
34
+ * v2.3.9 renamed the `'guidance'` band → `'restricted'`. The old name
35
+ * collided with the `guidance: {registrationUrl, ...}` help-payload object
36
+ * on VerificationResult, and the collision let denied requests pass any
37
+ * route gated at `'guidance'` (`hasMinimumAccess('guidance', 'guidance')
38
+ * === true`). Banded vocabulary stays capability-noun (none / restricted /
39
+ * read-only / standard / full / internal); response-shape descriptors stay
40
+ * nouns (guidance, advisory). Adapters additionally short-circuit on
41
+ * `!result.identityVerified || !result.policyAllowed` as belt-and-braces.
46
42
  */
47
43
  type AccessLevel = 'none' | 'restricted' | 'read-only' | 'standard' | 'full' | 'internal';
48
44
  /**
@@ -136,14 +132,20 @@ interface GatewayConfig {
136
132
  */
137
133
  disableInitChecks?: boolean;
138
134
  /**
139
- * Audit F-A6-33: when true, the init self-test runs synchronously on the
140
- * first verify() call and THROWS on misconfig (apiBaseUrl returning HTML,
141
- * unreachable, etc.) instead of warning + continuing. Recommended for
142
- * production deploys where you want a fast-fail startup signal rather
143
- * than silent verify-access call failures. Default false for backward
144
- * compatibility.
135
+ * When true, the init self-test runs synchronously on the first verify()
136
+ * call and THROWS on misconfig (apiBaseUrl returning HTML, unreachable,
137
+ * etc.) instead of warning + continuing. Recommended for production
138
+ * deploys where you want a fast-fail startup signal rather than silent
139
+ * verify-access call failures. Default false for backward compatibility.
145
140
  */
146
141
  strictInit?: boolean;
142
+ /**
143
+ * 4.0.0: hard timeout (ms) on the outbound verify-access call. Without it
144
+ * a hanging backend hangs the merchant's middleware — and every inbound
145
+ * agent request behind it — indefinitely. Timeouts surface as the
146
+ * fail-closed `verify_access.api_error` result. Default 10_000.
147
+ */
148
+ verifyTimeoutMs?: number;
147
149
  /**
148
150
  * v2.3.8: emit `X-Astra-Gateway-Mode: unenforced` (with
149
151
  * `X-Astra-Gateway-Reason: no-policy | no-match`) on responses where the
@@ -151,9 +153,9 @@ interface GatewayConfig {
151
153
  * tests assert "this endpoint should be gated; if it falls through, fail
152
154
  * loudly". Default off; opt-in.
153
155
  *
154
- * Round-10 (#49, O10): the header value was renamed from the ambiguous
155
- * `pass-through` to `unenforced` so it describes the GATE state only —
156
- * not whether the request succeeded end-to-end. The config FLAG name
156
+ * The header value was renamed from the ambiguous `pass-through` to
157
+ * `unenforced` so it describes the GATE state only — not whether the
158
+ * request succeeded end-to-end. The config FLAG name
157
159
  * (`setPassThroughHeader`) is unchanged for backwards compatibility.
158
160
  */
159
161
  setPassThroughHeader?: boolean;
@@ -161,13 +163,11 @@ interface GatewayConfig {
161
163
  * v2.3.8: dashboard origin used to construct configuration links in
162
164
  * boot-time warnings (e.g. when no per-route policy is configured).
163
165
  * Defaults to `https://astrasync.ai/dashboard` (the `app.astrasync.ai`
164
- * subdomain referenced in older docs does not currently resolve —
165
- * audit F-PROBE-01).
166
+ * subdomain referenced in older docs does not resolve).
166
167
  */
167
168
  dashboardUrl?: string;
168
169
  /**
169
- * Round-12 (F9, express) / round-13 (R13-5, mcp parity): when true, the
170
- * middleware calls verify-access for any request that presents
170
+ * When true, the middleware calls verify-access for any request that presents
171
171
  * AstraSync credentials, even on routes / MCP risk-tiers with
172
172
  * `minAccessLevel: 'none'`. Populates `req.agentVerification` and
173
173
  * records the verification event for the audit trail. Enforcement
@@ -392,7 +392,7 @@ interface SettlementArtifact {
392
392
  /**
393
393
  * Single failed gate on a verify-access denial. Aggregated into
394
394
  * `VerificationResult.failures[]` so partners can see every blocker in one
395
- * response. v2.9.8 (defect M1) — pre-fix the response was fail-fast on the
395
+ * response (v2.9.8+) — previously the response was fail-fast on the
396
396
  * first failed gate, forcing a fix-and-retry cascade through PDLSS
397
397
  * dimensions, counterparty allowlist, trust score, and attestations.
398
398
  *
@@ -410,19 +410,19 @@ interface AccessFailure {
410
410
  }
411
411
  interface VerificationResult {
412
412
  /**
413
- * Round-18 (G4): identity-verification status — was the caller successfully
413
+ * Identity-verification status — was the caller successfully
414
414
  * resolved to a registered agent (signature/credential check passed)?
415
415
  * Maps to backend `verificationContext.idVerified`. Drives HTTP 401 vs 403
416
416
  * mapping in default adapters: `!identityVerified` → 401 (re-authenticate);
417
417
  * `identityVerified && !policyAllowed` → 403 (re-auth won't help — update
418
- * PDLSS scope or step up). Replaces the round-17-and-earlier `verified`
419
- * field, which collapsed identity and policy into a single boolean and
420
- * forced merchants writing `verified ? 200 : 401` into the wrong HTTP-status
421
- * recovery path on PDLSS denials of authenticated agents.
418
+ * PDLSS scope or step up). Replaces the pre-4.x `verified` field, which
419
+ * collapsed identity and policy into a single boolean and forced merchants
420
+ * writing `verified ? 200 : 401` into the wrong HTTP-status recovery path
421
+ * on PDLSS denials of authenticated agents.
422
422
  */
423
423
  identityVerified: boolean;
424
424
  /**
425
- * Round-18 (G4): does the endpoint's PDLSS / access policy permit this
425
+ * Does the endpoint's PDLSS / access policy permit this
426
426
  * specific action? Maps to backend `access.allowed`. Distinct from
427
427
  * `identityVerified`: a verified agent can be policy-denied (403); an
428
428
  * unverified caller's policy field is `false` by definition.
@@ -450,17 +450,15 @@ interface VerificationResult {
450
450
  */
451
451
  failures?: AccessFailure[];
452
452
  /**
453
- * Round-10 (#47, O5): correlation handle for tying a partner-visible
454
- * denial to a server-side log line. Hoisted here from
455
- * `EnhancedVerificationResult` so adapter onDenied handlers can surface
456
- * it on the merchant's response body. Present on anonymous server
457
- * responses, on synthesised stubs for API-error fallbacks
458
- * (`createGuidanceResponse`), and on the new
459
- * `verify_access.internal_error` 200-shaped failure shape.
453
+ * Correlation handle for tying a partner-visible denial to a server-side
454
+ * log line, surfaced so adapter onDenied handlers can include it on the
455
+ * merchant's response body. Present on anonymous server responses, on
456
+ * synthesised stubs for API-error fallbacks (`createGuidanceResponse`),
457
+ * and on the `verify_access.internal_error` 200-shaped failure shape.
460
458
  */
461
459
  correlationId?: string;
462
460
  /**
463
- * 3.12.0 (Trust Record, §33.5 #3): attempt-chain handle, server-echoed on
461
+ * 3.12.0: attempt-chain handle, server-echoed on
464
462
  * every response branch (caller-supplied or server-minted). Disjoint from
465
463
  * `correlationId`/`sessionId` — those identify one verification EVENT; an
466
464
  * attempt CONTAINS events (the whole catalog → intent → settlement funnel
@@ -469,6 +467,14 @@ interface VerificationResult {
469
467
  * never leaks a prior attempt's id.
470
468
  */
471
469
  attemptId?: string;
470
+ /**
471
+ * 4.0.0: the backend rejected THIS INTEGRATION'S own API key (revoked /
472
+ * expired / rotated) — a deterministic merchant-side misconfig, distinct
473
+ * from both an agent denial and a transient `verify_access.api_error`.
474
+ * Adapters branch on it to answer inbound agents with 503 +
475
+ * `MERCHANT_VERIFICATION_MISCONFIGURED` instead of a misleading 401.
476
+ */
477
+ misconfigured?: boolean;
472
478
  /** Whether step-up authentication is required */
473
479
  requiresStepUp?: boolean;
474
480
  /** Whether approval is required */
@@ -513,11 +519,12 @@ interface CallerMetadata {
513
519
  agentCardUrl?: string;
514
520
  /**
515
521
  * The full sanitised view of the agent's inbound request headers + connection
516
- * signals (Workstream D — maximal metadata capture). Produced by
517
- * `sanitizeHeaders` (genuine secrets removed, credential headers reduced to a
518
- * safe format prefix). Forwarded so the endpoint owner sees every wire signal
519
- * about the agent, not just IP/UA. Local string work only — kept OUT of the
520
- * verify cache key so per-request maps don't defeat verdict caching.
522
+ * signals (maximal metadata capture: every signal legitimately visible on
523
+ * the wire is captured). Produced by `sanitizeHeaders` (genuine secrets
524
+ * removed, credential headers reduced to a safe format prefix). Forwarded so
525
+ * the endpoint owner sees every wire signal about the agent, not just IP/UA.
526
+ * Local string work only — kept OUT of the verify cache key so per-request
527
+ * maps don't defeat verdict caching.
521
528
  */
522
529
  observedMetadata?: ObservedMetadata;
523
530
  }
@@ -575,7 +582,7 @@ interface VerificationRequest {
575
582
  timeoutOverride?: number;
576
583
  };
577
584
  /**
578
- * Round-12 (F19): transport protocol marker. Set by the MCP middleware
585
+ * Transport protocol marker. Set by the MCP middleware
579
586
  * to `'mcp'`; non-MCP callers leave it unset (server treats as `'rest'`).
580
587
  * Separates "how did the call arrive" from "what does the agent want"
581
588
  * (`purpose`). Stored on platform_events.eventData for activity-feed
@@ -583,26 +590,26 @@ interface VerificationRequest {
583
590
  */
584
591
  invocationProtocol?: 'rest' | 'mcp' | 'a2a' | 'acp' | 'ap2' | 'mpp' | 'ucp';
585
592
  /**
586
- * 3.9.0 (§33.5 #1) — raw commerce-protocol artifacts forwarded verbatim
587
- * to verify-access, whose Step 0.5 commerce pipeline runs the full
593
+ * 3.9.0 — raw commerce-protocol artifacts forwarded verbatim
594
+ * to verify-access, whose commerce pipeline runs the full
588
595
  * cryptographic verification SERVER-side and persists commerce_context on
589
596
  * the session. Adapters forward artifacts, they never verify them locally
590
- * (bridge-is-transport: verify-access is the sole verification sink, so
591
- * every decision is recorded once, with events). Shape mirrors the
592
- * backend's `commerceArtifacts` schema 1:1.
597
+ * (verify-access is the sole verification sink, so every decision is
598
+ * recorded once, with events). Shape mirrors the backend's
599
+ * `commerceArtifacts` schema 1:1.
593
600
  */
594
601
  commerceArtifacts?: CommerceArtifactsPayload;
595
602
  /**
596
- * 3.12.0 (Trust Record, §33.5 #3) — attempt-chain handle correlating the
603
+ * 3.12.0 — attempt-chain handle correlating the
597
604
  * multi-call commerce funnel (catalog → intent → settlement) into ONE
598
605
  * attempt. Format `att_` + 32 lowercase hex. Optional: the server mints one
599
606
  * when absent and echoes it top-level on every response branch either way.
600
607
  * Observational pass-through — never affects the verdict, so it's excluded
601
- * from the verify cache key (see `getCacheKey`).
608
+ * from the verify cache key.
602
609
  */
603
610
  attemptId?: string;
604
611
  /**
605
- * 3.12.0 (Trust Record, §33.5 #3) — first-party observational data: the
612
+ * 3.12.0 — first-party observational data: the
606
613
  * offers the agent evaluated at this checkpoint (catalog browse / intent
607
614
  * selection). Forwarded verbatim to verify-access; never affects the
608
615
  * verdict (also excluded from the cache key).
@@ -610,7 +617,7 @@ interface VerificationRequest {
610
617
  considerationSet?: ConsiderationSet;
611
618
  }
612
619
  /**
613
- * One offer the agent evaluated (Trust Record, §33.5 #3). Mirrors the
620
+ * One offer the agent evaluated. Mirrors the
614
621
  * backend's `considerationItemSchema` 1:1 — first-party observational data
615
622
  * reported by the transport (bridge / adapters), never verified locally.
616
623
  */
@@ -631,8 +638,8 @@ interface ConsiderationItem {
631
638
  notChosenReason?: 'price' | 'policy' | 'trust_threshold' | 'stock' | 'other';
632
639
  }
633
640
  /**
634
- * The set of offers evaluated at one funnel checkpoint (Trust Record,
635
- * §33.5 #3). Mirrors the backend's `considerationSetSchema` 1:1.
641
+ * The set of offers evaluated at one funnel checkpoint.
642
+ * Mirrors the backend's `considerationSetSchema` 1:1.
636
643
  *
637
644
  * `items` is capped at 50 server-side — reporters MUST order chosen items
638
645
  * FIRST so purchased counts survive truncation; `totalEvaluated` carries the
@@ -650,8 +657,7 @@ interface ConsiderationSet {
650
657
  }
651
658
  /**
652
659
  * Terminal (or notable) outcome of an attempt chain, reported post-hoc via
653
- * `reportAttempt` (Trust Record, §33.5 #3). Mirrors the backend's
654
- * `attemptReportSchema.outcome` 1:1.
660
+ * `reportAttempt`. Mirrors the backend's `attemptReportSchema.outcome` 1:1.
655
661
  */
656
662
  interface AttemptOutcome {
657
663
  kind: 'settled' | 'blocked_step_up' | 'failed' | 'high_value_action';
@@ -669,8 +675,8 @@ interface AttemptOutcome {
669
675
  rail?: string;
670
676
  }
671
677
  /**
672
- * Body for `POST /agents/verify-access/attempt-report` (Trust Record,
673
- * §33.5 #3): post-hoc consideration/outcome data for an attempt chain that a
678
+ * Body for `POST /agents/verify-access/attempt-report`:
679
+ * post-hoc consideration/outcome data for an attempt chain that a
674
680
  * verify-access call couldn't carry (e.g. the catalog was served from a local
675
681
  * cache, or the deny happened transport-side). Must carry `considerationSet`
676
682
  * and/or `outcome`.
@@ -759,7 +765,7 @@ interface RouteAccessConfig {
759
765
  /** HTTP method (or * for all) */
760
766
  method: string | '*';
761
767
  /**
762
- * @deprecated 3.2.0 — the access-level band no longer gates (post-3.1.0 #1).
768
+ * @deprecated 3.2.0 — the access-level band no longer gates.
763
769
  * Optional/ignored; retained for back-compat. Use `minTrustScore` to tighten.
764
770
  */
765
771
  minAccessLevel?: AccessLevel;
@@ -777,13 +783,13 @@ interface RouteAccessConfig {
777
783
  /** Maximum transaction value for this route */
778
784
  maxTransactionValue?: number;
779
785
  /**
780
- * Backend-evaluator strict mode (audit F-A1-09): when true AND
786
+ * Backend-evaluator strict mode: when true AND
781
787
  * `allowedPurposes` is non-empty, verify-access denies requests arriving
782
788
  * WITHOUT a purpose. Configured in the dashboard; passed through here.
783
789
  */
784
790
  requirePurpose?: boolean;
785
791
  /**
786
- * SEND-mapping (Bug 14, §4.6) — not an allow-list: the PDLSS tokens the
792
+ * SEND-mapping — not an allow-list: the PDLSS tokens the
787
793
  * middleware STAMPS on verify-access calls matching this route, replacing
788
794
  * the generic `data`/`data.*` method-table fallback. `purpose` = bare
789
795
  * category noun (`shopping`, `trading`); `action` = dotted verb
@@ -812,8 +818,8 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
812
818
  extractPurpose?: (req: unknown) => string | undefined;
813
819
  /**
814
820
  * Function to extract the PDLSS action from a request — symmetric with
815
- * `extractPurpose` (Bug 14, §4.6: the action axis previously had NO
816
- * override and hardwired the HTTP verb). When configured it masks the
821
+ * `extractPurpose` (previously the action axis had no override and
822
+ * hardwired the HTTP verb). When configured it masks the
817
823
  * `X-Astra-Action` header step; returning undefined falls through to the
818
824
  * pinned method→action table (GET→data.read, POST/PUT/PATCH→data.write,
819
825
  * DELETE→data.delete). Dashboard route mapping still outranks it.
@@ -858,28 +864,39 @@ interface ExpressMiddlewareOptions extends GatewayConfig {
858
864
  *
859
865
  * In shadow mode (default), the middleware ALWAYS logs a
860
866
  * `[SHADOW] would-have-denied` line on throws including correlationId so
861
- * merchants can grep their own logs for impact analysis. SDK 2.4.x reads
862
- * the shadow logs across the 1-week observation window; the default
863
- * flips to `'closed'` in a follow-up release once <0.1% of throws appear
864
- * to be legitimate-traffic regressions.
867
+ * merchants can grep their own logs for impact analysis. The default
868
+ * flips to `'closed'` in a follow-up release once the shadow logs confirm
869
+ * legitimate traffic is unaffected.
865
870
  *
866
871
  * Small-value demo merchants can keep `'open'` indefinitely after the
867
- * default flip by setting this explicitly (audit F-A1-06).
872
+ * default flip by setting this explicitly.
868
873
  */
869
874
  failOnError?: 'open' | 'closed';
870
875
  /**
871
- * When true, route-pattern matching is case-insensitive (audit F-A6-31,
872
- * round-18.6.5 Finding #1 from astrasync.shop). Default false in SDK
873
- * 2.4.13 for backward compatibility; shadow logs record divergences so
874
- * merchants can preview impact before flipping. Follow-up release makes
875
- * case-insensitive the default after 1-week observation confirms <5
876
- * merchants with divergence-events.
876
+ * When true, route-pattern matching is case-insensitive. Default false in
877
+ * SDK 2.4.13 for backward compatibility; shadow logs record divergences so
878
+ * merchants can preview impact before flipping. A follow-up release makes
879
+ * case-insensitive the default once observation confirms merchants are
880
+ * unaffected.
877
881
  *
878
882
  * Recommended: set to true if your Express install uses the default
879
883
  * (case-insensitive) routing AND your policy entries don't deliberately
880
884
  * use case distinctions.
881
885
  */
882
886
  caseInsensitiveRouteMatch?: boolean;
887
+ /**
888
+ * Emit a fire-and-forget beacon for bot- and agent-shaped traffic that
889
+ * passes through UNGATED (no dashboard route matches the path, or the
890
+ * matching route is gated at `none`), so the endpoint's dashboard sees
891
+ * anonymous agent traffic the gate never evaluates. Human traffic and
892
+ * static assets are never beaconed; platform-fingerprinted agents always
893
+ * beacon; other non-browser traffic is sampled at the dashboard-configured
894
+ * `sampling.anonymousBeaconRate` (set the rate to 0 in the dashboard to
895
+ * stop sampling). The beacon is never awaited on the request path and adds
896
+ * no latency. Requires `counterpartyId`. Default true; set false to
897
+ * disable the beacon and its config fetch entirely.
898
+ */
899
+ anonymousBeacon?: boolean;
883
900
  }
884
901
  /**
885
902
  * Next.js middleware options.
@@ -892,9 +909,15 @@ interface NextJsMiddlewareOptions extends GatewayConfig {
892
909
  skipPaths?: string[];
893
910
  /** Refresh interval (ms) for the remote-fetched route policy. Default: 5 minutes. */
894
911
  routesRefreshMs?: number;
895
- /** Whether to show Commerce Shield overlay for unverified */
912
+ /**
913
+ * Whether to show the verification interstitial (the HTML overlay served to
914
+ * unverified web-page traffic). Default true. Takes precedence over the
915
+ * deprecated `showCommerceShield` when both are set.
916
+ */
917
+ showInterstitial?: boolean;
918
+ /** @deprecated Renamed in 4.1.0 — use `showInterstitial`. Alias removed next major. */
896
919
  showCommerceShield?: boolean;
897
- /** Commerce Shield configuration */
920
+ /** Verification interstitial configuration */
898
921
  commerceShield?: {
899
922
  title?: string;
900
923
  message?: string;
@@ -903,6 +926,13 @@ interface NextJsMiddlewareOptions extends GatewayConfig {
903
926
  };
904
927
  /** Enable runtime challenge for all verify-access calls (default: true) */
905
928
  enableRuntimeChallenge?: boolean;
929
+ /**
930
+ * Emit a fire-and-forget beacon for bot- and agent-shaped traffic that
931
+ * passes through ungated — same semantics as the express option of the
932
+ * same name (see `ExpressMiddlewareOptions.anonymousBeacon`). Default
933
+ * true; set false to disable entirely.
934
+ */
935
+ anonymousBeacon?: boolean;
906
936
  }
907
937
  /**
908
938
  * SDK function options
@@ -1008,10 +1038,11 @@ interface AstraSyncCredentials {
1008
1038
  */
1009
1039
  type ProtocolTransport = 'http' | 'a2a' | 'mcp';
1010
1040
  /**
1011
- * Commerce Shield UI props
1041
+ * Verification interstitial UI props (the React overlay shown to unverified
1042
+ * agents; user-visible title stays "AstraSync Agent Verification").
1012
1043
  */
1013
- interface CommerceShieldProps {
1014
- /** Whether the shield is visible */
1044
+ interface VerificationInterstitialProps {
1045
+ /** Whether the interstitial is visible */
1015
1046
  visible: boolean;
1016
1047
  /** Verification result (if any) */
1017
1048
  result?: VerificationResult;
@@ -1030,5 +1061,7 @@ interface CommerceShieldProps {
1030
1061
  /** Custom styles */
1031
1062
  className?: string;
1032
1063
  }
1064
+ /** @deprecated Renamed VerificationInterstitialProps in 4.1.0; alias removed next major. */
1065
+ type CommerceShieldProps = VerificationInterstitialProps;
1033
1066
 
1034
- 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 };
1067
+ 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 };