@adonis-agora/authkit-server 0.34.0

package/build/src/host/runtime_toggles.js

@@ -0,0 +1,784 @@
+/**
+ * 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
+ */
+// ---------------------------------------------------------------------------
+// Known setting keys registry
+// ---------------------------------------------------------------------------
+/**
+ * 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 const SETTING_KEYS = {
+    BOT_PROTECTION: 'bot_protection',
+    REGISTRATION: 'registration',
+    REQUIRE_VERIFIED_EMAIL: 'require_verified_email',
+    MAINTENANCE_MODE: 'maintenance_mode',
+    AUTH_METHODS: 'auth_methods',
+    EMAIL_CHANGE: 'email_change',
+    SECURITY_NOTIFICATIONS: 'security_notifications',
+    PASSWORD_HISTORY: 'password_history',
+    PASSWORD_EXPIRATION: 'password_expiration',
+    SESSION_POLICY: 'session_policy',
+    LOCKOUT: 'lockout',
+    RATE_LIMIT: 'rate_limit',
+    PASSWORD_POLICY: 'password_policy',
+    NOTIFICATIONS: 'notifications',
+    TRUSTED_DEVICES: 'trusted_devices',
+    TOKEN_TTL: 'token_ttl',
+    ADMIN_IMPERSONATION: 'admin_impersonation',
+    ORGANIZATIONS_POLICY: 'organizations_policy',
+    ROLES_CATALOG: 'roles_catalog',
+    OTP_LOCKOUT: 'otp_lockout',
+    SUDO_MODE: 'sudo_mode',
+    ACCOUNT_EXPIRATION: 'account_expiration',
+    KEY_ROTATION: 'key_rotation',
+};
+/**
+ * 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 async function resolveEffectiveRegistration(configDefault = true, settings) {
+    const raw = await settings.getSetting(SETTING_KEYS.REGISTRATION);
+    if (raw === null || raw === undefined)
+        return configDefault;
+    if (typeof raw !== 'object' || typeof raw.enabled !== 'boolean') {
+        return configDefault; // shape inválida → fallback
+    }
+    return raw.enabled;
+}
+/**
+ * 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 async function resolveEffectiveRequireVerifiedEmail(configDefault = false, settings) {
+    const raw = await settings.getSetting(SETTING_KEYS.REQUIRE_VERIFIED_EMAIL);
+    if (raw === null || raw === undefined)
+        return configDefault;
+    if (typeof raw !== 'object' || typeof raw.enabled !== 'boolean') {
+        return configDefault; // shape inválida → fallback
+    }
+    return raw.enabled;
+}
+/**
+ * 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 async function resolveEffectiveRequireVerifiedEmailFull(configDefault = false, settings) {
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.REQUIRE_VERIFIED_EMAIL);
+        if (raw === null || raw === undefined)
+            return { enabled: configDefault, graceDays: 0 };
+        if (typeof raw !== 'object' || typeof raw.enabled !== 'boolean') {
+            return { enabled: configDefault, graceDays: 0 };
+        }
+        const s = raw;
+        const graceDays = typeof s.graceDays === 'number' && s.graceDays >= 0 ? Math.floor(s.graceDays) : 0;
+        return { enabled: s.enabled, graceDays };
+    }
+    catch {
+        return { enabled: configDefault, graceDays: 0 };
+    }
+}
+/**
+ * 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 async function resolveEffectiveMaintenanceMode(settings) {
+    const raw = await settings.getSetting(SETTING_KEYS.MAINTENANCE_MODE);
+    if (raw === null || raw === undefined)
+        return { enabled: false };
+    if (typeof raw !== 'object' || typeof raw.enabled !== 'boolean') {
+        return { enabled: false }; // shape inválida → fail-safe
+    }
+    const setting = raw;
+    return {
+        enabled: setting.enabled,
+        message: typeof setting.message === 'string' ? setting.message : undefined,
+    };
+}
+/**
+ * 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 async function resolveEffectiveAuthMethods(settings, capabilities = {}) {
+    const { configuredSocialProviders = [], magicLinkCapable = false, passkeyCapable = false, } = capabilities;
+    // Defaults derivados do config/capabilities.
+    const configDefaults = {
+        password: true,
+        magicLink: magicLinkCapable,
+        passkey: passkeyCapable,
+        social: configuredSocialProviders,
+        forgotPassword: true,
+        passkeyAutofill: passkeyCapable, // on por default quando passkey disponível
+    };
+    const raw = await settings.getSetting(SETTING_KEYS.AUTH_METHODS);
+    if (raw === null || raw === undefined)
+        return configDefaults;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        return configDefaults; // shape inválida
+    const s = raw;
+    // Aplica campo a campo, com fallback ao default quando o campo está ausente.
+    const passwordEnabled = typeof s.password === 'boolean' ? s.password : configDefaults.password;
+    const magicLinkEnabled = typeof s.magicLink === 'boolean' ? s.magicLink : configDefaults.magicLink;
+    const passkeyEnabled = typeof s.passkey === 'boolean' ? s.passkey : configDefaults.passkey;
+    // Social: interseção com os providers do config (setting não pode ligar o que não existe).
+    let socialEnabled;
+    if (Array.isArray(s.social)) {
+        socialEnabled = s.social.filter((p) => configuredSocialProviders.includes(p));
+    }
+    else {
+        socialEnabled = configDefaults.social;
+    }
+    // forgotPassword: derivado automaticamente — sem senha NUNCA existe esqueci-senha.
+    const forgotPasswordEnabled = passwordEnabled && (typeof s.forgotPassword === 'boolean' ? s.forgotPassword : true);
+    // passkeyAutofill: só faz sentido quando passkey está ligado.
+    const passkeyAutofillEnabled = passkeyEnabled &&
+        (typeof s.passkeyAutofill === 'boolean' ? s.passkeyAutofill : configDefaults.passkeyAutofill);
+    const resolved = {
+        password: passwordEnabled,
+        magicLink: magicLinkEnabled,
+        passkey: passkeyEnabled,
+        social: socialEnabled,
+        forgotPassword: forgotPasswordEnabled,
+        passkeyAutofill: passkeyAutofillEnabled,
+    };
+    // FAIL-SAFE all-off: se todos ficaram false/vazio, volta ao config derivado.
+    const allOff = !resolved.password &&
+        !resolved.magicLink &&
+        !resolved.passkey &&
+        resolved.social.length === 0;
+    if (allOff) {
+        // eslint-disable-next-line no-console
+        console.warn('[authkit] auth_methods setting deixou todos os métodos desligados — ' +
+            'revertendo para os defaults do config (fail-safe). ' +
+            'Verifique a setting auth_methods no console admin.');
+        return configDefaults;
+    }
+    return resolved;
+}
+/**
+ * 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 async function resolveEffectiveEmailChange(settings) {
+    const defaults = { enabled: true, ttlHours: 24, requirePassword: true };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.EMAIL_CHANGE);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            ttlHours: typeof s.ttlHours === 'number' && s.ttlHours > 0 ? s.ttlHours : defaults.ttlHours,
+            requirePassword: typeof s.requirePassword === 'boolean' ? s.requirePassword : defaults.requirePassword,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/** Todos os tipos de notificação de segurança suportados. */
+export const ALL_SECURITY_NOTIFICATION_KINDS = [
+    'password_changed',
+    'mfa_enabled',
+    'mfa_disabled',
+    'passkey_added',
+    'passkey_removed',
+    'email_changed',
+];
+/**
+ * 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 async function resolveEffectiveSecurityNotifications(settings) {
+    const defaults = {
+        enabled: true,
+        kinds: [...ALL_SECURITY_NOTIFICATION_KINDS],
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.SECURITY_NOTIFICATIONS);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        const enabled = typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled;
+        let kinds;
+        if (Array.isArray(s.kinds) && s.kinds.length > 0) {
+            // Apenas aceita kinds válidos (interseção com os suportados).
+            kinds = s.kinds.filter((k) => ALL_SECURITY_NOTIFICATION_KINDS.includes(k));
+            if (kinds.length === 0)
+                kinds = [...ALL_SECURITY_NOTIFICATION_KINDS];
+        }
+        else {
+            kinds = [...ALL_SECURITY_NOTIFICATION_KINDS];
+        }
+        return { enabled, kinds };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * Resolve as configurações efetivas de histórico de senhas.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, count: 5 }`.
+ */
+export async function resolveEffectivePasswordHistory(settings) {
+    const defaults = { enabled: false, count: 5 };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.PASSWORD_HISTORY);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            count: typeof s.count === 'number' && s.count >= 1 ? Math.floor(s.count) : defaults.count,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/** Defaults da session_policy quando a setting não existe. */
+export const SESSION_POLICY_DEFAULTS = {
+    rememberEnabled: true,
+    rememberDays: 30,
+    defaultSessionHours: 168, // 7 dias em horas (= 604800 s padrão do oidc-provider)
+    singleSession: false,
+    idleTimeoutMinutes: 0,
+};
+/**
+ * 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 async function resolveEffectiveSessionPolicy(settings, configDefaultSessionHours) {
+    const defaults = {
+        ...SESSION_POLICY_DEFAULTS,
+        defaultSessionHours: configDefaultSessionHours ?? SESSION_POLICY_DEFAULTS.defaultSessionHours,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.SESSION_POLICY);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            rememberEnabled: typeof s.rememberEnabled === 'boolean' ? s.rememberEnabled : defaults.rememberEnabled,
+            rememberDays: typeof s.rememberDays === 'number' && s.rememberDays >= 1 ? Math.floor(s.rememberDays) : defaults.rememberDays,
+            defaultSessionHours: typeof s.defaultSessionHours === 'number' && s.defaultSessionHours >= 1 ? Math.floor(s.defaultSessionHours) : defaults.defaultSessionHours,
+            singleSession: typeof s.singleSession === 'boolean' ? s.singleSession : defaults.singleSession,
+            idleTimeoutMinutes: typeof s.idleTimeoutMinutes === 'number' && s.idleTimeoutMinutes >= 0 ? Math.floor(s.idleTimeoutMinutes) : defaults.idleTimeoutMinutes,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * Resolve as configurações efetivas de expiração de senha.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, maxAgeDays: 90 }`.
+ */
+export async function resolveEffectivePasswordExpiration(settings) {
+    const defaults = { enabled: false, maxAgeDays: 90 };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.PASSWORD_EXPIRATION);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            maxAgeDays: typeof s.maxAgeDays === 'number' && s.maxAgeDays >= 1 ? Math.floor(s.maxAgeDays) : defaults.maxAgeDays,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+const LOCKOUT_LIB_DEFAULTS = {
+    enabled: true,
+    maxAttempts: 5,
+    windowSec: 900,
+    baseLockoutSec: 60,
+    maxLockoutSec: 3600,
+};
+/**
+ * Resolve as configurações efetivas de lockout.
+ *
+ * Precedência: setting BD → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault (ou lib defaults).
+ */
+export async function resolveEffectiveLockout(settings, configDefault = {}) {
+    const defaults = {
+        enabled: configDefault.enabled ?? LOCKOUT_LIB_DEFAULTS.enabled,
+        maxAttempts: configDefault.maxAttempts ?? LOCKOUT_LIB_DEFAULTS.maxAttempts,
+        windowSec: configDefault.windowSec ?? LOCKOUT_LIB_DEFAULTS.windowSec,
+        baseLockoutSec: configDefault.baseLockoutSec ?? LOCKOUT_LIB_DEFAULTS.baseLockoutSec,
+        maxLockoutSec: configDefault.maxLockoutSec ?? LOCKOUT_LIB_DEFAULTS.maxLockoutSec,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.LOCKOUT);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            maxAttempts: typeof s.maxAttempts === 'number' && s.maxAttempts >= 1 ? Math.floor(s.maxAttempts) : defaults.maxAttempts,
+            windowSec: typeof s.windowSec === 'number' && s.windowSec >= 1 ? Math.floor(s.windowSec) : defaults.windowSec,
+            baseLockoutSec: typeof s.baseLockoutSec === 'number' && s.baseLockoutSec >= 1 ? Math.floor(s.baseLockoutSec) : defaults.baseLockoutSec,
+            maxLockoutSec: typeof s.maxLockoutSec === 'number' && s.maxLockoutSec >= 1 ? Math.floor(s.maxLockoutSec) : defaults.maxLockoutSec,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+const RATE_LIMIT_LIB_DEFAULTS = {
+    login: { points: 10, duration: '1 min' },
+    introspection: { points: 60, duration: '1 min' },
+};
+/**
+ * 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 async function resolveEffectiveRateLimit(settings, configDefault = {}) {
+    const defaults = {
+        login: {
+            points: configDefault.login?.points ?? RATE_LIMIT_LIB_DEFAULTS.login.points,
+            duration: configDefault.login?.duration ?? RATE_LIMIT_LIB_DEFAULTS.login.duration,
+        },
+        introspection: {
+            points: configDefault.introspection?.points ?? RATE_LIMIT_LIB_DEFAULTS.introspection.points,
+            duration: configDefault.introspection?.duration ?? RATE_LIMIT_LIB_DEFAULTS.introspection.duration,
+        },
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.RATE_LIMIT);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            login: {
+                points: typeof s.login?.points === 'number' && s.login.points >= 1 ? Math.floor(s.login.points) : defaults.login.points,
+                duration: typeof s.login?.duration === 'string' && s.login.duration.trim() ? s.login.duration.trim() : defaults.login.duration,
+            },
+            introspection: {
+                points: typeof s.introspection?.points === 'number' && s.introspection.points >= 1 ? Math.floor(s.introspection.points) : defaults.introspection.points,
+                duration: typeof s.introspection?.duration === 'string' && s.introspection.duration.trim() ? s.introspection.duration.trim() : defaults.introspection.duration,
+            },
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+const PASSWORD_POLICY_LIB_DEFAULTS = {
+    minLength: 8,
+    requireUppercase: false,
+    requireLowercase: false,
+    requireNumbers: false,
+    requireSymbols: false,
+    checkPwned: false,
+    blockCommon: true,
+};
+/**
+ * Resolve as configurações efetivas de política de senha.
+ *
+ * Precedência: setting BD → configDefault → lib default.
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export async function resolveEffectivePasswordPolicy(settings, configDefault = {}) {
+    const defaults = {
+        minLength: configDefault.minLength ?? PASSWORD_POLICY_LIB_DEFAULTS.minLength,
+        requireUppercase: configDefault.requireUppercase ?? PASSWORD_POLICY_LIB_DEFAULTS.requireUppercase,
+        requireLowercase: configDefault.requireLowercase ?? PASSWORD_POLICY_LIB_DEFAULTS.requireLowercase,
+        requireNumbers: configDefault.requireNumbers ?? PASSWORD_POLICY_LIB_DEFAULTS.requireNumbers,
+        requireSymbols: configDefault.requireSymbols ?? PASSWORD_POLICY_LIB_DEFAULTS.requireSymbols,
+        checkPwned: configDefault.checkPwned ?? PASSWORD_POLICY_LIB_DEFAULTS.checkPwned,
+        blockCommon: configDefault.blockCommon ?? PASSWORD_POLICY_LIB_DEFAULTS.blockCommon,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.PASSWORD_POLICY);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            minLength: typeof s.minLength === 'number' && s.minLength >= 1 ? Math.floor(s.minLength) : defaults.minLength,
+            requireUppercase: typeof s.requireUppercase === 'boolean' ? s.requireUppercase : defaults.requireUppercase,
+            requireLowercase: typeof s.requireLowercase === 'boolean' ? s.requireLowercase : defaults.requireLowercase,
+            requireNumbers: typeof s.requireNumbers === 'boolean' ? s.requireNumbers : defaults.requireNumbers,
+            requireSymbols: typeof s.requireSymbols === 'boolean' ? s.requireSymbols : defaults.requireSymbols,
+            checkPwned: typeof s.checkPwned === 'boolean' ? s.checkPwned : defaults.checkPwned,
+            blockCommon: typeof s.blockCommon === 'boolean' ? s.blockCommon : defaults.blockCommon,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * 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 async function resolveEffectiveNotifications(settings, configDefault = {}) {
+    const defaults = {
+        newLoginEmail: configDefault.newLoginEmail ?? true,
+        newDeviceEmail: configDefault.newDeviceEmail ?? true,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.NOTIFICATIONS);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            newLoginEmail: typeof s.newLoginEmail === 'boolean' ? s.newLoginEmail : defaults.newLoginEmail,
+            newDeviceEmail: typeof s.newDeviceEmail === 'boolean' ? s.newDeviceEmail : defaults.newDeviceEmail,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * 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 async function resolveEffectiveTrustedDevices(settings, configDefault = {}) {
+    const defaults = {
+        enabled: configDefault.enabled ?? true,
+        days: configDefault.days ?? 30,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.TRUSTED_DEVICES);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            days: typeof s.days === 'number' && s.days >= 1 ? Math.floor(s.days) : defaults.days,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * 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 async function resolveEffectiveTokenTtl(settings, configDefault = {}) {
+    const defaults = {
+        accessTokenSec: configDefault.accessTokenSec ?? 900,
+        idTokenSec: configDefault.idTokenSec ?? 900,
+        refreshTokenSec: configDefault.refreshTokenSec ?? 2592000,
+    };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.TOKEN_TTL);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            accessTokenSec: typeof s.accessTokenSec === 'number' && s.accessTokenSec >= 1 ? Math.floor(s.accessTokenSec) : defaults.accessTokenSec,
+            idTokenSec: typeof s.idTokenSec === 'number' && s.idTokenSec >= 1 ? Math.floor(s.idTokenSec) : defaults.idTokenSec,
+            refreshTokenSec: typeof s.refreshTokenSec === 'number' && s.refreshTokenSec >= 1 ? Math.floor(s.refreshTokenSec) : defaults.refreshTokenSec,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * Resolve as configurações efetivas de impersonation.
+ *
+ * Precedência: setting BD → configDefault → lib default (false).
+ * FAIL-SAFE: qualquer erro → configDefault.
+ */
+export async function resolveEffectiveAdminImpersonation(settings, configDefault = false) {
+    const defaults = { enabled: configDefault };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.ADMIN_IMPERSONATION);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+const ORGS_POLICY_LIB_DEFAULTS = {
+    allowSelfCreate: false,
+    invitationTtlHours: 168,
+    roles: ['owner', 'admin', 'member'],
+};
+/** Default da lib: apenas ADMIN. */
+export const ROLES_CATALOG_DEFAULT = {
+    roles: [{ name: 'ADMIN', description: 'Full access to the admin console' }],
+};
+/**
+ * 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 async function resolveEffectiveRolesCatalog(settings, orgId) {
+    async function fromRaw(raw) {
+        if (raw === null || raw === undefined)
+            return null;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return null;
+        const s = raw;
+        if (!Array.isArray(s.roles))
+            return null;
+        // Filtra entradas válidas (name deve ser string não-vazia).
+        const entries = s.roles
+            .filter((r) => typeof r === 'object' && r !== null && typeof r.name === 'string' && r.name.trim().length > 0)
+            .map((r) => ({
+            name: r.name.trim(),
+            ...(typeof r.description === 'string' && r.description.trim().length > 0
+                ? { description: r.description.trim() }
+                : {}),
+        }));
+        // Merge defensivo: ADMIN sempre presente.
+        const hasAdmin = entries.some((r) => r.name === 'ADMIN');
+        if (!hasAdmin) {
+            entries.unshift({ name: 'ADMIN', description: 'Full access to the admin console' });
+        }
+        // Ordena por nome.
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        return { roles: entries };
+    }
+    try {
+        // Resolução org → global → default
+        if (orgId) {
+            const orgRaw = await settings.getSetting(SETTING_KEYS.ROLES_CATALOG, orgId);
+            const orgResult = await fromRaw(orgRaw);
+            if (orgResult)
+                return orgResult;
+        }
+        const globalRaw = await settings.getSetting(SETTING_KEYS.ROLES_CATALOG, null);
+        const globalResult = await fromRaw(globalRaw);
+        if (globalResult)
+            return globalResult;
+        return ROLES_CATALOG_DEFAULT;
+    }
+    catch {
+        return ROLES_CATALOG_DEFAULT;
+    }
+}
+/**
+ * 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 async function resolveEffectiveOrganizationsPolicy(settings, configDefault = {}, orgId) {
+    const defaultRoles = configDefault.roles ?? ORGS_POLICY_LIB_DEFAULTS.roles;
+    const rolesWithOwner = defaultRoles.includes('owner') ? defaultRoles : ['owner', ...defaultRoles];
+    const defaults = {
+        allowSelfCreate: configDefault.allowSelfCreate ?? ORGS_POLICY_LIB_DEFAULTS.allowSelfCreate,
+        invitationTtlHours: configDefault.invitationTtlHours ?? ORGS_POLICY_LIB_DEFAULTS.invitationTtlHours,
+        roles: rolesWithOwner,
+    };
+    function applyRaw(raw) {
+        if (raw === null || raw === undefined)
+            return null;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return null;
+        const s = raw;
+        // Roles: usa o valor da setting apenas se for um array não-vazio; sempre
+        // garante que 'owner' está presente (invariante de governance).
+        let roles = defaults.roles;
+        if (Array.isArray(s.roles) && s.roles.length > 0) {
+            roles = s.roles.includes('owner') ? s.roles : ['owner', ...s.roles];
+        }
+        return {
+            allowSelfCreate: typeof s.allowSelfCreate === 'boolean' ? s.allowSelfCreate : defaults.allowSelfCreate,
+            invitationTtlHours: typeof s.invitationTtlHours === 'number' && s.invitationTtlHours >= 1 ? Math.floor(s.invitationTtlHours) : defaults.invitationTtlHours,
+            roles,
+        };
+    }
+    try {
+        // Resolução org → global → defaults
+        if (orgId) {
+            const orgRaw = await settings.getSetting(SETTING_KEYS.ORGANIZATIONS_POLICY, orgId);
+            const orgResult = applyRaw(orgRaw);
+            if (orgResult)
+                return orgResult;
+        }
+        const globalRaw = await settings.getSetting(SETTING_KEYS.ORGANIZATIONS_POLICY, null);
+        const globalResult = applyRaw(globalRaw);
+        if (globalResult)
+            return globalResult;
+        return defaults;
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * 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 async function resolveRoleCatalogList(settings, configDefault = {}, orgId) {
+    if (!settings) {
+        const roles = configDefault.roles ?? ORGS_POLICY_LIB_DEFAULTS.roles;
+        return roles.includes('owner') ? roles : ['owner', ...roles];
+    }
+    const policy = await resolveEffectiveOrganizationsPolicy(settings, configDefault, orgId);
+    return policy.roles;
+}
+/**
+ * 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 async function isRoleInCatalog(role, settings, configDefault = {}, orgId) {
+    const catalog = await resolveRoleCatalogList(settings, configDefault, orgId);
+    return catalog.includes(role);
+}
+/**
+ * Resolve as configurações efetivas de expiração de conta.
+ *
+ * FAIL-SAFE: qualquer erro → `{ enabled: false, inactiveDays: 365, warnDays: 14 }`.
+ */
+export async function resolveEffectiveAccountExpiration(settings) {
+    const defaults = { enabled: false, inactiveDays: 365, warnDays: 14 };
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.ACCOUNT_EXPIRATION);
+        if (raw === null || raw === undefined)
+            return defaults;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return defaults;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : defaults.enabled,
+            inactiveDays: typeof s.inactiveDays === 'number' && s.inactiveDays >= 1 ? Math.floor(s.inactiveDays) : defaults.inactiveDays,
+            warnDays: typeof s.warnDays === 'number' && s.warnDays >= 0 ? Math.floor(s.warnDays) : defaults.warnDays,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}