@nage-api/core 1.0.0-beta.2

package/dist/security/legacy-scan.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Source scanner for the insecure patterns the legacy framework shipped
+ * (PLAN.md §12, §23.3 — `nage doctor --legacy`).
+ *
+ * The config audit covers a `@nage-api` application. This covers the repository it
+ * is being migrated from, where the same problems live as literals in source:
+ * `rejectUnauthorized: false`, `Math.random()` for tokens, `synchronize: true`,
+ * an argument-less `enableCors()`, uuid v1, and shipped default credentials.
+ *
+ * It takes file contents rather than paths so it stays testable and free of any
+ * filesystem dependency; the CLI supplies the files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanForLegacyPatterns = scanForLegacyPatterns;
+const LEGACY_PATTERNS = [
+    {
+        pattern: /rejectUnauthorized\s*:\s*false/,
+        severity: 'critical',
+        message: 'TLS certificate verification is disabled, so the connection is interceptable.',
+        remediation: 'Remove it and declare `ssl: "verify-full"` in nage.config.ts.',
+    },
+    {
+        pattern: /Math\s*\.\s*random\s*\(/,
+        severity: 'high',
+        message: 'Math.random() is predictable and unsuitable for tokens, OTPs or ids.',
+        remediation: 'Use randomToken()/randomOtp() from @nage-api/core, which draw from node:crypto.',
+    },
+    {
+        pattern: /\buuid\s*\.\s*v1\s*\(|\bv1\s*\(\s*\)\s*(?=[,;)])|require\(['"]uuid\/v1['"]\)/,
+        severity: 'medium',
+        message: 'uuid v1 encodes a timestamp and MAC address, so ids are guessable and identifying.',
+        remediation: 'Use randomId(), which returns a v4 UUID.',
+    },
+    {
+        pattern: /synchronize\s*:\s*true|alter\s*:\s*true/,
+        severity: 'high',
+        message: 'Schema auto-sync rewrites tables at boot; data loss is one model edit away.',
+        remediation: 'Generate a migration and apply it with `nage db migrate`.',
+    },
+    {
+        pattern: /enableCors\s*\(\s*\)/,
+        severity: 'critical',
+        message: 'enableCors() with no arguments allows every origin.',
+        remediation: 'Configure http.cors.origins with an explicit allow-list.',
+    },
+    {
+        pattern: /admin@admin\.com|['"]123456['"]/,
+        severity: 'critical',
+        message: 'A default credential is present in source.',
+        remediation: 'Remove it; seed an administrator with a generated password on first run.',
+    },
+    {
+        pattern: /jwt\s*:\s*\{[^}]*secret\s*:\s*['"][^'"]{0,15}['"]/s,
+        severity: 'critical',
+        message: 'A JWT secret is hard-coded and short.',
+        remediation: 'Load signing material from the environment or a secret provider.',
+    },
+    {
+        pattern: /NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*['"]?0/,
+        severity: 'critical',
+        message: 'TLS verification is disabled for the whole Node process.',
+        remediation: 'Remove it and trust the correct CA instead.',
+    },
+];
+/** Lines that are obviously commented out are not findings. */
+function isCommented(line) {
+    const trimmed = line.trimStart();
+    return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+/**
+ * Scan files for legacy insecure patterns.
+ *
+ * @returns one finding per match, located as `path:line`.
+ */
+function scanForLegacyPatterns(files) {
+    const findings = [];
+    for (const file of files) {
+        const lines = file.content.split('\n');
+        lines.forEach((line, index) => {
+            if (isCommented(line))
+                return;
+            for (const legacy of LEGACY_PATTERNS) {
+                if (!legacy.pattern.test(line))
+                    continue;
+                findings.push({
+                    code: 'SEC_LEGACY_PATTERN',
+                    severity: legacy.severity,
+                    location: `${file.path}:${index + 1}`,
+                    message: legacy.message,
+                    remediation: legacy.remediation,
+                });
+            }
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=legacy-scan.js.map

package/dist/security/random.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cryptographically secure randomness (PLAN.md §12).
+ *
+ * The legacy framework built OTPs and tokens on `Math.random()` and used uuid
+ * v1 (which encodes a timestamp and MAC address). Both are predictable enough
+ * to guess. Everything here draws from `node:crypto`, and the shared ESLint
+ * config makes `Math.random()` an error so the old pattern cannot come back.
+ */
+/** Unambiguous alphabet: no `0`/`O`, no `1`/`l`/`I` — for codes people retype. */
+export declare const UNAMBIGUOUS_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export declare const ALPHANUMERIC_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** A v4 UUID. Unlike v1 it encodes neither a timestamp nor a MAC address. */
+export declare function randomId(): string;
+/** URL-safe random token of `byteLength` bytes of entropy (32 = 256 bits). */
+export declare function randomToken(byteLength?: number): string;
+/** Hex-encoded random token, for contexts that reject base64 characters. */
+export declare function randomHex(byteLength?: number): string;
+/**
+ * Random string over `alphabet`, drawn without modulo bias — `randomInt` rejects
+ * and re-draws rather than folding a range, which is where naive
+ * `bytes[i] % alphabet.length` implementations leak a skew.
+ */
+export declare function randomString(length: number, alphabet?: string): string;
+/** Uniform integer in `[min, max)`. */
+export declare function randomInt(min: number, max: number): number;
+/**
+ * Numeric one-time code.
+ *
+ * Returned as a string so leading zeros survive — a numeric OTP that loses them
+ * silently shrinks the keyspace it advertises.
+ */
+export declare function randomOtp(length?: number): string;
+/**
+ * Constant-time string comparison.
+ *
+ * Used for OTPs, API keys and token hashes: `a === b` returns as soon as it
+ * finds a difference, and that timing difference is measurable.
+ */
+export declare function secureCompare(left: string, right: string): boolean;
+//# sourceMappingURL=random.d.ts.map

package/dist/security/random.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Cryptographically secure randomness (PLAN.md §12).
+ *
+ * The legacy framework built OTPs and tokens on `Math.random()` and used uuid
+ * v1 (which encodes a timestamp and MAC address). Both are predictable enough
+ * to guess. Everything here draws from `node:crypto`, and the shared ESLint
+ * config makes `Math.random()` an error so the old pattern cannot come back.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALPHANUMERIC_ALPHABET = exports.UNAMBIGUOUS_ALPHABET = void 0;
+exports.randomId = randomId;
+exports.randomToken = randomToken;
+exports.randomHex = randomHex;
+exports.randomString = randomString;
+exports.randomInt = randomInt;
+exports.randomOtp = randomOtp;
+exports.secureCompare = secureCompare;
+const node_crypto_1 = require("node:crypto");
+/** Unambiguous alphabet: no `0`/`O`, no `1`/`l`/`I` — for codes people retype. */
+exports.UNAMBIGUOUS_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+exports.ALPHANUMERIC_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** A v4 UUID. Unlike v1 it encodes neither a timestamp nor a MAC address. */
+function randomId() {
+    return (0, node_crypto_1.randomUUID)();
+}
+/** URL-safe random token of `byteLength` bytes of entropy (32 = 256 bits). */
+function randomToken(byteLength = 32) {
+    return (0, node_crypto_1.randomBytes)(byteLength).toString('base64url');
+}
+/** Hex-encoded random token, for contexts that reject base64 characters. */
+function randomHex(byteLength = 32) {
+    return (0, node_crypto_1.randomBytes)(byteLength).toString('hex');
+}
+/**
+ * Random string over `alphabet`, drawn without modulo bias — `randomInt` rejects
+ * and re-draws rather than folding a range, which is where naive
+ * `bytes[i] % alphabet.length` implementations leak a skew.
+ */
+function randomString(length, alphabet = exports.ALPHANUMERIC_ALPHABET) {
+    if (length <= 0)
+        return '';
+    if (alphabet.length < 2) {
+        throw new RangeError('randomString needs an alphabet of at least two characters');
+    }
+    const characters = [];
+    for (let index = 0; index < length; index += 1) {
+        characters.push(alphabet.charAt((0, node_crypto_1.randomInt)(alphabet.length)));
+    }
+    return characters.join('');
+}
+/** Uniform integer in `[min, max)`. */
+function randomInt(min, max) {
+    return (0, node_crypto_1.randomInt)(min, max);
+}
+/**
+ * Numeric one-time code.
+ *
+ * Returned as a string so leading zeros survive — a numeric OTP that loses them
+ * silently shrinks the keyspace it advertises.
+ */
+function randomOtp(length = 6) {
+    if (length < 4)
+        throw new RangeError('An OTP shorter than 4 digits is not acceptable');
+    let code = '';
+    for (let index = 0; index < length; index += 1)
+        code += String((0, node_crypto_1.randomInt)(10));
+    return code;
+}
+/**
+ * Constant-time string comparison.
+ *
+ * Used for OTPs, API keys and token hashes: `a === b` returns as soon as it
+ * finds a difference, and that timing difference is measurable.
+ */
+function secureCompare(left, right) {
+    const leftBuffer = Buffer.from(left, 'utf8');
+    const rightBuffer = Buffer.from(right, 'utf8');
+    // timingSafeEqual requires equal lengths, and the length itself is not secret;
+    // compare the buffer against itself so the work is done either way.
+    if (leftBuffer.length !== rightBuffer.length) {
+        (0, node_crypto_1.timingSafeEqual)(leftBuffer, leftBuffer);
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(leftBuffer, rightBuffer);
+}
+//# sourceMappingURL=random.js.map

package/dist/security/rate-limit.decorators.d.ts

@@ -0,0 +1,24 @@
+import { type CustomDecorator } from '@nestjs/common';
+/** Per-route override of the global throttle. */
+export interface RateLimitPolicy {
+    readonly limit: number;
+    readonly windowMs: number;
+}
+/**
+ * Tighten (or loosen) the limit for one route.
+ *
+ * The expensive and abusable endpoints — login, OTP send, password reset — get
+ * their own budget rather than sharing the global one (§12).
+ *
+ * ```ts
+ * @RateLimit({ limit: 5, windowMs: 60_000 })
+ * @Post('auth/otp/send')
+ * ```
+ */
+export declare const RateLimit: (policy: RateLimitPolicy) => CustomDecorator;
+/**
+ * Exempt a route entirely — health probes an orchestrator polls every second,
+ * and internal callbacks behind their own authentication.
+ */
+export declare const SkipRateLimit: () => CustomDecorator;
+//# sourceMappingURL=rate-limit.decorators.d.ts.map

package/dist/security/rate-limit.decorators.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkipRateLimit = exports.RateLimit = void 0;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+/**
+ * Tighten (or loosen) the limit for one route.
+ *
+ * The expensive and abusable endpoints — login, OTP send, password reset — get
+ * their own budget rather than sharing the global one (§12).
+ *
+ * ```ts
+ * @RateLimit({ limit: 5, windowMs: 60_000 })
+ * @Post('auth/otp/send')
+ * ```
+ */
+const RateLimit = (policy) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.rateLimit, policy);
+exports.RateLimit = RateLimit;
+/**
+ * Exempt a route entirely — health probes an orchestrator polls every second,
+ * and internal callbacks behind their own authentication.
+ */
+const SkipRateLimit = () => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.skipRateLimit, true);
+exports.SkipRateLimit = SkipRateLimit;
+//# sourceMappingURL=rate-limit.decorators.js.map

package/dist/security/rate-limit.guard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The global throttle guard (PLAN.md §12).
+ *
+ * The legacy framework installed `@nestjs/throttler` but never registered a
+ * guard, so only one endpoint was ever limited and brute force was unimpeded.
+ * Here the guard is global: routes are limited unless they opt out, which is the
+ * direction that fails safe.
+ */
+import { type CanActivate, type ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { NageCoreConfig, RateLimitStore } from '@nage-api/contracts';
+import { RequestContextService } from '../context/request-context.service.js';
+import type { RateLimitPolicy } from './rate-limit.decorators.js';
+/** Defaults: 100 requests a minute per caller. */
+export declare const DEFAULT_RATE_LIMIT: RateLimitPolicy;
+interface RequestLike {
+    readonly ip?: string;
+    readonly url?: string;
+    readonly method?: string;
+    readonly socket?: {
+        readonly remoteAddress?: string;
+    };
+    readonly headers?: Record<string, string | string[] | undefined>;
+}
+export declare class RateLimitGuard implements CanActivate {
+    #private;
+    private readonly reflector;
+    private readonly context;
+    private readonly config;
+    private readonly store?;
+    constructor(reflector: Reflector, context: RequestContextService, config: NageCoreConfig, store?: RateLimitStore | undefined);
+    canActivate(execution: ExecutionContext): Promise<boolean>;
+}
+/**
+ * Best-effort client address.
+ *
+ * `request.ip` already honours the trust-proxy setting, so it is preferred;
+ * `x-forwarded-for` is only consulted as a fallback and takes the left-most
+ * entry. An untrusted proxy header is spoofable, which is why trust-proxy is
+ * configured explicitly rather than assumed.
+ */
+export declare function clientIp(request: RequestLike): string;
+export {};
+//# sourceMappingURL=rate-limit.guard.d.ts.map

package/dist/security/rate-limit.guard.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * The global throttle guard (PLAN.md §12).
+ *
+ * The legacy framework installed `@nestjs/throttler` but never registered a
+ * guard, so only one endpoint was ever limited and brute force was unimpeded.
+ * Here the guard is global: routes are limited unless they opt out, which is the
+ * direction that fails safe.
+ */
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitGuard = exports.DEFAULT_RATE_LIMIT = void 0;
+exports.clientIp = clientIp;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const constants_js_1 = require("../constants.js");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const catalog_js_1 = require("../errors/catalog.js");
+const tokens_js_1 = require("../tokens.js");
+/** Defaults: 100 requests a minute per caller. */
+exports.DEFAULT_RATE_LIMIT = { limit: 100, windowMs: 60_000 };
+let RateLimitGuard = class RateLimitGuard {
+    reflector;
+    context;
+    config;
+    store;
+    constructor(reflector, context, config, store) {
+        this.reflector = reflector;
+        this.context = context;
+        this.config = config;
+        this.store = store;
+    }
+    async canActivate(execution) {
+        if (execution.getType() !== 'http')
+            return true;
+        const settings = this.config.security?.rateLimit;
+        if (settings?.enabled === false || this.store === undefined)
+            return true;
+        const skip = this.reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.skipRateLimit, [execution.getHandler(), execution.getClass()]);
+        if (skip === true)
+            return true;
+        const http = execution.switchToHttp();
+        const request = http.getRequest();
+        if (this.#isExcluded(request.url, settings?.excludePaths))
+            return true;
+        const policy = this.#resolvePolicy(execution, settings);
+        const key = this.#buildKey(execution, request, settings?.perUser ?? true);
+        const result = await this.store.consume(key, policy.limit, policy.windowMs);
+        const response = http.getResponse();
+        response.setHeader?.('ratelimit-limit', result.limit);
+        response.setHeader?.('ratelimit-remaining', result.remaining);
+        response.setHeader?.('ratelimit-reset', Math.ceil((result.resetAt - Date.now()) / 1000));
+        if (!result.allowed) {
+            response.setHeader?.('retry-after', result.retryAfterSeconds);
+            throw new catalog_js_1.RateLimitError(result.retryAfterSeconds, {
+                detail: `Rate limit of ${policy.limit} per ${policy.windowMs}ms exceeded`,
+                meta: { key, limit: policy.limit, windowMs: policy.windowMs },
+            });
+        }
+        return true;
+    }
+    #resolvePolicy(execution, settings) {
+        const route = this.reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.rateLimit, [execution.getHandler(), execution.getClass()]);
+        if (route !== undefined)
+            return route;
+        return {
+            limit: settings?.limit ?? exports.DEFAULT_RATE_LIMIT.limit,
+            windowMs: settings?.windowMs ?? exports.DEFAULT_RATE_LIMIT.windowMs,
+        };
+    }
+    /**
+     * Budgets are per caller **and** per route, so one hammered endpoint cannot
+     * exhaust a caller's budget for every other endpoint. An authenticated caller
+     * is counted by user id: behind a shared NAT, IP alone would let one client
+     * throttle a whole office.
+     */
+    #buildKey(execution, request, perUser) {
+        const user = perUser ? this.context.get()?.user : undefined;
+        const identity = user === undefined ? `ip:${clientIp(request)}` : `user:${String(user.id)}`;
+        const route = `${request.method ?? 'GET'} ${execution.getClass().name}.${execution.getHandler().name}`;
+        return `${identity}|${route}`;
+    }
+    #isExcluded(url, excludePaths) {
+        if (url === undefined || excludePaths === undefined)
+            return false;
+        const path = url.split('?', 1)[0] ?? url;
+        return excludePaths.some((excluded) => path === excluded || path.startsWith(`${excluded}/`));
+    }
+};
+exports.RateLimitGuard = RateLimitGuard;
+exports.RateLimitGuard = RateLimitGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(core_1.Reflector)),
+    __param(1, (0, common_1.Inject)(request_context_service_js_1.RequestContextService)),
+    __param(2, (0, common_1.Inject)(tokens_js_1.NAGE_CONFIG)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(tokens_js_1.NAGE_RATE_LIMIT_STORE)),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        request_context_service_js_1.RequestContextService, Object, Object])
+], RateLimitGuard);
+/**
+ * Best-effort client address.
+ *
+ * `request.ip` already honours the trust-proxy setting, so it is preferred;
+ * `x-forwarded-for` is only consulted as a fallback and takes the left-most
+ * entry. An untrusted proxy header is spoofable, which is why trust-proxy is
+ * configured explicitly rather than assumed.
+ */
+function clientIp(request) {
+    if (request.ip !== undefined && request.ip !== '')
+        return request.ip;
+    const forwarded = request.headers?.['x-forwarded-for'];
+    const first = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    const candidate = first?.split(',')[0]?.trim();
+    if (candidate !== undefined && candidate !== '')
+        return candidate;
+    return request.socket?.remoteAddress ?? 'unknown';
+}
+//# sourceMappingURL=rate-limit.guard.js.map

package/dist/security/rate-limit.store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-process rate-limit counters (PLAN.md §12).
+ *
+ * A fixed window per key: cheap, predictable, and enough for a single instance.
+ * It is deliberately behind `RateLimitStore` because it is **per process** — a
+ * limit of 100 across four pods is 400 unless a shared store is supplied through
+ * `NageCoreModule.forRoot(config, { rateLimitStore })`.
+ *
+ * No shared implementation ships. An earlier version of this comment said
+ * `@nage-api/cache` provided a Redis-backed one; it never did, and a false claim here
+ * is worse than the gap, because it reads as "already handled" to the one person
+ * who would otherwise have written it.
+ */
+import type { RateLimitResult, RateLimitStore } from '@nage-api/contracts';
+export interface MemoryRateLimitStoreOptions {
+    /** Injectable clock, so window expiry is testable without waiting. */
+    readonly now?: () => number;
+    /** Entries are swept once this many keys accumulate. */
+    readonly sweepThreshold?: number;
+}
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    #private;
+    readonly name = "memory";
+    constructor(options?: MemoryRateLimitStoreOptions);
+    consume(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+    reset(key: string): Promise<void>;
+    /** Current number of tracked keys — for tests and health reporting. */
+    get size(): number;
+}
+//# sourceMappingURL=rate-limit.store.d.ts.map

package/dist/security/rate-limit.store.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * In-process rate-limit counters (PLAN.md §12).
+ *
+ * A fixed window per key: cheap, predictable, and enough for a single instance.
+ * It is deliberately behind `RateLimitStore` because it is **per process** — a
+ * limit of 100 across four pods is 400 unless a shared store is supplied through
+ * `NageCoreModule.forRoot(config, { rateLimitStore })`.
+ *
+ * No shared implementation ships. An earlier version of this comment said
+ * `@nage-api/cache` provided a Redis-backed one; it never did, and a false claim here
+ * is worse than the gap, because it reads as "already handled" to the one person
+ * who would otherwise have written it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRateLimitStore = void 0;
+class MemoryRateLimitStore {
+    name = 'memory';
+    #windows = new Map();
+    #now;
+    #sweepThreshold;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+        this.#sweepThreshold = options.sweepThreshold ?? 10_000;
+    }
+    consume(key, limit, windowMs) {
+        const now = this.#now();
+        const existing = this.#windows.get(key);
+        const window = existing === undefined || existing.resetAt <= now
+            ? { count: 0, resetAt: now + windowMs }
+            : existing;
+        window.count += 1;
+        this.#windows.set(key, window);
+        // An unbounded map is a memory leak an attacker can drive by varying the
+        // key, so expired windows are swept once the map grows.
+        if (this.#windows.size > this.#sweepThreshold)
+            this.#sweep(now);
+        const allowed = window.count <= limit;
+        return Promise.resolve({
+            allowed,
+            limit,
+            remaining: Math.max(0, limit - window.count),
+            resetAt: window.resetAt,
+            retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((window.resetAt - now) / 1000)),
+        });
+    }
+    reset(key) {
+        this.#windows.delete(key);
+        return Promise.resolve();
+    }
+    /** Current number of tracked keys — for tests and health reporting. */
+    get size() {
+        return this.#windows.size;
+    }
+    #sweep(now) {
+        for (const [key, window] of this.#windows) {
+            if (window.resetAt <= now)
+                this.#windows.delete(key);
+        }
+    }
+}
+exports.MemoryRateLimitStore = MemoryRateLimitStore;
+//# sourceMappingURL=rate-limit.store.js.map

package/dist/security/redaction.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Redaction (PLAN.md §12, §18).
+ *
+ * Structured logs are only safe if the structure cannot smuggle a credential
+ * out. Three places need scrubbing, and all three are here so they cannot drift:
+ * arbitrary field values, request headers, and URLs carrying tokens in the query
+ * string.
+ */
+export declare const REDACTED = "[redacted]";
+/**
+ * Substituted where the walk stops.
+ *
+ * The depth bound used to `return value`, which meant a credential nested deeper
+ * than the bound was written out verbatim — the redaction failed *open* at
+ * exactly the point where the structure was most likely to be something the
+ * caller had not thought about. Whatever cannot be scrubbed is not logged.
+ */
+export declare const TRUNCATED = "[truncated]";
+/** A structure that refers to itself. Emitted instead of recursing forever. */
+export declare const CIRCULAR = "[circular]";
+/** Headers that carry credentials and are never logged verbatim. */
+export declare const REDACTED_HEADERS: readonly string[];
+/** Query parameters that carry credentials, e.g. `?access_token=…`. */
+export declare const REDACTED_QUERY_PARAMS: readonly string[];
+/** Build a lookup set from the defaults plus any configured extras. */
+export declare function redactionSet(extra?: readonly string[]): ReadonlySet<string>;
+/**
+ * Replace the value of any matching key, at any depth.
+ *
+ * Three things this has to survive, because a logger that throws inside a
+ * request handler turns a log line into a 500:
+ *
+ *  - **Depth.** Bounded, and the bound substitutes `TRUNCATED` rather than
+ *    passing the subtree through — see that constant.
+ *  - **Cycles.** A request object, a Sequelize instance and an Axios error all
+ *    refer back to themselves. Tracked per branch, so a value that legitimately
+ *    appears twice side by side is still logged twice.
+ *  - **Values `JSON.stringify` mangles.** A `Date` has no own enumerable
+ *    properties, so walking it produced `{}` and lost the timestamp entirely; a
+ *    `Buffer` expanded into one key per byte, turning a 1MB upload into a log
+ *    line nothing will ever read.
+ */
+export declare function redact(value: unknown, fields: ReadonlySet<string>, depth?: number, seen?: ReadonlySet<object>): unknown;
+/** Scrub credential-bearing request headers before they reach a log line. */
+export declare function redactHeaders(headers: Record<string, unknown> | undefined, extra?: readonly string[]): Record<string, unknown>;
+/**
+ * Scrub credentials out of a URL's query string.
+ *
+ * Request URLs are logged on every error; a token passed as a query parameter
+ * (which the legacy WebSocket handshake did) would otherwise be written to disk
+ * in clear text on every failure.
+ */
+export declare function redactUrl(url: string | undefined): string | undefined;
+//# sourceMappingURL=redaction.d.ts.map