@arcis/node 1.4.4 → 1.5.0

package/dist/middleware/protect.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module @arcis/node/middleware/protect
+ *
+ * Composite protection helpers (issue #52). Pre-configured middleware
+ * stacks for the three endpoint shapes that show up in every app:
+ * login, signup, generic API. Each helper composes EXISTING middleware
+ * with sensible defaults; no new security logic lives here.
+ *
+ * Express supports passing an array of middleware to a route — the
+ * elements get unrolled in declaration order — so each helper returns
+ * a `RequestHandler[]` that drops directly into `app.post(...)`:
+ *
+ * ```ts
+ * import { protectLogin, protectSignup, protectApi } from '@arcis/node';
+ *
+ * app.post('/login',  protectLogin(),  loginHandler);
+ * app.post('/signup', protectSignup(), signupHandler);
+ * app.use ('/api',    protectApi());
+ * ```
+ *
+ * Defaults (issue #52 spec):
+ *
+ * | Helper        | rate-limit | bot | csrf | cors | sanitize | email |
+ * |---------------|------------|-----|------|------|----------|-------|
+ * | protectLogin  | 5/min      | yes | yes  | -    | yes      | -     |
+ * | protectSignup | 3/min      | yes | -    | -    | yes      | yes   |
+ * | protectApi    | 100/min    | -   | -    | yes  | yes      | -     |
+ *
+ * Each option is overridable. Pass `{ rateLimit: false }` to disable a
+ * specific layer; pass an options object to forward to the underlying
+ * factory.
+ */
+import type { RequestHandler } from 'express';
+import { type BotProtectionOptions } from './bot-detection';
+import { type CsrfOptions } from './csrf';
+import type { CorsOptions } from './cors';
+import { type SignupProtectionOptions } from './signup-protection';
+import type { RateLimitOptions, SanitizeOptions } from '../core/types';
+/**
+ * Per-layer override knob: pass `false` to disable, an options object
+ * to merge into the layer's defaults, or omit to accept the helper's
+ * baked-in default.
+ */
+type LayerOverride<T> = false | T | undefined;
+export interface ProtectLoginOptions {
+    rateLimit?: LayerOverride<RateLimitOptions>;
+    bot?: LayerOverride<BotProtectionOptions>;
+    csrf?: LayerOverride<CsrfOptions>;
+    sanitize?: LayerOverride<SanitizeOptions>;
+}
+export interface ProtectSignupOptions {
+    rateLimit?: LayerOverride<RateLimitOptions>;
+    bot?: LayerOverride<BotProtectionOptions>;
+    sanitize?: LayerOverride<SanitizeOptions>;
+    /** signupProtection options (email-style validation, disposable-mail block, etc.). */
+    signup?: LayerOverride<SignupProtectionOptions>;
+}
+export interface ProtectApiOptions {
+    rateLimit?: LayerOverride<RateLimitOptions>;
+    /** CORS is required to take an Origin/Methods config — no default origin. */
+    cors?: LayerOverride<CorsOptions>;
+    sanitize?: LayerOverride<SanitizeOptions>;
+}
+/**
+ * Login endpoints get the strictest defaults: 5 req/min/IP, deny
+ * AUTOMATED bots, CSRF token check, and input sanitization. Designed
+ * for `app.post('/login', protectLogin(), handler)`.
+ */
+export declare function protectLogin(options?: ProtectLoginOptions): RequestHandler[];
+/**
+ * Signup endpoints: 3 req/min/IP, deny AUTOMATED bots, sanitize input,
+ * and run signup-specific validation (email shape + disposable-domain
+ * check via `signupProtection`). No CSRF here because most signup
+ * forms are first-touch, no prior session to anchor a token to.
+ */
+export declare function protectSignup(options?: ProtectSignupOptions): RequestHandler[];
+/**
+ * Generic API endpoints: 100 req/min/IP, CORS, input sanitization. No
+ * bot detection by default because legitimate API consumers (curl,
+ * fetch, server-to-server) are often classified AUTOMATED — opt-in
+ * by passing a `bot` override... wait, protectApi doesn't expose bot.
+ * That's deliberate per the issue spec table. Users who want bot
+ * detection on API endpoints compose `botProtection()` directly.
+ *
+ * CORS is the one layer with no usable default — every app's allow
+ * list is different. Pass `cors: { origin: '...' }` or `cors: false`
+ * to skip it explicitly.
+ */
+export declare function protectApi(options?: ProtectApiOptions): RequestHandler[];
+export {};
+//# sourceMappingURL=protect.d.ts.map

package/dist/middleware/protect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../../src/middleware/protect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAErF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEvE;;;;GAIG;AACH,KAAK,aAAa,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC1C,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC1C,sFAAsF;IACtF,MAAM,CAAC,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC5C,6EAA6E;IAC7E,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAC3C;AAaD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,cAAc,EAAE,CAoBhF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,EAAE,CAoBlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,EAAE,CAgB5E"}

package/dist/middleware/rate-limit-sliding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-sliding.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit-sliding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAI/E,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAOD,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,oBAAyB,GAAG,uBAAuB,CAiGtG"}
+{"version":3,"file":"rate-limit-sliding.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit-sliding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAI/E,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAOD,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,oBAAyB,GAAG,uBAAuB,CAwGtG"}

package/dist/middleware/rate-limit-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-token.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/E,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAOD,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CA2FhG"}
+{"version":3,"file":"rate-limit-token.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAG/E,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAOD,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CA4FhG"}

package/dist/middleware/rate-limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAkB,MAAM,eAAe,CAAC;AAO7F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,qBAAqB,CAuIvF;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,0BAAoB,CAAC"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAkB,MAAM,eAAe,CAAC;AAO7F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,qBAAqB,CAwIvF;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,0BAAoB,CAAC"}

package/dist/middleware/response-splitting.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module @arcis/node/middleware/response-splitting
+ *
+ * HTTP response splitting prevention (sdk-vectors.md tier 1 #27).
+ *
+ * Response splitting is the *output* counterpart to header injection: app
+ * code passes user input into `res.setHeader`, `res.writeHead`, or
+ * `res.appendHeader` (Node 17+) without stripping CR/LF, and an attacker
+ * uses the embedded newline to break out of the header block and forge a
+ * second response. Most often weaponised against `Location:` after a
+ * redirect that reflects user input (`/redirect?to=...`).
+ *
+ * `sanitizeHeaderValue` already covers the byte-level fix on the way in;
+ * this middleware wraps the response object so every header that leaves
+ * the app gets sanitised on the way out — even when the app forgets.
+ *
+ * ```ts
+ * import { responseSplittingGuard } from '@arcis/node/middleware/response-splitting';
+ *
+ * app.use(responseSplittingGuard());
+ *
+ * // Later — even this passes through clean:
+ * app.get('/r', (req, res) => res.redirect(req.query.to as string));
+ * ```
+ *
+ * Pair with `validateRedirect` for full coverage: this middleware blocks
+ * the response-splitting payload, `validateRedirect` blocks the
+ * open-redirect payload.
+ */
+import type { RequestHandler } from 'express';
+import { detectHeaderInjection, sanitizeHeaderValue } from '../sanitizers/headers';
+export interface ResponseSplittingGuardOptions {
+    /**
+     * What to do when an outgoing header value contains CR / LF / NUL.
+     *
+     * - `'strip'` (default) — silently sanitise the value before it reaches
+     *   the wire. Preserves availability; existing routes don't break.
+     * - `'reject'` — throw a `ResponseSplittingError`. Use in apps that
+     *   would rather fail-closed than emit a partial response.
+     *
+     * Both modes invoke `onDetect` if provided.
+     */
+    mode?: 'strip' | 'reject';
+    /**
+     * Per-detection callback. Fires before strip/reject. Useful for
+     * logging or alerting when an attempted split slips through into the
+     * response builder.
+     */
+    onDetect?: (header: string, originalValue: string) => void;
+}
+/**
+ * Thrown by `responseSplittingGuard({ mode: 'reject' })` when an
+ * outgoing header value contains CR / LF / NUL. The header name is in
+ * `header`; the originally attempted value is in `value` so it can be
+ * logged or surfaced in an error handler.
+ */
+export declare class ResponseSplittingError extends Error {
+    readonly header: string;
+    readonly value: string;
+    constructor(header: string, value: string);
+}
+/**
+ * Re-export under the response-splitting name. Same byte pattern as
+ * header injection (CR / LF / NUL) — different threat model: input
+ * boundary vs output boundary.
+ */
+export declare const detectResponseSplitting: typeof detectHeaderInjection;
+/**
+ * Re-export under the response-splitting name. Strips CR / LF / NUL.
+ */
+export declare const sanitizeResponseHeader: typeof sanitizeHeaderValue;
+/**
+ * Build the response-splitting guard middleware. Wraps `res.setHeader`,
+ * `res.writeHead`, and `res.appendHeader` (when present) on each
+ * incoming request so every header that leaves the app gets the same
+ * CRLF / NUL treatment regardless of which code path emitted it.
+ *
+ * Wrapping happens per-request (not on the prototype) so multiple
+ * mounts with different options don't trample each other.
+ */
+export declare function responseSplittingGuard(options?: ResponseSplittingGuardOptions): RequestHandler;
+export default responseSplittingGuard;
+//# sourceMappingURL=response-splitting.d.ts.map

package/dist/middleware/response-splitting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-splitting.d.ts","sourceRoot":"","sources":["../../src/middleware/response-splitting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEnF,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5D;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAM1C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,8BAAwB,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,sBAAsB,4BAAsB,CAAC;AAiB1D;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC,GAC1C,cAAc,CAoHhB;AAED,eAAe,sBAAsB,CAAC"}

package/dist/middleware/sveltekit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module @arcis/node/sveltekit
+ *
+ * SvelteKit adapter for Arcis. Returns a `Handle` factory you can drop into
+ * `src/hooks.server.ts`:
+ *
+ * ```ts
+ * import { arcisHandle } from '@arcis/node/sveltekit';
+ * export const handle = arcisHandle({ rateLimit: { max: 100 }, bot: true });
+ * ```
+ *
+ * Or compose with other handles via SvelteKit's own `sequence` helper:
+ *
+ * ```ts
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { arcisHandle } from '@arcis/node/sveltekit';
+ * export const handle = sequence(arcisHandle(), authHandle, loggingHandle);
+ * ```
+ *
+ * SvelteKit uses Web Fetch `Request`/`Response` objects, not Express
+ * `req`/`res`, so this adapter implements the Arcis pipeline natively against
+ * the Fetch API rather than wrapping `arcis()`. There is no runtime dependency
+ * on `@sveltejs/kit` — its types are imported only for compile-time checks.
+ */
+import type { HeaderOptions, RateLimitOptions } from '../core/types';
+import { type BotProtectionOptions } from './bot-detection';
+interface SvelteKitCookies {
+    get(name: string): string | undefined;
+    set(name: string, value: string, opts: {
+        path: string;
+        [k: string]: unknown;
+    }): void;
+    delete(name: string, opts: {
+        path: string;
+    }): void;
+}
+export interface SvelteKitRequestEvent {
+    request: Request;
+    url: URL;
+    cookies: SvelteKitCookies;
+    getClientAddress(): string;
+}
+export type SvelteKitResolve = (event: SvelteKitRequestEvent, opts?: unknown) => Promise<Response> | Response;
+export type SvelteKitHandle = (input: {
+    event: SvelteKitRequestEvent;
+    resolve: SvelteKitResolve;
+}) => Promise<Response>;
+export interface ArcisHandleOptions {
+    /** Security headers configuration. Default: enabled. Pass `false` to disable. */
+    headers?: boolean | HeaderOptions;
+    /** Rate limiter configuration. Default: 100 req/60s in-memory. Pass `false` to disable. */
+    rateLimit?: boolean | RateLimitOptions;
+    /**
+     * Bot protection. Default: disabled (opt-in to avoid surprising behavior on
+     * legitimate crawlers). Pass `true` for sensible defaults or an options
+     * object for full control.
+     */
+    bot?: boolean | BotProtectionOptions;
+}
+/**
+ * Build a SvelteKit `Handle` that applies Arcis protections in this order on
+ * each request: rate limit (returns 429 if exceeded), bot detection (returns
+ * 403 if the bot is in the deny list), then runs downstream `resolve(event)`,
+ * then mutates the resulting `Response`'s headers with security defaults.
+ */
+export declare function arcisHandle(options?: ArcisHandleOptions): SvelteKitHandle;
+export default arcisHandle;
+//# sourceMappingURL=sveltekit.d.ts.map

package/dist/middleware/sveltekit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sveltekit.d.ts","sourceRoot":"","sources":["../../src/middleware/sveltekit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EACV,aAAa,EAEb,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAMzB,UAAU,gBAAgB;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,gBAAgB,CAAC;IAC1B,gBAAgB,IAAI,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,qBAAqB,EAC5B,IAAI,CAAC,EAAE,OAAO,KACX,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;AAElC,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE;IACpC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,CAAC;CAC3B,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAIxB,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAClC,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACtC;AAgID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,eAAe,CAqE7E;AAED,eAAe,WAAW,CAAC"}

package/dist/middleware/token-budget.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module @arcis/node/middleware/token-budget
+ *
+ * Token-budget protection middleware. Caps per-key token spend over a
+ * sliding window — meant for routes that proxy LLM calls, where a tight
+ * 100-req/min rate limit isn't enough because a single 50KB prompt costs
+ * the same as 1000 small requests.
+ *
+ * @example
+ * import express from 'express';
+ * import { tokenBudget } from '@arcis/node';
+ *
+ * const guard = tokenBudget({
+ *   maxTokens: 100_000,            // 100K tokens per window
+ *   windowMs: 60 * 60 * 1000,      // 1-hour window
+ *   maxRequestTokens: 5_000,       // reject any single request over this
+ *   keyGenerator: (req) => req.user?.id ?? req.ip,
+ * });
+ *
+ * app.post('/chat', guard, chatHandler);
+ *
+ * The default token estimator is `Math.ceil(bytesOf(body+query) / 4)` —
+ * close to OpenAI's "1 token ≈ 4 English characters" rule. Override via
+ * `estimateTokens` for accurate counting (tiktoken, etc.).
+ */
+import type { Request, RequestHandler } from 'express';
+export interface TokenBudgetOptions {
+    /** Max tokens a single key can spend in one window. Default: 100,000. */
+    maxTokens?: number;
+    /** Window length in milliseconds. Default: 60 * 60 * 1000 (1 hour). */
+    windowMs?: number;
+    /**
+     * Max tokens a single request may consume. Requests over this size are
+     * rejected with 413 BEFORE counting against the window budget. Default:
+     * unset (no per-request cap).
+     */
+    maxRequestTokens?: number;
+    /**
+     * Function that returns the budget key for a request. Default: client IP
+     * (req.ip), falling back to `unknown` when unresolvable.
+     */
+    keyGenerator?: (req: Request) => string;
+    /**
+     * Function that estimates the number of tokens a request will consume.
+     * Default: `Math.ceil((req.body + req.query stringified bytes) / 4)`,
+     * which approximates OpenAI's "1 token ≈ 4 characters" rule. Override
+     * with tiktoken/accurate counting when you need precision.
+     */
+    estimateTokens?: (req: Request) => number;
+    /** Status code for budget-exceeded responses. Default: 429. */
+    statusCode?: number;
+    /** Status code for oversize-request rejections. Default: 413. */
+    statusCodeOversize?: number;
+    /** Error message when budget is exceeded. */
+    message?: string;
+    /** Error message when a single request exceeds maxRequestTokens. */
+    messageOversize?: string;
+    /** Skip budget enforcement for certain requests. */
+    skip?: (req: Request) => boolean;
+}
+export interface TokenBudgetMiddleware extends RequestHandler {
+    /** Release internal cleanup resources. */
+    close: () => void;
+    /** Inspect current usage for a key (read-only; for tests/telemetry). */
+    inspect: (key: string) => {
+        used: number;
+        resetTime: number;
+    } | null;
+}
+/**
+ * Build a token-budget middleware. See module-level JSDoc for usage.
+ */
+export declare function tokenBudget(options?: TokenBudgetOptions): TokenBudgetMiddleware;
+export default tokenBudget;
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/middleware/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../src/middleware/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IAC1C,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,0CAA0C;IAC1C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wEAAwE;IACxE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtE;AAwCD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CAkGnF;AAED,eAAe,WAAW,CAAC"}