devn-bot-detector-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import { SiteInfo, SessionData, RateLimitResult, RiskResult, Telemetry, RequestContext, RiskReason, RiskLevel, RiskDecision, AnalyzeRequest, RiskConfig, TokenRevocationStore, CreateSessionRequest, CreateSessionResponse, RiskTokenPayload, VerifyRiskTokenOptions } from 'devn-bot-detector-core';
+export { API_PATHS, BotDetectorError, RequestContext, RiskDecision, RiskResult, RiskTokenPayload, SITE_KEY_HEADER, SessionData, SiteInfo, Telemetry, TokenRevocationStore, VerifyRiskTokenOptions } from 'devn-bot-detector-core';
+
+interface SiteResolver {
+    resolveSite(siteKey: string): Promise<SiteInfo | null>;
+}
+interface SessionStore {
+    create(session: SessionData): Promise<void>;
+    get(sessionId: string): Promise<SessionData | null>;
+    update(session: SessionData): Promise<void>;
+    invalidate(sessionId: string): Promise<void>;
+}
+interface RateLimiter {
+    check(key: string, limit: number, windowMs: number): RateLimitResult | Promise<RateLimitResult>;
+}
+interface EventSink {
+    onAnalysis?(result: RiskResult): Promise<void> | void;
+    onSessionCreated?(session: SessionData): Promise<void> | void;
+    onError?(error: {
+        code: string;
+        message: string;
+        requestId: string;
+    }): Promise<void> | void;
+}
+/** Minimal duck-typed Redis interface compatible with ioredis, @redis/client, upstash, etc. */
+interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    eval?(script: string, numkeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+
+interface RiskInput {
+    readonly telemetry: Telemetry;
+    readonly request: RequestContext;
+    readonly sessionAgeMs: number;
+    readonly sequence: number;
+    readonly action?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface RiskEvaluation {
+    readonly score: number;
+    readonly confidence: number;
+    readonly riskLevel: RiskLevel;
+    readonly decision?: RiskDecision;
+    readonly internalReasons: RiskReason[];
+    /** Optional additive risk from custom scoring (0–100 contribution scale). */
+    readonly risk?: number;
+}
+type Detector = (input: RiskInput) => RiskReason[];
+/** Automation indicators — never decisive alone. */
+declare const AutomationDetector: Detector;
+declare const HeadlessAdvancedDetector: Detector;
+declare const EntropyDetector: Detector;
+declare const ActionRiskDetector: Detector;
+declare const VelocityDetector: Detector;
+declare const TimingDetector: Detector;
+declare const InteractionDetector: Detector;
+declare const BrowserConsistencyDetector: Detector;
+declare const SessionDetector: Detector;
+declare const DEFAULT_DETECTORS: Detector[];
+interface RiskEngineOptions {
+    readonly detectors?: Detector[];
+    readonly detectorWeights?: Record<string, number>;
+}
+declare class RiskEngine {
+    private readonly detectors;
+    private readonly weights;
+    constructor(options?: Detector[] | RiskEngineOptions);
+    evaluate(input: RiskInput): RiskEvaluation;
+}
+
+interface ServerOptions {
+    readonly secret: string;
+    readonly sessionDuration?: number;
+    readonly riskThresholds?: Partial<RiskConfig>;
+    readonly actionThresholds?: Record<string, Partial<RiskConfig>>;
+    readonly ipAllowlist?: readonly string[];
+    readonly ipDenylist?: readonly string[];
+    readonly detectorWeights?: Record<string, number>;
+    readonly tokenRevocationStore?: TokenRevocationStore;
+    readonly enableRiskToken?: boolean;
+    readonly riskTokenDuration?: number;
+    readonly trustProxy?: boolean;
+    readonly debug?: boolean;
+    readonly siteResolver?: SiteResolver;
+    readonly sessionStore?: SessionStore;
+    readonly rateLimiter?: RateLimiter;
+    readonly eventSink?: EventSink;
+    readonly maxTelemetryBytes?: number;
+    readonly rateLimits?: {
+        readonly sitePerMinute?: number;
+        readonly sessionPerMinute?: number;
+        readonly ipPerMinute?: number;
+    };
+    readonly customScoring?: (input: RiskInput) => Partial<RiskEvaluation> | Promise<Partial<RiskEvaluation>>;
+}
+interface CreateSessionInput extends CreateSessionRequest {
+    readonly siteKey: string;
+    readonly request?: RequestContext;
+}
+interface AnalyzeInput extends AnalyzeRequest {
+    readonly siteKey: string;
+    readonly request?: RequestContext;
+}
+declare class BotDetectionServer {
+    private readonly sessionDuration;
+    private readonly thresholds;
+    private readonly actionThresholds?;
+    private readonly ipAllowlist;
+    private readonly ipDenylist;
+    private readonly tokenRevocationStore?;
+    private readonly enableRiskToken;
+    private readonly riskTokenDuration;
+    private readonly trustProxy;
+    private readonly debug;
+    private readonly maxTelemetryBytes;
+    private readonly siteResolver;
+    private readonly sessionStore;
+    private readonly rateLimiter;
+    private readonly eventSink?;
+    private readonly tokens;
+    private readonly engine;
+    private readonly customScoring?;
+    private readonly rateLimits;
+    constructor(options: ServerOptions);
+    getSite(siteKey: string): Promise<SiteInfo | null>;
+    validateHostname(hostname: string, site: SiteInfo, request?: RequestContext): boolean;
+    createSession(input: CreateSessionInput): Promise<CreateSessionResponse>;
+    analyze(input: AnalyzeInput): Promise<RiskResult>;
+    calculateRisk(input: RiskInput): Promise<RiskEvaluation>;
+    createRiskToken(payload: RiskTokenPayload): string;
+    verifyRiskToken(token: string, options?: VerifyRiskTokenOptions): RiskTokenPayload | null;
+    /**
+     * Validates risk token and consumes it (one-time use) if tokenRevocationStore is configured.
+     * Throws TOKEN_ALREADY_USED if already consumed or MALFORMED_REQUEST if invalid/expired.
+     */
+    consumeRiskToken(token: string, options?: VerifyRiskTokenOptions): Promise<RiskTokenPayload>;
+    private resolveActiveSite;
+    private assertRateLimits;
+    private resolveIp;
+    private normalizeRequest;
+}
+
+declare function secureId(prefix: string, bytes?: number): string;
+/** In-memory site resolver for development/testing only. */
+declare class MemorySiteResolver implements SiteResolver {
+    private readonly sites;
+    constructor(entries?: Array<{
+        siteKey: string;
+        site: SiteInfo;
+    }>);
+    set(siteKey: string, site: SiteInfo): void;
+    resolveSite(siteKey: string): Promise<SiteInfo | null>;
+}
+/** In-memory session store for development/testing only. */
+declare class MemorySessionStore implements SessionStore {
+    private readonly sessions;
+    create(session: SessionData): Promise<void>;
+    get(sessionId: string): Promise<SessionData | null>;
+    update(session: SessionData): Promise<void>;
+    invalidate(sessionId: string): Promise<void>;
+}
+/** In-memory token revocation store for single-instance / dev usage. */
+declare class MemoryTokenRevocationStore implements TokenRevocationStore {
+    private readonly revoked;
+    isRevoked(tokenId: string): boolean;
+    revoke(tokenId: string, ttlMs: number): void;
+}
+
+/** Simple in-memory sliding-window rate limiter (dev/default). */
+declare class MemoryRateLimiter implements RateLimiter {
+    private readonly buckets;
+    check(key: string, limit: number, windowMs: number): RateLimitResult;
+    /** Best-effort cleanup for long-running processes. */
+    prune(): void;
+}
+
+declare class TokenManager {
+    private readonly secret;
+    constructor(secret: string);
+    createRiskToken(payload: RiskTokenPayload): string;
+    verifyRiskToken(token: string, options?: VerifyRiskTokenOptions): RiskTokenPayload | null;
+}
+
+interface RedisSessionStoreOptions {
+    readonly prefix?: string;
+    readonly defaultTtlSeconds?: number;
+}
+/** Production Redis Session Store with automatic TTL expiry. */
+declare class RedisSessionStore implements SessionStore {
+    private readonly client;
+    private readonly prefix;
+    private readonly defaultTtl;
+    constructor(client: RedisLikeClient, options?: RedisSessionStoreOptions);
+    private key;
+    create(session: SessionData): Promise<void>;
+    get(sessionId: string): Promise<SessionData | null>;
+    update(session: SessionData): Promise<void>;
+    invalidate(sessionId: string): Promise<void>;
+}
+interface RedisRateLimiterOptions {
+    readonly prefix?: string;
+}
+/** Production Redis Rate Limiter with atomic INCR + EXPIRE via Lua or pipeline. */
+declare class RedisRateLimiter implements RateLimiter {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisLikeClient, options?: RedisRateLimiterOptions);
+    check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+}
+interface RedisTokenRevocationStoreOptions {
+    readonly prefix?: string;
+}
+/** Production Redis token revocation store for one-time token consumption / replay prevention. */
+declare class RedisTokenRevocationStore implements TokenRevocationStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisLikeClient, options?: RedisTokenRevocationStoreOptions);
+    isRevoked(tokenId: string): Promise<boolean>;
+    revoke(tokenId: string, ttlMs: number): Promise<void>;
+}
+
+interface FrameworkRequestLike {
+    headers?: Record<string, string | string[] | undefined>;
+    header?(name: string): string | undefined;
+    get?(name: string): string | undefined;
+    body?: unknown;
+    ip?: string;
+}
+interface FrameworkResponseLike {
+    status(code: number): this;
+    json(body: unknown): void;
+}
+interface TokenGuardOptions extends VerifyRiskTokenOptions {
+    /** If true, the token is consumed (one-time use, preventing replay attacks). Defaults to false. */
+    readonly consume?: boolean;
+    /** Header to read the token from. Defaults to 'x-risk-token'. */
+    readonly headerName?: string;
+    /** Fallback property to read the token from request body. Defaults to 'riskToken'. */
+    readonly bodyField?: string;
+}
+/**
+ * Universal helper to extract and verify or consume a risk token from any incoming HTTP request.
+ * Useful for Next.js Server Actions, Nuxt, SvelteKit, Remix, NestJS, Fastify, Express, and Hono.
+ */
+declare function verifyRequestRiskToken(server: BotDetectionServer, request: FrameworkRequestLike, options?: TokenGuardOptions): Promise<RiskTokenPayload>;
+/** Express / Connect helper creating ready-to-mount route handlers and guards. */
+declare function createExpressBotDetector(server: BotDetectionServer): {
+    /** Route handler for POST /v1/session */
+    sessionHandler: (req: any, res: any) => Promise<void>;
+    /** Route handler for POST /v1/analyze */
+    analyzeHandler: (req: any, res: any) => Promise<void>;
+    /** Middleware protecting sensitive routes with risk token verification */
+    requireRiskToken: (options?: TokenGuardOptions) => (req: any, res: any, next: any) => Promise<void>;
+};
+
+export { ActionRiskDetector, type AnalyzeInput, AutomationDetector, BotDetectionServer, BrowserConsistencyDetector, type CreateSessionInput, DEFAULT_DETECTORS, type Detector, EntropyDetector, type EventSink, type FrameworkRequestLike, type FrameworkResponseLike, HeadlessAdvancedDetector, InteractionDetector, MemoryRateLimiter, MemorySessionStore, MemorySiteResolver, MemoryTokenRevocationStore, type RateLimiter, type RedisLikeClient, RedisRateLimiter, type RedisRateLimiterOptions, RedisSessionStore, type RedisSessionStoreOptions, RedisTokenRevocationStore, type RedisTokenRevocationStoreOptions, RiskEngine, type RiskEngineOptions, type RiskEvaluation, type RiskInput, type ServerOptions, SessionDetector, type SessionStore, type SiteResolver, TimingDetector, type TokenGuardOptions, TokenManager, VelocityDetector, createExpressBotDetector, secureId, verifyRequestRiskToken };