@samimcodes/ai-shield 0.1.2 → 0.2.0

package/dist/{middleware-DNRM5IlO.d.cts → middleware-C7DQhFkV.d.cts}

@@ -204,6 +204,51 @@ interface AiShieldOptions {
      * Defaults to 'https://telemetry.ai-shield.dev/v1/events'.
      */
     dashboardUrl?: string | undefined;
+    /**
+     * When `true`, enables a self-contained live real-time security dashboard
+     * with live alerts and event stream directly in your Express app.
+     * Defaults to `false`.
+     */
+    enableDashboard?: boolean | undefined;
+    /**
+     * Route prefix where the live security dashboard will be mounted.
+     * Defaults to `'/admin/ai-shield'`.
+     */
+    dashboardPath?: string | undefined;
+    /**
+     * Optional authentication credentials to secure the dashboard.
+     */
+    dashboardAuth?: DashboardAuthConfig | undefined;
+}
+/** Optional authentication credentials for the built-in dashboard. */
+interface DashboardAuthConfig {
+    username?: string | undefined;
+    password?: string | undefined;
+    token?: string | undefined;
+}
+/** Individual live security event displayed on the dashboard. */
+interface DashboardSecurityEvent {
+    id: string;
+    timestamp: string;
+    botName: string;
+    category: BotCategory;
+    path: string;
+    score: number;
+    signals: DetectionSignal[];
+    ipHash: string;
+    userAgent: string;
+    action: 'POISON_HTML' | 'POISON_JSON' | 'POISON_SITEMAP' | 'HONEYPOT_TRAP' | 'SIMULATED_TEST';
+}
+/** Real-time statistics aggregated by the dashboard manager. */
+interface DashboardStats {
+    totalRequests: number;
+    botsIntercepted: number;
+    goodBotsAllowed: number;
+    honeypotTriggers: number;
+    poisonPayloadsServed: number;
+    estimatedFakeTokens: number;
+    topBots: Record<string, number>;
+    topRoutes: Record<string, number>;
 }
 /** Telemetry event record emitted when bots/scrapers are trapped or poisoned. */
 interface TelemetryEvent {
@@ -287,6 +332,62 @@ declare class TelemetryEmitter {
     destroy(): Promise<void>;
 }
 
+/**
+ * @file src/core/dashboard.ts
+ * @description Built-in live real-time security dashboard and SSE event broadcaster.
+ *
+ * Provides developers with an out-of-the-box, zero-dependency, ultra-sleek
+ * admin monitoring interface to watch AI bots being intercepted, poisoned,
+ * and trapped in real-time right on their own server.
+ */
+
+interface DashboardManagerOptions {
+    basePath?: string | undefined;
+    auth?: DashboardAuthConfig | undefined;
+    maxStoredEvents?: number | undefined;
+    debug?: boolean | undefined;
+}
+declare class DashboardManager {
+    private readonly basePath;
+    private readonly auth;
+    private readonly maxStoredEvents;
+    private readonly debug;
+    private events;
+    private sseClients;
+    private heartbeatTimer;
+    private stats;
+    constructor(options?: DashboardManagerOptions);
+    /**
+     * Stop background timers and disconnect SSE clients (useful during teardown).
+     */
+    close(): void;
+    /** Record a normal or bot request to update total counters. */
+    recordRequest(): void;
+    /** Record a legitimate search engine pass-through (Googlebot, Bingbot, etc). */
+    recordGoodBot(botName: string, path: string): void;
+    /**
+     * Record an intercepted AI crawler or scraper, update stats,
+     * prepend to event log, and push to all active SSE browser tabs.
+     */
+    recordEvent(event: Omit<DashboardSecurityEvent, 'id' | 'timestamp'> & {
+        timestamp?: string;
+    }): DashboardSecurityEvent;
+    /** Retrieve snapshot of current metrics. */
+    getStats(): DashboardStats;
+    /** Retrieve recent security events. */
+    getEvents(): DashboardSecurityEvent[];
+    /** Broadcast SSE event to all connected dashboard tabs. */
+    private broadcastEvent;
+    /** Broadcast periodic ping to keep SSE connections open through proxies. */
+    private broadcastPing;
+    /** Authenticate request if dashboardAuth is configured. */
+    private checkAuth;
+    /** Mount and return Express router serving the live dashboard and API. */
+    buildRouter(): Router;
+    /** Render self-contained, responsive, dark-mode single-page HTML dashboard. */
+    renderHtml(): string;
+}
+
 /**
  * @file src/core/detector.ts
  * @description Multi-signal bot fingerprinting engine.
@@ -638,10 +739,11 @@ declare global {
     }
 }
 /**
- * Extended RequestHandler with attached telemetry subsystem.
+ * Extended RequestHandler with attached telemetry and dashboard subsystems.
  */
 interface AiShieldHandler extends RequestHandler {
     telemetry?: TelemetryEmitter | undefined;
+    dashboard?: DashboardManager | undefined;
 }
 /**
  * Create the ai-shield middleware stack.
@@ -654,4 +756,4 @@ interface AiShieldHandler extends RequestHandler {
 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 };
+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 DashboardAuthConfig as e, DashboardManager as f, type DashboardSecurityEvent as g, type DashboardStats as h, type DetectionResult as i, type DetectionSignal as j, HoneypotManager as k, PoisonEngine as l, type PoisonPayload as m, type SignalWeights as n, type TelemetryEvent as o, type TrapCacheEntry as p, aiShieldMiddleware as q, createAiShield as r, hashClientIp as s, syntheticTokenPublic as t, type AiShieldHandler as u };

package/dist/{middleware-DNRM5IlO.d.ts → middleware-C7DQhFkV.d.ts}

@@ -204,6 +204,51 @@ interface AiShieldOptions {
      * Defaults to 'https://telemetry.ai-shield.dev/v1/events'.
      */
     dashboardUrl?: string | undefined;
+    /**
+     * When `true`, enables a self-contained live real-time security dashboard
+     * with live alerts and event stream directly in your Express app.
+     * Defaults to `false`.
+     */
+    enableDashboard?: boolean | undefined;
+    /**
+     * Route prefix where the live security dashboard will be mounted.
+     * Defaults to `'/admin/ai-shield'`.
+     */
+    dashboardPath?: string | undefined;
+    /**
+     * Optional authentication credentials to secure the dashboard.
+     */
+    dashboardAuth?: DashboardAuthConfig | undefined;
+}
+/** Optional authentication credentials for the built-in dashboard. */
+interface DashboardAuthConfig {
+    username?: string | undefined;
+    password?: string | undefined;
+    token?: string | undefined;
+}
+/** Individual live security event displayed on the dashboard. */
+interface DashboardSecurityEvent {
+    id: string;
+    timestamp: string;
+    botName: string;
+    category: BotCategory;
+    path: string;
+    score: number;
+    signals: DetectionSignal[];
+    ipHash: string;
+    userAgent: string;
+    action: 'POISON_HTML' | 'POISON_JSON' | 'POISON_SITEMAP' | 'HONEYPOT_TRAP' | 'SIMULATED_TEST';
+}
+/** Real-time statistics aggregated by the dashboard manager. */
+interface DashboardStats {
+    totalRequests: number;
+    botsIntercepted: number;
+    goodBotsAllowed: number;
+    honeypotTriggers: number;
+    poisonPayloadsServed: number;
+    estimatedFakeTokens: number;
+    topBots: Record<string, number>;
+    topRoutes: Record<string, number>;
 }
 /** Telemetry event record emitted when bots/scrapers are trapped or poisoned. */
 interface TelemetryEvent {
@@ -287,6 +332,62 @@ declare class TelemetryEmitter {
     destroy(): Promise<void>;
 }
 
+/**
+ * @file src/core/dashboard.ts
+ * @description Built-in live real-time security dashboard and SSE event broadcaster.
+ *
+ * Provides developers with an out-of-the-box, zero-dependency, ultra-sleek
+ * admin monitoring interface to watch AI bots being intercepted, poisoned,
+ * and trapped in real-time right on their own server.
+ */
+
+interface DashboardManagerOptions {
+    basePath?: string | undefined;
+    auth?: DashboardAuthConfig | undefined;
+    maxStoredEvents?: number | undefined;
+    debug?: boolean | undefined;
+}
+declare class DashboardManager {
+    private readonly basePath;
+    private readonly auth;
+    private readonly maxStoredEvents;
+    private readonly debug;
+    private events;
+    private sseClients;
+    private heartbeatTimer;
+    private stats;
+    constructor(options?: DashboardManagerOptions);
+    /**
+     * Stop background timers and disconnect SSE clients (useful during teardown).
+     */
+    close(): void;
+    /** Record a normal or bot request to update total counters. */
+    recordRequest(): void;
+    /** Record a legitimate search engine pass-through (Googlebot, Bingbot, etc). */
+    recordGoodBot(botName: string, path: string): void;
+    /**
+     * Record an intercepted AI crawler or scraper, update stats,
+     * prepend to event log, and push to all active SSE browser tabs.
+     */
+    recordEvent(event: Omit<DashboardSecurityEvent, 'id' | 'timestamp'> & {
+        timestamp?: string;
+    }): DashboardSecurityEvent;
+    /** Retrieve snapshot of current metrics. */
+    getStats(): DashboardStats;
+    /** Retrieve recent security events. */
+    getEvents(): DashboardSecurityEvent[];
+    /** Broadcast SSE event to all connected dashboard tabs. */
+    private broadcastEvent;
+    /** Broadcast periodic ping to keep SSE connections open through proxies. */
+    private broadcastPing;
+    /** Authenticate request if dashboardAuth is configured. */
+    private checkAuth;
+    /** Mount and return Express router serving the live dashboard and API. */
+    buildRouter(): Router;
+    /** Render self-contained, responsive, dark-mode single-page HTML dashboard. */
+    renderHtml(): string;
+}
+
 /**
  * @file src/core/detector.ts
  * @description Multi-signal bot fingerprinting engine.
@@ -638,10 +739,11 @@ declare global {
     }
 }
 /**
- * Extended RequestHandler with attached telemetry subsystem.
+ * Extended RequestHandler with attached telemetry and dashboard subsystems.
  */
 interface AiShieldHandler extends RequestHandler {
     telemetry?: TelemetryEmitter | undefined;
+    dashboard?: DashboardManager | undefined;
 }
 /**
  * Create the ai-shield middleware stack.
@@ -654,4 +756,4 @@ interface AiShieldHandler extends RequestHandler {
 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 };
+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 DashboardAuthConfig as e, DashboardManager as f, type DashboardSecurityEvent as g, type DashboardStats as h, type DetectionResult as i, type DetectionSignal as j, HoneypotManager as k, PoisonEngine as l, type PoisonPayload as m, type SignalWeights as n, type TelemetryEvent as o, type TrapCacheEntry as p, aiShieldMiddleware as q, createAiShield as r, hashClientIp as s, syntheticTokenPublic as t, type AiShieldHandler as u };