@krizaka/rate-limit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @krizaka/rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 shared by every instance. It replaces the `rate-limit.ts` that Yomizaka, Akinaza and Kachizaka carried byte for byte, and the PostgreSQL variants of Orochia and Yasakia.
+
+```ts
+import { emitMigration } from "@krizaka/db";
+import { createLimiter, dbLimitStore, rateLimitSchema, RateLimited } from "@krizaka/rate-limit";
+import { limitsFromSettings, rateLimitSettings } from "@krizaka/rate-limit/settings";
+import { clientIp } from "@krizaka/auth";
+
+emitMigration(rateLimitSchema, 1, { tables: {} }); // commit the SQL once, in your migrations: table rate_limit.bucket
+
+// the registry fragment: limits.signIn.perIp, limits.signIn.perSubject, limits.signIn.windowSeconds… the admin changes them without a redeploy
+export const limitSettings = rateLimitSettings({ signIn: { perIp: 30, perSubject: 10, windowSeconds: 900 }, me: { perIp: 600, windowSeconds: 3600 } });
+
+const limiter = createLimiter({
+  store: dbLimitStore(query),                       // or memoryLimitStore() in one process and in tests
+  clock: { now: () => new Date() },
+  limits: limitsFromSettings((key) => settings.get(key)), // or a plain table: { signIn: { perIp: 30, perSubject: 10, windowSeconds: 900 } }
+  onStoreError: (error, action) => log.error({ error, action }),
+});
+
+// in a route
+await limiter.enforce("signIn", { ip: clientIp(req.headers, rules), subject: email }); // throws RateLimited: status 429, headers { "Retry-After" }
+const verdict = await limiter.check("signIn", keys); // { ok: true } | { ok: false, retryAfterSeconds, scope: "ip" | "subject" }
+await limiter.forget("signIn", keys); // a successful sign-in clears its failures
+```
+
+- **The semantics of the copies**, so their tests pass unchanged: a window starts at its first hit and lasts `windowSeconds`; a refused hit is counted too; the address is counted first and a refusal stops there; the subject is compared in lower case and counted only when the action has a `perSubject` limit and one is given; an unknown address is counted under `unknown`. The old call `limit("sign-in", req, email, [30, 900], [10, 900])` is `enforce("signIn", { ip, subject: email })` with `{ perIp: 30, perSubject: 10, windowSeconds: 900 }` in the settings.
+- **The limiter takes keys, never a request.** The client's address is extracted by `clientIp` of `@krizaka/auth`; the package reads no header.
+- **Limits are settings.** `rateLimitSettings` (`@krizaka/rate-limit/settings`, needs `@krizaka/settings` and `zod`) declares `limits.<action>.perIp`, `.perSubject` and `.windowSeconds` as integers with the product's defaults; `limitsFromSettings` reads them back at each check. An action id is letters and digits (`signIn`), because it sits in a settings key.
+- **Stores:** `memoryLimitStore({ maxKeys })` keeps the copies' bound (10 000 windows; ended ones dropped first, then one shared overflow window, so a flood of keys limits itself and never clears a blocked caller's count). `dbLimitStore(query, { schema })` counts in **one atomic statement** (`INSERT … ON CONFLICT DO UPDATE … RETURNING`), so 100 parallel checks count exactly and every instance sees the same counters; times come from the injected clock, not the database's. The table is `rate_limit.bucket (key, count, window_start, reset_at)`, one row per key (a deviation from `(key, window_start)` as primary key: with the first hit starting the window, two concurrent first hits would otherwise open two rows). `purge(now)` deletes the ended windows: call it from the product's job.
+- **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.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import * as _krizaka_db from '@krizaka/db';
+import { Clock, Query } from '@krizaka/db';
+import { L as LimitKeys, C as CheckResult, a as LimitStore, b as LimitsSource } from './port-DCGtrBSX.js';
+export { A as ActionLimit, B as BucketHit, R as RATE_LIMIT_CODE, c as RateLimitCode, d as RateLimited } from './port-DCGtrBSX.js';
+
+interface LimiterDeps {
+    store: LimitStore;
+    clock: Clock;
+    /** The limits by action: a table, or a function reading the admin's settings at each check (see `@krizaka/rate-limit/settings`). */
+    limits: LimitsSource;
+    /**
+     * What a store that fails does: `true` (the default) lets the request through, so a limiter outage never takes the site down;
+     * `false` refuses it by rethrowing. Either way `onStoreError` hears of it.
+     */
+    failOpen?: boolean;
+    /** Told of every store failure (log it). */
+    onStoreError?: (error: unknown, action: string) => void;
+}
+interface Limiter {
+    /** Counts one hit for the action on the address and the subject, address first; the first limit exceeded refuses. */
+    check(action: string, keys: LimitKeys): Promise<CheckResult>;
+    /** `check`, throwing `RateLimited` (429 with `Retry-After`) on a refusal: the shape of the copies' `limit(…)`. */
+    enforce(action: string, keys: LimitKeys): Promise<void>;
+    /** Forgets the action's counters of these keys: a successful sign-in clears its failures. */
+    forget(action: string, keys: LimitKeys): Promise<void>;
+}
+/**
+ * The limiter of a product: fixed windows per address and per subject for each action, the limits from a table or from settings.
+ * The semantics are the copies' (`limit(action, req, subject, perIp, perSubject)`): a window starts at its first hit; a refused hit is
+ * counted too; the subject is only counted when a subject is given and the action limits it.
+ * @throws RangeError when an action has no limits, or limits that are not whole numbers from 1
+ */
+declare function createLimiter(deps: LimiterDeps): Limiter;
+
+/** The memory bound of the in-process store, not a business parameter. */
+declare const DEFAULT_MAX_KEYS = 10000;
+/**
+ * Counters kept in this process: fine for one instance, and for tests; a second instance needs `dbLimitStore`. Behaves like the copies
+ * Yomizaka, Akinaza and Kachizaka carried: when `maxKeys` live windows are held, the ended ones are dropped first, and if it is still
+ * full a new key shares ONE overflow window instead, so a flood of keys limits itself and never hands a blocked caller a fresh count.
+ * @param options `maxKeys`: the most windows held
+ */
+declare function memoryLimitStore(options?: {
+    maxKeys?: number;
+}): LimitStore;
+/** How long until a window ends, in whole seconds, at least one: the `Retry-After` of a refusal. */
+declare function retryAfterSeconds(resetAt: Date, now: Date): number;
+
+/**
+ * The counters shared by every instance, in `rate_limit.bucket` (see `rateLimitSchema`; the schema may be renamed by the product).
+ * `hit` is ONE atomic statement — `INSERT … ON CONFLICT DO UPDATE … RETURNING` — so the row lock serialises concurrent hits and
+ * they are counted exactly; an ended window restarts at 1 in the same statement. Times come from the caller (the injected clock),
+ * never from the database's `now()`.
+ * @param query the product's query (its pool, or a transaction's client)
+ * @param options `schema`: the Postgres schema of the module, default `rate_limit`
+ */
+declare function dbLimitStore(query: Query, options?: {
+    schema?: string;
+}): LimitStore;
+
+/**
+ * The table of counters of « rate-limit », in its own Postgres schema (ADR-001 §3). One row per key holds the open window: its count,
+ * when it started and when it ends. It references no product table. Version 1 is frozen once released: a change is version 2.
+ */
+declare const rateLimitSchema: _krizaka_db.ModuleSchema;
+
+export { CheckResult, DEFAULT_MAX_KEYS, LimitKeys, LimitStore, type Limiter, type LimiterDeps, LimitsSource, createLimiter, dbLimitStore, memoryLimitStore, rateLimitSchema, retryAfterSeconds };

package/dist/index.js

@@ -0,0 +1,194 @@
+// src/memory.ts
+import { addSeconds, differenceInMilliseconds, isAfter } from "@krizaka/time";
+var DEFAULT_MAX_KEYS = 1e4;
+var OVERFLOW = "overflow";
+function memoryLimitStore(options = {}) {
+  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+  const windows = /* @__PURE__ */ new Map();
+  const live = (entry, now) => !!entry && isAfter(entry.resetAt, now);
+  function prune(now) {
+    let dropped = 0;
+    for (const [key, entry] of windows) {
+      if (!live(entry, now)) {
+        windows.delete(key);
+        dropped += 1;
+      }
+    }
+    return dropped;
+  }
+  return {
+    async hit(key, windowSeconds, now) {
+      let slot = key;
+      let entry = windows.get(slot);
+      if (!live(entry, now)) {
+        if (windows.size >= maxKeys) prune(now);
+        slot = windows.size >= maxKeys ? OVERFLOW : key;
+        entry = windows.get(slot);
+        if (!live(entry, now)) {
+          entry = { count: 0, resetAt: addSeconds(now, windowSeconds) };
+          windows.set(slot, entry);
+        }
+      }
+      entry.count += 1;
+      return { count: entry.count, resetAt: entry.resetAt };
+    },
+    async peek(key, now) {
+      const entry = windows.get(key);
+      return live(entry, now) ? { ...entry } : null;
+    },
+    async set(key, count, seconds, now) {
+      if (!windows.has(key) && windows.size >= maxKeys) prune(now);
+      windows.set(key, { count, resetAt: addSeconds(now, seconds) });
+    },
+    async reset(key) {
+      windows.delete(key);
+    },
+    async purge(now) {
+      return prune(now);
+    }
+  };
+}
+function retryAfterSeconds(resetAt, now) {
+  return Math.max(1, Math.ceil(differenceInMilliseconds(resetAt, now) / 1e3));
+}
+
+// src/port.ts
+var RATE_LIMIT_CODE = {
+  limited: "RATE_LIMITED",
+  noLimits: "RATE_LIMIT_NO_LIMITS",
+  badLimit: "RATE_LIMIT_BAD_LIMIT"
+};
+var RateLimited = class extends Error {
+  constructor(retryAfterSeconds2, scope) {
+    super("Too many requests");
+    this.retryAfterSeconds = retryAfterSeconds2;
+    this.scope = scope;
+    this.name = "RateLimited";
+  }
+  retryAfterSeconds;
+  scope;
+  status = 429;
+  code = RATE_LIMIT_CODE.limited;
+  /** The header to send with the 429. */
+  get headers() {
+    return { "Retry-After": String(this.retryAfterSeconds) };
+  }
+};
+
+// src/limiter.ts
+var ipKey = (action, ip) => `${action}:ip:${ip ?? "unknown"}`;
+var subjectKey = (action, subject) => `${action}:s:${subject.toLowerCase()}`;
+function checked(action, limit) {
+  if (!limit) throw new RangeError(`${RATE_LIMIT_CODE.noLimits}: no limits declared for the action \xAB ${action} \xBB`);
+  const whole = (value) => value === void 0 || Number.isInteger(value) && value >= 1;
+  if (!Number.isInteger(limit.windowSeconds) || limit.windowSeconds < 1 || !whole(limit.perIp) || !whole(limit.perSubject)) {
+    throw new RangeError(`${RATE_LIMIT_CODE.badLimit}: \xAB ${action} \xBB needs whole numbers from 1 (windowSeconds ${limit.windowSeconds}, perIp ${limit.perIp}, perSubject ${limit.perSubject})`);
+  }
+  return limit;
+}
+function createLimiter(deps) {
+  const limitsOf = async (action) => checked(action, typeof deps.limits === "function" ? await deps.limits(action) : deps.limits[action]);
+  async function guarded(action, work, whenFailed) {
+    try {
+      return await work();
+    } catch (error) {
+      deps.onStoreError?.(error, action);
+      if (deps.failOpen === false) throw error;
+      return whenFailed;
+    }
+  }
+  async function check(action, keys) {
+    const limit = await limitsOf(action);
+    const now = deps.clock.now();
+    const counters = [];
+    if (limit.perIp !== void 0) counters.push({ scope: "ip", key: ipKey(action, keys.ip), max: limit.perIp });
+    if (limit.perSubject !== void 0 && keys.subject) counters.push({ scope: "subject", key: subjectKey(action, keys.subject), max: limit.perSubject });
+    for (const { scope, key, max } of counters) {
+      const hit = await guarded(action, () => deps.store.hit(key, limit.windowSeconds, now), null);
+      if (hit && hit.count > max) return { ok: false, retryAfterSeconds: retryAfterSeconds(hit.resetAt, now), scope };
+    }
+    return { ok: true };
+  }
+  return {
+    check,
+    async enforce(action, keys) {
+      const result = await check(action, keys);
+      if (!result.ok) throw new RateLimited(result.retryAfterSeconds, result.scope);
+    },
+    async forget(action, keys) {
+      const keysToForget = [ipKey(action, keys.ip), ...keys.subject ? [subjectKey(action, keys.subject)] : []];
+      for (const key of keysToForget) await guarded(action, () => deps.store.reset(key), void 0);
+    }
+  };
+}
+
+// src/persistence.ts
+import { ident } from "@krizaka/db";
+import { addSeconds as addSeconds2 } from "@krizaka/time";
+var toHit = (row) => ({ count: Number(row.count), resetAt: new Date(row.reset_at) });
+function dbLimitStore(query, options = {}) {
+  const bucket = `${ident(options.schema ?? "rate_limit")}.bucket`;
+  return {
+    async hit(key, windowSeconds, now) {
+      const [row] = await query(
+        `INSERT INTO ${bucket} AS b (key, count, window_start, reset_at) VALUES ($1, 1, $2, $3)
+         ON CONFLICT (key) DO UPDATE SET
+           count        = CASE WHEN b.reset_at <= $2 THEN 1 ELSE b.count + 1 END,
+           window_start = CASE WHEN b.reset_at <= $2 THEN $2 ELSE b.window_start END,
+           reset_at     = CASE WHEN b.reset_at <= $2 THEN $3 ELSE b.reset_at END
+         RETURNING count, reset_at`,
+        [key, now, addSeconds2(now, windowSeconds)]
+      );
+      return toHit(row);
+    },
+    async peek(key, now) {
+      const [row] = await query(`SELECT count, reset_at FROM ${bucket} WHERE key = $1 AND reset_at > $2`, [key, now]);
+      return row ? toHit(row) : null;
+    },
+    async set(key, count, seconds, now) {
+      await query(
+        `INSERT INTO ${bucket} (key, count, window_start, reset_at) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (key) DO UPDATE SET count = excluded.count, window_start = excluded.window_start, reset_at = excluded.reset_at`,
+        [key, count, now, addSeconds2(now, seconds)]
+      );
+    },
+    async reset(key) {
+      await query(`DELETE FROM ${bucket} WHERE key = $1`, [key]);
+    },
+    async purge(now) {
+      const rows = await query(`DELETE FROM ${bucket} WHERE reset_at <= $1 RETURNING 1`, [now]);
+      return rows.length;
+    }
+  };
+}
+
+// src/schema.ts
+import { defineModule } from "@krizaka/db";
+var rateLimitSchema = defineModule({
+  module: "rate_limit",
+  migrations: [
+    {
+      version: 1,
+      name: "buckets",
+      sql: (c) => `
+CREATE TABLE ${c.schema}.bucket (
+  key          text PRIMARY KEY CHECK (char_length(key) BETWEEN 1 AND 300),
+  count        integer NOT NULL CHECK (count >= 0),
+  window_start timestamptz NOT NULL,
+  reset_at     timestamptz NOT NULL
+);
+CREATE INDEX bucket_reset_at ON ${c.schema}.bucket (reset_at);`
+    }
+  ]
+});
+export {
+  DEFAULT_MAX_KEYS,
+  RATE_LIMIT_CODE,
+  RateLimited,
+  createLimiter,
+  dbLimitStore,
+  memoryLimitStore,
+  rateLimitSchema,
+  retryAfterSeconds
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory.ts","../src/port.ts","../src/limiter.ts","../src/persistence.ts","../src/schema.ts"],"sourcesContent":["import { addSeconds, differenceInMilliseconds, isAfter } from \"@krizaka/time\";\n\nimport type { BucketHit, LimitStore } from \"./port\";\n\n/** The memory bound of the in-process store, not a business parameter. */\n// @fixed: bounds the memory a flood of distinct keys can take\nexport const DEFAULT_MAX_KEYS = 10_000;\nconst OVERFLOW = \"overflow\";\n\n/**\n * Counters kept in this process: fine for one instance, and for tests; a second instance needs `dbLimitStore`. Behaves like the copies\n * Yomizaka, Akinaza and Kachizaka carried: when `maxKeys` live windows are held, the ended ones are dropped first, and if it is still\n * full a new key shares ONE overflow window instead, so a flood of keys limits itself and never hands a blocked caller a fresh count.\n * @param options `maxKeys`: the most windows held\n */\nexport function memoryLimitStore(options: { maxKeys?: number } = {}): LimitStore {\n  const maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;\n  const windows = new Map<string, BucketHit>();\n  const live = (entry: BucketHit | undefined, now: Date): entry is BucketHit => !!entry && isAfter(entry.resetAt, now);\n\n  function prune(now: Date): number {\n    let dropped = 0;\n    for (const [key, entry] of windows) {\n      if (!live(entry, now)) {\n        windows.delete(key);\n        dropped += 1;\n      }\n    }\n    return dropped;\n  }\n\n  return {\n    async hit(key, windowSeconds, now) {\n      let slot = key;\n      let entry = windows.get(slot);\n      if (!live(entry, now)) {\n        if (windows.size >= maxKeys) prune(now);\n        slot = windows.size >= maxKeys ? OVERFLOW : key;\n        entry = windows.get(slot);\n        if (!live(entry, now)) {\n          entry = { count: 0, resetAt: addSeconds(now, windowSeconds) };\n          windows.set(slot, entry);\n        }\n      }\n      entry.count += 1;\n      return { count: entry.count, resetAt: entry.resetAt };\n    },\n    async peek(key, now) {\n      const entry = windows.get(key);\n      return live(entry, now) ? { ...entry } : null;\n    },\n    async set(key, count, seconds, now) {\n      if (!windows.has(key) && windows.size >= maxKeys) prune(now);\n      windows.set(key, { count, resetAt: addSeconds(now, seconds) });\n    },\n    async reset(key) {\n      windows.delete(key);\n    },\n    async purge(now) {\n      return prune(now);\n    },\n  };\n}\n\n/** How long until a window ends, in whole seconds, at least one: the `Retry-After` of a refusal. */\nexport function retryAfterSeconds(resetAt: Date, now: Date): number {\n  return Math.max(1, Math.ceil(differenceInMilliseconds(resetAt, now) / 1000));\n}\n","/**\n * The ports of « rate-limit »: nothing here knows a request, a database client, an environment variable or the wall clock. The\n * product extracts the keys (an address, a subject) and the limiter counts them.\n */\n\n/** The state of a counter's window after a hit: how many hits it holds, and when it ends. */\nexport interface BucketHit {\n  count: number;\n  resetAt: Date;\n}\n\n/**\n * Where counters live: a fixed window per key, started by its first hit and lasting `windowSeconds`. A hit after the window ended\n * starts a new one. Adapters: `memoryLimitStore` (one process) and `dbLimitStore` (shared by every instance).\n */\nexport interface LimitStore {\n  /** Counts one hit on `key` and returns the window it fell in. Atomic: concurrent hits are counted exactly. */\n  hit(key: string, windowSeconds: number, now: Date): Promise<BucketHit>;\n  /** The open window of `key`, without counting; null when none is open. */\n  peek(key: string, now: Date): Promise<BucketHit | null>;\n  /** Opens (or replaces) a window holding `count` that ends `seconds` from now: a lock-out. */\n  set(key: string, count: number, seconds: number, now: Date): Promise<void>;\n  /** Forgets `key` (a successful sign-in clears its failures). */\n  reset(key: string): Promise<void>;\n  /** Drops the windows that ended; returns how many. The product's job calls it. */\n  purge(now: Date): Promise<number>;\n}\n\n/** What one action allows in one window. Each of `perIp` and `perSubject` is optional: absent means that key is not limited. */\nexport interface ActionLimit {\n  /** Hits an address may make in the window. */\n  perIp?: number;\n  /** Hits a subject (an e-mail address, an account id) may make in the window. */\n  perSubject?: number;\n  /** The window's length in seconds. */\n  windowSeconds: number;\n}\n\n/**\n * The limits, by action: a table, or a function that answers for an action (so the product can read them from its settings at each\n * check). `undefined` for an action nobody declared is a programming error and throws.\n */\nexport type LimitsSource = Readonly<Record<string, ActionLimit>> | ((action: string) => ActionLimit | undefined | Promise<ActionLimit | undefined>);\n\n/** The keys one check counts. The limiter receives keys, never a request: extract the address with `clientIp` of `@krizaka/auth`. */\nexport interface LimitKeys {\n  /** The client's address; null (unknown) is counted under `unknown`, like the copies did. */\n  ip?: string | null | undefined;\n  /** The subject: an address, an account. Compared in lower case. Counted only when the action has a `perSubject` limit. */\n  subject?: string | null | undefined;\n}\n\n/** A hit allowed, or refused with when to come back. */\nexport type CheckResult = { ok: true } | { ok: false; retryAfterSeconds: number; scope: \"ip\" | \"subject\" };\n\n/** Stable codes of this package's errors. */\nexport const RATE_LIMIT_CODE = {\n  limited: \"RATE_LIMITED\",\n  noLimits: \"RATE_LIMIT_NO_LIMITS\",\n  badLimit: \"RATE_LIMIT_BAD_LIMIT\",\n} as const;\nexport type RateLimitCode = (typeof RATE_LIMIT_CODE)[keyof typeof RATE_LIMIT_CODE];\n\n/** A refusal: HTTP 429, with the seconds to wait (the `Retry-After` header). */\nexport class RateLimited extends Error {\n  readonly status = 429;\n  readonly code = RATE_LIMIT_CODE.limited;\n  constructor(\n    readonly retryAfterSeconds: number,\n    readonly scope: \"ip\" | \"subject\",\n  ) {\n    super(\"Too many requests\");\n    this.name = \"RateLimited\";\n  }\n\n  /** The header to send with the 429. */\n  get headers(): { \"Retry-After\": string } {\n    return { \"Retry-After\": String(this.retryAfterSeconds) };\n  }\n}\n","import type { Clock } from \"@krizaka/db\";\n\nimport { retryAfterSeconds } from \"./memory\";\nimport { type ActionLimit, type CheckResult, type LimitKeys, type LimitsSource, type LimitStore, RATE_LIMIT_CODE, RateLimited } from \"./port\";\n\nexport interface LimiterDeps {\n  store: LimitStore;\n  clock: Clock;\n  /** The limits by action: a table, or a function reading the admin's settings at each check (see `@krizaka/rate-limit/settings`). */\n  limits: LimitsSource;\n  /**\n   * What a store that fails does: `true` (the default) lets the request through, so a limiter outage never takes the site down;\n   * `false` refuses it by rethrowing. Either way `onStoreError` hears of it.\n   */\n  failOpen?: boolean;\n  /** Told of every store failure (log it). */\n  onStoreError?: (error: unknown, action: string) => void;\n}\n\nexport interface Limiter {\n  /** Counts one hit for the action on the address and the subject, address first; the first limit exceeded refuses. */\n  check(action: string, keys: LimitKeys): Promise<CheckResult>;\n  /** `check`, throwing `RateLimited` (429 with `Retry-After`) on a refusal: the shape of the copies' `limit(…)`. */\n  enforce(action: string, keys: LimitKeys): Promise<void>;\n  /** Forgets the action's counters of these keys: a successful sign-in clears its failures. */\n  forget(action: string, keys: LimitKeys): Promise<void>;\n}\n\nconst ipKey = (action: string, ip: string | null | undefined) => `${action}:ip:${ip ?? \"unknown\"}`;\nconst subjectKey = (action: string, subject: string) => `${action}:s:${subject.toLowerCase()}`;\n\nfunction checked(action: string, limit: ActionLimit | undefined): ActionLimit {\n  if (!limit) throw new RangeError(`${RATE_LIMIT_CODE.noLimits}: no limits declared for the action « ${action} »`);\n  const whole = (value: number | undefined) => value === undefined || (Number.isInteger(value) && value >= 1);\n  if (!Number.isInteger(limit.windowSeconds) || limit.windowSeconds < 1 || !whole(limit.perIp) || !whole(limit.perSubject)) {\n    throw new RangeError(`${RATE_LIMIT_CODE.badLimit}: « ${action} » needs whole numbers from 1 (windowSeconds ${limit.windowSeconds}, perIp ${limit.perIp}, perSubject ${limit.perSubject})`);\n  }\n  return limit;\n}\n\n/**\n * The limiter of a product: fixed windows per address and per subject for each action, the limits from a table or from settings.\n * The semantics are the copies' (`limit(action, req, subject, perIp, perSubject)`): a window starts at its first hit; a refused hit is\n * counted too; the subject is only counted when a subject is given and the action limits it.\n * @throws RangeError when an action has no limits, or limits that are not whole numbers from 1\n */\nexport function createLimiter(deps: LimiterDeps): Limiter {\n  const limitsOf = async (action: string): Promise<ActionLimit> => checked(action, typeof deps.limits === \"function\" ? await deps.limits(action) : deps.limits[action]);\n\n  async function guarded<T>(action: string, work: () => Promise<T>, whenFailed: T): Promise<T> {\n    try {\n      return await work();\n    } catch (error) {\n      deps.onStoreError?.(error, action);\n      if (deps.failOpen === false) throw error;\n      return whenFailed;\n    }\n  }\n\n  async function check(action: string, keys: LimitKeys): Promise<CheckResult> {\n    const limit = await limitsOf(action);\n    const now = deps.clock.now();\n    const counters: { scope: \"ip\" | \"subject\"; key: string; max: number }[] = [];\n    if (limit.perIp !== undefined) counters.push({ scope: \"ip\", key: ipKey(action, keys.ip), max: limit.perIp });\n    if (limit.perSubject !== undefined && keys.subject) counters.push({ scope: \"subject\", key: subjectKey(action, keys.subject), max: limit.perSubject });\n    for (const { scope, key, max } of counters) {\n      const hit = await guarded(action, () => deps.store.hit(key, limit.windowSeconds, now), null);\n      if (hit && hit.count > max) return { ok: false, retryAfterSeconds: retryAfterSeconds(hit.resetAt, now), scope };\n    }\n    return { ok: true };\n  }\n\n  return {\n    check,\n    async enforce(action, keys) {\n      const result = await check(action, keys);\n      if (!result.ok) throw new RateLimited(result.retryAfterSeconds, result.scope);\n    },\n    async forget(action, keys) {\n      const keysToForget = [ipKey(action, keys.ip), ...(keys.subject ? [subjectKey(action, keys.subject)] : [])];\n      for (const key of keysToForget) await guarded(action, () => deps.store.reset(key), undefined);\n    },\n  };\n}\n","import { ident, type Query } from \"@krizaka/db\";\nimport { addSeconds } from \"@krizaka/time\";\n\nimport type { BucketHit, LimitStore } from \"./port\";\n\ninterface Row {\n  count: number;\n  reset_at: Date | string;\n}\nconst toHit = (row: Row): BucketHit => ({ count: Number(row.count), resetAt: new Date(row.reset_at) });\n\n/**\n * The counters shared by every instance, in `rate_limit.bucket` (see `rateLimitSchema`; the schema may be renamed by the product).\n * `hit` is ONE atomic statement — `INSERT … ON CONFLICT DO UPDATE … RETURNING` — so the row lock serialises concurrent hits and\n * they are counted exactly; an ended window restarts at 1 in the same statement. Times come from the caller (the injected clock),\n * never from the database's `now()`.\n * @param query the product's query (its pool, or a transaction's client)\n * @param options `schema`: the Postgres schema of the module, default `rate_limit`\n */\nexport function dbLimitStore(query: Query, options: { schema?: string } = {}): LimitStore {\n  const bucket = `${ident(options.schema ?? \"rate_limit\")}.bucket`;\n  return {\n    async hit(key, windowSeconds, now) {\n      const [row] = await query<Row>(\n        `INSERT INTO ${bucket} AS b (key, count, window_start, reset_at) VALUES ($1, 1, $2, $3)\n         ON CONFLICT (key) DO UPDATE SET\n           count        = CASE WHEN b.reset_at <= $2 THEN 1 ELSE b.count + 1 END,\n           window_start = CASE WHEN b.reset_at <= $2 THEN $2 ELSE b.window_start END,\n           reset_at     = CASE WHEN b.reset_at <= $2 THEN $3 ELSE b.reset_at END\n         RETURNING count, reset_at`,\n        [key, now, addSeconds(now, windowSeconds)],\n      );\n      return toHit(row!);\n    },\n    async peek(key, now) {\n      const [row] = await query<Row>(`SELECT count, reset_at FROM ${bucket} WHERE key = $1 AND reset_at > $2`, [key, now]);\n      return row ? toHit(row) : null;\n    },\n    async set(key, count, seconds, now) {\n      await query(\n        `INSERT INTO ${bucket} (key, count, window_start, reset_at) VALUES ($1, $2, $3, $4)\n         ON CONFLICT (key) DO UPDATE SET count = excluded.count, window_start = excluded.window_start, reset_at = excluded.reset_at`,\n        [key, count, now, addSeconds(now, seconds)],\n      );\n    },\n    async reset(key) {\n      await query(`DELETE FROM ${bucket} WHERE key = $1`, [key]);\n    },\n    async purge(now) {\n      const rows = await query(`DELETE FROM ${bucket} WHERE reset_at <= $1 RETURNING 1`, [now]);\n      return rows.length;\n    },\n  };\n}\n","import { defineModule } from \"@krizaka/db\";\n\n/**\n * The table of counters of « rate-limit », in its own Postgres schema (ADR-001 §3). One row per key holds the open window: its count,\n * when it started and when it ends. It references no product table. Version 1 is frozen once released: a change is version 2.\n */\nexport const rateLimitSchema = defineModule({\n  module: \"rate_limit\",\n  migrations: [\n    {\n      version: 1,\n      name: \"buckets\",\n      sql: (c) => `\nCREATE TABLE ${c.schema}.bucket (\n  key          text PRIMARY KEY CHECK (char_length(key) BETWEEN 1 AND 300),\n  count        integer NOT NULL CHECK (count >= 0),\n  window_start timestamptz NOT NULL,\n  reset_at     timestamptz NOT NULL\n);\nCREATE INDEX bucket_reset_at ON ${c.schema}.bucket (reset_at);`,\n    },\n  ],\n});\n"],"mappings":"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","names":["retryAfterSeconds","addSeconds"]}

package/dist/port-DCGtrBSX.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The ports of « rate-limit »: nothing here knows a request, a database client, an environment variable or the wall clock. The
+ * product extracts the keys (an address, a subject) and the limiter counts them.
+ */
+/** The state of a counter's window after a hit: how many hits it holds, and when it ends. */
+interface BucketHit {
+    count: number;
+    resetAt: Date;
+}
+/**
+ * Where counters live: a fixed window per key, started by its first hit and lasting `windowSeconds`. A hit after the window ended
+ * starts a new one. Adapters: `memoryLimitStore` (one process) and `dbLimitStore` (shared by every instance).
+ */
+interface LimitStore {
+    /** Counts one hit on `key` and returns the window it fell in. Atomic: concurrent hits are counted exactly. */
+    hit(key: string, windowSeconds: number, now: Date): Promise<BucketHit>;
+    /** The open window of `key`, without counting; null when none is open. */
+    peek(key: string, now: Date): Promise<BucketHit | null>;
+    /** Opens (or replaces) a window holding `count` that ends `seconds` from now: a lock-out. */
+    set(key: string, count: number, seconds: number, now: Date): Promise<void>;
+    /** Forgets `key` (a successful sign-in clears its failures). */
+    reset(key: string): Promise<void>;
+    /** Drops the windows that ended; returns how many. The product's job calls it. */
+    purge(now: Date): Promise<number>;
+}
+/** What one action allows in one window. Each of `perIp` and `perSubject` is optional: absent means that key is not limited. */
+interface ActionLimit {
+    /** Hits an address may make in the window. */
+    perIp?: number;
+    /** Hits a subject (an e-mail address, an account id) may make in the window. */
+    perSubject?: number;
+    /** The window's length in seconds. */
+    windowSeconds: number;
+}
+/**
+ * The limits, by action: a table, or a function that answers for an action (so the product can read them from its settings at each
+ * check). `undefined` for an action nobody declared is a programming error and throws.
+ */
+type LimitsSource = Readonly<Record<string, ActionLimit>> | ((action: string) => ActionLimit | undefined | Promise<ActionLimit | undefined>);
+/** The keys one check counts. The limiter receives keys, never a request: extract the address with `clientIp` of `@krizaka/auth`. */
+interface LimitKeys {
+    /** The client's address; null (unknown) is counted under `unknown`, like the copies did. */
+    ip?: string | null | undefined;
+    /** The subject: an address, an account. Compared in lower case. Counted only when the action has a `perSubject` limit. */
+    subject?: string | null | undefined;
+}
+/** A hit allowed, or refused with when to come back. */
+type CheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    retryAfterSeconds: number;
+    scope: "ip" | "subject";
+};
+/** Stable codes of this package's errors. */
+declare const RATE_LIMIT_CODE: {
+    readonly limited: "RATE_LIMITED";
+    readonly noLimits: "RATE_LIMIT_NO_LIMITS";
+    readonly badLimit: "RATE_LIMIT_BAD_LIMIT";
+};
+type RateLimitCode = (typeof RATE_LIMIT_CODE)[keyof typeof RATE_LIMIT_CODE];
+/** A refusal: HTTP 429, with the seconds to wait (the `Retry-After` header). */
+declare class RateLimited extends Error {
+    readonly retryAfterSeconds: number;
+    readonly scope: "ip" | "subject";
+    readonly status = 429;
+    readonly code: "RATE_LIMITED";
+    constructor(retryAfterSeconds: number, scope: "ip" | "subject");
+    /** The header to send with the 429. */
+    get headers(): {
+        "Retry-After": string;
+    };
+}
+
+export { type ActionLimit as A, type BucketHit as B, type CheckResult as C, type LimitKeys as L, RATE_LIMIT_CODE as R, type LimitStore as a, type LimitsSource as b, type RateLimitCode as c, RateLimited as d };

package/dist/settings.d.ts

@@ -0,0 +1,24 @@
+import { Registry } from '@krizaka/settings';
+import { A as ActionLimit } from './port-DCGtrBSX.js';
+
+/** What a product declares for an action: the defaults the admin can then change. */
+interface ActionDefaults {
+    perIp?: number;
+    perSubject?: number;
+    windowSeconds: number;
+}
+/**
+ * The registry fragment of the limits: `limits.<action>.perIp`, `limits.<action>.perSubject` (when the action has one) and
+ * `limits.<action>.windowSeconds`, each an integer with the product's default and bounds. Global scope. The admin changes a limit
+ * without a redeploy; `limitsFromSettings` reads them back for the limiter.
+ * @param actions the product's actions, by id (camelCase: `signIn`, `passwordForgot`), with their defaults
+ * @throws RangeError for an action id that cannot be part of a settings key
+ */
+declare function rateLimitSettings(actions: Readonly<Record<string, ActionDefaults>>): Registry;
+/**
+ * The limiter's `limits` function over the settings: it reads the keys of an action. `read` is the product's accessor
+ * (`(key) => service.get(key, ctx)`); a key the action does not declare answers `undefined` and is left out.
+ */
+declare function limitsFromSettings(read: (key: string) => number | undefined | Promise<number | undefined>): (action: string) => Promise<ActionLimit | undefined>;
+
+export { type ActionDefaults, limitsFromSettings, rateLimitSettings };

package/dist/settings.js

@@ -0,0 +1,27 @@
+// src/settings.ts
+import { integer } from "@krizaka/settings";
+var ACTION_ID = /^[a-z][A-Za-z0-9]{0,39}$/;
+function rateLimitSettings(actions) {
+  const fragment = {};
+  for (const [action, defaults] of Object.entries(actions)) {
+    if (!ACTION_ID.test(action)) throw new RangeError(`rate-limit action \xAB ${action} \xBB: use letters and digits, starting with a lower-case letter (it is part of a settings key)`);
+    if (defaults.perIp !== void 0) fragment[`limits.${action}.perIp`] = integer("limits", defaults.perIp, { min: 1, max: 1e6, unit: "hits" });
+    if (defaults.perSubject !== void 0) fragment[`limits.${action}.perSubject`] = integer("limits", defaults.perSubject, { min: 1, max: 1e6, unit: "hits" });
+    fragment[`limits.${action}.windowSeconds`] = integer("limits", defaults.windowSeconds, { min: 1, max: 86400, unit: "seconds" });
+  }
+  return fragment;
+}
+function limitsFromSettings(read) {
+  return async (action) => {
+    const windowSeconds = await read(`limits.${action}.windowSeconds`);
+    if (windowSeconds === void 0) return void 0;
+    const perIp = await read(`limits.${action}.perIp`);
+    const perSubject = await read(`limits.${action}.perSubject`);
+    return { windowSeconds, ...perIp === void 0 ? {} : { perIp }, ...perSubject === void 0 ? {} : { perSubject } };
+  };
+}
+export {
+  limitsFromSettings,
+  rateLimitSettings
+};
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/settings.ts"],"sourcesContent":["import { integer, type Registry } from \"@krizaka/settings\";\n\nimport type { ActionLimit } from \"./port\";\n\n/** What a product declares for an action: the defaults the admin can then change. */\nexport interface ActionDefaults {\n  perIp?: number;\n  perSubject?: number;\n  windowSeconds: number;\n}\n\n/** An action id that can sit in a settings key (`limits.signIn.perIp`): letters and digits, starting with a lower-case letter. */\nconst ACTION_ID = /^[a-z][A-Za-z0-9]{0,39}$/;\n\n/**\n * The registry fragment of the limits: `limits.<action>.perIp`, `limits.<action>.perSubject` (when the action has one) and\n * `limits.<action>.windowSeconds`, each an integer with the product's default and bounds. Global scope. The admin changes a limit\n * without a redeploy; `limitsFromSettings` reads them back for the limiter.\n * @param actions the product's actions, by id (camelCase: `signIn`, `passwordForgot`), with their defaults\n * @throws RangeError for an action id that cannot be part of a settings key\n */\nexport function rateLimitSettings(actions: Readonly<Record<string, ActionDefaults>>): Registry {\n  const fragment: Registry = {};\n  for (const [action, defaults] of Object.entries(actions)) {\n    if (!ACTION_ID.test(action)) throw new RangeError(`rate-limit action « ${action} »: use letters and digits, starting with a lower-case letter (it is part of a settings key)`);\n    // @fixed: an admin may set 1 to a million hits and a window of a second to a day; the defaults are the product's\n    if (defaults.perIp !== undefined) fragment[`limits.${action}.perIp`] = integer(\"limits\", defaults.perIp, { min: 1, max: 1_000_000, unit: \"hits\" });\n    if (defaults.perSubject !== undefined) fragment[`limits.${action}.perSubject`] = integer(\"limits\", defaults.perSubject, { min: 1, max: 1_000_000, unit: \"hits\" });\n    fragment[`limits.${action}.windowSeconds`] = integer(\"limits\", defaults.windowSeconds, { min: 1, max: 86_400, unit: \"seconds\" });\n  }\n  return fragment;\n}\n\n/**\n * The limiter's `limits` function over the settings: it reads the keys of an action. `read` is the product's accessor\n * (`(key) => service.get(key, ctx)`); a key the action does not declare answers `undefined` and is left out.\n */\nexport function limitsFromSettings(read: (key: string) => number | undefined | Promise<number | undefined>): (action: string) => Promise<ActionLimit | undefined> {\n  return async (action) => {\n    const windowSeconds = await read(`limits.${action}.windowSeconds`);\n    if (windowSeconds === undefined) return undefined;\n    const perIp = await read(`limits.${action}.perIp`);\n    const perSubject = await read(`limits.${action}.perSubject`);\n    return { windowSeconds, ...(perIp === undefined ? {} : { perIp }), ...(perSubject === undefined ? {} : { perSubject }) };\n  };\n}\n"],"mappings":";AAAA,SAAS,eAA8B;AAYvC,IAAM,YAAY;AASX,SAAS,kBAAkB,SAA6D;AAC7F,QAAM,WAAqB,CAAC;AAC5B,aAAW,CAAC,QAAQ,QAAQ,KAAK,OAAO,QAAQ,OAAO,GAAG;AACxD,QAAI,CAAC,UAAU,KAAK,MAAM,EAAG,OAAM,IAAI,WAAW,0BAAuB,MAAM,iGAA8F;AAE7K,QAAI,SAAS,UAAU,OAAW,UAAS,UAAU,MAAM,QAAQ,IAAI,QAAQ,UAAU,SAAS,OAAO,EAAE,KAAK,GAAG,KAAK,KAAW,MAAM,OAAO,CAAC;AACjJ,QAAI,SAAS,eAAe,OAAW,UAAS,UAAU,MAAM,aAAa,IAAI,QAAQ,UAAU,SAAS,YAAY,EAAE,KAAK,GAAG,KAAK,KAAW,MAAM,OAAO,CAAC;AAChK,aAAS,UAAU,MAAM,gBAAgB,IAAI,QAAQ,UAAU,SAAS,eAAe,EAAE,KAAK,GAAG,KAAK,OAAQ,MAAM,UAAU,CAAC;AAAA,EACjI;AACA,SAAO;AACT;AAMO,SAAS,mBAAmB,MAA+H;AAChK,SAAO,OAAO,WAAW;AACvB,UAAM,gBAAgB,MAAM,KAAK,UAAU,MAAM,gBAAgB;AACjE,QAAI,kBAAkB,OAAW,QAAO;AACxC,UAAM,QAAQ,MAAM,KAAK,UAAU,MAAM,QAAQ;AACjD,UAAM,aAAa,MAAM,KAAK,UAAU,MAAM,aAAa;AAC3D,WAAO,EAAE,eAAe,GAAI,UAAU,SAAY,CAAC,IAAI,EAAE,MAAM,GAAI,GAAI,eAAe,SAAY,CAAC,IAAI,EAAE,WAAW,EAAG;AAAA,EACzH;AACF;","names":[]}

package/dist/testkit.d.ts

@@ -0,0 +1,6 @@
+import { a as LimitStore } from './port-DCGtrBSX.js';
+
+/** What every `LimitStore` adapter must do: the same behaviour behind the same port. `make` gives a store with no counters. */
+declare function limitStoreContract(name: string, make: () => LimitStore | Promise<LimitStore>): void;
+
+export { limitStoreContract };

package/dist/testkit.js

@@ -0,0 +1,64 @@
+// src/testkit.ts
+import { expect, it } from "vitest";
+var T0 = /* @__PURE__ */ new Date("2026-10-26T12:00:00.000Z");
+var at = (seconds) => new Date(T0.valueOf() + seconds * 1e3);
+function limitStoreContract(name, make) {
+  it(`${name}: counts hits in a window that the first hit starts`, async () => {
+    const store = await make();
+    const first = await store.hit("k", 60, T0);
+    expect(first.count).toBe(1);
+    expect(first.resetAt.toISOString()).toBe(at(60).toISOString());
+    const later = await store.hit("k", 60, at(30));
+    expect(later.count).toBe(2);
+    expect(later.resetAt.toISOString()).toBe(at(60).toISOString());
+  });
+  it(`${name}: starts a new window when the last one has ended`, async () => {
+    const store = await make();
+    await store.hit("k", 60, T0);
+    await store.hit("k", 60, at(10));
+    const next = await store.hit("k", 60, at(60));
+    expect(next.count).toBe(1);
+    expect(next.resetAt.toISOString()).toBe(at(120).toISOString());
+  });
+  it(`${name}: keeps keys apart`, async () => {
+    const store = await make();
+    await store.hit("a", 60, T0);
+    await store.hit("a", 60, T0);
+    expect((await store.hit("b", 60, T0)).count).toBe(1);
+  });
+  it(`${name}: peeks without counting, and only while the window is open`, async () => {
+    const store = await make();
+    expect(await store.peek("k", T0)).toBeNull();
+    await store.hit("k", 60, T0);
+    expect((await store.peek("k", at(1)))?.count).toBe(1);
+    expect((await store.peek("k", at(1)))?.count).toBe(1);
+    expect(await store.peek("k", at(60))).toBeNull();
+  });
+  it(`${name}: opens a lock-out with set, and forgets with reset`, async () => {
+    const store = await make();
+    await store.set("k", 99, 300, T0);
+    expect(await store.peek("k", at(299))).toMatchObject({ count: 99 });
+    expect((await store.hit("k", 60, at(10))).count).toBe(100);
+    await store.reset("k");
+    expect(await store.peek("k", at(11))).toBeNull();
+    await store.reset("k");
+  });
+  it(`${name}: purges the ended windows and only those`, async () => {
+    const store = await make();
+    await store.hit("short", 10, T0);
+    await store.hit("long", 600, T0);
+    expect(await store.purge(at(30))).toBe(1);
+    expect(await store.peek("short", at(30))).toBeNull();
+    expect((await store.peek("long", at(30)))?.count).toBe(1);
+  });
+  it(`${name}: counts parallel hits exactly`, async () => {
+    const store = await make();
+    const hits = await Promise.all(Array.from({ length: 100 }, () => store.hit("burst", 60, T0)));
+    expect(hits.map((h) => h.count).sort((a, b) => a - b)).toEqual(Array.from({ length: 100 }, (_, i) => i + 1));
+    expect((await store.peek("burst", at(1)))?.count).toBe(100);
+  });
+}
+export {
+  limitStoreContract
+};
+//# sourceMappingURL=testkit.js.map

package/dist/testkit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testkit.ts"],"sourcesContent":["import { expect, it } from \"vitest\";\n\nimport type { LimitStore } from \"./port\";\n\nconst T0 = new Date(\"2026-10-26T12:00:00.000Z\");\nconst at = (seconds: number) => new Date(T0.valueOf() + seconds * 1000);\n\n/** What every `LimitStore` adapter must do: the same behaviour behind the same port. `make` gives a store with no counters. */\nexport function limitStoreContract(name: string, make: () => LimitStore | Promise<LimitStore>) {\n  it(`${name}: counts hits in a window that the first hit starts`, async () => {\n    const store = await make();\n    const first = await store.hit(\"k\", 60, T0);\n    expect(first.count).toBe(1);\n    expect(first.resetAt.toISOString()).toBe(at(60).toISOString());\n    const later = await store.hit(\"k\", 60, at(30));\n    expect(later.count).toBe(2);\n    expect(later.resetAt.toISOString()).toBe(at(60).toISOString()); // a later hit does not extend the window\n  });\n\n  it(`${name}: starts a new window when the last one has ended`, async () => {\n    const store = await make();\n    await store.hit(\"k\", 60, T0);\n    await store.hit(\"k\", 60, at(10));\n    const next = await store.hit(\"k\", 60, at(60));\n    expect(next.count).toBe(1);\n    expect(next.resetAt.toISOString()).toBe(at(120).toISOString());\n  });\n\n  it(`${name}: keeps keys apart`, async () => {\n    const store = await make();\n    await store.hit(\"a\", 60, T0);\n    await store.hit(\"a\", 60, T0);\n    expect((await store.hit(\"b\", 60, T0)).count).toBe(1);\n  });\n\n  it(`${name}: peeks without counting, and only while the window is open`, async () => {\n    const store = await make();\n    expect(await store.peek(\"k\", T0)).toBeNull();\n    await store.hit(\"k\", 60, T0);\n    expect((await store.peek(\"k\", at(1)))?.count).toBe(1);\n    expect((await store.peek(\"k\", at(1)))?.count).toBe(1);\n    expect(await store.peek(\"k\", at(60))).toBeNull();\n  });\n\n  it(`${name}: opens a lock-out with set, and forgets with reset`, async () => {\n    const store = await make();\n    await store.set(\"k\", 99, 300, T0);\n    expect(await store.peek(\"k\", at(299))).toMatchObject({ count: 99 });\n    expect((await store.hit(\"k\", 60, at(10))).count).toBe(100);\n    await store.reset(\"k\");\n    expect(await store.peek(\"k\", at(11))).toBeNull();\n    await store.reset(\"k\"); // twice: safe\n  });\n\n  it(`${name}: purges the ended windows and only those`, async () => {\n    const store = await make();\n    await store.hit(\"short\", 10, T0);\n    await store.hit(\"long\", 600, T0);\n    expect(await store.purge(at(30))).toBe(1);\n    expect(await store.peek(\"short\", at(30))).toBeNull();\n    expect((await store.peek(\"long\", at(30)))?.count).toBe(1);\n  });\n\n  it(`${name}: counts parallel hits exactly`, async () => {\n    const store = await make();\n    const hits = await Promise.all(Array.from({ length: 100 }, () => store.hit(\"burst\", 60, T0)));\n    expect(hits.map((h) => h.count).sort((a, b) => a - b)).toEqual(Array.from({ length: 100 }, (_, i) => i + 1));\n    expect((await store.peek(\"burst\", at(1)))?.count).toBe(100);\n  });\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@krizaka/rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "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",
+    "rate-limit",
+    "abuse",
+    "postgresql"
+  ],
+  "homepage": "https://github.com/krizaka/krizaka-ts/tree/main/packages/rate-limit",
+  "bugs": "https://github.com/krizaka/krizaka-ts/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krizaka/krizaka-ts.git",
+    "directory": "packages/rate-limit"
+  },
+  "license": "Apache-2.0",
+  "author": "Krizaka (https://www.krizaka.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "import": "./dist/settings.js"
+    },
+    "./testkit": {
+      "types": "./dist/testkit.d.ts",
+      "import": "./dist/testkit.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.23.1",
+    "eslint": "^9.39.0",
+    "pg": "^8.23.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.6.7",
+    "@krizaka/config": "^0.8.1"
+  },
+  "dependencies": {
+    "@krizaka/db": "^0.2.0",
+    "@krizaka/settings": "^0.5.0",
+    "@krizaka/time": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=4",
+    "zod": ">=3.23"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "lint": "eslint . --max-warnings 0 && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run lint && pnpm run test && pnpm run build"
+  }
 }