traffic-guard 0.2.0 → 0.2.1

package/dist/src/battery.d.ts

@@ -0,0 +1,19 @@
+import type { AssessmentResult, NormalizedRequest, RequestContext } from './types.js';
+export declare function loadTypeSafePrimitives(): Promise<{
+    choice: any;
+    noul: any;
+    score: any;
+}>;
+export declare function createBotGateBattery(): {
+    is_bot: any;
+    is_attack: any;
+    is_spoofed: any;
+    traffic_type: any;
+    risk_level: any;
+};
+/**
+ * Computes Shannon entropy of a string using Uint8Array frequency table.
+ * Useful for detecting obfuscated attack strings and random scanner paths.
+ */
+export declare function calculateShannonEntropy(str: string): number;
+export declare function heuristicAssessment(request: NormalizedRequest, context: RequestContext): AssessmentResult;

package/dist/src/crypto.d.ts

@@ -0,0 +1,16 @@
+export interface BotCookiePayload {
+    h: string;
+    c: number;
+    ws: number;
+    v?: number;
+}
+export declare function createClientHash(ip?: string, userAgent?: string): string;
+export declare function signBotToken(payload: BotCookiePayload, secret?: string): string;
+export declare function verifyBotToken(token: string, secret?: string): BotCookiePayload | null;
+export declare function parseCookies(cookieHeader?: string): Record<string, string>;
+export declare function createPoWChallenge(secret?: string, difficulty?: number): {
+    seed: string;
+    difficulty: number;
+};
+export declare function verifyPoW(seed: string, nonce: string, minDifficulty?: number, secret?: string): boolean;
+export declare function generateChallengeHtml(seed: string, difficulty: number, returnUrl?: string): string;

package/dist/src/gate.d.ts

@@ -0,0 +1,15 @@
+import type { BotGateDecision, BotGateOptions, RequestInput } from './types.js';
+export declare class BotGate {
+    private client;
+    private clientInitAttempted;
+    private options;
+    private battery;
+    constructor(options?: BotGateOptions);
+    private getClient;
+    inspect(input: RequestInput, runtimeOptions?: BotGateOptions): Promise<BotGateDecision>;
+    middleware(middlewareOptions?: BotGateOptions): (req: any, res: any, next: (err?: any) => void) => Promise<any>;
+    private createAllowedDecision;
+    private createBlockedDecision;
+}
+export type TrafficGuard = BotGate;
+export declare const TrafficGuard: typeof BotGate;

package/dist/src/index.d.ts

@@ -0,0 +1,32 @@
+import { BotGate, TrafficGuard } from './gate.js';
+import type { BotGateDecision, RequestInput, TrafficDecision, TrafficGuardOptions } from './types.js';
+/**
+ * Inspects an incoming request and returns a bot/attack defense decision in under 30 µs.
+ *
+ * @example
+ * ```ts
+ * import trafficguard from 'traffic-guard';
+ *
+ * const decision = await trafficguard(req);
+ * if (decision.shouldBlock) {
+ *   return res.status(403).json({ error: 'Forbidden', reasons: decision.reasons });
+ * }
+ * ```
+ */
+declare function trafficguard(input: RequestInput, options?: TrafficGuardOptions): Promise<TrafficDecision>;
+declare namespace trafficguard {
+    var create: (options?: TrafficGuardOptions) => BotGate;
+    var inspect: (input: RequestInput, options?: TrafficGuardOptions) => Promise<BotGateDecision>;
+    var middleware: (options?: TrafficGuardOptions) => (req: any, res: any, next: (err?: any) => void) => Promise<any>;
+    export { TrafficGuard };
+    export { BotGate };
+}
+declare const botgate: typeof trafficguard;
+declare const trafficGuard: typeof trafficguard;
+export { TrafficGuard, BotGate, trafficguard, trafficGuard, botgate };
+export { normalizeRequest, checkHeaderOrderAnomaly } from './normalizer.js';
+export { DEFAULT_POLICIES, evaluateDecision, resolvePolicy } from './policy.js';
+export { createBotGateBattery, heuristicAssessment, calculateShannonEntropy } from './battery.js';
+export { signBotToken, verifyBotToken, createPoWChallenge, verifyPoW, generateChallengeHtml, createClientHash } from './crypto.js';
+export type * from './types.js';
+export default trafficguard;

package/dist/src/normalizer.d.ts

@@ -0,0 +1,6 @@
+import type { NormalizedRequest, RequestContext, RequestInput } from './types.js';
+export declare function checkHeaderOrderAnomaly(rawHeaders: string[] | undefined, userAgent: string): boolean;
+export declare function normalizeRequest(input: RequestInput): {
+    request: NormalizedRequest;
+    context: RequestContext;
+};

package/dist/src/policy.d.ts

@@ -0,0 +1,4 @@
+import type { AssessmentResult, BotGateDecision, GatePolicy, PolicyName, BotGateOptions, RequestContext } from './types.js';
+export declare const DEFAULT_POLICIES: Record<PolicyName, GatePolicy>;
+export declare function resolvePolicy(policy?: PolicyName | Partial<GatePolicy>): GatePolicy;
+export declare function evaluateDecision(assessment: AssessmentResult, policy: GatePolicy, options: BotGateOptions, durationMs: number, context?: RequestContext): BotGateDecision;

package/dist/src/types.d.ts

@@ -0,0 +1,96 @@
+export type PolicyName = 'balanced' | 'strict' | 'permissive';
+export type ActionType = 'allow' | 'challenge' | 'block' | 'tarpit' | 'monitor';
+export type TrafficCategory = 'human' | 'good_bot' | 'bad_bot' | 'attack';
+export interface NormalizedRequest {
+    method: string;
+    path: string;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    rawHeaders?: string[];
+    body?: string | Record<string, unknown> | null;
+    ip?: string;
+    url?: string;
+    cookies?: Record<string, string>;
+}
+export interface RequestContext {
+    missingBrowserHeaders: string[];
+    suspiciousSignatures: string[];
+    claimsBrowser: boolean;
+    isKnownSearchBot: boolean;
+    headerOrderAnomaly: boolean;
+    shannonEntropy: number;
+    rateCount?: number;
+    isHoneypot?: boolean;
+}
+export interface GatePolicy {
+    attackThreshold: number;
+    botThreshold: number;
+    challengeThreshold: number;
+    riskBlock: number;
+    riskChallenge: number;
+    spoofThreshold: number;
+    velocityBurstLimit: number;
+}
+export interface BotGateOptions {
+    policy?: PolicyName | Partial<GatePolicy>;
+    apiKey?: string;
+    endpoint?: string;
+    model?: string;
+    timeout?: number;
+    allowGoodBots?: boolean;
+    whitelistedPaths?: (string | RegExp)[];
+    whitelistedIps?: string[];
+    honeypotPaths?: string[];
+    secretKey?: string;
+    tarpitMs?: number;
+    enablePoWChallenge?: boolean;
+    fallback?: 'heuristic' | 'allow' | 'block';
+    onBlock?: (decision: BotGateDecision, req: unknown, res: unknown) => void;
+    onChallenge?: (decision: BotGateDecision, req: unknown, res: unknown) => void;
+    onTarpit?: (decision: BotGateDecision, req: unknown, res: unknown) => void;
+}
+export interface AssessmentResult {
+    isBotProbability: number;
+    isAttackProbability: number;
+    isSpoofedProbability: number;
+    trafficType: TrafficCategory;
+    trafficTypeConfidence: number;
+    trafficTypeDistribution: Record<string, number>;
+    riskScore: number;
+    riskConfidence: number;
+    riskLevelDistribution: Record<string, number>;
+}
+export interface BotGateDecision {
+    action: ActionType;
+    shouldBlock: boolean;
+    shouldChallenge: boolean;
+    shouldTarpit: boolean;
+    isBot: boolean;
+    isAttack: boolean;
+    category: TrafficCategory;
+    riskScore: number;
+    confidence: number;
+    reasons: string[];
+    assessment: AssessmentResult;
+    durationMs: number;
+    setCookieHeader?: string;
+    challengeHtml?: string;
+    respond?: (res: any) => Promise<boolean> | boolean;
+}
+export type TrafficGuardOptions = BotGateOptions;
+export type TrafficDecision = BotGateDecision;
+export type RequestInput = string | NormalizedRequest | {
+    method?: string;
+    url?: string;
+    path?: string;
+    originalUrl?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    rawHeaders?: string[];
+    query?: Record<string, unknown>;
+    body?: unknown;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    cookies?: Record<string, string>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traffic-guard",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "High-throughput traffic and attack defense gate with zero required dependencies, wire-order analysis, and TypeSafe System One acceleration.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -46,9 +46,9 @@
     "@typesafe-ai/sdk": "^0.6.0"
   },
   "devDependencies": {
-    "@types/node": "^22.13.9",
+    "@types/node": "^26.6.4",
     "@typesafe-ai/sdk": "^0.6.0",
-    "esbuild": "^0.25.0",
-    "typescript": "^5.8.2"
+    "esbuild": "^0.28.2",
+    "typescript": "^5.8.3"
   }
 }