@kya-os/agentshield-express/dist/index.d.mts

Express.js middleware for AgentShield AI agent detection

import { Request, Response, NextFunction } from 'express';
import { AgentShieldConfig, DetectionResult } from '@kya-os/agentshield';

/**
 * Express-specific type definitions
 */

/**
 * Express middleware configuration
 */
interface ExpressMiddlewareConfig extends AgentShieldConfig {
    /**
     * 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>;
    };
}
/**
 * Extended Express Request with AgentShield data
 */
interface AgentShieldRequest extends Request {
    agentShield?: {
        result: DetectionResult;
        skipped: boolean;
    };
}
/**
 * Middleware function type
 */
type AgentShieldMiddleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;

/**
 * Express middleware for AgentShield
 */

/**
 * Create AgentShield middleware for Express
 */
declare function createAgentShieldMiddleware(config?: Partial<ExpressMiddlewareConfig>): AgentShieldMiddleware;
/**
 * Convenience function for basic setup
 */
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: Function, config?: {
    enabled?: boolean;
}): Function;

/**
 * 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?: any;
        behaviors?: any;
        fingerprintMatches?: any;
    };
}
/**
 * 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;
}

/**
 * Enhanced Express middleware with all features built-in
 */

/**
 * Enhanced configuration with built-in features
 */
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;
}
/**
 * Create enhanced AgentShield middleware with all features
 */
declare function createEnhancedAgentShieldMiddleware(config?: EnhancedMiddlewareConfig): (req: Request, res: Response, next: NextFunction) => Promise<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: any, options?: {
        ex?: number;
    }): Promise<string>;
    get(key: string): Promise<any>;
    zadd(key: string, ...args: any[]): 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 AgentShield Express Middleware
 * @version 0.1.0
 * @license MIT OR Apache-2.0
 */

/**
 * Library version
 */
declare const VERSION = "0.1.0";

export { type AgentDetectionEvent, type AgentSession, type AgentShieldMiddleware, type AgentShieldRequest, type EnhancedMiddlewareConfig, type ExpressMiddlewareConfig, ExpressSessionTracker, MemoryStorageAdapter, RedisStorageAdapter, type SessionData, type StorageAdapter, type StorageConfig, VERSION, agentShield, createAgentShieldMiddleware, createEnhancedAgentShieldMiddleware, createStorageAdapter, withSessionTracking };