@kya-os/checkpoint-wasm-runtime 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -1,5 +1,319 @@
-import { h as IWasmLoader, l as IWasmBindings, a as IDetectorOptions, I as IDetector } from './rules-detector-ZIKHN-_y.js';
-export { C as CONFIDENCE, D as DetectionClass, c as DynamicWasmLoader, F as ForgeabilityRisk, d as ICustomerPolicy, e as IDetectedAgent, b as IDetectionInput, f as IDetectionResult, m as IPathRule, g as IPolicyLoader, n as PolicyLoadError, P as PolicyLoader, o as PolicyLoaderConfig, R as RulesDetector, V as VerificationMethod, W as WasmDetector, i as createDynamicLoader, j as createPolicyLoader, k as createRulesDetector } from './rules-detector-ZIKHN-_y.js';
+/**
+ * AgentShield WASM Runtime Types
+ *
+ * Core interfaces following SOLID principles:
+ * - Interface Segregation: Small, focused interfaces
+ * - Dependency Inversion: Depend on abstractions
+ */
+/**
+ * Detection input - information about the request to analyze
+ */
+interface IDetectionInput {
+    /** User-Agent header value */
+    userAgent?: string;
+    /** Client IP address */
+    ipAddress?: string;
+    /** All request headers */
+    headers: Record<string, string>;
+    /** Request URL path */
+    url?: string;
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Client fingerprint data (for browser detection) */
+    clientFingerprint?: string;
+    /** Request timestamp */
+    timestamp?: Date;
+}
+/**
+ * Verification method used to detect the agent
+ */
+type VerificationMethod = 'signature' | 'pattern' | 'behavioral' | 'network' | 'mcp_i_handshake' | 'none';
+/**
+ * Detection class - categorization of the detected entity
+ */
+type DetectionClass = {
+    type: 'Human';
+} | {
+    type: 'AiAgent';
+    agentType: string;
+} | {
+    type: 'Bot';
+    botType?: string;
+} | {
+    type: 'Automation';
+    toolType?: string;
+} | {
+    type: 'Unknown';
+};
+/**
+ * Forgeability risk level
+ * How easy it is to spoof the detection signals
+ */
+type ForgeabilityRisk = 'low' | 'medium' | 'high';
+/**
+ * Detected agent information
+ */
+interface IDetectedAgent {
+    /** Agent type identifier (e.g., 'openai', 'anthropic') */
+    type: string;
+    /** Human-readable agent name (e.g., 'ChatGPT', 'Claude') */
+    name: string;
+    /** Vendor/company name */
+    vendor?: string;
+    /** Model identifier if known */
+    model?: string;
+    /** Version if known */
+    version?: string;
+}
+/**
+ * Detection result - output from the detection engine
+ * Confidence is ALWAYS on 0-100 scale
+ */
+interface IDetectionResult {
+    /** Whether the request was identified as coming from an agent */
+    isAgent: boolean;
+    /** Confidence score on 0-100 scale (NOT 0-1) */
+    confidence: number;
+    /** Detection classification */
+    detectionClass: DetectionClass;
+    /** Detected agent details if identified */
+    detectedAgent?: IDetectedAgent;
+    /** Method used for verification */
+    verificationMethod: VerificationMethod;
+    /** Risk level of signal forgeability */
+    forgeabilityRisk: ForgeabilityRisk;
+    /** Reasons/signals that contributed to detection */
+    reasons: string[];
+    /** Detection timestamp */
+    timestamp: Date;
+    /** Whether the request should be blocked (set by policy) */
+    shouldBlock?: boolean;
+    /** Reason for blocking (set by policy) */
+    blockReason?: string;
+}
+/**
+ * WASM bindings interface - functions exposed by the WASM module
+ */
+interface IWasmBindings {
+    /** Detect an agent from request metadata */
+    detect_agent(metadata: IWasmRequestMetadata): IWasmDetectionResult;
+    /** Get WASM module version */
+    get_version(): string;
+    /** Get build information */
+    get_build_info(): string;
+}
+/**
+ * WASM request metadata - input to WASM detect_agent function
+ */
+interface IWasmRequestMetadata {
+    user_agent: string | null;
+    ip_address: string | null;
+    headers: string;
+    timestamp: string;
+    url: string | null;
+    method: string | null;
+    client_fingerprint: string | null;
+    free(): void;
+}
+/**
+ * WASM detection result - output from WASM detect_agent function
+ */
+interface IWasmDetectionResult {
+    is_agent: boolean;
+    confidence: number;
+    agent: string | null;
+    verification_method: string;
+    risk_level: string;
+    timestamp: string;
+}
+/**
+ * WASM loader interface - abstracts WASM loading strategy
+ */
+interface IWasmLoader {
+    /** Load the WASM module */
+    load(): Promise<void>;
+    /** Get the WASM bindings after loading */
+    getBindings(): IWasmBindings;
+    /** Check if WASM is loaded */
+    isLoaded(): boolean;
+    /** Get the loading strategy name */
+    getStrategy(): string;
+}
+/**
+ * Agent detector interface - main detection API
+ */
+interface IDetector {
+    /** Analyze a request and detect if it's from an agent */
+    detect(input: IDetectionInput): Promise<IDetectionResult>;
+    /** Check if the detector is ready */
+    isReady(): boolean;
+    /** Ensure the detector is initialized */
+    ensureReady(): Promise<void>;
+    /** Get detector version */
+    getVersion(): Promise<string>;
+}
+/**
+ * Customer policy - rules for agent handling
+ */
+interface ICustomerPolicy {
+    /** Project ID */
+    projectId: string;
+    /** Agents to always block */
+    denyList?: string[];
+    /** Agents to always allow (if set, blocks all others) */
+    allowList?: string[];
+    /** Minimum confidence to trigger blocking */
+    blockThreshold?: number;
+    /** Path-based rules */
+    pathRules?: IPathRule[];
+    /** Policy version for cache invalidation */
+    version?: string;
+    /** Last updated timestamp */
+    updatedAt?: Date;
+}
+/**
+ * Path-based rule for policy
+ */
+interface IPathRule {
+    /** Path pattern (glob or regex) */
+    pattern: string;
+    /** Action for matching paths */
+    action: 'allow' | 'block' | 'challenge';
+    /** Specific agents this rule applies to */
+    agents?: string[];
+}
+/**
+ * Policy loader interface - loads customer policies
+ */
+interface IPolicyLoader {
+    /** Load policy for an API key */
+    loadPolicy(apiKey: string): Promise<ICustomerPolicy>;
+    /** Get cached policy if available */
+    getCachedPolicy(apiKey: string): ICustomerPolicy | null;
+    /** Invalidate cached policy */
+    invalidateCache(apiKey: string): void;
+}
+/**
+ * Detector configuration options
+ */
+interface IDetectorOptions {
+    /** API key for loading customer policies */
+    apiKey?: string;
+    /** Custom WASM loader (for Edge Runtime static imports) */
+    wasmLoader?: IWasmLoader;
+    /** Whether to fall back to JavaScript if WASM fails */
+    fallbackToJS?: boolean;
+    /** Whether to cache policies */
+    cachePolicy?: boolean;
+    /** Policy cache TTL in milliseconds */
+    policyTTL?: number;
+    /** Base URL for policy API */
+    policyApiUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Confidence thresholds - centralized constants
+ */
+declare const CONFIDENCE: {
+    /** Minimum confidence for isAgent=true */
+    readonly THRESHOLD_AGENT: 30;
+    /** Cryptographic signature verified */
+    readonly SIGNATURE_VERIFIED: 100;
+    /** Signature header present but not verified */
+    readonly SIGNATURE_PRESENT: 85;
+    /** Strong pattern match */
+    readonly PATTERN_HIGH: 85;
+    /** Moderate pattern match */
+    readonly PATTERN_MEDIUM: 60;
+    /** Weak pattern match */
+    readonly PATTERN_LOW: 40;
+    /** Cloud IP detection only */
+    readonly CLOUD_IP: 30;
+};
+
+/**
+ * Unified WASM Detector
+ *
+ * Single implementation of the AgentShield detection engine used by all packages.
+ * Follows the Single Responsibility Principle: this class only handles detection.
+ *
+ * Key design decisions:
+ * - Confidence is ALWAYS on 0-100 scale (no conversions needed)
+ * - WASM output is used directly (no post-processing adjustments)
+ * - Policy application is optional and happens after detection
+ */
+
+/**
+ * Unified WASM Detector
+ *
+ * Main detection class that wraps the WASM engine and provides
+ * a consistent interface across all AgentShield packages.
+ */
+declare class WasmDetector implements IDetector {
+    private readonly loader;
+    private readonly policyLoader?;
+    private readonly options;
+    private ready;
+    private loadPromise;
+    /**
+     * Create a new WasmDetector
+     * @param loader - WASM loader (static for Edge, dynamic for Node.js)
+     * @param policyLoader - Optional policy loader for API key support
+     * @param options - Detector configuration options
+     */
+    constructor(loader: IWasmLoader, policyLoader?: IPolicyLoader | undefined, options?: IDetectorOptions);
+    /**
+     * Analyze a request and detect if it's from an agent
+     */
+    detect(input: IDetectionInput): Promise<IDetectionResult>;
+    /**
+     * Check if the detector is ready
+     */
+    isReady(): boolean;
+    /**
+     * Ensure the detector is initialized
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Get detector version
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Initialize the detector
+     */
+    private initialize;
+    /**
+     * Apply customer policy to detection result
+     */
+    private applyPolicy;
+    /**
+     * Check if agent name matches a policy list entry
+     * Uses exact match or word-boundary prefix match to avoid false positives
+     * e.g., "gpt" matches "ChatGPT" and "GPT-4" but not "EgyptBot"
+     */
+    private matchesPolicyEntry;
+    /**
+     * Escape special regex characters in a string
+     */
+    private escapeRegex;
+    /**
+     * Apply policy rules to detection result
+     */
+    private applyPolicyRules;
+    /**
+     * Infer agent type from name
+     */
+    private inferAgentType;
+    /**
+     * Extract reasons from WASM result
+     */
+    private extractReasons;
+    /**
+     * Create default result (assumed human)
+     */
+    private createDefaultResult;
+}
 
 /**
  * Static WASM Loader for Edge Runtime
@@ -70,6 +384,220 @@ declare class StaticWasmLoader implements IWasmLoader {
  */
 declare function createStaticLoader(wasmModule: WebAssembly.Module): StaticWasmLoader;
 
+/**
+ * Dynamic WASM Loader for Node.js
+ *
+ * This loader dynamically loads and compiles WASM at runtime,
+ * which is supported in Node.js but NOT in Edge Runtime.
+ *
+ * Usage:
+ * ```typescript
+ * import { DynamicWasmLoader, WasmDetector } from '@kya-os/checkpoint-wasm-runtime/node';
+ *
+ * const loader = new DynamicWasmLoader();
+ * const detector = new WasmDetector(loader);
+ * ```
+ */
+
+/**
+ * Dynamic WASM Loader
+ *
+ * For Node.js environments that support dynamic WASM compilation.
+ * Automatically finds and loads the WASM module.
+ */
+declare class DynamicWasmLoader implements IWasmLoader {
+    private readonly wasmPath?;
+    private bindings;
+    private instance;
+    private loadPromise;
+    /**
+     * Create a new DynamicWasmLoader
+     * @param wasmPath - Optional custom path to WASM file
+     */
+    constructor(wasmPath?: string | undefined);
+    /**
+     * Load and compile the WASM module
+     */
+    load(): Promise<void>;
+    private doLoad;
+    /**
+     * Get the WASM bindings after loading
+     */
+    getBindings(): IWasmBindings;
+    /**
+     * Check if WASM is loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Get the loading strategy name
+     */
+    getStrategy(): string;
+    /**
+     * Create wasm-bindgen required imports
+     */
+    private createWasmBindgenImports;
+    /**
+     * Create bindings wrapper from WASM exports
+     */
+    private createBindings;
+}
+/**
+ * Create a dynamic loader
+ */
+declare function createDynamicLoader(wasmPath?: string): DynamicWasmLoader;
+
+/**
+ * Policy Loader
+ *
+ * Loads customer policies from the AgentShield API.
+ * Supports LRU caching with background refresh.
+ */
+
+/**
+ * Policy loader configuration
+ */
+interface PolicyLoaderConfig {
+    /** Base URL for the policy API */
+    apiUrl?: string;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTTL?: number;
+    /** Maximum number of policies to cache (default: 100) */
+    maxCacheSize?: number;
+    /** Enable background refresh (default: true) */
+    backgroundRefresh?: boolean;
+    /** Timeout for API requests in milliseconds (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Policy Loader
+ *
+ * Loads and caches customer policies from the AgentShield API.
+ * Follows Single Responsibility Principle: only handles policy loading.
+ */
+declare class PolicyLoader implements IPolicyLoader {
+    private cache;
+    private config;
+    constructor(config?: PolicyLoaderConfig);
+    /**
+     * Load policy for an API key
+     */
+    loadPolicy(apiKey: string): Promise<ICustomerPolicy>;
+    /**
+     * Get cached policy if available and not expired
+     */
+    getCachedPolicy(apiKey: string): ICustomerPolicy | null;
+    /**
+     * Invalidate cached policy
+     */
+    invalidateCache(apiKey: string): void;
+    /**
+     * Fetch policy from API and cache it
+     */
+    private fetchPolicy;
+    /**
+     * Fetch policy from API without caching
+     * Used internally for both direct fetches and background refreshes
+     */
+    private fetchPolicyFromApi;
+    /**
+     * Cache a policy
+     */
+    private cachePolicy;
+    /**
+     * Check if cached entry is expired
+     */
+    private isExpired;
+    /**
+     * Check if cache entry should be refreshed
+     */
+    private shouldRefresh;
+    /**
+     * Refresh policy in background
+     */
+    private refreshInBackground;
+    /**
+     * Get default policy for a project
+     */
+    private getDefaultPolicy;
+}
+/**
+ * Policy load error
+ */
+declare class PolicyLoadError extends Error {
+    readonly code: 'INVALID_API_KEY' | 'API_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT';
+    constructor(message: string, code: 'INVALID_API_KEY' | 'API_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT');
+}
+/**
+ * Create a policy loader with default configuration
+ */
+declare function createPolicyLoader(config?: PolicyLoaderConfig): PolicyLoader;
+
+/**
+ * Rules-Based Fallback Detector
+ *
+ * JavaScript fallback detector that uses merged-rules.json when WASM is unavailable.
+ * This provides consistent detection using the same rules as WASM, just implemented in JS.
+ */
+
+/**
+ * Rules-Based Fallback Detector
+ *
+ * Uses the same merged-rules.json as the WASM engine to provide
+ * consistent detection when WASM is not available.
+ */
+declare class RulesDetector implements IDetector {
+    private rules;
+    private ready;
+    /**
+     * Analyze a request and detect if it's from an agent
+     */
+    detect(input: IDetectionInput): Promise<IDetectionResult>;
+    /**
+     * Check if the detector is ready
+     */
+    isReady(): boolean;
+    /**
+     * Ensure the detector is initialized
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Get detector version
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Normalize headers to lowercase keys
+     */
+    private normalizeHeaders;
+    /**
+     * Match user agent against rules
+     */
+    private matchUserAgent;
+    /**
+     * Match headers against suspicious header rules
+     */
+    private matchHeaders;
+    /**
+     * Check if signature headers are present
+     */
+    private hasSignatureHeaders;
+    /**
+     * Get human-readable agent name from rule key
+     */
+    private getAgentName;
+    /**
+     * Infer agent type from name
+     */
+    private inferAgentType;
+    /**
+     * Determine detection class
+     */
+    private determineDetectionClass;
+}
+/**
+ * Create a rules-based fallback detector
+ */
+declare function createRulesDetector(): RulesDetector;
+
 /**
  * Create a detector with automatic runtime selection
  *
@@ -122,4 +650,4 @@ declare function createEdgeDetector(wasmModule: WebAssembly.Module, options?: ID
  */
 declare function createFallbackDetector(): IDetector;
 
-export { IDetector, IDetectorOptions, IWasmBindings, IWasmLoader, StaticWasmLoader, createDetector, createEdgeDetector, createFallbackDetector, createStaticLoader };
+export { CONFIDENCE, type DetectionClass, DynamicWasmLoader, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPathRule, type IPolicyLoader, type IWasmBindings, type IWasmLoader, PolicyLoadError, PolicyLoader, type PolicyLoaderConfig, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createDetector, createDynamicLoader, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader };

package/dist/index.js

@@ -2,8 +2,6 @@
 
 var checkpointShared = require('@kya-os/checkpoint-shared');
 
-// ../../node_modules/.pnpm/tsup@8.5.0_@swc+core@1.15.32_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
-
 // src/types.ts
 var CONFIDENCE = {
   /** Minimum confidence for isAgent=true */
@@ -1009,24 +1007,6 @@ async function findWasmModule() {
   try {
     const fs = await import('fs/promises');
     const nodePath = await import('path');
-    let moduleDir = null;
-    try {
-      const importMetaUrl = eval('typeof import.meta !== "undefined" && import.meta.url');
-      if (importMetaUrl) {
-        const url = await import('url');
-        moduleDir = nodePath.dirname(url.fileURLToPath(importMetaUrl));
-      }
-    } catch {
-    }
-    if (!moduleDir) {
-      try {
-        const cjsDirname = eval('typeof __dirname !== "undefined" && __dirname');
-        if (cjsDirname) {
-          moduleDir = cjsDirname;
-        }
-      } catch {
-      }
-    }
     const fsWasmPaths = [
       nodePath.resolve(
         process.cwd(),
@@ -1037,12 +1017,6 @@ async function findWasmModule() {
         "node_modules/@kya-os/checkpoint/dist/wasm/agentshield_wasm_bg.wasm"
       )
     ];
-    if (moduleDir) {
-      fsWasmPaths.unshift(
-        nodePath.resolve(moduleDir, "../wasm/agentshield_wasm_bg.wasm"),
-        nodePath.resolve(moduleDir, "../../wasm/agentshield_wasm_bg.wasm")
-      );
-    }
     for (const wasmPath of fsWasmPaths) {
       try {
         const buffer = await fs.readFile(wasmPath);
@@ -1099,8 +1073,8 @@ var DynamicWasmLoader = class {
     try {
       let wasmBuffer;
       if (this.wasmPath) {
-        const fs2 = await import('fs/promises');
-        const buffer = await fs2.readFile(this.wasmPath);
+        const fs = await import('fs/promises');
+        const buffer = await fs.readFile(this.wasmPath);
         wasmBuffer = new ArrayBuffer(buffer.byteLength);
         new Uint8Array(wasmBuffer).set(buffer);
       } else {

package/dist/index.mjs

@@ -1,8 +1,5 @@
-import { createRequire } from 'module';
 import { RuleLoader } from '@kya-os/checkpoint-shared';
 
-createRequire(import.meta.url);
-
 // src/types.ts
 var CONFIDENCE = {
   /** Minimum confidence for isAgent=true */
@@ -1008,24 +1005,6 @@ async function findWasmModule() {
   try {
     const fs = await import('fs/promises');
     const nodePath = await import('path');
-    let moduleDir = null;
-    try {
-      const importMetaUrl = eval('typeof import.meta !== "undefined" && import.meta.url');
-      if (importMetaUrl) {
-        const url = await import('url');
-        moduleDir = nodePath.dirname(url.fileURLToPath(importMetaUrl));
-      }
-    } catch {
-    }
-    if (!moduleDir) {
-      try {
-        const cjsDirname = eval('typeof __dirname !== "undefined" && __dirname');
-        if (cjsDirname) {
-          moduleDir = cjsDirname;
-        }
-      } catch {
-      }
-    }
     const fsWasmPaths = [
       nodePath.resolve(
         process.cwd(),
@@ -1036,12 +1015,6 @@ async function findWasmModule() {
         "node_modules/@kya-os/checkpoint/dist/wasm/agentshield_wasm_bg.wasm"
       )
     ];
-    if (moduleDir) {
-      fsWasmPaths.unshift(
-        nodePath.resolve(moduleDir, "../wasm/agentshield_wasm_bg.wasm"),
-        nodePath.resolve(moduleDir, "../../wasm/agentshield_wasm_bg.wasm")
-      );
-    }
     for (const wasmPath of fsWasmPaths) {
       try {
         const buffer = await fs.readFile(wasmPath);
@@ -1098,8 +1071,8 @@ var DynamicWasmLoader = class {
     try {
       let wasmBuffer;
       if (this.wasmPath) {
-        const fs2 = await import('fs/promises');
-        const buffer = await fs2.readFile(this.wasmPath);
+        const fs = await import('fs/promises');
+        const buffer = await fs.readFile(this.wasmPath);
         wasmBuffer = new ArrayBuffer(buffer.byteLength);
         new Uint8Array(wasmBuffer).set(buffer);
       } else {