@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,36 @@
+/**
+ * Serviço de notificações de segurança: envia e-mail quando eventos sensíveis
+ * ocorrem na conta (senha alterada, MFA ligado/desligado, passkey add/remove,
+ * e-mail alterado). Best-effort, fail-safe total — NUNCA lança na request.
+ *
+ * Respeita a setting `security_notifications` em `auth_settings` (enabled + kinds).
+ * O hook `mail.onSecurityNotice` do config tem prioridade sobre o mailer default.
+ */
+import type { HttpContext } from '@adonisjs/core/http';
+import type { MailHooks } from '../define_config.js';
+import type { AuditSink } from '../audit/audit_sink.js';
+import type { SecurityNotificationKind } from './runtime_toggles.js';
+/**
+ * Contexto para disparo de uma notificação de segurança.
+ */
+export interface SecurityNoticeContext {
+    account: {
+        id: string;
+        email: string;
+    };
+    kind: SecurityNotificationKind;
+    ip?: string | null;
+    userAgent?: string | null;
+    timestamp?: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Despacha uma notificação de segurança, se habilitada e o kind for um dos
+ * configurados. Best-effort: qualquer falha é ignorada silenciosamente (logged).
+ *
+ * @param ctx         HttpContext para o mailer default
+ * @param notice      Contexto da notificação
+ * @param mailHooks   Hooks de mail do config (opcional)
+ * @param audit       Sink de auditoria (opcional)
+ */
+export declare function dispatchSecurityNotice(ctx: HttpContext, notice: SecurityNoticeContext, mailHooks: Pick<MailHooks, 'onSecurityNotice'> | undefined, audit: AuditSink | undefined): Promise<void>;

package/build/src/host/security_notice_service.js

@@ -0,0 +1,87 @@
+/**
+ * Serviço de notificações de segurança: envia e-mail quando eventos sensíveis
+ * ocorrem na conta (senha alterada, MFA ligado/desligado, passkey add/remove,
+ * e-mail alterado). Best-effort, fail-safe total — NUNCA lança na request.
+ *
+ * Respeita a setting `security_notifications` em `auth_settings` (enabled + kinds).
+ * O hook `mail.onSecurityNotice` do config tem prioridade sobre o mailer default.
+ */
+import { resolveRuntimeSettings } from './runtime_settings.js';
+import { resolveEffectiveSecurityNotifications } from './runtime_toggles.js';
+import { sendSecurityNoticeEmail } from './default_mailer.js';
+/**
+ * Despacha uma notificação de segurança, se habilitada e o kind for um dos
+ * configurados. Best-effort: qualquer falha é ignorada silenciosamente (logged).
+ *
+ * @param ctx         HttpContext para o mailer default
+ * @param notice      Contexto da notificação
+ * @param mailHooks   Hooks de mail do config (opcional)
+ * @param audit       Sink de auditoria (opcional)
+ */
+export async function dispatchSecurityNotice(ctx, notice, mailHooks, audit) {
+    try {
+        // Resolve settings em runtime (fail-safe: sem tabela → defaults habilitados).
+        let enabled = true;
+        let enabledKinds = [
+            'password_changed',
+            'mfa_enabled',
+            'mfa_disabled',
+            'passkey_added',
+            'passkey_removed',
+            'email_changed',
+        ];
+        try {
+            const runtimeSettings = await resolveRuntimeSettings(ctx);
+            if (runtimeSettings && (await runtimeSettings.isTablePresent())) {
+                const resolved = await resolveEffectiveSecurityNotifications(runtimeSettings);
+                enabled = resolved.enabled;
+                enabledKinds = resolved.kinds;
+            }
+        }
+        catch {
+            // DB não disponível ou tabela ausente → usa defaults (habilitado, todos os kinds).
+        }
+        if (!enabled)
+            return;
+        if (!enabledKinds.includes(notice.kind))
+            return;
+        const timestamp = notice.timestamp ?? new Date().toISOString();
+        const noticeData = {
+            account: notice.account,
+            kind: notice.kind,
+            ip: notice.ip ?? null,
+            userAgent: notice.userAgent ?? null,
+            timestamp,
+            metadata: notice.metadata,
+        };
+        // Hook do config tem prioridade; senão usa o mailer default.
+        if (mailHooks?.onSecurityNotice) {
+            await mailHooks.onSecurityNotice(noticeData);
+        }
+        else {
+            await sendSecurityNoticeEmail(ctx, {
+                email: notice.account.email,
+                kind: notice.kind,
+                timestamp,
+                ip: notice.ip,
+                metadata: notice.metadata,
+            });
+        }
+        // Audita o envio da notificação (best-effort).
+        await audit?.record({
+            type: 'security_notice.sent',
+            accountId: notice.account.id,
+            ip: notice.ip ?? null,
+            metadata: { kind: notice.kind },
+        });
+    }
+    catch (error) {
+        // Fail-safe total: erro na notificação NUNCA quebra o fluxo principal.
+        try {
+            ctx.logger.error({ err: error, kind: notice.kind, accountId: notice.account.id }, 'authkit: falha ao enviar notificação de segurança');
+        }
+        catch {
+            // Logger também falhou — silencioso.
+        }
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+import type { AdminSession } from './admin_sessions_service.js';
+/**
+ * ENRIQUECE sessões ativas com contexto de dispositivo (user-agent → browser/SO),
+ * IP e localização, SEM tocar no payload da `Session` do oidc-provider (que não é
+ * extensível de forma portátil entre adapters).
+ *
+ * A FONTE do contexto é o próprio audit log: cada `login.success` carrega o `ip` e
+ * o `userAgent` (em `metadata.userAgent`, gravado por `notifyLoginSuccess`). Como a
+ * `Session` carrega o `loginTs` (epoch do login), correlacionamos cada sessão ao
+ * evento `login.success` da MESMA conta cujo timestamp é o mais próximo do `loginTs`
+ * — um join barato em memória sobre uma janela recente de eventos.
+ *
+ * CAPABILITY-PROBED + FAIL-SAFE: degrada para os campos vazios (sem quebrar a
+ * listagem) quando o sink de auditoria não suporta consulta (`list` ausente). A
+ * geolocalização usa o hook plugável `resolveGeo` (ausente = só IP, sem location),
+ * com timeout curto.
+ *
+ * LIMITAÇÃO: a correlação por timestamp é uma APROXIMAÇÃO — duas sessões da mesma
+ * conta criadas no mesmo segundo podem trocar de contexto entre si. É suficiente
+ * para exibição (não para decisões de segurança).
+ */
+export declare function enrichSessionsWithContext(cfg: Pick<ResolvedServerConfig, 'audit' | 'resolveGeo'>, accountId: string, sessions: AdminSession[]): Promise<AdminSession[]>;

package/build/src/host/session_context.js

@@ -0,0 +1,89 @@
+import { parseUserAgent } from './user_agent.js';
+import { resolveGeoSafe } from './geo.js';
+/**
+ * ENRIQUECE sessões ativas com contexto de dispositivo (user-agent → browser/SO),
+ * IP e localização, SEM tocar no payload da `Session` do oidc-provider (que não é
+ * extensível de forma portátil entre adapters).
+ *
+ * A FONTE do contexto é o próprio audit log: cada `login.success` carrega o `ip` e
+ * o `userAgent` (em `metadata.userAgent`, gravado por `notifyLoginSuccess`). Como a
+ * `Session` carrega o `loginTs` (epoch do login), correlacionamos cada sessão ao
+ * evento `login.success` da MESMA conta cujo timestamp é o mais próximo do `loginTs`
+ * — um join barato em memória sobre uma janela recente de eventos.
+ *
+ * CAPABILITY-PROBED + FAIL-SAFE: degrada para os campos vazios (sem quebrar a
+ * listagem) quando o sink de auditoria não suporta consulta (`list` ausente). A
+ * geolocalização usa o hook plugável `resolveGeo` (ausente = só IP, sem location),
+ * com timeout curto.
+ *
+ * LIMITAÇÃO: a correlação por timestamp é uma APROXIMAÇÃO — duas sessões da mesma
+ * conta criadas no mesmo segundo podem trocar de contexto entre si. É suficiente
+ * para exibição (não para decisões de segurança).
+ */
+export async function enrichSessionsWithContext(cfg, accountId, sessions) {
+    if (sessions.length === 0)
+        return sessions;
+    // Sem consulta de audit não há de onde puxar o contexto → devolve como veio.
+    if (typeof cfg.audit?.list !== 'function')
+        return sessions;
+    // Janela recente de login.success da conta (limite são para não estourar memória).
+    const page = await cfg.audit.list({
+        type: 'login.success',
+        subject: accountId,
+        page: 1,
+        limit: 200,
+    });
+    const events = page.data.map((e) => ({
+        ts: toEpochSeconds(e.createdAt),
+        ip: e.ip ?? null,
+        userAgent: e.metadata?.userAgent ?? null,
+    }));
+    return Promise.all(sessions.map(async (s) => {
+        const match = closestEvent(events, s.loginTs);
+        if (!match)
+            return s;
+        const { browser, os } = parseUserAgent(match.userAgent);
+        const location = await resolveGeoSafe(cfg.resolveGeo, match.ip);
+        return {
+            ...s,
+            userAgent: match.userAgent,
+            browser: match.userAgent ? browser : null,
+            os: match.userAgent ? os : null,
+            ip: match.ip,
+            location,
+        };
+    }));
+}
+/**
+ * Escolhe o evento cujo timestamp é o MAIS PRÓXIMO do `loginTs` da sessão. Quando a
+ * sessão não tem `loginTs`, devolve o evento mais recente com algum contexto. `null`
+ * quando não há eventos úteis.
+ */
+function closestEvent(events, loginTs) {
+    const usable = events.filter((e) => e.ip !== null || e.userAgent !== null);
+    if (usable.length === 0)
+        return null;
+    if (loginTs === undefined) {
+        // Sem loginTs: o primeiro (a listagem do sink vem desc por createdAt).
+        return usable[0];
+    }
+    let best = null;
+    let bestDelta = Number.POSITIVE_INFINITY;
+    for (const e of usable) {
+        if (e.ts === null)
+            continue;
+        const delta = Math.abs(e.ts - loginTs);
+        if (delta < bestDelta) {
+            bestDelta = delta;
+            best = e;
+        }
+    }
+    return best ?? usable[0];
+}
+/** Normaliza o createdAt do audit (Date | ISO string) para epoch-segundos. */
+function toEpochSeconds(createdAt) {
+    if (!createdAt)
+        return null;
+    const ms = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Sudo mode (confirm_password + grace period).
+ *
+ * Após confirmar a identidade (senha ou passkey), o helper `requireSudo` registra
+ * o timestamp na sessão Adonis. Dentro da janela de graça (`graceMinutes`) a
+ * confirmação é aceita; fora dela, o usuário é redirecionado para `/account/confirm`.
+ *
+ * Setting `sudo_mode`:
+ *   - `enabled`:      habilita/desabilita o sudo mode. Default: true.
+ *   - `graceMinutes`: janela de graça em minutos. Default: 15.
+ *
+ * Chave de sessão: `authkit_sudo_at` (timestamp ms).
+ */
+import type { HttpContext } from '@adonisjs/core/http';
+import type { SettingsCapability } from './runtime_settings.js';
+export interface SudoModeSetting {
+    enabled?: boolean;
+    graceMinutes?: number;
+}
+export interface ResolvedSudoModeSetting {
+    enabled: boolean;
+    graceMinutes: number;
+}
+export declare const SUDO_MODE_DEFAULTS: ResolvedSudoModeSetting;
+/**
+ * Resolve a setting `sudo_mode` em runtime (fail-safe).
+ */
+export declare function resolveEffectiveSudoMode(settings: SettingsCapability): Promise<ResolvedSudoModeSetting>;
+/** Chave da sessão Adonis que registra quando o sudo foi confirmado. */
+export declare const SUDO_SESSION_KEY = "authkit_sudo_at";
+/**
+ * Registra o timestamp de confirmação de sudo na sessão (NOW).
+ * Chamar após o usuário confirmar sua identidade (senha ou passkey).
+ */
+export declare function markSudo(ctx: HttpContext): void;
+/**
+ * Verifica se o sudo está ativo (dentro da janela de graça).
+ *
+ * @returns `true` se o sudo está ativo (dentro da graça); `false` caso contrário.
+ */
+export declare function isSudoActive(ctx: HttpContext, graceMinutes: number): boolean;
+/**
+ * Guard de sudo mode. Verifica se a confirmação de identidade está ativa e
+ * dentro da janela de graça. Se estiver, retorna `true`. Se não, redireciona
+ * para `/account/confirm?return_to=<path atual>` e retorna a resposta.
+ *
+ * Uso:
+ * ```ts
+ * const result = await requireSudo(ctx, settings)
+ * if (result !== true) return result
+ * ```
+ *
+ * FAIL-SAFE: qualquer erro lê settings → retorna `true` (deixa passar).
+ * Quando `sudo_mode.enabled = false`, sempre retorna `true`.
+ */
+export declare function requireSudo(ctx: HttpContext, settings: SettingsCapability | null): Promise<true | unknown>;

package/build/src/host/sudo_mode.js

@@ -0,0 +1,99 @@
+/**
+ * Sudo mode (confirm_password + grace period).
+ *
+ * Após confirmar a identidade (senha ou passkey), o helper `requireSudo` registra
+ * o timestamp na sessão Adonis. Dentro da janela de graça (`graceMinutes`) a
+ * confirmação é aceita; fora dela, o usuário é redirecionado para `/account/confirm`.
+ *
+ * Setting `sudo_mode`:
+ *   - `enabled`:      habilita/desabilita o sudo mode. Default: true.
+ *   - `graceMinutes`: janela de graça em minutos. Default: 15.
+ *
+ * Chave de sessão: `authkit_sudo_at` (timestamp ms).
+ */
+import { SETTING_KEYS } from './runtime_toggles.js';
+export const SUDO_MODE_DEFAULTS = {
+    enabled: true,
+    graceMinutes: 15,
+};
+/**
+ * Resolve a setting `sudo_mode` em runtime (fail-safe).
+ */
+export async function resolveEffectiveSudoMode(settings) {
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.SUDO_MODE);
+        if (raw === null || raw === undefined)
+            return SUDO_MODE_DEFAULTS;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return SUDO_MODE_DEFAULTS;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : SUDO_MODE_DEFAULTS.enabled,
+            graceMinutes: typeof s.graceMinutes === 'number' && s.graceMinutes >= 0
+                ? Math.floor(s.graceMinutes)
+                : SUDO_MODE_DEFAULTS.graceMinutes,
+        };
+    }
+    catch {
+        return SUDO_MODE_DEFAULTS;
+    }
+}
+// ---------------------------------------------------------------------------
+// Session key + helpers
+// ---------------------------------------------------------------------------
+/** Chave da sessão Adonis que registra quando o sudo foi confirmado. */
+export const SUDO_SESSION_KEY = 'authkit_sudo_at';
+/**
+ * Registra o timestamp de confirmação de sudo na sessão (NOW).
+ * Chamar após o usuário confirmar sua identidade (senha ou passkey).
+ */
+export function markSudo(ctx) {
+    ctx.session.put(SUDO_SESSION_KEY, Date.now());
+}
+/**
+ * Verifica se o sudo está ativo (dentro da janela de graça).
+ *
+ * @returns `true` se o sudo está ativo (dentro da graça); `false` caso contrário.
+ */
+export function isSudoActive(ctx, graceMinutes) {
+    const sudoAt = ctx.session.get(SUDO_SESSION_KEY);
+    if (!sudoAt)
+        return false;
+    const graceMs = graceMinutes * 60 * 1000;
+    return Date.now() - sudoAt <= graceMs;
+}
+/**
+ * Guard de sudo mode. Verifica se a confirmação de identidade está ativa e
+ * dentro da janela de graça. Se estiver, retorna `true`. Se não, redireciona
+ * para `/account/confirm?return_to=<path atual>` e retorna a resposta.
+ *
+ * Uso:
+ * ```ts
+ * const result = await requireSudo(ctx, settings)
+ * if (result !== true) return result
+ * ```
+ *
+ * FAIL-SAFE: qualquer erro lê settings → retorna `true` (deixa passar).
+ * Quando `sudo_mode.enabled = false`, sempre retorna `true`.
+ */
+export async function requireSudo(ctx, settings) {
+    try {
+        const cfg = settings ? await resolveEffectiveSudoMode(settings) : SUDO_MODE_DEFAULTS;
+        if (!cfg.enabled)
+            return true;
+        if (isSudoActive(ctx, cfg.graceMinutes))
+            return true;
+    }
+    catch {
+        // FAIL-SAFE: erro ao resolver a setting → deixa passar.
+        return true;
+    }
+    // Fora da graça: redireciona para confirmação.
+    const rawUrl = ctx.request.url?.() ?? '';
+    const qs = ctx.request.parsedUrl?.search ?? '';
+    const dest = qs ? `${rawUrl}${qs}` : rawUrl;
+    const returnTo = dest && dest !== '/' && !dest.startsWith('/account/confirm')
+        ? `?return_to=${encodeURIComponent(dest)}`
+        : '';
+    return ctx.response.redirect(`/account/confirm${returnTo}`);
+}

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

@@ -0,0 +1,15 @@
+import type { DailyPoint } from './admin_stats_service.js';
+/**
+ * Gera um gráfico de BARRAS em SVG inline (server-side, SEM nenhuma lib de chart e
+ * SEM JS no cliente) a partir de uma série diária. Estilo enxuto, consistente com o
+ * visual Tailwind do console (cor passável). Cada barra ganha um `<title>` para o
+ * tooltip nativo do browser (data + contagem) — acessível sem JS.
+ *
+ * A altura é normalizada pelo maior valor da série; séries todas-zero rendem barras
+ * de altura mínima (linha de base). O SVG é responsivo (`width: 100%`) via viewBox.
+ */
+export declare function barChartSvg(series: DailyPoint[], opts?: {
+    width?: number;
+    height?: number;
+    color?: string;
+}): string;

package/build/src/host/svg_chart.js

@@ -0,0 +1,45 @@
+/**
+ * Gera um gráfico de BARRAS em SVG inline (server-side, SEM nenhuma lib de chart e
+ * SEM JS no cliente) a partir de uma série diária. Estilo enxuto, consistente com o
+ * visual Tailwind do console (cor passável). Cada barra ganha um `<title>` para o
+ * tooltip nativo do browser (data + contagem) — acessível sem JS.
+ *
+ * A altura é normalizada pelo maior valor da série; séries todas-zero rendem barras
+ * de altura mínima (linha de base). O SVG é responsivo (`width: 100%`) via viewBox.
+ */
+export function barChartSvg(series, opts = {}) {
+    const width = opts.width ?? 600;
+    const height = opts.height ?? 80;
+    const color = opts.color ?? '#111827'; // gray-900
+    const n = series.length;
+    if (n === 0) {
+        return `<svg viewBox="0 0 ${width} ${height}" width="100%" role="img" aria-hidden="true"></svg>`;
+    }
+    const max = Math.max(1, ...series.map((p) => p.count));
+    const gap = 2;
+    const barWidth = Math.max(1, (width - gap * (n - 1)) / n);
+    const minBar = 1;
+    const bars = series
+        .map((p, i) => {
+        const x = i * (barWidth + gap);
+        const h = p.count > 0 ? Math.max(minBar, (p.count / max) * (height - 2)) : minBar;
+        const y = height - h;
+        const title = `${escapeXml(p.date)}: ${p.count}`;
+        return (`<rect x="${round(x)}" y="${round(y)}" width="${round(barWidth)}" height="${round(h)}" ` +
+            `rx="1" fill="${color}" opacity="${p.count > 0 ? 0.9 : 0.15}">` +
+            `<title>${title}</title></rect>`);
+    })
+        .join('');
+    return (`<svg viewBox="0 0 ${width} ${height}" width="100%" preserveAspectRatio="none" ` +
+        `role="img" aria-label="bar chart">${bars}</svg>`);
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+function escapeXml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

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

@@ -0,0 +1,61 @@
+/**
+ * "Trusted devices" — pular o 2º fator (MFA) neste dispositivo por N dias.
+ *
+ * Mecanismo SEM novos requisitos de DB: um cookie httpOnly assinado/encriptado
+ * com a appKey do host (via `response.encryptedCookie` / `request.encryptedCookie`,
+ * que são appKey-backed). O cookie carrega `{ a: accountId, d: deviceId, iat, exp }`.
+ *
+ * Validação (ver {@link isTrustedDeviceValid}):
+ *   - `exp` ainda no futuro;
+ *   - `a` casa com a conta que acabou de passar pela senha;
+ *   - `iat >= mfaEnabledAt` — re-enrolar o MFA invalida cookies antigos (revogação
+ *     por re-enrollment, sem estado server-side).
+ *
+ * Step-up (acr_values pedindo o mfaAcr) SEMPRE ignora o cookie e força o MFA — a
+ * decisão fica no controller, antes de checar o cookie.
+ *
+ * Limitação conhecida (documentada): NÃO há uma lista de revogação por-dispositivo
+ * server-side; a revogação disponível é "revogar todos" via re-enrollment do MFA.
+ * Uma allowlist/denylist persistida fica como trabalho futuro.
+ */
+/** Nome do cookie de dispositivo confiável. */
+export declare const TRUSTED_DEVICE_COOKIE = "authkit_trusted_device";
+/** Payload guardado (encriptado) no cookie de dispositivo confiável. */
+export interface TrustedDevicePayload {
+    /** accountId ao qual a confiança pertence. */
+    a: string;
+    /** id opaco do dispositivo (para futura revogação por-dispositivo). */
+    d: string;
+    /** issued-at (epoch ms). */
+    iat: number;
+    /** expiry (epoch ms). */
+    exp: number;
+}
+/**
+ * Infra de trusted devices. Política (enabled, days) é gerenciada em runtime
+ * via setting `trusted_devices` no admin console ou Admin API.
+ */
+export interface TrustedDevicesConfigInput {
+}
+export interface ResolvedTrustedDevicesConfig {
+    enabled: boolean;
+    days: number;
+}
+export declare function resolveTrustedDevices(_input?: TrustedDevicesConfigInput): ResolvedTrustedDevicesConfig;
+/** Constrói o payload de um novo cookie de confiança para a conta. */
+export declare function buildTrustedDevicePayload(accountId: string, cfg: ResolvedTrustedDevicesConfig, now?: number): TrustedDevicePayload;
+/**
+ * `true` se o payload do cookie é uma confiança VÁLIDA para `accountId`:
+ *   - estrutura íntegra;
+ *   - pertence à conta certa;
+ *   - não expirou;
+ *   - foi emitido em/depois do último (re)enrollment de MFA (`mfaEnabledAt`).
+ *
+ * `mfaEnabledAt` em epoch ms (ou null quando o store não rastreia — nesse caso a
+ * checagem de re-enrollment é pulada, mantendo a validade por expiração apenas).
+ */
+export declare function isTrustedDeviceValid(payload: unknown, opts: {
+    accountId: string;
+    mfaEnabledAt?: number | null;
+    now?: number;
+}): boolean;

package/build/src/host/trusted_device.js

@@ -0,0 +1,65 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * "Trusted devices" — pular o 2º fator (MFA) neste dispositivo por N dias.
+ *
+ * Mecanismo SEM novos requisitos de DB: um cookie httpOnly assinado/encriptado
+ * com a appKey do host (via `response.encryptedCookie` / `request.encryptedCookie`,
+ * que são appKey-backed). O cookie carrega `{ a: accountId, d: deviceId, iat, exp }`.
+ *
+ * Validação (ver {@link isTrustedDeviceValid}):
+ *   - `exp` ainda no futuro;
+ *   - `a` casa com a conta que acabou de passar pela senha;
+ *   - `iat >= mfaEnabledAt` — re-enrolar o MFA invalida cookies antigos (revogação
+ *     por re-enrollment, sem estado server-side).
+ *
+ * Step-up (acr_values pedindo o mfaAcr) SEMPRE ignora o cookie e força o MFA — a
+ * decisão fica no controller, antes de checar o cookie.
+ *
+ * Limitação conhecida (documentada): NÃO há uma lista de revogação por-dispositivo
+ * server-side; a revogação disponível é "revogar todos" via re-enrollment do MFA.
+ * Uma allowlist/denylist persistida fica como trabalho futuro.
+ */
+/** Nome do cookie de dispositivo confiável. */
+export const TRUSTED_DEVICE_COOKIE = 'authkit_trusted_device';
+export function resolveTrustedDevices(_input) {
+    return {
+        enabled: true,
+        days: 30,
+    };
+}
+/** Constrói o payload de um novo cookie de confiança para a conta. */
+export function buildTrustedDevicePayload(accountId, cfg, now = Date.now()) {
+    return {
+        a: accountId,
+        d: randomBytes(16).toString('hex'),
+        iat: now,
+        exp: now + cfg.days * 24 * 60 * 60 * 1000,
+    };
+}
+/**
+ * `true` se o payload do cookie é uma confiança VÁLIDA para `accountId`:
+ *   - estrutura íntegra;
+ *   - pertence à conta certa;
+ *   - não expirou;
+ *   - foi emitido em/depois do último (re)enrollment de MFA (`mfaEnabledAt`).
+ *
+ * `mfaEnabledAt` em epoch ms (ou null quando o store não rastreia — nesse caso a
+ * checagem de re-enrollment é pulada, mantendo a validade por expiração apenas).
+ */
+export function isTrustedDeviceValid(payload, opts) {
+    const now = opts.now ?? Date.now();
+    if (!payload || typeof payload !== 'object')
+        return false;
+    const p = payload;
+    if (typeof p.a !== 'string' || typeof p.iat !== 'number' || typeof p.exp !== 'number') {
+        return false;
+    }
+    if (p.a !== opts.accountId)
+        return false;
+    if (p.exp <= now)
+        return false;
+    // Re-enrollment do MFA revoga cookies emitidos antes dele.
+    if (typeof opts.mfaEnabledAt === 'number' && p.iat < opts.mfaEnabledAt)
+        return false;
+    return true;
+}