@erenthedeveloper0/zen-middleware 0.1.0-alpha.1

package/dist/store.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The counter store — rfcs/0001 §3.5, the `Store` seam.
+ *
+ * §3.5's inventory lists one interface shared by the cache, the rate limiter
+ * and the session store, with an in-memory default and Redis / SQLite / D1 /
+ * Durable Object as the alternates. This module is the rate limiter's half of
+ * it: the narrowest contract that a fixed-window counter needs, chosen so that
+ * a Redis implementation is two commands rather than a transaction.
+ *
+ *     INCR    zen:rl:{window}:{key}
+ *     PEXPIRE zen:rl:{window}:{key} {windowMs}   // only on the first hit
+ *
+ * That is the whole implementation, and it is the reason `hit` returns the
+ * count *including* the current request rather than taking a "should I allow
+ * this" decision. A store that decided would need the limit, and a store that
+ * needs the limit cannot be shared with the cache.
+ */
+/** One key's standing in the window it is currently inside. */
+export interface Tally {
+    /** Hits in this window, **including** the one that produced this tally. */
+    readonly count: number;
+    /** Epoch milliseconds at which this window ends and the count resets. */
+    readonly resetAt: number;
+}
+/**
+ * A counter keyed by string, bucketed into fixed windows.
+ *
+ * `hit` may be async — a Redis store is a round trip — and the rate limiter
+ * awaits it only when it actually returns a promise, so the in-memory default
+ * keeps the whole limiter on §8.4's synchronous fast path.
+ */
+export interface Store {
+    hit(key: string, now: number): Tally | Promise<Tally>;
+    /** Drop everything. Tests use it; production has no reason to. */
+    reset?(): void;
+    /** Release connections. Called from the limiter's `onClose` (§4.5). */
+    close?(): void | Promise<void>;
+    /** Live keys, when the store can say. Read by the memory-bound gate. */
+    readonly size?: number;
+}
+export interface MemoryStoreOptions {
+    readonly windowMs: number;
+}
+/**
+ * The default store: a fixed-window counter that forgets a window when it ends.
+ *
+ * **Fixed windows, stated plainly.** A key's count resets at a wall-clock
+ * boundary, so a client can spend its whole budget in the last millisecond of
+ * one window and its whole budget again in the first millisecond of the next —
+ * up to `2 × limit` inside one window's worth of time straddling the boundary.
+ * That is the known cost of fixed windows and it belongs here rather than in a
+ * footnote, because the alternatives are not free: a sliding log keeps one
+ * timestamp per request, which is unbounded memory per key and the key is the
+ * thing an attacker chooses; and a sliding-window *counter* cannot be expressed
+ * as `INCR` + `PEXPIRE`, so it would push every alternate store into a Lua
+ * script or a transaction. §28.8 records it as a gap.
+ *
+ * **Eviction is a dropped reference, not a sweep.** The failure mode of every
+ * in-memory limiter is that its map is keyed by something the client chooses —
+ * an IP, an API key, a header — so whoever is attacking decides how much memory
+ * the process holds. The usual answer is a timer that walks the map, and
+ * walking a map with ten million keys is a pause that happens under exactly the
+ * load that created the keys.
+ *
+ * A fixed window needs neither. When the clock crosses into a new window every
+ * count in the old one is dead by definition, so the map is replaced whole: one
+ * assignment, no scan, no pause, and the collector reclaims a generation at
+ * once. Memory is bounded by the distinct keys seen inside a *single* window,
+ * and there is no timer to leak — which also means no `unref`, a Node API this
+ * package cannot use if it is to run everywhere core does.
+ *
+ * The saving is that the eviction rule falls out of the counting rule instead
+ * of being a second mechanism bolted beside it. Everything a sweep could get
+ * wrong — evicting a live key, retaining a dead one, pausing — is unreachable,
+ * because there is no sweep. What *is* reachable is losing or double-counting a
+ * key across the boundary, and that is what the differential suite fuzzes.
+ */
+export declare class MemoryStore implements Store {
+    #private;
+    constructor(options: MemoryStoreOptions);
+    hit(key: string, now: number): Tally;
+    reset(): void;
+    get size(): number;
+}
+/**
+ * The reference twin — rfcs/0001 §14.5, §20.5, I6.
+ *
+ * Same contract, no eviction: one map keyed by window *and* key, which grows
+ * forever. It is obviously correct and completely unusable, which is exactly
+ * what a reference implementation is for. `MemoryStore` must agree with it on
+ * every verdict over a non-decreasing clock; where they differ, the difference
+ * is a count the evicting store lost or repeated at a window boundary, and that
+ * is the only bug class this component has.
+ *
+ * They *do* diverge, in one case, and it is a documented property rather than a
+ * defect: on a clock that steps **backwards** across a boundary the reference
+ * still remembers the window it left and `MemoryStore` does not. Fuzzing a
+ * non-decreasing clock and pinning the backwards case in one named test is the
+ * honest split — a fuzzer that quietly avoided the disagreement would be
+ * hiding it, and one that asserted equality there would be asserting something
+ * neither implementation promises.
+ *
+ * Exported rather than kept in the test directory for the same reason
+ * `PlainContext` and `walkSerializer` are: a twin only the framework's own
+ * tests can reach is one nobody verifying an alternate store can use, and
+ * §14.5 says every optimised subsystem ships its reference implementation.
+ */
+export declare class ReferenceStore implements Store {
+    #private;
+    constructor(options: MemoryStoreOptions);
+    hit(key: string, now: number): Tally;
+    reset(): void;
+    get size(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,KAAK;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IACrD,kEAAkE;IAClE,KAAK,CAAC,IAAI,IAAI,CAAA;IACd,uEAAuE;IACvE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,WAAY,YAAW,KAAK;;gBAM3B,OAAO,EAAE,kBAAkB;IAIvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK;IAepC,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAe,YAAW,KAAK;;gBAI9B,OAAO,EAAE,kBAAkB;IAIvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK;IAUpC,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/store.js

@@ -0,0 +1,126 @@
+/**
+ * The counter store — rfcs/0001 §3.5, the `Store` seam.
+ *
+ * §3.5's inventory lists one interface shared by the cache, the rate limiter
+ * and the session store, with an in-memory default and Redis / SQLite / D1 /
+ * Durable Object as the alternates. This module is the rate limiter's half of
+ * it: the narrowest contract that a fixed-window counter needs, chosen so that
+ * a Redis implementation is two commands rather than a transaction.
+ *
+ *     INCR    zen:rl:{window}:{key}
+ *     PEXPIRE zen:rl:{window}:{key} {windowMs}   // only on the first hit
+ *
+ * That is the whole implementation, and it is the reason `hit` returns the
+ * count *including* the current request rather than taking a "should I allow
+ * this" decision. A store that decided would need the limit, and a store that
+ * needs the limit cannot be shared with the cache.
+ */
+/**
+ * The default store: a fixed-window counter that forgets a window when it ends.
+ *
+ * **Fixed windows, stated plainly.** A key's count resets at a wall-clock
+ * boundary, so a client can spend its whole budget in the last millisecond of
+ * one window and its whole budget again in the first millisecond of the next —
+ * up to `2 × limit` inside one window's worth of time straddling the boundary.
+ * That is the known cost of fixed windows and it belongs here rather than in a
+ * footnote, because the alternatives are not free: a sliding log keeps one
+ * timestamp per request, which is unbounded memory per key and the key is the
+ * thing an attacker chooses; and a sliding-window *counter* cannot be expressed
+ * as `INCR` + `PEXPIRE`, so it would push every alternate store into a Lua
+ * script or a transaction. §28.8 records it as a gap.
+ *
+ * **Eviction is a dropped reference, not a sweep.** The failure mode of every
+ * in-memory limiter is that its map is keyed by something the client chooses —
+ * an IP, an API key, a header — so whoever is attacking decides how much memory
+ * the process holds. The usual answer is a timer that walks the map, and
+ * walking a map with ten million keys is a pause that happens under exactly the
+ * load that created the keys.
+ *
+ * A fixed window needs neither. When the clock crosses into a new window every
+ * count in the old one is dead by definition, so the map is replaced whole: one
+ * assignment, no scan, no pause, and the collector reclaims a generation at
+ * once. Memory is bounded by the distinct keys seen inside a *single* window,
+ * and there is no timer to leak — which also means no `unref`, a Node API this
+ * package cannot use if it is to run everywhere core does.
+ *
+ * The saving is that the eviction rule falls out of the counting rule instead
+ * of being a second mechanism bolted beside it. Everything a sweep could get
+ * wrong — evicting a live key, retaining a dead one, pausing — is unreachable,
+ * because there is no sweep. What *is* reachable is losing or double-counting a
+ * key across the boundary, and that is what the differential suite fuzzes.
+ */
+export class MemoryStore {
+    #windowMs;
+    #counts = new Map();
+    /** The window index (`floor(now / windowMs)`) `#counts` belongs to. */
+    #window = -1;
+    constructor(options) {
+        this.#windowMs = options.windowMs;
+    }
+    hit(key, now) {
+        const window = Math.floor(now / this.#windowMs);
+        if (window !== this.#window) {
+            // Not `.clear()`: replacing the reference lets the collector take the
+            // whole map, while `clear` walks it. At the sizes this exists to survive,
+            // that is the difference the design is for.
+            this.#counts = new Map();
+            this.#window = window;
+        }
+        const count = (this.#counts.get(key) ?? 0) + 1;
+        this.#counts.set(key, count);
+        return { count, resetAt: (window + 1) * this.#windowMs };
+    }
+    reset() {
+        this.#counts = new Map();
+        this.#window = -1;
+    }
+    get size() {
+        return this.#counts.size;
+    }
+}
+/**
+ * The reference twin — rfcs/0001 §14.5, §20.5, I6.
+ *
+ * Same contract, no eviction: one map keyed by window *and* key, which grows
+ * forever. It is obviously correct and completely unusable, which is exactly
+ * what a reference implementation is for. `MemoryStore` must agree with it on
+ * every verdict over a non-decreasing clock; where they differ, the difference
+ * is a count the evicting store lost or repeated at a window boundary, and that
+ * is the only bug class this component has.
+ *
+ * They *do* diverge, in one case, and it is a documented property rather than a
+ * defect: on a clock that steps **backwards** across a boundary the reference
+ * still remembers the window it left and `MemoryStore` does not. Fuzzing a
+ * non-decreasing clock and pinning the backwards case in one named test is the
+ * honest split — a fuzzer that quietly avoided the disagreement would be
+ * hiding it, and one that asserted equality there would be asserting something
+ * neither implementation promises.
+ *
+ * Exported rather than kept in the test directory for the same reason
+ * `PlainContext` and `walkSerializer` are: a twin only the framework's own
+ * tests can reach is one nobody verifying an alternate store can use, and
+ * §14.5 says every optimised subsystem ships its reference implementation.
+ */
+export class ReferenceStore {
+    #windowMs;
+    #counts = new Map();
+    constructor(options) {
+        this.#windowMs = options.windowMs;
+    }
+    hit(key, now) {
+        const window = Math.floor(now / this.#windowMs);
+        // The window is always base-10 digits, so the text up to the first colon is
+        // unambiguous however exotic the key is — no separator a key could forge.
+        const composite = `${window}:${key}`;
+        const count = (this.#counts.get(composite) ?? 0) + 1;
+        this.#counts.set(composite, count);
+        return { count, resetAt: (window + 1) * this.#windowMs };
+    }
+    reset() {
+        this.#counts.clear();
+    }
+    get size() {
+        return this.#counts.size;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA+BH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,WAAW;IACb,SAAS,CAAQ;IAC1B,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IACnC,uEAAuE;IACvE,OAAO,GAAG,CAAC,CAAC,CAAA;IAEZ,YAAY,OAA2B;QACrC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAA;IACnC,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,GAAW;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5B,sEAAsE;YACtE,0EAA0E;YAC1E,4CAA4C;YAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAA;YACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACvB,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QAC9C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC5B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;IAC1D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAA;QACxB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;IACnB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,cAAc;IAChB,SAAS,CAAQ;IACjB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE5C,YAAY,OAA2B;QACrC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAA;IACnC,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,GAAW;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAA;QAC/C,4EAA4E;QAC5E,0EAA0E;QAC1E,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,GAAG,EAAE,CAAA;QACpC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QACpD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QAClC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;IAC1D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@erenthedeveloper0/zen-middleware",
+  "version": "0.1.0-alpha.1",
+  "description": "Zen first-party middleware: CORS, security headers, request ids and rate limiting, as hooks that also run on unmatched requests.",
+  "keywords": [
+    "cors",
+    "security-headers",
+    "rate-limit",
+    "request-id",
+    "middleware",
+    "zen"
+  ],
+  "homepage": "https://github.com/erenthedeveloper0/zen/tree/main/packages/middleware#readme",
+  "bugs": {
+    "url": "https://github.com/erenthedeveloper0/zen/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erenthedeveloper0/zen.git",
+    "directory": "packages/middleware"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Eren Sümer",
+    "url": "https://github.com/erenthedeveloper0"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --test \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@erenthedeveloper0/zen-core": "0.1.0-alpha.1"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/src/consistency.ts

@@ -0,0 +1,62 @@
+import { Codes, ZenError } from '@erenthedeveloper0/zen-core'
+import type { CorsExports } from './cors.ts'
+
+/**
+ * Cross-plugin consistency — the check §2.4 makes possible.
+ *
+ * `Cross-Origin-Resource-Policy: same-origin` tells the browser to refuse
+ * cross-origin reads of this response. `cors({ origin: [...] })` tells it to
+ * permit them. Together they are a configuration that says two opposite things,
+ * the CORP one wins, and the symptom is a CORS setup that "does not work" for
+ * reasons that appear nowhere in the CORS configuration.
+ *
+ * In a framework where middleware is a list of opaque functions there is
+ * nothing to check. Here both are plugins on one graph and `exportsOf` lets
+ * each read the other's decision, so it is a boot error naming both settings.
+ *
+ * ### Why this is its own module rather than a function in `security.ts`
+ *
+ * Because only the plugin that runs **second** can see both, and which one that
+ * is now depends on hook ordering rather than on this check. `securityHeaders`
+ * has to register its hook *first* — its headers must be staged before anything
+ * can short-circuit, or a preflight and a 429 go out without `nosniff` — so it
+ * can no longer be the one that reads `cors`'s exports.
+ *
+ * Rather than move the check to `cors.ts` and leave it there until the next
+ * ordering change moves it back, both plugins call this with whatever they can
+ * see. The one that ran first passes `undefined` for the other half and returns;
+ * the one that ran second has both and decides. Order-independent by
+ * construction, which is the property that was actually wanted.
+ */
+export function assertCorsCorpConsistent(
+  corp: string | false,
+  cors: CorsExports | undefined,
+  reporter: string,
+): void {
+  if (cors === undefined || corp !== 'same-origin') return
+
+  const allowing = cors.origins === 'any' || cors.origins === 'dynamic' || cors.origins.length > 0
+  if (!allowing) return
+
+  const described =
+    cors.origins === 'any' ? "'*'"
+    : cors.origins === 'dynamic' ? 'origins chosen by a predicate'
+    : cors.origins.join(', ')
+
+  throw new ZenError(
+    Codes.CONFIG_INVALID,
+    `security-headers sets Cross-Origin-Resource-Policy: same-origin while cors allows ${described}. ` +
+      'The two instruct the browser to do opposite things, and the CORP header wins.',
+    {
+      status: 500,
+      expose: false,
+      hint:
+        "Use crossOriginResource: 'same-site' (the default) or 'cross-origin' if these responses are " +
+        'meant to be read cross-origin, or narrow the CORS allowlist if they are not.',
+      consequence:
+        'Left as configured, every allowed origin still fails in the browser — and it fails with a ' +
+        'message naming CORS, so the search starts in the file that is correct. ' +
+        `Reported by ${reporter}, whichever of the two was registered second.`,
+    },
+  )
+}