@astrasyncai/verification-gateway 3.2.0 → 3.3.0

package/dist/git-trigger/git-hooks.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-BNiLZY0i.mjs';
-import '../types-rFh4VMH4.mjs';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-ClvUqrEm.mjs';
+import '../types-B_wnd7ZX.mjs';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/git-trigger/git-hooks.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-DJi-u3fz.js';
-import '../types-rFh4VMH4.js';
+import { V as VerificationDecision, P as PDLSSContext } from '../types-B6uD4jAI.js';
+import '../types-B_wnd7ZX.js';
 
 /**
  * Git Trigger — Enterprise git push / PR verification

package/dist/{index-DtGziFEm.d.mts → index-BLeiWFLu.d.mts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-rFh4VMH4.mjs';
+import { c as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-B_wnd7ZX.mjs';
 
 /**
  * AgentClient — Credential Presentation

package/dist/{index-DBmlycVm.d.ts → index-DFwfHOGj.d.ts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport, G as GatewayConfig } from './types-rFh4VMH4.js';
+import { c as AstraSyncCredentials, g as ProtocolTransport, G as GatewayConfig } from './types-B_wnd7ZX.js';
 
 /**
  * AgentClient — Credential Presentation

package/dist/{index-DzXXBuLm.d.ts → index-E3fAidVt.d.ts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-rFh4VMH4.js';
+import { c as AstraSyncCredentials, g as ProtocolTransport } from './types-B_wnd7ZX.js';
 import { JWK } from 'jose';
 
 /**

package/dist/{index-B51W8gn8.d.mts → index-kxLJ873R.d.mts}

@@ -1,4 +1,4 @@
-import { b as AstraSyncCredentials, f as ProtocolTransport } from './types-rFh4VMH4.mjs';
+import { c as AstraSyncCredentials, g as ProtocolTransport } from './types-B_wnd7ZX.mjs';
 import { JWK } from 'jose';
 
 /**

package/dist/index.d.mts

@@ -1,12 +1,12 @@
-import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-rFh4VMH4.mjs';
-export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-rFh4VMH4.mjs';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-e5jg7sqW.mjs';
-export { e as express } from './express-CeoSdOAZ.mjs';
-export { n as nextjs } from './nextjs-BW1rzr1I.mjs';
-export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-B51W8gn8.mjs';
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, V as VerificationRequest, j as VerificationResult, E as EnhancedVerificationResult, A as AccessFailure } from './types-B_wnd7ZX.mjs';
+export { c as AstraSyncCredentials, C as CommerceShieldProps, d as CounterpartyType, e as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, k as VerifiedAgent, l as VerifiedDeveloper, m as VerifiedOrganization } from './types-B_wnd7ZX.mjs';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-D1MuiiNz.mjs';
+export { e as express } from './express-DAOTESQo.mjs';
+export { n as nextjs } from './nextjs-CFQ_KDFf.mjs';
+export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-kxLJ873R.mjs';
 export { McpMiddlewareOptions, ToolGateConfig, createMcpMiddleware } from './adapters/mcp.mjs';
 export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.mjs';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DtGziFEm.mjs';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-BLeiWFLu.mjs';
 import 'express';
 import 'next/server';
 import 'jose';
@@ -50,6 +50,53 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     reason?: string;
 }>;
 
+/**
+ * Settlement authorization — the value-aware, FAIL-CLOSED gate a direct merchant
+ * MUST call before settling a priced cart (post-#447 partner round, finding #1).
+ *
+ * The bug it closes: the SDK request middleware performs a header-only ACCESS
+ * check and never sends the transaction VALUE to verify-access, so the limit
+ * engine never evaluates value and returns `grant` — a fully SDK-compliant
+ * merchant settles every band, with the agent's PDLSS spend limits silently
+ * unenforced. The bridge is safe only because `confirm_purchase` re-verifies
+ * with the authoritative session total.
+ *
+ * The authoritative value exists ONLY after the merchant prices the cart (in the
+ * handler, after the middleware), and it must be the MERCHANT's priced total —
+ * never an agent-suppliable header (spoofable). So value enforcement is a
+ * settlement-time, merchant-invoked call that mirrors the bridge: verify the
+ * priced value against the agent's limits and refuse settlement unless it
+ * cleanly grants.
+ */
+
+interface SettlementRequest {
+    /** The agent's ASTRA-id (the caller you are about to settle for). */
+    agentId: string;
+    /** The MERCHANT's authoritative priced total for the cart. Never an agent-supplied amount. */
+    value: number;
+    /** ISO-4217 currency of `value`. */
+    currency: string;
+    /** Defaults to the canonical commerce pair; override for custom categories (e.g. 'trading' / 'trading.execute'). */
+    purpose?: string;
+    action?: string;
+}
+interface SettlementDecision {
+    /** TRUE only on a clean grant. A step-up/approval outcome, any deny, a missing value, or a verify error all → false. */
+    authorized: boolean;
+    recommendation?: EnhancedVerificationResult['recommendation'];
+    reason?: string;
+    failures?: AccessFailure[];
+    correlationId?: string;
+}
+/**
+ * Authorize a settlement of `value` for `agentId` against the agent's PDLSS
+ * limits. FAIL-CLOSED: returns `authorized:false` on a missing/invalid value,
+ * a verify-access error, a step-up/approval outcome (the value is in the
+ * human-approval band and cannot complete autonomously), or any policy deny.
+ * Settle ONLY when `authorized === true`.
+ */
+declare function authorizeSettlement(config: GatewayConfig, req: SettlementRequest): Promise<SettlementDecision>;
+
 /**
  * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
  *
@@ -107,4 +154,4 @@ declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCom
 
 declare const VERSION = "2.0.0";
 
-export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };
+export { AccessLevel, AgentCredentials, EnhancedVerificationResult, GatewayConfig, type SettlementDecision, type SettlementRequest, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, authorizeSettlement, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { a as AgentCredentials, G as GatewayConfig, A as AccessLevel, V as VerificationRequest, i as VerificationResult } from './types-rFh4VMH4.js';
-export { b as AstraSyncCredentials, C as CommerceShieldProps, c as CounterpartyType, E as EnhancedVerificationResult, d as ExpressMiddlewareOptions, e as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, f as ProtocolTransport, R as RouteAccessConfig, g as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, h as TrustLevel, j as VerifiedAgent, k as VerifiedDeveloper, l as VerifiedOrganization } from './types-rFh4VMH4.js';
-export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-ZYgI7G9f.js';
-export { e as express } from './express-BowlMHQF.js';
-export { n as nextjs } from './nextjs-V_K0qlAQ.js';
-export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-DzXXBuLm.js';
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, V as VerificationRequest, j as VerificationResult, E as EnhancedVerificationResult, A as AccessFailure } from './types-B_wnd7ZX.js';
+export { c as AstraSyncCredentials, C as CommerceShieldProps, d as CounterpartyType, e as ExpressMiddlewareOptions, f as GuidanceInfo, N as NextJsMiddlewareOptions, P as PDLSSInfo, g as ProtocolTransport, R as RouteAccessConfig, h as RuntimeChallengeResult, S as SDKOptions, T as TokenGuidance, i as TrustLevel, k as VerifiedAgent, l as VerifiedDeveloper, m as VerifiedOrganization } from './types-B_wnd7ZX.js';
+export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as AccessCapabilities, D as DEFAULT_TRUST_THRESHOLDS, T as TRUST_LEVEL_RANGES, d as determineAccessLevel, g as getAccessLevelForScore, e as getCapabilities, f as getTrustLevel, h as hasMinimumAccess, s as sdk } from './sdk-C7qAfpGB.js';
+export { e as express } from './express-Lb8-Ybio.js';
+export { n as nextjs } from './nextjs-BXK0nD73.js';
+export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-E3fAidVt.js';
 export { McpMiddlewareOptions, ToolGateConfig, createMcpMiddleware } from './adapters/mcp.js';
 export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.js';
-export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DBmlycVm.js';
+export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DFwfHOGj.js';
 import 'express';
 import 'next/server';
 import 'jose';
@@ -50,6 +50,53 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     reason?: string;
 }>;
 
+/**
+ * Settlement authorization — the value-aware, FAIL-CLOSED gate a direct merchant
+ * MUST call before settling a priced cart (post-#447 partner round, finding #1).
+ *
+ * The bug it closes: the SDK request middleware performs a header-only ACCESS
+ * check and never sends the transaction VALUE to verify-access, so the limit
+ * engine never evaluates value and returns `grant` — a fully SDK-compliant
+ * merchant settles every band, with the agent's PDLSS spend limits silently
+ * unenforced. The bridge is safe only because `confirm_purchase` re-verifies
+ * with the authoritative session total.
+ *
+ * The authoritative value exists ONLY after the merchant prices the cart (in the
+ * handler, after the middleware), and it must be the MERCHANT's priced total —
+ * never an agent-suppliable header (spoofable). So value enforcement is a
+ * settlement-time, merchant-invoked call that mirrors the bridge: verify the
+ * priced value against the agent's limits and refuse settlement unless it
+ * cleanly grants.
+ */
+
+interface SettlementRequest {
+    /** The agent's ASTRA-id (the caller you are about to settle for). */
+    agentId: string;
+    /** The MERCHANT's authoritative priced total for the cart. Never an agent-supplied amount. */
+    value: number;
+    /** ISO-4217 currency of `value`. */
+    currency: string;
+    /** Defaults to the canonical commerce pair; override for custom categories (e.g. 'trading' / 'trading.execute'). */
+    purpose?: string;
+    action?: string;
+}
+interface SettlementDecision {
+    /** TRUE only on a clean grant. A step-up/approval outcome, any deny, a missing value, or a verify error all → false. */
+    authorized: boolean;
+    recommendation?: EnhancedVerificationResult['recommendation'];
+    reason?: string;
+    failures?: AccessFailure[];
+    correlationId?: string;
+}
+/**
+ * Authorize a settlement of `value` for `agentId` against the agent's PDLSS
+ * limits. FAIL-CLOSED: returns `authorized:false` on a missing/invalid value,
+ * a verify-access error, a step-up/approval outcome (the value is in the
+ * human-approval band and cannot complete autonomously), or any policy deny.
+ * Settle ONLY when `authorized === true`.
+ */
+declare function authorizeSettlement(config: GatewayConfig, req: SettlementRequest): Promise<SettlementDecision>;
+
 /**
  * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
  *
@@ -107,4 +154,4 @@ declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCom
 
 declare const VERSION = "2.0.0";
 
-export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };
+export { AccessLevel, AgentCredentials, EnhancedVerificationResult, GatewayConfig, type SettlementDecision, type SettlementRequest, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, authorizeSettlement, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };

package/dist/index.js

@@ -45,6 +45,7 @@ __export(src_exports, {
   TRUST_LEVEL_RANGES: () => TRUST_LEVEL_RANGES,
   VERSION: () => VERSION,
   agent: () => agent_exports,
+  authorizeSettlement: () => authorizeSettlement,
   buildGuidance: () => buildGuidance,
   clearCache: () => clearCache,
   createMcpMiddleware: () => createMcpMiddleware,
@@ -192,7 +193,7 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.2.0";
+var SDK_VERSION = "3.3.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -742,6 +743,67 @@ async function quickVerify(config, credentials) {
   };
 }
 
+// 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.";
+function requiresHumanApproval(result) {
+  return result.requiresStepUp === true || result.requiresApproval === true;
+}
+function annotateApprovalRequired(result) {
+  result.failures = [
+    ...result.failures ?? [],
+    { dimension: "commerce.intent.approval_required", message: APPROVAL_REASON }
+  ];
+  result.denialReasons = [APPROVAL_REASON, ...result.denialReasons ?? []];
+}
+
+// src/settlement.ts
+async function authorizeSettlement(config, req) {
+  if (typeof req.value !== "number" || !Number.isFinite(req.value) || req.value <= 0) {
+    return {
+      authorized: false,
+      recommendation: "deny",
+      reason: "No valid transaction value supplied to authorizeSettlement; settlement refused (fail-closed). Pass the merchant-priced cart total as `value`.",
+      failures: [
+        {
+          dimension: "commerce.settlement.value_missing",
+          message: "A positive, authoritative transaction value is required to authorize settlement."
+        }
+      ]
+    };
+  }
+  let result;
+  try {
+    result = await verify(config, {
+      credentials: { astraId: req.agentId },
+      purpose: req.purpose ?? "shopping",
+      action: req.action ?? "shopping.purchase",
+      transactionValue: req.value,
+      currency: req.currency
+    });
+  } catch (err) {
+    return {
+      authorized: false,
+      recommendation: "deny",
+      reason: `Settlement verification failed (${err instanceof Error ? err.message : String(err)}); settlement refused (fail-closed).`,
+      failures: [
+        {
+          dimension: "commerce.settlement.verify_error",
+          message: "verify-access could not be reached or returned an error; settlement is refused."
+        }
+      ]
+    };
+  }
+  const recommendation = result.recommendation;
+  const authorized = result.identityVerified === true && result.policyAllowed === true && !requiresHumanApproval(result) && (recommendation === void 0 || recommendation === "grant");
+  return {
+    authorized,
+    recommendation,
+    reason: authorized ? void 0 : result.denialReasons?.[0] ?? (requiresHumanApproval(result) ? "Transaction is above the autonomous limit and requires human approval; settlement cannot be authorized automatically." : "Settlement not authorized by the agent's PDLSS limits."),
+    failures: result.failures,
+    correlationId: result.correlationId
+  };
+}
+
 // src/adapters/express.ts
 var express_exports = {};
 __export(express_exports, {
@@ -1205,6 +1267,16 @@ function createMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (requiresHumanApproval(result)) {
+        annotateApprovalRequired(result);
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        dedupeFailures(result);
+        onDenied(result, req, res);
+        return;
+      }
       if (!shouldEnforce) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -1652,7 +1724,9 @@ function createMiddleware2(options) {
         agentCardUrl: request.headers.get("x-astrasync-agent-card") || void 0
       }
     });
-    if (!result.identityVerified || !result.policyAllowed) {
+    const approvalRequired = result.identityVerified && result.policyAllowed && requiresHumanApproval(result);
+    if (approvalRequired) annotateApprovalRequired(result);
+    if (!result.identityVerified || !result.policyAllowed || approvalRequired) {
       if (pathname.startsWith("/api/")) {
         return NextResponse.json(
           {
@@ -1662,7 +1736,8 @@ function createMiddleware2(options) {
               // OK, policy denied (update PDLSS / step up).
               code: !result.identityVerified ? "UNAUTHORIZED" : "POLICY_DENIED",
               message: result.denialReasons?.[0] || "Access denied",
-              guidance: result.guidance
+              guidance: result.guidance,
+              failures: result.failures
             }
           },
           { status: !result.identityVerified ? 401 : 403 }
@@ -4733,6 +4808,16 @@ function createMcpMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (requiresHumanApproval(result)) {
+        annotateApprovalRequired(result);
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        dedupeFailures2(result);
+        onDenied(result, req, res);
+        return;
+      }
       if (!shouldEnforce) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -5498,6 +5583,7 @@ var VERSION = "2.0.0";
   TRUST_LEVEL_RANGES,
   VERSION,
   agent,
+  authorizeSettlement,
   buildGuidance,
   clearCache,
   createMcpMiddleware,