@kya-os/checkpoint-express 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+import { Request, RequestHandler, Response, NextFunction } from 'express';
+import { DidResolverAdapter, StatusListCacheAdapter, ReputationOracleAdapter, PolicyEvaluatorAdapter } from '@kya-os/checkpoint-wasm-runtime/adapters';
+import { EnforcementMode, VerifyResult } from '@kya-os/checkpoint-wasm-runtime/engine';
+import { DetectionResult, AgentShieldConfig } from '@kya-os/checkpoint-shared';
+export { DEFAULT_POLICY, ENFORCEMENT_ACTIONS, PolicyConfig, PolicyEvaluationContext, PolicyEvaluationResult, createEvaluationContext, evaluatePolicy } from '@kya-os/checkpoint-shared';
+export { PolicyMiddlewareConfig, applyPolicy, createContextFromDetection, evaluatePolicyForDetection, getPolicy, handlePolicyDecision, sendBlockedResponse, sendRedirectResponse } from './policy.js';
+
+/**
+ * E.1 + E.3 — Express middleware entry: `withCheckpoint(config)`.
+ *
+ * The host wrapper that composes Phase B adapters + Phase C
+ * `verifyRequest` (sync engine) + Phase D translate/adapt into the
+ * `withCheckpoint(config)` factory. Mounted under Node-runtime Express
+ * servers via `app.use(withCheckpoint({...}))`.
+ *
+ * Phase E only ships the Node-runtime entry — Express doesn't have an
+ * Edge variant (Express runs on Node only). Phase D's edge orchestrator
+ * (`verifyRequestEdge`) exists for the Next.js + Vercel Edge use case;
+ * Express imports the sync `verifyRequest` directly.
+ *
+ * **Public API contract (architect § 4.1):**
+ *
+ *   - `withCheckpoint(config)` — factory returning Express middleware.
+ *   - `CheckpointConfig` — the config shape; new fields are additive.
+ *
+ * Internal implementation gutted, external contract held. The legacy
+ * `agentShield()` / `createAgentShieldMiddleware()` exports remain in
+ * the package during the deprecation window (see E.4) — but as
+ * throw-stubs with migration messages, not working entry points.
+ */
+
+/**
+ * Configuration for `withCheckpoint`.
+ *
+ * Shape mirrors `checkpoint-nextjs`'s `CheckpointConfig` so customers
+ * running both runtimes have a single mental model.
+ */
+interface CheckpointConfig {
+    /**
+     * Tenant identifier — typically the customer's dashboard hostname
+     * (e.g. `acme.checkpoint.example`). The PolicyEvaluator uses this
+     * to look up tenant policy from the dashboard.
+     */
+    tenantHost: string;
+    /**
+     * `'enforce'` (default) blocks; `'observe'` passes everything
+     * through with `X-Checkpoint-Would-Have-Been` headers. Per Phase 0.2.
+     */
+    enforcementMode?: EnforcementMode;
+    /**
+     * Argus reputation oracle base URL. Omit to use the trust-by-default
+     * baseline (reputation defaults to 1.0; orchestrator logs a one-shot
+     * warning at first request).
+     */
+    argusUrl?: string;
+    /**
+     * Dashboard base URL for the PolicyEvaluator to fetch tenant policy
+     * from. Omit to use the open-by-default tenant policy.
+     */
+    dashboardUrl?: string;
+    /**
+     * Returned to the PolicyEvaluator for anonymous requests (no agent
+     * DID). Default 1.0 (trust-by-default).
+     */
+    reputationBaseline?: number;
+    /**
+     * Pre-built adapter instances. Production deployments use the
+     * factory-built defaults from `@kya-os/checkpoint-wasm-runtime/
+     * adapters`; tests use stubs. The factory composes any provided
+     * overrides over defaults — partial overrides are supported.
+     */
+    adapters?: Partial<{
+        didResolver: DidResolverAdapter;
+        statusListCache: StatusListCacheAdapter;
+        reputationOracle: ReputationOracleAdapter;
+        policyEvaluator: PolicyEvaluatorAdapter;
+    }>;
+    /**
+     * Optional callback for the post-verdict path — fires after every
+     * verification, regardless of permit/block, with the full
+     * `VerifyResult`. Use for logging, dashboards, telemetry. Errors
+     * thrown here are swallowed so user code can't break the middleware
+     * response.
+     */
+    onResult?: (result: VerifyResult, req: Request) => void | Promise<void>;
+}
+/**
+ * Build the Checkpoint middleware. Returns an Express `RequestHandler`
+ * suitable for `app.use(withCheckpoint({...}))`.
+ *
+ * Every verification decision flows through the Rust `kya-os-engine`
+ * via WASM. The TS layer translates request shape, calls
+ * `verifyRequest`, and applies the verdict to `res` (or calls `next()`
+ * for pass-through). No verification logic lives in this file.
+ */
+declare function withCheckpoint(config: CheckpointConfig): RequestHandler;
+
+/**
+ * Express-specific type definitions
+ */
+
+/**
+ * Express middleware configuration
+ */
+interface ExpressMiddlewareConfig extends AgentShieldConfig {
+    /**
+     * API key for loading customer policies from AgentShield dashboard
+     * When provided, enables policy enforcement (deny lists, allow lists, thresholds)
+     */
+    apiKey?: string;
+    /**
+     * Custom URL for the policy API
+     * @default 'https://api.agentshield.io'
+     */
+    policyApiUrl?: string;
+    /**
+     * Action to take when an agent is detected
+     */
+    onAgentDetected?: 'block' | 'allow' | 'log';
+    /**
+     * Custom handler for agent detection
+     */
+    onDetection?: (req: Request, res: Response, result: DetectionResult) => void | Promise<void>;
+    /**
+     * Skip agent detection for certain routes
+     */
+    skipPaths?: string[] | RegExp[];
+    /**
+     * Custom response when blocking agents
+     */
+    blockedResponse?: {
+        status: number;
+        message: string;
+        headers?: Record<string, string>;
+    };
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Extended Express Request with AgentShield data
+ */
+interface AgentShieldRequest extends Request {
+    agentShield?: {
+        result: DetectionResult;
+        skipped: boolean;
+        session?: {
+            id: string;
+            agent: string;
+            confidence: number;
+            detectedAt: number;
+            expires: number;
+        };
+    };
+}
+/**
+ * Middleware function type
+ */
+type AgentShieldMiddleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+
+/**
+ * Legacy Express middleware — Phase E throw-stub.
+ *
+ * The local-detection chain (pattern matching → JS-side policy
+ * evaluation) was retired in Phase E. Every legacy
+ * call site now throws with a migration message pointing at
+ * `withCheckpoint()` from `@kya-os/checkpoint-express`.
+ *
+ * Per Dylan's architect call 2026-05-16: local-detection chain entry
+ * points become throw-stubs after the engine-backed replacement ships.
+ * The export names survive so customers don't `ImportError` on upgrade
+ * — calls throw at runtime with a clear migration path. SaaS-API
+ * entry points (`AgentShieldClient`, `client.enforce()`) get a
+ * different treatment (rename + preserve); Express had no such surface
+ * (audit confirmed 2026-05-16 in the Phase E kickoff brief § "addendum
+ * 2026-05-16").
+ *
+ * @deprecated Use `withCheckpoint` from `@kya-os/checkpoint-express`.
+ */
+
+/**
+ * @deprecated Throws with a migration message. Use `withCheckpoint` instead.
+ */
+declare function createAgentShieldMiddleware(_config?: Partial<ExpressMiddlewareConfig>): AgentShieldMiddleware;
+/**
+ * @deprecated Throws with a migration message. Use `withCheckpoint` instead.
+ */
+declare function agentShield(_config?: Partial<ExpressMiddlewareConfig>): AgentShieldMiddleware;
+
+/**
+ * Session tracking helper for Express
+ * Provides graceful degradation of session tracking for non-Next.js environments
+ */
+
+interface SessionData {
+    id: string;
+    agent: string;
+    confidence: number;
+    detectedAt: number;
+    expires: number;
+}
+/**
+ * Express-compatible session tracker
+ * Uses cookies when available, falls back to headers
+ */
+declare class ExpressSessionTracker {
+    private readonly cookieName;
+    /**
+     * Check for existing session from Express request
+     */
+    check(req: Request): SessionData | null;
+    /**
+     * Track a new session in Express response
+     */
+    track(res: Response, result: DetectionResult): void;
+    /**
+     * Generate a simple ID without crypto dependency
+     */
+    private generateId;
+}
+/**
+ * Helper to add session tracking to Express middleware
+ */
+declare function withSessionTracking(middleware: (req: Request, res: Response, next: NextFunction) => void | Promise<void>, config?: {
+    enabled?: boolean;
+}): (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+
+/**
+ * Storage adapter types for Express
+ * Matches the Next.js storage adapter interface for consistency
+ */
+/**
+ * Agent detection event
+ */
+interface AgentDetectionEvent {
+    eventId: string;
+    sessionId: string;
+    timestamp: string;
+    agentType: string;
+    agentName: string;
+    confidence: number;
+    path: string;
+    userAgent?: string;
+    ipAddress?: string;
+    method: string;
+    detectionReasons: string[];
+    verificationMethod: string;
+    detectionDetails?: {
+        patterns?: Record<string, unknown>;
+        behaviors?: Record<string, unknown>;
+        fingerprintMatches?: string[];
+    };
+}
+/**
+ * Agent session data
+ */
+interface AgentSession {
+    sessionId: string;
+    ipAddress?: string;
+    userAgent?: string;
+    agentType: string;
+    agentName: string;
+    firstSeen: string;
+    lastSeen: string;
+    eventCount: number;
+    paths: string[];
+    averageConfidence: number;
+    verificationMethods: string[];
+}
+/**
+ * Storage adapter interface
+ */
+interface StorageAdapter {
+    /**
+     * Store an agent detection event
+     */
+    storeEvent(event: AgentDetectionEvent): Promise<void>;
+    /**
+     * Store or update a session
+     */
+    storeSession(session: AgentSession): Promise<void>;
+    /**
+     * Get events for a session
+     */
+    getEvents(sessionId: string, limit?: number): Promise<AgentDetectionEvent[]>;
+    /**
+     * Get session by ID
+     */
+    getSession(sessionId: string): Promise<AgentSession | null>;
+    /**
+     * Get recent events
+     */
+    getRecentEvents(limit?: number): Promise<AgentDetectionEvent[]>;
+    /**
+     * Get active sessions
+     */
+    getActiveSessions(limit?: number): Promise<AgentSession[]>;
+    /**
+     * Clear old data
+     */
+    cleanup?(before: Date): Promise<void>;
+}
+/**
+ * Storage configuration
+ */
+interface StorageConfig {
+    type: 'memory' | 'redis' | 'custom';
+    ttl?: number;
+    redis?: {
+        url: string;
+        token: string;
+    };
+    custom?: StorageAdapter;
+}
+
+/**
+ * Legacy enhanced middleware — Phase E throw-stub.
+ *
+ * `createEnhancedAgentShieldMiddleware` previously bundled local
+ * detection + session tracking + Redis/Memory event storage in one
+ * factory. Phase E retires the local detection per Dylan's architect
+ * call 2026-05-16 (local-detection chain → throw-stub) but preserves
+ * the session/Redis observability surface as **composable primitives**:
+ *
+ *   - Storage adapters (`MemoryStorageAdapter`, `RedisStorageAdapter`,
+ *     `createStorageAdapter`) remain exported from `./storage`.
+ *   - Session-cookie helpers remain exported from `./session-helper`.
+ *
+ * Customers who used `createEnhancedAgentShieldMiddleware` for the
+ * combined behaviour migrate to `withCheckpoint` + an `onResult`
+ * callback that calls into the storage adapter:
+ *
+ *   import { withCheckpoint } from '@kya-os/checkpoint-express';
+ *   import { createStorageAdapter } from '@kya-os/checkpoint-express';
+ *
+ *   const storage = createStorageAdapter({ type: 'redis', ... });
+ *
+ *   app.use(withCheckpoint({
+ *     tenantHost: 'your.tenant.example',
+ *     onResult: async (result, req) => {
+ *       await storage.recordEvent({
+ *         verdict: result.decision.kind,
+ *         agentDid: result.agentDid,
+ *         ts: Date.now(),
+ *         // ... whatever the customer's event shape is.
+ *       });
+ *     },
+ *   }));
+ *
+ * This is the "session/Redis observability" bucket in Dylan's
+ * three-bucket decision matrix (Phase E kickoff brief § addendum 2):
+ * preserve, refactor to consume engine `Decision` instead of legacy
+ * `DetectionResult`. The refactor is customer-side — they wire the
+ * adapter into `onResult` themselves. The engine doesn't need to know.
+ *
+ * @deprecated Throws with a migration message. Compose `withCheckpoint`
+ *   with the storage adapter directly (example above).
+ */
+
+/**
+ * Enhanced middleware configuration (legacy). Kept as a type export so
+ * customers' config types keep type-checking through the migration
+ * window; the factory function below throws at runtime.
+ */
+interface EnhancedMiddlewareConfig {
+    /** Storage configuration. */
+    storage?: StorageConfig;
+    /** Session tracking configuration. */
+    sessionTracking?: {
+        enabled?: boolean;
+        ttl?: number;
+    };
+    /** Paths to skip detection. */
+    skipPaths?: string[];
+    /** Action when agent detected. */
+    onAgentDetected?: 'block' | 'log' | 'allow';
+    /** Custom handler for agent detection. */
+    onDetection?: (result: DetectionResult, req: Request) => void | Promise<void>;
+    /** Confidence threshold. */
+    confidenceThreshold?: number;
+    /** Response when blocking. */
+    blockedResponse?: {
+        status?: number;
+        message?: string;
+    };
+    /** Enable WASM (if available). */
+    enableWasm?: boolean;
+}
+/**
+ * @deprecated Throws with a migration message. Compose `withCheckpoint`
+ *   with `createStorageAdapter` via the `onResult` callback.
+ */
+declare function createEnhancedAgentShieldMiddleware(_config?: EnhancedMiddlewareConfig): void;
+
+/**
+ * In-memory storage adapter for Express
+ * Useful for development and testing
+ */
+
+declare class MemoryStorageAdapter implements StorageAdapter {
+    private events;
+    private sessions;
+    private eventTimeline;
+    private maxEventsPerSession;
+    private maxTimelineEvents;
+    storeEvent(event: AgentDetectionEvent): Promise<void>;
+    storeSession(session: AgentSession): Promise<void>;
+    getEvents(sessionId: string, limit?: number): Promise<AgentDetectionEvent[]>;
+    getSession(sessionId: string): Promise<AgentSession | null>;
+    getRecentEvents(limit?: number): Promise<AgentDetectionEvent[]>;
+    getActiveSessions(limit?: number): Promise<AgentSession[]>;
+    cleanup(before: Date): Promise<void>;
+}
+
+/**
+ * Redis storage adapter for Express
+ * Provides persistent storage for production environments
+ */
+
+interface RedisClient {
+    set(key: string, value: string, options?: {
+        ex?: number;
+    }): Promise<string>;
+    get(key: string): Promise<string | null>;
+    zadd(key: string, ...args: Array<number | string>): Promise<number>;
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    zrevrange(key: string, start: number, stop: number): Promise<string[]>;
+    expire(key: string, seconds: number): Promise<number>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+}
+declare class RedisStorageAdapter implements StorageAdapter {
+    private redis;
+    private prefix;
+    private ttl;
+    constructor(redis: RedisClient, ttl?: number);
+    private getKey;
+    storeEvent(event: AgentDetectionEvent): Promise<void>;
+    storeSession(session: AgentSession): Promise<void>;
+    getEvents(sessionId: string, limit?: number): Promise<AgentDetectionEvent[]>;
+    getSession(sessionId: string): Promise<AgentSession | null>;
+    getRecentEvents(limit?: number): Promise<AgentDetectionEvent[]>;
+    getActiveSessions(limit?: number): Promise<AgentSession[]>;
+    cleanup(before: Date): Promise<void>;
+}
+
+/**
+ * Storage adapter exports and factory for Express
+ */
+
+/**
+ * Create a storage adapter based on configuration
+ */
+declare function createStorageAdapter(config?: StorageConfig): Promise<StorageAdapter>;
+
+/**
+ * @fileoverview Checkpoint Express Middleware — engine-backed AI agent
+ * detection and MCP-I verification.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Library version
+ */
+declare const VERSION = "1.0.0";
+
+export { type AgentDetectionEvent, type AgentSession, type AgentShieldMiddleware, type AgentShieldRequest, type CheckpointConfig, type EnhancedMiddlewareConfig, type ExpressMiddlewareConfig, ExpressSessionTracker, MemoryStorageAdapter, RedisStorageAdapter, type SessionData, type StorageAdapter, type StorageConfig, VERSION, agentShield, createAgentShieldMiddleware, createEnhancedAgentShieldMiddleware, createStorageAdapter, withCheckpoint, withSessionTracking };