botshield-express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Travelio
+
+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,72 @@
+# botshield-express
+
+Drop-in Express middleware for BotShield.
+
+It reads the verdict the gateway already computed, scores the request through the
+engine when there is none, attaches the result to `req.botshield`, and **fails
+open** — an unreachable engine degrades to "no verdict"; it never blocks a
+request and never throws into the request path.
+
+## Install
+
+```bash
+npm install botshield-express
+```
+
+`express` is a peer dependency (^4.18) — bring your own.
+
+## Usage
+
+```js
+const express = require('express');
+const { botShield } = require('botshield-express');
+
+const app = express();
+
+app.use(
+  botShield({
+    engineUrl: process.env.ENGINE_URL ?? 'http://engine:4000',
+    appName: 'my-app',
+    mode: 'shadow', // observes only; never blocks
+    protectedRoutes: ['/login*', '/checkout*'],
+    logger: console,
+  }),
+);
+
+app.get('/login', (req, res) => {
+  req.botshield.verdict; // 'allow' | 'notify' | 'challenge' | 'block'
+  req.botshield.score; // 0-100
+  req.botshield.requestId;
+  req.botshield.record('login_attempt', { ok: false }); // business event, fire and forget
+  res.sendStatus(200);
+});
+```
+
+## Options
+
+| option              | default  | meaning                                                                        |
+| ------------------- | -------- | ------------------------------------------------------------------------------ |
+| `engineUrl`         | –        | Base URL of the BotShield engine (`http://engine:4000` inside the compose net)  |
+| `appName`           | –        | Reported to the engine as the `app` field                                      |
+| `mode`              | `shadow` | `shadow` observes only; `enforce` permits block/challenge actions              |
+| `protectedRoutes`   | `[]`     | Patterns the middleware scores; every other request passes through untouched    |
+| `fingerprintCookie` | –        | Overrides the cookie name the browser sensor sets                              |
+| `timeoutMs`         | –        | Bounded time budget for the engine call                                        |
+| `cacheMaxEntries`   | `5000`   | Entries retained in the in-process verdict cache                               |
+| `onVerdict`         | –        | `(context, req) => void` hook                                                  |
+| `logger`            | –        | `{ warn(obj, msg?), error(obj, msg?) }`                                        |
+
+## Exports
+
+`botShield`, `VerdictCache`, `matchesProtected`, `createEngineClient`, and the
+types `BotShieldConfig`, `BotShieldContext`, `BotShieldMiddleware`, `Verdict`,
+`VerifyRequest`, `EngineClient`, `Action`, `NextFunction`, `Request`,
+`RequestHandler`, `Response`.
+
+## Notes
+
+- The engine must be reachable. From a container outside the BotShield compose
+  project, join its network first (`docker network ls | grep botshield`).
+- Verdicts are cached for the TTL the engine returns, and a verdict supplied by
+  the gateway is reused instead of calling the engine again.
+- This package is CommonJS and targets Node 20+.

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { Verdict, VerifyRequest } from './types';
+/**
+ * Engine client for the SDK.
+ *
+ * Three rules, in order of importance:
+ *  1. **Fail open.** Any failure — timeout, connection refused, 5xx, malformed
+ *     JSON — yields `null`, and the caller lets the request through (§3.3).
+ *  2. **Bounded latency.** A slow engine must not become a slow application, so
+ *     every call carries an AbortController deadline.
+ *  3. **Never throw.** The request path does not tolerate exceptions from here.
+ */
+export interface EngineClientOptions {
+    engineUrl: string;
+    timeoutMs?: number;
+}
+export declare const DEFAULT_TIMEOUT_MS = 1000;
+export interface EngineClient {
+    verify(input: VerifyRequest): Promise<Verdict | null>;
+    recordEvent(input: {
+        app: string;
+        event: string;
+        occurredAt: string;
+        subject: {
+            ip: string;
+            userId?: string;
+            fingerprint?: string;
+        };
+        attributes: Record<string, unknown>;
+    }): Promise<void>;
+}
+export declare function createEngineClient(options: EngineClientOptions): EngineClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtD;;;;;;;;;GASG;AAEH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtD,WAAW,CAAC,KAAK,EAAE;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/D,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AA4CD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAiB7E"}

package/dist/client.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.createEngineClient = createEngineClient;
+exports.DEFAULT_TIMEOUT_MS = 1_000;
+function isVerdict(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.action === 'string' &&
+        typeof candidate.score === 'number' &&
+        typeof candidate.verdict === 'string');
+}
+async function postJson(url, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text === '' ? null : JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+        return { ok: response.ok, status: response.status, body: parsed };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function createEngineClient(options) {
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const base = options.engineUrl.replace(/\/+$/, '');
+    return {
+        async verify(input) {
+            const result = await postJson(`${base}/verify`, input, timeoutMs);
+            if (!result || !result.ok)
+                return null;
+            return isVerdict(result.body) ? result.body : null;
+        },
+        async recordEvent(input) {
+            // Business-event reporting is explicitly fire-and-forget. The /events
+            // endpoint lands in Phase 3; until then this is a tolerated 404.
+            await postJson(`${base}/events`, input, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAyEA,gDAiBC;AAxEY,QAAA,kBAAkB,GAAG,KAAK,CAAC;AAaxC,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAyB,CAAC;IAC5C,OAAO,CACL,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;QACpC,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ;QACnC,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ,CACtC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,GAAW,EACX,IAAa,EACb,SAAiB;IAEjB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,MAAM,GAAY,IAAI,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QAED,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,SAAgB,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,0BAAkB,CAAC;IAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEnD,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAoB;YAC/B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,OAAO,IAAI,CAAC;YACvC,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACrD,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,KAAK;YACrB,sEAAsE;YACtE,iEAAiE;YACjE,MAAM,QAAQ,CAAC,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { botShield, VerdictCache, matchesProtected } from './middleware';
+export { createEngineClient } from './client';
+export type { Action, BotShieldConfig, BotShieldContext, BotShieldMiddleware, Verdict, VerifyRequest, } from './types';
+export type { EngineClient } from './client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EACV,MAAM,EACN,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,OAAO,EACP,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEngineClient = exports.matchesProtected = exports.VerdictCache = exports.botShield = void 0;
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "botShield", { enumerable: true, get: function () { return middleware_1.botShield; } });
+Object.defineProperty(exports, "VerdictCache", { enumerable: true, get: function () { return middleware_1.VerdictCache; } });
+Object.defineProperty(exports, "matchesProtected", { enumerable: true, get: function () { return middleware_1.matchesProtected; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "createEngineClient", { enumerable: true, get: function () { return client_1.createEngineClient; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAAyE;AAAhE,uGAAA,SAAS,OAAA;AAAE,0GAAA,YAAY,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAClD,mCAA8C;AAArC,4GAAA,kBAAkB,OAAA"}

package/dist/middleware.d.ts

@@ -0,0 +1,40 @@
+import { createEngineClient, type EngineClient } from './client';
+import type { BotShieldConfig, BotShieldMiddleware, Verdict } from './types';
+/**
+ * botshield-express middleware (§15).
+ *
+ * Requirements this file exists to satisfy:
+ *  - fail open when the engine is unreachable
+ *  - never throw into the request path
+ *  - cache verdicts locally for the TTL the engine returned
+ *  - skip the engine call entirely when the gateway already supplied a verdict
+ *
+ * Every request-scoped value lives in a closure created per request. There is
+ * deliberately no shared mutable state: a module-level "current request" would
+ * leak between concurrent requests, which is the classic way an observability
+ * middleware becomes a security hole.
+ */
+export interface VerdictCacheEntry {
+    verdict: Verdict;
+    expiresAt: number;
+}
+/** Small bounded cache; Map insertion order doubles as eviction order. */
+export declare class VerdictCache {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    get(key: string, now?: number): Verdict | null;
+    set(key: string, verdict: Verdict, now?: number): void;
+    get size(): number;
+}
+export interface RequestScope {
+    ip: string;
+    fingerprint?: string | undefined;
+    sessionId?: string | undefined;
+    userId?: string | undefined;
+}
+export declare function matchesProtected(path: string, patterns: readonly string[]): boolean;
+export declare function botShield(config: BotShieldConfig): BotShieldMiddleware;
+export { createEngineClient, VerdictCache as VerdictCacheImpl };
+export type { EngineClient };
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAEV,eAAe,EAEf,mBAAmB,EAKnB,OAAO,EACR,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;gBAEnC,UAAU,SAAQ;IAE/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,GAAG,IAAI;IAYlD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,IAAI;IAU1D,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAsCD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAKnF;AAQD,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,mBAAmB,CAqItE;AAED,OAAO,EAAE,kBAAkB,EAAE,YAAY,IAAI,gBAAgB,EAAE,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/middleware.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerdictCacheImpl = exports.createEngineClient = exports.VerdictCache = void 0;
+exports.matchesProtected = matchesProtected;
+exports.botShield = botShield;
+const client_1 = require("./client");
+Object.defineProperty(exports, "createEngineClient", { enumerable: true, get: function () { return client_1.createEngineClient; } });
+/** Small bounded cache; Map insertion order doubles as eviction order. */
+class VerdictCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries = 5_000) {
+        this.maxEntries = maxEntries;
+    }
+    get(key, now = Date.now()) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= now) {
+            this.entries.delete(key);
+            return null;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.verdict;
+    }
+    set(key, verdict, now = Date.now()) {
+        this.entries.set(key, { verdict, expiresAt: now + Math.max(0, verdict.ttl) * 1000 });
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+exports.VerdictCache = VerdictCache;
+exports.VerdictCacheImpl = VerdictCache;
+function parseCookies(header) {
+    const cookies = {};
+    if (!header)
+        return cookies;
+    for (const part of header.split(';')) {
+        const index = part.indexOf('=');
+        if (index === -1)
+            continue;
+        const name = part.slice(0, index).trim();
+        if (name === '')
+            continue;
+        const raw = part.slice(index + 1).trim();
+        try {
+            cookies[name] = decodeURIComponent(raw);
+        }
+        catch {
+            cookies[name] = raw;
+        }
+    }
+    return cookies;
+}
+function headerValue(headers, name) {
+    const value = headers[name];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && typeof value[0] === 'string')
+        return value[0];
+    return undefined;
+}
+function toHeaderRecord(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value === 'string')
+            result[name] = value;
+        else if (Array.isArray(value))
+            result[name] = value.join(', ');
+    }
+    return result;
+}
+function matchesProtected(path, patterns) {
+    return patterns.some((pattern) => {
+        if (pattern.endsWith('*'))
+            return path.startsWith(pattern.slice(0, -1));
+        return path === pattern;
+    });
+}
+function actionFromHeader(value) {
+    return value === 'allow' || value === 'notify' || value === 'challenge' || value === 'block'
+        ? value
+        : null;
+}
+function botShield(config) {
+    const mode = config.mode ?? 'shadow';
+    const protectedRoutes = config.protectedRoutes ?? [];
+    const fingerprintCookie = config.fingerprintCookie ?? 'bs_fp';
+    const cache = new VerdictCache(config.cacheMaxEntries ?? 5_000);
+    const client = (0, client_1.createEngineClient)({
+        engineUrl: config.engineUrl,
+        timeoutMs: config.timeoutMs,
+    });
+    function buildContext(verdict, score, requestId, cached, scope) {
+        return {
+            verdict,
+            score,
+            requestId,
+            cached,
+            record(event, attributes) {
+                // Fire-and-forget (§15): not awaited, cannot fail the request.
+                void client
+                    .recordEvent({
+                    app: config.appName,
+                    event,
+                    occurredAt: new Date().toISOString(),
+                    subject: {
+                        ip: scope.ip,
+                        ...(scope.userId ? { userId: scope.userId } : {}),
+                        ...(scope.fingerprint ? { fingerprint: scope.fingerprint } : {}),
+                    },
+                    attributes,
+                })
+                    .catch(() => undefined);
+            },
+        };
+    }
+    const handler = async (req, res, next) => {
+        const headers = toHeaderRecord(req.headers);
+        const cookies = parseCookies(headerValue(headers, 'cookie'));
+        const scope = {
+            ip: headerValue(headers, 'x-real-ip') ?? req.socket?.remoteAddress ?? '0.0.0.0',
+            fingerprint: cookies[fingerprintCookie],
+            sessionId: cookies.bs_sid,
+            userId: req.user?.id,
+        };
+        /** Attaches the context and lets the request proceed. */
+        const pass = (context) => {
+            req.botshield = context;
+            config.onVerdict?.(context, req);
+            next();
+        };
+        try {
+            // The gateway already decided — trust it and skip the engine (§13.1, §15).
+            const gatewayVerdict = actionFromHeader(headerValue(headers, 'x-bot-verdict'));
+            if (gatewayVerdict !== null) {
+                pass(buildContext(gatewayVerdict, Number(headerValue(headers, 'x-bot-score') ?? 0), headerValue(headers, 'x-request-id') ?? 'gateway', true, scope));
+                return;
+            }
+            const cacheKey = `${scope.fingerprint ?? 'no-fp'}|${scope.ip}`;
+            const cached = scope.fingerprint ? cache.get(cacheKey) : null;
+            if (cached) {
+                pass(buildContext(cached.action, cached.score, cached.requestId, true, scope));
+                return;
+            }
+            const pageLoadTs = cookies.bs_load ? Number(cookies.bs_load) : undefined;
+            const submitTs = cookies.bs_submit ? Number(cookies.bs_submit) : undefined;
+            const ja4 = headerValue(headers, 'x-ja4-hash');
+            const verdict = await client.verify({
+                app: config.appName,
+                method: req.method,
+                path: req.originalUrl ?? req.url,
+                ip: scope.ip,
+                ...(scope.userId ? { userId: scope.userId } : {}),
+                ...(scope.fingerprint ? { fingerprint: scope.fingerprint } : {}),
+                ...(scope.sessionId ? { sessionId: scope.sessionId } : {}),
+                ...(ja4 ? { ja4 } : {}),
+                headers,
+                ...(pageLoadTs !== undefined && submitTs !== undefined
+                    ? { timing: { pageLoadTs, submitTs } }
+                    : {}),
+            });
+            if (!verdict) {
+                // Fail open: engine down, too slow, or nonsense (§3.3, §15).
+                pass(buildContext('allow', 0, 'unavailable', false, scope));
+                return;
+            }
+            if (scope.fingerprint)
+                cache.set(cacheKey, verdict);
+            const context = buildContext(verdict.action, verdict.score, verdict.requestId, verdict.cached, scope);
+            if (mode === 'enforce' &&
+                context.verdict === 'block' &&
+                matchesProtected(req.path, protectedRoutes)) {
+                req.botshield = context;
+                config.onVerdict?.(context, req);
+                res.status(403).json({ error: 'forbidden', requestId: context.requestId });
+                return;
+            }
+            // `challenge` is intentionally not enforced here: §19 schedules the
+            // proof-of-work endpoint for a later phase, and a redirect to a route
+            // that does not exist would be worse than observing.
+            pass(context);
+        }
+        catch (error) {
+            // The request path must never see an exception from here (§15).
+            try {
+                config.logger?.error({ err: error }, 'botshield middleware failed — failing open');
+                req.botshield = buildContext('allow', 0, 'error', false, scope);
+            }
+            catch {
+                /* nothing more we can safely do */
+            }
+            next();
+        }
+    };
+    const wrapped = Object.assign(handler, { client });
+    return wrapped;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":";;;AA6GA,4CAKC;AAQD,8BAqIC;AA/PD,qCAAiE;AAiQxD,mGAjQA,2BAAkB,OAiQA;AAhO3B,0EAA0E;AAC1E,MAAa,YAAY;IAGM;IAFZ,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEhE,YAA6B,aAAa,KAAK;QAAlB,eAAU,GAAV,UAAU,CAAQ;IAAG,CAAC;IAEnD,GAAG,CAAC,GAAW,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,OAAgB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QACjD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAErF,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YAC1C,IAAI,MAAM,CAAC,IAAI;gBAAE,MAAM;YACvB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AA9BD,oCA8BC;AAiM4C,wCAAgB;AAxL7D,SAAS,YAAY,CAAC,MAA0B;IAC9C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAE5B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAS;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,OAAgC,EAAE,IAAY;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,cAAc,CAAC,OAAgC;IACtD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;aAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,gBAAgB,CAAC,IAAY,EAAE,QAA2B;IACxE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,OAAO,IAAI,KAAK,OAAO,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAyB;IACjD,OAAO,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,OAAO;QAC1F,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,SAAgB,SAAS,CAAC,MAAuB;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC;IACrC,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC;IACrD,MAAM,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,IAAI,OAAO,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,eAAe,IAAI,KAAK,CAAC,CAAC;IAChE,MAAM,MAAM,GAAiB,IAAA,2BAAkB,EAAC;QAC9C,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC;IAEH,SAAS,YAAY,CAAC,OAAe,EAAE,KAAa,EAAE,SAAiB,EAAE,MAAe,EAAE,KAAmB;QAC3G,OAAO;YACL,OAAO;YACP,KAAK;YACL,SAAS;YACT,MAAM;YACN,MAAM,CAAC,KAAK,EAAE,UAAU;gBACtB,+DAA+D;gBAC/D,KAAK,MAAM;qBACR,WAAW,CAAC;oBACX,GAAG,EAAE,MAAM,CAAC,OAAO;oBACnB,KAAK;oBACL,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACpC,OAAO,EAAE;wBACP,EAAE,EAAE,KAAK,CAAC,EAAE;wBACZ,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACjD,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACjE;oBACD,UAAU;iBACX,CAAC;qBACD,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC5B,CAAC;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAmB,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAiB,EAAE;QACvG,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAiB;YAC1B,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,aAAa,IAAI,SAAS;YAC/E,WAAW,EAAE,OAAO,CAAC,iBAAiB,CAAC;YACvC,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,MAAM,EAAG,GAA6C,CAAC,IAAI,EAAE,EAAE;SAChE,CAAC;QAEF,yDAAyD;QACzD,MAAM,IAAI,GAAG,CAAC,OAAyB,EAAQ,EAAE;YAC/C,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC;YACxB,MAAM,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC;QACT,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,2EAA2E;YAC3E,MAAM,cAAc,GAAG,gBAAgB,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;YAC/E,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,IAAI,CACF,YAAY,CACV,cAAc,EACd,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,EAChD,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,SAAS,EACjD,IAAI,EACJ,KAAK,CACN,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YAED,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,WAAW,IAAI,OAAO,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC9D,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC/E,OAAO;YACT,CAAC;YAED,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3E,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAE/C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;gBAClC,GAAG,EAAE,MAAM,CAAC,OAAO;gBACnB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG;gBAChC,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1D,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvB,OAAO;gBACP,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;oBACpD,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE;oBACtC,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;YAEH,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,6DAA6D;gBAC7D,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC5D,OAAO;YACT,CAAC;YAED,IAAI,KAAK,CAAC,WAAW;gBAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAEpD,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAEtG,IACE,IAAI,KAAK,SAAS;gBAClB,OAAO,CAAC,OAAO,KAAK,OAAO;gBAC3B,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,eAAe,CAAC,EAC3C,CAAC;gBACD,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC;gBACxB,MAAM,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBACjC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;gBAC3E,OAAO;YACT,CAAC;YAED,oEAAoE;YACpE,sEAAsE;YACtE,qDAAqD;YACrD,IAAI,CAAC,OAAO,CAAC,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gEAAgE;YAChE,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,4CAA4C,CAAC,CAAC;gBACnF,GAAG,CAAC,SAAS,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;YACD,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,OAAO,GAAwB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACxE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+/** Verdict actions, mirroring §9.2. */
+export type Action = 'allow' | 'notify' | 'challenge' | 'block';
+export interface Verdict {
+    verdict: Action;
+    action: Action;
+    score: number;
+    breakdown: Record<string, number>;
+    rulesTripped: string[];
+    requestId: string;
+    ttl: number;
+    cached: boolean;
+    shortCircuited: boolean;
+}
+/** What the middleware attaches to each request. */
+export interface BotShieldContext {
+    verdict: Action;
+    score: number;
+    requestId: string;
+    /** True when the verdict came from a cache (gateway header or local cache). */
+    cached: boolean;
+    /**
+     * Reports a business event (§6.1). Fire-and-forget: it never throws and never
+     * delays the response. The /events endpoint this targets arrives in Phase 3.
+     */
+    record(event: string, attributes: Record<string, unknown>): void;
+}
+export interface BotShieldConfig {
+    engineUrl: string;
+    appName: string;
+    /** `shadow` observes only; `enforce` permits block/challenge. */
+    mode?: 'shadow' | 'enforce';
+    protectedRoutes?: string[];
+    /** Overrides the sensor cookie name the SDK reads the fingerprint from. */
+    fingerprintCookie?: string;
+    /** Bounded time budget for the engine call, ms. */
+    timeoutMs?: number;
+    /** Entries retained in the in-process verdict cache. */
+    cacheMaxEntries?: number;
+    onVerdict?: (context: BotShieldContext, req: Request) => void;
+    logger?: {
+        warn(obj: unknown, msg?: string): void;
+        error(obj: unknown, msg?: string): void;
+    };
+}
+declare module 'express-serve-static-core' {
+    interface Request {
+        botshield?: BotShieldContext;
+    }
+}
+export type BotShieldMiddleware = RequestHandler & {
+    /** Exposed for tests. */
+    readonly client: {
+        verify(input: VerifyRequest): Promise<Verdict | null>;
+    };
+};
+export interface VerifyRequest {
+    app: string;
+    method: string;
+    path: string;
+    ip: string;
+    /** Forwarded so userId-scoped exemptions can be enforced server-side. */
+    userId?: string;
+    fingerprint?: string;
+    sessionId?: string;
+    ja4?: string;
+    headers: Record<string, string>;
+    timing?: {
+        pageLoadTs?: number;
+        submitTs?: number;
+    };
+}
+export type { NextFunction, Request, RequestHandler, Response };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/E,uCAAuC;AACvC,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC9F;AAED,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,OAAO;QACf,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAC9B;CACF;AAED,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG;IACjD,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;KAAE,CAAC;CAC5E,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "botshield-express",
+  "version": "0.1.0",
+  "description": "Drop-in Express middleware for BotShield — reads gateway verdicts, scores via the engine, fails open",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "4.17.25",
+    "@types/node": "20.19.43",
+    "@types/supertest": "7.2.1",
+    "express": "4.22.3",
+    "supertest": "7.2.2",
+    "vitest": "2.1.9"
+  }
+}