@arcis/node 1.4.3 → 1.5.0

package/dist/middleware/koa.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module @arcis/node/koa
+ *
+ * Koa adapter for Arcis. Returns a Koa middleware function suitable for
+ * `app.use(...)`. Rate-limit + bot detection run BEFORE `next()` (the
+ * handler); security headers are applied AFTER `next()` so they ride on
+ * the buffered response that Koa flushes on its own.
+ *
+ * ```ts
+ * import Koa from 'koa';
+ * import { arcisKoa } from '@arcis/node/koa';
+ *
+ * const app = new Koa();
+ * app.use(arcisKoa({
+ *   rateLimit: { max: 100, windowMs: 60_000 },
+ *   bot: true,
+ * }));
+ * app.use(async (ctx) => { ctx.body = { ok: true }; });
+ * app.listen(3000);
+ * ```
+ *
+ * No runtime dependency on `koa` — its types are duck-typed enough to
+ * satisfy Koa's actual `Context` shape. Real `Context` is assignable
+ * into `KoaContextLike` without imports.
+ */
+import type { HeaderOptions, RateLimitOptions } from '../core/types';
+import { type BotProtectionOptions } from './bot-detection';
+export interface KoaRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    url?: string;
+    method?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+export interface KoaResponseLike {
+    status: number;
+    body: unknown;
+    set(name: string, value: string): void;
+}
+export interface KoaContextLike {
+    request: KoaRequestLike;
+    response: KoaResponseLike;
+    /**
+     * Koa attaches IP at `ctx.ip` (delegating to `ctx.request.ip`). We read
+     * either; whichever is set wins.
+     */
+    ip?: string;
+    /** `ctx.set` shortcuts to `ctx.response.set` in real Koa. */
+    set(name: string, value: string): void;
+    /** Setting `ctx.status` shortcuts to `ctx.response.status`. */
+    status: number;
+    /** Setting `ctx.body` shortcuts to `ctx.response.body`. */
+    body: unknown;
+}
+export type KoaNext = () => Promise<unknown>;
+export type KoaMiddleware = (ctx: KoaContextLike, next: KoaNext) => Promise<void>;
+export interface ArcisKoaOptions {
+    /** 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 Koa middleware that applies Arcis protections on each request:
+ * rate-limit (returns 429 if exceeded), bot detection (returns
+ * `botStatusCode` if denied), then `await next()`, then security headers
+ * on the buffered response. Order matches the SvelteKit / Fastify /
+ * Next.js adapters so cross-framework behavior is consistent.
+ *
+ * Setting `ctx.status` and `ctx.body` before returning is Koa's idiomatic
+ * way to short-circuit a response — we don't call `next()` on the deny
+ * path so downstream middleware doesn't run.
+ */
+export declare function arcisKoa(options?: ArcisKoaOptions): KoaMiddleware;
+export default arcisKoa;
+//# sourceMappingURL=koa.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"koa.d.ts","sourceRoot":"","sources":["../../src/middleware/koa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EACV,aAAa,EAEb,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAMzB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAC7C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAIlF,MAAM,WAAW,eAAe;IAC9B,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;AAgKD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,aAAa,CAkErE;AAED,eAAe,QAAQ,CAAC"}

package/dist/middleware/main.d.ts

@@ -3,36 +3,6 @@
  * Main arcis() middleware factory
  */
 import type { ArcisOptions, ArcisFunction, ArcisMiddlewareStack } from '../core/types';
-/**
- * Create Arcis middleware with all protections enabled.
- *
- * @param options - Configuration options
- * @returns Array of Express middleware
- *
- * @example
- * // Full protection (recommended)
- * app.use(arcis());
- *
- * @example
- * // Custom configuration
- * app.use(arcis({
- *   rateLimit: { max: 50 },
- *   headers: { frameOptions: 'SAMEORIGIN' }
- * }));
- *
- * @example
- * // Disable specific features
- * app.use(arcis({
- *   rateLimit: false,
- *   sanitize: { sql: false }
- * }));
- *
- * @example
- * // Cleanup on shutdown
- * const middleware = arcis();
- * app.use(middleware);
- * process.on('SIGTERM', () => middleware.close());
- */
 export declare function arcis(options?: ArcisOptions): ArcisMiddlewareStack;
 declare const arcisWithMethods: ArcisFunction;
 export { arcisWithMethods as arcisFunction };

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/middleware/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,oBAAoB,EAIrB,MAAM,eAAe,CAAC;AAwCvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,oBAAoB,CAyDtE;AAGD,QAAA,MAAM,gBAAgB,EAAY,aAAa,CAAC;AAQhD,OAAO,EAAE,gBAAgB,IAAI,aAAa,EAAE,CAAC;AAC7C,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/middleware/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,oBAAoB,EAKrB,MAAM,eAAe,CAAC;AA8KvB,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,oBAAoB,CA6EtE;AAGD,QAAA,MAAM,gBAAgB,EAAY,aAAa,CAAC;AAQhD,OAAO,EAAE,gBAAgB,IAAI,aAAa,EAAE,CAAC;AAC7C,eAAe,gBAAgB,CAAC"}

package/dist/middleware/mass-assign.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module @arcis/node/middleware/mass-assign
+ *
+ * Mass-assignment runtime guard (sdk-vectors.md tier 1 #25).
+ *
+ * The classic mass-assignment vulnerability:
+ *
+ * ```js
+ * const user = await User.findOne({ id });
+ * Object.assign(user, req.body);  // attacker sets req.body.is_admin = true
+ * await user.save();
+ * ```
+ *
+ * This middleware filters `req.body` to a per-route allowlist before
+ * the handler runs. Two modes:
+ *
+ * - `'strip'` (default) — silently drop disallowed keys, continue.
+ * - `'reject'` — return 400 with the offending key names.
+ *
+ * Pair it with the audit rule (`MASS-ASSIGN` in `arcis audit`) for the
+ * static-analysis side and the route-level middleware for the runtime
+ * side. Audit catches `Object.assign(target, req.body)` patterns at
+ * build time; this middleware catches the runtime data flow.
+ *
+ * ```ts
+ * import { massAssign } from '@arcis/node';
+ *
+ * app.post('/users',
+ *   massAssign({ allow: ['email', 'password', 'name'] }),
+ *   async (req, res) => {
+ *     // req.body has been filtered — is_admin / role / created_at all gone.
+ *     const user = await User.create(req.body);
+ *     res.json(user);
+ *   },
+ * );
+ * ```
+ *
+ * Default scope is top-level keys only. Nested objects pass through
+ * untouched — that's deliberate: nested allowlists encourage
+ * `allow: ['profile.bio', 'profile.avatar']` style strings which
+ * become a parser, not a guard. Use a schema validator (Zod / Joi /
+ * Arcis's `validate`) when nested filtering is required; this
+ * middleware handles the 80% case of "filter req.body for an ORM
+ * mass-assign call".
+ */
+import type { RequestHandler } from 'express';
+export interface MassAssignOptions {
+    /**
+     * Allowlist of permitted top-level keys on `req.body`. Required —
+     * a missing or empty array would silently strip every key, almost
+     * certainly a configuration mistake.
+     */
+    allow: readonly string[];
+    /**
+     * Behavior when `req.body` contains a key NOT in `allow`:
+     *   - `'strip'` (default): silently drop the key, continue.
+     *   - `'reject'`: return `statusCode` (default 400) with a JSON
+     *     body listing the disallowed keys.
+     */
+    mode?: 'strip' | 'reject';
+    /** Status code for the reject path. Default: 400. */
+    statusCode?: number;
+    /** Error message in the reject body. Default: "Disallowed fields". */
+    message?: string;
+    /**
+     * Skip the filter when `req.body` is not a plain object (string,
+     * array, FormData, etc.). Default: true. Set to false to surface
+     * a 400 ("body must be an object") on those payloads — useful for
+     * routes that should ONLY accept JSON objects.
+     */
+    passThroughNonObjects?: boolean;
+}
+/**
+ * Build a mass-assignment guard middleware. Runs against `req.body`
+ * before the route handler — must be installed AFTER body-parsing
+ * middleware (`express.json()` / `express.urlencoded()`) so `req.body`
+ * is already populated.
+ */
+export declare function massAssign(options: MassAssignOptions): RequestHandler;
+export default massAssign;
+//# sourceMappingURL=mass-assign.d.ts.map

package/dist/middleware/mass-assign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mass-assign.d.ts","sourceRoot":"","sources":["../../src/middleware/mass-assign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAW,cAAc,EAA0B,MAAM,SAAS,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AASD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAgFrE;AAED,eAAe,UAAU,CAAC"}

package/dist/middleware/method-allowlist.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module @arcis/node/middleware/method-allowlist
+ *
+ * HTTP method tampering protection (sdk-vectors.md tier 1 #26).
+ *
+ * Two related threats:
+ *
+ * 1. **Disallowed methods** — TRACE leaks Authorization headers (XST);
+ *    CONNECT is for proxies and shouldn't reach an application server;
+ *    custom verbs slip past route-handlers that only check `if (req.method
+ *    === 'POST')`. The middleware rejects anything outside an allowlist
+ *    with 405.
+ *
+ * 2. **Method-override bypass** — frameworks that respect
+ *    `X-HTTP-Method-Override` let an attacker turn a GET into a POST or
+ *    DELETE, bypassing route-level method checks. The middleware strips
+ *    these headers BEFORE the route handler sees them.
+ *
+ * Pair with the bundle middleware:
+ *
+ * ```ts
+ * import { arcis } from '@arcis/node';
+ * import { methodAllowlist } from '@arcis/node/middleware/method-allowlist';
+ *
+ * app.use(methodAllowlist());
+ * app.use(arcis());
+ * ```
+ *
+ * Or standalone for fine-grained mounts:
+ *
+ * ```ts
+ * app.use('/api', methodAllowlist({ allow: ['GET', 'POST'] }));
+ * ```
+ */
+import type { RequestHandler } from 'express';
+export interface MethodAllowlistOptions {
+    /**
+     * Methods to permit. Each entry is uppercased before comparison so
+     * `['get', 'post']` works the same as `['GET', 'POST']`. Defaults to
+     * the full standard CRUD set: GET, POST, PUT, DELETE, HEAD, OPTIONS,
+     * PATCH. TRACE and CONNECT are intentionally excluded — the former
+     * leaks Authorization (XST), the latter is for proxies.
+     */
+    allow?: readonly string[];
+    /**
+     * Strip method-override headers (`X-HTTP-Method-Override`,
+     * `X-Method-Override`, `X-HTTP-Method`) before the request reaches the
+     * route handler. Default: true. Set to false only if your stack
+     * legitimately uses one of these headers for client-method tunnelling
+     * AND you've verified each override target is auth-checked
+     * independently.
+     */
+    stripOverrideHeaders?: boolean;
+    /** HTTP status code for the deny response. Default: 405 Method Not Allowed. */
+    statusCode?: number;
+    /** Error message body. Default: "Method not allowed". */
+    message?: string;
+}
+/**
+ * Build a method-allowlist middleware. Uppercase-matches `req.method`
+ * against the allow set; strips override headers so downstream code
+ * can't be tricked into running a different method's logic.
+ */
+export declare function methodAllowlist(options?: MethodAllowlistOptions): RequestHandler;
+export default methodAllowlist;
+//# sourceMappingURL=method-allowlist.d.ts.map

package/dist/middleware/method-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-allowlist.d.ts","sourceRoot":"","sources":["../../src/middleware/method-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAuB9C,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CAgCpF;AAED,eAAe,eAAe,CAAC"}

package/dist/middleware/nestjs.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module @arcis/node/nestjs
+ *
+ * NestJS adapter for Arcis.
+ *
+ * Two ways to wire this up:
+ *
+ * 1. Global functional middleware (zero NestJS knowledge required):
+ *    ```ts
+ *    // main.ts
+ *    import { NestFactory } from '@nestjs/core';
+ *    import { arcis } from '@arcis/node';
+ *    const app = await NestFactory.create(AppModule);
+ *    app.use(arcis({ block: true }));
+ *    ```
+ *
+ * 2. DI-aware module + class middleware (per-route control):
+ *    ```ts
+ *    // app.module.ts
+ *    import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+ *    import { ArcisModule, ArcisMiddleware } from '@arcis/node/nestjs';
+ *
+ *    @Module({ imports: [ArcisModule.forRoot({ block: true })] })
+ *    export class AppModule implements NestModule {
+ *      configure(consumer: MiddlewareConsumer) {
+ *        consumer.apply(ArcisMiddleware).forRoutes('*');
+ *      }
+ *    }
+ *    ```
+ *
+ * No runtime dependency on `@nestjs/common`: the only NestJS reference is a
+ * type-only import erased at compile time. NestJS users already have
+ * `@nestjs/common` installed; non-NestJS users pay nothing.
+ */
+import type { Request, Response, NextFunction } from 'express';
+import type { DynamicModule } from '@nestjs/common';
+import type { ArcisOptions } from '../core/types';
+/** Injection token for `ArcisOptions` consumed by `ArcisMiddleware`'s factory. */
+export declare const ARCIS_OPTIONS: unique symbol;
+/**
+ * NestJS-compatible class middleware. Implements the structural shape NestJS
+ * expects (`.use(req, res, next)`) without importing `NestMiddleware` at
+ * runtime. Internally builds the same handler stack as `arcis()` and walks it
+ * sequentially, propagating errors and short-circuit responses correctly.
+ */
+export declare class ArcisMiddleware {
+    private readonly handlers;
+    constructor(options?: ArcisOptions);
+    use(req: Request, res: Response, next: NextFunction): void;
+    /** Release rate-limiter intervals etc. Call from `OnApplicationShutdown`. */
+    close(): void;
+}
+/**
+ * NestJS dynamic module. `ArcisModule.forRoot(options)` is the entry point.
+ * Returns a plain `DynamicModule` literal so `@Module({})` is unnecessary on
+ * `ArcisModule` itself; this keeps `@nestjs/common` purely a type-only import.
+ */
+export declare class ArcisModule {
+    static forRoot(options?: ArcisOptions): DynamicModule;
+}
+export default ArcisModule;
+//# sourceMappingURL=nestjs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.d.ts","sourceRoot":"","sources":["../../src/middleware/nestjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAkB,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAwB,MAAM,eAAe,CAAC;AAExE,kFAAkF;AAClF,eAAO,MAAM,aAAa,eAA0B,CAAC;AAErD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;gBAEpC,OAAO,GAAE,YAAiB;IAItC,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAsB1D,6EAA6E;IAC7E,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,YAAiB,GAAG,aAAa;CAc1D;AAED,eAAe,WAAW,CAAC"}

package/dist/middleware/nextjs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @module @arcis/node/nextjs
+ *
+ * Next.js adapter for Arcis. Two entry points covering the modern Next.js
+ * stack (Edge Middleware + App Router route handlers):
+ *
+ * **1. Edge Middleware (`middleware.ts` at the project root):**
+ *
+ * ```ts
+ * import { arcisMiddleware } from '@arcis/node/nextjs';
+ * import { NextResponse } from 'next/server';
+ *
+ * const arcis = arcisMiddleware({
+ *   rateLimit: { max: 100, windowMs: 60_000 },
+ *   bot: true,
+ * });
+ *
+ * export default async function middleware(request: Request) {
+ *   const blocked = await arcis(request);
+ *   if (blocked) return blocked;
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * The returned function inspects the request and returns either:
+ *   - a `Response` (rate-limited 429 / bot-blocked 403) to short-circuit, or
+ *   - `undefined` to let the request proceed.
+ *
+ * The caller decides what "proceed" means — `NextResponse.next()` for Edge
+ * Middleware, or a re-thrown handler call for custom plumbing. Keeping the
+ * allow-path explicit avoids importing `next/server` from the adapter.
+ *
+ * **2. App Router route handlers (`app/api/.../route.ts`):**
+ *
+ * ```ts
+ * import { arcisProtect } from '@arcis/node/nextjs';
+ *
+ * export const POST = arcisProtect(
+ *   async (request: Request) => Response.json({ ok: true }),
+ *   { rateLimit: { max: 100 }, bot: true },
+ * );
+ * ```
+ *
+ * The wrapper runs the same allow / deny pipeline as `arcisMiddleware`,
+ * then on the allow path calls the handler, mutates the resulting
+ * Response's headers with security defaults, and returns it.
+ *
+ * Pages-router API routes (`pages/api/...`) use Node-style req/res rather
+ * than the Web Fetch shape; for those, drop the standard Express adapter
+ * (`arcis()` from the package root) into `app.use(...)` of a custom server,
+ * or migrate to the App Router for first-party support.
+ *
+ * No runtime dependency on `next` — the adapter speaks Web Fetch
+ * `Request`/`Response` directly. NextRequest extends Request and
+ * NextResponse extends Response, so both are assignable into / out of this
+ * surface without imports.
+ */
+import type { HeaderOptions, RateLimitOptions } from '../core/types';
+import { type BotProtectionOptions } from './bot-detection';
+export interface ArcisNextOptions {
+    /** 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 Next.js Edge Middleware factory. The returned function runs the
+ * Arcis allow / deny pipeline against the request and returns a `Response`
+ * to short-circuit OR `undefined` to indicate "let the request proceed."
+ *
+ * The caller is responsible for the proceed-path (typically
+ * `NextResponse.next()` from `next/server`). This split keeps the adapter
+ * dependency-free of `next/server` while preserving clean Edge Middleware
+ * ergonomics.
+ *
+ * Security headers are NOT applied here — Edge Middleware can't easily
+ * mutate the response body's headers without consuming the body. For
+ * security-headers-on-response, use `arcisProtect` on the route handler.
+ */
+export declare function arcisMiddleware(options?: ArcisNextOptions): (request: Request) => Promise<Response | undefined>;
+/**
+ * Wrap an App Router route handler with the Arcis pipeline. Runs rate-limit
+ * + bot checks BEFORE the handler, then security headers on the response
+ * AFTER. The `...args` spread preserves the second-arg shape route handlers
+ * receive, e.g. `(request, { params })` for dynamic routes.
+ *
+ * ```ts
+ * export const GET = arcisProtect(
+ *   async (request, { params }) => Response.json({ id: params.id }),
+ *   { rateLimit: { max: 50 } },
+ * );
+ * ```
+ */
+export declare function arcisProtect<TArgs extends unknown[]>(handler: (request: Request, ...args: TArgs) => Promise<Response> | Response, options?: ArcisNextOptions): (request: Request, ...args: TArgs) => Promise<Response>;
+export default arcisMiddleware;
+//# sourceMappingURL=nextjs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/middleware/nextjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAIH,OAAO,KAAK,EACV,aAAa,EAEb,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAIzB,MAAM,WAAW,gBAAgB;IAC/B,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;AA4PD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,gBAAqB,GAC7B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAMrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,SAAS,OAAO,EAAE,EAClD,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,EAC3E,OAAO,GAAE,gBAAqB,GAC7B,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,QAAQ,CAAC,CAezD;AAED,eAAe,eAAe,CAAC"}

package/dist/middleware/nuxt.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module @arcis/node/nuxt
+ *
+ * Nuxt (h3) adapter for Arcis. Drop into a server middleware file:
+ *
+ * ```ts
+ * // server/middleware/arcis.ts
+ * import { defineEventHandler } from 'h3';
+ * import { arcisHandler } from '@arcis/node/nuxt';
+ * export default defineEventHandler(arcisHandler({ rateLimit: { max: 100 } }));
+ * ```
+ *
+ * Or compose with other handlers — each Nuxt server middleware file runs in
+ * the order Nitro discovers them (alphabetical by default).
+ *
+ * The adapter operates against h3's Node-compat layer (`event.node.req` /
+ * `event.node.res`) so it works on the standard Nuxt server. There is no
+ * runtime dependency on `h3` — its event shape is duck-typed.
+ */
+import type { HeaderOptions, RateLimitOptions } from '../core/types';
+import { type BotProtectionOptions } from './bot-detection';
+interface NodeIncomingMessageLike {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    method?: string;
+    url?: string;
+}
+interface NodeServerResponseLike {
+    statusCode: number;
+    writableEnded?: boolean;
+    setHeader(name: string, value: string | number | string[]): void;
+    removeHeader(name: string): void;
+    end(body?: string): void;
+}
+export interface H3EventLike {
+    node: {
+        req: NodeIncomingMessageLike;
+        res: NodeServerResponseLike;
+    };
+}
+export type ArcisH3Handler = (event: H3EventLike) => Promise<void> | void;
+export interface ArcisNuxtOptions {
+    /** 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). */
+    bot?: boolean | BotProtectionOptions;
+}
+/**
+ * Build an h3 event handler that applies Arcis protections on each request.
+ * Wrap it with `defineEventHandler` in your Nuxt server middleware. When a
+ * request is rate-limited or denied, the handler writes the 429/403 response
+ * directly via `event.node.res` and returns; otherwise it sets security
+ * headers and falls through to the next handler.
+ */
+export declare function arcisHandler(options?: ArcisNuxtOptions): ArcisH3Handler;
+export default arcisHandler;
+//# sourceMappingURL=nuxt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.d.ts","sourceRoot":"","sources":["../../src/middleware/nuxt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EACV,aAAa,EAEb,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,iBAAiB,CAAC;AAIzB,UAAU,uBAAuB;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,UAAU,sBAAsB;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACjE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE;QACJ,GAAG,EAAE,uBAAuB,CAAC;QAC7B,GAAG,EAAE,sBAAsB,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAI1E,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAClC,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,kDAAkD;IAClD,GAAG,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACtC;AA8HD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,cAAc,CA8D3E;AAED,eAAe,YAAY,CAAC"}

package/dist/middleware/overload.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module @arcis/node/middleware/overload
+ *
+ * Event-loop overload protection (sdk-vectors.md tier 1 #30, issue #51).
+ *
+ * Rate limiting caps per-client load; this middleware caps **total server
+ * load** by sampling event-loop lag and shedding new requests with 503
+ * when the loop is saturated. Pairs with rate-limit (per-client) +
+ * `methodAllowlist` (per-route) to give Arcis three orthogonal layers
+ * of "this server is healthy enough to do work" gating.
+ *
+ * ```ts
+ * import { eventLoopProtection } from '@arcis/node';
+ *
+ * app.use(eventLoopProtection({
+ *   maxLagMs: 500,         // 503 above this smoothed lag
+ *   sampleIntervalMs: 250, // measure every 250ms
+ * }));
+ * ```
+ *
+ * Sampling strategy:
+ *   - `setInterval(fn, sampleIntervalMs)` is scheduled; the callback
+ *     compares wall-clock elapsed against the configured interval. Lag
+ *     IS the difference: when the loop is busy, the timer fires late.
+ *   - The interval handle is `.unref()`-ed so the process can exit
+ *     cleanly even if the caller forgets to call `close()`.
+ *   - Exponential moving average (`smoothed = 0.7 * smoothed + 0.3 *
+ *     measured`) smooths out single-sample spikes — a 600ms GC pause
+ *     shouldn't cause every request to 503 for the next sample window.
+ *
+ * Implementation deliberately picks `setTimeout` measurement over
+ * `perf_hooks.monitorEventLoopDelay` (Node 12+ alternative) for two
+ * reasons: (1) it works on every supported Node version with no feature
+ * detection branch, (2) the perf_hooks histogram returns nanosecond
+ * lag from a 10ms-resolution sampler, but applying the spec's EMA
+ * formula on that signal would skew toward unreal lag values that the
+ * sampler smoothed away. Keeping the sampler the spec calls for keeps
+ * the math testable.
+ */
+import type { RequestHandler } from 'express';
+export interface EventLoopProtectionOptions {
+    /** Smoothed lag threshold in ms above which the middleware returns 503. Default: 500. */
+    maxLagMs?: number;
+    /** Sample frequency in ms. Default: 250. Lower = more responsive, higher = less overhead. */
+    sampleIntervalMs?: number;
+    /** Status code to return when overloaded. Default: 503. */
+    statusCode?: number;
+    /** Error message in the response body. Default: "Server overloaded, please retry". */
+    message?: string;
+    /** Retry-After header value in seconds. Default: 5. */
+    retryAfterSeconds?: number;
+    /**
+     * EMA smoothing factor for the new measurement. Default: 0.3 (per
+     * issue #51 spec). Must be in (0, 1]; lower values smooth harder
+     * (longer memory of past samples), higher values track more reactively.
+     */
+    alpha?: number;
+    /**
+     * When true, every response gets `X-EventLoop-Lag: <ms>` so monitoring
+     * can graph saturation independent of the deny decision. Off by default
+     * because most apps don't need it and an extra header on every response
+     * adds noise.
+     */
+    exposeLagHeader?: boolean;
+}
+export interface EventLoopProtectionMiddleware extends RequestHandler {
+    /**
+     * Stop the sampler. Call from a SIGTERM handler so the interval doesn't
+     * keep a misconfigured process alive. Idempotent: subsequent calls are
+     * no-ops.
+     */
+    close(): void;
+    /**
+     * Read the current smoothed lag in ms. Useful for tests that want to
+     * assert the smoothing math without mocking timers, and for callers
+     * who want to expose the value through a different surface (Prometheus,
+     * dashboard panel, etc.).
+     */
+    currentLagMs(): number;
+}
+/**
+ * Build an event-loop protection middleware. Returns a request handler
+ * with `close()` and `currentLagMs()` attached (Pattern 6 in the
+ * monorepo's middleware conventions: factories return a callable
+ * augmented with cleanup helpers).
+ */
+export declare function eventLoopProtection(options?: EventLoopProtectionOptions): EventLoopProtectionMiddleware;
+export default eventLoopProtection;
+export declare const __test: {
+    ema(prior: number, measured: number, alpha: number): number;
+};
+//# sourceMappingURL=overload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overload.d.ts","sourceRoot":"","sources":["../../src/middleware/overload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,0BAA0B;IACzC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA8B,SAAQ,cAAc;IACnE;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;IACd;;;;;OAKG;IACH,YAAY,IAAI,MAAM,CAAC;CACxB;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAoE/B;AAED,eAAe,mBAAmB,CAAC;AAInC,eAAO,MAAM,MAAM;eACN,MAAM,YAAY,MAAM,SAAS,MAAM,GAAG,MAAM;CAG5D,CAAC"}