@astrasyncai/verification-gateway 5.4.2 → 5.6.0

package/README.md

@@ -99,7 +99,8 @@ const result = await gateway.verify({
   purpose: 'data-exchange',
 });
 
-if (result.verified && result.accessLevel !== 'none') {
+// 5.0.0: the accessLevel band is gone — the decision is the two axes.
+if (result.identityVerified && result.policyAllowed) {
   // Safe to interact with this agent
   console.log(`Trust score: ${result.agent?.trustScore}`);
 }
@@ -330,16 +331,19 @@ rest.use(
 with `X-Astra-Id` so the inner middleware can verify the marker matches
 the claimed agent. The marker only gates the dedupe-skip decision.
 
-## Access Levels
+## Access Decision (5.0.0 — two axes, no bands)
 
-| Level        | Description                                     |
-| ------------ | ----------------------------------------------- |
-| `none`       | No credentials provided                         |
-| `restricted` | Minimal access; verification interstitial shown |
-| `read-only`  | Can browse, no mutations                        |
-| `standard`   | Normal access per PDLSS                         |
-| `full`       | Full access for high-trust agents               |
-| `internal`   | Organization member access                      |
+The graded `accessLevel` band was removed in 5.0.0. A verification is now two
+explicit booleans:
+
+| Axis               | Question it answers                                      |
+| ------------------ | -------------------------------------------------------- |
+| `identityVerified` | WHO — did the caller resolve to a registered agent?      |
+| `policyAllowed`    | WHAT — does this request fit the agent's declared PDLSS? |
+
+Both true → proceed. Either false → `failures[]` says exactly which dimension
+failed and what fixes it. Value-gating (autonomous limit / hard limit) rides
+`recommendation` + `stepUpApproval`, not an access band.
 
 ## Trust Levels
 
@@ -394,8 +398,9 @@ Agents can provide credentials via:
 
 ```typescript
 interface VerificationResult {
-  verified: boolean;
-  accessLevel: 'none' | 'guidance' | 'read-only' | 'standard' | 'full' | 'internal';
+  // 5.0.0: two explicit axes replaced the old verified/accessLevel band.
+  identityVerified: boolean; // WHO: the caller resolved to a registered agent
+  policyAllowed: boolean; // WHAT: the request fits the agent's PDLSS boundary
 
   agent?: {
     astraId: string;
@@ -463,12 +468,62 @@ When a transaction value is between the agent's Autonomous Limit and Hard Limit,
 interface StepUpApprovalInfo {
   approvalId: string; // Capability token (UUID)
   pollUrl: string; // GET /api/step-up-approvals/poll/:approvalId
-  expiresAt: string; // ISO-8601, 5-minute TTL
+  expiresAt: string; // ISO-8601 (decision window: 30 min, aligned to the intent mandate)
 }
 ```
 
 Poll the `pollUrl` (unauthenticated, rate-limited 60 req/min) to check if the owner approved. The `getApprovalPollingInfo(result)` helper extracts it from a `VerificationResult`.
 
+## Checkout & settlement (astra-pay)
+
+The first-party commerce rail: an agent shops under its ASTRA-id, holds NO
+payment credential, and the platform settles from the owner's saved
+instrument. Two phases discriminate quote from money movement:
+
+- `commercePhase: 'quote'` (or unphased) — verification only, never settles.
+- `commercePhase: 'confirm'` — the ONLY leg that can settle. Use
+  `client.confirmCheckout({ astraId, transactionValue, currency,
+checkoutSessionId, checkoutItems, counterpartyUrl })`; `checkoutSessionId`
+  is the per-cart idempotency key (one order row per session, normative).
+
+Read `result.settlementOutcome.status` — never `success` alone:
+
+| status              | Meaning                                   | Your action                                                                                                                       |
+| ------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `settled`           | Charged; `orderId` present                | Fulfil / mark paid                                                                                                                |
+| `requires_approval` | Held for human step-up — not a failure    | Record as pending; a re-drive follows approval                                                                                    |
+| `pending_merchant`  | 5.5.0 self-settle: YOU charge (see below) | Charge with the `settlementToken`, then report                                                                                    |
+| `failed`            | Charge declined (`failureCode`)           | Mark failed                                                                                                                       |
+| `requires_action`   | 3DS/SCA needed on the saved card          | Per your policy                                                                                                                   |
+| `no_instrument`     | Policy passed, no chargeable card on file | Terminal on autonomous; NON-terminal after approval — the human's approval survives; re-drive the same session once a card exists |
+| _anything else_     | A status newer than your SDK              | Treat as PENDING, never failed (open union, 5.5.0)                                                                                |
+
+**Self-settling merchants (5.5.0, `settlement_mode='self_settle'`):** the
+confirm result carries `settlementToken` (agent-blind
+`{ stripeCustomerId, stripePaymentMethodId, amountMinor, currency, sessionId,
+orderId, jti, statementSuffix, expiresAt }`) instead of a completed charge.
+Charge on your own integration with Stripe idempotency key
+`voucher:<token.jti>` and `metadata: { jti, sessionId }`, then call
+`client.reportSettlement({ sessionId, status, amountMinor, currency,
+processorRef })` so the buyer's dashboard and the agent's poll surface
+reconcile. Amounts must match the order exactly; replays are safe. Never
+expose the token to the agent plane or logs.
+
+**Fulfilment PII (5.6.0):** first-party confirm results carry a
+`fulfilment: { email, emailSource }` block — you ALWAYS get a fulfilment
+email for a first-party order. `emailSource: 'agent_provided'` means the
+agent passed a `buyerEmail` (on the bridge handoff body, the verify-access
+request, or your `confirmCheckout({ buyerEmail })` call);
+`emailSource: 'account'` means the platform defaulted to the buyer's account
+email. Emails arrive canonicalized (trimmed, lower-cased). Precedence: an
+explicit handoff-body `buyerEmail` wins over `fulfilment.email`'s account
+default. Store the email with the pending order and fulfil against it only
+once the order reaches `settled` / `pending_merchant`. All of it is
+transit-only — AstraSync stores nothing; treat `fulfilment` as merchant-only
+material (the bridge strips it from the agent plane). Shipping addresses
+never transit AstraSync: take them agent → your fulfilment endpoint
+directly, joined by `sessionId`.
+
 ## Settlement Artifacts
 
 On a clean merchant-mediated grant where the owner has a verified payment instrument, verify-access returns a `settlement` object (wire format **v2**, versioned via the `ver: 2` claim — verify/redeem reject other versions):
@@ -543,7 +598,6 @@ interface GatewayConfig {
 
   // Optional
   apiKey?: string; // For authenticated requests
-  defaultAccessLevel?: string; // Default: 'guidance'
   cacheTtl?: number; // Cache duration in seconds (default: 300)
   debug?: boolean; // Enable debug logging
 
@@ -575,12 +629,11 @@ interface GatewayConfig {
   // 404 case). Set true for tests where the extra request is undesirable.
   disableInitChecks?: boolean;
 
-  // @deprecated — removed as functional config in v2.3.0. Server is the
-  // single source of truth for access-level decisions; the SDK reads
-  // access.accessLevel from the response verbatim. Setting these has no
-  // effect (a one-shot console.warn fires). To gate access to your
-  // endpoint, configure trust_score_requirement server-side via the
-  // /api/endpoints registration.
+  // @deprecated — removed as functional config in v2.3.0; the accessLevel
+  // band itself was removed in 5.0.0 (identityVerified + policyAllowed are
+  // the decision axes). Setting these has no effect (a one-shot
+  // console.warn fires). To gate access to your endpoint, configure
+  // trust_score_requirement server-side via the /api/endpoints registration.
   minTrustScore?: number;
   minTrustScoreForFull?: number;
 }
@@ -948,7 +1001,7 @@ use the upgrade flow (coming soon) or retire-and-re-register.
 ### v2.4.4 — Round-12 partner integration testing
 
 - **F9** — `ExpressMiddlewareOptions.evaluateAlwaysIfCredentialed`: when true + credentials present + route-none, the middleware calls verify-access for the audit trail + `req.agentVerification` population, then proceeds without enforcement. Default false preserves existing behaviour. Use for tiered-response rendering on routes that grant public access but want caller identity visible to the handler.
-- **F12** — `defaultOnDenied` / `defaultMcpDenied` synthesise `access_level.insufficient` failure entry on accessLevel-below-route + trust-score-below-route denials. Guidance text references the step-up verification flow ("coming soon — ships this month") only. Prior denials carried `INSUFFICIENT_ACCESS` with empty `failures[]` / `denialReasons[]` arrays.
+- **F12** — `defaultOnDenied` / `defaultMcpDenied` synthesise `access_level.insufficient` failure entry on accessLevel-below-route + trust-score-below-route denials. _(Historical note: the accessLevel band was removed in 5.0.0 — current denials carry the two-axis `identityVerified`/`policyAllowed` shape.)_ Guidance text references the step-up verification flow ("coming soon — ships this month") only. Prior denials carried `INSUFFICIENT_ACCESS` with empty `failures[]` / `denialReasons[]` arrays.
 - **F16** — `register()` now passes the API response's `warnings[]` through verbatim on both 201 (sync) and 202 (pending-approval) paths. Pre-fix the SDK silently dropped backend advisories like `no_callback_endpoint`. `RegisterResult` + `PendingRegistrationResponse` + `RegistrationResponse` types extended.
 - **F19** — MCP middleware purpose pass-through. The hardcoded `purpose: 'mcp_invoke'` is now a fallback; resolution precedence is `X-Astra-Purpose` header → `params._meta.astrasync.purpose` → `'mcp_invoke'` default. Adds `invocationProtocol: 'mcp'` to the verify-access body so transport is marked separately from intent. Debug-level `purpose_source` log line per call for adoption tracking + support triage.
 - **`mcpToPdlss`** signature extended to accept optional `headerPurpose` + `toolArgumentPurpose` args; return type gains `purposeSource: 'header' | 'tool_argument' | 'default_mcp_invoke'`.

package/dist/adapters/express.d.mts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BU04qAAR.mjs';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BK_pRNSs.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BU04qAAR.js';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-BK_pRNSs.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.js

@@ -26,7 +26,7 @@ __export(express_exports, {
 module.exports = __toCommonJS(express_exports);
 
 // src/version.ts
-var SDK_VERSION = "5.4.1";
+var SDK_VERSION = "5.6.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -449,6 +449,7 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.commercePhase) body.commercePhase = requestData.commercePhase;
   if (requestData.checkoutSessionId) body.checkoutSessionId = requestData.checkoutSessionId;
   if (requestData.checkoutItems) body.checkoutItems = requestData.checkoutItems;
+  if (requestData.buyerEmail) body.buyerEmail = requestData.buyerEmail;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
   if (requestData.attemptId) body.attemptId = requestData.attemptId;
   if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
@@ -621,7 +622,12 @@ async function verify(config, request, options) {
       recommendationReasons: apiResponse.recommendationReasons,
       stepUpApproval: apiResponse.stepUpApproval,
       settlement: apiResponse.settlement,
-      settlementOutcome: apiResponse.settlementOutcome
+      settlementOutcome: apiResponse.settlementOutcome,
+      // 5.5.0 self-settlement: merchant-only material — passes through to the
+      // MERCHANT caller only (bridge callers strip it before the agent plane).
+      settlementToken: apiResponse.settlementToken,
+      // 5.6.0: fulfilment contact — merchant-only lane, same strip rule.
+      fulfilment: apiResponse.fulfilment
     };
     return result2;
   }
@@ -679,7 +685,10 @@ async function verify(config, request, options) {
     warningHeader: apiResponse.warningHeader,
     stepUpApproval: apiResponse.stepUpApproval,
     settlement: apiResponse.settlement,
-    settlementOutcome: apiResponse.settlementOutcome
+    settlementOutcome: apiResponse.settlementOutcome,
+    settlementToken: apiResponse.settlementToken,
+    // 5.6.0: fulfilment contact — merchant-only lane, same strip rule.
+    fulfilment: apiResponse.fulfilment
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;