@krizaka/rate-limit 0.1.2 → 0.2.0

package/README.md

@@ -33,3 +33,7 @@ await limiter.forget("signIn", keys); // a successful sign-in clears its failure
 - **A store that fails lets the request through** (the limiter must not take the site down) and tells `onStoreError`; `failOpen: false` rethrows instead.
 - **Orochia's extras** are in the port: `peek` (read without counting), `set` (a lock-out) and `reset`.
 - `limitStoreContract` (from `@krizaka/rate-limit/testkit`) is the contract every store runs.
+
+## Turnstile (`@krizaka/rate-limit/turnstile`)
+
+A Cloudflare Turnstile widget protects nothing until the server asks Cloudflare about the token it produced. `createTurnstileVerifier({ secret, hostnames, now })` returns `verify({ token, remoteIp, action })` → `{ ok: true }` or `{ ok: false, reason, errorCodes }`. It **fails closed**: no secret (`not-configured`), no or oversized token (`missing-token`), a refusal (`rejected`), a token solved on another hostname or for another form's `action`, a replayed token (single-use, remembered for Cloudflare's 300 s), a timeout or an unreachable service (`unavailable`) all refuse. The secret is `ABUSE_CAPTCHA_SECRET_KEY` with `ABUSE_CAPTCHA_PROVIDER=turnstile` (the provider is a value; never in the browser); the site key is the public `NEXT_PUBLIC_ABUSE_CAPTCHA_SITE_KEY`. Answer a refusal with a 4xx and send nothing; log the `reason` only (no address, no message). Rule `turnstile-server-side` of the org registry.

package/dist/turnstile.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Server-side check of a Cloudflare Turnstile token (siteverify). The widget alone protects nothing: the token it hands the
+ * browser is only worth something once the server has asked Cloudflare about it. Fails closed — no secret, no token, a refusal, a
+ * wrong hostname or action, a replayed token, a timeout or an unreachable service all answer `ok: false` — so a form that calls
+ * it never sends a message on doubt. Nothing here knows a request, an environment variable or the wall clock.
+ */
+declare const TURNSTILE_SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+declare const TURNSTILE_MAX_TOKEN_LENGTH = 2048;
+type TurnstileFailure = "not-configured" | "missing-token" | "rejected" | "hostname" | "action" | "replayed" | "unavailable";
+type TurnstileResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: TurnstileFailure;
+    errorCodes: string[];
+};
+interface TurnstileResponse {
+    ok: boolean;
+    json(): Promise<unknown>;
+}
+type TurnstileFetch = (url: string, init: {
+    method: string;
+    body: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<TurnstileResponse>;
+interface TurnstileDeps {
+    /** The widget's secret key (`ABUSE_TURNSTILE_SECRET`). Absent or blank: every check fails (`not-configured`). */
+    secret: string | undefined;
+    /** The hostnames a token may have been solved on (`www.krizaka.com`). Empty: the hostname is not checked. */
+    hostnames?: readonly string[];
+    /** The clock, injected. */
+    now: () => Date;
+    fetch?: TurnstileFetch;
+    timeoutMs?: number;
+}
+interface TurnstileCheck {
+    token: unknown;
+    /** The visitor's address; "unknown" and blank are not sent. */
+    remoteIp?: string;
+    /** The widget's `action`, when the form sets one: a token solved for another form is refused. */
+    action?: string;
+}
+/** A verifier with its replay memory: one per process, shared by the forms. */
+declare function createTurnstileVerifier(deps: TurnstileDeps): (check: TurnstileCheck) => Promise<TurnstileResult>;
+
+export { TURNSTILE_MAX_TOKEN_LENGTH, TURNSTILE_SITEVERIFY_URL, type TurnstileCheck, type TurnstileDeps, type TurnstileFailure, type TurnstileFetch, type TurnstileResponse, type TurnstileResult, createTurnstileVerifier };

package/dist/turnstile.js

@@ -0,0 +1,50 @@
+// src/turnstile.ts
+var TURNSTILE_SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+var TURNSTILE_MAX_TOKEN_LENGTH = 2048;
+var DEFAULT_TIMEOUT_MS = 8e3;
+var REPLAY_WINDOW_MS = 3e5;
+var MAX_REMEMBERED_TOKENS = 5e3;
+var fail = (reason, errorCodes = []) => ({ ok: false, reason, errorCodes });
+function createTurnstileVerifier(deps) {
+  const seen = /* @__PURE__ */ new Map();
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  const remember = (token, nowMs) => {
+    for (const [t, at] of seen) if (nowMs - at > REPLAY_WINDOW_MS) seen.delete(t);
+    if (seen.has(token)) return false;
+    if (seen.size >= MAX_REMEMBERED_TOKENS) seen.delete(seen.keys().next().value);
+    seen.set(token, nowMs);
+    return true;
+  };
+  return async ({ token, remoteIp, action }) => {
+    const secret = deps.secret?.trim();
+    if (!secret) return fail("not-configured");
+    if (typeof token !== "string" || !token.trim() || token.length > TURNSTILE_MAX_TOKEN_LENGTH) return fail("missing-token");
+    if (!remember(token, deps.now().valueOf())) return fail("replayed");
+    const body = new URLSearchParams({ secret, response: token });
+    if (remoteIp && remoteIp !== "unknown") body.set("remoteip", remoteIp);
+    let answer;
+    try {
+      const res = await doFetch(TURNSTILE_SITEVERIFY_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+        signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+      });
+      if (!res.ok) return fail("unavailable");
+      answer = await res.json();
+    } catch {
+      return fail("unavailable");
+    }
+    const codes = Array.isArray(answer["error-codes"]) ? answer["error-codes"] : [];
+    if (answer.success !== true) return fail("rejected", codes);
+    if (deps.hostnames?.length && !deps.hostnames.includes(answer.hostname ?? "")) return fail("hostname", codes);
+    if (action !== void 0 && answer.action !== action) return fail("action", codes);
+    return { ok: true };
+  };
+}
+export {
+  TURNSTILE_MAX_TOKEN_LENGTH,
+  TURNSTILE_SITEVERIFY_URL,
+  createTurnstileVerifier
+};
+//# sourceMappingURL=turnstile.js.map

package/dist/turnstile.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/turnstile.ts"],"sourcesContent":["/**\n * Server-side check of a Cloudflare Turnstile token (siteverify). The widget alone protects nothing: the token it hands the\n * browser is only worth something once the server has asked Cloudflare about it. Fails closed — no secret, no token, a refusal, a\n * wrong hostname or action, a replayed token, a timeout or an unreachable service all answer `ok: false` — so a form that calls\n * it never sends a message on doubt. Nothing here knows a request, an environment variable or the wall clock.\n */\nexport const TURNSTILE_SITEVERIFY_URL = \"https://challenges.cloudflare.com/turnstile/v0/siteverify\";\n\n// @fixed: a Turnstile token is a few hundred characters; 2048 is Cloudflare's own documented maximum\nexport const TURNSTILE_MAX_TOKEN_LENGTH = 2048;\n// @fixed: a form submit must not hang on the verification service\nconst DEFAULT_TIMEOUT_MS = 8000;\n// @fixed: a token expires after 300 s at Cloudflare; remembering it for as long is enough to refuse a replay here\nconst REPLAY_WINDOW_MS = 300_000;\n// @fixed: bounds the replay memory of one process\nconst MAX_REMEMBERED_TOKENS = 5000;\n\nexport type TurnstileFailure = \"not-configured\" | \"missing-token\" | \"rejected\" | \"hostname\" | \"action\" | \"replayed\" | \"unavailable\";\nexport type TurnstileResult = { ok: true } | { ok: false; reason: TurnstileFailure; errorCodes: string[] };\n\nexport interface TurnstileResponse {\n  ok: boolean;\n  json(): Promise<unknown>;\n}\nexport type TurnstileFetch = (\n  url: string,\n  init: { method: string; body: string; headers: Record<string, string>; signal?: AbortSignal },\n) => Promise<TurnstileResponse>;\n\nexport interface TurnstileDeps {\n  /** The widget's secret key (`ABUSE_TURNSTILE_SECRET`). Absent or blank: every check fails (`not-configured`). */\n  secret: string | undefined;\n  /** The hostnames a token may have been solved on (`www.krizaka.com`). Empty: the hostname is not checked. */\n  hostnames?: readonly string[];\n  /** The clock, injected. */\n  now: () => Date;\n  fetch?: TurnstileFetch;\n  timeoutMs?: number;\n}\n\nexport interface TurnstileCheck {\n  token: unknown;\n  /** The visitor's address; \"unknown\" and blank are not sent. */\n  remoteIp?: string;\n  /** The widget's `action`, when the form sets one: a token solved for another form is refused. */\n  action?: string;\n}\n\nconst fail = (reason: TurnstileFailure, errorCodes: string[] = []): TurnstileResult => ({ ok: false, reason, errorCodes });\n\n/** A verifier with its replay memory: one per process, shared by the forms. */\nexport function createTurnstileVerifier(deps: TurnstileDeps): (check: TurnstileCheck) => Promise<TurnstileResult> {\n  const seen = new Map<string, number>();\n  const doFetch = deps.fetch ?? (globalThis.fetch as unknown as TurnstileFetch);\n\n  const remember = (token: string, nowMs: number): boolean => {\n    for (const [t, at] of seen) if (nowMs - at > REPLAY_WINDOW_MS) seen.delete(t);\n    if (seen.has(token)) return false;\n    if (seen.size >= MAX_REMEMBERED_TOKENS) seen.delete(seen.keys().next().value as string);\n    seen.set(token, nowMs);\n    return true;\n  };\n\n  return async ({ token, remoteIp, action }) => {\n    const secret = deps.secret?.trim();\n    if (!secret) return fail(\"not-configured\");\n    if (typeof token !== \"string\" || !token.trim() || token.length > TURNSTILE_MAX_TOKEN_LENGTH) return fail(\"missing-token\");\n    if (!remember(token, deps.now().valueOf())) return fail(\"replayed\");\n\n    const body = new URLSearchParams({ secret, response: token });\n    if (remoteIp && remoteIp !== \"unknown\") body.set(\"remoteip\", remoteIp);\n    let answer: { success?: boolean; hostname?: string; action?: string; \"error-codes\"?: string[] };\n    try {\n      const res = await doFetch(TURNSTILE_SITEVERIFY_URL, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n        body: body.toString(),\n        signal: AbortSignal.timeout(deps.timeoutMs ?? DEFAULT_TIMEOUT_MS),\n      });\n      if (!res.ok) return fail(\"unavailable\");\n      answer = (await res.json()) as typeof answer;\n    } catch {\n      return fail(\"unavailable\");\n    }\n    const codes = Array.isArray(answer[\"error-codes\"]) ? answer[\"error-codes\"] : [];\n    if (answer.success !== true) return fail(\"rejected\", codes);\n    if (deps.hostnames?.length && !deps.hostnames.includes(answer.hostname ?? \"\")) return fail(\"hostname\", codes);\n    if (action !== undefined && answer.action !== action) return fail(\"action\", codes);\n    return { ok: true };\n  };\n}\n"],"mappings":";AAMO,IAAM,2BAA2B;AAGjC,IAAM,6BAA6B;AAE1C,IAAM,qBAAqB;AAE3B,IAAM,mBAAmB;AAEzB,IAAM,wBAAwB;AAiC9B,IAAM,OAAO,CAAC,QAA0B,aAAuB,CAAC,OAAwB,EAAE,IAAI,OAAO,QAAQ,WAAW;AAGjH,SAAS,wBAAwB,MAA0E;AAChH,QAAM,OAAO,oBAAI,IAAoB;AACrC,QAAM,UAAU,KAAK,SAAU,WAAW;AAE1C,QAAM,WAAW,CAAC,OAAe,UAA2B;AAC1D,eAAW,CAAC,GAAG,EAAE,KAAK,KAAM,KAAI,QAAQ,KAAK,iBAAkB,MAAK,OAAO,CAAC;AAC5E,QAAI,KAAK,IAAI,KAAK,EAAG,QAAO;AAC5B,QAAI,KAAK,QAAQ,sBAAuB,MAAK,OAAO,KAAK,KAAK,EAAE,KAAK,EAAE,KAAe;AACtF,SAAK,IAAI,OAAO,KAAK;AACrB,WAAO;AAAA,EACT;AAEA,SAAO,OAAO,EAAE,OAAO,UAAU,OAAO,MAAM;AAC5C,UAAM,SAAS,KAAK,QAAQ,KAAK;AACjC,QAAI,CAAC,OAAQ,QAAO,KAAK,gBAAgB;AACzC,QAAI,OAAO,UAAU,YAAY,CAAC,MAAM,KAAK,KAAK,MAAM,SAAS,2BAA4B,QAAO,KAAK,eAAe;AACxH,QAAI,CAAC,SAAS,OAAO,KAAK,IAAI,EAAE,QAAQ,CAAC,EAAG,QAAO,KAAK,UAAU;AAElE,UAAM,OAAO,IAAI,gBAAgB,EAAE,QAAQ,UAAU,MAAM,CAAC;AAC5D,QAAI,YAAY,aAAa,UAAW,MAAK,IAAI,YAAY,QAAQ;AACrE,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,QAAQ,0BAA0B;AAAA,QAClD,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,oCAAoC;AAAA,QAC/D,MAAM,KAAK,SAAS;AAAA,QACpB,QAAQ,YAAY,QAAQ,KAAK,aAAa,kBAAkB;AAAA,MAClE,CAAC;AACD,UAAI,CAAC,IAAI,GAAI,QAAO,KAAK,aAAa;AACtC,eAAU,MAAM,IAAI,KAAK;AAAA,IAC3B,QAAQ;AACN,aAAO,KAAK,aAAa;AAAA,IAC3B;AACA,UAAM,QAAQ,MAAM,QAAQ,OAAO,aAAa,CAAC,IAAI,OAAO,aAAa,IAAI,CAAC;AAC9E,QAAI,OAAO,YAAY,KAAM,QAAO,KAAK,YAAY,KAAK;AAC1D,QAAI,KAAK,WAAW,UAAU,CAAC,KAAK,UAAU,SAAS,OAAO,YAAY,EAAE,EAAG,QAAO,KAAK,YAAY,KAAK;AAC5G,QAAI,WAAW,UAAa,OAAO,WAAW,OAAQ,QAAO,KAAK,UAAU,KAAK;AACjF,WAAO,EAAE,IAAI,KAAK;AAAA,EACpB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/rate-limit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Limits per action for every Krizaka product: fixed windows per address and per subject, the limits read from the admin's settings, a memory store and a PostgreSQL store whose atomic upsert counts exactly under concurrency, a stable 429 with Retry-After. No database client, no wall clock, no request object.",
   "keywords": [
     "krizaka",
@@ -30,6 +30,10 @@
       "types": "./dist/settings.d.ts",
       "import": "./dist/settings.js"
     },
+    "./turnstile": {
+      "types": "./dist/turnstile.d.ts",
+      "import": "./dist/turnstile.js"
+    },
     "./testkit": {
       "types": "./dist/testkit.d.ts",
       "import": "./dist/testkit.js"
@@ -54,12 +58,12 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
     "zod": "^4.6.7",
-    "@krizaka/config": "^0.14.1"
+    "@krizaka/config": "^0.15.0"
   },
   "dependencies": {
-    "@krizaka/db": "^0.3.0",
-    "@krizaka/settings": "^0.5.1",
-    "@krizaka/time": "^0.1.0"
+    "@krizaka/db": "^0.3.1",
+    "@krizaka/time": "^0.1.0",
+    "@krizaka/settings": "^0.5.1"
   },
   "peerDependencies": {
     "vitest": ">=4",