@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,25 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+/**
+ * Parâmetros PRONTOS do RFC 8693 Token Exchange para o admin assumir a identidade
+ * de um usuário-alvo. NÃO é um bypass de auth: o exchange real (no
+ * `token_endpoint`) exige um access token do PRÓPRIO admin como `subject_token`
+ * (que o handler valida ter a role admin) e um client habilitado ao grant
+ * token-exchange. O painel só monta os parâmetros + um curl pronto — honesto com
+ * o mecanismo que já existe em `provider/token_exchange.ts`.
+ */
+export interface ImpersonationPanel {
+    tokenEndpoint: string;
+    grantType: string;
+    subjectTokenType: string;
+    requestedSubject: string;
+    /** Client habilitado ao grant token-exchange usado no exemplo. */
+    clientId: string;
+    /** Comando curl pronto (subject_token como placeholder a preencher). */
+    curl: string;
+}
+/**
+ * Monta o painel de impersonation para o `targetId`. Retorna `null` quando NENHUM
+ * client da config tem o grant token-exchange habilitado (sem ele o fluxo não
+ * funciona) — a UI então mostra a instrução de habilitar o grant.
+ */
+export declare function buildImpersonationPanel(cfg: Pick<ResolvedServerConfig, 'issuer' | 'clients'>, targetId: string): ImpersonationPanel | null;

package/build/src/host/impersonation.js

@@ -0,0 +1,31 @@
+const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+/**
+ * Monta o painel de impersonation para o `targetId`. Retorna `null` quando NENHUM
+ * client da config tem o grant token-exchange habilitado (sem ele o fluxo não
+ * funciona) — a UI então mostra a instrução de habilitar o grant.
+ */
+export function buildImpersonationPanel(cfg, targetId) {
+    const client = cfg.clients.find((c) => (c.grants ?? []).includes(TOKEN_EXCHANGE));
+    if (!client)
+        return null;
+    const tokenEndpoint = `${cfg.issuer.replace(/\/+$/, '')}/token`;
+    const auth = client.clientSecret
+        ? `  -u '${client.clientId}:${client.clientSecret}' \\\n`
+        : `  -d 'client_id=${client.clientId}' \\\n`;
+    const curl = `curl -X POST '${tokenEndpoint}' \\\n` +
+        auth +
+        `  -d 'grant_type=${TOKEN_EXCHANGE}' \\\n` +
+        `  -d 'subject_token=<ADMIN_ACCESS_TOKEN>' \\\n` +
+        `  -d 'subject_token_type=${ACCESS_TOKEN_TYPE}' \\\n` +
+        `  -d 'requested_subject=${targetId}' \\\n` +
+        `  -d 'scope=openid profile email'`;
+    return {
+        tokenEndpoint,
+        grantType: TOKEN_EXCHANGE,
+        subjectTokenType: ACCESS_TOKEN_TYPE,
+        requestedSubject: targetId,
+        clientId: client.clientId,
+        curl,
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { SettingsCapability } from './runtime_settings.js';
+export interface KeyRotationSetting {
+    enabled?: boolean;
+    maxAgeDays?: number;
+    keep?: number;
+}
+export interface ResolvedKeyRotationSetting {
+    enabled: boolean;
+    maxAgeDays: number;
+    keep: number;
+}
+export declare const KEY_ROTATION_DEFAULTS: ResolvedKeyRotationSetting;
+/** Resolve a setting `key_rotation` em runtime (fail-safe → defaults). */
+export declare function resolveEffectiveKeyRotation(settings: SettingsCapability): Promise<ResolvedKeyRotationSetting>;

package/build/src/host/key_rotation.js

@@ -0,0 +1,27 @@
+import { SETTING_KEYS } from './runtime_toggles.js';
+export const KEY_ROTATION_DEFAULTS = {
+    enabled: false,
+    maxAgeDays: 90,
+    keep: 2,
+};
+/** Resolve a setting `key_rotation` em runtime (fail-safe → defaults). */
+export async function resolveEffectiveKeyRotation(settings) {
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.KEY_ROTATION);
+        if (raw === null || raw === undefined)
+            return KEY_ROTATION_DEFAULTS;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return KEY_ROTATION_DEFAULTS;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : KEY_ROTATION_DEFAULTS.enabled,
+            maxAgeDays: typeof s.maxAgeDays === 'number' && s.maxAgeDays >= 1
+                ? Math.floor(s.maxAgeDays)
+                : KEY_ROTATION_DEFAULTS.maxAgeDays,
+            keep: typeof s.keep === 'number' && s.keep >= 1 ? Math.floor(s.keep) : KEY_ROTATION_DEFAULTS.keep,
+        };
+    }
+    catch {
+        return KEY_ROTATION_DEFAULTS;
+    }
+}

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

@@ -0,0 +1,42 @@
+import { type ResolvedKeyRotationSetting } from './key_rotation.js';
+import type { SettingsCapability } from './runtime_settings.js';
+import type { ManagedKeyInfo } from '../keys/keystore.js';
+/**
+ * Ações compartilhadas de rotação de chave. Funções puras-ish que tanto a Admin
+ * REST API (Bearer) quanto o console (sessão) chamam, evitando duplicar a lógica
+ * de status (idade + política + ETA) e de rotação (validação de keep/retire).
+ */
+export interface KeysStatus {
+    ageDays: number;
+    policy: ResolvedKeyRotationSetting;
+    nextRotationInDays: number | null;
+    keys: ManagedKeyInfo[];
+}
+/**
+ * Status da chave de assinatura managed. Retorna null quando o serviço não tem
+ * keystore gerenciável (jwks não é managed+store) — o controller traduz para 501.
+ * A política vem do runtime settings; sem settings, usa defaults (rotação off).
+ */
+export declare function buildKeysStatus(svc: {
+    keystoreAgeDays(): Promise<number | null>;
+    listManagedKeys(): Promise<ManagedKeyInfo[]>;
+}, settings: SettingsCapability | null): Promise<KeysStatus | null>;
+/**
+ * Rotaciona a chave agora. Valida `keep` (>= 1, default 2) e `retire` do body.
+ * A aplicação ao vivo + auditoria (keys.rotated) acontecem dentro de svc.rotateKeys.
+ */
+export declare function rotateNow(svc: {
+    rotateKeys(keep: number, retire?: boolean): Promise<{
+        newKid: string;
+        retiredKids: string[];
+        keptKids: string[];
+    }>;
+}, body: {
+    retire?: boolean;
+    keep?: number;
+} | undefined): Promise<{
+    rotated: true;
+    newKid: string;
+    retiredKids: string[];
+    keptKids: string[];
+}>;

package/build/src/host/key_rotation_actions.js

@@ -0,0 +1,27 @@
+import { resolveEffectiveKeyRotation } from './key_rotation.js';
+/**
+ * Status da chave de assinatura managed. Retorna null quando o serviço não tem
+ * keystore gerenciável (jwks não é managed+store) — o controller traduz para 501.
+ * A política vem do runtime settings; sem settings, usa defaults (rotação off).
+ */
+export async function buildKeysStatus(svc, settings) {
+    const ageDays = await svc.keystoreAgeDays();
+    if (ageDays === null)
+        return null;
+    const policy = settings
+        ? await resolveEffectiveKeyRotation(settings)
+        : { enabled: false, maxAgeDays: 90, keep: 2 };
+    const nextRotationInDays = policy.enabled ? Math.max(0, policy.maxAgeDays - ageDays) : null;
+    const keys = await svc.listManagedKeys();
+    return { ageDays, policy, nextRotationInDays, keys };
+}
+/**
+ * Rotaciona a chave agora. Valida `keep` (>= 1, default 2) e `retire` do body.
+ * A aplicação ao vivo + auditoria (keys.rotated) acontecem dentro de svc.rotateKeys.
+ */
+export async function rotateNow(svc, body) {
+    const retire = body?.retire === true;
+    const keep = typeof body?.keep === 'number' && body.keep >= 1 ? Math.floor(body.keep) : 2;
+    const res = await svc.rotateKeys(keep, retire);
+    return { rotated: true, ...res };
+}

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

@@ -0,0 +1,98 @@
+import type { AuthAccount } from '../accounts/account_store.js';
+import type { AuditSink } from '../audit/audit_sink.js';
+import type { ResolvedServerConfig } from '../define_config.js';
+import type { SettingsCapability } from './runtime_settings.js';
+/**
+ * `requireVerifiedEmail` efetivo (config ou runtime setting) E o store sabe dizer
+ * se o e-mail está verificado E a conta NÃO está verificada → bloqueia.
+ * Capability-probed: sem {@link EmailVerificationStatusCapability} a checagem é
+ * no-op (não bloqueia). Compartilhado pelos três fluxos de login (senha, magic
+ * link, passkey-first).
+ *
+ * Suporta `graceDays`: se a conta foi criada há menos de `graceDays` dias e ainda
+ * não verificou o e-mail, o login é permitido (mas a UI mostra um banner avisando).
+ *
+ * @param settings - SettingsCapability para ler o runtime setting. Quando
+ *   ausente (chamadores que ainda não injetam o settings), faz fallback ao config.
+ */
+export declare function isEmailUnverifiedBlock(cfg: ResolvedServerConfig, accountId: string, settings?: SettingsCapability): Promise<boolean>;
+/**
+ * Verifica se a senha da conta está vencida (password expiration).
+ * Capability-probed: sem `getPasswordChangedAt` → retorna false.
+ * Quando `password_expiration.enabled` é false ou a coluna não existe → false.
+ *
+ * @returns true se a senha expirou e deve ser trocada antes de completar o login.
+ */
+export declare function isPasswordExpired(cfg: ResolvedServerConfig, accountId: string, settings: SettingsCapability): Promise<boolean>;
+/**
+ * Verifica se a conta está expirada por inatividade (account_expiration setting).
+ *
+ * "Última atividade" = timestamp do último `login.success` da conta no audit.
+ * Capability-probed: sem `audit.list` → retorna false (feature indisponível).
+ * Quando enabled=false ou sem audit queryável → false (no-op).
+ *
+ * @param audit - AuditSink. Quando ausente ou sem `list`, retorna false.
+ * @param accountId - ID da conta a verificar.
+ * @param settings - SettingsCapability para ler a setting `account_expiration`.
+ * @param logger - logger mínimo opcional. Quando presente, registra falhas de DB
+ *   no caminho fail-safe (sem ele, o erro continua silencioso por compat).
+ * @returns true se a conta está expirada e o login deve ser bloqueado.
+ */
+export declare function isAccountExpired(audit: AuditSink | null | undefined, accountId: string, settings: SettingsCapability, logger?: LoginAttemptLogger): Promise<boolean>;
+/** Logger mínimo (subconjunto do logger do AdonisJS) para o caminho fail-safe. */
+export interface LoginAttemptLogger {
+    warn(obj: unknown, msg?: string): void;
+}
+/** Entrada de uma tentativa de login por senha (keyed por email). */
+export interface PasswordLoginInput {
+    email: string;
+    password: string;
+    /** IP da request (para auditoria + lockout). null quando indisponível. */
+    ip: string | null;
+    /**
+     * client_id da interaction OIDC, quando existir. Só é incluído no evento de
+     * auditoria nos fluxos que o têm (interaction); ausente no console de conta.
+     */
+    clientId?: string | null;
+    /**
+     * SettingsCapability para ler o runtime setting de `require_verified_email`.
+     * Quando ausente, faz fallback ao valor de `cfg.login.requireVerifiedEmail`.
+     */
+    settings?: SettingsCapability;
+    /**
+     * Logger mínimo opcional. Repassado aos caminhos fail-safe (ex.: checagem de
+     * expiração por inatividade) para que falhas de infra não fiquem silenciosas.
+     */
+    logger?: LoginAttemptLogger;
+}
+/** Resultado de {@link attemptPasswordLogin}. */
+export type PasswordLoginResult = {
+    ok: true;
+    account: AuthAccount;
+} | {
+    ok: false;
+    locked: boolean;
+    retryAfterSec?: number;
+    disabled?: boolean;
+    unverified?: boolean;
+    unverifiedGraceDays?: number;
+    passwordExpired?: boolean;
+    accountExpired?: boolean;
+    account?: AuthAccount;
+};
+/**
+ * Sequência canônica de login por senha + bloqueio progressivo, compartilhada
+ * pelos dois fluxos que pedem senha (interaction OIDC e console de conta):
+ *
+ *   1. `lockout.isLocked(email)` — se travada, NÃO verifica a senha; devolve
+ *      `{ ok: false, locked: true, retryAfterSec }` (o controller renderiza o erro).
+ *   2. `verifyCredentials(email, password)` — em falha: emite `login.failure`
+ *      (com `clientId` apenas quando fornecido), registra a falha no lockout
+ *      (`{ sink: cfg.audit, ip }`) e devolve `{ ok: false, locked: false }`.
+ *   3. Em sucesso: limpa o contador de falhas e devolve `{ ok: true, account }`.
+ *
+ * O evento `login.success` e a finalização da sessão/interaction ficam a cargo de
+ * cada controller (os fluxos diferem: MFA gate na interaction, sessão no console),
+ * assim como toda a renderização.
+ */
+export declare function attemptPasswordLogin(cfg: ResolvedServerConfig, input: PasswordLoginInput): Promise<PasswordLoginResult>;

package/build/src/host/login_attempt.js

@@ -0,0 +1,211 @@
+import { supportsAccountStatus, supportsEmailVerificationStatus, supportsPasswordExpiration, } from '../accounts/account_store.js';
+import { createAccountLockout } from './account_lockout.js';
+import { resolveEffectiveRequireVerifiedEmail, resolveEffectiveRequireVerifiedEmailFull, resolveEffectivePasswordExpiration, resolveEffectiveAccountExpiration, resolveEffectiveLockout, } from './runtime_toggles.js';
+/**
+ * `requireVerifiedEmail` efetivo (config ou runtime setting) E o store sabe dizer
+ * se o e-mail está verificado E a conta NÃO está verificada → bloqueia.
+ * Capability-probed: sem {@link EmailVerificationStatusCapability} a checagem é
+ * no-op (não bloqueia). Compartilhado pelos três fluxos de login (senha, magic
+ * link, passkey-first).
+ *
+ * Suporta `graceDays`: se a conta foi criada há menos de `graceDays` dias e ainda
+ * não verificou o e-mail, o login é permitido (mas a UI mostra um banner avisando).
+ *
+ * @param settings - SettingsCapability para ler o runtime setting. Quando
+ *   ausente (chamadores que ainda não injetam o settings), faz fallback ao config.
+ */
+export async function isEmailUnverifiedBlock(cfg, accountId, settings) {
+    // Resolve o valor efetivo: runtime setting sobrescreve o config estático.
+    const requireVerified = settings
+        ? await resolveEffectiveRequireVerifiedEmail(cfg.login?.requireVerifiedEmail ?? false, settings)
+        : (cfg.login?.requireVerifiedEmail ?? false);
+    if (!requireVerified)
+        return false;
+    if (!supportsEmailVerificationStatus(cfg.accountStore))
+        return false;
+    const verified = await cfg.accountStore.isEmailVerified(accountId);
+    if (verified)
+        return false;
+    // Grace period: se a setting tem graceDays e a conta foi criada recentemente,
+    // permite o login.
+    if (settings) {
+        const full = await resolveEffectiveRequireVerifiedEmailFull(cfg.login?.requireVerifiedEmail ?? false, settings);
+        if (full.graceDays > 0) {
+            // Busca a conta para checar created_at (se o store suportar).
+            const account = await cfg.accountStore.findById(accountId);
+            if (account) {
+                // Tenta ler `created_at` via duck-typing (não é parte do contrato AccountStore).
+                const raw = account;
+                const createdAt = raw.createdAt instanceof Date
+                    ? raw.createdAt
+                    : typeof raw.createdAt === 'string'
+                        ? new Date(raw.createdAt)
+                        : null;
+                if (createdAt) {
+                    const graceCutoff = new Date(createdAt.getTime() + full.graceDays * 24 * 60 * 60 * 1000);
+                    if (new Date() <= graceCutoff) {
+                        return false; // dentro da janela de graça → não bloqueia
+                    }
+                }
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Verifica se a senha da conta está vencida (password expiration).
+ * Capability-probed: sem `getPasswordChangedAt` → retorna false.
+ * Quando `password_expiration.enabled` é false ou a coluna não existe → false.
+ *
+ * @returns true se a senha expirou e deve ser trocada antes de completar o login.
+ */
+export async function isPasswordExpired(cfg, accountId, settings) {
+    const expiration = await resolveEffectivePasswordExpiration(settings);
+    if (!expiration.enabled)
+        return false;
+    if (!supportsPasswordExpiration(cfg.accountStore))
+        return false;
+    const changedAt = await cfg.accountStore.getPasswordChangedAt(accountId);
+    if (!changedAt) {
+        // Senha nunca trocada (coluna NULL = conta legacy) → considera vencida quando
+        // expiration está ligada (seguro: força a troca na 1ª vez).
+        return true;
+    }
+    const maxAgeMs = expiration.maxAgeDays * 24 * 60 * 60 * 1000;
+    return Date.now() - changedAt.getTime() > maxAgeMs;
+}
+/**
+ * Verifica se a conta está expirada por inatividade (account_expiration setting).
+ *
+ * "Última atividade" = timestamp do último `login.success` da conta no audit.
+ * Capability-probed: sem `audit.list` → retorna false (feature indisponível).
+ * Quando enabled=false ou sem audit queryável → false (no-op).
+ *
+ * @param audit - AuditSink. Quando ausente ou sem `list`, retorna false.
+ * @param accountId - ID da conta a verificar.
+ * @param settings - SettingsCapability para ler a setting `account_expiration`.
+ * @param logger - logger mínimo opcional. Quando presente, registra falhas de DB
+ *   no caminho fail-safe (sem ele, o erro continua silencioso por compat).
+ * @returns true se a conta está expirada e o login deve ser bloqueado.
+ */
+export async function isAccountExpired(audit, accountId, settings, logger) {
+    const expiration = await resolveEffectiveAccountExpiration(settings);
+    if (!expiration.enabled)
+        return false;
+    // Sem audit queryável → feature indisponível → não bloqueia.
+    if (typeof audit?.list !== 'function')
+        return false;
+    try {
+        // Busca o último login.success da conta (ordem desc, limit 1).
+        const result = await audit.list({ type: 'login.success', subject: accountId, page: 1, limit: 1 });
+        if (result.data.length === 0) {
+            // Nunca logou → considera ativa (conta nova, não inativa).
+            return false;
+        }
+        const lastLogin = result.data[0];
+        const createdAt = lastLogin.createdAt;
+        if (!createdAt)
+            return false;
+        const lastMs = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+        if (!Number.isFinite(lastMs))
+            return false;
+        const cutoffMs = Date.now() - expiration.inactiveDays * 24 * 60 * 60 * 1000;
+        return lastMs < cutoffMs;
+    }
+    catch (err) {
+        // Fail-safe: erro de DB → não bloqueia. Loga: enquanto a query de audit estiver
+        // quebrada, a expiração por inatividade não é aplicada (admin precisa saber).
+        logger?.warn({ err, accountId }, 'authkit: account-expiration check failed (audit query error) — not blocking login (fail-safe); inactivity enforcement is disabled until the audit store recovers.');
+        return false;
+    }
+}
+/**
+ * Sequência canônica de login por senha + bloqueio progressivo, compartilhada
+ * pelos dois fluxos que pedem senha (interaction OIDC e console de conta):
+ *
+ *   1. `lockout.isLocked(email)` — se travada, NÃO verifica a senha; devolve
+ *      `{ ok: false, locked: true, retryAfterSec }` (o controller renderiza o erro).
+ *   2. `verifyCredentials(email, password)` — em falha: emite `login.failure`
+ *      (com `clientId` apenas quando fornecido), registra a falha no lockout
+ *      (`{ sink: cfg.audit, ip }`) e devolve `{ ok: false, locked: false }`.
+ *   3. Em sucesso: limpa o contador de falhas e devolve `{ ok: true, account }`.
+ *
+ * O evento `login.success` e a finalização da sessão/interaction ficam a cargo de
+ * cada controller (os fluxos diferem: MFA gate na interaction, sessão no console),
+ * assim como toda a renderização.
+ */
+export async function attemptPasswordLogin(cfg, input) {
+    const { email, password, ip } = input;
+    // Lockout efetivo: runtime setting `lockout` sobrescreve o config estático.
+    // FAIL-SAFE → cfg.lockout (resolveEffectiveLockout já trata erros internamente).
+    // `store` é infra e permanece no config estático (não vem da setting).
+    const effectiveLockout = input.settings
+        ? { ...(await resolveEffectiveLockout(input.settings, cfg.lockout)), store: cfg.lockout.store }
+        : cfg.lockout;
+    const lockout = createAccountLockout(effectiveLockout);
+    // Bloqueio progressivo (keyed por email): se travada, não verifica a senha.
+    const lock = await lockout.isLocked(email);
+    if (lock.locked) {
+        return { ok: false, locked: true, retryAfterSec: lock.retryAfterSec };
+    }
+    const account = await cfg.accountStore.verifyCredentials(email, password);
+    if (!account) {
+        // `clientId` só entra no evento quando o fluxo o fornece (interaction).
+        await cfg.audit?.record(input.clientId !== undefined
+            ? { type: 'login.failure', email, ip, clientId: input.clientId }
+            : { type: 'login.failure', email, ip });
+        await lockout.recordFailure(email, { sink: cfg.audit, ip });
+        return { ok: false, locked: false };
+    }
+    // Conta desabilitada: rejeita o login (mesmo com senha correta). A capacidade é
+    // opcional — só checada quando o store a implementa. Emite `login.failure` (com
+    // motivo `disabled` no metadata) e NÃO registra falha no lockout (não é tentativa
+    // de adivinhar senha).
+    if (supportsAccountStatus(cfg.accountStore) && (await cfg.accountStore.isDisabled(account.id))) {
+        await cfg.audit?.record(input.clientId !== undefined
+            ? { type: 'login.failure', email, ip, clientId: input.clientId, metadata: { reason: 'disabled' } }
+            : { type: 'login.failure', email, ip, metadata: { reason: 'disabled' } });
+        return { ok: false, locked: false, disabled: true };
+    }
+    // E-mail não verificado (LGPD/compliance): rejeita o login se a política exige
+    // verificação E o store sabe responder. Não conta como falha de senha (a senha
+    // estava correta) — limpa o contador e emite login.failure com motivo `unverified`.
+    if (await isEmailUnverifiedBlock(cfg, account.id, input.settings)) {
+        await lockout.clearFailures(email);
+        await cfg.audit?.record(input.clientId !== undefined
+            ? { type: 'login.failure', email, ip, clientId: input.clientId, metadata: { reason: 'unverified' } }
+            : { type: 'login.failure', email, ip, metadata: { reason: 'unverified' } });
+        return { ok: false, locked: false, unverified: true };
+    }
+    // Senha expirada (password expiration): se a senha está vencida, sinaliza ao
+    // controller para forçar a troca ANTES de completar o login.
+    // Capability-probed: sem `getPasswordChangedAt` ou sem a setting → no-op.
+    if (input.settings) {
+        const expired = await isPasswordExpired(cfg, account.id, input.settings);
+        if (expired) {
+            // Não é uma falha de credenciais — limpa o contador.
+            await lockout.clearFailures(email);
+            await cfg.audit?.record(input.clientId !== undefined
+                ? { type: 'password.expired_change_forced', accountId: account.id, email, ip, clientId: input.clientId }
+                : { type: 'password.expired_change_forced', accountId: account.id, email, ip });
+            return { ok: false, locked: false, passwordExpired: true, account: account };
+        }
+    }
+    // Conta expirada por inatividade (account_expiration setting): bloqueia o login
+    // se a conta não teve login.success há mais de `inactiveDays` dias (via audit).
+    // Capability-probed: sem audit.list ou sem setting → no-op.
+    // Reativação: fluxo de reset de senha (link exibido pelo controller na mensagem).
+    if (input.settings) {
+        const expired = await isAccountExpired(cfg.audit, account.id, input.settings, input.logger);
+        if (expired) {
+            await lockout.clearFailures(email);
+            await cfg.audit?.record(input.clientId !== undefined
+                ? { type: 'account.expired_login_blocked', accountId: account.id, email, ip, clientId: input.clientId }
+                : { type: 'account.expired_login_blocked', accountId: account.id, email, ip });
+            return { ok: false, locked: false, accountExpired: true };
+        }
+    }
+    // Senha correta: limpa o contador de falhas (o lockout protege a etapa de senha).
+    await lockout.clearFailures(email);
+    return { ok: true, account };
+}

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

@@ -0,0 +1,27 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ResolvedServerConfig } from '../define_config.js';
+/** Dados de um login bem-sucedido a auditar/notificar. */
+export interface LoginSuccessInput {
+    accountId: string;
+    email?: string | null;
+    ip?: string | null;
+    clientId?: string | null;
+    /**
+     * Sinal "dispositivo já confiável" quando o caller JÁ resolveu o cookie de
+     * confiança (ex.: o controller pulou o MFA por causa dele). Quando omitido, a
+     * notificação resolve o cookie por conta própria (best-effort). `true` =
+     * dispositivo conhecido → NÃO notifica novo dispositivo.
+     */
+    trustedDevice?: boolean;
+    /** Metadata extra a anexar ao evento login.success (ex.: { mfa: 'totp' }). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Centraliza o pós-login bem-sucedido: registra o evento `login.success` e dispara
+ * (best-effort) o alerta de NOVO acesso quando o IP nunca foi visto para a conta.
+ *
+ * É fire-and-forget e FAIL-SAFE: a notificação roda DEPOIS do audit e qualquer erro
+ * é engolido — NUNCA bloqueia nem lança no caminho do login. Substitui as chamadas
+ * `cfg.audit?.record({ type: 'login.success', ... })` espalhadas pelos controllers.
+ */
+export declare function notifyLoginSuccess(ctx: HttpContext, cfg: ResolvedServerConfig, input: LoginSuccessInput): Promise<void>;

package/build/src/host/login_notify.js

@@ -0,0 +1,142 @@
+import { sendNewLoginEmail, sendNewDeviceLoginEmail } from './default_mailer.js';
+import { TRUSTED_DEVICE_COOKIE, isTrustedDeviceValid } from './trusted_device.js';
+/**
+ * Centraliza o pós-login bem-sucedido: registra o evento `login.success` e dispara
+ * (best-effort) o alerta de NOVO acesso quando o IP nunca foi visto para a conta.
+ *
+ * É fire-and-forget e FAIL-SAFE: a notificação roda DEPOIS do audit e qualquer erro
+ * é engolido — NUNCA bloqueia nem lança no caminho do login. Substitui as chamadas
+ * `cfg.audit?.record({ type: 'login.success', ... })` espalhadas pelos controllers.
+ */
+export async function notifyLoginSuccess(ctx, cfg, input) {
+    const { accountId, email, ip, clientId, metadata, trustedDevice } = input;
+    // User-agent da request: anexado ao `login.success` em `metadata.userAgent` para
+    // dar contexto de dispositivo às sessões (o admin/account o lê via join por
+    // accountId+loginTs). Sem migração — usa a coluna JSON `metadata` já existente.
+    const ua = ctx.request.header?.('user-agent') ?? null;
+    // 1) Audit do login.success (mesmo formato de antes + userAgent em metadata).
+    await cfg.audit?.record({
+        type: 'login.success',
+        accountId,
+        email: email ?? null,
+        ip: ip ?? null,
+        clientId: clientId ?? null,
+        metadata: ua ? { ...(metadata ?? {}), userAgent: ua } : metadata,
+    });
+    // 2) Sinal de DISPOSITIVO NOVO: login sem cookie de confiança válido para a
+    //    conta. Auditamos `login.new_device` (mesmo sem mail configurado) e, se
+    //    `notifications.newDeviceEmail`, enviamos o alerta. Resolvido aqui (síncrono
+    //    com o audit) porque depende do cookie da REQUEST atual; o e-mail em si é
+    //    fire-and-forget. `trustedDevice === true` (o caller já decidiu) pula tudo.
+    const onNewDevice = trustedDevice === true ? false : !hasTrustedDeviceCookie(ctx, accountId);
+    if (onNewDevice) {
+        await cfg.audit?.record({
+            type: 'login.new_device',
+            accountId,
+            email: email ?? null,
+            ip: ip ?? null,
+            clientId: clientId ?? null,
+        });
+    }
+    const userAgent = ua;
+    // 3) Alertas por e-mail (fire-and-forget): nunca propaga erro pro login.
+    if (!cfg.notifications.newLoginEmail && !(onNewDevice && cfg.notifications.newDeviceEmail))
+        return;
+    void (async () => {
+        // Resolve o e-mail quando o caller não o forneceu (ex.: fluxo de MFA só tem o
+        // accountId em escopo). Best-effort.
+        let resolvedEmail = email ?? null;
+        if (!resolvedEmail) {
+            resolvedEmail = (await cfg.accountStore.findById(accountId))?.email ?? null;
+        }
+        if (cfg.notifications.newLoginEmail) {
+            await maybeNotifyNewLogin(ctx, cfg, { accountId, email: resolvedEmail, ip: ip ?? null });
+        }
+        if (onNewDevice && cfg.notifications.newDeviceEmail && resolvedEmail) {
+            await notifyNewDevice(ctx, cfg, {
+                accountId,
+                email: resolvedEmail,
+                ip: ip ?? null,
+                userAgent,
+            });
+        }
+    })().catch((error) => {
+        // Defensivo: o próprio handler de erro nunca pode lançar (logger pode faltar
+        // em contextos mínimos). Best-effort.
+        ctx.logger?.error?.({ err: error, accountId }, 'authkit: falha no alerta de login');
+    });
+}
+/**
+ * `true` se há um cookie de dispositivo confiável VÁLIDO (estrutura íntegra, conta
+ * casa, não expirou) para `accountId`. Best-effort: qualquer erro de leitura →
+ * `false` (tratado como dispositivo novo). NÃO checa o re-enrollment de MFA
+ * (mfaEnabledAt) — o sinal de "dispositivo conhecido" é a mera presença de um
+ * cookie de confiança válido, independente do estado do MFA.
+ */
+function hasTrustedDeviceCookie(ctx, accountId) {
+    try {
+        const payload = ctx.request.encryptedCookie?.(TRUSTED_DEVICE_COOKIE);
+        return isTrustedDeviceValid(payload, { accountId });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Envia o alerta de NOVO DISPOSITIVO: usa o hook `mail.onNewDeviceLogin` (override
+ * do host) ou o mailer default. Best-effort — qualquer erro é engolido (já estamos
+ * dentro do fire-and-forget de {@link notifyLoginSuccess}).
+ */
+async function notifyNewDevice(ctx, cfg, data) {
+    const timestamp = new Date().toISOString();
+    if (cfg.mail?.onNewDeviceLogin) {
+        await cfg.mail.onNewDeviceLogin({
+            account: { id: data.accountId, email: data.email },
+            ip: data.ip,
+            userAgent: data.userAgent,
+            timestamp,
+        });
+        return;
+    }
+    await sendNewDeviceLoginEmail(ctx, {
+        email: data.email,
+        ip: data.ip,
+        userAgent: data.userAgent,
+        when: timestamp,
+    });
+}
+/**
+ * Verifica se o IP é novo para a conta (consultando o audit sink por
+ * `login.success` do subject) e, se for, envia o e-mail de alerta + audita
+ * `login.new_ip_notified`. Degrada para no-op quando: sem IP, sem e-mail, sem
+ * sink consultável (`list`), ou já houve um login.success deste IP antes.
+ */
+async function maybeNotifyNewLogin(ctx, cfg, data) {
+    const { accountId, email, ip } = data;
+    if (!ip || !email)
+        return;
+    // Sem consulta do histórico não dá pra decidir se o IP é novo → no-op.
+    if (typeof cfg.audit?.list !== 'function')
+        return;
+    // Lê o histórico de login.success do subject. O evento ATUAL já foi gravado por
+    // notifyLoginSuccess, então um IP visto antes aparece com count >= 2 para o IP.
+    // Buscamos uma página ampla e contamos as ocorrências deste IP.
+    const page = await cfg.audit.list({
+        type: 'login.success',
+        subject: accountId,
+        page: 1,
+        limit: 200,
+    });
+    const sameIpCount = page.data.filter((e) => e.ip === ip).length;
+    // > 1 significa que já havia um login.success deste IP antes do atual → não é novo.
+    if (sameIpCount > 1)
+        return;
+    const when = new Date().toISOString();
+    await sendNewLoginEmail(ctx, { email, ip, when });
+    await cfg.audit?.record({
+        type: 'login.new_ip_notified',
+        accountId,
+        email,
+        ip,
+    });
+}

package/build/src/host/middleware/account_auth.d.ts

@@ -0,0 +1,7 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+export declare const ACCOUNT_SESSION_KEY = "account_user_id";
+export default class AccountAuthMiddleware {
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}