@astram/guard 0.18.0 → 0.20.0

package/dist/captcha/captcha.providers.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCaptchaVerifier = buildCaptchaVerifier;
+exports.captchaProviders = captchaProviders;
+/**
+ * `AuthModule` providers for the `captcha` option (auth capabilities R7.1, D-6):
+ * - absent ⇒ `SHIELD_CAPTCHA_CONFIG` and `SHIELD_CAPTCHA_GATE` bound `null` (every route as today,
+ *   no `CAPTCHA_*` variable read);
+ * - `'env'` ⇒ the config from `CAPTCHA_*` (`loadCaptchaConfig`, boot fails on a bad value), the
+ *   provider's verifier, and the gate over the guard's Redis client and the auth audit sink. One
+ *   boot line names the provider, mode, fail mode and endpoints (never the keys).
+ */
+const common_1 = require("@nestjs/common");
+const captcha_config_js_1 = require("../config/captcha-config.js");
+const boot_secrets_js_1 = require("../secrets/boot-secrets.js");
+const captcha_gate_js_1 = require("../auth/captcha-gate.js");
+const tokens_js_1 = require("../auth/tokens.js");
+const recaptcha_verifier_js_1 = require("./recaptcha-verifier.js");
+const turnstile_verifier_js_1 = require("./turnstile-verifier.js");
+/** Build the adapter named by `CAPTCHA_PROVIDER`. */
+function buildCaptchaVerifier(config) {
+    if (config.provider === 'turnstile') {
+        return new turnstile_verifier_js_1.TurnstileVerifier({
+            secret: config.secret,
+            expectedHostnames: config.expectedHostnames,
+            timeoutMs: config.timeoutMs,
+        });
+    }
+    return new recaptcha_verifier_js_1.RecaptchaVerifier({
+        version: config.provider === 'recaptcha-v3' ? 'v3' : 'v2',
+        secret: config.secret,
+        expectedHostnames: config.expectedHostnames,
+        minScore: config.minScore,
+        timeoutMs: config.timeoutMs,
+    });
+}
+/** Providers for one `AuthModule` registration (see the file header). */
+function captchaProviders(option) {
+    if (option !== undefined && option !== 'env') {
+        throw new Error("ShieldModule: `captcha` must be 'env' (or omitted)");
+    }
+    if (option === undefined) {
+        return [
+            { provide: tokens_js_1.SHIELD_CAPTCHA_CONFIG, useValue: null },
+            { provide: tokens_js_1.SHIELD_CAPTCHA_GATE, useValue: null },
+        ];
+    }
+    return [
+        {
+            provide: tokens_js_1.SHIELD_CAPTCHA_CONFIG,
+            useFactory: () => (0, captcha_config_js_1.loadCaptchaConfig)(process.env, { resolvedFromSecretRef: boot_secrets_js_1.wasResolvedFromSecretRef }),
+        },
+        {
+            provide: tokens_js_1.SHIELD_CAPTCHA_VERIFIER,
+            useFactory: (config) => buildCaptchaVerifier(config),
+            inject: [tokens_js_1.SHIELD_CAPTCHA_CONFIG],
+        },
+        {
+            provide: tokens_js_1.SHIELD_CAPTCHA_GATE,
+            useFactory: (config, verifier, redis, auditSink) => {
+                new common_1.Logger('ShieldCaptcha').log(`CAPTCHA on: provider=${config.provider} mode=${config.mode} ` +
+                    `failMode=${config.failMode} endpoints=${config.endpoints.join(',')}`);
+                return new captcha_gate_js_1.CaptchaGate({
+                    config,
+                    verifier,
+                    counters: new captcha_gate_js_1.RedisCaptchaCounterStore(redis),
+                    auditSink,
+                });
+            },
+            inject: [
+                tokens_js_1.SHIELD_CAPTCHA_CONFIG,
+                tokens_js_1.SHIELD_CAPTCHA_VERIFIER,
+                tokens_js_1.SHIELD_REDIS,
+                { token: tokens_js_1.SHIELD_AUDIT_SINK, optional: true },
+            ],
+        },
+    ];
+}

package/dist/captcha/recaptcha-verifier.d.ts

@@ -0,0 +1,20 @@
+import type { CancellationSignal, CaptchaVerifier, CaptchaVerifyRequest, CaptchaVerifyResult } from '@astram/core';
+import { type CaptchaLogger } from './siteverify.js';
+export declare const RECAPTCHA_SITEVERIFY_URL = "https://www.google.com/recaptcha/api/siteverify";
+export interface RecaptchaVerifierOptions {
+    readonly version: 'v3' | 'v2';
+    readonly secret: string;
+    readonly expectedHostnames: readonly string[];
+    /** v3 only. */
+    readonly minScore: number;
+    readonly timeoutMs: number;
+    readonly fetch?: typeof fetch;
+    readonly logger?: CaptchaLogger;
+}
+export declare class RecaptchaVerifier implements CaptchaVerifier {
+    private readonly opts;
+    private readonly logger;
+    constructor(opts: RecaptchaVerifierOptions);
+    verify(request: CaptchaVerifyRequest, signal?: CancellationSignal): Promise<CaptchaVerifyResult>;
+}
+//# sourceMappingURL=recaptcha-verifier.d.ts.map

package/dist/captcha/recaptcha-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recaptcha-verifier.d.ts","sourceRoot":"","sources":["../../src/captcha/recaptcha-verifier.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,wBAAwB,oDAAoD,CAAC;AAE1F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,eAAe;IACf,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,qBAAa,iBAAkB,YAAW,eAAe;IAG3C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAEV,IAAI,EAAE,wBAAwB;IAIrD,MAAM,CACV,OAAO,EAAE,oBAAoB,EAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,mBAAmB,CAAC;CA2BhC"}

package/dist/captcha/recaptcha-verifier.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecaptchaVerifier = exports.RECAPTCHA_SITEVERIFY_URL = void 0;
+/**
+ * Google reCAPTCHA adapter for the core `CaptchaVerifier` port (auth capabilities R7.1, R7.4,
+ * AC-14). v3: `success`, hostname, action equal to the endpoint and `score ≥ CAPTCHA_MIN_SCORE`
+ * (an equal score passes, a missing score fails). v2 (checkbox): `success` and hostname only; v2
+ * reports no action or score. See `siteverify.ts` for transport rules.
+ */
+const common_1 = require("@nestjs/common");
+const siteverify_js_1 = require("./siteverify.js");
+exports.RECAPTCHA_SITEVERIFY_URL = 'https://www.google.com/recaptcha/api/siteverify';
+class RecaptchaVerifier {
+    opts;
+    logger;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = opts.logger ?? new common_1.Logger('ShieldCaptcha');
+    }
+    async verify(request, signal) {
+        const pre = (0, siteverify_js_1.precheckToken)(request.token);
+        if (pre !== null)
+            return { ok: false, reason: pre };
+        const answer = await (0, siteverify_js_1.siteverify)({
+            url: exports.RECAPTCHA_SITEVERIFY_URL,
+            secret: this.opts.secret,
+            timeoutMs: this.opts.timeoutMs,
+            ...(this.opts.fetch ? { fetch: this.opts.fetch } : {}),
+        }, request.token, request.remoteIp, signal);
+        if (answer === null)
+            return { ok: false, reason: 'unavailable' };
+        if (!answer.success)
+            return (0, siteverify_js_1.failureOf)(answer, this.logger, 'reCAPTCHA');
+        if (!(0, siteverify_js_1.hostnameAllowed)(answer.hostname, this.opts.expectedHostnames)) {
+            return { ok: false, reason: 'hostname' };
+        }
+        const hostname = answer.hostname ?? '';
+        if (this.opts.version === 'v2')
+            return { ok: true, hostname };
+        if (answer.action !== request.expectedAction)
+            return { ok: false, reason: 'action' };
+        if (answer.score === undefined || answer.score < this.opts.minScore) {
+            return { ok: false, reason: 'score' };
+        }
+        return { ok: true, hostname, action: answer.action, score: answer.score };
+    }
+}
+exports.RecaptchaVerifier = RecaptchaVerifier;

package/dist/captcha/siteverify.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The shared siteverify call for the CAPTCHA adapters (auth capabilities R7.1, R7.4; D-4: global
+ * `fetch`, no new dependency).
+ *
+ * Both Cloudflare Turnstile (`challenges.cloudflare.com/turnstile/v0/siteverify`) and Google
+ * reCAPTCHA (`www.google.com/recaptcha/api/siteverify`) take a form-encoded POST of `secret`,
+ * `response` and optional `remoteip`, and answer JSON with `success`, `hostname`, `action`,
+ * (reCAPTCHA v3) `score` and `error-codes`. A token is single use: a second check answers
+ * `timeout-or-duplicate` (also for an expired token).
+ *
+ * The call is bounded by `timeoutMs` (its own AbortController, chained to the caller's signal).
+ * Any transport error, timeout, non-2xx status or unreadable body is `unavailable`; nothing thrown
+ * escapes. Nothing here logs the secret, the token or the provider's text.
+ */
+import type { CancellationSignal, CaptchaFailureReason, CaptchaVerifyResult } from '@astram/core';
+/** Tokens are at most 2048 characters (Turnstile); anything far longer is refused locally. */
+export declare const MAX_CAPTCHA_TOKEN_LENGTH = 4096;
+/** The minimal logger the adapters use (Nest `Logger` satisfies it). */
+export interface CaptchaLogger {
+    warn(message: string): void;
+}
+export interface SiteverifyDeps {
+    readonly url: string;
+    readonly secret: string;
+    readonly timeoutMs: number;
+    readonly fetch?: typeof fetch;
+}
+/** The parsed provider answer (fields read defensively). */
+export interface SiteverifyAnswer {
+    readonly success: boolean;
+    readonly hostname?: string;
+    readonly action?: string;
+    readonly score?: number;
+    readonly errorCodes: readonly string[];
+}
+/** Local token check before any provider call. `null` = looks fine. */
+export declare function precheckToken(token: unknown): CaptchaFailureReason | null;
+/** POST the token; `null` = unavailable. */
+export declare function siteverify(deps: SiteverifyDeps, token: string, remoteIp: string | undefined, signal: CancellationSignal | undefined): Promise<SiteverifyAnswer | null>;
+/**
+ * Map a failed provider answer to a result. A bad secret warns once per call (no value) and is a
+ * rejection, so `CAPTCHA_FAIL_MODE=open` can never turn a broken config into a pass.
+ */
+export declare function failureOf(answer: SiteverifyAnswer, logger: CaptchaLogger, providerLabel: string): CaptchaVerifyResult;
+/** `true` when the hostname is allowed (an empty list = not checked; development/test only). */
+export declare function hostnameAllowed(hostname: string | undefined, expected: readonly string[]): boolean;
+//# sourceMappingURL=siteverify.d.ts.map

package/dist/captcha/siteverify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteverify.d.ts","sourceRoot":"","sources":["../../src/captcha/siteverify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAElG,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAOD,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAIzE;AAED,4CAA4C;AAC5C,wBAAsB,UAAU,CAC9B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,kBAAkB,GAAG,SAAS,GACrC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA6ClC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,MAAM,GACpB,mBAAmB,CAarB;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAGT"}

package/dist/captcha/siteverify.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CAPTCHA_TOKEN_LENGTH = void 0;
+exports.precheckToken = precheckToken;
+exports.siteverify = siteverify;
+exports.failureOf = failureOf;
+exports.hostnameAllowed = hostnameAllowed;
+/** Tokens are at most 2048 characters (Turnstile); anything far longer is refused locally. */
+exports.MAX_CAPTCHA_TOKEN_LENGTH = 4096;
+/** Error codes that mean the operator's secret is wrong: a rejection, never fail-open. */
+const SECRET_ERRORS = new Set(['missing-input-secret', 'invalid-input-secret']);
+/** Error codes that mean the provider failed: `unavailable`. */
+const PROVIDER_ERRORS = new Set(['internal-error']);
+/** Local token check before any provider call. `null` = looks fine. */
+function precheckToken(token) {
+    if (typeof token !== 'string' || token.trim() === '')
+        return 'missing';
+    if (token.length > exports.MAX_CAPTCHA_TOKEN_LENGTH)
+        return 'invalid';
+    return null;
+}
+/** POST the token; `null` = unavailable. */
+async function siteverify(deps, token, remoteIp, signal) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), deps.timeoutMs);
+    const onAbort = () => ctl.abort();
+    if (signal?.aborted === true)
+        ctl.abort();
+    else
+        signal?.addEventListener('abort', onAbort);
+    try {
+        const form = new URLSearchParams({ secret: deps.secret, response: token });
+        if (typeof remoteIp === 'string' && remoteIp !== '')
+            form.set('remoteip', remoteIp);
+        const doFetch = deps.fetch ?? globalThis.fetch;
+        const res = await Promise.race([
+            doFetch(deps.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: form.toString(),
+                signal: ctl.signal,
+            }),
+            // Settles even when a fetch ignores the abort.
+            new Promise((_resolve, reject) => {
+                if (ctl.signal.aborted)
+                    reject(new Error('aborted'));
+                ctl.signal.addEventListener('abort', () => reject(new Error('aborted')));
+            }),
+        ]);
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (body === null || typeof body !== 'object' || typeof body.success !== 'boolean') {
+            return null;
+        }
+        const codes = Array.isArray(body['error-codes'])
+            ? body['error-codes'].filter((c) => typeof c === 'string')
+            : [];
+        return {
+            success: body.success,
+            ...(typeof body.hostname === 'string' ? { hostname: body.hostname } : {}),
+            ...(typeof body.action === 'string' ? { action: body.action } : {}),
+            ...(typeof body.score === 'number' && Number.isFinite(body.score)
+                ? { score: body.score }
+                : {}),
+            errorCodes: codes,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Map a failed provider answer to a result. A bad secret warns once per call (no value) and is a
+ * rejection, so `CAPTCHA_FAIL_MODE=open` can never turn a broken config into a pass.
+ */
+function failureOf(answer, logger, providerLabel) {
+    if (answer.errorCodes.some((c) => PROVIDER_ERRORS.has(c))) {
+        return { ok: false, reason: 'unavailable' };
+    }
+    if (answer.errorCodes.some((c) => SECRET_ERRORS.has(c))) {
+        logger.warn(`${providerLabel} rejected CAPTCHA_SECRET (missing or invalid secret); every challenge fails ` +
+            'until it is fixed');
+        return { ok: false, reason: 'invalid' };
+    }
+    if (answer.errorCodes.includes('timeout-or-duplicate'))
+        return { ok: false, reason: 'reused' };
+    return { ok: false, reason: 'invalid' };
+}
+/** `true` when the hostname is allowed (an empty list = not checked; development/test only). */
+function hostnameAllowed(hostname, expected) {
+    if (expected.length === 0)
+        return true;
+    return typeof hostname === 'string' && expected.includes(hostname.toLowerCase());
+}

package/dist/captcha/turnstile-verifier.d.ts

@@ -0,0 +1,18 @@
+import type { CancellationSignal, CaptchaVerifier, CaptchaVerifyRequest, CaptchaVerifyResult } from '@astram/core';
+import { type CaptchaLogger } from './siteverify.js';
+export declare const TURNSTILE_SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export interface TurnstileVerifierOptions {
+    readonly secret: string;
+    readonly expectedHostnames: readonly string[];
+    readonly timeoutMs: number;
+    /** Injected in tests; defaults to global `fetch`. */
+    readonly fetch?: typeof fetch;
+    readonly logger?: CaptchaLogger;
+}
+export declare class TurnstileVerifier implements CaptchaVerifier {
+    private readonly opts;
+    private readonly logger;
+    constructor(opts: TurnstileVerifierOptions);
+    verify(request: CaptchaVerifyRequest, signal?: CancellationSignal): Promise<CaptchaVerifyResult>;
+}
+//# sourceMappingURL=turnstile-verifier.d.ts.map

package/dist/captcha/turnstile-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile-verifier.d.ts","sourceRoot":"","sources":["../../src/captcha/turnstile-verifier.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,wBAAwB,8DAA8D,CAAC;AAEpG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,qBAAa,iBAAkB,YAAW,eAAe;IAG3C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAEV,IAAI,EAAE,wBAAwB;IAIrD,MAAM,CACV,OAAO,EAAE,oBAAoB,EAC7B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,mBAAmB,CAAC;CAsBhC"}

package/dist/captcha/turnstile-verifier.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnstileVerifier = exports.TURNSTILE_SITEVERIFY_URL = void 0;
+/**
+ * Cloudflare Turnstile adapter for the core `CaptchaVerifier` port (auth capabilities R7.1, R7.4,
+ * AC-14). Checks `success`, the hostname against `CAPTCHA_EXPECTED_HOSTNAMES` and the action
+ * (the widget's `data-action`) against the endpoint. See `siteverify.ts` for transport rules.
+ */
+const common_1 = require("@nestjs/common");
+const siteverify_js_1 = require("./siteverify.js");
+exports.TURNSTILE_SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+class TurnstileVerifier {
+    opts;
+    logger;
+    constructor(opts) {
+        this.opts = opts;
+        this.logger = opts.logger ?? new common_1.Logger('ShieldCaptcha');
+    }
+    async verify(request, signal) {
+        const pre = (0, siteverify_js_1.precheckToken)(request.token);
+        if (pre !== null)
+            return { ok: false, reason: pre };
+        const answer = await (0, siteverify_js_1.siteverify)({
+            url: exports.TURNSTILE_SITEVERIFY_URL,
+            secret: this.opts.secret,
+            timeoutMs: this.opts.timeoutMs,
+            ...(this.opts.fetch ? { fetch: this.opts.fetch } : {}),
+        }, request.token, request.remoteIp, signal);
+        if (answer === null)
+            return { ok: false, reason: 'unavailable' };
+        if (!answer.success)
+            return (0, siteverify_js_1.failureOf)(answer, this.logger, 'Turnstile');
+        if (!(0, siteverify_js_1.hostnameAllowed)(answer.hostname, this.opts.expectedHostnames)) {
+            return { ok: false, reason: 'hostname' };
+        }
+        if (answer.action !== request.expectedAction)
+            return { ok: false, reason: 'action' };
+        return { ok: true, hostname: answer.hostname ?? '', action: answer.action };
+    }
+}
+exports.TurnstileVerifier = TurnstileVerifier;

package/dist/config/captcha-config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CAPTCHA config (auth capabilities R7.1, AC-15): what `ShieldModule.forRoot({ captcha: 'env' })`
+ * reads from the environment. Mirrors {@link loadMessageConfig}: every missing or invalid value
+ * refuses boot with a message that names the variable, never its value (Shield #1, #10); outside
+ * development/test `CAPTCHA_SECRET` must have been resolved from a `secret-ref:` at boot
+ * (ADR-0032) and `CAPTCHA_EXPECTED_HOSTNAMES` is required.
+ *
+ * A blank variable counts as unset.
+ */
+import { type CaptchaProvider } from '@astram/core';
+/** The endpoints a challenge can protect (Phase 1), and their provider action names (R7.4). */
+export declare const CAPTCHA_ENDPOINTS: readonly ["login", "forgot_password", "reset_password"];
+export type CaptchaEndpoint = (typeof CAPTCHA_ENDPOINTS)[number];
+export declare const CAPTCHA_MODES: readonly ["adaptive", "always"];
+export type CaptchaMode = (typeof CAPTCHA_MODES)[number];
+export declare const CAPTCHA_FAIL_MODES: readonly ["closed", "open"];
+export type CaptchaFailMode = (typeof CAPTCHA_FAIL_MODES)[number];
+export declare const DEFAULT_CAPTCHA_THRESHOLD = 3;
+export declare const MAX_CAPTCHA_THRESHOLD = 20;
+export declare const DEFAULT_CAPTCHA_MIN_SCORE = 0.5;
+export declare const DEFAULT_CAPTCHA_TIMEOUT_MS = 5000;
+export declare const MAX_CAPTCHA_TIMEOUT_MS = 10000;
+export interface CaptchaConfig {
+    readonly provider: CaptchaProvider;
+    /** Public; served by `GET /auth/login-options`. */
+    readonly siteKey: string;
+    /** Never logged, never served. */
+    readonly secret: string;
+    /** Lower-case; empty only in development/test (hostname then not checked). */
+    readonly expectedHostnames: readonly string[];
+    readonly mode: CaptchaMode;
+    readonly threshold: number;
+    readonly minScore: number;
+    readonly failMode: CaptchaFailMode;
+    readonly timeoutMs: number;
+    readonly endpoints: readonly CaptchaEndpoint[];
+}
+export interface LoadCaptchaConfigOptions {
+    /**
+     * Provenance check for `CAPTCHA_SECRET` outside development/test (`wasResolvedFromSecretRef`).
+     * Omitted there: fail closed, the secret counts as a literal and is refused.
+     */
+    readonly resolvedFromSecretRef?: (envKey: string, env: Readonly<Record<string, string | undefined>>) => boolean;
+}
+/** Read the CAPTCHA config for `captcha: 'env'` (see the file header). */
+export declare function loadCaptchaConfig(env: NodeJS.ProcessEnv, options?: LoadCaptchaConfigOptions): CaptchaConfig;
+//# sourceMappingURL=captcha-config.d.ts.map

package/dist/config/captcha-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha-config.d.ts","sourceRoot":"","sources":["../../src/config/captcha-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpF,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,yDAInB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,eAAO,MAAM,aAAa,iCAAiD,CAAC;AAC5E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,kBAAkB,6BAA6C,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAChD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAC/B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,KAC9C,OAAO,CAAC;CACd;AAYD,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAmCf"}

package/dist/config/captcha-config.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CAPTCHA_TIMEOUT_MS = exports.DEFAULT_CAPTCHA_TIMEOUT_MS = exports.DEFAULT_CAPTCHA_MIN_SCORE = exports.MAX_CAPTCHA_THRESHOLD = exports.DEFAULT_CAPTCHA_THRESHOLD = exports.CAPTCHA_FAIL_MODES = exports.CAPTCHA_MODES = exports.CAPTCHA_ENDPOINTS = void 0;
+exports.loadCaptchaConfig = loadCaptchaConfig;
+/**
+ * CAPTCHA config (auth capabilities R7.1, AC-15): what `ShieldModule.forRoot({ captcha: 'env' })`
+ * reads from the environment. Mirrors {@link loadMessageConfig}: every missing or invalid value
+ * refuses boot with a message that names the variable, never its value (Shield #1, #10); outside
+ * development/test `CAPTCHA_SECRET` must have been resolved from a `secret-ref:` at boot
+ * (ADR-0032) and `CAPTCHA_EXPECTED_HOSTNAMES` is required.
+ *
+ * A blank variable counts as unset.
+ */
+const core_1 = require("@astram/core");
+const app_config_js_1 = require("./app-config.js");
+/** The endpoints a challenge can protect (Phase 1), and their provider action names (R7.4). */
+exports.CAPTCHA_ENDPOINTS = Object.freeze([
+    'login',
+    'forgot_password',
+    'reset_password',
+]);
+exports.CAPTCHA_MODES = Object.freeze(['adaptive', 'always']);
+exports.CAPTCHA_FAIL_MODES = Object.freeze(['closed', 'open']);
+exports.DEFAULT_CAPTCHA_THRESHOLD = 3;
+exports.MAX_CAPTCHA_THRESHOLD = 20;
+exports.DEFAULT_CAPTCHA_MIN_SCORE = 0.5;
+exports.DEFAULT_CAPTCHA_TIMEOUT_MS = 5_000;
+exports.MAX_CAPTCHA_TIMEOUT_MS = 10_000;
+const HOST_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const HOSTNAME = new RegExp(`^${HOST_LABEL}(?:\\.${HOST_LABEL})*$`);
+const PLAIN_POSITIVE_INT = /^[1-9]\d*$/;
+const DECIMAL = /^(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+)$/;
+const SITE_KEY = /^[A-Za-z0-9_.-]{1,256}$/;
+function present(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+/** Read the CAPTCHA config for `captcha: 'env'` (see the file header). */
+function loadCaptchaConfig(env, options = {}) {
+    const devOrTest = (0, app_config_js_1.isDevOrTestNodeEnv)(env.NODE_ENV);
+    const providerRaw = env.CAPTCHA_PROVIDER?.trim();
+    const providers = core_1.CAPTCHA_PROVIDERS.join(', ');
+    if (!providerRaw) {
+        throw new Error(`CAPTCHA_PROVIDER must be set when ShieldModule.forRoot({ captcha: 'env' }) (one of ${providers})`);
+    }
+    if (!core_1.CAPTCHA_PROVIDERS.includes(providerRaw)) {
+        throw new Error(`CAPTCHA_PROVIDER must be one of ${providers}`);
+    }
+    const provider = providerRaw;
+    const siteKey = env.CAPTCHA_SITE_KEY?.trim() ?? '';
+    if (!SITE_KEY.test(siteKey)) {
+        throw new Error('CAPTCHA_SITE_KEY must be set (letters, digits, `_`, `.`, `-`; ≤ 256)');
+    }
+    const secret = readSecret(env, devOrTest, options);
+    const expectedHostnames = readHostnames(env, devOrTest);
+    return {
+        provider,
+        siteKey,
+        secret,
+        expectedHostnames,
+        mode: readEnum(env, 'CAPTCHA_MODE', exports.CAPTCHA_MODES, 'adaptive'),
+        threshold: readThreshold(env.CAPTCHA_THRESHOLD),
+        minScore: readMinScore(env.CAPTCHA_MIN_SCORE),
+        failMode: readEnum(env, 'CAPTCHA_FAIL_MODE', exports.CAPTCHA_FAIL_MODES, 'closed'),
+        timeoutMs: readTimeout(env.CAPTCHA_TIMEOUT_MS),
+        endpoints: readEndpoints(env.CAPTCHA_ENDPOINTS),
+    };
+}
+function readSecret(env, devOrTest, options) {
+    const name = 'CAPTCHA_SECRET';
+    const value = env[name];
+    if (!present(value))
+        throw new Error(`${name} must be set when CAPTCHA_PROVIDER is set`);
+    const noProvider = !present(env.SECRETS_PROVIDER) || env.SECRETS_PROVIDER.trim() === 'none';
+    if ((0, core_1.isSecretRef)(value)) {
+        if (noProvider) {
+            throw new Error(`${name} is a secret-ref: value but SECRETS_PROVIDER is not set; configure a secrets ` +
+                "provider (e.g. 'encrypted-file') before using captcha: 'env' (runbook §6)");
+        }
+        throw new Error(`${name} still holds an unresolved secret-ref: value; call resolveBootSecrets() in main.ts ` +
+            'before loading AppModule');
+    }
+    if (!devOrTest && !(options.resolvedFromSecretRef?.(name, env) === true)) {
+        const prerequisite = noProvider
+            ? "; this needs SECRETS_PROVIDER (e.g. 'encrypted-file') configured first (runbook §6)"
+            : '';
+        throw new Error(`${name} must be a secret-ref: value outside NODE_ENV development/test ` +
+            `(literal credentials are refused; see ADR-0032)${prerequisite}`);
+    }
+    return value;
+}
+function readHostnames(env, devOrTest) {
+    const name = 'CAPTCHA_EXPECTED_HOSTNAMES';
+    const raw = env[name];
+    const list = present(raw)
+        ? raw
+            .split(',')
+            .map((h) => h.trim().toLowerCase())
+            .filter((h) => h !== '')
+        : [];
+    if (list.length === 0) {
+        if (devOrTest)
+            return [];
+        throw new Error(`${name} must be set outside NODE_ENV development/test (comma-separated hostnames the ` +
+            'CAPTCHA provider may report)');
+    }
+    if (list.some((h) => h.length > 253 || !HOSTNAME.test(h))) {
+        throw new Error(`${name} must be a comma-separated list of hostnames (no scheme, port or path)`);
+    }
+    return [...new Set(list)];
+}
+function readEnum(env, name, values, fallback) {
+    const raw = env[name];
+    if (!present(raw))
+        return fallback;
+    const v = raw.trim();
+    if (!values.includes(v)) {
+        throw new Error(`${name} must be one of ${values.join(', ')}`);
+    }
+    return v;
+}
+function readThreshold(raw) {
+    if (!present(raw))
+        return exports.DEFAULT_CAPTCHA_THRESHOLD;
+    const v = raw.trim();
+    const n = PLAIN_POSITIVE_INT.test(v) ? Number(v) : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > exports.MAX_CAPTCHA_THRESHOLD) {
+        throw new Error(`CAPTCHA_THRESHOLD must be an integer from 1 to ${exports.MAX_CAPTCHA_THRESHOLD}`);
+    }
+    return n;
+}
+function readMinScore(raw) {
+    if (!present(raw))
+        return exports.DEFAULT_CAPTCHA_MIN_SCORE;
+    const v = raw.trim();
+    const n = DECIMAL.test(v) ? Number(v) : NaN;
+    if (!Number.isFinite(n) || n < 0 || n > 1) {
+        throw new Error('CAPTCHA_MIN_SCORE must be a number from 0 to 1');
+    }
+    return n;
+}
+function readTimeout(raw) {
+    if (!present(raw))
+        return exports.DEFAULT_CAPTCHA_TIMEOUT_MS;
+    const v = raw.trim();
+    const n = PLAIN_POSITIVE_INT.test(v) ? Number(v) : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > exports.MAX_CAPTCHA_TIMEOUT_MS) {
+        throw new Error(`CAPTCHA_TIMEOUT_MS must be an integer from 1 to ${exports.MAX_CAPTCHA_TIMEOUT_MS} (milliseconds)`);
+    }
+    return n;
+}
+function readEndpoints(raw) {
+    if (!present(raw))
+        return [...exports.CAPTCHA_ENDPOINTS];
+    const list = raw
+        .split(',')
+        .map((e) => e.trim())
+        .filter((e) => e !== '');
+    if (list.length === 0 ||
+        list.some((e) => !exports.CAPTCHA_ENDPOINTS.includes(e))) {
+        throw new Error(`CAPTCHA_ENDPOINTS must be a comma-separated list of ${exports.CAPTCHA_ENDPOINTS.join(', ')}`);
+    }
+    return exports.CAPTCHA_ENDPOINTS.filter((e) => list.includes(e));
+}

package/dist/config/reserved-principal-ids.d.ts

@@ -5,6 +5,21 @@
  * the runner's operation binding. It must never be a platform root, so `rootIdsFromEnv` refuses it.
  */
 export declare const ORG_BOOTSTRAP_PRINCIPAL_ID = "5b0d7e1a-0c4f-4a6e-9d3b-b007572a9001";
+/** A framework operation that runs as a reserved principal: its key and its display name. */
+export interface ReservedOperationPrincipal {
+    /** The operation key bound to the principal (e.g. `shield:org-bootstrap`). */
+    readonly operationKey: string;
+    /** The human name shown wherever the principal would otherwise be resolved (the audit viewer). */
+    readonly label: string;
+}
+/**
+ * Every reserved operation principal, keyed by its lower-case id (KI #140). The audit viewer labels
+ * a row by this registry instead of looking the id up as a user (which would read "Deleted user"),
+ * and {@link assertNoReservedRootId} refuses every id listed here. Append only.
+ */
+export declare const RESERVED_OPERATION_PRINCIPALS: ReadonlyMap<string, ReservedOperationPrincipal>;
+/** The reserved operation an id belongs to (case-insensitive), else `undefined`. */
+export declare function reservedOperationPrincipal(id: string | null | undefined): ReservedOperationPrincipal | undefined;
 /**
  * Refuse a root allowlist that names a reserved principal, however the app built it (`rootIdsFromEnv`,
  * its own variable, or a literal). Called by `ShieldModule.forRoot` and `IdentityFeatureModule.forRoot`.

package/dist/config/reserved-principal-ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-principal-ids.d.ts","sourceRoot":"","sources":["../../src/config/reserved-principal-ids.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,yCAAyC,CAAC;AAEjF;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAM1F"}
+{"version":3,"file":"reserved-principal-ids.d.ts","sourceRoot":"","sources":["../../src/config/reserved-principal-ids.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,yCAAyC,CAAC;AAEjF,6FAA6F;AAC7F,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAMtF,CAAC;AAEL,oFAAoF;AACpF,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC5B,0BAA0B,GAAG,SAAS,CAGxC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAK1F"}

package/dist/config/reserved-principal-ids.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ORG_BOOTSTRAP_PRINCIPAL_ID = void 0;
+exports.RESERVED_OPERATION_PRINCIPALS = exports.ORG_BOOTSTRAP_PRINCIPAL_ID = void 0;
+exports.reservedOperationPrincipal = reservedOperationPrincipal;
 exports.assertNoReservedRootId = assertNoReservedRootId;
 /**
  * Principal ids the framework reserves for its own trusted operations (Shield #9).
@@ -9,6 +10,23 @@ exports.assertNoReservedRootId = assertNoReservedRootId;
  * the runner's operation binding. It must never be a platform root, so `rootIdsFromEnv` refuses it.
  */
 exports.ORG_BOOTSTRAP_PRINCIPAL_ID = '5b0d7e1a-0c4f-4a6e-9d3b-b007572a9001';
+/**
+ * Every reserved operation principal, keyed by its lower-case id (KI #140). The audit viewer labels
+ * a row by this registry instead of looking the id up as a user (which would read "Deleted user"),
+ * and {@link assertNoReservedRootId} refuses every id listed here. Append only.
+ */
+exports.RESERVED_OPERATION_PRINCIPALS = new Map([
+    [
+        exports.ORG_BOOTSTRAP_PRINCIPAL_ID.toLowerCase(),
+        Object.freeze({ operationKey: 'shield:org-bootstrap', label: 'Org bootstrap' }),
+    ],
+]);
+/** The reserved operation an id belongs to (case-insensitive), else `undefined`. */
+function reservedOperationPrincipal(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return undefined;
+    return exports.RESERVED_OPERATION_PRINCIPALS.get(id.trim().toLowerCase());
+}
 /**
  * Refuse a root allowlist that names a reserved principal, however the app built it (`rootIdsFromEnv`,
  * its own variable, or a literal). Called by `ShieldModule.forRoot` and `IdentityFeatureModule.forRoot`.
@@ -17,8 +35,7 @@ exports.ORG_BOOTSTRAP_PRINCIPAL_ID = '5b0d7e1a-0c4f-4a6e-9d3b-b007572a9001';
 function assertNoReservedRootId(rootIds) {
     if (!rootIds)
         return;
-    const reserved = exports.ORG_BOOTSTRAP_PRINCIPAL_ID.toLowerCase();
-    if (rootIds.some((id) => typeof id === 'string' && id.trim().toLowerCase() === reserved)) {
+    if (rootIds.some((id) => reservedOperationPrincipal(id) !== undefined)) {
         throw new Error('rootIds contains a reserved principal id; a reserved id is never a root.');
     }
 }