@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/types-BfILnheI.d.mts

@@ -0,0 +1,189 @@
+/**
+ * AstraSync Universal Verification Gateway Types
+ *
+ * TypeScript type definitions for agent verification across all counterparty types.
+ */
+
+/**
+ * Types of counterparties that can integrate the gateway
+ */
+type CounterpartyType = 'agent' | 'api' | 'mcp_server' | 'website' | 'other' | 'unknown';
+/**
+ * Configuration options for the verification gateway
+ */
+interface GatewayConfig {
+    /** AstraSync API base URL */
+    apiBaseUrl: string;
+    /** API key for authenticating with AstraSync. */
+    apiKey?: string;
+    /**
+     * @deprecated Removed in v2.3.0 — server is the single source of truth for
+     * access decisions (verified ID + runtime challenge + PDLSS + trust score).
+     * Setting this no longer affects access decisions. If you need a higher gate
+     * for an endpoint, configure it server-side via the endpoint's
+     * `trust_score_requirement`.
+     */
+    minTrustScore?: number;
+    /**
+     * @deprecated Removed in v2.3.0 — see `minTrustScore` above.
+     */
+    minTrustScoreForFull?: number;
+    /** Cache verification results (TTL in seconds) */
+    cacheTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom headers to send with verification requests */
+    customHeaders?: Record<string, string>;
+    /** This counterparty's URL (sent with verify-access requests for analytics) */
+    counterpartyUrl?: string;
+    /** This counterparty's type (sent with verify-access requests for analytics) */
+    counterpartyType?: CounterpartyType;
+    /**
+     * This counterparty's ASTRAE-id (issued at endpoint registration). When set,
+     * the SDK forwards it on verify-access calls so the server attributes traffic
+     * directly to this endpoint rather than resolving by URL. Useful when:
+     *  - The merchant has multiple endpoints under the same origin (each running
+     *    its own SDK instance with its own counterpartyId)
+     *  - The endpoint URL might be served behind a proxy / different host than
+     *    the registered origin
+     */
+    counterpartyId?: string;
+    /**
+     * Step-up hold-and-poll (3.6.0, opt-in). When set, adapters HOLD a request
+     * whose verify() came back step_up_required, poll the approval status, and
+     * on 'approved' re-verify the same request once (cache-bypassed) so the
+     * backend redeems the single-use approval — the MFA model the Java SDK
+     * ships default-on. Values:
+     *  - undefined (default): feature OFF — adapters fail closed immediately,
+     *    exactly as 3.5.0 (a minor release must not silently convert instant
+     *    403s into multi-minute holds).
+     *  - 0: hold until the approval's expiresAt (+5s grace); 5-min fallback
+     *    when expiresAt is missing/unparsable (Java parity).
+     *  - >0: hold at most this many milliseconds.
+     * Next.js edge runtimes enforce ~25s wall-clock budgets — set a small value
+     * there (≤20000) or gate in a Node route handler instead.
+     */
+    stepUpMaxWaitMs?: number;
+    /**
+     * Poll interval for the step-up hold (3.6.0). Default 3000ms, clamped to a
+     * 250ms floor. At the default the backend's 60/min/IP poll rate limit
+     * tolerates ~3 concurrent holds per merchant IP; poll errors are treated as
+     * transient, so limiter hits degrade the hold to 'timeout', never an error.
+     */
+    stepUpPollIntervalMs?: number;
+    /**
+     * Disable the one-time init self-test. The SDK normally fires a HEAD/OPTIONS
+     * to `${apiBaseUrl}/agents/verify-access` on first verify() call and warns
+     * if the response is HTML (indicating apiBaseUrl is pointing at a marketing
+     * site rather than the API). Set true for tests or environments where the
+     * extra request is undesirable.
+     */
+    disableInitChecks?: boolean;
+    /**
+     * When true, the init self-test runs synchronously on the first verify()
+     * call and THROWS on misconfig (apiBaseUrl returning HTML, unreachable,
+     * etc.) instead of warning + continuing. Recommended for production
+     * deploys where you want a fast-fail startup signal rather than silent
+     * verify-access call failures. Default false for backward compatibility.
+     */
+    strictInit?: boolean;
+    /**
+     * 4.0.0: hard timeout (ms) on the outbound verify-access call. Without it
+     * a hanging backend hangs the merchant's middleware — and every inbound
+     * agent request behind it — indefinitely. Timeouts surface as the
+     * fail-closed `verify_access.api_error` result. Default 10_000.
+     */
+    verifyTimeoutMs?: number;
+    /**
+     * v2.3.8: emit `X-Astra-Gateway-Mode: unenforced` (with
+     * `X-Astra-Gateway-Reason: no-policy | no-match`) on responses where the
+     * middleware fell through without consulting verify-access. Lets integration
+     * tests assert "this endpoint should be gated; if it falls through, fail
+     * loudly". Default off; opt-in.
+     *
+     * The header value was renamed from the ambiguous `pass-through` to
+     * `unenforced` so it describes the GATE state only — not whether the
+     * request succeeded end-to-end. The config FLAG name
+     * (`setPassThroughHeader`) is unchanged for backwards compatibility.
+     */
+    setPassThroughHeader?: boolean;
+    /**
+     * v2.3.8: dashboard origin used to construct configuration links in
+     * boot-time warnings (e.g. when no per-route policy is configured).
+     * Defaults to `https://astrasync.ai/dashboard` (the `app.astrasync.ai`
+     * subdomain referenced in older docs does not resolve).
+     */
+    dashboardUrl?: string;
+    /**
+     * When true, the middleware calls verify-access for any request that presents
+     * AstraSync credentials, even on `observe`-marked routes / tools that would
+     * otherwise pass through unevaluated. Populates `req.agentVerification` and
+     * records the verification event for the audit trail. Enforcement still
+     * respects the gate — an `observe` marker still passes through regardless of
+     * the server decision. Default false to preserve existing behaviour.
+     *
+     * Use this when a single endpoint serves both anonymous and verified
+     * traffic with different response shapes (e.g. anonymous catalog vs
+     * verified catalog with agent-only SKUs; anonymous MCP tool listing
+     * vs verified tool-listing with restricted tools surfaced). Without
+     * the flag, anonymous-with-credentials passes are invisible to the
+     * merchant handler and to the AstraSync activity feed.
+     *
+     * Lives on `GatewayConfig` (not adapter-specific) so both express and
+     * MCP middlewares inherit it via their `extends GatewayConfig` chain.
+     */
+    evaluateAlwaysIfCredentialed?: boolean;
+}
+/**
+ * Token guidance returned from verify-access.
+ *
+ * `recommendedRateLimit` carries `requestsPerMinute` and `currency` only.
+ * `maxTransactionValue` was removed in v2.2.4 — it leaked the agent's
+ * spending headroom to the merchant, which is a price-discrimination signal
+ * (a merchant could see the agent's autonomous threshold and price the
+ * transaction just under it to capture surplus). The agent's SDK receives
+ * its own limits separately for client-side budgeting; the merchant's
+ * decision doesn't need amount info.
+ */
+interface TokenGuidance {
+    recommendedScopes: string[];
+    recommendedTtlSeconds: number;
+    recommendedRateLimit?: {
+        requestsPerMinute: number;
+        currency?: string;
+    };
+    jurisdictionConstraints?: string[];
+    delegationAllowed: boolean;
+    maxDelegationDepth?: number;
+    safetyDefaults: {
+        writePrivilegesRequested: boolean;
+        shortLivedTokenRecommended: boolean;
+        scopeConvention: 'astrasync-canonical';
+    };
+}
+/**
+ * Cross-protocol credential config
+ */
+interface AstraSyncCredentials {
+    agentId: string;
+    verifyUrl?: string;
+    challengeUrl?: string;
+    pdlss?: {
+        purpose?: {
+            category: string;
+            action?: string;
+        };
+        duration?: {
+            maxSessionDuration?: number;
+        };
+        scope?: {
+            jurisdiction?: string;
+        };
+    };
+}
+/**
+ * Protocol transport type
+ */
+type ProtocolTransport = 'http' | 'a2a' | 'mcp';
+
+export type { AstraSyncCredentials as A, CounterpartyType as C, GatewayConfig as G, ProtocolTransport as P, TokenGuidance as T };

package/dist/types-BfILnheI.d.ts

@@ -0,0 +1,189 @@
+/**
+ * AstraSync Universal Verification Gateway Types
+ *
+ * TypeScript type definitions for agent verification across all counterparty types.
+ */
+
+/**
+ * Types of counterparties that can integrate the gateway
+ */
+type CounterpartyType = 'agent' | 'api' | 'mcp_server' | 'website' | 'other' | 'unknown';
+/**
+ * Configuration options for the verification gateway
+ */
+interface GatewayConfig {
+    /** AstraSync API base URL */
+    apiBaseUrl: string;
+    /** API key for authenticating with AstraSync. */
+    apiKey?: string;
+    /**
+     * @deprecated Removed in v2.3.0 — server is the single source of truth for
+     * access decisions (verified ID + runtime challenge + PDLSS + trust score).
+     * Setting this no longer affects access decisions. If you need a higher gate
+     * for an endpoint, configure it server-side via the endpoint's
+     * `trust_score_requirement`.
+     */
+    minTrustScore?: number;
+    /**
+     * @deprecated Removed in v2.3.0 — see `minTrustScore` above.
+     */
+    minTrustScoreForFull?: number;
+    /** Cache verification results (TTL in seconds) */
+    cacheTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom headers to send with verification requests */
+    customHeaders?: Record<string, string>;
+    /** This counterparty's URL (sent with verify-access requests for analytics) */
+    counterpartyUrl?: string;
+    /** This counterparty's type (sent with verify-access requests for analytics) */
+    counterpartyType?: CounterpartyType;
+    /**
+     * This counterparty's ASTRAE-id (issued at endpoint registration). When set,
+     * the SDK forwards it on verify-access calls so the server attributes traffic
+     * directly to this endpoint rather than resolving by URL. Useful when:
+     *  - The merchant has multiple endpoints under the same origin (each running
+     *    its own SDK instance with its own counterpartyId)
+     *  - The endpoint URL might be served behind a proxy / different host than
+     *    the registered origin
+     */
+    counterpartyId?: string;
+    /**
+     * Step-up hold-and-poll (3.6.0, opt-in). When set, adapters HOLD a request
+     * whose verify() came back step_up_required, poll the approval status, and
+     * on 'approved' re-verify the same request once (cache-bypassed) so the
+     * backend redeems the single-use approval — the MFA model the Java SDK
+     * ships default-on. Values:
+     *  - undefined (default): feature OFF — adapters fail closed immediately,
+     *    exactly as 3.5.0 (a minor release must not silently convert instant
+     *    403s into multi-minute holds).
+     *  - 0: hold until the approval's expiresAt (+5s grace); 5-min fallback
+     *    when expiresAt is missing/unparsable (Java parity).
+     *  - >0: hold at most this many milliseconds.
+     * Next.js edge runtimes enforce ~25s wall-clock budgets — set a small value
+     * there (≤20000) or gate in a Node route handler instead.
+     */
+    stepUpMaxWaitMs?: number;
+    /**
+     * Poll interval for the step-up hold (3.6.0). Default 3000ms, clamped to a
+     * 250ms floor. At the default the backend's 60/min/IP poll rate limit
+     * tolerates ~3 concurrent holds per merchant IP; poll errors are treated as
+     * transient, so limiter hits degrade the hold to 'timeout', never an error.
+     */
+    stepUpPollIntervalMs?: number;
+    /**
+     * Disable the one-time init self-test. The SDK normally fires a HEAD/OPTIONS
+     * to `${apiBaseUrl}/agents/verify-access` on first verify() call and warns
+     * if the response is HTML (indicating apiBaseUrl is pointing at a marketing
+     * site rather than the API). Set true for tests or environments where the
+     * extra request is undesirable.
+     */
+    disableInitChecks?: boolean;
+    /**
+     * When true, the init self-test runs synchronously on the first verify()
+     * call and THROWS on misconfig (apiBaseUrl returning HTML, unreachable,
+     * etc.) instead of warning + continuing. Recommended for production
+     * deploys where you want a fast-fail startup signal rather than silent
+     * verify-access call failures. Default false for backward compatibility.
+     */
+    strictInit?: boolean;
+    /**
+     * 4.0.0: hard timeout (ms) on the outbound verify-access call. Without it
+     * a hanging backend hangs the merchant's middleware — and every inbound
+     * agent request behind it — indefinitely. Timeouts surface as the
+     * fail-closed `verify_access.api_error` result. Default 10_000.
+     */
+    verifyTimeoutMs?: number;
+    /**
+     * v2.3.8: emit `X-Astra-Gateway-Mode: unenforced` (with
+     * `X-Astra-Gateway-Reason: no-policy | no-match`) on responses where the
+     * middleware fell through without consulting verify-access. Lets integration
+     * tests assert "this endpoint should be gated; if it falls through, fail
+     * loudly". Default off; opt-in.
+     *
+     * The header value was renamed from the ambiguous `pass-through` to
+     * `unenforced` so it describes the GATE state only — not whether the
+     * request succeeded end-to-end. The config FLAG name
+     * (`setPassThroughHeader`) is unchanged for backwards compatibility.
+     */
+    setPassThroughHeader?: boolean;
+    /**
+     * v2.3.8: dashboard origin used to construct configuration links in
+     * boot-time warnings (e.g. when no per-route policy is configured).
+     * Defaults to `https://astrasync.ai/dashboard` (the `app.astrasync.ai`
+     * subdomain referenced in older docs does not resolve).
+     */
+    dashboardUrl?: string;
+    /**
+     * When true, the middleware calls verify-access for any request that presents
+     * AstraSync credentials, even on `observe`-marked routes / tools that would
+     * otherwise pass through unevaluated. Populates `req.agentVerification` and
+     * records the verification event for the audit trail. Enforcement still
+     * respects the gate — an `observe` marker still passes through regardless of
+     * the server decision. Default false to preserve existing behaviour.
+     *
+     * Use this when a single endpoint serves both anonymous and verified
+     * traffic with different response shapes (e.g. anonymous catalog vs
+     * verified catalog with agent-only SKUs; anonymous MCP tool listing
+     * vs verified tool-listing with restricted tools surfaced). Without
+     * the flag, anonymous-with-credentials passes are invisible to the
+     * merchant handler and to the AstraSync activity feed.
+     *
+     * Lives on `GatewayConfig` (not adapter-specific) so both express and
+     * MCP middlewares inherit it via their `extends GatewayConfig` chain.
+     */
+    evaluateAlwaysIfCredentialed?: boolean;
+}
+/**
+ * Token guidance returned from verify-access.
+ *
+ * `recommendedRateLimit` carries `requestsPerMinute` and `currency` only.
+ * `maxTransactionValue` was removed in v2.2.4 — it leaked the agent's
+ * spending headroom to the merchant, which is a price-discrimination signal
+ * (a merchant could see the agent's autonomous threshold and price the
+ * transaction just under it to capture surplus). The agent's SDK receives
+ * its own limits separately for client-side budgeting; the merchant's
+ * decision doesn't need amount info.
+ */
+interface TokenGuidance {
+    recommendedScopes: string[];
+    recommendedTtlSeconds: number;
+    recommendedRateLimit?: {
+        requestsPerMinute: number;
+        currency?: string;
+    };
+    jurisdictionConstraints?: string[];
+    delegationAllowed: boolean;
+    maxDelegationDepth?: number;
+    safetyDefaults: {
+        writePrivilegesRequested: boolean;
+        shortLivedTokenRecommended: boolean;
+        scopeConvention: 'astrasync-canonical';
+    };
+}
+/**
+ * Cross-protocol credential config
+ */
+interface AstraSyncCredentials {
+    agentId: string;
+    verifyUrl?: string;
+    challengeUrl?: string;
+    pdlss?: {
+        purpose?: {
+            category: string;
+            action?: string;
+        };
+        duration?: {
+            maxSessionDuration?: number;
+        };
+        scope?: {
+            jurisdiction?: string;
+        };
+    };
+}
+/**
+ * Protocol transport type
+ */
+type ProtocolTransport = 'http' | 'a2a' | 'mcp';
+
+export type { AstraSyncCredentials as A, CounterpartyType as C, GatewayConfig as G, ProtocolTransport as P, TokenGuidance as T };

package/dist/{types-z_RNjHWm.d.mts → types-CfBpm3w5.d.mts}

@@ -1,4 +1,4 @@
-import { i as CounterpartyType, T as TokenGuidance } from './types-CD1F9fmp.mjs';
+import { C as CounterpartyType, T as TokenGuidance } from './types-BfILnheI.mjs';
 
 /**
  * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.
@@ -172,4 +172,4 @@ interface InterceptResult {
     skipReason?: string;
 }
 
-export type { AgentAction as A, InterceptResult as I, LocalPolicy as L, PDLSSContext as P, VerificationDecision as V, AstraSyncGatewayConfig as a, LocalPurposeRule as b, LocalRiskThresholds as c, LocalScope as d };
+export type { AgentAction as A, InterceptResult as I, LocalPolicy as L, PDLSSContext as P, VerificationDecision as V, AstraSyncGatewayConfig as a, LocalPurposeRule as b };