@astram/guard 0.18.0 → 0.20.0

package/dist/auth/auth.module.d.ts

@@ -64,6 +64,8 @@
  */
 import { type DynamicModule, type Provider } from '@nestjs/common';
 import type { CredentialResolver, HmacSha1, FactorVerifier } from '@astram/core';
+import { type SignInMethod } from '../authentication/sign-in-with.js';
+import { type ShieldCaptchaOption } from '../captcha/captcha.providers.js';
 import type { SessionFactsProjector } from './ports/session-facts-projector.js';
 import type { ScopeSubtreeResolver } from './ports/scope-subtree-resolver.js';
 import type { MembershipChecker } from './ports/membership-checker.js';
@@ -107,6 +109,26 @@ export declare function resolveTotpVerifier(override: FactorVerifier | null | un
  * consumer's built CJS dist. Async because of {@link loadCore}.
  */
 export declare function makeDefaultTotpVerifier(): Promise<FactorVerifier>;
+/**
+ * Mandatory 2FA (R2.3–R2.5, R2.7): the service the login, the request path, device confirm and
+ * device removal use — bound ONLY when `@astram/identity` signals its security-policy feature
+ * ({@link SHIELD_MFA_POLICY_FEATURE}); otherwise `null` and the guard behaves exactly as before (no
+ * evaluation, no extra read, no new claim). Grants come from the session-facts projector (the
+ * decision authority's own `loadCoarseGrants`); the self-authenticating routes read the version
+ * from Redis (miss ⇒ one DB fill, Redis error ⇒ deny), as gate 5 does.
+ */
+export declare const mfaRequirementProvider: Provider;
+/**
+ * Admin sign-in controls (auth capabilities R11.2): the admin's own TOTP step-up, over the device
+ * store, the replay-guarded login verifier and the `mfa:pid` limiter (the same three the code-gated
+ * `/account` routes use). For `@astram/identity`'s `/identity/users/:uuid/*` controls.
+ */
+export declare const adminStepUpProvider: Provider;
+/**
+ * Admin sign-in controls (R11.1 unlock): clears one principal's `login:pid`, `mfa:pid`,
+ * `recovery:` and CAPTCHA account counters on the guard's one Redis client (fails closed).
+ */
+export declare const accountUnlockerProvider: Provider;
 /** DI token for the single-layout privilege probe hook (a no-op in the four layout). */
 export declare const SHIELD_SINGLE_LAYOUT_PROBE: unique symbol;
 /**
@@ -238,6 +260,27 @@ export interface AuthModuleOptions {
      * `emailSender: 'disabled'` (Phase 13 #1; `RESET_LINK_BASE_URL` follows the same rule).
      */
     readonly emailChangeLinkBaseUrl?: string;
+    /**
+     * R15.1 / D-9: require proof for `POST /auth/logout` (a refresh token of the session, or an
+     * access token bound to it). `false` (default, this release): an unproven logout still revokes,
+     * counted as `auth.logout.unproven` with a one-time deprecation warning. `true`: an unproven
+     * logout revokes nothing (204). Becomes `true` by default at the next guard major.
+     */
+    readonly logoutRequiresProof?: boolean;
+    /**
+     * R1.8: the sign-in forms `POST /auth/login` accepts. `['email']` (default) is today's
+     * behaviour; `['email', 'username']` also accepts the user's login name (`users.u_login_name`,
+     * set by an admin or `bootstrap:org`). Validated at registration: an unknown value, an empty
+     * list or a list without `'email'` throws. Applies to the framework-default credential
+     * resolver; a consumer `credentialResolver` decides for itself.
+     */
+    readonly signInWith?: readonly SignInMethod[];
+    /**
+     * Auth capabilities R7: `'env'` turns CAPTCHA on for `/auth/login`, `/auth/forgot-password` and
+     * `/auth/reset-password` from `CAPTCHA_*` (`loadCaptchaConfig`; a missing or invalid value fails
+     * the boot). Omitted ⇒ off, every route answers exactly as before.
+     */
+    readonly captcha?: ShieldCaptchaOption;
 }
 /**
  * The per-account email-change REQUEST limiter (Phase 12) — `email-change:pid:<id>`, 3 per 60-min
@@ -251,6 +294,12 @@ export declare const attemptLimiterFactoryProvider: Provider;
  * the unit test only — not part of the package's public surface.
  */
 export declare function resolveDefaultEmailSender(rawNodeEnv: string | undefined): EmailSender;
+/**
+ * The auth audit sink (R12.1, B-3): the app-supplied `auditSink` wins; else the framework default
+ * on {@link SHIELD_DEFAULT_AUTH_AUDIT_SINK} (bound globally by `@astram/identity`), injected
+ * optionally; else `null` (un-audited, as before).
+ */
+export declare function makeAuditSinkProvider(override?: AuditSink): Provider;
 /**
  * The auth composition module. Imports {@link PersistenceModule} (the live
  * connections) and provides the adapters + composed engines. Exports the two

package/dist/auth/auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":"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"}

package/dist/auth/auth.module.js

@@ -104,10 +104,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 var AuthModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthModule = exports.attemptLimiterFactoryProvider = exports.singleLayoutProbeProvider = exports.SHIELD_SINGLE_LAYOUT_PROBE = exports.hmacSha1 = void 0;
+exports.AuthModule = exports.attemptLimiterFactoryProvider = exports.singleLayoutProbeProvider = exports.SHIELD_SINGLE_LAYOUT_PROBE = exports.accountUnlockerProvider = exports.adminStepUpProvider = exports.mfaRequirementProvider = exports.hmacSha1 = void 0;
 exports.resolveTotpVerifier = resolveTotpVerifier;
 exports.makeDefaultTotpVerifier = makeDefaultTotpVerifier;
 exports.resolveDefaultEmailSender = resolveDefaultEmailSender;
+exports.makeAuditSinkProvider = makeAuditSinkProvider;
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const app_config_js_1 = require("../config/app-config.js");
@@ -136,13 +137,22 @@ const index_js_1 = require("../session/index.js");
 const replay_outcome_js_1 = require("../session/replay-outcome.js");
 const persistence_module_js_1 = require("./persistence.module.js");
 const auth_controller_js_1 = require("./auth.controller.js");
+const logout_proof_js_1 = require("./logout-proof.js");
 const account_controller_js_1 = require("./account.controller.js");
 const confirm_email_controller_js_1 = require("./confirm-email.controller.js");
 const pending_mfa_store_js_1 = require("./pending-mfa-store.js");
 const mfa_step_up_js_1 = require("./mfa-step-up.js");
 const tokens_js_1 = require("./tokens.js");
+const admin_signin_controls_js_1 = require("./admin-signin-controls.js");
+const captcha_gate_js_1 = require("./captcha-gate.js");
+const sign_in_with_js_1 = require("../authentication/sign-in-with.js");
+const captcha_providers_js_1 = require("../captcha/captcha.providers.js");
+const login_name_count_boot_js_1 = require("./login-name-count-boot.js");
+const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
 const permission_version_cache_js_1 = require("../authz/permission-version-cache.js");
 const session_restriction_store_js_1 = require("../session/session-restriction-store.js");
+const mariadb_mfa_requirement_source_js_1 = require("../authentication/mariadb-mfa-requirement-source.js");
+const mfa_requirement_service_js_1 = require("../session/mfa-requirement-service.js");
 const attempt_limiter_js_1 = require("./rate-limit/attempt-limiter.js");
 const trust_proxy_check_js_1 = require("./rate-limit/trust-proxy-check.js");
 const email_delivery_js_1 = require("../messaging/email-delivery.js");
@@ -256,8 +266,11 @@ function makeCredentialResolverProvider(override) {
             provide: tokens_js_1.SHIELD_CREDENTIAL_RESOLVER,
             // #7: the default resolver folds the principal's CONFIRMED MFA devices into a
             // `totp` required factor, so enrolled MFA is enforced at every password login.
-            useFactory: (pool, devices, config) => new mariadb_credential_resolver_js_1.MariaDbCredentialResolver(pool, devices, undefined, (0, app_config_js_1.frameworkSchemasOf)(config)),
-            inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_MFA_DEVICE_STORE, config_module_js_1.APP_CONFIG],
+            // R1.8: `signInWith` decides whether a hint without `@` may resolve by login name.
+            useFactory: (pool, devices, config, signInWith) => new mariadb_credential_resolver_js_1.MariaDbCredentialResolver(pool, devices, undefined, (0, app_config_js_1.frameworkSchemasOf)(config), {
+                signInWith,
+            }),
+            inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_MFA_DEVICE_STORE, config_module_js_1.APP_CONFIG, tokens_js_1.SHIELD_SIGN_IN_WITH],
         };
 }
 /**
@@ -303,6 +316,88 @@ const sessionRestrictionStoreProvider = {
     useFactory: (pool, config) => new session_restriction_store_js_1.MariaDbSessionRestrictionStore(pool, (0, app_config_js_1.frameworkSchemasOf)(config)),
     inject: [tokens_js_1.SHIELD_DB_POOL, config_module_js_1.APP_CONFIG],
 };
+/**
+ * The guard's MariaDB {@link MfaRequirementSource} (auth capabilities B-1) over the runtime pool:
+ * policies, scope chain, confirmed devices, the per-user grace clock. Reads nothing until asked.
+ */
+const mfaRequirementSourceProvider = {
+    provide: tokens_js_1.SHIELD_MFA_REQUIREMENT_SOURCE,
+    useFactory: (pool, config) => new mariadb_mfa_requirement_source_js_1.MariaDbMfaRequirementSource(pool, (0, app_config_js_1.frameworkSchemasOf)(config)),
+    inject: [tokens_js_1.SHIELD_DB_POOL, config_module_js_1.APP_CONFIG],
+};
+/**
+ * Mandatory 2FA (R2.3–R2.5, R2.7): the service the login, the request path, device confirm and
+ * device removal use — bound ONLY when `@astram/identity` signals its security-policy feature
+ * ({@link SHIELD_MFA_POLICY_FEATURE}); otherwise `null` and the guard behaves exactly as before (no
+ * evaluation, no extra read, no new claim). Grants come from the session-facts projector (the
+ * decision authority's own `loadCoarseGrants`); the self-authenticating routes read the version
+ * from Redis (miss ⇒ one DB fill, Redis error ⇒ deny), as gate 5 does.
+ */
+exports.mfaRequirementProvider = {
+    provide: tokens_js_1.SHIELD_MFA_REQUIREMENT,
+    useFactory: (feature, pool, config, projector, versionCache, permissionFacts, binder, restrictions) => {
+        if (feature !== true)
+            return null;
+        const source = new mariadb_mfa_requirement_source_js_1.MariaDbMfaRequirementSource(pool, (0, app_config_js_1.frameworkSchemasOf)(config));
+        return new mfa_requirement_service_js_1.MfaRequirementService({
+            source,
+            // R11.3: the admin users list's batched page reads.
+            batch: source,
+            loadGrants: async (principalId, tenantId) => {
+                if (projector === null || projector === undefined)
+                    return null;
+                if (typeof projector.isActive === 'function' && projector.isActive() !== true)
+                    return null;
+                return projector.project(principalId, tenantId);
+            },
+            currentVersion: (0, mfa_requirement_service_js_1.currentVersionReader)(versionCache, (tenantId) => permissionFacts.currentVersionFor('', tenantId)),
+            binder,
+            restrictions,
+        });
+    },
+    inject: [
+        { token: tokens_js_1.SHIELD_MFA_POLICY_FEATURE, optional: true },
+        tokens_js_1.SHIELD_DB_POOL,
+        config_module_js_1.APP_CONFIG,
+        tokens_js_1.SHIELD_SESSION_FACTS_PROJECTOR,
+        tokens_js_1.SHIELD_PERMISSION_VERSION_CACHE,
+        tokens_js_1.SHIELD_PERMISSION_FACTS,
+        tokens_js_2.SHIELD_SESSION_TOKEN_BINDER,
+        tokens_js_1.SHIELD_SESSION_RESTRICTIONS,
+    ],
+};
+/**
+ * Admin sign-in controls (auth capabilities R11.2): the admin's own TOTP step-up, over the device
+ * store, the replay-guarded login verifier and the `mfa:pid` limiter (the same three the code-gated
+ * `/account` routes use). For `@astram/identity`'s `/identity/users/:uuid/*` controls.
+ */
+exports.adminStepUpProvider = {
+    provide: tokens_js_1.SHIELD_ADMIN_STEP_UP,
+    useFactory: (devices, verifier, limiter) => new admin_signin_controls_js_1.TotpAdminStepUp({
+        devices: devices ?? null,
+        verifier: verifier ?? null,
+        limiter: limiter ?? null,
+    }),
+    inject: [
+        { token: tokens_js_1.SHIELD_MFA_DEVICE_STORE, optional: true },
+        { token: tokens_js_1.SHIELD_LOGIN_TOTP_VERIFIER, optional: true },
+        { token: tokens_js_1.SHIELD_MFA_LIMITER, optional: true },
+    ],
+};
+/**
+ * Admin sign-in controls (R11.1 unlock): clears one principal's `login:pid`, `mfa:pid`,
+ * `recovery:` and CAPTCHA account counters on the guard's one Redis client (fails closed).
+ */
+exports.accountUnlockerProvider = {
+    provide: tokens_js_1.SHIELD_ACCOUNT_UNLOCKER,
+    useFactory: (redis, login, mfa, recovery) => new admin_signin_controls_js_1.RedisAccountUnlocker({
+        login,
+        mfa,
+        recovery,
+        captcha: new captcha_gate_js_1.RedisCaptchaCounterStore(redis),
+    }),
+    inject: [tokens_js_1.SHIELD_REDIS, tokens_js_1.SHIELD_LOGIN_LIMITER, tokens_js_1.SHIELD_MFA_LIMITER, tokens_js_1.SHIELD_RECOVERY_LIMITER],
+};
 /** Hot session store (Redis adapter, injected with the live client). */
 const hotSessionStoreProvider = {
     provide: index_js_1.SHIELD_HOT_SESSION_STORE,
@@ -680,6 +775,17 @@ const totpVerifierProvider = {
         return createTotpFactorVerifier({ hmacSha1: exports.hmacSha1 });
     },
 };
+/** DI token for the R1.9 boot count of users with a login name. */
+const SHIELD_LOGIN_NAME_COUNT_BOOT = Symbol('SHIELD_LOGIN_NAME_COUNT_BOOT');
+/**
+ * Auth capabilities R1.9: with `signInWith` including `'username'`, log once at boot how many
+ * active users have a login name (count only) through the runtime pool. A no-op otherwise.
+ */
+const loginNameCountBootProvider = {
+    provide: SHIELD_LOGIN_NAME_COUNT_BOOT,
+    useFactory: (pool, config, signInWith) => new login_name_count_boot_js_1.LoginNameCountBoot(async (sql) => (await pool.query(sql)), (0, framework_schema_names_js_1.qualifiedTableName)((0, app_config_js_1.frameworkSchemasOf)(config).app, 'users'), signInWith),
+    inject: [tokens_js_1.SHIELD_DB_POOL, config_module_js_1.APP_CONFIG, tokens_js_1.SHIELD_SIGN_IN_WITH],
+};
 /**
  * Bind the current-user profile resolver backing `GET /auth/me`.
  *
@@ -895,8 +1001,19 @@ function makeMfaDeviceStoreProvider(override) {
             inject: [tokens_js_1.SHIELD_DB_POOL, config_module_js_1.APP_CONFIG],
         };
 }
+/**
+ * The auth audit sink (R12.1, B-3): the app-supplied `auditSink` wins; else the framework default
+ * on {@link SHIELD_DEFAULT_AUTH_AUDIT_SINK} (bound globally by `@astram/identity`), injected
+ * optionally; else `null` (un-audited, as before).
+ */
 function makeAuditSinkProvider(override) {
-    return { provide: tokens_js_1.SHIELD_AUDIT_SINK, useValue: override ?? null };
+    return override
+        ? { provide: tokens_js_1.SHIELD_AUDIT_SINK, useValue: override }
+        : {
+            provide: tokens_js_1.SHIELD_AUDIT_SINK,
+            useFactory: (defaultSink) => defaultSink ?? null,
+            inject: [{ token: tokens_js_1.SHIELD_DEFAULT_AUTH_AUDIT_SINK, optional: true }],
+        };
 }
 /**
  * Bind the OPTIONAL eager session-facts projector (ADR-0011). Same value-provider
@@ -973,6 +1090,10 @@ let AuthModule = AuthModule_1 = class AuthModule {
         // `resolveDefaultEmailSender` (that clearer error is kept; in development/test the rule is off).
         // G-010: `'env'` is a real sender unless `EMAIL_PROVIDER=disabled` (read after resolveBootSecrets).
         const mailDisabled = (0, email_delivery_js_1.isMailDisabled)(options.emailSender, process.env);
+        // R1.8: validated here so a bad value fails the boot with a clear message.
+        const signInWith = (0, sign_in_with_js_1.resolveSignInWith)(options.signInWith);
+        // R7: validated here too, so a bad value fails the boot with a clear message.
+        const captcha = (0, captcha_providers_js_1.captchaProviders)(options.captcha);
         return {
             module: AuthModule_1,
             imports: [persistence_module_js_1.PersistenceModule.forRoot()],
@@ -986,6 +1107,11 @@ let AuthModule = AuthModule_1 = class AuthModule {
             controllers: [auth_controller_js_1.AuthController, confirm_email_controller_js_1.ConfirmEmailController, account_controller_js_1.AccountController, auth_facts_controller_js_1.AuthFactsController],
             providers: [
                 passwordHasherProvider,
+                { provide: tokens_js_1.SHIELD_SIGN_IN_WITH, useValue: signInWith },
+                // R1.9: boot count of active users with a login name (only with `username`).
+                loginNameCountBootProvider,
+                // R7: the CAPTCHA config, verifier and gate (`null` gate when the option is absent).
+                ...captcha,
                 makeCredentialResolverProvider(options.credentialResolver),
                 // The current-user profile seam backing `GET /auth/me` (null when absent).
                 makeProfileResolverProvider(options.profileResolver),
@@ -1024,6 +1150,9 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 // fails closed, denying every switch — cannot verify the target binding). Consumed by
                 // AuthController's scopeSwitch handler.
                 makeMembershipCheckerProvider(options.membershipChecker),
+                // R15.1: the logout proof check + the `logoutRequiresProof` option (default false).
+                logout_proof_js_1.logoutProofVerifierProvider,
+                (0, logout_proof_js_1.makeLogoutRequiresProofProvider)(options.logoutRequiresProof),
                 // The framework-DEFAULT permission-facts adapter backing AuthFactsController
                 // (`/identity/auth-facts` + `/identity/permissions-version`). Reads role grants +
                 // per-tenant version from the pool; expands `identity:*` wildcards against the
@@ -1045,6 +1174,13 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 permissionVersionCacheProvider,
                 // Phase 3B review P1: the durable re-enroll marker + account status for the rebuild.
                 sessionRestrictionStoreProvider,
+                // Auth capabilities R2: the MariaDB requirement source and the mandatory-2FA service
+                // (`null` unless identity signals the security-policy feature).
+                mfaRequirementSourceProvider,
+                exports.mfaRequirementProvider,
+                // R11: identity's admin sign-in controls (step-up and unlock).
+                exports.adminStepUpProvider,
+                exports.accountUnlockerProvider,
                 hotSessionStoreProvider,
                 tokenGeneratorProvider,
                 refreshHasherProvider,
@@ -1132,6 +1268,15 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 // reads it (gate 5) and `@astram/identity`'s bumper publishes to it after commit.
                 tokens_js_1.SHIELD_PERMISSION_VERSION_CACHE,
                 tokens_js_1.SHIELD_SESSION_RESTRICTIONS,
+                // Auth capabilities R2: the enforcement guard injects the service (gate-5 recompute).
+                tokens_js_1.SHIELD_MFA_REQUIREMENT,
+                tokens_js_1.SHIELD_MFA_REQUIREMENT_SOURCE,
+                tokens_js_1.SHIELD_SIGN_IN_WITH,
+                // R7: exported for inspection and for later endpoints (OTP request, R7.2).
+                tokens_js_1.SHIELD_CAPTCHA_GATE,
+                // R11: identity's admin sign-in controls inject these (through @astram/guard/internal).
+                tokens_js_1.SHIELD_ADMIN_STEP_UP,
+                tokens_js_1.SHIELD_ACCOUNT_UNLOCKER,
             ],
         };
     }

package/dist/auth/captcha-gate.d.ts

@@ -0,0 +1,103 @@
+import type Redis from 'ioredis';
+import { type CaptchaProvider, type CaptchaVerifier } from '@astram/core';
+import type { CaptchaConfig, CaptchaEndpoint, CaptchaMode } from '../config/captcha-config.js';
+import type { AuditSink } from './ports/audit-sink.js';
+/** Fixed counter window (ms). */
+export declare const CAPTCHA_WINDOW_MS: number;
+export declare const AUTH_CAPTCHA_FAILED = "auth.captcha.failed";
+export declare const AUTH_CAPTCHA_FAIL_OPEN = "auth.captcha.fail_open";
+/**
+ * Bump every key and arm the window on the first hit (or a key left without a TTL). Returns the
+ * new counts, in key order. KEYS = the counter keys; ARGV[1] = window ms.
+ */
+export declare const CAPTCHA_BUMP_SCRIPT = "local out = {}\nfor i, k in ipairs(KEYS) do\n  local n = redis.call('INCR', k)\n  if n == 1 or redis.call('PTTL', k) == -1 then\n    redis.call('PEXPIRE', k, ARGV[1])\n  end\n  out[i] = n\nend\nreturn out";
+/** The counters behind the adaptive decision. */
+export interface CaptchaCounterStore {
+    /** Current counts (missing = 0). REJECTS on a store error. */
+    counts(keys: readonly string[]): Promise<readonly number[]>;
+    /** Increment each key (fixed window); returns the new counts. REJECTS on a store error. */
+    bump(keys: readonly string[]): Promise<readonly number[]>;
+    /** Remove keys. Best-effort. */
+    clear(keys: readonly string[]): Promise<void>;
+    /** `true` the first time `key` is seen in a window (audit bounding). Best-effort: error ⇒ false. */
+    firstInWindow(key: string): Promise<boolean>;
+}
+/** {@link CaptchaCounterStore} over the guard's bounded ioredis client. */
+export declare class RedisCaptchaCounterStore implements CaptchaCounterStore {
+    private readonly redis;
+    private readonly windowMs;
+    constructor(redis: Pick<Redis, 'mget' | 'eval' | 'del' | 'set'>, windowMs?: number);
+    private k;
+    counts(keys: readonly string[]): Promise<readonly number[]>;
+    bump(keys: readonly string[]): Promise<readonly number[]>;
+    clear(keys: readonly string[]): Promise<void>;
+    /**
+     * Remove keys and REJECT on a store error (auth capabilities R11.1: an admin unlock clears the
+     * account counters and must not report a success it did not achieve). Not on the port: only the
+     * unlocker uses it.
+     */
+    clearStrict(keys: readonly string[]): Promise<void>;
+    firstInWindow(key: string): Promise<boolean>;
+}
+/** Who/what an attempt is about. `ip` is set only when per-IP limiting is on. */
+export interface CaptchaSubject {
+    readonly accountId?: string | null;
+    readonly tenantId?: string | null;
+    readonly typedText?: string | null;
+    readonly ip?: string | null;
+}
+/** The gate's verdict for one request. */
+export type CaptchaVerdict = {
+    readonly kind: 'not_required';
+} | {
+    readonly kind: 'passed';
+} | {
+    readonly kind: 'fail_open';
+} | {
+    readonly kind: 'failed';
+};
+/** What `GET /auth/login-options` publishes (never the secret). */
+export interface CaptchaPublicOptions {
+    readonly provider: CaptchaProvider;
+    readonly siteKey: string;
+    readonly mode: CaptchaMode;
+}
+export interface CaptchaGateDeps {
+    readonly config: CaptchaConfig;
+    readonly verifier: CaptchaVerifier;
+    readonly counters: CaptchaCounterStore;
+    readonly auditSink?: AuditSink | null;
+    readonly logger?: {
+        log(message: unknown): void;
+        warn(message: string): void;
+    };
+}
+export declare class CaptchaGate {
+    private readonly deps;
+    private readonly logger;
+    constructor(deps: CaptchaGateDeps);
+    /** The public part of the config (provider, site key, mode). */
+    get publicOptions(): CaptchaPublicOptions;
+    /** True when this endpoint is protected (`CAPTCHA_ENDPOINTS`). */
+    covers(endpoint: CaptchaEndpoint): boolean;
+    /** True when the mode is `always` (every attempt is challenged). */
+    get always(): boolean;
+    private keys;
+    private overThreshold;
+    /** Is a challenge required now? A store error ⇒ `true` (fail closed). */
+    required(endpoint: CaptchaEndpoint, subject: CaptchaSubject): Promise<boolean>;
+    /**
+     * Decide and, when required, verify `token`. Call BEFORE any hash / code check. Never throws.
+     */
+    check(endpoint: CaptchaEndpoint, subject: CaptchaSubject, token: unknown, remoteIp?: string): Promise<CaptchaVerdict>;
+    /**
+     * Count one failure (login: wrong password; forgot: every request; reset: bad token). Returns
+     * whether the NEXT attempt needs a challenge (the failure body's `captcha: 'required'` flag). A
+     * store error ⇒ `true` (fail closed, consistent with {@link required}).
+     */
+    recordFailure(endpoint: CaptchaEndpoint, subject: CaptchaSubject): Promise<boolean>;
+    /** A success clears the account and typed-text counters (never the IP one). Best-effort. */
+    recordSuccess(endpoint: CaptchaEndpoint, subject: CaptchaSubject): Promise<void>;
+    private count;
+}
+//# sourceMappingURL=captcha-gate.d.ts.map

package/dist/auth/captcha-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha-gate.d.ts","sourceRoot":"","sources":["../../src/auth/captcha-gate.ts"],"names":[],"mappings":"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"}