@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/infra/schedule/scheduled-runs.js

@@ -0,0 +1,163 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, } from "@nestjs/common";
+import { DiscoveryService, MetadataScanner } from "@nestjs/core";
+import { SchedulerRegistry } from "@nestjs/schedule";
+import { waitWithin } from "../close-within.js";
+import { runOutsideTransaction } from "../database/transaction-host.js";
+import { GracefulShutdown } from "../lifecycle/graceful-shutdown.service.js";
+import { KERNEL_LOGGER } from "../tokens.js";
+import { LockedIntervalScheduler } from "./locked-interval.js";
+import { LOCKED_JOB, LOCKED_JOB_BODY, SCHEDULED_RUNS, } from "./locked-tick.js";
+/**
+ * The runs of the `@LockedCron` / `@LockedInterval` jobs (ticks and `runOnStart` runs), their
+ * start gate ({@link open}) and their stop. At module init it attaches itself to every provider instance with a locked job
+ * (`SCHEDULED_RUNS`), so each run is tracked and gets {@link signal}. {@link stop} (idempotent)
+ * stops the cron and interval timers, aborts the signal, refuses new runs and waits for the runs in
+ * progress within its budget, capped by what is left of the shared stop deadline
+ * (`GracefulShutdown`): the runs end (and release their locks) before Redis and the pool close.
+ * Runs over the budget are abandoned with a WARN; the job's own failures after the stop began are
+ * logged at WARN / INFO, never ERROR. The kernel's stop phases call it through the worker role
+ * (`WorkerRole.stopSchedules`, awaited in the runs phase, before the extension host closes: jobs may
+ * call extensions); `beforeApplicationShutdown` covers an application without them.
+ */
+let ScheduledRuns = class ScheduledRuns {
+    discovery;
+    scanner;
+    crons;
+    intervals;
+    shutdown;
+    log;
+    abort = new AbortController();
+    inFlight = new Set();
+    stopping;
+    gateOpen = false;
+    /** Each locked job's body by job name, bound to its instance (for {@link runNow}). */
+    bodies = new Map();
+    constructor(discovery, scanner, crons, intervals, shutdown, log) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+        this.crons = crons;
+        this.intervals = intervals;
+        this.shutdown = shutdown;
+        this.log = log;
+    }
+    /**
+     * Attaches itself to every instance with a locked job in `onModuleInit`, which runs before any
+     * `onApplicationBootstrap` hook, so the start gate already guards the jobs when the cron
+     * orchestrator and the interval scheduler arm their timers there.
+     */
+    onModuleInit() {
+        for (const wrapper of this.discovery.getProviders()) {
+            const instance = wrapper.instance;
+            if (!instance || typeof instance !== "object" || !wrapper.isDependencyTreeStatic())
+                continue;
+            const proto = Object.getPrototypeOf(instance);
+            if (!proto)
+                continue;
+            let hasJob = false;
+            for (const m of this.scanner.getAllMethodNames(proto)) {
+                const fn = instance[m];
+                if (typeof fn !== "function" || Reflect.getMetadata(LOCKED_JOB, fn) !== true)
+                    continue;
+                hasJob = true;
+                const job = Reflect.getMetadata(LOCKED_JOB_BODY, fn);
+                if (job)
+                    this.bodies.set(job.name, (signal) => job.body.call(instance, signal));
+            }
+            if (hasJob) {
+                Object.defineProperty(instance, SCHEDULED_RUNS, { value: this, configurable: true });
+            }
+        }
+    }
+    /**
+     * Runs the body of the locked job named `name` once, now, outside its schedule: no tick marker
+     * and no run lock, in a fresh async context (no transaction), with the stop signal. A job's name
+     * enqueued on the maintenance queue runs this way, as the maintenance handlers of the periodic
+     * jobs did before they became locked jobs. Resolves false when no job has that name; the body's
+     * error is thrown.
+     */
+    async runNow(name) {
+        const body = this.bodies.get(name);
+        if (!body)
+            return false;
+        await runOutsideTransaction(() => Promise.resolve(body(this.abort.signal)));
+        return true;
+    }
+    /** The start gate is open: ticks and start runs may run. */
+    get opened() {
+        return this.gateOpen && this.stopping === undefined;
+    }
+    /**
+     * Opens the start gate. Until this is called every tick and start run skips at INFO: the
+     * cron and interval timers are armed at application bootstrap, which runs before the kernel's
+     * start sequence (migrations, bootstrap, extension load). The kernel's worker role opens it once
+     * its queue consumers started (then starts the `runOnStart` runs); a stop closes it again.
+     */
+    open() {
+        if (this.stopping === undefined)
+            this.gateOpen = true;
+    }
+    get stopped() {
+        return this.stopping !== undefined;
+    }
+    get signal() {
+        return this.abort.signal;
+    }
+    /** The number of runs in progress. */
+    get inFlightCount() {
+        return this.inFlight.size;
+    }
+    track(p) {
+        this.inFlight.add(p);
+        const forget = () => {
+            this.inFlight.delete(p);
+        };
+        p.then(forget, forget);
+        return p;
+    }
+    /**
+     * Stops the schedulers and waits for the runs in progress, at most `budgetMs` (capped by the
+     * shared stop deadline). Idempotent: later calls return the first call's promise.
+     */
+    stop(budgetMs) {
+        this.stopping ??= this.runStop(budgetMs);
+        return this.stopping;
+    }
+    async beforeApplicationShutdown() {
+        await this.stop(this.shutdown.remainingMs());
+    }
+    async runStop(budgetMs) {
+        this.gateOpen = false;
+        for (const job of this.crons.getCronJobs().values())
+            void job.stop();
+        this.intervals.stopAll();
+        this.abort.abort(new Error("the scheduler is stopping"));
+        if (this.inFlight.size === 0)
+            return;
+        const waitMs = Math.max(0, Math.min(budgetMs, this.shutdown.remainingMs()));
+        if (!(await waitWithin(Promise.allSettled([...this.inFlight]), waitMs))) {
+            this.log.warn("shutdown: scheduled jobs did not stop in time; abandoned", {
+                inFlight: this.inFlight.size,
+                budgetMs: waitMs,
+            });
+        }
+    }
+};
+ScheduledRuns = __decorate([
+    Injectable(),
+    __param(0, Inject(DiscoveryService)),
+    __param(1, Inject(MetadataScanner)),
+    __param(2, Inject(SchedulerRegistry)),
+    __param(3, Inject(LockedIntervalScheduler)),
+    __param(4, Inject(GracefulShutdown)),
+    __param(5, Inject(KERNEL_LOGGER))
+], ScheduledRuns);
+export { ScheduledRuns };

package/dist/infra/swagger/swagger.d.ts

@@ -0,0 +1,16 @@
+import type { INestApplication } from "@nestjs/common";
+import { type OpenAPIObject } from "@nestjs/swagger";
+/** A `$ref` to a named DTO's schema, for `@ApiBody({ schema: dtoRef(Dto) })` and friends. */
+export declare function dtoRef(dto: {
+    readonly dtoName: string | undefined;
+}): {
+    $ref: string;
+};
+/** Builds the OpenAPI document: the routes Nest found plus every named zod DTO's JSON Schema. */
+export declare function buildSwaggerDocument(app: INestApplication, version: string): OpenAPIObject;
+/**
+ * Serves the swagger UI at `/docs` (JSON at `/docs-json`) when `enabled`; otherwise does nothing
+ * and builds no document. The routes sit outside Nest's guards, so they are unauthenticated: the
+ * option is for development and trials (`http.swagger`, default false).
+ */
+export declare function setupSwagger(app: INestApplication, enabled: boolean, version?: string): void;

package/dist/infra/swagger/swagger.js

@@ -0,0 +1,31 @@
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { registeredZodDtos } from "../validation/create-zod-dto.js";
+/** A `$ref` to a named DTO's schema, for `@ApiBody({ schema: dtoRef(Dto) })` and friends. */
+export function dtoRef(dto) {
+    if (dto.dtoName === undefined)
+        throw new Error("dtoRef: the DTO has no name");
+    return { $ref: `#/components/schemas/${dto.dtoName}` };
+}
+/** Builds the OpenAPI document: the routes Nest found plus every named zod DTO's JSON Schema. */
+export function buildSwaggerDocument(app, version) {
+    const doc = SwaggerModule.createDocument(app, new DocumentBuilder().setTitle("Capybara kernel API").setVersion(version).build());
+    const schemas = { ...(doc.components?.schemas ?? {}) };
+    for (const dto of registeredZodDtos()) {
+        if (dto.dtoName !== undefined)
+            schemas[dto.dtoName] = dto.jsonSchema();
+    }
+    doc.components = { ...doc.components, schemas: schemas };
+    return doc;
+}
+/**
+ * Serves the swagger UI at `/docs` (JSON at `/docs-json`) when `enabled`; otherwise does nothing
+ * and builds no document. The routes sit outside Nest's guards, so they are unauthenticated: the
+ * option is for development and trials (`http.swagger`, default false).
+ */
+export function setupSwagger(app, enabled, version = "0") {
+    if (!enabled)
+        return;
+    SwaggerModule.setup("docs", app, buildSwaggerDocument(app, version), {
+        jsonDocumentUrl: "docs-json",
+    });
+}

package/dist/infra/throttler/credential-throttler.d.ts

@@ -0,0 +1,35 @@
+import { type ThrottlerStorage } from "@nestjs/throttler";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { type NamedThrottler } from "./named-throttlers.js";
+/**
+ * The Redis key of one counter. All counters of a credential group share the hash tag
+ * `{cred:<group>}`, so the keys of one reservation live in one Redis Cluster slot (one EVAL, no
+ * CROSSSLOT).
+ */
+export declare const credentialRedisKey: (t: NamedThrottler, tracker: string) => string;
+/**
+ * Credential-attempt limiting for handlers (login, change password, setup token, invitation
+ * accept), on the named-throttler table and the Redis storage.
+ * Call it inside the handler after pipes and preconditions, as the limiter is called today:
+ *
+ * ```ts
+ * await this.credentials.reserve(["login", "login-ip", "login-account"], req, reply);
+ * ... check the credentials ...
+ * await this.credentials.succeeded(["login", "login-ip", "login-account"], req);
+ * ```
+ *
+ * `reserve` is one EVAL across the keys, all or nothing: a request rejected on one dimension is
+ * counted on none, and `retry-after` is the largest remaining TTL among the keys at their limit.
+ * `succeeded` is one EVAL: `clear` throttlers lose their counter, `refund` ones one attempt.
+ * FAIL-CLOSED: a Redis error propagates (a 500).
+ */
+export declare class CredentialThrottler {
+    private readonly storage;
+    constructor(storage: ThrottlerStorage);
+    /** Reserves one attempt on every named throttler or throws 429 `auth.rate_limited` (header set on `reply`). */
+    reserve(names: readonly string[], req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /** A successful attempt: clears the `clear` counters and refunds one on the `refund` ones. */
+    succeeded(names: readonly string[], req: FastifyRequest): Promise<void>;
+    private resolve;
+    private redisStorage;
+}

package/dist/infra/throttler/credential-throttler.js

@@ -0,0 +1,77 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { getStorageToken } from "@nestjs/throttler";
+import { ApiError } from "../../errors.js";
+import { NAMED_THROTTLERS, throttlerKey } from "./named-throttlers.js";
+/**
+ * The Redis key of one counter. All counters of a credential group share the hash tag
+ * `{cred:<group>}`, so the keys of one reservation live in one Redis Cluster slot (one EVAL, no
+ * CROSSSLOT).
+ */
+export const credentialRedisKey = (t, tracker) => `throttler:{cred:${t.group}}:${t.name}:${throttlerKey(t.name, tracker)}`;
+/**
+ * Credential-attempt limiting for handlers (login, change password, setup token, invitation
+ * accept), on the named-throttler table and the Redis storage.
+ * Call it inside the handler after pipes and preconditions, as the limiter is called today:
+ *
+ * ```ts
+ * await this.credentials.reserve(["login", "login-ip", "login-account"], req, reply);
+ * ... check the credentials ...
+ * await this.credentials.succeeded(["login", "login-ip", "login-account"], req);
+ * ```
+ *
+ * `reserve` is one EVAL across the keys, all or nothing: a request rejected on one dimension is
+ * counted on none, and `retry-after` is the largest remaining TTL among the keys at their limit.
+ * `succeeded` is one EVAL: `clear` throttlers lose their counter, `refund` ones one attempt.
+ * FAIL-CLOSED: a Redis error propagates (a 500).
+ */
+let CredentialThrottler = class CredentialThrottler {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /** Reserves one attempt on every named throttler or throws 429 `auth.rate_limited` (header set on `reply`). */
+    async reserve(names, req, reply) {
+        const ts = this.resolve(names);
+        const r = await this.redisStorage().reserve(ts.map((t) => credentialRedisKey(t, t.getTracker(req))), ts.map((t) => t.limit), ts[0]?.ttl ?? 0);
+        if (r.allowed)
+            return;
+        reply.header("retry-after", String(r.retryAfterSeconds));
+        throw new ApiError("auth.rate_limited", ts[0]?.message ?? "");
+    }
+    /** A successful attempt: clears the `clear` counters and refunds one on the `refund` ones. */
+    async succeeded(names, req) {
+        const ts = this.resolve(names);
+        const key = (t) => credentialRedisKey(t, t.getTracker(req));
+        await this.redisStorage().succeeded(ts.filter((t) => t.onSuccess === "clear").map(key), ts.filter((t) => t.onSuccess === "refund").map(key));
+    }
+    resolve(names) {
+        const ts = names.map((n) => {
+            const t = NAMED_THROTTLERS.find((x) => x.name === n);
+            if (!t)
+                throw new Error(`unknown throttler "${n}"`);
+            return t;
+        });
+        const group = ts[0]?.group;
+        if (!group || ts.some((t) => t.group !== group || t.ttl !== ts[0]?.ttl)) {
+            throw new Error("credential throttlers of one call must share one group and window");
+        }
+        return ts;
+    }
+    redisStorage() {
+        return this.storage;
+    }
+};
+CredentialThrottler = __decorate([
+    Injectable(),
+    __param(0, Inject(getStorageToken()))
+], CredentialThrottler);
+export { CredentialThrottler };

package/dist/infra/throttler/named-throttlers.d.ts

@@ -0,0 +1,31 @@
+import type { FastifyRequest } from "fastify";
+/** The counting window of every credential throttler, ms (first attempt starts it). */
+export declare const CREDENTIAL_WINDOW_MS = 900000;
+/** A named throttler: a limit over a tracker, answering 429 `auth.rate_limited` with `message`. */
+export interface NamedThrottler {
+    name: string;
+    limit: number;
+    ttl: number;
+    /** The 429 message (today's text of the route that used the limiter). */
+    message: string;
+    /** The credential group: throttlers of one group are reserved together (one Redis hash tag). */
+    group: string;
+    /** What a successful attempt does to this counter: delete it, or give one attempt back. */
+    onSuccess: "clear" | "refund";
+    getTracker: (req: FastifyRequest) => string;
+}
+/**
+ * Every rate limit of the kernel today, as named throttlers (spec §2.4). The credential routes
+ * reserve theirs through `CredentialThrottler` inside the handler (one group per route, all or
+ * nothing); a plain per-route limit would opt in with `@Throttled(...names)`.
+ *
+ * | route | names (reserved via `CredentialThrottler`) |
+ * |---|---|
+ * | `POST /api/v1/auth/login` | `login`, `login-ip`, `login-account` |
+ * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
+ * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
+ * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ */
+export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
+/** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
+export declare const throttlerKey: (name: string, tracker: string) => string;

package/dist/infra/throttler/named-throttlers.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+/** The counting window of every credential throttler, ms (first attempt starts it). */
+export const CREDENTIAL_WINDOW_MS = 900_000;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+/** Logins are normalized the way local accounts are (no format check): case / space variants share a count. */
+const loginHash = (login) => sha256(login.normalize("NFKC").trim().toLowerCase());
+const bodyLogin = (req) => {
+    const b = req.body;
+    const login = typeof b === "object" && b !== null ? b.login : undefined;
+    return typeof login === "string" ? login : "";
+};
+/** The client address: Fastify's `request.ip`, which already honors `http.trustProxy`. */
+const ip = (req) => req.ip;
+const principalAccountId = (req) => {
+    const p = req.principal;
+    return p?.account?.id ?? "";
+};
+const routeToken = (req) => String(req.params?.token ?? "");
+const LOGIN_MSG = "Too many failed login attempts; try again later";
+/**
+ * Every rate limit of the kernel today, as named throttlers (spec §2.4). The credential routes
+ * reserve theirs through `CredentialThrottler` inside the handler (one group per route, all or
+ * nothing); a plain per-route limit would opt in with `@Throttled(...names)`.
+ *
+ * | route | names (reserved via `CredentialThrottler`) |
+ * |---|---|
+ * | `POST /api/v1/auth/login` | `login`, `login-ip`, `login-account` |
+ * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
+ * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
+ * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ */
+export const NAMED_THROTTLERS = [
+    // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
+    {
+        name: "login",
+        group: "login",
+        onSuccess: "clear",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: LOGIN_MSG,
+        getTracker: (req) => `${loginHash(bodyLogin(req))}:${sha256(ip(req))}`,
+    },
+    // client IP across logins (credential stuffing): 50
+    {
+        name: "login-ip",
+        group: "login",
+        onSuccess: "refund",
+        limit: 50,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: LOGIN_MSG,
+        getTracker: ip,
+    },
+    // one login across IPs (distributed guessing): 100
+    {
+        name: "login-account",
+        group: "login",
+        onSuccess: "clear",
+        limit: 100,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: LOGIN_MSG,
+        getTracker: (req) => loginHash(bodyLogin(req)),
+    },
+    {
+        name: "change-password",
+        group: "change-password",
+        onSuccess: "clear",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many failed password attempts; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
+    {
+        name: "change-password-ip",
+        group: "change-password",
+        onSuccess: "refund",
+        limit: 50,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many failed password attempts; try again later",
+        getTracker: ip,
+    },
+    {
+        name: "setup-token",
+        group: "setup",
+        onSuccess: "clear",
+        limit: 100,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many setup attempts; try again later",
+        getTracker: () => sha256("token"),
+    },
+    {
+        name: "setup-ip",
+        group: "setup",
+        onSuccess: "refund",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many setup attempts; try again later",
+        getTracker: ip,
+    },
+    {
+        name: "invitation",
+        group: "invitation",
+        onSuccess: "clear",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many invitation attempts; try again later",
+        getTracker: (req) => sha256(routeToken(req)),
+    },
+    {
+        name: "invitation-ip",
+        group: "invitation",
+        onSuccess: "refund",
+        limit: 20,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many invitation attempts; try again later",
+        getTracker: ip,
+    },
+];
+/** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
+export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/infra/throttler/redis-throttler-storage.d.ts

@@ -0,0 +1,38 @@
+import type { ThrottlerStorage } from "@nestjs/throttler";
+import type { Redis } from "ioredis";
+import type { KernelLogger } from "../../log.js";
+interface ThrottlerStorageRecord {
+    totalHits: number;
+    timeToExpire: number;
+    isBlocked: boolean;
+    timeToBlockExpire: number;
+}
+export type ReserveResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+};
+/** The Redis key of a counter. The `{key}` hash tag keeps it in one Redis Cluster slot. */
+export declare const throttlerRedisKey: (key: string, throttlerName: string) => string;
+/**
+ * The `@nestjs/throttler` storage on the shared Redis connection: every replica counts into the
+ * same keys (the default in-memory storage would give each replica its own quota). Fail-open: a
+ * Redis error lets the request through and logs a warning, so a Redis blip never turns every
+ * throttled route into a 5xx (availability over limit precision).
+ */
+export declare class RedisThrottlerStorage implements ThrottlerStorage {
+    private readonly redis;
+    private readonly log;
+    constructor(redis: Redis, log: KernelLogger);
+    /** `ttl` is in milliseconds (the throttler convention); `blockDuration` is unused. */
+    increment(key: string, ttl: number, limit: number, _blockDuration: number, throttlerName: string): Promise<ThrottlerStorageRecord>;
+    /**
+     * Reserves one attempt on every key (which must share one hash tag), all or nothing. Unlike
+     * `increment` it does NOT swallow Redis errors: the caller fails closed.
+     */
+    reserve(keys: string[], limits: number[], ttlMs: number): Promise<ReserveResult>;
+    /** A successful attempt: deletes the `clear` counters and refunds one on the `refund` ones. Fails closed. */
+    succeeded(clear: string[], refund: string[]): Promise<void>;
+}
+export {};

package/dist/infra/throttler/redis-throttler-storage.js

@@ -0,0 +1,130 @@
+/**
+ * One atomic EVAL: when the counter already reached the limit the attempt is rejected and
+ * NOT counted (a rejected attempt must not push the count further, so the window ends on
+ * schedule); otherwise the counter is incremented and always carries a TTL. Returns
+ * `{hits, pttl, blocked}`. `now` is not needed: no TIME command, no clock in the script.
+ */
+const INCREMENT_LUA = `
+local key = KEYS[1]
+local ttlMs = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local hits = tonumber(redis.call('GET', key) or '0')
+local blocked = 0
+if hits >= limit then
+  blocked = 1
+else
+  hits = redis.call('INCR', key)
+end
+local pttl = redis.call('PTTL', key)
+if pttl < 0 then
+  redis.call('PEXPIRE', key, ttlMs)
+  pttl = ttlMs
+end
+return {hits, pttl, blocked}
+`;
+/**
+ * All-or-nothing reservation across KEYS (one hash tag): ARGV[1] is the window in ms, ARGV[i + 1]
+ * the limit of KEYS[i]. Any key at its limit rejects the attempt and NOTHING is incremented;
+ * otherwise every key is incremented and carries a TTL. Returns `{1}` or `{0, retryPttl}` (the
+ * largest remaining TTL among the keys at their limit).
+ */
+const RESERVE_LUA = `
+local retry = -1
+for i, key in ipairs(KEYS) do
+  local n = tonumber(redis.call('GET', key) or '0')
+  if n >= tonumber(ARGV[i + 1]) then
+    local pttl = redis.call('PTTL', key)
+    if pttl > retry then retry = pttl end
+    if retry < 1 then retry = 1 end
+  end
+end
+if retry > 0 then
+  return {0, retry}
+end
+for i, key in ipairs(KEYS) do
+  local n = redis.call('INCR', key)
+  if n == 1 or redis.call('PTTL', key) < 0 then
+    redis.call('PEXPIRE', key, ARGV[1])
+  end
+end
+return {1}
+`;
+/**
+ * Success: the first ARGV[1] keys are deleted, the rest lose one count (deleted at zero, never
+ * created).
+ */
+const SUCCEEDED_LUA = `
+local nClear = tonumber(ARGV[1])
+for i = 1, nClear do
+  redis.call('DEL', KEYS[i])
+end
+for i = nClear + 1, #KEYS do
+  if redis.call('EXISTS', KEYS[i]) == 1 then
+    if redis.call('DECR', KEYS[i]) <= 0 then
+      redis.call('DEL', KEYS[i])
+    end
+  end
+end
+return 0
+`;
+const NOT_BLOCKED = {
+    totalHits: 0,
+    timeToExpire: 0,
+    isBlocked: false,
+    timeToBlockExpire: 0,
+};
+/** The Redis key of a counter. The `{key}` hash tag keeps it in one Redis Cluster slot. */
+export const throttlerRedisKey = (key, throttlerName) => `throttler:{${key}}:${throttlerName}`;
+/**
+ * The `@nestjs/throttler` storage on the shared Redis connection: every replica counts into the
+ * same keys (the default in-memory storage would give each replica its own quota). Fail-open: a
+ * Redis error lets the request through and logs a warning, so a Redis blip never turns every
+ * throttled route into a 5xx (availability over limit precision).
+ */
+export class RedisThrottlerStorage {
+    redis;
+    log;
+    constructor(redis, log) {
+        this.redis = redis;
+        this.log = log;
+    }
+    /** `ttl` is in milliseconds (the throttler convention); `blockDuration` is unused. */
+    async increment(key, ttl, limit, _blockDuration, throttlerName) {
+        try {
+            const [hits, pttl, blocked] = (await this.redis.eval(INCREMENT_LUA, 1, throttlerRedisKey(key, throttlerName), ttl, limit));
+            // seconds, at least 1 and at most the window: the Retry-After value
+            const timeToExpire = Math.min(Math.max(Math.ceil(pttl / 1000), 1), Math.ceil(ttl / 1000));
+            return {
+                totalHits: hits,
+                timeToExpire,
+                isBlocked: blocked === 1,
+                timeToBlockExpire: blocked === 1 ? timeToExpire : 0,
+            };
+        }
+        catch (err) {
+            this.log.warn("throttler storage unavailable, request allowed (fail-open)", {
+                throttler: throttlerName,
+                err,
+            });
+            return NOT_BLOCKED;
+        }
+    }
+    /**
+     * Reserves one attempt on every key (which must share one hash tag), all or nothing. Unlike
+     * `increment` it does NOT swallow Redis errors: the caller fails closed.
+     */
+    async reserve(keys, limits, ttlMs) {
+        const out = (await this.redis.eval(RESERVE_LUA, keys.length, ...keys, ttlMs, ...limits));
+        if (out[0] === 1)
+            return { allowed: true };
+        const window = Math.ceil(ttlMs / 1000);
+        return {
+            allowed: false,
+            retryAfterSeconds: Math.min(Math.max(Math.ceil((out[1] ?? ttlMs) / 1000), 1), window),
+        };
+    }
+    /** A successful attempt: deletes the `clear` counters and refunds one on the `refund` ones. Fails closed. */
+    async succeeded(clear, refund) {
+        await this.redis.eval(SUCCEEDED_LUA, clear.length + refund.length, ...clear, ...refund, clear.length);
+    }
+}

package/dist/infra/throttler/throttler.guard.d.ts

@@ -0,0 +1,23 @@
+import { type ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { ThrottlerGuard, type ThrottlerModuleOptions, type ThrottlerRequest, type ThrottlerStorage } from "@nestjs/throttler";
+/** The throttler names selected for the route `context` runs (empty: none, the guard passes). */
+export declare function selectedThrottlers(context: ExecutionContext): readonly string[];
+/**
+ * Opts a route (or controller) in to the named throttlers `names` (see `NAMED_THROTTLERS`).
+ * Throttling is per-route opt-in because the kernel limits only credential-checking routes today;
+ * health, SSE and extension routes stay unlimited.
+ */
+export declare const Throttled: (...names: string[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+/**
+ * `@nestjs/throttler`'s guard with the kernel's error contract: the first named throttler of the
+ * route at its limit answers 429 `auth.rate_limited` with its own message and `retry-after`
+ * (seconds, 1..window), as the credential routes answer; no `x-ratelimit-*` headers (the
+ * kernel sends none today). Which throttlers apply to a route is chosen by `@Throttled`; they are
+ * counted one after another in `NAMED_THROTTLERS` order (table order is check order). Fail-open on
+ * Redis errors (see `RedisThrottlerStorage`). For credential checks use `CredentialThrottler`.
+ */
+export declare class KernelThrottlerGuard extends ThrottlerGuard {
+    constructor(options: ThrottlerModuleOptions, storage: ThrottlerStorage, reflector: Reflector);
+    protected handleRequest(props: ThrottlerRequest): Promise<boolean>;
+}