@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,119 @@
+import type { OidcService } from '../provider/oidc_service.js';
+/** Uma sessão ativa do IdP (login do usuário no provider), apresentada ao admin. */
+export interface AdminSession {
+    /** Id do artefato `Session` no adapter. */
+    id: string;
+    accountId: string;
+    /**
+     * Email da conta — resolvido pelo `listAllSessions()` na listagem global.
+     * Ausente em `listSessions(accountId)` (já é implícito pelo contexto).
+     */
+    email?: string | null;
+    /** Epoch (segundos) do login, quando presente no payload. */
+    loginTs?: number;
+    /** Métodos de autenticação registrados na sessão (amr), quando presentes. */
+    amr?: string[];
+    /**
+     * User-agent bruto do login, recuperado do audit `login.success` por join
+     * accountId+loginTs ({@link enrichSessionsWithContext}). Ausente quando o sink de
+     * auditoria não consulta ou não há evento correlacionável.
+     */
+    userAgent?: string | null;
+    /** Família do browser derivada do user-agent (ex.: 'Chrome'). */
+    browser?: string | null;
+    /** Sistema operacional derivado do user-agent (ex.: 'macOS'). */
+    os?: string | null;
+    /** IP do login (do mesmo audit `login.success`). */
+    ip?: string | null;
+    /** Localização legível resolvida via o hook `resolveGeo` (null sem hook/resolução). */
+    location?: string | null;
+}
+/** Um grant (autorização concedida a um client), com a contagem de tokens vivos. */
+export interface AdminGrant {
+    /** Id do artefato `Grant` no adapter (== grantId dos tokens). */
+    id: string;
+    accountId: string;
+    clientId?: string;
+    /** Tokens de acesso vivos que referenciam este grant. */
+    accessTokens: number;
+    /** Refresh tokens vivos que referenciam este grant. */
+    refreshTokens: number;
+}
+/** Resultado de uma revogação em massa das sessões/grants de uma conta. */
+export interface RevokeResult {
+    sessions: number;
+    grants: number;
+    accessTokens: number;
+    refreshTokens: number;
+}
+export declare class AdminSessionsService {
+    #private;
+    constructor(oidc: OidcService);
+    /**
+     * Grava uma revogação por `sub` na tabela compartilhada `auth_session_revocations`,
+     * para que clients COOKIE-BASED (que não têm store de sessão server-side) derrubem
+     * a sessão na próxima request — INSTANTÂNEO, sem esperar o refresh token falhar.
+     *
+     * Best-effort: a destruição de grants/tokens acima já é a fonte da verdade; esta
+     * linha só acelera o efeito nos clients. Falha (tabela ausente) é silenciosa.
+     *
+     * @param accountId Conta cujas sessões devem ser derrubadas (gravado em `sub`).
+     * @param revokedAt Timestamp da revogação. Default: agora. A checagem do client
+     *   é `revoked_at >= iat(id_token)` (em segundos): uma sessão só é derrubada se
+     *   foi estabelecida ANTES (ou no mesmo segundo) da revogação. O
+     *   {@link revokeAllExcept} passa um `revokedAt` ANTERIOR ao `iat` da sessão
+     *   PRESERVADA, para que esta NÃO se auto-derrube (ver lá).
+     */
+    protected recordSubRevocation(accountId: string, revokedAt?: Date): Promise<void>;
+    /** Indica se o adapter suporta enumeração (capacidade opcional). */
+    get canList(): boolean;
+    /**
+     * Conta TODAS as sessões ativas do IdP (todas as contas). 0 quando o adapter não
+     * enumera. Usado pelo dashboard de métricas.
+     */
+    countActiveSessions(): Promise<number>;
+    /** Lista as sessões ativas da conta (vazio quando o adapter não enumera). */
+    listSessions(accountId: string): Promise<AdminSession[]>;
+    /**
+     * Lista TODAS as sessões ativas de TODAS as contas — usada pela listagem global
+     * do console admin (sem `accountId`). Resolve o email de cada conta via
+     * `accountStore.findById` com cache por id (evita N+1). Limita a
+     * {@link GLOBAL_SESSION_LIMIT} entradas; quando truncado, inclui `truncated:true`
+     * nos metadados (accessível via `result.truncated`). Retorna vazio quando o
+     * adapter não enumera.
+     */
+    listAllSessions(): Promise<{
+        sessions: AdminSession[];
+        truncated: boolean;
+    }>;
+    /**
+     * Lista os grants da conta, com a contagem de access/refresh tokens vivos que
+     * referenciam cada grant (`payload.grantId`). As contagens são baratas (uma
+     * enumeração de cada model token), feitas só quando o adapter enumera.
+     */
+    listGrants(accountId: string): Promise<AdminGrant[]>;
+    /**
+     * Revoga todas as sessões e grants da conta EXCETO a sessão corrente (pelo id).
+     * Usado pela política single-session: após login, revoga todas as outras sessões
+     * preservando a recém-criada. Retorna as contagens do que foi removido.
+     *
+     * @param accountId Id da conta.
+     * @param exceptSessionId Id da sessão OIDC a preservar (a sessão corrente).
+     */
+    revokeAllExcept(accountId: string, exceptSessionId: string): Promise<RevokeResult>;
+    /**
+     * Revoga TODAS as sessões e grants da conta. Destruir os grants já invalida os
+     * tokens (cascata via `grant not found`); ainda assim, quando o adapter enumera,
+     * destruímos explicitamente as linhas de AT/RT desses grants (belt-and-braces),
+     * deixando o store limpo. Retorna as contagens do que foi removido.
+     */
+    revokeAll(accountId: string): Promise<RevokeResult>;
+    /**
+     * Revoga os grants de uma conta para UM client específico (+ tokens ligados),
+     * deixando os demais clients intactos. Reaproveita a lógica de {@link revokeAll}
+     * restrita ao `clientId`. Usado pelo self-service de consentimento
+     * (/account/apps) e por qualquer revogação granular do admin. Retorna as
+     * contagens do que foi removido.
+     */
+    revokeClientGrants(accountId: string, clientId: string): Promise<RevokeResult>;
+}

package/build/src/host/admin_sessions_service.js

@@ -0,0 +1,284 @@
+/**
+ * Serviço de inspeção/revogação das SESSÕES e GRANTS ativos de uma conta,
+ * persistidos pelo oidc-provider via o MESMO `AdapterClass` (mesmo padrão do
+ * {@link AdminClientsService}). Encapsula:
+ *   - a enumeração via a capacidade opcional `list` do adapter (degrada quando
+ *     ausente, igual ao CRUD de clients);
+ *   - a destruição das sessões + grants da conta. Destruir um grant CASCATEIA a
+ *     invalidação dos tokens no oidc-provider: os consumidores de access/refresh
+ *     token carregam `Grant.find(token.grantId)` e lançam `InvalidToken('grant not
+ *     found')` quando o grant some (verificado em oidc-provider v9). Mesmo assim,
+ *     por garantia (belt-and-braces), também destruímos as linhas de AT/RT que
+ *     referenciam os grants revogados quando o adapter enumera.
+ */
+/** Limite máximo de sessões retornadas na listagem global (proteção contra explosão de memória). */
+const GLOBAL_SESSION_LIMIT = 500;
+export class AdminSessionsService {
+    #AdapterClass;
+    #accountStore;
+    /** Conexão Lucid das tabelas authkit (schema `auth`) — onde vive auth_session_revocations. */
+    #schemaConnection;
+    constructor(oidc) {
+        this.#AdapterClass = oidc.config.AdapterClass;
+        this.#accountStore = oidc.config.accountStore;
+        this.#schemaConnection = oidc.config.schema?.connection;
+    }
+    #adapter(model) {
+        return new this.#AdapterClass(model);
+    }
+    /**
+     * Grava uma revogação por `sub` na tabela compartilhada `auth_session_revocations`,
+     * para que clients COOKIE-BASED (que não têm store de sessão server-side) derrubem
+     * a sessão na próxima request — INSTANTÂNEO, sem esperar o refresh token falhar.
+     *
+     * Best-effort: a destruição de grants/tokens acima já é a fonte da verdade; esta
+     * linha só acelera o efeito nos clients. Falha (tabela ausente) é silenciosa.
+     *
+     * @param accountId Conta cujas sessões devem ser derrubadas (gravado em `sub`).
+     * @param revokedAt Timestamp da revogação. Default: agora. A checagem do client
+     *   é `revoked_at >= iat(id_token)` (em segundos): uma sessão só é derrubada se
+     *   foi estabelecida ANTES (ou no mesmo segundo) da revogação. O
+     *   {@link revokeAllExcept} passa um `revokedAt` ANTERIOR ao `iat` da sessão
+     *   PRESERVADA, para que esta NÃO se auto-derrube (ver lá).
+     */
+    async recordSubRevocation(accountId, revokedAt = new Date()) {
+        try {
+            const db = (await import('@adonisjs/lucid/services/db')).default;
+            const conn = this.#schemaConnection
+                ? db.connection(this.#schemaConnection)
+                : db.connection();
+            await conn.insertQuery().table('auth_session_revocations').insert({
+                sid: null,
+                sub: accountId,
+                revoked_at: revokedAt,
+            });
+        }
+        catch {
+            /* tabela ausente / lucid indisponível — a invalidação server-side ainda vale */
+        }
+    }
+    /** Indica se o adapter suporta enumeração (capacidade opcional). */
+    get canList() {
+        return typeof this.#adapter('Session').list === 'function';
+    }
+    async #listModel(model) {
+        const adapter = this.#adapter(model);
+        if (!adapter.list)
+            return [];
+        return adapter.list();
+    }
+    /**
+     * Conta TODAS as sessões ativas do IdP (todas as contas). 0 quando o adapter não
+     * enumera. Usado pelo dashboard de métricas.
+     */
+    async countActiveSessions() {
+        const rows = await this.#listModel('Session');
+        return rows.length;
+    }
+    /** Lista as sessões ativas da conta (vazio quando o adapter não enumera). */
+    async listSessions(accountId) {
+        const rows = await this.#listModel('Session');
+        return rows
+            .filter((r) => r.payload.accountId === accountId)
+            .map((r) => ({
+            id: r.id,
+            accountId,
+            loginTs: r.payload.loginTs,
+            amr: r.payload.amr ?? undefined,
+        }));
+    }
+    /**
+     * Lista TODAS as sessões ativas de TODAS as contas — usada pela listagem global
+     * do console admin (sem `accountId`). Resolve o email de cada conta via
+     * `accountStore.findById` com cache por id (evita N+1). Limita a
+     * {@link GLOBAL_SESSION_LIMIT} entradas; quando truncado, inclui `truncated:true`
+     * nos metadados (accessível via `result.truncated`). Retorna vazio quando o
+     * adapter não enumera.
+     */
+    async listAllSessions() {
+        const rows = await this.#listModel('Session');
+        const truncated = rows.length > GLOBAL_SESSION_LIMIT;
+        const slice = truncated ? rows.slice(0, GLOBAL_SESSION_LIMIT) : rows;
+        // Cache accountId → email para evitar N+1
+        const emailCache = new Map();
+        const resolveEmail = async (accountId) => {
+            if (emailCache.has(accountId))
+                return emailCache.get(accountId);
+            const account = await this.#accountStore.findById(accountId);
+            const email = account?.email ?? null;
+            emailCache.set(accountId, email);
+            return email;
+        };
+        const sessions = await Promise.all(slice.map(async (r) => {
+            const accountId = r.payload.accountId ?? '';
+            const email = accountId ? await resolveEmail(accountId) : null;
+            return {
+                id: r.id,
+                accountId,
+                email,
+                loginTs: r.payload.loginTs,
+                amr: r.payload.amr ?? undefined,
+            };
+        }));
+        return { sessions, truncated };
+    }
+    /**
+     * Lista os grants da conta, com a contagem de access/refresh tokens vivos que
+     * referenciam cada grant (`payload.grantId`). As contagens são baratas (uma
+     * enumeração de cada model token), feitas só quando o adapter enumera.
+     */
+    async listGrants(accountId) {
+        const rows = await this.#listModel('Grant');
+        const grants = rows.filter((r) => r.payload.accountId === accountId);
+        if (grants.length === 0)
+            return [];
+        const atByGrant = await this.#countByGrant('AccessToken');
+        const rtByGrant = await this.#countByGrant('RefreshToken');
+        return grants.map((g) => ({
+            id: g.id,
+            accountId,
+            clientId: g.payload.clientId,
+            accessTokens: atByGrant.get(g.id) ?? 0,
+            refreshTokens: rtByGrant.get(g.id) ?? 0,
+        }));
+    }
+    /** Conta artefatos de um model token agrupados por `grantId`. */
+    async #countByGrant(model) {
+        const rows = await this.#listModel(model);
+        const map = new Map();
+        for (const r of rows) {
+            const gid = r.payload.grantId;
+            if (!gid)
+                continue;
+            map.set(gid, (map.get(gid) ?? 0) + 1);
+        }
+        return map;
+    }
+    /**
+     * Revoga todas as sessões e grants da conta EXCETO a sessão corrente (pelo id).
+     * Usado pela política single-session: após login, revoga todas as outras sessões
+     * preservando a recém-criada. Retorna as contagens do que foi removido.
+     *
+     * @param accountId Id da conta.
+     * @param exceptSessionId Id da sessão OIDC a preservar (a sessão corrente).
+     */
+    async revokeAllExcept(accountId, exceptSessionId) {
+        const sessionAdapter = this.#adapter('Session');
+        const grantAdapter = this.#adapter('Grant');
+        const sessions = await this.listSessions(accountId);
+        const preserved = sessions.find((s) => s.id === exceptSessionId);
+        const sessionsToRevoke = sessions.filter((s) => s.id !== exceptSessionId);
+        for (const s of sessionsToRevoke) {
+            await sessionAdapter.destroy(s.id);
+        }
+        // Revogamos todos os grants da conta (que pertencem à conta, não à sessão
+        // específica). A sessão corrente gerará novos grants no próximo authorize.
+        // Isso garante que sessões antigas não mantenham tokens vivos.
+        const grants = await this.listGrants(accountId);
+        const grantIds = new Set(grants.map((g) => g.id));
+        let accessTokens = 0;
+        let refreshTokens = 0;
+        accessTokens = await this.#destroyTokensOfGrants('AccessToken', grantIds);
+        refreshTokens = await this.#destroyTokensOfGrants('RefreshToken', grantIds);
+        for (const g of grants) {
+            await grantAdapter.revokeByGrantId(g.id);
+            await grantAdapter.destroy(g.id);
+        }
+        // M7: propaga a revogação por `sub` para clients COOKIE-BASED (instantâneo),
+        // igual ao revokeAll. Sem isto, o 1º dispositivo só cai quando o AT expira.
+        //
+        // Ordem do `iat` (CUIDADO): a sessão PRESERVADA já existe aqui (foi criada no
+        // completeLogin ANTES desta revogação), com `loginTs` (== iat do id_token) em
+        // segundos. A checagem do client é `revoked_at >= iat`. Se gravássemos
+        // `revoked_at = now`, como `now >= iat_preservada`, a sessão NOVA se
+        // auto-derrubaria. Por isso ancoramos `revoked_at` ESTRITAMENTE ANTES do
+        // `iat` da sessão preservada (`loginTs - 1s`): as sessões antigas (iat menor)
+        // continuam sendo apanhadas (`revoked_at >= iat_antiga`), enquanto a nova
+        // (iat = loginTs) sobrevive (`revoked_at < iat_nova`).
+        //
+        // Sem sessão preservada (exceptSessionId não encontrado / sem loginTs), caímos
+        // no default (`now`) — não há sessão nova a proteger nesse caminho.
+        const cutoff = typeof preserved?.loginTs === 'number'
+            ? new Date((preserved.loginTs - 1) * 1000)
+            : undefined;
+        await this.recordSubRevocation(accountId, cutoff);
+        return {
+            sessions: sessionsToRevoke.length,
+            grants: grants.length,
+            accessTokens,
+            refreshTokens,
+        };
+    }
+    /**
+     * Revoga TODAS as sessões e grants da conta. Destruir os grants já invalida os
+     * tokens (cascata via `grant not found`); ainda assim, quando o adapter enumera,
+     * destruímos explicitamente as linhas de AT/RT desses grants (belt-and-braces),
+     * deixando o store limpo. Retorna as contagens do que foi removido.
+     */
+    async revokeAll(accountId) {
+        const sessionAdapter = this.#adapter('Session');
+        const grantAdapter = this.#adapter('Grant');
+        const sessions = await this.listSessions(accountId);
+        for (const s of sessions) {
+            await sessionAdapter.destroy(s.id);
+        }
+        const grants = await this.listGrants(accountId);
+        const grantIds = new Set(grants.map((g) => g.id));
+        let accessTokens = 0;
+        let refreshTokens = 0;
+        // Belt-and-braces: destrói as linhas de token que referenciam os grants alvo
+        // ANTES de destruir os grants (quando o adapter enumera).
+        accessTokens = await this.#destroyTokensOfGrants('AccessToken', grantIds);
+        refreshTokens = await this.#destroyTokensOfGrants('RefreshToken', grantIds);
+        for (const g of grants) {
+            // `revokeByGrantId` derruba os artefatos ligados ao grant (no Redis isso
+            // limpa a lista do grant; no DB apaga as linhas com `grant_id`); `destroy`
+            // remove o próprio artefato `Grant`.
+            await grantAdapter.revokeByGrantId(g.id);
+            await grantAdapter.destroy(g.id);
+        }
+        // Revogação total → propaga p/ clients cookie-based via tabela compartilhada (instantâneo).
+        await this.recordSubRevocation(accountId);
+        return {
+            sessions: sessions.length,
+            grants: grants.length,
+            accessTokens,
+            refreshTokens,
+        };
+    }
+    /**
+     * Revoga os grants de uma conta para UM client específico (+ tokens ligados),
+     * deixando os demais clients intactos. Reaproveita a lógica de {@link revokeAll}
+     * restrita ao `clientId`. Usado pelo self-service de consentimento
+     * (/account/apps) e por qualquer revogação granular do admin. Retorna as
+     * contagens do que foi removido.
+     */
+    async revokeClientGrants(accountId, clientId) {
+        const grantAdapter = this.#adapter('Grant');
+        const grants = (await this.listGrants(accountId)).filter((g) => g.clientId === clientId);
+        const grantIds = new Set(grants.map((g) => g.id));
+        const accessTokens = await this.#destroyTokensOfGrants('AccessToken', grantIds);
+        const refreshTokens = await this.#destroyTokensOfGrants('RefreshToken', grantIds);
+        for (const g of grants) {
+            await grantAdapter.revokeByGrantId(g.id);
+            await grantAdapter.destroy(g.id);
+        }
+        return { sessions: 0, grants: grants.length, accessTokens, refreshTokens };
+    }
+    /** Destrói (quando enumerável) os artefatos de um model token cujos grantId estão em `grantIds`. */
+    async #destroyTokensOfGrants(model, grantIds) {
+        const adapter = this.#adapter(model);
+        if (!adapter.list)
+            return 0;
+        const rows = await adapter.list();
+        let count = 0;
+        for (const r of rows) {
+            const gid = r.payload.grantId;
+            if (gid && grantIds.has(gid)) {
+                await adapter.destroy(r.id);
+                count++;
+            }
+        }
+        return count;
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+/** Um ponto de série diária (dia ISO `YYYY-MM-DD` + contagem). */
+export interface DailyPoint {
+    /** Data no formato `YYYY-MM-DD` (UTC). */
+    date: string;
+    count: number;
+}
+/** Métricas-resumo do IdP para o dashboard do console admin. */
+export interface AdminStats {
+    /** Total de contas (do accountStore). */
+    totalUsers: number;
+    /** Sessões ativas (Session enumeradas no adapter); null quando o adapter não enumera. */
+    activeSessions: number | null;
+    /** Monthly Active Users: contas únicas com login.success nos últimos 30 dias. */
+    mau: number;
+    /** Sign-ins por dia (login.success) nos últimos 30 dias. */
+    signInsPerDay: DailyPoint[];
+    /** Sign-ups por dia (signup) nos últimos 30 dias. */
+    signUpsPerDay: DailyPoint[];
+    /** Total de sign-ins na janela de 30 dias. */
+    signInsTotal: number;
+    /** Total de sign-ups na janela de 30 dias. */
+    signUpsTotal: number;
+    /** Indica se o audit suporta consulta (`list`). Quando false, as séries vêm vazias. */
+    auditSupported: boolean;
+    /** Quantos dias a janela cobre (30). */
+    windowDays: number;
+}
+/**
+ * Agrega métricas do IdP para o dashboard. CAPABILITY-PROBED: a fonte das séries é
+ * o audit store via `list` — quando ausente, as séries/MAU degradam para vazio/0 e
+ * `auditSupported=false` (a UI mostra "consulta não suportada"). As sessões ativas
+ * vêm da enumeração do adapter OIDC (null quando o adapter não enumera).
+ *
+ * LIMITAÇÃO: a agregação é em memória sobre as {@link MAX_EVENTS} linhas mais
+ * recentes de cada tipo (o `AuditSink` não expõe agregação por dia/distinct). Em
+ * volumes muito altos a janela pode não cobrir os 30 dias inteiros; documentado e
+ * suficiente para um dashboard. Um sink customizado pode implementar agregação
+ * nativa e expor um `stats()` próprio no futuro.
+ */
+export declare function computeAdminStats(cfg: Pick<ResolvedServerConfig, 'audit' | 'accountStore'>, sessionsService: {
+    canList: boolean;
+    countActiveSessions(): Promise<number>;
+}): Promise<AdminStats>;

package/build/src/host/admin_stats_service.js

@@ -0,0 +1,130 @@
+/** Janela de agregação (dias). */
+const WINDOW_DAYS = 30;
+/**
+ * Teto de eventos lidos do audit por tipo na agregação em memória. O sink default
+ * (Lucid) não tem agregação SQL exposta, então listamos as N linhas mais recentes e
+ * agregamos aqui. 10000 cobre ~333 logins/dia por 30 dias com folga.
+ */
+const MAX_EVENTS = 10000;
+/**
+ * Agrega métricas do IdP para o dashboard. CAPABILITY-PROBED: a fonte das séries é
+ * o audit store via `list` — quando ausente, as séries/MAU degradam para vazio/0 e
+ * `auditSupported=false` (a UI mostra "consulta não suportada"). As sessões ativas
+ * vêm da enumeração do adapter OIDC (null quando o adapter não enumera).
+ *
+ * LIMITAÇÃO: a agregação é em memória sobre as {@link MAX_EVENTS} linhas mais
+ * recentes de cada tipo (o `AuditSink` não expõe agregação por dia/distinct). Em
+ * volumes muito altos a janela pode não cobrir os 30 dias inteiros; documentado e
+ * suficiente para um dashboard. Um sink customizado pode implementar agregação
+ * nativa e expor um `stats()` próprio no futuro.
+ */
+export async function computeAdminStats(cfg, sessionsService) {
+    const totalUsers = (await cfg.accountStore.listAccounts({ page: 1, limit: 1 })).total;
+    const activeSessions = sessionsService.canList
+        ? await sessionsService.countActiveSessions()
+        : null;
+    const auditSupported = typeof cfg.audit?.list === 'function';
+    if (!auditSupported) {
+        return {
+            totalUsers,
+            activeSessions,
+            mau: 0,
+            signInsPerDay: emptySeries(),
+            signUpsPerDay: emptySeries(),
+            signInsTotal: 0,
+            signUpsTotal: 0,
+            auditSupported: false,
+            windowDays: WINDOW_DAYS,
+        };
+    }
+    const windowStartMs = startOfWindowMs();
+    const signIns = await loadEventsInWindow(cfg.audit, 'login.success', windowStartMs);
+    const signUps = await loadEventsInWindow(cfg.audit, 'signup', windowStartMs);
+    // MAU: contas únicas com algum login.success na janela.
+    const mauSet = new Set();
+    for (const e of signIns) {
+        if (e.accountId)
+            mauSet.add(e.accountId);
+    }
+    return {
+        totalUsers,
+        activeSessions,
+        mau: mauSet.size,
+        signInsPerDay: bucketByDay(signIns),
+        signUpsPerDay: bucketByDay(signUps),
+        signInsTotal: signIns.length,
+        signUpsTotal: signUps.length,
+        auditSupported: true,
+        windowDays: WINDOW_DAYS,
+    };
+}
+/**
+ * Carrega (paginando) os eventos de um tipo dentro da janela, com teto de
+ * {@link MAX_EVENTS}. Para assim que a página vier mais antiga que a janela (o sink
+ * lista desc por createdAt) ou ao atingir o teto.
+ */
+async function loadEventsInWindow(audit, type, windowStartMs) {
+    const out = [];
+    const limit = 200;
+    let page = 1;
+    while (out.length < MAX_EVENTS) {
+        const result = await audit.list({ type, page, limit });
+        if (result.data.length === 0)
+            break;
+        let allBelowWindow = true;
+        for (const e of result.data) {
+            const tsMs = toMs(e.createdAt);
+            if (tsMs === null)
+                continue;
+            if (tsMs >= windowStartMs) {
+                allBelowWindow = false;
+                out.push({ accountId: e.accountId ?? null, tsMs });
+                if (out.length >= MAX_EVENTS)
+                    break;
+            }
+        }
+        // Página inteira anterior à janela → não há mais nada relevante (ordem desc).
+        if (allBelowWindow)
+            break;
+        if (result.data.length < limit)
+            break;
+        page += 1;
+    }
+    return out;
+}
+/** Agrupa eventos por dia (UTC `YYYY-MM-DD`), preenchendo TODOS os dias da janela com 0. */
+function bucketByDay(events) {
+    const counts = new Map();
+    for (const e of events) {
+        const day = dayKey(e.tsMs);
+        counts.set(day, (counts.get(day) ?? 0) + 1);
+    }
+    return seriesDays().map((date) => ({ date, count: counts.get(date) ?? 0 }));
+}
+/** Série de 30 dias vazia (todos os dias com 0), p/ o degrade sem audit. */
+function emptySeries() {
+    return seriesDays().map((date) => ({ date, count: 0 }));
+}
+/** Os WINDOW_DAYS dias da janela (do mais antigo ao hoje), `YYYY-MM-DD` UTC. */
+function seriesDays() {
+    const days = [];
+    const todayMs = Date.now();
+    for (let i = WINDOW_DAYS - 1; i >= 0; i--) {
+        days.push(dayKey(todayMs - i * 86400000));
+    }
+    return days;
+}
+function startOfWindowMs() {
+    // Início (00:00 UTC) do primeiro dia da janela.
+    const firstDay = seriesDays()[0];
+    return Date.parse(`${firstDay}T00:00:00.000Z`);
+}
+function dayKey(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function toMs(createdAt) {
+    if (!createdAt)
+        return null;
+    const ms = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+    return Number.isFinite(ms) ? ms : null;
+}