@astrasyncai/verification-gateway 3.4.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-Cj92yKeA.mjs';
-import '../types-Cwrvo30g.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-DOeL-dIw.js';
-import '../types-Cwrvo30g.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-Cwrvo30g.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-CeFvNWDD.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-Cwrvo30g.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-RIh05wW2.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;
@@ -986,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,
@@ -996,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"],