@nage-api/core 1.0.0-beta.2

package/dist/module/core.module.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * `NageCoreModule.forRoot(config)` — the one module every application imports
+ * (PLAN.md §7.3).
+ *
+ * Registering the interceptor, filter and guard as providers (rather than
+ * `app.useGlobal*`) keeps them inside the DI container, so they can inject the
+ * context and the logger, and so tests get the same wiring as production.
+ */
+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 NageCoreModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageCoreModule = void 0;
+exports.buildValidationPipe = buildValidationPipe;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const lifecycle_js_1 = require("../bootstrap/lifecycle.js");
+const request_context_middleware_js_1 = require("../context/request-context.middleware.js");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const api_version_guard_js_1 = require("../guards/api-version.guard.js");
+const all_exceptions_filter_js_1 = require("../http/all-exceptions.filter.js");
+const request_timeout_interceptor_js_1 = require("../http/request-timeout.interceptor.js");
+const response_interceptor_js_1 = require("../http/response.interceptor.js");
+const json_logger_js_1 = require("../logging/json.logger.js");
+const rate_limit_guard_js_1 = require("../security/rate-limit.guard.js");
+const rate_limit_store_js_1 = require("../security/rate-limit.store.js");
+const tokens_js_1 = require("../tokens.js");
+/**
+ * Validation defaults (§16.2). `forbidNonWhitelisted` means an unexpected
+ * property is an error rather than something silently dropped — a mass-assignment
+ * guard, not a style preference.
+ */
+function buildValidationPipe(config) {
+    return new common_1.ValidationPipe({
+        whitelist: config.validation?.whitelist ?? true,
+        forbidNonWhitelisted: config.validation?.forbidNonWhitelisted ?? true,
+        transform: config.validation?.transform ?? true,
+        transformOptions: { enableImplicitConversion: false },
+    });
+}
+let NageCoreModule = NageCoreModule_1 = class NageCoreModule {
+    static forRoot(config, options = {}) {
+        const providers = [
+            { provide: tokens_js_1.NAGE_CONFIG, useValue: config },
+            // The process's phase, not this module's: `installShutdown` flips it to
+            // `draining` on a signal and `/health/ready` reads it (§21). Published as a
+            // provider so a controller can inject it rather than import a singleton.
+            { provide: tokens_js_1.NAGE_LIFECYCLE, useValue: (0, lifecycle_js_1.processLifecycle)() },
+            request_context_service_js_1.RequestContextService,
+            { provide: tokens_js_1.NAGE_REQUEST_CONTEXT, useExisting: request_context_service_js_1.RequestContextService },
+            { provide: tokens_js_1.NAGE_LOGGER, useClass: json_logger_js_1.JsonLogger },
+            request_context_middleware_js_1.RequestContextMiddleware,
+            { provide: core_1.APP_INTERCEPTOR, useClass: response_interceptor_js_1.ResponseInterceptor },
+            // Registered after the envelope interceptor, which makes it the inner one:
+            // the timeout has to be closer to the handler than anything that maps its
+            // result, and the error it raises travels out to the exception filter like
+            // any other. On by default, and `http.requestTimeoutMs: 0` is the only way
+            // to have no ceiling at all (§21).
+            { provide: core_1.APP_INTERCEPTOR, useClass: request_timeout_interceptor_js_1.RequestTimeoutInterceptor },
+            { provide: core_1.APP_FILTER, useClass: all_exceptions_filter_js_1.AllExceptionsFilter },
+            { provide: core_1.APP_GUARD, useClass: api_version_guard_js_1.ApiVersionGuard },
+        ];
+        // Throttling is global and opt-out (§12): the legacy framework registered
+        // no guard at all, so only one endpoint was ever limited. The in-process
+        // store is the default, and it counts per process — `options.rateLimitStore`
+        // is how a multi-instance deployment makes the limit mean what it says.
+        const rateLimitEnabled = config.security?.rateLimit?.enabled !== false;
+        if (rateLimitEnabled) {
+            providers.push({
+                provide: tokens_js_1.NAGE_RATE_LIMIT_STORE,
+                useValue: options.rateLimitStore ?? new rate_limit_store_js_1.MemoryRateLimitStore(),
+            }, { provide: core_1.APP_GUARD, useClass: rate_limit_guard_js_1.RateLimitGuard });
+        }
+        // Validation needs class-validator/class-transformer, which are optional
+        // peers: an app that has no DTOs should not have to install them.
+        if (config.validation?.enabled !== false) {
+            providers.push({ provide: core_1.APP_PIPE, useValue: buildValidationPipe(config) });
+        }
+        return {
+            module: NageCoreModule_1,
+            providers,
+            // Only export what was actually provided: exporting the store token while
+            // throttling is off makes the whole application fail to boot.
+            exports: [
+                tokens_js_1.NAGE_CONFIG,
+                tokens_js_1.NAGE_LIFECYCLE,
+                tokens_js_1.NAGE_LOGGER,
+                tokens_js_1.NAGE_REQUEST_CONTEXT,
+                request_context_service_js_1.RequestContextService,
+                ...(rateLimitEnabled ? [tokens_js_1.NAGE_RATE_LIMIT_STORE] : []),
+            ],
+        };
+    }
+    configure(consumer) {
+        // Every route, including ones added by feature packages. The middleware is
+        // idempotent, so an app that also installs it in `bootstrap()` is fine.
+        consumer
+            .apply(request_context_middleware_js_1.RequestContextMiddleware)
+            .forRoutes({ path: '*path', method: common_1.RequestMethod.ALL });
+    }
+};
+exports.NageCoreModule = NageCoreModule;
+exports.NageCoreModule = NageCoreModule = NageCoreModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], NageCoreModule);
+//# sourceMappingURL=core.module.js.map

package/dist/security/audit.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The security audit behind `nage doctor` (PLAN.md §12, §24 Phase 4).
+ *
+ * Pure functions over a configuration and an environment: no filesystem, no CLI,
+ * no Nest. Phase 6's `nage doctor` renders these findings, `assertSecureConfig`
+ * enforces them at boot, and tests assert them directly — one implementation,
+ * three consumers.
+ *
+ * The reference list is §12's table: every insecure default the legacy framework
+ * shipped with should be findable here.
+ */
+import type { NageConfig, SecurityFinding, SecuritySeverity } from '@nage-api/contracts';
+export interface SecurityAuditInput {
+    readonly config: NageConfig;
+    /**
+     * Environment values, used only to judge secret **strength**. Values are never
+     * copied into a finding.
+     */
+    readonly env?: Record<string, string | undefined>;
+}
+/** Order used when sorting a report; worst first. */
+export declare const SEVERITY_ORDER: readonly SecuritySeverity[];
+/**
+ * Audit a configuration against the security baseline.
+ *
+ * @returns findings sorted worst-first; an empty array means nothing to fix.
+ */
+export declare function auditSecurity(input: SecurityAuditInput): readonly SecurityFinding[];
+/** Sort worst-first, then by location, so reports are stable across runs. */
+export declare function sortFindings(findings: readonly SecurityFinding[]): SecurityFinding[];
+/** `15m`, `24h`, `30d` → milliseconds. Unparseable input counts as zero. */
+export declare function parseDurationMs(duration: string): number;
+/**
+ * Boot-time gate (§21): refuse to start with a critical finding.
+ *
+ * On by default in production and staging. Development reports and continues —
+ * a baseline that blocks local work is a baseline people switch off.
+ */
+export declare function assertSecureConfig(input: SecurityAuditInput): readonly SecurityFinding[];
+/** Render findings for a terminal — used by `nage doctor` (Phase 6). */
+export declare function formatFindings(findings: readonly SecurityFinding[]): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/security/audit.js

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * The security audit behind `nage doctor` (PLAN.md §12, §24 Phase 4).
+ *
+ * Pure functions over a configuration and an environment: no filesystem, no CLI,
+ * no Nest. Phase 6's `nage doctor` renders these findings, `assertSecureConfig`
+ * enforces them at boot, and tests assert them directly — one implementation,
+ * three consumers.
+ *
+ * The reference list is §12's table: every insecure default the legacy framework
+ * shipped with should be findable here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_ORDER = void 0;
+exports.auditSecurity = auditSecurity;
+exports.sortFindings = sortFindings;
+exports.parseDurationMs = parseDurationMs;
+exports.assertSecureConfig = assertSecureConfig;
+exports.formatFindings = formatFindings;
+const catalog_js_1 = require("../errors/catalog.js");
+/** Order used when sorting a report; worst first. */
+exports.SEVERITY_ORDER = [
+    'critical',
+    'high',
+    'medium',
+    'low',
+    'info',
+];
+/** Secrets shorter than this are rejected outright. */
+const MINIMUM_SECRET_LENGTH = 16;
+/** Values that appear in every default config and every breach list. */
+const KNOWN_WEAK_SECRETS = new Set([
+    'changeme',
+    'change-me',
+    'secret',
+    'password',
+    'passw0rd',
+    '123456',
+    '12345678',
+    'admin',
+    'test',
+    'dev',
+    'nage',
+    'jwt-secret',
+    'your-secret-key',
+]);
+const SECRET_VARIABLE_PATTERN = /(SECRET|PASSWORD|PRIVATE_KEY|_KEY|TOKEN|CREDENTIAL|PEPPER)/i;
+/** Variables that name a file or an identifier rather than a credential. */
+const SECRET_VARIABLE_EXCEPTIONS = /(KEY_PATH|KEY_FILE|KEY_ID|PUBLIC_KEY|_URL|_URI)$/i;
+/**
+ * A finding's severity depends on where it is found: an unverified TLS mode is a
+ * critical problem in production and a note in development.
+ */
+function inProduction(environment) {
+    return environment === 'production' || environment === 'staging';
+}
+function escalate(environment, productionSeverity, otherwise) {
+    return inProduction(environment) ? productionSeverity : otherwise;
+}
+/**
+ * Audit a configuration against the security baseline.
+ *
+ * @returns findings sorted worst-first; an empty array means nothing to fix.
+ */
+function auditSecurity(input) {
+    const { config } = input;
+    const environment = config.app.environment;
+    const findings = [];
+    // ── CORS (§12: `enableCors()` with no arguments allowed every origin) ─────
+    const cors = config.http?.cors;
+    if (cors?.origins === '*') {
+        findings.push({
+            code: 'SEC_CORS_WILDCARD',
+            severity: escalate(environment, 'critical', 'low'),
+            location: 'http.cors.origins',
+            message: 'Every origin is allowed to call this API.',
+            remediation: 'Replace "*" with an explicit list of the origins that need access.',
+        });
+        if (cors.credentials === true) {
+            findings.push({
+                code: 'SEC_CORS_WILDCARD_WITH_CREDENTIALS',
+                severity: 'critical',
+                location: 'http.cors.credentials',
+                message: 'Credentialed requests are accepted from any origin.',
+                remediation: 'Set an explicit origin allow-list, or turn credentials off.',
+            });
+        }
+    }
+    // ── Secure headers ────────────────────────────────────────────────────────
+    if (config.http?.helmet?.enabled === false) {
+        findings.push({
+            code: 'SEC_HELMET_DISABLED',
+            severity: escalate(environment, 'high', 'medium'),
+            location: 'http.helmet.enabled',
+            message: 'Security headers are not sent (no CSP, no nosniff, no frame protection).',
+            remediation: 'Remove `helmet.enabled: false`; disable individual headers instead if needed.',
+        });
+    }
+    else if (config.http?.helmet?.contentSecurityPolicy === false) {
+        findings.push({
+            code: 'SEC_CSP_DISABLED',
+            severity: 'medium',
+            location: 'http.helmet.contentSecurityPolicy',
+            message: 'Content-Security-Policy is disabled for the whole application.',
+            remediation: 'Scope the exemption to the routes that need it, such as Swagger UI.',
+        });
+    }
+    if (inProduction(environment) && config.http?.helmet?.hsts === false) {
+        findings.push({
+            code: 'SEC_HSTS_DISABLED',
+            severity: 'high',
+            location: 'http.helmet.hsts',
+            message: 'HSTS is switched off in a deployed environment.',
+            remediation: 'Leave HSTS on so browsers refuse to downgrade to plain HTTP.',
+        });
+    }
+    // ── TLS to the database (§12: `rejectUnauthorized: false`) ────────────────
+    const ssl = config.database?.ssl;
+    if (ssl === 'no-verify') {
+        findings.push({
+            code: 'SEC_TLS_NO_VERIFY',
+            severity: escalate(environment, 'critical', 'medium'),
+            location: 'database.ssl',
+            message: 'The database certificate is not verified; the connection is interceptable.',
+            remediation: 'Use "verify-full" and install the server CA where the app can read it.',
+        });
+    }
+    else if (ssl === 'disable' && config.database?.enabled === true) {
+        findings.push({
+            code: 'SEC_TLS_DISABLED',
+            severity: escalate(environment, 'critical', 'low'),
+            location: 'database.ssl',
+            message: 'The database connection is not encrypted.',
+            remediation: 'Set database.ssl to "verify-full" outside local development.',
+        });
+    }
+    // ── Input validation ──────────────────────────────────────────────────────
+    if (config.validation?.enabled === false) {
+        findings.push({
+            code: 'SEC_VALIDATION_DISABLED',
+            severity: 'high',
+            location: 'validation.enabled',
+            message: 'Request bodies are not validated.',
+            remediation: 'Re-enable validation; exempt individual routes instead if necessary.',
+        });
+    }
+    else if (config.validation?.forbidNonWhitelisted === false) {
+        findings.push({
+            code: 'SEC_VALIDATION_PERMISSIVE',
+            severity: 'medium',
+            location: 'validation.forbidNonWhitelisted',
+            message: 'Unexpected body properties are dropped silently instead of rejected.',
+            remediation: 'Set forbidNonWhitelisted: true so mass-assignment attempts fail loudly.',
+        });
+    }
+    // ── Throttling (§12: the legacy throttler had no global guard) ────────────
+    if (config.security?.rateLimit?.enabled === false) {
+        findings.push({
+            code: 'SEC_RATE_LIMIT_DISABLED',
+            severity: escalate(environment, 'high', 'low'),
+            location: 'security.rateLimit.enabled',
+            message: 'No global request limit; brute-force and scraping are unimpeded.',
+            remediation: 'Leave the global limit on and exempt specific routes with @SkipRateLimit().',
+        });
+    }
+    // ── Query limits (§12: `limit: -1` was unbounded) ─────────────────────────
+    const maxQueryLimit = config.database?.maxQueryLimit;
+    if (maxQueryLimit !== undefined && (maxQueryLimit <= 0 || maxQueryLimit > 1000)) {
+        findings.push({
+            code: 'SEC_UNBOUNDED_QUERY_LIMIT',
+            severity: maxQueryLimit <= 0 ? 'high' : 'medium',
+            location: 'database.maxQueryLimit',
+            message: maxQueryLimit <= 0
+                ? 'Clients can request an unbounded number of rows.'
+                : `A single request can ask for ${maxQueryLimit} rows.`,
+            remediation: 'Set a bounded maxQueryLimit (100 is the default) and use cursors for exports.',
+        });
+    }
+    // ── Deployment behaviour ──────────────────────────────────────────────────
+    if (inProduction(environment) && config.database?.migrations?.runOnBoot === true) {
+        findings.push({
+            code: 'SEC_MIGRATIONS_ON_BOOT',
+            severity: 'medium',
+            location: 'database.migrations.runOnBoot',
+            message: 'Every instance runs migrations at start-up, concurrently.',
+            remediation: 'Run `nage db migrate` as a deploy step instead.',
+        });
+    }
+    const level = config.logging?.level;
+    if (inProduction(environment) && (level === 'trace' || level === 'debug')) {
+        findings.push({
+            code: 'SEC_DEBUG_LOGGING',
+            severity: 'medium',
+            location: 'logging.level',
+            message: `Log level "${level}" in a deployed environment writes request detail to disk.`,
+            remediation: 'Use "info" or higher in production.',
+        });
+    }
+    if (config.shutdown?.enabled === false) {
+        findings.push({
+            code: 'SEC_SHUTDOWN_HOOKS_DISABLED',
+            severity: 'low',
+            location: 'shutdown.enabled',
+            message: 'Shutdown hooks are off; connections are dropped rather than drained on SIGTERM.',
+            remediation: 'Leave shutdown hooks enabled so deploys do not sever in-flight requests.',
+        });
+    }
+    if (config.http?.requestTimeoutMs === 0) {
+        findings.push({
+            code: 'SEC_NO_REQUEST_TIMEOUT',
+            severity: escalate(environment, 'medium', 'low'),
+            location: 'http.requestTimeoutMs',
+            // Availability is part of the threat model: a handler with no ceiling
+            // holds a connection, a rate-limit slot and (during a deploy) the drain,
+            // which is a resource-exhaustion vector a slow upstream can trigger by
+            // accident and an attacker on purpose.
+            message: 'No request timeout: a slow or wedged handler holds its connection indefinitely.',
+            remediation: 'Leave http.requestTimeoutMs at its default and use @RequestTimeout on the few routes that need longer.',
+        });
+    }
+    findings.push(...auditAuth(config, environment));
+    findings.push(...auditSecrets(input.env));
+    return sortFindings(findings);
+}
+/** Auth-specific checks; skipped entirely when auth is not enabled. */
+function auditAuth(config, environment) {
+    const auth = config.auth;
+    if (auth?.enabled !== true)
+        return [];
+    const findings = [];
+    if (auth.jwt?.algorithm === 'HS256') {
+        findings.push({
+            code: 'SEC_WEAK_JWT_ALGORITHM',
+            severity: escalate(environment, 'high', 'low'),
+            location: 'auth.jwt.algorithm',
+            message: 'HS256 is symmetric: every service that verifies a token can also mint one.',
+            remediation: 'Use RS256 (or ES256) so only the issuer holds the signing key.',
+        });
+    }
+    const accessTtl = auth.jwt?.accessTtl;
+    if (accessTtl !== undefined && parseDurationMs(accessTtl) > 60 * 60 * 1000) {
+        findings.push({
+            code: 'SEC_LONG_ACCESS_TTL',
+            severity: 'medium',
+            location: 'auth.jwt.accessTtl',
+            message: `Access tokens live for ${accessTtl}; a stolen one stays valid that long.`,
+            remediation: 'Keep access tokens short (15m) and rely on refresh rotation.',
+        });
+    }
+    if (auth.refresh?.rotate === false) {
+        findings.push({
+            code: 'SEC_REFRESH_ROTATION_DISABLED',
+            severity: 'high',
+            location: 'auth.refresh.rotate',
+            message: 'Refresh tokens are reusable, so a captured one works until it expires.',
+            remediation: 'Rotate refresh tokens on every use.',
+        });
+    }
+    else if (auth.refresh?.reuseDetection === false) {
+        findings.push({
+            code: 'SEC_REUSE_DETECTION_DISABLED',
+            severity: 'medium',
+            location: 'auth.refresh.reuseDetection',
+            message: 'A replayed refresh token is not detected, so theft goes unnoticed.',
+            remediation: 'Enable reuse detection to revoke the session family on replay.',
+        });
+    }
+    const minLength = auth.password?.minLength;
+    if (minLength !== undefined && minLength < 12) {
+        findings.push({
+            code: 'SEC_WEAK_PASSWORD_POLICY',
+            severity: 'medium',
+            location: 'auth.password.minLength',
+            message: `Passwords as short as ${minLength} characters are accepted.`,
+            remediation: 'Require at least 12 characters.',
+        });
+    }
+    return findings;
+}
+/**
+ * Judge the strength of secret-shaped environment variables.
+ *
+ * Only the variable **name** ever reaches a finding: this report is written to
+ * CI logs and terminals.
+ */
+function auditSecrets(env) {
+    if (env === undefined)
+        return [];
+    const findings = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (!SECRET_VARIABLE_PATTERN.test(name) || SECRET_VARIABLE_EXCEPTIONS.test(name))
+            continue;
+        if (value === undefined || value === '') {
+            findings.push({
+                code: 'SEC_MISSING_SECRET',
+                severity: 'high',
+                location: name,
+                message: `${name} is declared but empty.`,
+                remediation: `Set ${name}, or remove it if the feature that needs it is disabled.`,
+            });
+            continue;
+        }
+        // A PEM key is long by construction and not subject to the length rule.
+        if (value.includes('BEGIN') && value.includes('PRIVATE KEY'))
+            continue;
+        if (KNOWN_WEAK_SECRETS.has(value.toLowerCase())) {
+            findings.push({
+                code: 'SEC_WEAK_SECRET',
+                severity: 'critical',
+                location: name,
+                message: `${name} is set to a well-known placeholder value.`,
+                remediation: `Generate a random value, e.g. \`openssl rand -base64 32\`.`,
+            });
+        }
+        else if (value.length < MINIMUM_SECRET_LENGTH) {
+            findings.push({
+                code: 'SEC_WEAK_SECRET',
+                severity: 'high',
+                location: name,
+                message: `${name} is shorter than ${MINIMUM_SECRET_LENGTH} characters.`,
+                remediation: `Generate a random value, e.g. \`openssl rand -base64 32\`.`,
+            });
+        }
+    }
+    return findings;
+}
+/** Sort worst-first, then by location, so reports are stable across runs. */
+function sortFindings(findings) {
+    return [...findings].sort((left, right) => {
+        const bySeverity = exports.SEVERITY_ORDER.indexOf(left.severity) - exports.SEVERITY_ORDER.indexOf(right.severity);
+        return bySeverity !== 0 ? bySeverity : left.location.localeCompare(right.location);
+    });
+}
+/** `15m`, `24h`, `30d` → milliseconds. Unparseable input counts as zero. */
+function parseDurationMs(duration) {
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(duration);
+    if (match === null)
+        return 0;
+    const amount = Number(match[1]);
+    switch (match[2]) {
+        case 'ms':
+            return amount;
+        case 's':
+            return amount * 1000;
+        case 'm':
+            return amount * 60_000;
+        case 'h':
+            return amount * 3_600_000;
+        case 'd':
+            return amount * 86_400_000;
+        default:
+            return 0;
+    }
+}
+/**
+ * Boot-time gate (§21): refuse to start with a critical finding.
+ *
+ * On by default in production and staging. Development reports and continues —
+ * a baseline that blocks local work is a baseline people switch off.
+ */
+function assertSecureConfig(input) {
+    const findings = auditSecurity(input);
+    const environment = input.config.app.environment;
+    const enforce = input.config.security?.assertOnBoot ?? inProduction(environment);
+    const blocking = findings.filter((finding) => finding.severity === 'critical');
+    if (enforce && blocking.length > 0) {
+        throw new catalog_js_1.ConfigurationError({
+            detail: `Refusing to start: ${blocking.length} critical security ${blocking.length === 1 ? 'problem' : 'problems'} in the configuration (${blocking.map((finding) => finding.code).join(', ')})`,
+            meta: {
+                findings: blocking.map((finding) => `${finding.code} at ${finding.location}`),
+                environment,
+            },
+        });
+    }
+    return findings;
+}
+/** Render findings for a terminal — used by `nage doctor` (Phase 6). */
+function formatFindings(findings) {
+    if (findings.length === 0)
+        return '✔ No security findings.';
+    const marks = {
+        critical: '✖',
+        high: '✖',
+        medium: '▲',
+        low: '▲',
+        info: 'ℹ',
+    };
+    return [
+        `Security findings (${findings.length}):`,
+        '',
+        ...findings.flatMap((finding) => [
+            `  ${marks[finding.severity]} [${finding.severity}] ${finding.code} — ${finding.location}`,
+            `      ${finding.message}`,
+            `      → ${finding.remediation}`,
+        ]),
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=audit.js.map

package/dist/security/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The security baseline (PLAN.md §12, Phase 4).
+ *
+ * Secure defaults that apply everywhere, plus the audit that reports when a
+ * configuration departs from them.
+ */
+export { randomHex, randomId, randomInt, randomOtp, randomString, randomToken, secureCompare, ALPHANUMERIC_ALPHABET, UNAMBIGUOUS_ALPHABET, } from './random.js';
+export { redact, redactHeaders, redactUrl, redactionSet, REDACTED, REDACTED_HEADERS, REDACTED_QUERY_PARAMS, } from './redaction.js';
+export { assertTlsAllowed, resolveTlsOptions, DEFAULT_TLS_MODE, type TlsOptions } from './tls.js';
+export { MemoryRateLimitStore, type MemoryRateLimitStoreOptions } from './rate-limit.store.js';
+export { RateLimit, SkipRateLimit, type RateLimitPolicy } from './rate-limit.decorators.js';
+export { RateLimitGuard, clientIp, DEFAULT_RATE_LIMIT } from './rate-limit.guard.js';
+export { assertSecureConfig, auditSecurity, formatFindings, parseDurationMs, sortFindings, SEVERITY_ORDER, type SecurityAuditInput, } from './audit.js';
+export { scanForLegacyPatterns, type SourceFile } from './legacy-scan.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * The security baseline (PLAN.md §12, Phase 4).
+ *
+ * Secure defaults that apply everywhere, plus the audit that reports when a
+ * configuration departs from them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanForLegacyPatterns = exports.SEVERITY_ORDER = exports.sortFindings = exports.parseDurationMs = exports.formatFindings = exports.auditSecurity = exports.assertSecureConfig = exports.DEFAULT_RATE_LIMIT = exports.clientIp = exports.RateLimitGuard = exports.SkipRateLimit = exports.RateLimit = exports.MemoryRateLimitStore = exports.DEFAULT_TLS_MODE = exports.resolveTlsOptions = exports.assertTlsAllowed = exports.REDACTED_QUERY_PARAMS = exports.REDACTED_HEADERS = exports.REDACTED = exports.redactionSet = exports.redactUrl = exports.redactHeaders = exports.redact = exports.UNAMBIGUOUS_ALPHABET = exports.ALPHANUMERIC_ALPHABET = exports.secureCompare = exports.randomToken = exports.randomString = exports.randomOtp = exports.randomInt = exports.randomId = exports.randomHex = void 0;
+var random_js_1 = require("./random.js");
+Object.defineProperty(exports, "randomHex", { enumerable: true, get: function () { return random_js_1.randomHex; } });
+Object.defineProperty(exports, "randomId", { enumerable: true, get: function () { return random_js_1.randomId; } });
+Object.defineProperty(exports, "randomInt", { enumerable: true, get: function () { return random_js_1.randomInt; } });
+Object.defineProperty(exports, "randomOtp", { enumerable: true, get: function () { return random_js_1.randomOtp; } });
+Object.defineProperty(exports, "randomString", { enumerable: true, get: function () { return random_js_1.randomString; } });
+Object.defineProperty(exports, "randomToken", { enumerable: true, get: function () { return random_js_1.randomToken; } });
+Object.defineProperty(exports, "secureCompare", { enumerable: true, get: function () { return random_js_1.secureCompare; } });
+Object.defineProperty(exports, "ALPHANUMERIC_ALPHABET", { enumerable: true, get: function () { return random_js_1.ALPHANUMERIC_ALPHABET; } });
+Object.defineProperty(exports, "UNAMBIGUOUS_ALPHABET", { enumerable: true, get: function () { return random_js_1.UNAMBIGUOUS_ALPHABET; } });
+var redaction_js_1 = require("./redaction.js");
+Object.defineProperty(exports, "redact", { enumerable: true, get: function () { return redaction_js_1.redact; } });
+Object.defineProperty(exports, "redactHeaders", { enumerable: true, get: function () { return redaction_js_1.redactHeaders; } });
+Object.defineProperty(exports, "redactUrl", { enumerable: true, get: function () { return redaction_js_1.redactUrl; } });
+Object.defineProperty(exports, "redactionSet", { enumerable: true, get: function () { return redaction_js_1.redactionSet; } });
+Object.defineProperty(exports, "REDACTED", { enumerable: true, get: function () { return redaction_js_1.REDACTED; } });
+Object.defineProperty(exports, "REDACTED_HEADERS", { enumerable: true, get: function () { return redaction_js_1.REDACTED_HEADERS; } });
+Object.defineProperty(exports, "REDACTED_QUERY_PARAMS", { enumerable: true, get: function () { return redaction_js_1.REDACTED_QUERY_PARAMS; } });
+var tls_js_1 = require("./tls.js");
+Object.defineProperty(exports, "assertTlsAllowed", { enumerable: true, get: function () { return tls_js_1.assertTlsAllowed; } });
+Object.defineProperty(exports, "resolveTlsOptions", { enumerable: true, get: function () { return tls_js_1.resolveTlsOptions; } });
+Object.defineProperty(exports, "DEFAULT_TLS_MODE", { enumerable: true, get: function () { return tls_js_1.DEFAULT_TLS_MODE; } });
+var rate_limit_store_js_1 = require("./rate-limit.store.js");
+Object.defineProperty(exports, "MemoryRateLimitStore", { enumerable: true, get: function () { return rate_limit_store_js_1.MemoryRateLimitStore; } });
+var rate_limit_decorators_js_1 = require("./rate-limit.decorators.js");
+Object.defineProperty(exports, "RateLimit", { enumerable: true, get: function () { return rate_limit_decorators_js_1.RateLimit; } });
+Object.defineProperty(exports, "SkipRateLimit", { enumerable: true, get: function () { return rate_limit_decorators_js_1.SkipRateLimit; } });
+var rate_limit_guard_js_1 = require("./rate-limit.guard.js");
+Object.defineProperty(exports, "RateLimitGuard", { enumerable: true, get: function () { return rate_limit_guard_js_1.RateLimitGuard; } });
+Object.defineProperty(exports, "clientIp", { enumerable: true, get: function () { return rate_limit_guard_js_1.clientIp; } });
+Object.defineProperty(exports, "DEFAULT_RATE_LIMIT", { enumerable: true, get: function () { return rate_limit_guard_js_1.DEFAULT_RATE_LIMIT; } });
+var audit_js_1 = require("./audit.js");
+Object.defineProperty(exports, "assertSecureConfig", { enumerable: true, get: function () { return audit_js_1.assertSecureConfig; } });
+Object.defineProperty(exports, "auditSecurity", { enumerable: true, get: function () { return audit_js_1.auditSecurity; } });
+Object.defineProperty(exports, "formatFindings", { enumerable: true, get: function () { return audit_js_1.formatFindings; } });
+Object.defineProperty(exports, "parseDurationMs", { enumerable: true, get: function () { return audit_js_1.parseDurationMs; } });
+Object.defineProperty(exports, "sortFindings", { enumerable: true, get: function () { return audit_js_1.sortFindings; } });
+Object.defineProperty(exports, "SEVERITY_ORDER", { enumerable: true, get: function () { return audit_js_1.SEVERITY_ORDER; } });
+var legacy_scan_js_1 = require("./legacy-scan.js");
+Object.defineProperty(exports, "scanForLegacyPatterns", { enumerable: true, get: function () { return legacy_scan_js_1.scanForLegacyPatterns; } });
+//# sourceMappingURL=index.js.map

package/dist/security/legacy-scan.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+import type { SecurityFinding } from '@nage-api/contracts';
+export interface SourceFile {
+    readonly path: string;
+    readonly content: string;
+}
+/**
+ * Scan files for legacy insecure patterns.
+ *
+ * @returns one finding per match, located as `path:line`.
+ */
+export declare function scanForLegacyPatterns(files: readonly SourceFile[]): readonly SecurityFinding[];
+//# sourceMappingURL=legacy-scan.d.ts.map