@adonis-agora/authkit-server 0.34.0

package/build/src/define_config.js

@@ -0,0 +1,351 @@
+import { configProvider } from "@adonisjs/core";
+import { generateJwks } from "./keys/jwks_manager.js";
+import { KeystoreManager, resolveKeystoreVault, } from "./keys/keystore_manager.js";
+import { KeystoreCodec } from "./keys/keystore_codec.js";
+import { loadEncryptionService } from "./keys/keystore_crypto.js";
+import { adapters, } from "./adapters/factory.js";
+import { composeAuditSink, resolveEvents, } from "./events/dispatcher.js";
+import { resolveMessages, } from "./host/i18n.js";
+import { resolveTrustedDevices, } from "./host/trusted_device.js";
+import { resolveBotProtection, } from "./host/bot_protection.js";
+import { deriveLockedSettingKeys } from "./host/config_locks.js";
+export { adapters };
+const RATE_LIMIT_DEFAULTS = {
+    login: { points: 10, duration: "1 min" },
+    introspection: { points: 60, duration: "1 min" },
+    adminIp: { points: 30, duration: "1 min" },
+};
+export function resolveRateLimit(input) {
+    const enabled = input?.enabled ?? true;
+    return {
+        enabled,
+        login: RATE_LIMIT_DEFAULTS.login,
+        introspection: RATE_LIMIT_DEFAULTS.introspection,
+        adminIp: RATE_LIMIT_DEFAULTS.adminIp,
+        store: input?.store,
+    };
+}
+export function resolveLockout(input) {
+    return {
+        enabled: true,
+        maxAttempts: 5,
+        windowSec: 900,
+        baseLockoutSec: 60,
+        maxLockoutSec: 3600,
+        store: input?.store,
+    };
+}
+export function resolveNotifications() {
+    return {
+        newLoginEmail: true,
+        newDeviceEmail: true,
+    };
+}
+/**
+ * Resolve a config de registro dinâmico e VALIDA invariantes em tempo de resolução.
+ * O Registration Management (RFC 7592) só faz sentido com o registro habilitado
+ * (RFC 7591) — `management: true` com `enabled: false` é um erro de configuração.
+ */
+export function resolveDynamicRegistration(input) {
+    const enabled = input?.enabled ?? false;
+    const management = input?.management ?? false;
+    if (management && !enabled) {
+        throw new Error("authkit: dynamicRegistration.management (RFC 7592) requer " +
+            "dynamicRegistration.enabled: true (RFC 7591). Habilite o registro dinâmico " +
+            "ou desligue o management.");
+    }
+    return {
+        enabled,
+        initialAccessToken: input?.initialAccessToken,
+        management,
+    };
+}
+export function resolveDeviceFlow(input) {
+    return { enabled: input?.enabled ?? false };
+}
+export function resolveUploads(input) {
+    return {
+        avatars: {
+            disk: input?.avatars?.disk,
+            directory: input?.avatars?.directory ?? "authkit/avatars",
+            maxSizeMb: input?.avatars?.maxSizeMb ?? 5,
+        },
+    };
+}
+export function resolveDpop(input) {
+    return { enabled: input?.enabled ?? false };
+}
+export function resolvePar(input) {
+    return {
+        enabled: input?.enabled ?? false,
+        requirePushedAuthorizationRequests: input?.requirePushedAuthorizationRequests ?? false,
+    };
+}
+export function resolveStepUp(input) {
+    const mfaAcr = input?.mfaAcr ?? "urn:authkit:mfa";
+    // Garante que o mfaAcr esteja sempre na lista anunciada como suportada.
+    const acrValues = Array.from(new Set([...(input?.acrValues ?? []), mfaAcr]));
+    return { acrValues, mfaAcr };
+}
+export function resolvePasswordless(input) {
+    return {
+        magicLink: input?.magicLink ?? false,
+        passkeyFirst: input?.passkeyFirst ?? false,
+    };
+}
+export function resolveLogin(input) {
+    return {
+        requireVerifiedEmail: input?.requireVerifiedEmail ?? false,
+    };
+}
+export function resolveRegistration(input) {
+    return {
+        enabled: input?.enabled ?? true,
+    };
+}
+/**
+ * Resolve a config de access tokens. No modo simples (`format: 'jwt'` sem
+ * `resources`), o `audience` default vira o próprio issuer e materializamos uma
+ * resource implícita com essa URI para que o oidc-provider emita o JWT (um JWT AT
+ * SEMPRE exige um resource indicator com `aud`). Cada entrada de `resources`
+ * herda o `format` raiz quando não especifica o seu.
+ */
+export function resolveAccessTokens(issuer, input) {
+    const format = input?.format ?? "opaque";
+    const audience = input?.audience ?? issuer;
+    const resources = {};
+    for (const [indicator, rc] of Object.entries(input?.resources ?? {})) {
+        resources[indicator] = {
+            audience: rc.audience ?? indicator,
+            scopes: rc.scopes,
+            format: rc.format ?? format,
+            expiresIn: rc.expiresIn,
+        };
+    }
+    const anyResourceJwt = Object.values(resources).some((r) => r.format === "jwt");
+    const anyJwt = format === "jwt" || anyResourceJwt;
+    return { format, audience, anyJwt, resources };
+}
+export function resolveAdmin(input) {
+    return {
+        enabled: input?.enabled ?? false,
+        roles: input?.roles && input.roles.length > 0 ? input.roles : ["ADMIN"],
+        impersonation: false,
+    };
+}
+/** Lê API keys de `AUTHKIT_ADMIN_API_KEY` (uma ou várias, separadas por vírgula). */
+function adminApiKeysFromEnv() {
+    return (process.env.AUTHKIT_ADMIN_API_KEY ?? "")
+        .split(",")
+        .map((key) => key.trim())
+        .filter(Boolean);
+}
+export function resolveAdminApi(input) {
+    const apiKeys = input?.apiKeys === "env" ? adminApiKeysFromEnv() : (input?.apiKeys ?? []);
+    return {
+        // Default inteligente: liga quando há key resolvida (a menos que enabled:false explícito).
+        enabled: input?.enabled ?? apiKeys.length > 0,
+        apiKeys,
+    };
+}
+export function resolveOrganizations(input) {
+    return {
+        enabled: input?.enabled,
+        roles: ["owner", "admin", "member"],
+        allowSelfCreate: false,
+        invitationTtlHours: 168,
+        claimStrategy: input?.claimStrategy ?? "active",
+    };
+}
+/**
+ * Resolve os parâmetros do RP de WebAuthn a partir do `issuer` quando omitidos.
+ * `rpName` cai no `fallbackName` (branding/mfaIssuer) quando ausente.
+ */
+export function resolveWebauthn(issuer, fallbackName, input) {
+    let host = "localhost";
+    let origin = "http://localhost";
+    try {
+        const url = new URL(issuer);
+        host = url.hostname;
+        origin = url.origin;
+    }
+    catch {
+        // issuer inválido → mantém defaults de localhost (dev).
+    }
+    return {
+        rpName: input?.rpName ?? fallbackName,
+        rpId: input?.rpId ?? host,
+        origin: input?.origin ?? origin,
+    };
+}
+const UNITS = { s: 1, m: 60, h: 3600, d: 86400 };
+export function toSeconds(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === "number")
+        return value;
+    const m = /^(\d+)\s*([smhd])$/.exec(value.trim());
+    if (!m)
+        throw new Error(`TTL inválido: ${value}`);
+    return Number(m[1]) * UNITS[m[2]];
+}
+/**
+ * Default backend-aware de encryption: file/drive/lucid/redis ON; vaults reais OFF.
+ * Evita gravar chaves privadas em texto claro em stores que não gerenciam segredos
+ * (blobs burros). Vaults reais (aws-secrets-manager, etc.) cuidam da criptografia
+ * internamente — encrypt OFF para não duplo-encriptar.
+ */
+export function defaultEncryptForStore(store) {
+    if (typeof store === "string")
+        return true;
+    return ["file", "drive", "lucid", "redis"].includes(store.driver);
+}
+/**
+ * Mensagem de aviso quando `jwks: 'auto'` cai no fallback de disco (sem
+ * AUTHKIT_JWKS): a chave privada será persistida em arquivo. `null` = sem aviso.
+ */
+export function jwksAutoFallbackWarning(storePath) {
+    if (!storePath)
+        return null;
+    return (`AuthKit: jwks 'auto' caiu no fallback de disco (${storePath}) — a chave privada de ` +
+        `assinatura será persistida em arquivo. Para produção, defina AUTHKIT_JWKS ` +
+        `(secret manager) ou configure jwks.store explicitamente.`);
+}
+export function defineConfig(config) {
+    return configProvider.create(async (app) => {
+        const AdapterClass = await config.adapter.resolver(app);
+        // `jwks: 'auto'` → resolve env-aware: AUTHKIT_JWKS inline, senão managed em arquivo.
+        const jwksConfig = config.jwks === "auto"
+            ? process.env.AUTHKIT_JWKS
+                ? {
+                    source: "jwks",
+                    keys: JSON.parse(process.env.AUTHKIT_JWKS).keys,
+                }
+                : {
+                    source: "managed",
+                    algorithm: "RS256",
+                    store: "tmp/authkit_jwks.json",
+                }
+            : config.jwks;
+        if (config.jwks === "auto" && !process.env.AUTHKIT_JWKS) {
+            const warning = jwksAutoFallbackWarning(jwksConfig.store ?? null);
+            if (warning) {
+                await app.container
+                    .make("logger")
+                    .then((l) => l?.warn(warning))
+                    .catch(() => { });
+            }
+        }
+        const storeCfg = jwksConfig.store;
+        if (jwksConfig.source === "managed" &&
+            storeCfg &&
+            typeof storeCfg === "object" &&
+            storeCfg.driver === "redis") {
+            await app.container
+                .make("logger")
+                .then((l) => l?.warn('AuthKit: keystore no driver "redis" — garanta PERSISTÊNCIA (RDB/AOF). Num Redis cache-only, um flush apaga o keystore e invalida todos os tokens.'))
+                .catch(() => { });
+        }
+        let jwks;
+        if (jwksConfig.source === "managed") {
+            const alg = jwksConfig.algorithm ?? "RS256";
+            if (jwksConfig.store) {
+                const vault = resolveKeystoreVault(jwksConfig.store, {
+                    makePath: (p) => app.makePath(p),
+                    container: app.container,
+                });
+                const encrypt = jwksConfig.encrypt ??
+                    defaultEncryptForStore(jwksConfig.store);
+                const enc = encrypt ? await loadEncryptionService() : undefined;
+                const manager = new KeystoreManager(vault, new KeystoreCodec({ encrypt, enc }), alg);
+                const store = await manager.ensure();
+                // Remove o metadado interno `iat` antes de entregar ao oidc-provider.
+                jwks = { keys: store.keys.map(({ iat: _iat, ...jwk }) => jwk) };
+            }
+            else {
+                jwks = await generateJwks(alg);
+            }
+        }
+        else {
+            jwks = { keys: jwksConfig.keys ?? [] };
+        }
+        // #9: mfaIssuer efetivo — top-level do defineConfig vence; senão o do lucidAccountStore; senão default.
+        const effectiveMfaIssuer = config.mfaIssuer ??
+            config.accountStore?.__mfaIssuer ??
+            "AuthKit";
+        return {
+            issuer: config.issuer,
+            AdapterClass,
+            clients: config.clients ?? [],
+            jwks: jwks,
+            jwksConfig,
+            ttl: {
+                accessToken: toSeconds(config.ttl?.accessToken, 900),
+                refreshToken: toSeconds(config.ttl?.refreshToken, 2592000),
+                idToken: toSeconds(config.ttl?.idToken, 900),
+                session: toSeconds(config.ttl?.session, 604800),
+            },
+            globalRolesClaim: config.globalRolesClaim ?? "roles",
+            cookieKeys: config.cookieKeys ?? [],
+            observability: config.observability ?? {},
+            findAccount: (sub) => config.accountStore.findById(sub),
+            verifyCredentials: async (email, password) => {
+                const acc = await config.accountStore.verifyCredentials(email, password);
+                return acc ? { id: acc.id } : null;
+            },
+            accountStore: config.accountStore,
+            patStore: config.patStore,
+            mountPath: config.mountPath ?? "/oidc",
+            render: config.render,
+            branding: config.branding,
+            social: config.social,
+            patIntrospectionSecret: config.patIntrospectionSecret,
+            rateLimit: resolveRateLimit(config.rateLimit),
+            lockout: resolveLockout(config.lockout),
+            notifications: resolveNotifications(),
+            mail: config.mail,
+            audit: (() => {
+                // Sempre compõe o fan-out: além de onEvent/webhook (quando configurados),
+                // o sink composto republica TODO evento de auditoria no barramento de
+                // diagnostics do Agora (best-effort, zero-config, no-op sem o slot).
+                const events = resolveEvents(config.events);
+                return composeAuditSink(config.audit, events ?? {});
+            })(),
+            // #9: reusa mfaIssuer/webauthn declarados no lucidAccountStore quando o
+            // top-level não os fornece — consumidor declara UMA vez. Top-level ainda vence.
+            mfaIssuer: effectiveMfaIssuer,
+            webauthn: resolveWebauthn(config.issuer, effectiveMfaIssuer, config.webauthn ??
+                config.accountStore
+                    ?.__webauthn),
+            dynamicRegistration: resolveDynamicRegistration(config.dynamicRegistration),
+            deviceFlow: resolveDeviceFlow(config.deviceFlow),
+            uploads: resolveUploads(config.uploads),
+            dpop: resolveDpop(config.dpop),
+            par: resolvePar(config.par),
+            stepUp: resolveStepUp(config.stepUp),
+            trustedDevices: resolveTrustedDevices(config.trustedDevices),
+            botProtection: resolveBotProtection(config.botProtection),
+            passwordless: resolvePasswordless(config.passwordless),
+            login: resolveLogin(config.login),
+            registration: resolveRegistration(config.registration),
+            accessTokens: resolveAccessTokens(config.issuer, config.accessTokens),
+            admin: resolveAdmin(config.admin),
+            adminApi: resolveAdminApi(config.adminApi),
+            organizations: resolveOrganizations(config.organizations),
+            resolveGeo: config.resolveGeo,
+            messages: resolveMessages(config.i18n),
+            locale: config.i18n?.locale ?? "pt-BR",
+            schema: {
+                autoManage: config.schema?.autoManage !== false,
+                connection: config.schema?.connection,
+            },
+            // OPT-IN: default false → caminho síncrono de sempre (byte-idêntico).
+            accountLifecycle: {
+                durable: config.accountLifecycle?.durable === true,
+            },
+            // Keys de auth_settings travadas porque foram definidas no defineConfig:
+            // config vence e a UI/Admin API não pode alterá-las (ver host/config_locks.ts).
+            lockedSettingKeys: deriveLockedSettingKeys(config),
+        };
+    });
+}

package/build/src/doctor/checks.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Funções puras de verificação para `node ace authkit:doctor`. Não dependem do
+ * Ace nem do container — recebem objetos simples para serem testáveis em
+ * isolamento. O comando `authkit:doctor` só coleta o ambiente e imprime os
+ * resultados destas funções.
+ */
+export type FindingLevel = 'ok' | 'warn' | 'error';
+export interface Finding {
+    level: FindingLevel;
+    message: string;
+}
+/** Entrada mínima necessária para rodar os checks (subconjunto da config AuthKit). */
+export interface DoctorInput {
+    /** A config `authkit` resolvida pelo container, ou null se não resolver. */
+    authkitConfig: Record<string, any> | null;
+    /** A config `session` do app (config('session')), ou null se ausente. */
+    sessionConfig: Record<string, any> | null;
+    /** Resultado de tentar resolver cada peer (true = importável). */
+    peers: {
+        session: boolean;
+        shield: boolean;
+        ally: boolean;
+        limiter: boolean;
+    };
+    /**
+     * Whether the `auth_settings` table is present (runtime settings capability).
+     * Provided by the doctor command; undefined = not checked (doctor runs old version).
+     */
+    settingsTablePresent?: boolean;
+    /**
+     * Classes de adapter para detecção de volatilidade (injetadas pelo doctor command
+     * em runtime). Quando ausente, o check de volatilidade usa heurística conservadora.
+     * Uso interno — não deve ser definido pelo host.
+     */
+    __adapterClasses?: {
+        DatabaseAdapter?: new (...args: any[]) => any;
+    };
+}
+/** config('authkit') resolve? */
+export declare function checkConfigResolves(input: DoctorInput): Finding;
+/** issuer é uma URL válida e seu pathname casa com o mountPath. */
+export declare function checkIssuer(input: DoctorInput): Finding[];
+/**
+ * Clients: verifica que não há clients estáticos no config (clients são 100%
+ * runtime via console admin / Admin API).
+ */
+export declare function checkClients(input: DoctorInput): Finding;
+/**
+ * Aviso de adapter volátil. Como clients são 100% runtime (sem config estático),
+ * um adapter volátil (Redis sem persistência, in-memory) pode perder os clients
+ * num restart sem aviso prévio.
+ *
+ * Detecção de volatilidade: o `AdapterClass` é inspecionado estruturalmente:
+ *   - `DatabaseAdapter` (ou subclasse) → persistente (sem warn)
+ *   - qualquer outra classe → pode ser volátil → warn informativo
+ */
+export declare function checkAdapterVolatility(input: DoctorInput): Finding | null;
+/** accountStore presente + quais capacidades implementa. */
+export declare function checkAccountStore(input: DoctorInput): Finding[];
+/** session provider configurado + warn se cookie store com tokenSets grandes. */
+export declare function checkSession(input: DoctorInput): Finding[];
+/** Hint de exceções de CSRF do shield para o mountPath. */
+export declare function checkShield(input: DoctorInput): Finding;
+/** ally só é necessário quando social está configurado. */
+export declare function checkAlly(input: DoctorInput): Finding;
+/**
+ * OTP lockout: informativa. Avisa quando enabled mas limiter ausente (no-op).
+ * Não emite nada quando OTP lockout está desligado por setting (runtime).
+ */
+export declare function checkOtpLockout(input: DoctorInput): Finding | null;
+/**
+ * Sudo mode: informativa. O sudo mode requer sessões Adonis (sempre disponíveis
+ * no console de conta). Apenas informa o estado.
+ */
+export declare function checkSudoMode(_input: DoctorInput): Finding | null;
+/** rateLimit ligado mas @adonisjs/limiter ausente → warn. */
+export declare function checkRateLimit(input: DoctorInput): Finding;
+/** admin.enabled mas sem roles → warn. Reporta o modo de UI ativo. */
+export declare function checkAdmin(input: DoctorInput): Finding | null;
+/** requireVerifiedEmail ligado mas o store não sabe checar verificação → warn. */
+export declare function checkRequireVerifiedEmail(input: DoctorInput): Finding | null;
+/**
+ * Bot protection (informativo): ativo quando `botProtection.verify` é uma função.
+ * Reporta em quais ações está ligado e lembra da semântica fail-safe. Silencioso
+ * quando não configurado.
+ */
+export declare function checkBotProtection(input: DoctorInput): Finding | null;
+/** webauthn rpId deve casar com o host do issuer. */
+export declare function checkWebauthn(input: DoctorInput): Finding | null;
+/**
+ * Política de senha + checagem de vazamento (config do accountStore — opção
+ * `password`). Valida o shape da policy e informa quando o HIBP está ligado. A
+ * config vive no store (não no nível raiz da config authkit), então lemos de
+ * `accountStore` quando o host a expõe via `__passwordConfig` (best-effort) — na
+ * ausência, este check é silencioso (não falha).
+ */
+export declare function checkPasswordPolicy(input: DoctorInput): Finding | null;
+/** info sobre rotação quando jwks é managed; warn se managed sem store (sem rotação real). */
+export declare function checkJwks(input: DoctorInput): Finding | null;
+/**
+ * Formato dos Access Tokens (RFC 9068). Informa o formato configurado e, no modo
+ * JWT, lembra que o JWKS precisa ser estável (store persistido) para que os RPs
+ * validem os ATs via jwks_uri através de reinícios/rotação.
+ */
+export declare function checkAccessTokens(input: DoctorInput): Finding | null;
+/**
+ * Organizations (multi-tenancy). Informa se a capacidade está disponível
+ * (store expõe createOrg) e avisa se `organizations.enabled: true` no config mas
+ * a capacidade não está presente no store (organizationModels não foram passados).
+ */
+export declare function checkOrganizations(input: DoctorInput): Finding | null;
+/**
+ * Runtime settings: informa se a tabela `auth_settings` está presente.
+ * Quando ausente, é silencioso (a feature é opt-in). Quando presente mas
+ * `botProtection.verify` NÃO está no config, alerta que a setting em banco
+ * é órfã e não tem efeito.
+ */
+export declare function checkSettings(input: DoctorInput): Finding | null;
+/**
+ * auth_methods setting: verifica se o valor persistido tem forma válida.
+ * O input `authMethodsSetting` é injetado pelo doctor command quando a tabela
+ * está presente — similar ao padrão do checkSettings mas focado na setting específica.
+ *
+ * Warns quando:
+ *   - Todos os métodos estão desligados (fail-safe será acionado em runtime).
+ *   - A lista `social` referencia um provider não presente em `config.social.providers`.
+ */
+export declare function checkAuthMethodsSetting(input: DoctorInput): Finding | null;
+/**
+ * Verifica se o fluxo de troca de e-mail verificada está disponível.
+ * Reporta se o store suporta a capability de security (requestEmailChange/confirmEmailChange).
+ */
+export declare function checkEmailChange(input: DoctorInput): Finding | null;
+/**
+ * Verifica a capability de notificações de segurança:
+ * - mail configurado (para envio dos alertas)
+ * - store com suporte a AccountSecurityCapability
+ */
+export declare function checkSecurityNotifications(input: DoctorInput): Finding | null;
+/**
+ * Verifica a capability de histórico de senhas.
+ * - Informa se a tabela `auth_password_history` está presente.
+ * - Avisa quando pepper está configurado como string (não array) — rotation recomendada.
+ */
+export declare function checkPasswordPepper(input: DoctorInput): Finding | null;
+/**
+ * Verifica a capability de histórico de senhas (disallow_password_reuse).
+ * Informa se a tabela `auth_password_history` está presente e a capability está disponível.
+ * Avisa quando a setting está ligada mas a capability não está presente.
+ */
+export declare function checkPasswordHistory(input: DoctorInput): Finding | null;
+/**
+ * Verifica a capability de expiração de senha.
+ * Informa se a coluna `password_changed_at` está presente. Avisa quando a setting
+ * está ligada mas a coluna não existe.
+ */
+export declare function checkPasswordExpiration(input: DoctorInput): Finding | null;
+/**
+ * Verifica a setting `session_policy` para valores absurdos ou inconsistentes.
+ *
+ * Checks:
+ *   - idleTimeoutMinutes > defaultSessionHours*60: idle timeout nunca irá disparar.
+ *   - rememberDays > 365: incomumente longo (warn).
+ *   - idleTimeoutMinutes > 0 mas defaultSessionHours = 0: impossível (error).
+ */
+export declare function checkSessionPolicy(input: DoctorInput): Finding | null;
+/**
+ * Verifica o catálogo de roles globais (informativo).
+ *
+ * Checks:
+ *   - Informa o número de roles no catálogo quando a setting está presente.
+ *   - Avisa se `cfg.admin.roles` contém role(s) fora do catálogo (o gate do console
+ *     pode não funcionar como esperado se a role não existir no catálogo).
+ */
+export declare function checkRolesCatalog(input: DoctorInput): Finding | null;
+/**
+ * Verifica a feature de expiração de conta por inatividade.
+ *
+ * - Capability-probed: sem audit com `list` → a feature fica indisponível; explica o motivo.
+ * - Quando a setting `account_expiration` está presente, valida a coerência dos campos.
+ */
+export declare function checkAccountExpiration(input: DoctorInput): Finding | null;
+/**
+ * Verifica a disponibilidade do WebAuthn passkey autofill (conditional mediation).
+ *
+ * Informativo: se webauthn não estiver configurado, o autofill nunca será exibido.
+ */
+export declare function checkPasskeyAutofill(input: DoctorInput): Finding | null;
+/**
+ * Finding da idade da chave de assinatura managed. `ageDays === null` (sem
+ * keystore em arquivo/cofre) → no-op `ok`. Acima de `maxAgeDays` → `warn`.
+ */
+export declare function signingKeyAgeFinding(ageDays: number | null, maxAgeDays: number): Finding;
+/** Roda todos os checks e devolve a lista plana de findings. */
+export declare function runAllChecks(input: DoctorInput): Finding[];
+/** Há algum finding de nível 'error'? (define o exit code). */
+export declare function hasErrors(findings: Finding[]): boolean;