@astrasyncai/verification-gateway 3.3.0 → 3.5.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
@@ -494,6 +549,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-ClvUqrEm.mjs';
-import '../types-B_wnd7ZX.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-C8HyQEaz.mjs';
+import '../types-DrDIouvO.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-B6uD4jAI.js';
-import '../types-B_wnd7ZX.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-xofemo0G.js';
+import '../types-DrDIouvO.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-B_wnd7ZX.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DAOTESQo.mjs';
+import '../types-DrDIouvO.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BH5ADAyb.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-B_wnd7ZX.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-Lb8-Ybio.js';
+import '../types-DrDIouvO.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-jUzLIoep.js';

package/dist/adapters/express.js

@@ -34,7 +34,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.3.0";
+var SDK_VERSION = "3.5.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -446,7 +446,9 @@ async function verify(config, request) {
       // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
       recommendation: apiResponse.recommendation,
-      recommendationReasons: apiResponse.recommendationReasons
+      recommendationReasons: apiResponse.recommendationReasons,
+      stepUpApproval: apiResponse.stepUpApproval,
+      settlement: apiResponse.settlement
     };
     return result2;
   }
@@ -498,7 +500,9 @@ async function verify(config, request) {
     tokenGuidance: apiResponse.tokenGuidance,
     recommendation: apiResponse.recommendation,
     recommendationReasons: apiResponse.recommendationReasons,
-    warningHeader: apiResponse.warningHeader
+    warningHeader: apiResponse.warningHeader,
+    stepUpApproval: apiResponse.stepUpApproval,
+    settlement: apiResponse.settlement
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
@@ -692,7 +696,7 @@ function resolveHttpPdlss(input) {
 }
 
 // src/adapters/approval-gate.ts
-var APPROVAL_REASON = "Transaction is above the autonomous limit and requires human approval, which is not yet available - it cannot be completed automatically.";
+var APPROVAL_REASON = "Transaction is above the autonomous limit and requires human approval. The agent owner can approve or deny this transaction in the AstraSync dashboard.";
 function requiresHumanApproval(result) {
   return result.requiresStepUp === true || result.requiresApproval === true;
 }
@@ -831,7 +835,8 @@ function defaultOnDenied(result, _req, res) {
       guidance: result.guidance,
       // Round-10: aggregated per-dimension detail + correlation handle.
       failures: result.failures,
-      correlationId: result.correlationId
+      correlationId: result.correlationId,
+      stepUpApproval: result.stepUpApproval
     }
   });
 }
@@ -981,6 +986,21 @@ function createMiddleware(options) {
         );
       }
       const agentCardUrl = typeof req.headers["x-astrasync-agent-card"] === "string" ? req.headers["x-astrasync-agent-card"] : void 0;
+      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 result = await verify(config, {
         credentials,
         purpose,
@@ -991,6 +1011,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"],