@astrasyncai/verification-gateway 5.4.0 → 5.4.2

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

@@ -1,8 +1,258 @@
-import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-z_RNjHWm.mjs';
-import '../types-CD1F9fmp.mjs';
+import { T as TokenGuidance, b as CounterpartyType } from '../types-Bd2O3eX1.mjs';
 import '../metadata-capture.mjs';
 
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
 /**
  * Git Trigger — Enterprise git push / PR verification
  *

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

@@ -1,8 +1,258 @@
-import { AstraSyncGateway } from '../gateway/gateway.js';
-import { V as VerificationDecision, P as PDLSSContext } from '../types-DGh2akuh.js';
-import '../types-76TB0fxW.js';
+import { T as TokenGuidance, b as CounterpartyType } from '../types-DMChboN_.js';
 import '../metadata-capture.js';
 
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
 /**
  * Git Trigger — Enterprise git push / PR verification
  *