@astrasyncai/verification-gateway 3.8.0 → 3.10.0

package/dist/{types-DedAJbNI.d.ts → types-sy3tq8lp.d.mts}

@@ -1,8 +1,11 @@
+import { ObservedMetadata } from './metadata-capture.mjs';
+
 /**
  * AstraSync Universal Verification Gateway Types
  *
  * TypeScript type definitions for agent verification across all counterparty types.
  */
+
 /**
  * Trust levels assigned to agents based on their composite trust score
  */
@@ -498,6 +501,15 @@ interface CallerMetadata {
     forwardedFor?: string;
     /** Published agent card URL, if the agent advertised one (future: from agent headers). */
     agentCardUrl?: string;
+    /**
+     * The full sanitised view of the agent's inbound request headers + connection
+     * signals (Workstream D — maximal metadata capture). Produced by
+     * `sanitizeHeaders` (genuine secrets removed, credential headers reduced to a
+     * safe format prefix). Forwarded so the endpoint owner sees every wire signal
+     * about the agent, not just IP/UA. Local string work only — kept OUT of the
+     * verify cache key so per-request maps don't defeat verdict caching.
+     */
+    observedMetadata?: ObservedMetadata;
 }
 interface VerificationRequest {
     /** Agent credentials */
@@ -560,6 +572,81 @@ interface VerificationRequest {
      * visibility into transport-vs-intent.
      */
     invocationProtocol?: 'rest' | 'mcp' | 'a2a' | 'acp' | 'ap2' | 'mpp' | 'ucp';
+    /**
+     * 3.9.0 (§33.5 #1) — raw commerce-protocol artifacts forwarded verbatim
+     * to verify-access, whose Step 0.5 commerce pipeline runs the full
+     * cryptographic verification SERVER-side and persists commerce_context on
+     * the session. Adapters forward artifacts, they never verify them locally
+     * (bridge-is-transport: verify-access is the sole verification sink, so
+     * every decision is recorded once, with events). Shape mirrors the
+     * backend's `commerceArtifacts` schema 1:1.
+     */
+    commerceArtifacts?: CommerceArtifactsPayload;
+}
+/**
+ * Raw commerce-protocol artifacts as verify-access accepts them (backend
+ * `validation.ts` → `commerceArtifacts`). All optional; send what was
+ * detected on the wire.
+ */
+interface CommerceArtifactsPayload {
+    /** Compact VI SD-JWT. */
+    viSdJwt?: string;
+    /** AP2 mandate triple as compact SD-JWTs. */
+    ap2Mandates?: {
+        intent?: string;
+        cart?: string;
+        payment?: string;
+    };
+    /** RFC 9421 signed request (Agent Pay / TAP / Web Bot Auth). */
+    rfc9421?: {
+        headers: Record<string, string | string[]>;
+        method: string;
+        url: string;
+        body?: string;
+        tag?: string;
+    };
+    /** UCP checkout session request. */
+    ucpRequest?: {
+        method: string;
+        url: string;
+        body?: unknown;
+    };
+    /** ACP request (HMAC-signed webhook or checkout body). */
+    acpRequest?: {
+        method: string;
+        url: string;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+        rawBody?: string;
+    };
+    mppRequest?: {
+        method: string;
+        url: string;
+        headers: Record<string, string | string[]>;
+        body?: unknown;
+        rawBody?: string;
+    };
+    mppResponse?: {
+        status: number;
+        headers: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    x402Request?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    x402Response?: {
+        status?: number;
+        headers?: Record<string, string | string[]>;
+        body?: unknown;
+    };
+    stripeWebhook?: {
+        payload: string;
+        signatureHeader: string;
+        secret: string;
+    };
 }
 /**
  * Route-specific access configuration
@@ -842,4 +929,4 @@ interface CommerceShieldProps {
     className?: string;
 }
 
-export type { AccessFailure as A, CommerceShieldProps as C, EnhancedVerificationResult as E, FiatSettlementBinding as F, GatewayConfig as G, NextJsMiddlewareOptions as N, PDLSSInfo as P, RouteAccessConfig as R, SDKOptions as S, TokenGuidance as T, VerificationRequest as V, AccessLevel as a, AgentCredentials as b, AstraSyncCredentials as c, CounterpartyType as d, ExpressMiddlewareOptions as e, GuidanceInfo as f, ProtocolTransport as g, RuntimeChallengeResult as h, SettlementArtifact as i, SettlementArtifactBinding as j, SettlementArtifactBindingBase as k, StablecoinSettlementBinding as l, StepUpApprovalInfo as m, StepUpApprovalStatus as n, StepUpOutcome as o, TrustLevel as p, VerificationResult as q, VerifiedAgent as r, VerifiedDeveloper as s, VerifiedOrganization as t };
+export type { AccessFailure as A, CommerceArtifactsPayload as C, EnhancedVerificationResult as E, FiatSettlementBinding as F, GatewayConfig as G, NextJsMiddlewareOptions as N, PDLSSInfo as P, RouteAccessConfig as R, SDKOptions as S, TokenGuidance as T, VerificationRequest as V, AccessLevel as a, AgentCredentials as b, AstraSyncCredentials as c, CommerceShieldProps as d, CounterpartyType as e, ExpressMiddlewareOptions as f, GuidanceInfo as g, ProtocolTransport as h, RuntimeChallengeResult as i, SettlementArtifact as j, SettlementArtifactBinding as k, SettlementArtifactBindingBase as l, StablecoinSettlementBinding as m, StepUpApprovalInfo as n, StepUpApprovalStatus as o, StepUpOutcome as p, TrustLevel as q, VerificationResult as r, VerifiedAgent as s, VerifiedDeveloper as t, VerifiedOrganization as u };

package/dist/ui/index.d.mts

@@ -1,4 +1,5 @@
-import { C as CommerceShieldProps, q as VerificationResult, b as AgentCredentials, f as GuidanceInfo, p as TrustLevel } from '../types-DedAJbNI.mjs';
+import { d as CommerceShieldProps, r as VerificationResult, b as AgentCredentials, g as GuidanceInfo, q as TrustLevel } from '../types-sy3tq8lp.mjs';
+import '../metadata-capture.mjs';
 
 /**
  * AstraSync Commerce Shield Component

package/dist/ui/index.d.ts

@@ -1,4 +1,5 @@
-import { C as CommerceShieldProps, q as VerificationResult, b as AgentCredentials, f as GuidanceInfo, p as TrustLevel } from '../types-DedAJbNI.js';
+import { d as CommerceShieldProps, r as VerificationResult, b as AgentCredentials, g as GuidanceInfo, q as TrustLevel } from '../types-9tns4wyl.js';
+import '../metadata-capture.js';
 
 /**
  * AstraSync Commerce Shield Component

package/dist/verify.d.mts

@@ -0,0 +1,151 @@
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, V as VerificationRequest, r as VerificationResult } from './types-sy3tq8lp.mjs';
+import { ObservedMetadata } from './metadata-capture.mjs';
+
+/**
+ * AstraSync Universal Verification Gateway - Core Verification Logic
+ *
+ * This module handles the core verification logic, calling the AstraSync API
+ * and processing the response into a standardized VerificationResult.
+ */
+
+/**
+ * Clear the verification cache
+ */
+declare function clearCache(): void;
+/**
+ * Extract agent credentials from various sources
+ */
+declare function extractCredentials(headers: Record<string, string | string[] | undefined>, query?: Record<string, string | undefined>): AgentCredentials;
+/**
+ * Check if credentials are present
+ */
+declare function hasCredentials(credentials: AgentCredentials): boolean;
+/**
+ * Options for a single verify() call (as opposed to GatewayConfig, which is
+ * per-gateway). Mirrors the Java SDK's `verify(request, bypassCache)`.
+ */
+interface VerifyOptions {
+    /**
+     * Skip the cache READ for this call so the request is guaranteed to reach
+     * the backend (the result is still written to the cache if cacheable).
+     * Used by the step-up hold-and-poll retry: the re-verify after an approval
+     * must hit the server to redeem the single-use approval.
+     */
+    bypassCache?: boolean;
+}
+/**
+ * Main verification function
+ */
+declare function verify(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Record a counterparty's grant/deny decision for a verification session.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function recordDecision(config: GatewayConfig, sessionId: string, decision: 'granted' | 'denied', reason?: string): Promise<void>;
+/**
+ * Fetch the per-route policy for an endpoint from the AstraSync backend.
+ * v2.9.7 moved policy authority into the dashboard — the SDK no longer
+ * accepts `routes` from merchant-side source code, it fetches them from
+ * here on init (and refreshes periodically).
+ *
+ * Returns `null` when the request fails for any reason — the caller decides
+ * how to fall back (the middleware allows-all when no policy is loaded so
+ * a misconfigured init doesn't take down the merchant's API).
+ */
+declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): Promise<RouteAccessConfigShape[] | null>;
+/**
+ * Minimal shape of an EndpointRoute as the SDK consumes it. Mirrors the
+ * server's `EndpointRoute` type and the SDK's `RouteAccessConfig` — same
+ * JSON moves between server and SDK unchanged.
+ */
+interface RouteAccessConfigShape {
+    pattern: string;
+    method: string;
+    /** @deprecated 3.2.0 — band no longer gates; optional, ignored. Use minTrustScore. */
+    minAccessLevel?: 'none' | 'restricted' | 'read-only' | 'standard' | 'full' | 'internal';
+    minTrustScore?: number;
+    requiredPurposes?: string[];
+    allowedPurposes?: string[];
+    allowedJurisdictions?: string[];
+    maxDuration?: number;
+    maxTransactionValue?: number;
+    requirePurpose?: boolean;
+    /** Send-mapping (Bug 14, §4.6) — see RouteAccessConfig in types.ts. */
+    purpose?: string;
+    action?: string;
+}
+/**
+ * Verify an agent AND automatically record the grant/deny decision.
+ *
+ * This is the recommended entry point for counterparties that call verify()
+ * directly (e.g. MCP servers) rather than using createMiddleware().
+ * It adds createSession: true, then fire-and-forgets the decision.
+ */
+declare function verifyAndRecord(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Report an unregistered agent attempt (no AstraSync credentials).
+ * Called by SDK adapters when an agent is redirected to /docs/agent-access.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function reportUnregisteredAttempt(config: GatewayConfig, data: {
+    /**
+     * 3.6.0: optional — the backend attributes by counterpartyId first (sent
+     * from config below) and requires at least ONE of counterpartyId/URL.
+     * A null/undefined URL is omitted from the body, not sent as null.
+     */
+    counterpartyUrl?: string;
+    counterpartyType?: string;
+    sourceIp?: string;
+    userAgent?: string;
+    requestPath?: string;
+    requestMethod?: string;
+    /**
+     * 3.9.0 (§33.5 #1) — edge-adapter evidence fields, persisted into the
+     * event's eventData by the backend: `protocol` = detected transport/
+     * credential protocol; `evidence` = light crypto-free detection detail.
+     */
+    protocol?: string;
+    evidence?: Record<string, unknown>;
+    /**
+     * Workstream D — the full sanitised metadata capture for an unregistered
+     * caller. Persisted into eventData; feeds platform attribution and (via
+     * correlationId) registration auto-fill. Fire-and-forget, so free.
+     */
+    observedMetadata?: ObservedMetadata;
+}): Promise<void>;
+/**
+ * Report a counterparty-side PDLSS pre-check failure.
+ * Called by SDK adapters when the agent's requested PDLSS exceeds
+ * counterparty-defined maximums BEFORE calling verify-access.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function reportCounterpartyPreCheckFailure(config: GatewayConfig, data: {
+    agentId: string;
+    counterpartyUrl: string;
+    counterpartyType?: string;
+    failures: Array<{
+        field: string;
+        requested: string | number;
+        limit: string | number | string[];
+        message: string;
+    }>;
+    requestPath?: string;
+    requestMethod?: string;
+}): Promise<void>;
+/**
+ * Quick verification — checks credentials and policy in one call.
+ *
+ * Round-18 G4: return shape mirrors `VerificationResult`'s split — partners
+ * writing custom handlers around `quickVerify` get the same identity/policy
+ * distinction as those calling `verify()` directly. Map to HTTP status the
+ * same way: `!identityVerified` → 401; `identityVerified && !policyAllowed`
+ * → 403.
+ */
+declare function quickVerify(config: GatewayConfig, credentials: AgentCredentials): Promise<{
+    identityVerified: boolean;
+    policyAllowed: boolean;
+    accessLevel: AccessLevel;
+    reason?: string;
+}>;
+
+export { type RouteAccessConfigShape, type VerifyOptions, clearCache, extractCredentials, fetchRoutes, hasCredentials, quickVerify, recordDecision, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };

package/dist/verify.d.ts

@@ -0,0 +1,151 @@
+import { b as AgentCredentials, G as GatewayConfig, a as AccessLevel, V as VerificationRequest, r as VerificationResult } from './types-9tns4wyl.js';
+import { ObservedMetadata } from './metadata-capture.js';
+
+/**
+ * AstraSync Universal Verification Gateway - Core Verification Logic
+ *
+ * This module handles the core verification logic, calling the AstraSync API
+ * and processing the response into a standardized VerificationResult.
+ */
+
+/**
+ * Clear the verification cache
+ */
+declare function clearCache(): void;
+/**
+ * Extract agent credentials from various sources
+ */
+declare function extractCredentials(headers: Record<string, string | string[] | undefined>, query?: Record<string, string | undefined>): AgentCredentials;
+/**
+ * Check if credentials are present
+ */
+declare function hasCredentials(credentials: AgentCredentials): boolean;
+/**
+ * Options for a single verify() call (as opposed to GatewayConfig, which is
+ * per-gateway). Mirrors the Java SDK's `verify(request, bypassCache)`.
+ */
+interface VerifyOptions {
+    /**
+     * Skip the cache READ for this call so the request is guaranteed to reach
+     * the backend (the result is still written to the cache if cacheable).
+     * Used by the step-up hold-and-poll retry: the re-verify after an approval
+     * must hit the server to redeem the single-use approval.
+     */
+    bypassCache?: boolean;
+}
+/**
+ * Main verification function
+ */
+declare function verify(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Record a counterparty's grant/deny decision for a verification session.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function recordDecision(config: GatewayConfig, sessionId: string, decision: 'granted' | 'denied', reason?: string): Promise<void>;
+/**
+ * Fetch the per-route policy for an endpoint from the AstraSync backend.
+ * v2.9.7 moved policy authority into the dashboard — the SDK no longer
+ * accepts `routes` from merchant-side source code, it fetches them from
+ * here on init (and refreshes periodically).
+ *
+ * Returns `null` when the request fails for any reason — the caller decides
+ * how to fall back (the middleware allows-all when no policy is loaded so
+ * a misconfigured init doesn't take down the merchant's API).
+ */
+declare function fetchRoutes(config: GatewayConfig, counterpartyId: string): Promise<RouteAccessConfigShape[] | null>;
+/**
+ * Minimal shape of an EndpointRoute as the SDK consumes it. Mirrors the
+ * server's `EndpointRoute` type and the SDK's `RouteAccessConfig` — same
+ * JSON moves between server and SDK unchanged.
+ */
+interface RouteAccessConfigShape {
+    pattern: string;
+    method: string;
+    /** @deprecated 3.2.0 — band no longer gates; optional, ignored. Use minTrustScore. */
+    minAccessLevel?: 'none' | 'restricted' | 'read-only' | 'standard' | 'full' | 'internal';
+    minTrustScore?: number;
+    requiredPurposes?: string[];
+    allowedPurposes?: string[];
+    allowedJurisdictions?: string[];
+    maxDuration?: number;
+    maxTransactionValue?: number;
+    requirePurpose?: boolean;
+    /** Send-mapping (Bug 14, §4.6) — see RouteAccessConfig in types.ts. */
+    purpose?: string;
+    action?: string;
+}
+/**
+ * Verify an agent AND automatically record the grant/deny decision.
+ *
+ * This is the recommended entry point for counterparties that call verify()
+ * directly (e.g. MCP servers) rather than using createMiddleware().
+ * It adds createSession: true, then fire-and-forgets the decision.
+ */
+declare function verifyAndRecord(config: GatewayConfig, request: VerificationRequest, options?: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Report an unregistered agent attempt (no AstraSync credentials).
+ * Called by SDK adapters when an agent is redirected to /docs/agent-access.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function reportUnregisteredAttempt(config: GatewayConfig, data: {
+    /**
+     * 3.6.0: optional — the backend attributes by counterpartyId first (sent
+     * from config below) and requires at least ONE of counterpartyId/URL.
+     * A null/undefined URL is omitted from the body, not sent as null.
+     */
+    counterpartyUrl?: string;
+    counterpartyType?: string;
+    sourceIp?: string;
+    userAgent?: string;
+    requestPath?: string;
+    requestMethod?: string;
+    /**
+     * 3.9.0 (§33.5 #1) — edge-adapter evidence fields, persisted into the
+     * event's eventData by the backend: `protocol` = detected transport/
+     * credential protocol; `evidence` = light crypto-free detection detail.
+     */
+    protocol?: string;
+    evidence?: Record<string, unknown>;
+    /**
+     * Workstream D — the full sanitised metadata capture for an unregistered
+     * caller. Persisted into eventData; feeds platform attribution and (via
+     * correlationId) registration auto-fill. Fire-and-forget, so free.
+     */
+    observedMetadata?: ObservedMetadata;
+}): Promise<void>;
+/**
+ * Report a counterparty-side PDLSS pre-check failure.
+ * Called by SDK adapters when the agent's requested PDLSS exceeds
+ * counterparty-defined maximums BEFORE calling verify-access.
+ * Fire-and-forget — errors are silently swallowed.
+ */
+declare function reportCounterpartyPreCheckFailure(config: GatewayConfig, data: {
+    agentId: string;
+    counterpartyUrl: string;
+    counterpartyType?: string;
+    failures: Array<{
+        field: string;
+        requested: string | number;
+        limit: string | number | string[];
+        message: string;
+    }>;
+    requestPath?: string;
+    requestMethod?: string;
+}): Promise<void>;
+/**
+ * Quick verification — checks credentials and policy in one call.
+ *
+ * Round-18 G4: return shape mirrors `VerificationResult`'s split — partners
+ * writing custom handlers around `quickVerify` get the same identity/policy
+ * distinction as those calling `verify()` directly. Map to HTTP status the
+ * same way: `!identityVerified` → 401; `identityVerified && !policyAllowed`
+ * → 403.
+ */
+declare function quickVerify(config: GatewayConfig, credentials: AgentCredentials): Promise<{
+    identityVerified: boolean;
+    policyAllowed: boolean;
+    accessLevel: AccessLevel;
+    reason?: string;
+}>;
+
+export { type RouteAccessConfigShape, type VerifyOptions, clearCache, extractCredentials, fetchRoutes, hasCredentials, quickVerify, recordDecision, reportCounterpartyPreCheckFailure, reportUnregisteredAttempt, verify, verifyAndRecord };