@nifrajs/middleware 0.1.0-alpha.1

package/dist/token-auth.d.ts

@@ -0,0 +1,65 @@
+import { type NifraPlugin } from "@nifrajs/core";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` — it rejects unauthorized
+ * requests to **routes defined after it** with `401` (unless `optional`). Read the verified principal
+ * inside a handler/loader via {@link AuthPlugin.principal} (nullable) or
+ * {@link AuthPlugin.requirePrincipal} (throws `401` when absent). The principal is verified once per
+ * request and cached, so reading it is free.
+ *
+ * `beforeHandle` is **order-scoped**: place `app.use(auth)` before the routes it should guard. Hold the
+ * returned instance to read the principal (mirrors `@nifrajs/auth`'s `sessions.get(c)` and
+ * `@nifrajs/better-auth`'s `getSession(auth, req)`):
+ *
+ * ```ts
+ * const auth = bearer({ verify: (t) => lookupUser(t) }) // P = User (inferred)
+ * const app = server().use(auth).get("/me", (c) => auth.requirePrincipal(c.req))
+ * ```
+ */
+export type AuthPlugin<P> = NifraPlugin & {
+    /** The verified principal for this request, or `null` (no/invalid token in `optional` mode). */
+    principal(request: Request): P | null;
+    /** The verified principal, or **throws a `401` `Response`** when absent. */
+    requirePrincipal(request: Request): P;
+};
+export interface BearerOptions<P> {
+    /** Verify a bearer token → a principal (truthy) or `null`/`undefined` (rejected). May be async
+     * (DB/JWT lookup). For a constant-secret comparison, use a constant-time compare — never `===`. */
+    readonly verify: (token: string) => MaybePromise<P | null | undefined>;
+    /** When `true`, requests without a valid token pass through (`principal` is `null`) instead of `401`. */
+    readonly optional?: boolean;
+    /** `realm` for the `WWW-Authenticate: Bearer` header on `401`. Default `"api"`. */
+    readonly realm?: string;
+}
+/**
+ * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
+ * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
+ * verified principal is read via the returned instance — see {@link AuthPlugin}.
+ */
+export declare function bearer<P>(options: BearerOptions<P>): AuthPlugin<P>;
+export interface ApiKeyVerifyOptions<P> {
+    /** Verify an API key → a principal or `null`/`undefined` (rejected). May be async. */
+    readonly verify: (key: string) => MaybePromise<P | null | undefined>;
+    /** Header carrying the key. Default `"x-api-key"`. */
+    readonly header?: string;
+    readonly optional?: boolean;
+}
+export interface ApiKeyStaticOptions {
+    /** A fixed set of valid keys. Compared in **constant time** (see below); the matched key becomes the
+     * principal. Use `verify` instead for DB-backed / per-tenant keys. */
+    readonly keys: readonly string[];
+    readonly header?: string;
+    readonly optional?: boolean;
+}
+/**
+ * API-key authentication via a header (default `x-api-key`). Two forms:
+ * - `apiKey({ keys })` — a fixed key set, compared in **constant time**; the matched key is the principal.
+ * - `apiKey({ verify })` — custom (e.g. DB-backed) verification returning a typed principal.
+ *
+ * Rejects missing/invalid keys with `401` (unless `optional`). Read the principal via the returned
+ * instance — see {@link AuthPlugin}.
+ */
+export declare function apiKey(options: ApiKeyStaticOptions): AuthPlugin<string>;
+export declare function apiKey<P>(options: ApiKeyVerifyOptions<P>): AuthPlugin<P>;
+export {};
+//# sourceMappingURL=token-auth.d.ts.map

package/dist/token-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.d.ts","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAE9D,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,WAAW,GAAG;IACxC,gGAAgG;IAChG,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,CAAA;IACrC,4EAA4E;IAC5E,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAA;CACtC,CAAA;AA8CD,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B;uGACmG;IACnG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACtE,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAYlE;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,YAAY,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACpE,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC;0EACsE;IACtE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAoCD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;AACxE,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA"}

package/dist/token-auth.js

@@ -0,0 +1,90 @@
+import { definePlugin } from "@nifrajs/core";
+function createTokenAuth(config) {
+    // Per-request principal cache: verify runs once (in beforeHandle), reads are free + can't desync.
+    const store = new WeakMap();
+    const reject = () => Response.json({ ok: false, error: "unauthorized" }, {
+        status: 401,
+        headers: config.challenge !== undefined ? { "www-authenticate": config.challenge } : {},
+    });
+    const plugin = definePlugin(config.name, (app) => app.beforeHandle(async (c) => {
+        const token = config.extract(c.req);
+        // Empty string is treated as "no credential" — never passed to verify.
+        const principal = token !== undefined && token !== "" ? await config.verify(token) : null;
+        if (principal !== null && principal !== undefined) {
+            store.set(c.req, principal);
+            return undefined; // authorized — continue to the handler
+        }
+        return config.optional ? undefined : reject(); // 401 short-circuits (skips the handler)
+    }));
+    return Object.assign(plugin, {
+        principal: (request) => store.get(request) ?? null,
+        requirePrincipal: (request) => {
+            const principal = store.get(request);
+            if (principal === undefined)
+                throw reject();
+            return principal;
+        },
+    });
+}
+/**
+ * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
+ * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
+ * verified principal is read via the returned instance — see {@link AuthPlugin}.
+ */
+export function bearer(options) {
+    const realm = options.realm ?? "api";
+    return createTokenAuth({
+        name: "bearer",
+        extract: (request) => {
+            const header = request.headers.get("authorization");
+            return header?.startsWith("Bearer ") === true ? header.slice(7).trim() : undefined;
+        },
+        verify: options.verify,
+        optional: options.optional === true,
+        challenge: `Bearer realm="${realm}"`,
+    });
+}
+const textEncoder = new TextEncoder();
+async function sha256(input) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", textEncoder.encode(input)));
+}
+/** Constant-time byte compare. Inputs here are always 32-byte SHA-256 digests, so the early
+ * length check never leaks key length (digests are fixed-width). */
+function timingSafeEqualBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+    return diff === 0;
+}
+/**
+ * Build a constant-time verifier for a fixed key set. Each valid key is hashed once (SHA-256, fixed
+ * 32 bytes); per request the candidate is hashed and compared against every digest **without early
+ * exit**, so timing depends only on the (public) key count — never on the secret value or which key
+ * matched. Portable across all runtimes via WebCrypto.
+ */
+function staticKeyVerify(keys) {
+    const validDigests = Promise.all(keys.map((key) => sha256(key)));
+    return async (candidate) => {
+        const candidateDigest = await sha256(candidate);
+        let matched = false;
+        for (const digest of await validDigests) {
+            // No early `break`: every comparison runs so total time is independent of which key (if any) hit.
+            if (timingSafeEqualBytes(candidateDigest, digest))
+                matched = true;
+        }
+        return matched ? candidate : null;
+    };
+}
+export function apiKey(options) {
+    const header = (options.header ?? "x-api-key").toLowerCase();
+    const verify = "keys" in options ? staticKeyVerify(options.keys) : options.verify;
+    return createTokenAuth({
+        name: "apiKey",
+        extract: (request) => request.headers.get(header) ?? undefined,
+        verify,
+        optional: options.optional === true,
+    });
+}
+//# sourceMappingURL=token-auth.js.map

package/dist/token-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-auth.js","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"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"}

package/dist/trailing-slash.d.ts

@@ -0,0 +1,23 @@
+export interface TrailingSlashOptions {
+    /** Redirect (default) or route internally with a rewritten URL. */
+    readonly mode?: "redirect" | "rewrite";
+    /** Redirect status. Default `308` (method-preserving permanent redirect). */
+    readonly status?: 301 | 302 | 307 | 308;
+    /** Methods affected. Default `["GET", "HEAD"]`; add write methods only when you want 308 redirects. */
+    readonly methods?: readonly string[];
+    /** Skip paths whose last segment looks like a file (`/app.css`). Default `true` for append mode. */
+    readonly ignoreFileExtensions?: boolean;
+    /** App-specific skip predicate. */
+    readonly ignore?: (path: string, request: Request) => boolean;
+}
+/**
+ * Remove trailing slashes from non-root paths. Redirect mode is the production default because it
+ * canonicalizes URLs for clients and caches; rewrite mode is available for compatibility migrations.
+ */
+export declare function trimTrailingSlash(options?: TrailingSlashOptions): import("@nifrajs/core").NifraPlugin<import("@nifrajs/core").AnyServer, import("@nifrajs/core").AnyServer>;
+/**
+ * Append a trailing slash to non-root paths. By default it skips file-looking paths such as
+ * `/app.css`, which keeps static assets and extensionful API routes stable.
+ */
+export declare function appendTrailingSlash(options?: TrailingSlashOptions): import("@nifrajs/core").NifraPlugin<import("@nifrajs/core").AnyServer, import("@nifrajs/core").AnyServer>;
+//# sourceMappingURL=trailing-slash.d.ts.map

package/dist/trailing-slash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailing-slash.d.ts","sourceRoot":"","sources":["../src/trailing-slash.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;IACvC,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,oGAAoG;IACpG,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;IACvC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;CAC9D;AAsCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,oBAAyB,6GAenE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,6GAiBrE"}

package/dist/trailing-slash.js

@@ -0,0 +1,70 @@
+import { definePlugin } from "@nifrajs/core";
+const DEFAULT_METHODS = ["GET", "HEAD"];
+const REDIRECT_STATUSES = new Set([301, 302, 307, 308]);
+function validateStatus(status) {
+    if (!REDIRECT_STATUSES.has(status)) {
+        throw new Error("trailingSlash: status must be 301, 302, 307, or 308");
+    }
+}
+function hasFileExtension(path) {
+    const slash = path.lastIndexOf("/");
+    const segment = path.slice(slash + 1);
+    return segment.includes(".");
+}
+function withPath(req, path) {
+    const url = new URL(req.url);
+    url.pathname = path;
+    return url;
+}
+function route(req, url, mode, status) {
+    return mode === "rewrite"
+        ? new Request(url.toString(), req)
+        : new Response(null, { status, headers: { location: url.toString() } });
+}
+function methodsOf(methods) {
+    return new Set((methods ?? DEFAULT_METHODS).map((m) => m.toUpperCase()));
+}
+/**
+ * Remove trailing slashes from non-root paths. Redirect mode is the production default because it
+ * canonicalizes URLs for clients and caches; rewrite mode is available for compatibility migrations.
+ */
+export function trimTrailingSlash(options = {}) {
+    const mode = options.mode ?? "redirect";
+    const status = options.status ?? 308;
+    validateStatus(status);
+    const methods = methodsOf(options.methods);
+    return definePlugin("trimTrailingSlash", (app) => app.onRequest((req) => {
+        if (!methods.has(req.method.toUpperCase()))
+            return undefined;
+        const path = new URL(req.url).pathname;
+        if (path === "/" || !path.endsWith("/"))
+            return undefined;
+        if (options.ignore?.(path, req) === true)
+            return undefined;
+        return route(req, withPath(req, path.replace(/\/+$/, "") || "/"), mode, status);
+    }));
+}
+/**
+ * Append a trailing slash to non-root paths. By default it skips file-looking paths such as
+ * `/app.css`, which keeps static assets and extensionful API routes stable.
+ */
+export function appendTrailingSlash(options = {}) {
+    const mode = options.mode ?? "redirect";
+    const status = options.status ?? 308;
+    const ignoreFileExtensions = options.ignoreFileExtensions !== false;
+    validateStatus(status);
+    const methods = methodsOf(options.methods);
+    return definePlugin("appendTrailingSlash", (app) => app.onRequest((req) => {
+        if (!methods.has(req.method.toUpperCase()))
+            return undefined;
+        const path = new URL(req.url).pathname;
+        if (path === "/" || path.endsWith("/"))
+            return undefined;
+        if (ignoreFileExtensions && hasFileExtension(path))
+            return undefined;
+        if (options.ignore?.(path, req) === true)
+            return undefined;
+        return route(req, withPath(req, `${path}/`), mode, status);
+    }));
+}
+//# sourceMappingURL=trailing-slash.js.map

package/dist/trailing-slash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailing-slash.js","sourceRoot":"","sources":["../src/trailing-slash.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nifrajs/middleware",
+  "version": "0.1.0-alpha.1",
+  "description": "Composable middleware for nifra — auth, CSRF, JWT/JWKS, IP restriction, CORS, body limits, response cache, timing, and operational helpers.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr",
+    "cors",
+    "rate-limit",
+    "jwt",
+    "csrf",
+    "openapi",
+    "security-headers"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./context-storage": {
+      "bun": "./src/context-storage.ts",
+      "types": "./dist/context-storage.d.ts",
+      "default": "./dist/context-storage.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/schema": "workspace:*"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*",
+    "@nifrajs/schema": "workspace:*",
+    "@nifrajs/test-utils": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/middleware"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/_utils.ts

@@ -0,0 +1,163 @@
+export type MaybePromise<T> = T | Promise<T>
+
+export const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"])
+
+const TEXT = new TextEncoder()
+
+export function jsonError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): Response {
+  return Response.json(
+    { ok: false, error },
+    headers === undefined ? { status } : { status, headers },
+  )
+}
+
+export function parseCookies(header: string | null | undefined): Record<string, string> {
+  // Null-prototype: an untrusted cookie name (`constructor`/`__proto__`/…) is an inert own key,
+  // never a prototype-member shadow. Mirrors core's parseCookies + the query/form parsers.
+  const out: Record<string, string> = Object.create(null)
+  if (!header) return out
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=")
+    if (eq < 1) continue
+    const name = part.slice(0, eq).trim()
+    if (name === "") continue
+    let value = part.slice(eq + 1).trim()
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1)
+    }
+    try {
+      out[name] = decodeURIComponent(value)
+    } catch {
+      out[name] = value
+    }
+  }
+  return out
+}
+
+export function quotedHeaderValue(value: string): string {
+  let out = ""
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i)
+    if (c < 0x20 || c === 0x7f) continue
+    const ch = value[i] ?? ""
+    out += ch === "\\" || ch === '"' ? `\\${ch}` : ch
+  }
+  return out
+}
+
+export function utf8Bytes(value: string): Uint8Array<ArrayBuffer> {
+  return TEXT.encode(value)
+}
+
+export function secretBytes(secret: string | Uint8Array, label: string): Uint8Array<ArrayBuffer> {
+  const bytes = typeof secret === "string" ? utf8Bytes(secret) : new Uint8Array(secret)
+  if (bytes.byteLength < 32) {
+    throw new Error(`${label}: secret must be at least 32 bytes`)
+  }
+  return bytes as Uint8Array<ArrayBuffer>
+}
+
+export async function sha256(input: string | Uint8Array): Promise<Uint8Array<ArrayBuffer>> {
+  const bytes = typeof input === "string" ? utf8Bytes(input) : new Uint8Array(input)
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)) as Uint8Array<ArrayBuffer>
+}
+
+export function timingSafeEqualBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) return false
+  let diff = 0
+  for (let i = 0; i < a.byteLength; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0)
+  return diff === 0
+}
+
+export async function timingSafeEqualString(a: string, b: string): Promise<boolean> {
+  const [left, right] = await Promise.all([sha256(a), sha256(b)])
+  return timingSafeEqualBytes(left, right)
+}
+
+export function base64UrlEncode(bytes: ArrayBuffer | Uint8Array): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  let bin = ""
+  for (const b of view) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+export function base64UrlDecode(input: string): Uint8Array<ArrayBuffer> | null {
+  if (!/^[A-Za-z0-9_-]*$/.test(input) || input.length % 4 === 1) return null
+  const padded = input
+    .replace(/-/g, "+")
+    .replace(/_/g, "/")
+    .padEnd(Math.ceil(input.length / 4) * 4, "=")
+  try {
+    const bin = atob(padded)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return bytes as Uint8Array<ArrayBuffer>
+  } catch {
+    return null
+  }
+}
+
+export function decodeBase64(input: string): Uint8Array<ArrayBuffer> | null {
+  try {
+    const bin = atob(input)
+    const bytes = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+    return bytes as Uint8Array<ArrayBuffer>
+  } catch {
+    return null
+  }
+}
+
+export async function importHmacKey(
+  secret: string | Uint8Array,
+  hash = "SHA-256",
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    secretBytes(secret, "hmac"),
+    { name: "HMAC", hash },
+    false,
+    ["sign", "verify"],
+  )
+}
+
+export async function hmacSha256(input: string, secret: string | Uint8Array): Promise<string> {
+  const key = await importHmacKey(secret, "SHA-256")
+  const sig = await crypto.subtle.sign("HMAC", key, utf8Bytes(input))
+  return base64UrlEncode(sig)
+}
+
+export async function verifyHmacSha256(
+  input: string,
+  signature: string,
+  secret: string | Uint8Array,
+): Promise<boolean> {
+  const sig = base64UrlDecode(signature)
+  if (sig === null) return false
+  const key = await importHmacKey(secret, "SHA-256")
+  return crypto.subtle.verify("HMAC", key, sig, utf8Bytes(input))
+}
+
+/**
+ * Apply header mutations to a response, in place when possible. Framework-built responses
+ * (`new Response`, `Response.json`) have mutable headers across every runtime — so the common path
+ * mutates `res` directly and returns it, allocating nothing. Only an *immutable*-headers response
+ * (`Response.redirect()`/`Response.error()`, or a proxied `fetch()` response on Node/Deno/workerd —
+ * never on Bun) makes `.set`/`.append` throw; that path clones into a fresh `Headers` + `Response`,
+ * exactly the old always-clone behavior. `apply` runs once either way (immutability is all-or-nothing
+ * — the first mutation throws before any partial change), so a mutation chain is safe to pass.
+ */
+export function withHeaders(res: Response, apply: (headers: Headers) => void): Response {
+  try {
+    apply(res.headers)
+    return res
+  } catch {
+    const headers = new Headers(res.headers)
+    apply(headers)
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+  }
+}

package/src/basic-auth.ts

@@ -0,0 +1,109 @@
+import { definePlugin, type NifraPlugin } from "@nifrajs/core"
+import {
+  decodeBase64,
+  jsonError,
+  type MaybePromise,
+  quotedHeaderValue,
+  sha256,
+  timingSafeEqualBytes,
+} from "./_utils.ts"
+
+export type BasicAuthPlugin<P> = NifraPlugin & {
+  principal(request: Request): P | null
+  requirePrincipal(request: Request): P
+}
+
+export interface BasicAuthStaticOptions<P = string> {
+  readonly username: string
+  readonly password: string
+  readonly principal?: P
+  readonly realm?: string
+  readonly optional?: boolean
+}
+
+export interface BasicAuthVerifyOptions<P> {
+  readonly verify: (username: string, password: string) => MaybePromise<P | null | undefined>
+  readonly realm?: string
+  readonly optional?: boolean
+}
+
+const UTF8 = new TextDecoder("utf-8", { fatal: true })
+
+function challenge(realm: string): string {
+  return `Basic realm="${quotedHeaderValue(realm)}", charset="UTF-8"`
+}
+
+function reject(realm: string): Response {
+  return jsonError(401, "unauthorized", { "www-authenticate": challenge(realm) })
+}
+
+function credentials(request: Request): { username: string; password: string } | null {
+  const header = request.headers.get("authorization")
+  if (header?.startsWith("Basic ") !== true) return null
+  const raw = decodeBase64(header.slice(6).trim())
+  if (raw === null) return null
+  let decoded: string
+  try {
+    decoded = UTF8.decode(raw)
+  } catch {
+    return null
+  }
+  const colon = decoded.indexOf(":")
+  if (colon < 0) return null
+  return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) }
+}
+
+async function staticVerifier<P>(
+  username: string,
+  password: string,
+  principal: P,
+): Promise<(u: string, p: string) => Promise<P | null>> {
+  const [expectedUser, expectedPass] = await Promise.all([sha256(username), sha256(password)])
+  return async (u, p) => {
+    const [gotUser, gotPass] = await Promise.all([sha256(u), sha256(p)])
+    const userOk = timingSafeEqualBytes(gotUser, expectedUser)
+    const passOk = timingSafeEqualBytes(gotPass, expectedPass)
+    return userOk && passOk ? principal : null
+  }
+}
+
+/**
+ * HTTP Basic authentication. Prefer short-lived Basic Auth for internal tools and staging gates, not
+ * public user login. Static credentials are compared in constant time after SHA-256 hashing; the
+ * callback form is available for external stores.
+ */
+export function basicAuth(options: BasicAuthStaticOptions): BasicAuthPlugin<string>
+export function basicAuth<P>(options: BasicAuthStaticOptions<P>): BasicAuthPlugin<P>
+export function basicAuth<P>(options: BasicAuthVerifyOptions<P>): BasicAuthPlugin<P>
+export function basicAuth<P>(
+  options: BasicAuthStaticOptions<P> | BasicAuthVerifyOptions<P>,
+): BasicAuthPlugin<P | string> {
+  const realm = options.realm ?? "api"
+  const optional = options.optional === true
+  const store = new WeakMap<Request, P | string>()
+  const verifyPromise =
+    "verify" in options
+      ? Promise.resolve(options.verify)
+      : staticVerifier(options.username, options.password, options.principal ?? options.username)
+
+  const plugin = definePlugin("basicAuth", (app) =>
+    app.beforeHandle(async (c: { readonly req: Request }) => {
+      const parsed = credentials(c.req)
+      const principal =
+        parsed === null ? null : await (await verifyPromise)(parsed.username, parsed.password)
+      if (principal !== null && principal !== undefined) {
+        store.set(c.req, principal)
+        return undefined
+      }
+      return optional ? undefined : reject(realm)
+    }),
+  )
+  return Object.assign(plugin, {
+    principal: (request: Request): P | string | null => store.get(request) ?? null,
+    requirePrincipal: (request: Request): P | string => {
+      const principal = store.get(request)
+      if (principal === undefined) throw reject(realm)
+      return principal
+    },
+  }) as BasicAuthPlugin<P | string>
+}

package/src/body-limit.ts

@@ -0,0 +1,53 @@
+import type { Middleware } from "@nifrajs/core"
+import { jsonError, SAFE_METHODS } from "./_utils.ts"
+
+export interface BodyLimitOptions {
+  /** Maximum raw request-body bytes accepted. */
+  readonly maxBytes: number
+  /** Methods to inspect. Default: every method except GET/HEAD/OPTIONS/TRACE. */
+  readonly methods?: readonly string[]
+  /** Response error name for over-limit bodies. Default `"payload_too_large"`. */
+  readonly error?: string
+  /** Allow bodies without Content-Length. Default false (fail closed with 411). */
+  readonly allowLengthless?: boolean
+}
+
+function parseContentLength(value: string | null): number | undefined | null {
+  if (value === null) return undefined
+  if (!/^\d+$/.test(value)) return null
+  const n = Number(value)
+  return Number.isSafeInteger(n) ? n : Infinity
+}
+
+/**
+ * Enforce a raw byte cap for request bodies before routing. This middleware is intentionally
+ * Content-Length based: reading a cloned Web body is not transparent on every runtime. Lengthless
+ * bodies fail closed by default; use route-level `c.boundedBody()` / schema validation for endpoints
+ * that intentionally accept streamed bodies.
+ */
+export function bodyLimit(options: BodyLimitOptions): Middleware {
+  const { maxBytes } = options
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw new Error("bodyLimit: maxBytes must be a non-negative safe integer")
+  }
+  const methods =
+    options.methods !== undefined ? new Set(options.methods.map((m) => m.toUpperCase())) : undefined
+  const error = options.error ?? "payload_too_large"
+  const allowLengthless = options.allowLengthless === true
+
+  return {
+    name: "body-limit",
+    onRequest(req) {
+      if (methods !== undefined ? !methods.has(req.method) : SAFE_METHODS.has(req.method)) {
+        return undefined
+      }
+      const contentLength = parseContentLength(req.headers.get("content-length"))
+      if (contentLength === null) return jsonError(400, "invalid_content_length")
+      if (contentLength === undefined && req.body !== null && !allowLengthless) {
+        return jsonError(411, "length_required")
+      }
+      if (contentLength !== undefined && contentLength > maxBytes) return jsonError(413, error)
+      return undefined
+    },
+  }
+}