traffic-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth HM <hemanth@h3manth.com> (https://h3manth.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# traffic-guard
+
+High-throughput traffic and attack defense gate for incoming web traffic with zero required dependencies, wire-order analysis, and TypeSafe System One acceleration.
+
+```bash
+npm install traffic-guard
+```
+
+## Quick start
+
+```js
+import trafficguard from 'traffic-guard';
+
+const decision = await trafficguard(req);
+
+if (decision.shouldBlock) {
+  return res.status(403).json({ error: 'Forbidden', reasons: decision.reasons });
+}
+```
+
+`trafficguard(req)` inspects headers, wire sequence order, payload entropy, and velocity signals in under 30 µs. Returns `action`, `shouldBlock`, `shouldTarpit`, `riskScore`, and calibrated reasons.
+
+## Express middleware
+
+```js
+import express from 'express';
+import trafficguard from 'traffic-guard';
+
+const app = express();
+
+app.use(trafficguard.middleware({
+  policy: 'balanced',
+  allowGoodBots: true,
+  honeypotPaths: ['/__tg_trap'], // instant ban for web spiders touching hidden links
+  whitelistedPaths: ['/healthz', /^\/public\//]
+}));
+
+app.get('/api/data', (req, res) => res.json({ message: 'Hello Human!' }));
+app.listen(3000);
+```
+
+## Advanced defense patterns implemented
+
+1. **Header Order Sequence Analysis**: Real Chromium browsers send `Host` before `User-Agent` and Client Hints (`sec-ch-ua`) in a strict order. Bots forging user-agents in Python/cURL exhibit sequence disorder.
+2. **Stateless HMAC Tokens & Velocity Tracking**: Signs a signed `__trafficguard` cookie via HMAC-SHA256 tracking request velocity in 10-second sliding windows with zero database dependency.
+3. **Silent Proof-of-Work (PoW) Micro-Challenge**: Serves an inline 1.2 KB HashCash puzzle. Legitimate browsers solve it in 15–30 ms; automated CLI scrapers cannot execute JS.
+4. **Tarpitting (Slowdown Defense)**: Configurable artificial latency delay for scrapers to exhaust their concurrency pools.
+5. **Canary Honeypot Traps**: Immediate blocking of crawlers that scrape invisible honeypot URLs.
+
+## Empirical benchmark
+
+Evaluated on 25 canonical golden test cases (`bench/dataset.json`):
+
+| Metric | In-Tree Zero-Dep Engine (JS) | TypeSafe Cloud Tier (Jev-latest) |
+|---|---|---|
+| Category Classification | 100.0% | 100.0% |
+| Action Accuracy | 100.0% | 100.0% |
+| Attack Block Rate (Recall) | 100.0% | 100.0% |
+| Human False Positive Rate | 0.0% | 0.0% |
+| Good Bot Passthrough Rate | 100.0% | 100.0% |
+| Mean Latency | 30 µs (0.03 ms) | ~250 ms |
+| p95 Latency | 56 µs | ~320 ms |
+| External Dependencies | 0 required | Optional `@typesafe-ai/sdk` |
+
+## License
+
+MIT © [Hemanth.HM](https://h3manth.com)

package/dist/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/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/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;