@samimcodes/ai-shield 0.0.0-stage → 0.1.0

package/dist/middleware-DNRM5IlO.d.cts

@@ -0,0 +1,657 @@
+import { Router, RequestHandler } from 'express';
+import { IncomingHttpHeaders } from 'node:http';
+
+/**
+ * @file src/types/index.ts
+ * @description Canonical type definitions for the ai-shield middleware system.
+ *
+ * All shared interfaces, enums, and type aliases live here so every module
+ * can import from a single source of truth without circular dependencies.
+ */
+/**
+ * Broad category assigned to an incoming request after fingerprinting.
+ *
+ * - `AI_CRAWLER`    — Known LLM training / inference crawlers (GPTBot, Claude-Web…)
+ * - `SCRAPER`       — General-purpose commercial scrapers (ByteSpider, PetalBot…)
+ * - `SCRAPING_LIB`  — Headless browsers & HTTP scraping libraries (Puppeteer, Scrapy…)
+ * - `GOOD_BOT`      — Verified search-engine crawlers that MUST NOT be blocked
+ * - `HUMAN`         — Regular browser traffic or unrecognised agents
+ */
+declare enum BotCategory {
+    AI_CRAWLER = "AI_CRAWLER",
+    SCRAPER = "SCRAPER",
+    SCRAPING_LIB = "SCRAPING_LIB",
+    GOOD_BOT = "GOOD_BOT",
+    HUMAN = "HUMAN"
+}
+/**
+ * Confidence level of the bot classification decision.
+ * Used to gate aggressive poisoning strategies.
+ */
+declare enum Confidence {
+    HIGH = "HIGH",
+    MEDIUM = "MEDIUM",
+    LOW = "LOW"
+}
+/**
+ * Individual evidence signals collected during fingerprinting.
+ * Multiple signals are fused into a final `DetectionResult`.
+ */
+type DetectionSignal = 'UA_PATTERN_MATCH' | 'MISSING_ACCEPT_LANGUAGE' | 'MISSING_ACCEPT' | 'AUTOMATION_HEADER' | 'SUSPICIOUS_UA' | 'HONEYPOT_TRIGGERED' | 'EMPTY_UA';
+/** Rich result produced by the detector for every incoming request. */
+interface DetectionResult {
+    /** Broad category of the visitor. */
+    category: BotCategory;
+    /** How confident we are in the classification. */
+    confidence: Confidence;
+    /** Human-readable label, e.g. "GPTBot", "Googlebot", "Unknown". */
+    label: string;
+    /**
+     * The specific fingerprint rule that triggered the UA match,
+     * or `null` for heuristic-only or unmatched traffic.
+     */
+    matchedRule: string | null;
+    /** Raw User-Agent string extracted from the request headers. */
+    userAgent: string;
+    /** All evidence signals that contributed to this classification. */
+    signals: DetectionSignal[];
+    /**
+     * Numeric score in [0, 100]. Higher = more certain bot.
+     * Useful for threshold-based gating (e.g., only poison score ≥ 60).
+     */
+    score: number;
+}
+/**
+ * A single fingerprint entry in the bot registry.
+ * Rules are evaluated in declaration order; first match wins.
+ */
+interface BotFingerprint {
+    /** Unique, stable identifier for this rule (used in logs & metrics). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Category this fingerprint maps to. */
+    category: BotCategory;
+    /** Confidence assigned when this rule fires. */
+    confidence: Confidence;
+    /** RegExp tested against the User-Agent header. */
+    uaPattern: RegExp;
+    /** Optional additional description / reference URL. */
+    description?: string | undefined;
+}
+/**
+ * Weights applied to each detection signal when computing the bot score.
+ * Override via `AiShieldOptions.signalWeights` to tune sensitivity.
+ */
+interface SignalWeights {
+    UA_PATTERN_MATCH: number;
+    MISSING_ACCEPT_LANGUAGE: number;
+    MISSING_ACCEPT: number;
+    AUTOMATION_HEADER: number;
+    SUSPICIOUS_UA: number;
+    HONEYPOT_TRIGGERED: number;
+    EMPTY_UA: number;
+}
+/** Default signal weights. Sum is deliberately > 100 to allow multi-signal certainty. */
+declare const DEFAULT_SIGNAL_WEIGHTS: Readonly<SignalWeights>;
+/**
+ * The type of synthetic content that the poison engine will emit.
+ *
+ * - `HTML`   — Full HTML page with plausible but misleading prose.
+ * - `JSON`   — Structured JSON payload that looks like an API response.
+ * - `TEXT`   — Plain-text document.
+ * - `SITEMAP`— Fake XML sitemap full of dead-end URLs.
+ */
+type PoisonContentType = 'HTML' | 'JSON' | 'TEXT' | 'SITEMAP';
+/** A single poisoned response payload ready to be sent to the client. */
+interface PoisonPayload {
+    /** HTTP Content-Type header value. */
+    contentType: string;
+    /** Response body string. */
+    body: string;
+    /** HTTP status code — always 200 to avoid triggering bot retry logic. */
+    statusCode: 200;
+}
+/** Configuration for a single honeypot trap route. */
+interface HoneypotRoute {
+    /** Express-compatible path string, e.g. `/wp-login.php`. */
+    path: string;
+    /** Label written to logs when this trap is triggered. */
+    label: string;
+}
+/**
+ * Entry stored in the in-memory honeypot IP cache.
+ */
+interface TrapCacheEntry {
+    /** Unix timestamp (ms) when this IP first triggered a trap. */
+    firstSeenAt: number;
+    /** Unix timestamp (ms) after which this entry expires. `null` = permanent. */
+    expiresAt: number | null;
+    /** How many times this IP has hit trap routes since first detection. */
+    hitCount: number;
+    /** Label of the FIRST trap path that was triggered. */
+    triggeringTrap: string;
+}
+/**
+ * Top-level options accepted by `createAiShield()`.
+ *
+ * All fields are optional; sensible production defaults are applied
+ * when a field is omitted.
+ */
+interface AiShieldOptions {
+    /**
+     * Additional User-Agent fingerprints to append to the built-in registry.
+     * Useful for blocking proprietary scrapers not yet in the default list.
+     */
+    customFingerprints?: BotFingerprint[] | undefined;
+    /**
+     * Paths that should NEVER be intercepted, even if the requester
+     * is classified as an AI crawler (e.g. your own health-check endpoint).
+     * Supports exact strings only; no glob patterns.
+     */
+    excludePaths?: string[] | undefined;
+    /**
+     * Override the default poison-content strategy for AI crawlers.
+     * Defaults to `'HTML'`.
+     */
+    poisonContentType?: PoisonContentType | undefined;
+    /**
+     * When `true`, inject hidden `<a>` honeypot links into every HTML
+     * response served to AI bots, leading them deeper into the maze.
+     * Defaults to `true`.
+     */
+    injectHoneypotLinks?: boolean | undefined;
+    /**
+     * Custom list of honeypot trap paths to register on the Express router.
+     * Merged with (not replacing) the built-in trap set.
+     */
+    honeypotPaths?: HoneypotRoute[] | undefined;
+    /**
+     * Callback invoked whenever a bot is detected — handy for metrics /
+     * logging pipelines. Called asynchronously; errors are swallowed.
+     */
+    onBotDetected?: ((result: DetectionResult) => void) | undefined;
+    /**
+     * Minimum bot score [0–100] required before poison is served.
+     * Traffic below this threshold passes through even if some signals fire.
+     * Defaults to `50` (any heuristic combination that exceeds MEDIUM).
+     */
+    scoreThreshold?: number | undefined;
+    /**
+     * Override per-signal scoring weights. Merged with `DEFAULT_SIGNAL_WEIGHTS`.
+     */
+    signalWeights?: Partial<SignalWeights> | undefined;
+    /**
+     * TTL in milliseconds for honeypot IP cache entries.
+     * After expiry the IP is no longer considered flagged unless it hits
+     * another trap. Set to `null` for permanent flagging.
+     * Defaults to `24 * 60 * 60 * 1000` (24 hours).
+     */
+    honeypotTtlMs?: number | null | undefined;
+    /**
+     * Enable verbose debug logging to stdout.
+     * Should be `false` in production.
+     * Defaults to `false`.
+     */
+    debug?: boolean | undefined;
+    /**
+     * Optional API key to authenticate with the ai-shield telemetry service.
+     * When provided, activates asynchronous non-blocking event emissions.
+     */
+    apiKey?: string | undefined;
+    /**
+     * Target endpoint URL for telemetry event reporting.
+     * Defaults to 'https://telemetry.ai-shield.dev/v1/events'.
+     */
+    dashboardUrl?: string | undefined;
+}
+/** Telemetry event record emitted when bots/scrapers are trapped or poisoned. */
+interface TelemetryEvent {
+    /** Timestamp formatted as ISO-8601 string. */
+    timestamp: string;
+    /** Request path that triggered the defense. */
+    path: string;
+    /** Label/reason for the interception. */
+    reason: string;
+    /** Privacy-preserving SHA-256 hash of the client IP address. */
+    clientIpHash: string;
+    /** Client User-Agent string. */
+    userAgent: string;
+}
+/**
+ * Properties added to `express.Request` by the middleware so downstream
+ * handlers have access to the detection result without re-computing it.
+ */
+interface AiShieldRequestMeta {
+    detection: DetectionResult;
+    poisoned: boolean;
+}
+/** Configuration options alias for the aiShield middleware. */
+type ShieldOptions = AiShieldOptions;
+
+/**
+ * @file src/core/telemetry.ts
+ * @description Non-blocking batch telemetry emitter for ai-shield events.
+ *
+ * Requirements:
+ *   - Asynchronous and non-blocking (zero latency impact on HTTP request handling).
+ *   - Uses native Node.js global fetch.
+ *   - Flushes events in batches every 5 seconds OR immediately when queue hits 20 items.
+ *   - Fire-and-forget: errors are silently swallowed to preserve host application resilience.
+ */
+
+/**
+ * Computes a privacy-preserving SHA-256 hash of a client IP address.
+ */
+declare function hashClientIp(ip: string): string;
+interface TelemetryEmitterOptions {
+    apiKey: string;
+    dashboardUrl?: string | undefined;
+    flushIntervalMs?: number | undefined;
+    batchSize?: number | undefined;
+    fetchFn?: typeof fetch | undefined;
+}
+/**
+ * In-memory batched telemetry emitter.
+ */
+declare class TelemetryEmitter {
+    private readonly apiKey;
+    private readonly dashboardUrl;
+    private readonly flushIntervalMs;
+    private readonly batchSize;
+    private readonly fetchFn;
+    private buffer;
+    private flushTimer;
+    private isDestroyed;
+    constructor(options: TelemetryEmitterOptions);
+    /**
+     * Queue an event into the in-memory buffer.
+     * Flushes immediately if buffer capacity is reached.
+     */
+    emit(event: TelemetryEvent): void;
+    /**
+     * Drains the current buffer and sends events via HTTP POST.
+     */
+    flush(): Promise<void>;
+    /**
+     * Current number of buffered events pending transmission.
+     */
+    get queueLength(): number;
+    /**
+     * Starts background interval flusher.
+     */
+    private startTimer;
+    /**
+     * Stops timer and drains any remaining events.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * @file src/core/detector.ts
+ * @description Multi-signal bot fingerprinting engine.
+ *
+ * Classification pipeline (in execution order):
+ *
+ *   1. SEO WHITELIST — O(1) Set lookup against known good-bot UA tokens.
+ *      Matching immediately returns GOOD_BOT with no further evaluation.
+ *      This is the absolute safety gate: Googlebot is NEVER intercepted.
+ *
+ *   2. UA PATTERN MATCHING — Pre-compiled RegExp battery covering:
+ *        • AI / LLM training crawlers (GPTBot, Claude-Web, CCBot…)
+ *        • Commercial scraper bots (ByteSpider, PetalBot, SemrushBot…)
+ *        • Scraping libraries (Scrapy, python-requests, Playwright, Puppeteer, cURL…)
+ *
+ *   3. HEADER HEURISTICS — Browser header analysis:
+ *        • Missing Accept-Language (always present in real browsers)
+ *        • Missing Accept header
+ *        • Automation-specific headers (X-Playwright, X-Puppeteer, selenium-*)
+ *        • Blank / absent User-Agent
+ *
+ *   4. SCORE FUSION — Weighted sum of fired signals clamped to [0, 100].
+ *      Final BotCategory and Confidence are derived from the fused score.
+ *
+ * Performance guarantees:
+ *   - GOOD_BOT whitelist: O(1) — `Set.has()` on normalised UA token.
+ *   - UA pattern matching: O(n) worst-case where n = number of rules,
+ *     but rules short-circuit on first match so typical cost is O(1)
+ *     for known bots and O(n) only for humans (smallest n traversal).
+ *   - Heuristic header checks: O(1) — direct property lookups.
+ *   - Total p99 latency: < 2 ms on any modern V8 runtime.
+ */
+
+/**
+ * `BotDetector` evaluates an HTTP request using a multi-signal pipeline
+ * and returns a richly annotated `DetectionResult`.
+ *
+ * **Instantiate once** at application startup — the constructor pre-compiles
+ * and caches all regex patterns and data structures. The `detect()` method
+ * is pure (no mutation) and safe for concurrent calls.
+ *
+ * ```ts
+ * const detector = new BotDetector();
+ * const result = detector.detect(req.headers);
+ *
+ * if (result.score >= 60) {
+ *   // serve poison
+ * }
+ * ```
+ */
+declare class BotDetector {
+    private readonly fingerprints;
+    private readonly weights;
+    /**
+     * @param customFingerprints - Additional rules evaluated BEFORE the
+     *   built-in list, giving them higher priority.
+     * @param signalWeights - Override default per-signal scoring weights.
+     */
+    constructor(customFingerprints?: BotFingerprint[], signalWeights?: Partial<SignalWeights>);
+    /**
+     * Classify an incoming HTTP request.
+     *
+     * @param headers - Raw `IncomingHttpHeaders` from Express `req.headers`.
+     * @param ip      - Optional client IP address; checked against the
+     *                  honeypot cache if provided.
+     * @param isHoneypotFlagged - Set `true` if the IP was already flagged
+     *                  by the `HoneypotManager` before calling detect().
+     * @returns A fully populated `DetectionResult`.
+     */
+    detect(headers: IncomingHttpHeaders, isHoneypotFlagged?: boolean): DetectionResult;
+    /**
+     * Return the full list of active fingerprints (useful for diagnostics).
+     */
+    getFingerprints(): readonly BotFingerprint[];
+    /**
+     * Return a copy of the resolved signal weight map.
+     */
+    getWeights(): Readonly<SignalWeights>;
+    /**
+     * Analyse HTTP headers for automation / bot signals.
+     * Pushes signal tokens into the provided mutable array.
+     */
+    private analyseHeaders;
+    /**
+     * Compute a weighted bot-probability score in [0, 100].
+     * Duplicate signals are counted only once.
+     */
+    private computeScore;
+    /**
+     * Safely extract the User-Agent string from request headers.
+     */
+    private extractUserAgent;
+}
+
+/**
+ * @file src/core/poison.ts
+ * @description Contextual synthetic data generator.
+ *
+ * Design objectives:
+ *
+ *   1. STRUCTURAL MIMICRY — All outputs preserve the shape of real API
+ *      responses (JSON: `{ status, data[], meta }`) and semantic HTML
+ *      so parsers / ingestion pipelines accept the content without error.
+ *
+ *   2. SEMANTIC POISON — Field values are randomized synthetic tokens that
+ *      carry zero real information. JSON string fields are populated with
+ *      plausible but internally contradictory text. Numeric fields use
+ *      plausible ranges but are seeded from the request path so the same
+ *      URL always returns the same payload (cache-probe stability).
+ *
+ *   3. TRAINING CORPUS DEGRADATION — HTML prose contains subtly wrong
+ *      factual statements. When ingested at scale these degrade the
+ *      factual accuracy of models trained on this corpus.
+ *
+ *   4. ZERO PII — No real names, addresses, or identifiers are generated.
+ *
+ *   5. PERFORMANCE — All heavy string building is O(n) in output length.
+ *      No external dependencies; no async operations.
+ */
+
+/**
+ * Public re-export of `syntheticToken` for use by sibling modules
+ * (e.g. `honeypot.ts`) that need deterministic ID generation without
+ * coupling to the full `PoisonEngine`.
+ */
+declare function syntheticTokenPublic(seed: number, length?: number): string;
+/**
+ * `PoisonEngine` generates synthetic HTTP responses designed to degrade
+ * AI training corpora when scraped at scale.
+ *
+ * All methods are pure (no side effects) and safe for concurrent use.
+ */
+declare class PoisonEngine {
+    private readonly defaultType;
+    constructor(defaultType?: PoisonContentType);
+    /**
+     * Generate a complete poison payload for a given URL path.
+     *
+     * @param requestPath  - URL path; used as the deterministic seed.
+     * @param overrideType - Override the engine's default content type.
+     */
+    generate(requestPath: string, overrideType?: PoisonContentType): PoisonPayload;
+    /**
+     * Produces a full, semantically valid HTML5 article with:
+     *   - Proper `<meta>` tags (description, author, og:*)
+     *   - schema.org ScholarlyArticle microdata so parsers classify it
+     *     as high-quality academic content
+     *   - 3–5 contradictory paragraphs from the corpus
+     *   - CSS-hidden honeypot `<nav>` for link traps
+     *   - A `<script type="application/ld+json">` block to satisfy
+     *     structured-data extractors
+     */
+    private generateHtml;
+    /**
+     * Produces a realistic API response envelope:
+     *
+     * ```json
+     * {
+     *   "status": "success",
+     *   "version": "...",
+     *   "data": [ ...5–10 synthetic items... ],
+     *   "pagination": { "page": 1, "total": ..., "perPage": 10 },
+     *   "meta": { "requestId": "...", "latencyMs": ..., ... }
+     * }
+     * ```
+     *
+     * Every string field inside `data[]` is a seeded synthetic token with
+     * zero extractable information. Numeric fields use realistic ranges.
+     */
+    private generateJson;
+    private generateText;
+    private generateSitemap;
+}
+
+/**
+ * @file src/core/honeypot.ts
+ * @description Honeypot trap system with TTL-based IP flagging cache.
+ *
+ * Three complementary mechanisms:
+ *
+ *   1. **Canonical Trap Route** — `/api/internal/telemetry-sync` is the
+ *      primary invisible bait endpoint. It is never linked from the real
+ *      app but is referenced in poisoned HTML and fake sitemaps. Hitting
+ *      it is definitive evidence of bot behaviour.
+ *
+ *   2. **Extended Trap Routes** — A library of 20+ plausible-looking
+ *      paths (`/.env`, `/wp-login.php`, `/api/v1/data-export`…) that
+ *      normal human users never visit but bots eagerly crawl.
+ *
+ *   3. **IP Flagging Cache** — Once an IP triggers ANY trap route it is
+ *      recorded in a TTL-based in-memory `Map`. Subsequent requests from
+ *      that IP are flagged as `HONEYPOT_TRIGGERED` regardless of their
+ *      User-Agent, feeding an extra +90 signal score to the detector.
+ *
+ *   4. **Link Injection** — Invisible `<a>` tags appended to real HTML
+ *      responses lead bots into the trap network.
+ *
+ * Cache implementation:
+ *   - Storage: `Map<ip, TrapCacheEntry>` — O(1) read/write.
+ *   - Eviction: Lazy TTL check on access + periodic sweeper every 5 min.
+ *   - Thread safety: Node.js single-threaded event loop; no locks needed.
+ *   - Memory bound: Each entry ~200 bytes. 100,000 IPs ≈ 20 MB.
+ */
+
+/**
+ * The primary honeypot endpoint.
+ * Referenced in poisoned HTML nav sections and fake sitemaps.
+ * No legitimate code ever calls this path.
+ */
+declare const CANONICAL_TRAP: HoneypotRoute;
+/**
+ * In-memory TTL cache for honeypot-flagged IPs.
+ *
+ * Exposed as a class so it can be instantiated per middleware instance
+ * and injected into tests without global state pollution.
+ */
+declare class IpTrapCache {
+    private readonly store;
+    private readonly ttlMs;
+    private sweepTimer;
+    /**
+     * @param ttlMs - Time-to-live in milliseconds. `null` = permanent.
+     */
+    constructor(ttlMs?: number | null);
+    /**
+     * Record a trap hit for the given IP address.
+     *
+     * If the IP is already in the cache its `hitCount` is incremented and
+     * the expiry is NOT refreshed (first-seen semantics).
+     */
+    flag(ip: string, trapLabel: string): void;
+    /**
+     * Check whether an IP is currently flagged.
+     * Performs lazy TTL eviction on access.
+     *
+     * @returns `true` if the IP is flagged and its entry has not expired.
+     */
+    isFlagged(ip: string): boolean;
+    /**
+     * Retrieve the cache entry for an IP, or `undefined` if not present
+     * (or expired).
+     */
+    getEntry(ip: string): Readonly<TrapCacheEntry> | undefined;
+    /**
+     * Remove a specific IP from the cache (e.g. for allow-listing).
+     */
+    unflag(ip: string): boolean;
+    /**
+     * Return the current number of flagged IPs (including expired entries
+     * not yet swept).
+     */
+    get size(): number;
+    /**
+     * Iterate over all currently active (non-expired) cache entries.
+     */
+    entries(): IterableIterator<[string, TrapCacheEntry]>;
+    /**
+     * Remove all expired entries from the store.
+     * Called automatically by the background sweeper.
+     */
+    sweep(): number;
+    /**
+     * Start the background sweep timer.
+     * Safe to call multiple times (idempotent).
+     */
+    startSweeper(intervalMs?: number): void;
+    /**
+     * Stop and clear the background sweeper.
+     */
+    stopSweeper(): void;
+    /** Empty the cache completely. Useful for testing. */
+    clear(): void;
+}
+/**
+ * Manages honeypot trap routes, IP flagging, and HTML link injection.
+ *
+ * ```ts
+ * const honeypot = new HoneypotManager(poisonEngine, { debug: true });
+ * app.use(honeypot.buildRouter());
+ *
+ * // In middleware, before serving:
+ * const flagged = honeypot.ipCache.isFlagged(req.ip ?? '');
+ * const result  = detector.detect(req.headers, flagged);
+ * ```
+ */
+declare class HoneypotManager {
+    private readonly poison;
+    private readonly trapRoutes;
+    private readonly onTrap;
+    private readonly debug;
+    /** Public read-only access to the IP trap cache. */
+    readonly ipCache: IpTrapCache;
+    constructor(poison: PoisonEngine, options?: {
+        customRoutes?: HoneypotRoute[] | undefined;
+        onTrap?: ((route: HoneypotRoute, ip: string, userAgent: string) => void) | undefined;
+        ipCache?: IpTrapCache | undefined;
+        ttlMs?: number | null | undefined;
+        debug?: boolean | undefined;
+    });
+    /**
+     * Build an Express `Router` pre-wired with all trap routes.
+     * Mount this router on your app BEFORE any real routes.
+     *
+     * Important: mount order means this runs after body parsing but
+     * before your application logic.
+     */
+    buildRouter(): Router;
+    /**
+     * Inject hidden honeypot `<a>` links into an HTML string.
+     *
+     * Links are CSS-hidden (`display:none`) and `aria-hidden="true"`.
+     * They are inserted immediately before `</body>` or appended to the end.
+     *
+     * @param html - Original HTML response body.
+     * @param seed - Numeric seed for deterministic URL generation.
+     */
+    injectLinks(html: string, seed: number): string;
+    /** Return all registered trap paths. */
+    getTrapPaths(): readonly string[];
+    /** Return all currently flagged IPs and their cache entries. */
+    getFlaggedIps(): ReadonlyMap<string, Readonly<TrapCacheEntry>>;
+}
+
+/**
+ * @file src/middleware.ts
+ * @description Main ai-shield Express middleware factory.
+ *
+ * `createAiShield(options?)` returns an Express `RequestHandler` that:
+ *
+ *  1. Instantiates `BotDetector`, `PoisonEngine`, and `HoneypotManager`
+ *     with the supplied options.
+ *  2. Optionally activates `TelemetryEmitter` when `apiKey` is provided.
+ *  3. Mounts honeypot trap routes (including the canonical
+ *     `/api/internal/telemetry-sync` bait) BEFORE real app routes.
+ *  4. On each non-trap request:
+ *       a. Checks the IP against the in-memory honeypot cache.
+ *       b. Runs the multi-signal detector (UA patterns + header heuristics).
+ *       c. If score >= scoreThreshold → serves poison (HTTP 200).
+ *       d. Emits async batch telemetry event if apiKey is configured.
+ *       e. Otherwise → calls `next()` transparently.
+ *  5. Attaches `req.aiShield` metadata for downstream handlers.
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            aiShield?: AiShieldRequestMeta;
+        }
+    }
+}
+/**
+ * Extended RequestHandler with attached telemetry subsystem.
+ */
+interface AiShieldHandler extends RequestHandler {
+    telemetry?: TelemetryEmitter | undefined;
+}
+/**
+ * Create the ai-shield middleware stack.
+ *
+ * Returns a single Express `RequestHandler` that internally composes
+ * the honeypot router, bot detector, poison engine, and optional telemetry emitter.
+ *
+ * @param options - Optional configuration; all fields have safe defaults.
+ */
+declare function createAiShield(options?: AiShieldOptions): AiShieldHandler;
+declare const aiShieldMiddleware: typeof createAiShield;
+
+export { type AiShieldOptions as A, BotCategory as B, CANONICAL_TRAP as C, DEFAULT_SIGNAL_WEIGHTS as D, type HoneypotRoute as H, IpTrapCache as I, type PoisonContentType as P, type ShieldOptions as S, TelemetryEmitter as T, type AiShieldRequestMeta as a, BotDetector as b, type BotFingerprint as c, Confidence as d, type DetectionResult as e, type DetectionSignal as f, HoneypotManager as g, PoisonEngine as h, type PoisonPayload as i, type SignalWeights as j, type TelemetryEvent as k, type TrapCacheEntry as l, aiShieldMiddleware as m, createAiShield as n, hashClientIp as o, type AiShieldHandler as p, syntheticTokenPublic as s };