@kya-os/checkpoint-wasm-runtime 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @kya-os/checkpoint-wasm-runtime
 
+## 1.1.3 — 2026-05-17
+
+**Critical runtime fix for Express on Vercel.** 1.1.2 still failed at
+deploy time on `@vercel/node`-hosted Express functions with:
+
+```
+Error: Dynamic require of "fs" is not supported
+  at .../dist/orchestrator-node.mjs:14:9
+  at wasm/kya-os-engine/kya_os_engine.js (...:454:21)
+```
+
+### Root cause
+
+The wasm-bindgen `--target nodejs` glue contains literal
+`require('fs').readFileSync(...)` to load the .wasm artifact. esbuild
+rewrites that to its `__require('fs')` helper. The helper checks
+`typeof require !== "undefined"` — in a pure ESM context (.mjs at
+runtime) there is no global `require`, so the helper falls through
+to its `throw Error('Dynamic require of "X" is not supported')`.
+
+`shims: true` injects `__dirname` / `__filename` shims but does **not**
+inject a `require` shim. The two are separate concerns in tsup.
+
+### Fix
+
+Format-aware tsup `banner` injects
+`const require = createRequire(import.meta.url);` at the top of every
+ESM (.mjs) Node-target bundle. esbuild's `__require` helper then
+finds `require` in scope and uses it for the .wasm load. CJS bundles
+are unchanged (they already have a real `require` global). Edge
+bundles are unchanged (separate tsup config, no banner — Edge runtimes
+do not support `node:module`).
+
+### Why the previous "pivot to Express" path didn't escape this
+
+The architect's earlier verdict (close [#2616](https://github.com/Know-That-Ai/agent-shield/pull/2616),
+pivot bench to Express) was made under the assumption that Express's
+direct Node import flow would bypass the bundler-interop layers that
+broke Next.js Turbopack. Empirically, `@vercel/node` compiles the
+function entry into a CJS→ESM hybrid that loads
+`dist/orchestrator-node.mjs` through `loadESMFromCJS` — which executes
+the .mjs in pure ESM context. Same require-less environment, same
+failure. Express was not an escape.
+
+### Followup
+
+[SDK-Next.js-Integration-Audit-1 (#2618)](https://github.com/Know-That-Ai/agent-shield/issues/2618)
+Option B (wasm-bindgen `--target bundler`) remains the proper long-term
+fix — it generates wasm-bindgen glue that does not require runtime CJS
+globals. Until that lands, the createRequire banner is the minimal
+defense for all Node-host runtimes.
+
+### Surfaced by
+
+Bench-Before-After-1 §3.8 — `bench-new-express` deployment on Vercel
+returned `FUNCTION_INVOCATION_FAILED` with the stack trace above. The
+stack proved the failure persists past the Express pivot, requiring
+the wasm-runtime fix to be re-opened.
+
+---
+
+## 1.1.2 — 2026-05-17
+
+Fourth in the SDK-WASM-Bundler-Loader sequence. The 1.1.1 fix made
+`engineVerify` reference the real wasm binding, but Node's strict
+ESM loader at Vercel runtime still failed with:
+
+```
+ReferenceError: __dirname is not defined in ES module scope
+```
+
+The wasm-bindgen `--target nodejs` glue uses CJS-only globals
+(`__dirname`, `__require`) which don't exist in ESM scope. When
+tsup inlines that CJS code into the .mjs bundle, ESM execution
+breaks.
+
+### Fix
+
+`shims: true` in tsup config. Injects the standard polyfills at the
+top of every ESM output:
+
+```javascript
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+```
+
+Bundle proof:
+
+```
+var getFilename, getDirname, __dirname$1;
+getFilename = () => fileURLToPath(import.meta.url);
+__dirname$1 = getDirname();
+// ...
+var wasmPath = `${__dirname$1}/kya_os_engine_bg.wasm`;
+```
+
+### Edge bundle caveat
+
+`shims: true` applies to ALL ESM outputs, including the Edge entry.
+The Edge bundle now has `import 'path'` + `import 'url'` at the top.
+`path` is not available in Vercel Edge runtime — could be an issue
+for Edge consumers. Bench-new uses Node runtime so this doesn't
+affect the immediate measurement, but a follow-up should split the
+tsup build into per-runtime configs (Node-only entries get shims;
+Edge entries don't). Filing as SDK-WASM-Bundler-Loader-4.
+
+### Consumers
+
+No package.json changes needed in `@kya-os/checkpoint-{nextjs,express}` —
+both already use `workspace:^` to depend on `^1.1.0`, so fresh
+installs automatically pull 1.1.2 transitively. Bench-new needs
+a lockfile bump + redeploy.
+
+---
+
 ## 1.1.1 — 2026-05-17
 
 **Critical runtime fix.** 1.1.0 (and all prior versions back to 1.0.0)

package/dist/edge.d.mts

@@ -1,6 +1,533 @@
-import { I as IDetectorOptions, a as IDetector, d as IDetectionInput } from './rules-detector-DjbTJ1-Q.mjs';
-export { C as CONFIDENCE, D as DetectionClass, F as ForgeabilityRisk, b as ICustomerPolicy, c as IDetectedAgent, e as IDetectionResult, g as IPolicyLoader, i as IWasmLoader, j as PolicyLoader, R as RulesDetector, V as VerificationMethod, W as WasmDetector, l as createPolicyLoader, m as createRulesDetector } from './rules-detector-DjbTJ1-Q.mjs';
-export { S as StaticWasmLoader, c as createStaticLoader } from './static-loader-Ds4iNw7c.mjs';
+/**
+ * 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
+ *
+ * This loader is designed for environments that require static WASM imports,
+ * such as Vercel Edge Runtime and Cloudflare Workers.
+ *
+ * Usage:
+ * ```typescript
+ * // In your middleware.ts:
+ * import wasmModule from '@kya-os/checkpoint-wasm-runtime/wasm?module';
+ * import { StaticWasmLoader, WasmDetector } from '@kya-os/checkpoint-wasm-runtime/edge';
+ *
+ * const loader = new StaticWasmLoader(wasmModule);
+ * const detector = new WasmDetector(loader);
+ * ```
+ *
+ * The `?module` suffix tells bundlers (webpack, esbuild) to import the WASM
+ * as a pre-compiled WebAssembly.Module, which is required for Edge Runtime.
+ */
+
+/**
+ * Static WASM Loader
+ *
+ * For Edge Runtime environments that require pre-compiled WASM modules.
+ * The consumer must provide the WASM module via a static import with `?module` suffix.
+ *
+ * This loader uses the wasm-bindgen generated JS glue code to properly
+ * initialize the WASM module with all required imports.
+ */
+declare class StaticWasmLoader implements IWasmLoader {
+    private readonly wasmModule;
+    private bindings;
+    private loadPromise;
+    private wasmExports;
+    /**
+     * Create a new StaticWasmLoader
+     * @param wasmModule - Pre-compiled WebAssembly.Module from static import
+     */
+    constructor(wasmModule: WebAssembly.Module);
+    /**
+     * Load and instantiate the WASM module
+     */
+    load(): Promise<void>;
+    /**
+     * Internal load implementation using wasm-bindgen initSync
+     */
+    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 bindings wrapper using wasm-bindgen exports
+     */
+    private createBindings;
+}
+/**
+ * Create a static loader with validation
+ */
+declare function createStaticLoader(wasmModule: WebAssembly.Module): StaticWasmLoader;
+
+/**
+ * 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;
+}
+/**
+ * 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 for Edge Runtime with static WASM import
@@ -19,4 +546,4 @@ declare function createFallbackDetector(): IDetector;
  */
 declare function extractInputFromRequest(request: Request): IDetectionInput;
 
-export { IDetectionInput, IDetector, IDetectorOptions, createEdgeDetector, createFallbackDetector, extractInputFromRequest };
+export { CONFIDENCE, type DetectionClass, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPolicyLoader, type IWasmLoader, PolicyLoader, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader, extractInputFromRequest };