@adonis-agora/authkit-server 0.34.0

package/build/src/host/runtime_toggles.d.ts

@@ -0,0 +1,807 @@
+/**
+ * Runtime toggles — settings de `auth_settings` que controlam comportamento
+ * operacional em tempo de execução, no padrão do bot_protection resolver.
+ *
+ * Cada setting segue o contrato:
+ *   - setting presente → manda (sobrescreve config estático)
+ *   - setting ausente/inválido/erro DB → config estático (fail-safe total)
+ *
+ * Keys conhecidas em `auth_settings`:
+ *   - `registration`         → RegistrationSetting
+ *   - `require_verified_email` → RequireVerifiedEmailSetting
+ *   - `maintenance_mode`     → MaintenanceModeSetting
+ */
+import type { SettingsCapability } from './runtime_settings.js';
+/**
+ * Chaves conhecidas do catálogo de runtime settings. Centralizado aqui para
+ * que qualquer code-path possa importar a constante e não depender de strings.
+ */
+export declare const SETTING_KEYS: {
+    readonly BOT_PROTECTION: "bot_protection";
+    readonly REGISTRATION: "registration";
+    readonly REQUIRE_VERIFIED_EMAIL: "require_verified_email";
+    readonly MAINTENANCE_MODE: "maintenance_mode";
+    readonly AUTH_METHODS: "auth_methods";
+    readonly EMAIL_CHANGE: "email_change";
+    readonly SECURITY_NOTIFICATIONS: "security_notifications";
+    readonly PASSWORD_HISTORY: "password_history";
+    readonly PASSWORD_EXPIRATION: "password_expiration";
+    readonly SESSION_POLICY: "session_policy";
+    readonly LOCKOUT: "lockout";
+    readonly RATE_LIMIT: "rate_limit";
+    readonly PASSWORD_POLICY: "password_policy";
+    readonly NOTIFICATIONS: "notifications";
+    readonly TRUSTED_DEVICES: "trusted_devices";
+    readonly TOKEN_TTL: "token_ttl";
+    readonly ADMIN_IMPERSONATION: "admin_impersonation";
+    readonly ORGANIZATIONS_POLICY: "organizations_policy";
+    readonly ROLES_CATALOG: "roles_catalog";
+    readonly OTP_LOCKOUT: "otp_lockout";
+    readonly SUDO_MODE: "sudo_mode";
+    readonly ACCOUNT_EXPIRATION: "account_expiration";
+    readonly KEY_ROTATION: "key_rotation";
+};
+export type SettingKey = (typeof SETTING_KEYS)[keyof typeof SETTING_KEYS];
+/**
+ * Shape da setting `registration` em `auth_settings`.
+ *
+ * Quando `enabled: false`, o signup público é recusado (GET mostra mensagem;
+ * POST rejeita). Fluxos administrativos (admin create + org invite) continuam
+ * funcionando — eles NÃO passam por este guard.
+ */
+export interface RegistrationSetting {
+    enabled: boolean;
+}
+/**
+ * Resolve o valor efetivo de "registration enabled" combinando a setting
+ * persistida em runtime com o config estático.
+ *
+ * Regras:
+ *   - `config.registration?.enabled` pode estar em `ResolvedServerConfig`
+ *     (quando o host o declara). Default: `true` (aberto por padrão).
+ *   - setting presente → sobrescreve o default/config.
+ *   - setting ausente/inválido/erro → usa configDefault.
+ *
+ * FAIL-SAFE: `getSetting` nunca lança (contrato do RuntimeSettings). Se
+ * retornar null, usamos configDefault.
+ */
+export declare function resolveEffectiveRegistration(configDefault: boolean | undefined, settings: SettingsCapability): Promise<boolean>;
+/**
+ * Shape da setting `require_verified_email` em `auth_settings`.
+ *
+ * Quando presente, sobrescreve `login.requireVerifiedEmail` do config estático
+ * para todos os três fluxos de login (senha, magic link, passkey-first).
+ *
+ * `graceDays` (opcional, default 0): conta NÃO verificada pode logar até
+ * `created_at + graceDays` dias. Após a janela, comporta-se como hoje (bloqueia).
+ * 0 = sem graça (comportamento original).
+ */
+export interface RequireVerifiedEmailSetting {
+    enabled: boolean;
+    /** Dias de graça após o cadastro. Default: 0 (sem graça). */
+    graceDays?: number;
+}
+/** Resultado resolvido de `require_verified_email`. */
+export interface ResolvedRequireVerifiedEmail {
+    enabled: boolean;
+    /** Dias de graça após o cadastro (0 = sem graça). */
+    graceDays: number;
+}
+/**
+ * Resolve o valor efetivo de `requireVerifiedEmail` combinando a setting
+ * persistida em runtime com o config estático.
+ *
+ * Regras (mesmas do `resolveEffectiveRegistration`):
+ *   - configDefault vem de `cfg.login.requireVerifiedEmail` (default false).
+ *   - setting presente → sobrescreve.
+ *   - setting ausente/inválido/erro → usa configDefault.
+ */
+export declare function resolveEffectiveRequireVerifiedEmail(configDefault: boolean | undefined, settings: SettingsCapability): Promise<boolean>;
+/**
+ * Resolve o valor efetivo COMPLETO de `require_verified_email` incluindo
+ * `graceDays`. Usado pelo gate de login para implementar a janela de graça.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: configDefault, graceDays: 0 }`.
+ */
+export declare function resolveEffectiveRequireVerifiedEmailFull(configDefault: boolean | undefined, settings: SettingsCapability): Promise<ResolvedRequireVerifiedEmail>;
+/**
+ * Shape da setting `maintenance_mode` em `auth_settings`.
+ *
+ * Quando `enabled: true`:
+ *   - Telas de login/signup/forgot/interaction mostram página de manutenção.
+ *   - POSTs desses fluxos rejeitam (503-like / redirect para manutenção).
+ *   - Fluxos de token OIDC já autenticados (refresh, introspection, userinfo)
+ *     CONTINUAM funcionando — não derrubamos sessões existentes.
+ *   - Admin API e console admin continuam acessíveis.
+ *   - Login de contas com role admin (conforme `cfg.admin.roles`) CONTINUA
+ *     PERMITIDO — senão o operador se tranca fora. Contas comuns são bloqueadas.
+ *
+ * `message` é exibida na página de manutenção. Quando ausente, usa i18n default.
+ *
+ * @remarks LOCKOUT SAFETY
+ *   O login admin continua funcionando durante a manutenção (verificado pela
+ *   role da conta). Se por qualquer razão o console admin não estiver acessível
+ *   via browser (ex.: infra), o operador pode desligar a manutenção via Admin
+ *   REST API (PUT /api/authkit/v1/settings/maintenance_mode) sem precisar fazer
+ *   login. A Admin API usa API-key authentication, imune ao modo manutenção.
+ */
+export interface MaintenanceModeSetting {
+    enabled: boolean;
+    /** Mensagem custom exibida na tela de manutenção. Opcional. */
+    message?: string;
+}
+/** Resultado resolvido do maintenance mode, pronto para consumo pelos controllers. */
+export interface ResolvedMaintenanceMode {
+    enabled: boolean;
+    message?: string;
+}
+/**
+ * Resolve o estado efetivo do maintenance mode a partir da setting persistida.
+ *
+ * Regras:
+ *   - setting ausente/inválido/erro DB → `{ enabled: false }` (default: sistema UP).
+ *   - setting presente → usa o valor da setting.
+ *
+ * FAIL-SAFE: qualquer erro → sistema considerado UP (disponibilidade > proteção).
+ */
+export declare function resolveEffectiveMaintenanceMode(settings: SettingsCapability): Promise<ResolvedMaintenanceMode>;
+/**
+ * Shape da setting `auth_methods` em `auth_settings`.
+ *
+ * Controla quais métodos de login a tela oferece em runtime. Todos os campos
+ * são opcionais — campos ausentes são derivados do config/capabilities.
+ *
+ * @remarks
+ *   - `password`:      exibe o formulário de senha. Default: true.
+ *   - `magicLink`:     exibe o botão "me envie um link de login". Default: true
+ *                      se o mail/store suportam.
+ *   - `passkey`:       exibe o botão "entrar com passkey" (passkey-first).
+ *                      Default: true se webauthn configurado e conta tem passkeys.
+ *   - `social`:        lista dos providers sociais a exibir. Default: todos os
+ *                      providers configurados em `config.social.providers`.
+ *                      A setting só pode FILTRAR (não ATIVAR) providers; providers
+ *                      não presentes no config nunca aparecem.
+ *   - `forgotPassword`: exibe o link "esqueci minha senha". Default: true.
+ *                      AUTO-DERIVADO: sempre false quando `password` efetivo é false.
+ */
+export interface AuthMethodsSetting {
+    password?: boolean;
+    magicLink?: boolean;
+    passkey?: boolean;
+    social?: string[];
+    forgotPassword?: boolean;
+    /**
+     * Habilita WebAuthn conditional mediation (autofill) na tela de login.
+     * Quando true (default quando passkey on), o input de e-mail exibe sugestões
+     * de passkey direto no autofill do browser (discoverable credentials).
+     * Fail-safe: browsers sem suporte ou abort → silêncio (login normal segue).
+     * Default: true (quando passkey habilitado).
+     */
+    passkeyAutofill?: boolean;
+}
+/**
+ * Resultado resolvido dos métodos de autenticação, pronto para consumo pelas views.
+ */
+export interface ResolvedAuthMethods {
+    password: boolean;
+    magicLink: boolean;
+    passkey: boolean;
+    social: string[];
+    forgotPassword: boolean;
+    /** WebAuthn conditional mediation ativa (autofill de passkey no input de e-mail). */
+    passkeyAutofill: boolean;
+}
+/**
+ * Capabilities de runtime necessárias para derivar os defaults de auth_methods.
+ * Campos opcionais — quando ausentes, assume defaults conservadores.
+ */
+export interface AuthMethodsCapabilities {
+    /** Providers sociais configurados no config estático. */
+    configuredSocialProviders?: string[];
+    /** Magic link disponível (config.passwordless.magicLink && store.issueMagicLinkToken). */
+    magicLinkCapable?: boolean;
+    /** Passkey-first disponível (config.passwordless.passkeyFirst && store tem passkeys). */
+    passkeyCapable?: boolean;
+}
+/**
+ * Resolve os métodos de autenticação efetivos combinando config estático + setting
+ * persistida em runtime + capabilities.
+ *
+ * Regras:
+ *   1. Defaults derivados do config/capabilities.
+ *   2. Setting presente → sobrescreve campo a campo.
+ *   3. DERIVAÇÃO: `forgotPassword` efetivo = (setting.forgotPassword ?? true) && passwordEnabled.
+ *      Sem método senha ativo, "esqueci minha senha" NUNCA aparece.
+ *   4. `social` efetivo = interseção do setting.social com os providers do config.
+ *      Setting não pode LIGAR provider que o código não tem.
+ *   5. FAIL-SAFE all-off: se todos os métodos ficarem desligados, volta ao derivado
+ *      do config (nunca deixar a tela sem nenhum método). Loga um aviso (console.warn).
+ *   6. Qualquer erro DB → defaults derivados do config (fail-safe total).
+ */
+export declare function resolveEffectiveAuthMethods(settings: SettingsCapability, capabilities?: AuthMethodsCapabilities): Promise<ResolvedAuthMethods>;
+/**
+ * Shape da setting `email_change` em `auth_settings`.
+ *
+ * Controla o fluxo de troca de e-mail verificada em runtime:
+ *   - `enabled`:          habilita/desabilita o fluxo. Default: true (se a capability presente).
+ *   - `ttlHours`:         duração do token de confirmação em horas. Default: 24.
+ *   - `requirePassword`:  exige senha atual para iniciar a troca. Default: true.
+ */
+export interface EmailChangeSetting {
+    enabled?: boolean;
+    ttlHours?: number;
+    requirePassword?: boolean;
+}
+/** Resultado resolvido da setting email_change. */
+export interface ResolvedEmailChangeSetting {
+    enabled: boolean;
+    ttlHours: number;
+    requirePassword: boolean;
+}
+/**
+ * Resolve as configurações efetivas de troca de e-mail, combinando a setting
+ * persistida em runtime com defaults.
+ *
+ * FAIL-SAFE: qualquer erro → defaults (enabled true, 24h, requirePassword true).
+ */
+export declare function resolveEffectiveEmailChange(settings: SettingsCapability): Promise<ResolvedEmailChangeSetting>;
+/**
+ * Tipos de evento de segurança que disparam notificação por e-mail.
+ */
+export type SecurityNotificationKind = 'password_changed' | 'mfa_enabled' | 'mfa_disabled' | 'passkey_added' | 'passkey_removed' | 'email_changed';
+/** Todos os tipos de notificação de segurança suportados. */
+export declare const ALL_SECURITY_NOTIFICATION_KINDS: SecurityNotificationKind[];
+/**
+ * Shape da setting `security_notifications` em `auth_settings`.
+ *
+ *   - `enabled`:  habilita/desabilita todas as notificações. Default: true.
+ *   - `kinds`:    lista dos tipos de evento a notificar. Default: todos.
+ */
+export interface SecurityNotificationsSetting {
+    enabled?: boolean;
+    kinds?: string[];
+}
+/** Resultado resolvido das notificações de segurança. */
+export interface ResolvedSecurityNotifications {
+    enabled: boolean;
+    kinds: SecurityNotificationKind[];
+}
+/**
+ * Resolve as notificações de segurança efetivas, combinando a setting
+ * persistida em runtime com defaults.
+ *
+ * FAIL-SAFE: qualquer erro → defaults (enabled true, todos os kinds).
+ */
+export declare function resolveEffectiveSecurityNotifications(settings: SettingsCapability): Promise<ResolvedSecurityNotifications>;
+/**
+ * Shape da setting `password_history` em `auth_settings`.
+ *
+ * Quando `enabled: true` E a tabela `auth_password_history` existe (capability-
+ * probed), a aplicação verifica os últimos `count` hashes ANTES de aceitar uma
+ * nova senha e rejeita reutilização.
+ *
+ * Sem tabela → setting sem efeito; doctor explica o schema necessário.
+ */
+export interface PasswordHistorySetting {
+    enabled?: boolean;
+    /** Quantos hashes anteriores verificar. Default: 5. */
+    count?: number;
+}
+/** Resultado resolvido de `password_history`. */
+export interface ResolvedPasswordHistory {
+    enabled: boolean;
+    /** Quantos hashes anteriores verificar (>= 1). */
+    count: number;
+}
+/**
+ * Resolve as configurações efetivas de histórico de senhas.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, count: 5 }`.
+ */
+export declare function resolveEffectivePasswordHistory(settings: SettingsCapability): Promise<ResolvedPasswordHistory>;
+/**
+ * Shape da setting `session_policy` em `auth_settings`.
+ *
+ * Controla o comportamento da sessão SSO do oidc-provider e da sessão do console
+ * de conta em runtime, sem necessidade de redeploy.
+ *
+ * ### remember-me
+ * Quando `rememberEnabled: true` (default), a tela de login exibe o checkbox
+ * "manter conectado". Marcado → sessão persistente por `rememberDays` dias.
+ * Desmarcado → sessão transiente (cookie expires ao fechar o browser) com duração
+ * máxima de `defaultSessionHours` horas.
+ *
+ * ### single session
+ * Quando `singleSession: true`, após um login bem-sucedido TODAS as outras sessões
+ * OIDC da conta são revogadas (grants + tokens cascateados). A sessão RECÉM-CRIADA
+ * é preservada. Auditado como `session.single_enforced`.
+ *
+ * ### idle timeout
+ * Quando `idleTimeoutMinutes > 0`, o console de conta (e o console admin) registra
+ * o timestamp da última atividade (`authkit_last_seen`) na sessão Adonis. A cada
+ * request autenticado, se a inatividade exceder o limite, a sessão é encerrada e o
+ * usuário é redirecionado ao login com uma mensagem i18n. Apenas o console de conta
+ * é coberto — o lado OIDC (refresh tokens) tem vida própria e está fora de escopo.
+ *
+ * @remarks
+ * A duração da sessão OIDC é controlada pelo TTL do oidc-provider, que é uma função
+ * configurada em build_provider.ts e lê esta setting via um holder mutável atualizado
+ * a cada save/reset desta setting. O TTL é **síncrono** no oidc-provider — não podemos
+ * fazer leituras de DB no path. O holder é atualizado de forma assíncrona (após write)
+ * e cacheado; num restart sem setting persistida, o provider usa o config estático.
+ */
+export interface SessionPolicySetting {
+    /** Exibe checkbox "manter conectado" na tela de login. Default: true. */
+    rememberEnabled?: boolean;
+    /** Duração da sessão quando "manter conectado" está marcado (dias). Default: 30. */
+    rememberDays?: number;
+    /**
+     * Duração máxima da sessão quando "manter conectado" NÃO está marcado (horas).
+     * Default: derivado de `config.ttl.session` em horas (default 168 h = 7 dias).
+     * Independente do remember, a sessão OIDC nunca excede este valor quando transiente.
+     */
+    defaultSessionHours?: number;
+    /** Força sessão única por conta: revoga outras sessões no login. Default: false. */
+    singleSession?: boolean;
+    /**
+     * Timeout de inatividade do console de conta (minutos). 0 = desligado. Default: 0.
+     * O idle é rastreado pela sessão Adonis; não cobre o lado OIDC (tokens independentes).
+     */
+    idleTimeoutMinutes?: number;
+}
+/** Resultado resolvido de `session_policy`. */
+export interface ResolvedSessionPolicy {
+    rememberEnabled: boolean;
+    rememberDays: number;
+    defaultSessionHours: number;
+    singleSession: boolean;
+    idleTimeoutMinutes: number;
+}
+/** Defaults da session_policy quando a setting não existe. */
+export declare const SESSION_POLICY_DEFAULTS: ResolvedSessionPolicy;
+/**
+ * Resolve as configurações efetivas de session policy.
+ *
+ * FAIL-SAFE: qualquer erro → defaults (comportamento original intacto).
+ *
+ * @param configDefaultSessionHours Horas derivadas de `config.ttl.session` (em segundos → horas).
+ *   Quando ausente, usa 168 h (7 dias = padrão do oidc-provider).
+ */
+export declare function resolveEffectiveSessionPolicy(settings: SettingsCapability, configDefaultSessionHours?: number): Promise<ResolvedSessionPolicy>;
+/**
+ * Shape da setting `password_expiration` em `auth_settings`.
+ *
+ * Quando `enabled: true` E a coluna `password_changed_at` existe (capability-
+ * probed), força a troca de senha no login após `maxAgeDays` dias sem trocar.
+ *
+ * Sem coluna → setting sem efeito; doctor explica a migração necessária.
+ */
+export interface PasswordExpirationSetting {
+    enabled?: boolean;
+    /** Máximo de dias desde a última troca. Default: 90. */
+    maxAgeDays?: number;
+}
+/** Resultado resolvido de `password_expiration`. */
+export interface ResolvedPasswordExpiration {
+    enabled: boolean;
+    /** Máximo de dias desde a última troca (>= 1). */
+    maxAgeDays: number;
+}
+/**
+ * Resolve as configurações efetivas de expiração de senha.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, maxAgeDays: 90 }`.
+ */
+export declare function resolveEffectivePasswordExpiration(settings: SettingsCapability): Promise<ResolvedPasswordExpiration>;
+/**
+ * Shape da setting `lockout` em `auth_settings`.
+ *
+ * Controla a política de bloqueio progressivo de conta em runtime. Os campos de
+ * política (enabled, maxAttempts, windowSec, baseLockoutSec, maxLockoutSec) são
+ * gerenciados aqui; o campo `store` do config estático é infra e NÃO é movido.
+ *
+ * FALLBACK: campos ausentes caem nos valores do `config.lockout` (via
+ * `configDefault`) ou nos defaults da lib.
+ */
+export interface LockoutSetting {
+    enabled?: boolean;
+    maxAttempts?: number;
+    windowSec?: number;
+    baseLockoutSec?: number;
+    maxLockoutSec?: number;
+}
+/** Resultado resolvido de `lockout` (política apenas; store vem do config estático). */
+export interface ResolvedLockoutSetting {
+    enabled: boolean;
+    maxAttempts: number;
+    windowSec: number;
+    baseLockoutSec: number;
+    maxLockoutSec: number;
+}
+/** Config default de lockout (valores que chegam do config estático). */
+export interface LockoutConfigDefaults {
+    enabled?: boolean;
+    maxAttempts?: number;
+    windowSec?: number;
+    baseLockoutSec?: number;
+    maxLockoutSec?: number;
+}
+/**
+ * Resolve as configurações efetivas de lockout.
+ *
+ * Precedência: setting BD → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault (ou lib defaults).
+ */
+export declare function resolveEffectiveLockout(settings: SettingsCapability, configDefault?: LockoutConfigDefaults): Promise<ResolvedLockoutSetting>;
+/**
+ * Shape do bucket de rate-limit.
+ */
+export interface RateLimitBucketSetting {
+    points?: number;
+    duration?: string;
+}
+/**
+ * Shape da setting `rate_limit` em `auth_settings`.
+ *
+ * LIMITAÇÃO CONHECIDA: O throttle do `@adonisjs/limiter` é construído NO
+ * REGISTRO DA ROTA (boot-time) com os valores da config estática. O oidc-provider
+ * e o Adonis não permitem alterar middlewares de rota em runtime. Por isso, os
+ * valores de `rate_limit` da setting SÃO LIDOS pelo AccountLockout e pelo
+ * middleware de throttle via função utilitária que é chamada por request, mas
+ * APENAS no caminho do lockout/bloqueio — o middleware de throttle por IP (que
+ * usa `@adonisjs/limiter` diretamente) CONTINUA usando a config estática.
+ * Para throttle dinâmico verdadeiro, reconfigure e reinicie o servidor.
+ *
+ * Em termos práticos: `login.points`/`duration` e `introspection.points`/`duration`
+ * AFETAM o comportamento do lockout (AccountLockout, que usa o limiter diretamente),
+ * MAS o middleware de throttle de rota fica com a config de boot.
+ *
+ * @see resolveEffectiveRateLimit
+ */
+export interface RateLimitSetting {
+    login?: RateLimitBucketSetting;
+    introspection?: RateLimitBucketSetting;
+}
+/** Resultado resolvido do rate_limit (somente os buckets de política). */
+export interface ResolvedRateLimitSetting {
+    login: {
+        points: number;
+        duration: string;
+    };
+    introspection: {
+        points: number;
+        duration: string;
+    };
+}
+export interface RateLimitConfigDefaults {
+    login?: {
+        points?: number;
+        duration?: string;
+    };
+    introspection?: {
+        points?: number;
+        duration?: string;
+    };
+}
+/**
+ * Resolve as configurações efetivas dos buckets de rate-limit.
+ *
+ * Precedência: setting BD → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault.
+ *
+ * NOTA: o middleware de throttle de rota (Adonis) usa os valores do config de
+ * boot e NÃO é afetado por esta setting em runtime. Veja JSDoc de RateLimitSetting.
+ */
+export declare function resolveEffectiveRateLimit(settings: SettingsCapability, configDefault?: RateLimitConfigDefaults): Promise<ResolvedRateLimitSetting>;
+/**
+ * Shape da setting `password_policy` em `auth_settings`.
+ *
+ * Controla as regras de complexidade de senha e checagem de vazamento.
+ * Os campos `legacyVerifier`, `pepper` e `timeoutMs` do config estático são
+ * infra/código e NÃO são movidos para a setting.
+ *
+ * FALLBACK: campos ausentes caem nos valores do `config.accountStore` password
+ * config (via `configDefault`) ou nos defaults da lib.
+ */
+export interface PasswordPolicySetting {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSymbols?: boolean;
+    /** Verifica se a senha aparece em vazamentos (HaveIBeenPwned, k-anonymity). */
+    checkPwned?: boolean;
+    /**
+     * Rejeita senhas que constam na lista offline de ~10 000 senhas mais comuns.
+     * A checagem é case-insensitive e roda ANTES do HIBP (mais barata).
+     * Default: true.
+     */
+    blockCommon?: boolean;
+}
+/** Resultado resolvido da password_policy. */
+export interface ResolvedPasswordPolicySetting {
+    minLength: number;
+    requireUppercase: boolean;
+    requireLowercase: boolean;
+    requireNumbers: boolean;
+    requireSymbols: boolean;
+    checkPwned: boolean;
+    /** Rejeita senhas da lista offline de senhas comuns. Default: true. */
+    blockCommon: boolean;
+}
+export interface PasswordPolicyConfigDefaults {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSymbols?: boolean;
+    checkPwned?: boolean;
+    blockCommon?: boolean;
+}
+/**
+ * Resolve as configurações efetivas de política de senha.
+ *
+ * Precedência: setting BD → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export declare function resolveEffectivePasswordPolicy(settings: SettingsCapability, configDefault?: PasswordPolicyConfigDefaults): Promise<ResolvedPasswordPolicySetting>;
+/**
+ * Shape da setting `notifications` em `auth_settings`.
+ *
+ * Controla se e-mails de alerta de novo acesso e novo dispositivo são enviados.
+ * FALLBACK: campos ausentes caem nos valores do `config.notifications`.
+ */
+export interface NotificationsSetting {
+    newLoginEmail?: boolean;
+    newDeviceEmail?: boolean;
+}
+/** Resultado resolvido de `notifications`. */
+export interface ResolvedNotificationsSetting {
+    newLoginEmail: boolean;
+    newDeviceEmail: boolean;
+}
+export interface NotificationsConfigDefaults {
+    newLoginEmail?: boolean;
+    newDeviceEmail?: boolean;
+}
+/**
+ * Resolve as configurações efetivas de notificações de acesso/dispositivo.
+ *
+ * Precedência: setting BD → configDefault → lib default (true/true).
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export declare function resolveEffectiveNotifications(settings: SettingsCapability, configDefault?: NotificationsConfigDefaults): Promise<ResolvedNotificationsSetting>;
+/**
+ * Shape da setting `trusted_devices` em `auth_settings`.
+ *
+ * Controla a POLÍTICA de dispositivos confiáveis (enabled, days). Os campos de
+ * infra (cookie name, segredos) continuam no config estático.
+ *
+ * FALLBACK: campos ausentes caem nos valores do `config.trustedDevices`.
+ */
+export interface TrustedDevicesSetting {
+    enabled?: boolean;
+    days?: number;
+}
+/** Resultado resolvido de `trusted_devices` (política). */
+export interface ResolvedTrustedDevicesSetting {
+    enabled: boolean;
+    days: number;
+}
+export interface TrustedDevicesConfigDefaults {
+    enabled?: boolean;
+    days?: number;
+}
+/**
+ * Resolve as configurações efetivas de trusted devices.
+ *
+ * Precedência: setting BD → configDefault → lib default (enabled=true, days=30).
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export declare function resolveEffectiveTrustedDevices(settings: SettingsCapability, configDefault?: TrustedDevicesConfigDefaults): Promise<ResolvedTrustedDevicesSetting>;
+/**
+ * Shape da setting `token_ttl` em `auth_settings`.
+ *
+ * Controla os TTLs dos tokens OIDC em runtime via holders mutáveis (mesmo padrão
+ * do session_policy / sessionTtlHolder). Os holders são atualizados de forma
+ * SÍNCRONA após um write/reset da setting — o oidc-provider lê os TTL functions
+ * de forma síncrona, portanto os valores ficam disponíveis sem redeploy.
+ *
+ * Valores em SEGUNDOS. Campos ausentes caem nos valores do `config.ttl`.
+ *
+ * NOTA: session TTL JÁ é dinâmico via session_policy — NÃO duplique aqui.
+ */
+export interface TokenTtlSetting {
+    accessTokenSec?: number;
+    idTokenSec?: number;
+    refreshTokenSec?: number;
+}
+/** Resultado resolvido de `token_ttl`. */
+export interface ResolvedTokenTtlSetting {
+    accessTokenSec: number;
+    idTokenSec: number;
+    refreshTokenSec: number;
+}
+export interface TokenTtlConfigDefaults {
+    accessTokenSec?: number;
+    idTokenSec?: number;
+    refreshTokenSec?: number;
+}
+/**
+ * Resolve as configurações efetivas de TTL de tokens.
+ *
+ * Precedência: setting BD → configDefault → lib default (900s/900s/2592000s).
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export declare function resolveEffectiveTokenTtl(settings: SettingsCapability, configDefault?: TokenTtlConfigDefaults): Promise<ResolvedTokenTtlSetting>;
+/**
+ * Shape da setting `admin_impersonation` em `auth_settings`.
+ *
+ * Controla se o painel de impersonation (RFC 8693 token exchange) é exibido no
+ * console admin. FALLBACK: campo ausente cai em `config.admin.impersonation`.
+ */
+export interface AdminImpersonationSetting {
+    enabled?: boolean;
+}
+/** Resultado resolvido de `admin_impersonation`. */
+export interface ResolvedAdminImpersonationSetting {
+    enabled: boolean;
+}
+/**
+ * Resolve as configurações efetivas de impersonation.
+ *
+ * Precedência: setting BD → configDefault → lib default (false).
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export declare function resolveEffectiveAdminImpersonation(settings: SettingsCapability, configDefault?: boolean): Promise<ResolvedAdminImpersonationSetting>;
+/**
+ * Shape da setting `organizations_policy` em `auth_settings`.
+ *
+ * Controla as POLÍTICAS de organizações em runtime (allowSelfCreate,
+ * invitationTtlHours, roles). O campo `enabled` da capability e a derivação de
+ * tabelas ficam no config estático / capability-probing. FALLBACK: campos
+ * ausentes caem nos valores do `config.organizations`.
+ */
+export interface OrganizationsPolicySetting {
+    allowSelfCreate?: boolean;
+    invitationTtlHours?: number;
+    roles?: string[];
+}
+/** Resultado resolvido de `organizations_policy`. */
+export interface ResolvedOrganizationsPolicySetting {
+    allowSelfCreate: boolean;
+    invitationTtlHours: number;
+    roles: string[];
+}
+export interface OrganizationsPolicyConfigDefaults {
+    allowSelfCreate?: boolean;
+    invitationTtlHours?: number;
+    roles?: string[];
+}
+/**
+ * Uma entrada do catálogo de roles globais.
+ */
+export interface RoleCatalogEntry {
+    /** Nome da role — maiúsculas e underscores (ex.: ADMIN, EDITOR). */
+    name: string;
+    /** Descrição legível (opcional). */
+    description?: string;
+}
+/**
+ * Shape da setting `roles_catalog` em `auth_settings`.
+ *
+ * Catálogo de roles globais disponíveis para atribuição a usuários no console
+ * admin. O catálogo substitui o campo de texto livre na página de usuários por
+ * checkboxes derivadas deste catálogo.
+ *
+ * INVARIANTE: `ADMIN` é sempre garantido no catálogo (merge defensivo) — é o
+ * gate do console admin (cfg.admin.roles default ['ADMIN']).
+ */
+export interface RolesCatalogSetting {
+    roles: RoleCatalogEntry[];
+}
+/** Resultado resolvido do catálogo de roles, ordenado por nome. */
+export interface ResolvedRolesCatalog {
+    roles: RoleCatalogEntry[];
+}
+/** Default da lib: apenas ADMIN. */
+export declare const ROLES_CATALOG_DEFAULT: ResolvedRolesCatalog;
+/**
+ * Resolve o catálogo efetivo de roles globais a partir da setting persistida.
+ *
+ * Regras:
+ *   - ADMIN é SEMPRE garantido no resultado (merge defensivo — é o gate do console).
+ *   - setting ausente/inválida/erro → default (apenas ADMIN).
+ *   - O resultado é ordenado por nome (ADMIN sempre incluído).
+ *   - Entradas com `name` inválido (não-string ou vazio) são descartadas silenciosamente.
+ *
+ * FAIL-SAFE: qualquer erro DB → default.
+ */
+/**
+ * Resolve roles catalog efetivo: org → global → default.
+ *
+ * @param settings - SettingsCapability
+ * @param orgId - opcional; quando fornecido, tenta settings da org antes do global
+ */
+export declare function resolveEffectiveRolesCatalog(settings: SettingsCapability, orgId?: string | null): Promise<ResolvedRolesCatalog>;
+/**
+ * Resolve as configurações efetivas de política de organizações.
+ *
+ * Precedência: org-setting → global-setting → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault.
+ *
+ * Invariante mantida: 'owner' é sempre incluído na lista de roles (governance).
+ *
+ * @param settings - SettingsCapability
+ * @param configDefault - defaults estáticos do config do host
+ * @param orgId - opcional; quando fornecido, tenta settings da org antes do global
+ */
+export declare function resolveEffectiveOrganizationsPolicy(settings: SettingsCapability, configDefault?: OrganizationsPolicyConfigDefaults, orgId?: string | null): Promise<ResolvedOrganizationsPolicySetting>;
+/**
+ * Resolve o CATÁLOGO efetivo de roles de org (lista de roles permitidas),
+ * garantindo a invariante de governance: `owner` está sempre presente.
+ *
+ * Layer canônico de validação de role de org, compartilhado entre o caminho
+ * admin (`AdminOrgsService.resolveRoleCatalog`) e o member-facing
+ * (`account_orgs_controller`). Fail-safe: sem `settings` (null), usa o catálogo
+ * do config estático (mesma semântica do `resolveEffectiveOrganizationsPolicy`
+ * com `settings` indisponível — que cai nos `configDefault`).
+ *
+ * @param settings - SettingsCapability ou null (null → só config defaults)
+ * @param configDefault - defaults estáticos do config do host
+ * @param orgId - opcional; quando fornecido, tenta settings da org antes do global
+ */
+export declare function resolveRoleCatalogList(settings: SettingsCapability | null, configDefault?: OrganizationsPolicyConfigDefaults, orgId?: string | null): Promise<string[]>;
+/**
+ * Função PURA: valida se um `role` faz parte do catálogo efetivo de roles de org.
+ *
+ * É o único ponto de verdade para "esta role é válida para esta org?", reusado
+ * tanto pelo caminho admin quanto pelo member-facing — eliminando a
+ * reimplementação inline `policy.roles.includes(role)` que vivia em dois layers.
+ * H4: bloqueia roles fora do catálogo (incluindo arbitrárias e, quando não
+ * catalogadas, `owner`). Fail-safe via {@link resolveRoleCatalogList}.
+ *
+ * @param role - role candidata
+ * @param settings - SettingsCapability ou null
+ * @param configDefault - defaults estáticos do config do host
+ * @param orgId - opcional; escopo de org para a resolução do catálogo
+ */
+export declare function isRoleInCatalog(role: string, settings: SettingsCapability | null, configDefault?: OrganizationsPolicyConfigDefaults, orgId?: string | null): Promise<boolean>;
+/**
+ * Shape da setting `account_expiration` em `auth_settings`.
+ *
+ * Quando `enabled: true` E o audit suporta `list` (capability-probed):
+ *   - O login de contas inativas (sem `login.success` há mais de `inactiveDays`
+ *     dias) é BLOQUEADO com mensagem i18n clara e auditado como
+ *     `account.expired_login_blocked`. A reativação se dá via reset de senha
+ *     (link exibido na mensagem de erro) — um reset bem-sucedido registra
+ *     atividade e reativa implicitamente.
+ *   - Comando de varredura `authkit:accounts:expire-scan` (cron do host):
+ *     reporta expiradas e "a expirar em warnDays dias"; com `--warn` envia
+ *     e-mail de aviso via hook `mail.onAccountExpirationWarning` (deduplicado
+ *     via audit `account.expiration_warned` na janela de `warnDays` dias).
+ *
+ * SEM audit queryável → feature indisponível (no-op + doctor explica).
+ * SEM coluna nova — "última atividade" = último `login.success` no audit.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, inactiveDays: 365, warnDays: 14 }`.
+ */
+export interface AccountExpirationSetting {
+    enabled?: boolean;
+    /** Dias de inatividade para expirar. Default: 365. */
+    inactiveDays?: number;
+    /** Dias de antecipação para enviar aviso. Default: 14. */
+    warnDays?: number;
+}
+/** Resultado resolvido de `account_expiration`. */
+export interface ResolvedAccountExpiration {
+    enabled: boolean;
+    inactiveDays: number;
+    warnDays: number;
+}
+/**
+ * Resolve as configurações efetivas de expiração de conta.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, inactiveDays: 365, warnDays: 14 }`.
+ */
+export declare function resolveEffectiveAccountExpiration(settings: SettingsCapability): Promise<ResolvedAccountExpiration>;