@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/interface-q1WrMsB1.d.mts

@@ -0,0 +1,365 @@
+/**
+ * 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';
+/**
+ * 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';
+    };
+}
+
+/**
+ * AstraSync Gateway - Types for gateway modes, local evaluation, and adapter interface.
+ */
+type GatewayMode = 'online' | 'local' | 'hybrid';
+/**
+ * Posture controls whether the gateway actively blocks or just monitors.
+ * - active: Evaluate and enforce decisions (block/allow/review)
+ * - passive: Evaluate and log but never block (telemetry-only mode)
+ */
+type GatewayPosture = 'active' | 'passive';
+interface AstraSyncGatewayConfig {
+    mode: GatewayMode;
+    /** Enforcement posture: 'active' blocks actions, 'passive' logs only (default: 'active') */
+    posture?: GatewayPosture;
+    /** AstraSync API base URL (required for online/hybrid modes) */
+    apiBaseUrl?: string;
+    /** API key for authenticating with AstraSync (required for online/hybrid modes) */
+    apiKey?: string;
+    /**
+     * ASTRA- agent id this gateway acts as. Attached to hybrid sync entries and
+     * used as the default identity for online verification when the caller
+     * passes no per-call astraId.
+     */
+    agentId?: string;
+    /** Path to local PDLSS policy YAML file (required for local/hybrid modes) */
+    policyFile?: string;
+    /** Inline policy object (alternative to policyFile) */
+    policy?: LocalPolicy;
+    /** Sync interval in seconds for hybrid mode (default: 3600) */
+    syncInterval?: number;
+    /** Cache verification results TTL in seconds (default: 300) */
+    cacheTtl?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable trace logging to .astrasync/traces/ (default: false) */
+    traceEnabled?: boolean;
+    /** Trace log directory (default: .astrasync/traces/) */
+    tracePath?: string;
+    /** Minimum trust score for standard access (online/hybrid) */
+    minTrustScore?: number;
+    /** Minimum trust score for full access (online/hybrid) */
+    minTrustScoreForFull?: number;
+    /** Custom headers to send with API requests */
+    customHeaders?: Record<string, string>;
+    /** Counterparty URL for analytics */
+    counterpartyUrl?: string;
+    /** Counterparty type for analytics */
+    counterpartyType?: CounterpartyType;
+}
+interface PDLSSContext {
+    /** Purpose category (e.g. email.send, shell.exec, file.read) */
+    purpose: string;
+    /** Specific action within purpose */
+    action: string;
+    /** Target resource, recipient, or counterparty */
+    target: string;
+    /** Types of data access (read, write, delete) */
+    dataAccess?: string[];
+    /** Network domains/IPs being accessed */
+    networkAccess?: string[];
+    /** Resource type (customer, order, file, directory, process) */
+    resourceType?: string;
+    /** Risk factors for this action */
+    riskFactors?: RiskFactor[];
+    /** Transaction value (if financial) */
+    transactionValue?: number;
+    /** Currency for transaction */
+    currency?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface RiskFactor {
+    type: 'financial' | 'data_sensitivity' | 'privilege_escalation' | 'network_scope' | 'destructive';
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    detail: string;
+}
+interface VerificationDecision {
+    recommendation: 'ALLOW' | 'DENY' | 'MANUAL_REVIEW';
+    reason: string;
+    trustScore?: number;
+    tokenGuidance?: TokenGuidance;
+    sessionId?: string;
+    /**
+     * PDLSS dimensions that were evaluated. `true` = the dimension was
+     * configured in the policy and therefore ran; `false` = the dimension is
+     * absent from the policy and was skipped — NOT "failed" (a failed
+     * dimension never produces an ALLOW; this field is only set on ALLOW).
+     */
+    evaluatedDimensions?: {
+        purpose: boolean;
+        scope: boolean;
+        limits: boolean;
+        riskThresholds: boolean;
+    };
+}
+interface LocalPolicy {
+    version: string;
+    name: string;
+    description?: string;
+    purposes: LocalPurposeRule[];
+    scope?: LocalScope;
+    limits?: LocalLimits;
+    riskThresholds?: LocalRiskThresholds;
+    selfInstantiation?: LocalSelfInstantiation;
+}
+interface LocalPurposeRule {
+    id: string;
+    allowed: boolean;
+    targets?: string[];
+    blockedPatterns?: string[];
+    requiresApproval?: boolean;
+}
+interface LocalScope {
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    blockedResources?: string[];
+}
+interface LocalLimits {
+    /**
+     * Autonomous Limit — a transaction value at or below this is granted without
+     * escalation. A value in the band `[autonomousThreshold, maxTransactionAmount)`
+     * requires human approval (step-up → MANUAL_REVIEW), mirroring the backend
+     * `checkWithinLimits` ladder. When omitted there is no autonomous band: every
+     * positive value below the Hard Limit is granted (legacy flat-cap behaviour).
+     */
+    autonomousThreshold?: number;
+    /**
+     * Hard Limit — a transaction value at or above this is denied outright. (Named
+     * `maxTransactionAmount` for backward compatibility with existing local policy
+     * files; it is the SDK equivalent of the backend `approvalThreshold`.)
+     */
+    maxTransactionAmount?: number;
+    maxRequestsPerHour?: number;
+    currency?: string;
+}
+interface LocalRiskThresholds {
+    autoAllow: {
+        min: number;
+        max: number;
+    };
+    requireApproval: {
+        min: number;
+        max: number;
+    };
+    autoBlock: {
+        min: number;
+        max: number;
+    };
+}
+interface LocalSelfInstantiation {
+    /** Whether sub-agent spawning is allowed */
+    allowed: boolean;
+    /** Maximum depth of sub-agent chain */
+    maxDepth?: number;
+}
+interface AgentAction {
+    /** Raw action data from the platform */
+    raw: unknown;
+    /** Platform identifier (e.g. 'openclaw-cli', 'cursor', 'browser') */
+    platform: string;
+    /** Timestamp of the action */
+    timestamp: Date;
+}
+interface InterceptResult {
+    /** Whether the action was intercepted */
+    intercepted: boolean;
+    /** Extracted PDLSS context (if intercepted) */
+    context?: PDLSSContext;
+    /** Reason for not intercepting (if not intercepted) */
+    skipReason?: string;
+}
+
+/**
+ * Hybrid Mode — Local evaluation for speed, async API sync for trust scoring.
+ *
+ * Immediate: local PDLSS evaluation (< 1ms)
+ * Async: queued API verification for audit trail and trust score updates
+ *
+ * Queue entries are persisted to disk so they survive process restarts.
+ */
+
+interface FlushOptions {
+    /** Max entries to attempt this flush (default: all pending). */
+    limit?: number;
+    /**
+     * Per-entry time budget in ms. A timed-out entry stays pending (no retry
+     * penalty — slow network is not a failure) and ends the flush early.
+     * Stateless callers (the Claude Code hook) use this to keep sync off the
+     * tool-call critical path.
+     */
+    perEntryTimeoutMs?: number;
+}
+
+/**
+ * AstraSyncGateway — Primary API surface for agent verification.
+ *
+ * Supports three operational modes:
+ * - online: Full API-based verification with trust scoring and audit trail
+ * - local: Offline PDLSS evaluation using a local policy file (no account required)
+ * - hybrid: Local eval for speed + async API sync for trust scoring
+ *
+ * @example
+ * ```typescript
+ * // Local mode (free, no account)
+ * const gateway = new AstraSyncGateway({ mode: 'local', policyFile: './policy.yaml' });
+ * const decision = await gateway.evaluate(context);
+ *
+ * // Online mode (paid, full features)
+ * const gateway = new AstraSyncGateway({ mode: 'online', apiKey: 'key' });
+ * const decision = await gateway.evaluate(context);
+ * ```
+ */
+
+declare class AstraSyncGateway {
+    private config;
+    private evaluator;
+    private syncQueue;
+    private traceLogger;
+    private initialized;
+    constructor(config: AstraSyncGatewayConfig);
+    private validateConfig;
+    /**
+     * Initialize the gateway (loads policy files, starts sync queues).
+     * Called automatically on first evaluate() if not called manually.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Graceful shutdown. Flushes sync queue and cleans up resources.
+     * Stateless callers (hooks) pass bounded flush options so sync never
+     * sits on a tool call's critical path.
+     */
+    shutdown(options?: {
+        syncFlush?: FlushOptions;
+    }): Promise<void>;
+    /**
+     * Evaluate an action against the verification policy.
+     * Routes to the appropriate mode handler.
+     *
+     * In passive posture, evaluation runs but always returns ALLOW
+     * (the real decision is logged for telemetry).
+     */
+    evaluate(context: PDLSSContext, astraId?: string): Promise<VerificationDecision>;
+    /**
+     * Get the current mode.
+     */
+    get mode(): AstraSyncGatewayConfig['mode'];
+    /**
+     * Get the current posture (active or passive).
+     */
+    get posture(): 'active' | 'passive';
+    /**
+     * Switch modes at runtime (e.g. after upgrade from free to paid).
+     */
+    switchMode(newMode: AstraSyncGatewayConfig['mode'], additionalConfig?: Partial<AstraSyncGatewayConfig>): Promise<void>;
+    /**
+     * Get sync queue status (hybrid mode only).
+     */
+    getSyncStatus(): {
+        pending: number;
+        total: number;
+    } | null;
+    /**
+     * Record a tool call the calling adapter saw but did not govern
+     * (unmapped tool, skipTools, MCP with governMcp off). Trace-only.
+     */
+    logSkippedTool(toolName: string, reason: string): void;
+}
+
+/**
+ * PlatformAdapter Interface
+ *
+ * The contract that Layer 4 platform adapters implement.
+ * Agent-side interception: governs what agents are allowed to do before they do it.
+ *
+ * Each adapter is 200-500 lines of platform-specific code.
+ * All verification logic lives in the gateway — adapters just translate
+ * between the platform's world and AstraSync's world.
+ */
+
+interface AdapterConfig {
+    /** The AstraSyncGateway instance (handles mode routing) */
+    gateway: AstraSyncGateway;
+    /** Platform-specific configuration */
+    adapterOptions: Record<string, unknown>;
+}
+interface PlatformAdapter {
+    /**
+     * Interface version for compatibility checking.
+     * Current version: 1.
+     */
+    readonly interfaceVersion: number;
+    /**
+     * Platform-specific initialization.
+     * Load config, register hooks, establish connections.
+     */
+    initialize(config: AdapterConfig): Promise<void>;
+    /**
+     * Graceful shutdown.
+     * Drain in-flight verifications, deregister hooks, close connections.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Intercept an agent action before execution.
+     *
+     * How this works depends on the platform:
+     * - CLI adapter: proxy server captures outbound request
+     * - Browser adapter: content script intercepts DOM interaction
+     * - Express: middleware captures inbound request
+     */
+    interceptAction(action: AgentAction): Promise<InterceptResult>;
+    /**
+     * Extract PDLSS-compatible context from a platform-specific action.
+     * Maps platform-native action format to the universal PDLSSContext.
+     */
+    extractContext(action: AgentAction): PDLSSContext;
+    /**
+     * Enforce the verification decision in a platform-specific way.
+     *
+     * How this works depends on the platform:
+     * - CLI: block command / allow command / prompt for approval
+     * - Browser: block navigation / show confirmation dialog
+     * - Express: return 403 / pass through / inject headers
+     */
+    enforceDecision(decision: VerificationDecision): Promise<void>;
+}
+
+export { type AdapterConfig as A, type InterceptResult as I, type LocalPolicy as L, type PDLSSContext as P, type VerificationDecision as V, type AgentAction as a, AstraSyncGateway as b, type LocalPurposeRule as c, type LocalRiskThresholds as d, type LocalScope as e, type PlatformAdapter as f };