@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

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,36 @@
+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` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
+ */
+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,157 @@
+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` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
+ */
+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,
+    },
+    // device sign-in codes issued per client address (each one holds Redis state for its TTL): 20.
+    // Opted in with @Throttled, which counts every request before the handler: group and onSuccess
+    // are unused (they matter only to CredentialThrottler).
+    {
+        name: "device-authorize-ip",
+        group: "device-authorize",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in attempts; try again later",
+        getTracker: ip,
+    },
+    // device token polls per client address (@Throttled like device-authorize-ip): 600, one login
+    // polls up to 120 times (600 s / 5 s), so several machines behind one NAT address fit
+    {
+        name: "device-token-ip",
+        group: "device-token",
+        onSuccess: "clear",
+        limit: 600,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in polls; try again later",
+        getTracker: ip,
+    },
+    // user codes tried per signed-in person (guessing another machine's code): 10, refunded on success
+    {
+        name: "device-code-account",
+        group: "device-code",
+        onSuccess: "refund",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device code attempts; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
+];
+/** 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 {};