@astrasyncai/verification-gateway 5.7.0 → 5.8.0

package/README.md

@@ -474,6 +474,42 @@ interface StepUpApprovalInfo {
 
 Poll the `pollUrl` (unauthenticated, rate-limited 60 req/min) to check if the owner approved. The `getApprovalPollingInfo(result)` helper extracts it from a `VerificationResult`.
 
+### Attempt chain (`X-Astra-Attempt-Id`, 5.8.0)
+
+Every interaction chain carries an attempt id of the form `att_<32 hex>`. The
+AstraSync bridge stamps it on each call it delivers to your endpoint as the
+`X-Astra-Attempt-Id` request header, and the express / Next.js middleware
+automatically read the header and thread the id into verify-access (invalid
+values are dropped). Two effects:
+
+- **One intent = one approval.** A step-up the owner already approved for
+  this chain passes every later verify-access hop that carries the same
+  attempt id (the bridge pre-verify, your middleware's re-verify, and any
+  re-drive after a delivery failure) — it is never asked for twice.
+- **Idempotency key.** Key your own idempotency/dedupe on the header value:
+  a re-drive of the same chain arrives with the SAME id, so replays of an
+  already-executed action can be detected venue-side.
+
+No configuration is needed; direct (non-bridge) callers simply don't send the
+header and behaviour is unchanged.
+
+### Bridge-fronted endpoints: hold budgets
+
+The bridge delivers your endpoint's response within an HTTP budget of **30 s
+by default (60 s maximum, configurable per route via `responseBudgetMs` in
+your registration's `routes[]`)**. `stepUpMaxWaitMs: 0` (hold in-request
+until the approval decides) is designed for direct integrations and will
+outlive that budget — behind the bridge, either:
+
+- leave `stepUpMaxWaitMs` unset and return the 403 with `stepUpApproval`
+  in-band (the bridge renders the approval card and re-drives after
+  approval), or
+- bound the hold to well under the budget (~20 s) so the deny still reaches
+  the bridge in time.
+
+Either way the attempt chain above guarantees the post-approval re-drive
+passes without a second approval.
+
 ## Checkout & settlement (astra-pay)
 
 The first-party commerce rail: an agent shops under its ASTRA-id, holds NO

package/dist/adapters/express.js

@@ -26,7 +26,7 @@ __export(express_exports, {
 module.exports = __toCommonJS(express_exports);
 
 // src/version.ts
-var SDK_VERSION = "5.7.0";
+var SDK_VERSION = "5.8.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -1834,6 +1834,8 @@ function createMiddleware(options) {
           }
         }
       }
+      const attemptHeader = req.headers["x-astra-attempt-id"];
+      const inboundAttemptId = typeof attemptHeader === "string" && /^att_[0-9a-f]{32}$/.test(attemptHeader) ? attemptHeader : void 0;
       const verificationRequest = {
         credentials,
         purpose,
@@ -1846,6 +1848,7 @@ function createMiddleware(options) {
         durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
         ...txValue !== void 0 && { transactionValue: txValue },
         ...txCurrency && { currency: txCurrency },
+        ...inboundAttemptId && { attemptId: inboundAttemptId },
         callerMetadata: {
           sourceIp: originalClientIp,
           userAgent: req.headers["user-agent"],