@adonis-agora/authkit-server 0.34.0

package/build/src/adapters/factory.js

@@ -0,0 +1,43 @@
+import { RedisAdapter } from './redis_adapter.js';
+import { DatabaseAdapter } from './database_adapter.js';
+export const adapters = {
+    /**
+     * Factory para o adapter Redis. O consumidor precisa ter o @adonisjs/redis
+     * configurado, pois o resolver resolve o `RedisManager` pelo token `'redis'`
+     * do container e obtém a conexão nomeada via `connection(name)`.
+     */
+    redis(config) {
+        return {
+            async resolver(app) {
+                const redisManager = await app.container.make('redis');
+                const client = redisManager.connection(config.connection);
+                const prefix = config.prefix ?? 'authkit';
+                return class extends RedisAdapter {
+                    constructor(name) {
+                        super(name, client, prefix);
+                    }
+                };
+            },
+        };
+    },
+    /**
+     * Factory para o adapter de banco (Lucid). Resolve o `Database` manager pelo
+     * token `'lucid.db'`. O `DatabaseAdapter` consome o manager diretamente
+     * (`db.query()`/`db.table()`); quando uma conexão específica é solicitada,
+     * usamos `db.connection(name)` para obter o cliente daquela conexão.
+     */
+    database(config = {}) {
+        return {
+            async resolver(app) {
+                const db = await app.container.make('lucid.db');
+                const connection = config.connection;
+                const conn = connection ? db.connection(connection) : db;
+                return class extends DatabaseAdapter {
+                    constructor(name) {
+                        super(name, conn);
+                    }
+                };
+            },
+        };
+    },
+};

package/build/src/adapters/redis_adapter.d.ts

@@ -0,0 +1,24 @@
+import type { Redis } from 'ioredis';
+import type { EnumeratedArtifact, OidcAdapter, OidcPayload } from './adapter_contract.js';
+export declare class RedisAdapter implements OidcAdapter {
+    #private;
+    private name;
+    private redis;
+    private prefix;
+    constructor(name: string, redis: Redis, prefix: string);
+    upsert(id: string, payload: OidcPayload, expiresIn: number): Promise<void>;
+    find(id: string): Promise<OidcPayload | undefined>;
+    findByUid(uid: string): Promise<OidcPayload | undefined>;
+    findByUserCode(userCode: string): Promise<OidcPayload | undefined>;
+    consume(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    revokeByGrantId(grantId: string): Promise<void>;
+    /**
+     * Enumeração genérica dos artefatos do model deste adapter via SCAN sobre o
+     * prefixo de chave do model (`<prefix>:<name>:*`). É limpo porque cada artefato
+     * é uma chave única já namespaceada por `prefix` + `name`; SCAN é não-bloqueante
+     * (cursor) ao contrário de KEYS. Usado pelo console admin (`Client`, `Session`,
+     * `Grant`, tokens).
+     */
+    list(): Promise<EnumeratedArtifact[]>;
+}

package/build/src/adapters/redis_adapter.js

@@ -0,0 +1,122 @@
+const grantable = new Set([
+    'AccessToken',
+    'AuthorizationCode',
+    'RefreshToken',
+    'DeviceCode',
+    'BackchannelAuthenticationRequest',
+]);
+export class RedisAdapter {
+    name;
+    redis;
+    prefix;
+    constructor(name, redis, prefix) {
+        this.name = name;
+        this.redis = redis;
+        this.prefix = prefix;
+    }
+    #key(id) {
+        return `${this.prefix}:${this.name}:${id}`;
+    }
+    #grantKey(grantId) {
+        return `${this.prefix}:grant:${grantId}`;
+    }
+    #userCodeKey(userCode) {
+        return `${this.prefix}:userCode:${userCode}`;
+    }
+    #uidKey(uid) {
+        return `${this.prefix}:uid:${uid}`;
+    }
+    async upsert(id, payload, expiresIn) {
+        const key = this.#key(id);
+        const multi = this.redis.multi();
+        multi.set(key, JSON.stringify(payload));
+        if (grantable.has(this.name) && payload.grantId) {
+            const gk = this.#grantKey(payload.grantId);
+            multi.rpush(gk, key);
+            if (expiresIn)
+                multi.expire(gk, expiresIn);
+        }
+        if (payload.userCode) {
+            const uck = this.#userCodeKey(payload.userCode);
+            multi.set(uck, id);
+            if (expiresIn)
+                multi.expire(uck, expiresIn);
+        }
+        if (this.name === 'Session' && payload.uid) {
+            const uk = this.#uidKey(payload.uid);
+            multi.set(uk, id);
+            if (expiresIn)
+                multi.expire(uk, expiresIn);
+        }
+        if (expiresIn)
+            multi.expire(key, expiresIn);
+        await multi.exec();
+    }
+    async find(id) {
+        const data = await this.redis.get(this.#key(id));
+        if (!data)
+            return undefined;
+        return JSON.parse(data);
+    }
+    async findByUid(uid) {
+        const id = await this.redis.get(this.#uidKey(uid));
+        if (!id)
+            return undefined;
+        return this.find(id);
+    }
+    async findByUserCode(userCode) {
+        const id = await this.redis.get(this.#userCodeKey(userCode));
+        if (!id)
+            return undefined;
+        return this.find(id);
+    }
+    async consume(id) {
+        const found = await this.find(id);
+        if (!found)
+            return;
+        found.consumed = Math.floor(Date.now() / 1000);
+        const ttl = await this.redis.ttl(this.#key(id));
+        if (ttl > 0)
+            await this.redis.set(this.#key(id), JSON.stringify(found), 'EX', ttl);
+        else
+            await this.redis.set(this.#key(id), JSON.stringify(found));
+    }
+    async destroy(id) {
+        await this.redis.del(this.#key(id));
+    }
+    async revokeByGrantId(grantId) {
+        const gk = this.#grantKey(grantId);
+        const keys = await this.redis.lrange(gk, 0, -1);
+        const multi = this.redis.multi();
+        keys.forEach((k) => multi.del(k));
+        multi.del(gk);
+        await multi.exec();
+    }
+    /**
+     * Enumeração genérica dos artefatos do model deste adapter via SCAN sobre o
+     * prefixo de chave do model (`<prefix>:<name>:*`). É limpo porque cada artefato
+     * é uma chave única já namespaceada por `prefix` + `name`; SCAN é não-bloqueante
+     * (cursor) ao contrário de KEYS. Usado pelo console admin (`Client`, `Session`,
+     * `Grant`, tokens).
+     */
+    async list() {
+        const prefix = `${this.prefix}:${this.name}:`;
+        const result = [];
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.redis.scan(cursor, 'MATCH', `${prefix}*`, 'COUNT', 100);
+            cursor = next;
+            for (const key of keys) {
+                const data = await this.redis.get(key);
+                if (!data)
+                    continue;
+                result.push({
+                    id: key.slice(prefix.length),
+                    payload: JSON.parse(data),
+                });
+            }
+        } while (cursor !== '0');
+        result.sort((a, b) => a.id.localeCompare(b.id));
+        return result;
+    }
+}

package/build/src/audit/audit_sink.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP.
+ */
+export type AuditEventType = 'login.success' | 'login.failure' | 'signup' | 'password_reset.issued' | 'password_reset.consumed' | 'pat.issued' | 'pat.revoked' | 'pat.used' | 'impersonation' | 'impersonation.started' | 'mfa.enabled' | 'mfa.disabled' | 'account.locked' | 'passkey.registered' | 'passkey.removed' | 'email_verification.issued' | 'email_verification.consumed' | 'client.created' | 'client.updated' | 'client.deleted' | 'session.revoked_all' | 'password.changed' | 'password.rehashed' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified' | 'login.new_device' | 'bot_protection.rejected' | 'grant.revoked_by_user' | 'user.created' | 'user.password_reset_sent' | 'user.disabled' | 'user.enabled' | 'user.deleted' | 'profile.updated' | 'account.deleted' | 'account.exported' | 'keys.rotated' | 'organization.created' | 'organization.updated' | 'organization.deleted' | 'organization.member_added' | 'organization.member_removed' | 'organization.member_role_changed' | 'organization.member_role_updated' | 'organization.switched' | 'organization.deactivated' | 'organization.invitation_sent' | 'organization.invitation_accepted' | 'organization.invitation_revoked' | 'email_change.requested' | 'email_change.confirmed' | 'email_change.cancelled' | 'security_notice.sent' | 'settings.updated' | 'maintenance.enabled' | 'maintenance.disabled' | 'trusted_device.revoked' | 'password.expired_change_forced' | 'otp.locked' | 'otp.unlocked' | 'otp.unlock_failed' | 'sudo.confirmed' | 'session.single_enforced' | 'account.expired_login_blocked' | 'account.expiration_warned';
+/**
+ * Evento de auditoria a registrar. O timestamp é definido pelo sink (não aqui).
+ */
+export interface AuditEvent {
+    type: AuditEventType;
+    accountId?: string | null;
+    email?: string | null;
+    clientId?: string | null;
+    /** Impersonation: quem agiu (o admin). */
+    actorId?: string | null;
+    ip?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Evento de auditoria já persistido (lido de volta pelo console admin). Carrega
+ * o id e o timestamp atribuídos pelo sink.
+ */
+export interface StoredAuditEvent extends AuditEvent {
+    id: string;
+    createdAt: Date | string | null;
+}
+/** Filtros de listagem do log de auditoria (console admin). */
+export interface ListAuditParams {
+    /** Página (1-based). Default: 1. */
+    page?: number;
+    /** Itens por página. Default: 20. */
+    limit?: number;
+    /** Filtra por tipo de evento exato. */
+    type?: string;
+    /** Filtra pelo subject (accountId) do evento. */
+    subject?: string;
+}
+/** Página de eventos + total absoluto. */
+export interface AuditPage {
+    data: StoredAuditEvent[];
+    total: number;
+}
+/**
+ * Sink plugável de auditoria. Implementações devem ser best-effort: `record`
+ * NUNCA deve lançar para dentro do caminho da request.
+ *
+ * `list` é OPCIONAL: sinks customizados podem só implementar `record` (write-only).
+ * O console admin degrada graciosamente ("consulta não suportada") quando o sink
+ * configurado não fornece `list`.
+ */
+export interface AuditSink {
+    record(event: AuditEvent): Promise<void>;
+    /** Lista eventos paginados (opcional — só sinks que suportam consulta). */
+    list?(params: ListAuditParams): Promise<AuditPage>;
+    /**
+     * Anonimiza (LGPD/GDPR) os eventos de uma conta SEM apagar o histórico: remove
+     * os identificadores pessoais (`email`, `ip`) e re-escreve o `accountId` para um
+     * pseudônimo estável (`anon:<hash>`), preservando a linha do tempo, o `type` e a
+     * forma para auditoria/forense. OPCIONAL: sinks write-only podem omitir — a
+     * deleção de conta segue funcionando (best-effort), só não anonimiza.
+     * Retorna a quantidade de linhas afetadas.
+     */
+    anonymizeAccount?(accountId: string): Promise<number>;
+}

package/build/src/audit/audit_sink.js

@@ -0,0 +1 @@
+export {};

package/build/src/audit/lucid_audit_sink.d.ts

@@ -0,0 +1,10 @@
+import type { AuditSink } from './audit_sink.js';
+/**
+ * Implementação default do {@link AuditSink} sobre um model Lucid composto de
+ * `withAuditLog()`. Insere o evento na tabela `audit_logs` e suporta consulta
+ * paginada para o console admin.
+ *
+ * BEST-EFFORT: erros de inserção são logados via `console.error` e engolidos —
+ * a auditoria nunca deve lançar para dentro do caminho da request.
+ */
+export declare function lucidAuditSink(Model: any): AuditSink;

package/build/src/audit/lucid_audit_sink.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+/**
+ * Pseudônimo estável para um accountId anonimizado: `anon:<sha256(accountId)[:16]>`.
+ * Mantém os eventos de uma conta deletada correlacionáveis ENTRE SI (mesmo
+ * pseudônimo) sem permitir reidentificar a pessoa (one-way).
+ */
+function anonId(accountId) {
+    return `anon:${createHash('sha256').update(accountId).digest('hex').slice(0, 16)}`;
+}
+/**
+ * Implementação default do {@link AuditSink} sobre um model Lucid composto de
+ * `withAuditLog()`. Insere o evento na tabela `audit_logs` e suporta consulta
+ * paginada para o console admin.
+ *
+ * BEST-EFFORT: erros de inserção são logados via `console.error` e engolidos —
+ * a auditoria nunca deve lançar para dentro do caminho da request.
+ */
+export function lucidAuditSink(Model) {
+    return {
+        async record(event) {
+            try {
+                await Model.create({
+                    type: event.type,
+                    accountId: event.accountId ?? null,
+                    email: event.email ?? null,
+                    clientId: event.clientId ?? null,
+                    actorId: event.actorId ?? null,
+                    ip: event.ip ?? null,
+                    metadata: event.metadata ?? null,
+                });
+            }
+            catch (error) {
+                // eslint-disable-next-line no-console
+                console.error('[authkit] audit sink falhou ao registrar evento', event.type, error);
+            }
+        },
+        async list(params) {
+            const page = Math.max(1, params.page ?? 1);
+            const limit = Math.max(1, params.limit ?? 20);
+            const base = () => {
+                const q = Model.query();
+                if (params.type)
+                    q.where('type', params.type);
+                if (params.subject)
+                    q.where('accountId', params.subject);
+                return q;
+            };
+            const countResult = await base().count('* as total');
+            const total = Number(countResult[0]?.$extras?.total ?? 0);
+            const rows = await base()
+                .orderBy('createdAt', 'desc')
+                .offset((page - 1) * limit)
+                .limit(limit);
+            const data = rows.map((row) => ({
+                id: String(row.id),
+                type: row.type,
+                accountId: row.accountId ?? null,
+                email: row.email ?? null,
+                clientId: row.clientId ?? null,
+                actorId: row.actorId ?? null,
+                ip: row.ip ?? null,
+                metadata: row.metadata ?? undefined,
+                // createdAt é um luxon DateTime no Lucid; normaliza para ISO string.
+                createdAt: row.createdAt?.toISO?.() ?? row.createdAt ?? null,
+            }));
+            return { data, total };
+        },
+        /**
+         * Anonimiza (LGPD/GDPR) as linhas de audit cujo subject (`accountId`) OU ator
+         * (`actorId`) é a conta dada: substitui o id pelo pseudônimo estável e zera os
+         * identificadores pessoais (`email`, `ip`). Preserva `type`, `clientId`,
+         * `metadata` e o timestamp — o histórico continua íntegro, só não é mais
+         * reidentificável. Best-effort: erros são logados e engolidos (retorna 0).
+         */
+        async anonymizeAccount(accountId) {
+            if (!accountId)
+                return 0;
+            const pseudonym = anonId(accountId);
+            try {
+                // accountId === conta deletada → subject.
+                const asSubject = await Model.query()
+                    .where('accountId', accountId)
+                    .update({ accountId: pseudonym, email: null, ip: null });
+                // actorId === conta deletada (ações que ela fez como admin) → ator.
+                const asActor = await Model.query()
+                    .where('actorId', accountId)
+                    .update({ actorId: pseudonym });
+                // O retorno do update varia por dialeto (número ou array). Normaliza.
+                const n = (v) => (Array.isArray(v) ? Number(v[0] ?? 0) : Number(v ?? 0));
+                return n(asSubject) + n(asActor);
+            }
+            catch (error) {
+                // eslint-disable-next-line no-console
+                console.error('[authkit] audit sink falhou ao anonimizar conta', accountId, error);
+                return 0;
+            }
+        },
+    };
+}

package/build/src/commands/expire_scan_command.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Ace command: `authkit:accounts:expire-scan`
+ *
+ * Varre contas para detectar expiração por inatividade (account_expiration setting).
+ *
+ * Mecânica honesta:
+ *   - "Última atividade" = último `login.success` da conta no audit (list capability).
+ *   - Sem audit queryável → aborta com aviso (feature indisponível).
+ *   - Usa `audit.list({ type: 'login.success', subject: accountId })` por conta — de
+ *     forma paginada sobre `accountStore.listAccounts`. Esse padrão é O(accounts) em
+ *     queries ao audit, o que é compatível com volumes moderados (<= 50k contas).
+ *     Para volumes maiores, o operador deve implementar um sink com agregação nativa.
+ *   - `--warn`: envia e-mail de aviso ("sua conta expira em N dias — faça login") via
+ *     hook `mail.onAccountExpirationWarning` + template default. Deduplicado via
+ *     audit `account.expiration_warned` — não re-avisa quem já foi avisado dentro
+ *     da janela de `warnDays` dias.
+ *   - `--dry-run`: reporta sem enviar e-mails nem auditar.
+ *   - `--json`: output machine-readable.
+ *
+ * Designed pra cron do host (ex.: `0 2 * * * node ace authkit:accounts:expire-scan --warn`).
+ */
+import type { ApplicationService } from '@adonisjs/core/types';
+export interface ExpireScanResult {
+    /** Contas já expiradas (bloqueadas no login). */
+    expired: Array<{
+        accountId: string;
+        email: string;
+        lastActivityDaysAgo: number | null;
+    }>;
+    /** Contas a expirar em até warnDays dias. */
+    warnSoon: Array<{
+        accountId: string;
+        email: string;
+        expiresInDays: number;
+    }>;
+    /** Avisos enviados por e-mail (quando --warn). */
+    warned: number;
+    /** Contas ignoradas por já terem sido avisadas na janela. */
+    deduped: number;
+    /** Resumo do scan. */
+    summary: {
+        scanned: number;
+        expired: number;
+        warnSoon: number;
+        inactiveDays: number;
+        warnDays: number;
+        auditSupported: boolean;
+        dryRun: boolean;
+    };
+}
+export declare function runExpireScan(app: ApplicationService, opts: {
+    dryRun?: boolean;
+    warn?: boolean;
+    json?: boolean;
+    logger: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+        error: (m: string) => void;
+    };
+}): Promise<ExpireScanResult>;

package/build/src/commands/expire_scan_command.js

@@ -0,0 +1,229 @@
+/**
+ * Ace command: `authkit:accounts:expire-scan`
+ *
+ * Varre contas para detectar expiração por inatividade (account_expiration setting).
+ *
+ * Mecânica honesta:
+ *   - "Última atividade" = último `login.success` da conta no audit (list capability).
+ *   - Sem audit queryável → aborta com aviso (feature indisponível).
+ *   - Usa `audit.list({ type: 'login.success', subject: accountId })` por conta — de
+ *     forma paginada sobre `accountStore.listAccounts`. Esse padrão é O(accounts) em
+ *     queries ao audit, o que é compatível com volumes moderados (<= 50k contas).
+ *     Para volumes maiores, o operador deve implementar um sink com agregação nativa.
+ *   - `--warn`: envia e-mail de aviso ("sua conta expira em N dias — faça login") via
+ *     hook `mail.onAccountExpirationWarning` + template default. Deduplicado via
+ *     audit `account.expiration_warned` — não re-avisa quem já foi avisado dentro
+ *     da janela de `warnDays` dias.
+ *   - `--dry-run`: reporta sem enviar e-mails nem auditar.
+ *   - `--json`: output machine-readable.
+ *
+ * Designed pra cron do host (ex.: `0 2 * * * node ace authkit:accounts:expire-scan --warn`).
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { resolveAuthkitConfig } from './resolve_config.js';
+import { RuntimeSettings } from '../host/runtime_settings.js';
+import { resolveEffectiveAccountExpiration } from '../host/runtime_toggles.js';
+// ---------------------------------------------------------------------------
+// Core logic (pura, testável sem Ace)
+// ---------------------------------------------------------------------------
+export async function runExpireScan(app, opts) {
+    const { dryRun = false, warn = false, logger } = opts;
+    // ---- resolve config ----
+    const raw = app.config?.get?.('authkit') ?? null;
+    const cfg = await resolveAuthkitConfig(app, raw);
+    if (!cfg) {
+        logger.error('[expire-scan] Could not resolve authkit config.');
+        return emptyResult(dryRun, 0, 0);
+    }
+    const accountStore = cfg.accountStore;
+    const audit = cfg.audit;
+    // ---- audit capability check ----
+    if (typeof audit?.list !== 'function') {
+        logger.warn('[expire-scan] Audit sink does not support list(). Account expiration requires a queryable audit (e.g. lucidAuditSink). Feature unavailable.');
+        return emptyResult(dryRun, 0, 0, false);
+    }
+    // ---- resolve setting ----
+    let runtimeSettings = null;
+    try {
+        const db = await app.container.make('lucid.db');
+        const connection = accountStore?.connectionName;
+        runtimeSettings = new RuntimeSettings(db, connection ? { connection } : {});
+    }
+    catch {
+        // Sem DB → usa defaults.
+    }
+    const expiration = runtimeSettings
+        ? await resolveEffectiveAccountExpiration(runtimeSettings)
+        : { enabled: false, inactiveDays: 365, warnDays: 14 };
+    if (!expiration.enabled && !dryRun) {
+        logger.warn('[expire-scan] account_expiration setting is disabled. Pass --dry-run to scan anyway.');
+        return emptyResult(dryRun, expiration.inactiveDays, expiration.warnDays);
+    }
+    const { inactiveDays, warnDays } = expiration;
+    const nowMs = Date.now();
+    const expiryCutoffMs = nowMs - inactiveDays * 24 * 60 * 60 * 1000;
+    const warnCutoffMs = nowMs - (inactiveDays - warnDays) * 24 * 60 * 60 * 1000;
+    // ---- scan accounts ----
+    const expired = [];
+    const warnSoon = [];
+    let warnedCount = 0;
+    let dedupedCount = 0;
+    let scanned = 0;
+    let page = 1;
+    const limit = 100;
+    while (true) {
+        const batch = await accountStore.listAccounts({ page, limit });
+        if (batch.data.length === 0)
+            break;
+        for (const account of batch.data) {
+            scanned++;
+            const lastMs = await getLastLoginMs(audit, account.id);
+            if (lastMs === null) {
+                // Nunca logou → trata como ativa (conta nova).
+                continue;
+            }
+            const daysAgo = (nowMs - lastMs) / (24 * 60 * 60 * 1000);
+            if (lastMs < expiryCutoffMs) {
+                // Expirada.
+                expired.push({
+                    accountId: account.id,
+                    email: account.email,
+                    lastActivityDaysAgo: Math.floor(daysAgo),
+                });
+            }
+            else if (warnDays > 0 && lastMs < warnCutoffMs) {
+                // A expirar em breve.
+                const daysUntilExpiry = Math.ceil((lastMs + inactiveDays * 24 * 60 * 60 * 1000 - nowMs) / (24 * 60 * 60 * 1000));
+                warnSoon.push({ accountId: account.id, email: account.email, expiresInDays: daysUntilExpiry });
+                if (warn && !dryRun) {
+                    // Verifica se já foi avisado dentro da janela de warnDays dias.
+                    const alreadyWarned = await wasWarnedRecently(audit, account.id, warnDays);
+                    if (alreadyWarned) {
+                        dedupedCount++;
+                    }
+                    else {
+                        // Envia e-mail de aviso.
+                        await sendWarnEmail(cfg, account, daysUntilExpiry);
+                        // Audita para deduplicação.
+                        await audit.record({
+                            type: 'account.expiration_warned',
+                            accountId: account.id,
+                            email: account.email,
+                            metadata: { expiresInDays: daysUntilExpiry },
+                        });
+                        warnedCount++;
+                    }
+                }
+            }
+        }
+        if (batch.data.length < limit)
+            break;
+        page++;
+    }
+    const result = {
+        expired,
+        warnSoon,
+        warned: warnedCount,
+        deduped: dedupedCount,
+        summary: {
+            scanned,
+            expired: expired.length,
+            warnSoon: warnSoon.length,
+            inactiveDays,
+            warnDays,
+            auditSupported: true,
+            dryRun,
+        },
+    };
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Retorna o timestamp em ms do último login.success da conta, ou null se nunca logou. */
+async function getLastLoginMs(audit, accountId) {
+    try {
+        const result = await audit.list({ type: 'login.success', subject: accountId, page: 1, limit: 1 });
+        if (result.data.length === 0)
+            return null;
+        const createdAt = result.data[0].createdAt;
+        if (!createdAt)
+            return null;
+        const ms = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verifica se a conta já foi avisada sobre expiração dentro da janela de `warnDays` dias.
+ * Usa o audit `account.expiration_warned` para deduplicação.
+ */
+async function wasWarnedRecently(audit, accountId, warnDays) {
+    try {
+        const result = await audit.list({ type: 'account.expiration_warned', subject: accountId, page: 1, limit: 1 });
+        if (result.data.length === 0)
+            return false;
+        const lastWarned = result.data[0].createdAt;
+        if (!lastWarned)
+            return false;
+        const lastMs = lastWarned instanceof Date ? lastWarned.getTime() : Date.parse(lastWarned);
+        if (!Number.isFinite(lastMs))
+            return false;
+        const windowMs = warnDays * 24 * 60 * 60 * 1000;
+        return Date.now() - lastMs < windowMs;
+    }
+    catch {
+        return false;
+    }
+}
+/** Envia e-mail de aviso de expiração iminente. Best-effort (silencioso em caso de erro). */
+async function sendWarnEmail(cfg, account, expiresInDays) {
+    try {
+        if (cfg.mail?.onAccountExpirationWarning) {
+            await cfg.mail.onAccountExpirationWarning({ email: account.email, expiresInDays });
+            return;
+        }
+        // Default: tenta via @adonisjs/mail se disponível.
+        const mailSpecifier = '@adonisjs/mail/services/main';
+        const mailMod = await import(__rewriteRelativeImportExtension(mailSpecifier)).catch(() => null);
+        const mail = mailMod?.default ?? null;
+        if (!mail)
+            return; // Sem mail configurado — silêncio.
+        await mail.send((message) => {
+            message
+                .to(account.email)
+                .subject(`Your account will be deactivated due to inactivity`)
+                .html(`<p>Your account will be deactivated in <strong>${expiresInDays} day(s)</strong> due to inactivity. Sign in to keep your account active.</p>`)
+                .text(`Your account will be deactivated in ${expiresInDays} day(s) due to inactivity. Sign in to keep your account active.`);
+        });
+    }
+    catch {
+        // Best-effort: nunca propaga erros de e-mail.
+    }
+}
+function emptyResult(dryRun, inactiveDays, warnDays, auditSupported = false) {
+    return {
+        expired: [],
+        warnSoon: [],
+        warned: 0,
+        deduped: 0,
+        summary: {
+            scanned: 0,
+            expired: 0,
+            warnSoon: 0,
+            inactiveDays,
+            warnDays,
+            auditSupported,
+            dryRun,
+        },
+    };
+}