@astrasyncai/verification-gateway 3.4.0 → 3.6.0

package/README.md

@@ -409,6 +409,61 @@ interface VerificationResult {
 }
 ```
 
+## Settlement Authorization
+
+For direct-path merchants settling a priced cart, call `authorizeSettlement()` **after** pricing — the middleware only verifies identity/access, not the transaction value:
+
+```typescript
+import { authorizeSettlement } from '@astrasyncai/verification-gateway';
+
+const decision = await authorizeSettlement(config, {
+  agentId: req.agentVerification.agent.astraId,
+  value: cart.total, // YOUR authoritative priced total, never agent-supplied
+  currency: 'USD',
+});
+
+if (!decision.authorized) {
+  // decision.stepUpApproval?.pollUrl — if in the approval band, the owner can approve
+  return res.status(402).json({ error: decision.reason, stepUpApproval: decision.stepUpApproval });
+}
+// Safe to settle
+```
+
+## Step-Up Approval
+
+When a transaction value is between the agent's Autonomous Limit and Hard Limit, verify-access returns `stepUpApproval` on the result:
+
+```typescript
+interface StepUpApprovalInfo {
+  approvalId: string; // Capability token (UUID)
+  pollUrl: string; // GET /api/step-up-approvals/poll/:approvalId
+  expiresAt: string; // ISO-8601, 5-minute TTL
+}
+```
+
+Poll the `pollUrl` (unauthenticated, rate-limited 60 req/min) to check if the owner approved. The `getApprovalPollingInfo(result)` helper extracts it from a `VerificationResult`.
+
+## Settlement Artifacts
+
+On a clean merchant-mediated grant where the owner has a verified payment instrument, verify-access returns a `settlement` object:
+
+```typescript
+interface SettlementArtifact {
+  type: string; // e.g. "stablecoin_voucher"
+  artifact: string; // JWS compact-serialised (ES256)
+  binding: {
+    merchantId: string;
+    amount: number;
+    currency: string;
+    sessionId: string;
+    singleUse: true;
+    expiresAt: string;
+  };
+}
+```
+
+Verify vouchers server-side via `POST /api/wallets/voucher/verify` or fetch the signing keys from `GET /api/wallets/voucher/.well-known/jwks.json`.
+
 ## Configuration
 
 ```typescript
@@ -430,6 +485,22 @@ interface GatewayConfig {
   // forwarded on every verify-access call so the server attributes traffic
   // directly to this endpoint rather than resolving by URL.
 
+  // Step-up hold-and-poll (v3.6.0+, OPT-IN). When stepUpMaxWaitMs is set, the
+  // express/mcp/nextjs middleware HOLDS a step_up_required request, polls the
+  // approval, and on 'approved' re-verifies once (cache-bypassed) so the
+  // backend redeems the single-use approval — the owner approves in their
+  // dashboard while the original request waits (MFA model). Unset = current
+  // fail-closed behavior (immediate 403 with stepUpApproval polling info).
+  //   0  → hold until the approval's expiresAt (+5s grace; 5-min fallback)
+  //   >0 → hold at most this many milliseconds
+  // CAUTION: Next.js edge runtimes enforce ~25s wall-clock budgets — use a
+  // small value there (≤20000) or gate in a Node route handler instead.
+  stepUpMaxWaitMs?: number;
+  // Poll interval for the hold (default 3000ms, 250ms floor). The poll route
+  // is rate-limited 60/min/IP: at the default interval ~3 concurrent holds
+  // per merchant IP fit; excess polls degrade the hold to 'timeout'.
+  stepUpPollIntervalMs?: number;
+
   // Init self-test (v2.2.3+) — fires a HEAD probe to verify-access on first
   // call and warns if apiBaseUrl is pointing at HTML (catches the marketing-
   // 404 case). Set true for tests where the extra request is undesirable.
@@ -494,6 +565,37 @@ Pre-v2.4.2 used the value `pass-through` — renamed in v2.4.2 to disambiguate "
 
 ## Changelog
 
+### v3.4.0 — Type alignment for LMAX settlement + step-up approval
+
+- `StepUpApprovalInfo` and `SettlementArtifact` interfaces added to `VerificationResult`
+- `stepUpApproval` surfaced in Express/MCP/Next.js adapter deny response bodies
+- `SettlementDecision` carries `stepUpApproval` on step-up denials via `authorizeSettlement()`
+- `getApprovalPollingInfo()` simplified — typed field, no more `unknown` casts
+- `Attestation.checkedAt` (required) — merchant freshness gate timestamp
+- `VERSION` constant updated to `3.4.0`
+
+### v3.3.0 — Direct-path value enforcement
+
+- `authorizeSettlement(config, { agentId, value, currency })` — fail-closed settlement gate for direct-path merchants
+- `restrictions` surfaces `approvalThreshold` (enforced per-tx) and `maxPerPeriod` (not yet enforced)
+- ASCII-safe agent-facing strings
+
+### v3.2.1 — Platform-agent go-live readiness
+
+- Canonical PDLSS limits terminology (`autonomousThreshold`, `approvalThreshold`)
+- Step-up/approval fail-closed in Express/MCP/Next.js adapters via `approval-gate.ts`
+
+### v3.2.0 — Commerce observability
+
+- Access-level band no longer gates (informational only); `requiresStepUp` carries the signal
+- Trust score redacted from agent-facing responses
+- Cross-merchant cache key fix
+
+### v3.1.0 — Canonical PDLSS vocabulary (Bug 14)
+
+- Two-axis purpose/action chains with dotted action tokens
+- Route send-mapping for tool→semantic-action translation
+
 ### v2.4.6 — Round-14 partner integration testing
 
 **⚠️ BREAKING CHANGE — `endpointUrl` → `counterpartyUrl` on `POST /api/endpoints` AND `PUT /api/endpoints/{id}`**

package/dist/adapter-interface/interface.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-Cj92yKeA.mjs';
-import '../types-Cwrvo30g.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-B-ubjHER.mjs';
+import '../types-CKe8O0lR.mjs';
 
 /**
  * PlatformAdapter Interface

package/dist/adapter-interface/interface.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-DOeL-dIw.js';
-import '../types-Cwrvo30g.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-Bgn5gxHQ.js';
+import '../types-CKe8O0lR.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-Cwrvo30g.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-CeFvNWDD.mjs';
+import '../types-CKe8O0lR.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BnMO-H3y.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-Cwrvo30g.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-RIh05wW2.js';
+import '../types-CKe8O0lR.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DQhDzNAt.js';

package/dist/adapters/express.js

@@ -25,6 +25,64 @@ __export(express_exports, {
 });
 module.exports = __toCommonJS(express_exports);
 
+// src/adapters/stepup-poll.ts
+var DEFAULT_POLL_INTERVAL_MS = 3e3;
+var MIN_POLL_INTERVAL_MS = 250;
+var FALLBACK_MAX_WAIT_MS = 5 * 60 * 1e3;
+var EXPIRY_GRACE_MS = 5e3;
+var POLL_REQUEST_TIMEOUT_MS = 1e4;
+function resolvePollUrl(config, pollUrl) {
+  if (pollUrl.startsWith("http")) return pollUrl;
+  const origin = (config.apiBaseUrl ?? "").replace(/\/api\/?$/, "");
+  return origin + pollUrl;
+}
+async function pollStepUpStatus(config, approval) {
+  if (!approval.pollUrl) return null;
+  try {
+    const res = await fetch(resolvePollUrl(config, approval.pollUrl), {
+      method: "GET",
+      signal: AbortSignal.timeout(POLL_REQUEST_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const data = body?.data;
+    const status = data && typeof data === "object" ? data.status : body?.status;
+    return typeof status === "string" ? status : null;
+  } catch {
+    return null;
+  }
+}
+function resolveDeadline(config, approval) {
+  const now = Date.now();
+  const maxWait = config.stepUpMaxWaitMs ?? 0;
+  if (maxWait > 0) return now + maxWait;
+  if (approval.expiresAt) {
+    const expiry = Date.parse(approval.expiresAt);
+    if (!Number.isNaN(expiry)) return Math.max(now, expiry) + EXPIRY_GRACE_MS;
+  }
+  return now + FALLBACK_MAX_WAIT_MS;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function awaitStepUpApproval(config, approval) {
+  const deadline = resolveDeadline(config, approval);
+  const pollInterval = Math.max(
+    MIN_POLL_INTERVAL_MS,
+    config.stepUpPollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+  );
+  while (Date.now() < deadline) {
+    const status = await pollStepUpStatus(config, approval);
+    if (status && status !== "pending") {
+      return status;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(pollInterval, remaining));
+  }
+  return "timeout";
+}
+
 // src/access-levels.ts
 function getTrustLevel(score) {
   if (score >= 80) return "PLATINUM";
@@ -34,7 +92,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.3.0";
+var SDK_VERSION = "3.6.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -104,10 +162,10 @@ var DEFAULT_CONFIG = {
   // through (`hasMinimumAccess('guidance', 'guidance') === true`).
   defaultAccessLevel: "none",
   // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
-  // Round-18.5 F4: cacheTtl deliberately unset. When undefined, cacheResult
-  // applies the split default (60s autonomous / 300s step-up). When the
-  // caller sets cacheTtl explicitly, that value is honoured uniformly.
-  // Set cacheTtl: 0 to disable caching entirely.
+  // cacheTtl deliberately unset. When undefined, cacheResult applies the 60s
+  // default; the caller's explicit value is honoured for cacheable results.
+  // Denials and step-up escalations are NEVER cached (3.6.0) regardless of
+  // cacheTtl. Set cacheTtl: 0 to disable caching entirely.
   debug: false
 };
 var initCheckPerformed = false;
@@ -194,10 +252,9 @@ function getCachedResult(request, counterpartyId) {
   }
   return null;
 }
-var DEFAULT_AUTONOMOUS_TTL_SECONDS = 60;
-var DEFAULT_STEP_UP_TTL_SECONDS = 300;
+var DEFAULT_CACHE_TTL_SECONDS = 60;
 function cacheResult(request, result, configuredTtl, counterpartyId) {
-  const ttlSeconds = configuredTtl && configuredTtl > 0 ? configuredTtl : result.requiresStepUp ? DEFAULT_STEP_UP_TTL_SECONDS : DEFAULT_AUTONOMOUS_TTL_SECONDS;
+  const ttlSeconds = configuredTtl && configuredTtl > 0 ? configuredTtl : DEFAULT_CACHE_TTL_SECONDS;
   const key = getCacheKey(request, counterpartyId);
   verificationCache.set(key, {
     result,
@@ -373,7 +430,7 @@ async function callVerifyAccessAPI(config, request) {
     };
   }
 }
-async function verify(config, request) {
+async function verify(config, request, options) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
@@ -389,7 +446,7 @@ async function verify(config, request) {
       "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access-level decisions (the SDK reads access.accessLevel from the verify-access response). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
     );
   }
-  if (mergedConfig.cacheTtl !== 0) {
+  if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache) {
     const cached = getCachedResult(request, mergedConfig.counterpartyId);
     if (cached) {
       if (mergedConfig.debug) {
@@ -409,6 +466,8 @@ async function verify(config, request) {
     console.log("[VerificationGateway] Calling verify-access API");
   }
   const apiResponse = await callVerifyAccessAPI(mergedConfig, enrichedRequest);
+  const rawServerDenialReasons = apiResponse.denialReasons;
+  const serverDenialReasons = Array.isArray(rawServerDenialReasons) && rawServerDenialReasons.length > 0 ? rawServerDenialReasons : void 0;
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
       source: "api_error",
@@ -430,7 +489,10 @@ async function verify(config, request) {
       // ALSO short-circuit on `!identityVerified || !policyAllowed` before
       // the gate check — belt-and-braces.
       accessLevel: "none",
-      denialReasons: aggregatedFailures && aggregatedFailures.length > 0 ? aggregatedFailures.map((f) => f.message) : apiResponse.access?.reason ? [apiResponse.access.reason] : ["Access denied"],
+      // 3.6.0: the server now emits top-level denialReasons on every deny
+      // path — prefer it verbatim; the failure-message reconstruction remains
+      // as the fallback for older backends.
+      denialReasons: serverDenialReasons ?? (aggregatedFailures && aggregatedFailures.length > 0 ? aggregatedFailures.map((f) => f.message) : apiResponse.access?.reason ? [apiResponse.access.reason] : ["Access denied"]),
       failures: aggregatedFailures,
       requiresStepUp: apiResponse.access?.requiresStepUp,
       requiresApproval: apiResponse.access?.requiresApproval,
@@ -507,9 +569,7 @@ async function verify(config, request) {
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
     result.accessLevel = "none";
-    result.denialReasons = result.recommendationReasons || [
-      "Access denied by AstraSync recommendation"
-    ];
+    result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Access denied by AstraSync recommendation"];
     result.guidance = result.runtimeChallenge ? {
       message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
       registrationUrl: urls?.registrationUrl ?? "",
@@ -521,9 +581,10 @@ async function verify(config, request) {
     };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
-    result.denialReasons = result.recommendationReasons || ["Step-up verification required"];
+    result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Step-up verification required"];
   }
-  if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny") {
+  const escalates = result.requiresStepUp === true || result.requiresApproval === true || result.recommendation === "step_up_required";
+  if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny" && !escalates) {
     cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
   }
   return result;
@@ -836,7 +897,10 @@ function defaultOnDenied(result, _req, res) {
       // Round-10: aggregated per-dimension detail + correlation handle.
       failures: result.failures,
       correlationId: result.correlationId,
-      stepUpApproval: result.stepUpApproval
+      stepUpApproval: result.stepUpApproval,
+      // 3.6.0: terminal outcome of an opt-in hold-and-poll wait (denied /
+      // expired / consumed / timeout). Absent when the feature is off.
+      ...result.stepUpOutcome && { stepUpOutcome: result.stepUpOutcome }
     }
   });
 }
@@ -986,7 +1050,22 @@ function createMiddleware(options) {
         );
       }
       const agentCardUrl = typeof req.headers["x-astrasync-agent-card"] === "string" ? req.headers["x-astrasync-agent-card"] : void 0;
-      const result = await verify(config, {
+      let txValue;
+      let txCurrency;
+      if (config.extractTransactionValue) {
+        try {
+          const extracted = config.extractTransactionValue(req);
+          if (extracted) {
+            txValue = extracted.value;
+            txCurrency = extracted.currency;
+          }
+        } catch (e) {
+          if (config.debug) {
+            console.warn("[VerificationGateway] extractTransactionValue threw:", e);
+          }
+        }
+      }
+      const verificationRequest = {
         credentials,
         purpose,
         action: pdlssPair.action,
@@ -996,6 +1075,8 @@ function createMiddleware(options) {
         counterpartyType: config.counterpartyType || "api",
         enableRuntimeChallenge,
         durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
+        ...txValue !== void 0 && { transactionValue: txValue },
+        ...txCurrency && { currency: txCurrency },
         callerMetadata: {
           sourceIp: originalClientIp,
           userAgent: req.headers["user-agent"],
@@ -1004,9 +1085,21 @@ function createMiddleware(options) {
           forwardedFor: forwardedForStr,
           agentCardUrl
         }
-      });
+      };
+      let result = await verify(config, verificationRequest);
       req.agentVerification = result;
-      const sessionId = result.sessionId;
+      let sessionId = result.sessionId;
+      if (config.stepUpMaxWaitMs !== void 0 && result.identityVerified && requiresHumanApproval(result) && result.stepUpApproval?.pollUrl) {
+        const outcome = await awaitStepUpApproval(config, result.stepUpApproval);
+        res.setHeader("X-Astra-Step-Up", outcome);
+        if (outcome === "approved") {
+          result = await verify(config, verificationRequest, { bypassCache: true });
+          req.agentVerification = result;
+          sessionId = result.sessionId;
+        } else {
+          result.stepUpOutcome = outcome;
+        }
+      }
       if (!result.identityVerified || !result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {