@dudousxd/adonis-authkit-server 0.5.0 → 0.7.0

package/build/src/accounts/lucid_store/mfa.js

@@ -11,7 +11,10 @@ export function buildMfa(ctx) {
     return {
         async getMfaState(accountId) {
             const row = await Model.find(accountId);
-            return { enabled: !!row?.mfaEnabledAt };
+            // `enabledAt` (epoch ms) habilita o trusted-device check: um cookie de
+            // confiança emitido ANTES deste instante é inválido (re-enrolar revoga).
+            const enabledAt = row?.mfaEnabledAt ? row.mfaEnabledAt.toMillis() : null;
+            return { enabled: !!row?.mfaEnabledAt, enabledAt };
         },
         async startTotpEnrollment(accountId) {
             const row = await Model.find(accountId);

package/build/src/accounts/lucid_store/status_profile.d.ts

@@ -0,0 +1,21 @@
+import type { AccountStatusCapability, ProfileCapability } from '../account_store.js';
+import type { LucidStoreContext } from './shared.js';
+/**
+ * Indica se o model declara uma coluna (pela propriedade do model, ex.: `disabledAt`).
+ * Lucid expõe as colunas em `$columnsDefinitions` (Map de propertyName → definição).
+ * Usado para montar as capacidades opcionais SÓ quando a coluna existe — assim o
+ * store degrada graciosamente (capacidade ausente) em models que não têm a coluna.
+ */
+export declare function hasColumn(Model: any, property: string): boolean;
+/**
+ * Status da conta (habilitar/desabilitar) sobre a coluna `disabled_at`
+ * (propriedade `disabledAt`) do model. Só deve ser montado quando a coluna existe
+ * ({@link hasColumn}).
+ */
+export declare function buildStatus(ctx: LucidStoreContext): AccountStatusCapability;
+/**
+ * Edição de perfil (nome/avatar) sobre as colunas `full_name`/`avatar_url` do
+ * model. Grava apenas as colunas que existirem. Só deve ser montado quando ao
+ * menos uma das colunas existe.
+ */
+export declare function buildProfile(ctx: LucidStoreContext): ProfileCapability;

package/build/src/accounts/lucid_store/status_profile.js

@@ -0,0 +1,66 @@
+import { DateTime } from 'luxon';
+/**
+ * Indica se o model declara uma coluna (pela propriedade do model, ex.: `disabledAt`).
+ * Lucid expõe as colunas em `$columnsDefinitions` (Map de propertyName → definição).
+ * Usado para montar as capacidades opcionais SÓ quando a coluna existe — assim o
+ * store degrada graciosamente (capacidade ausente) em models que não têm a coluna.
+ */
+export function hasColumn(Model, property) {
+    const defs = Model?.$columnsDefinitions;
+    if (!defs || typeof defs.has !== 'function')
+        return false;
+    return defs.has(property);
+}
+/**
+ * Status da conta (habilitar/desabilitar) sobre a coluna `disabled_at`
+ * (propriedade `disabledAt`) do model. Só deve ser montado quando a coluna existe
+ * ({@link hasColumn}).
+ */
+export function buildStatus(ctx) {
+    const { Model } = ctx;
+    return {
+        async disableAccount(accountId) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return;
+            row.disabledAt = DateTime.now();
+            await row.save();
+        },
+        async enableAccount(accountId) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return;
+            row.disabledAt = null;
+            await row.save();
+        },
+        async isDisabled(accountId) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return false;
+            return row.disabledAt !== null && row.disabledAt !== undefined;
+        },
+    };
+}
+/**
+ * Edição de perfil (nome/avatar) sobre as colunas `full_name`/`avatar_url` do
+ * model. Grava apenas as colunas que existirem. Só deve ser montado quando ao
+ * menos uma das colunas existe.
+ */
+export function buildProfile(ctx) {
+    const { Model, toAccount } = ctx;
+    const canName = hasColumn(Model, 'fullName');
+    const canAvatar = hasColumn(Model, 'avatarUrl');
+    return {
+        async updateProfile(accountId, patch) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return null;
+            if (canName && patch.name !== undefined)
+                row.fullName = patch.name;
+            if (canAvatar && patch.avatarUrl !== undefined)
+                row.avatarUrl = patch.avatarUrl;
+            await row.save();
+            return toAccount(row);
+        },
+    };
+}

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

@@ -1,7 +1,7 @@
 /**
  * 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' | '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' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified';
+export type AuditEventType = 'login.success' | 'login.failure' | 'signup' | 'password_reset.issued' | 'password_reset.consumed' | 'pat.issued' | 'pat.revoked' | 'pat.used' | 'impersonation' | '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' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified' | 'grant.revoked_by_user' | 'user.created' | 'user.password_reset_sent' | 'user.disabled' | 'user.enabled' | 'profile.updated';
 /**
  * Evento de auditoria a registrar. O timestamp é definido pelo sink (não aqui).
  */

package/build/src/define_config.d.ts

@@ -4,8 +4,10 @@ import { adapters, type AdapterFactory, type OidcAdapterClass } from './adapters
 import type { AccountStore, AuthAccount } from './accounts/account_store.js';
 import type { PatStore } from './pat/pat_store.js';
 import type { AuditSink } from './audit/audit_sink.js';
+import { type EventsConfigInput } from './events/dispatcher.js';
 import type { BrandingConfig } from './host/branding.js';
 import { type AuthMessages, type I18nConfig } from './host/i18n.js';
+import { type ResolvedTrustedDevicesConfig, type TrustedDevicesConfigInput } from './host/trusted_device.js';
 export { adapters };
 export type { AuthAccount };
 export type AuthHostRenderer = (ctx: HttpContext, view: string, props: Record<string, unknown>) => unknown;
@@ -30,6 +32,12 @@ export interface MailHooks {
         verifyUrl: string;
         token: string;
     }) => Promise<void>;
+    /** Disparado após gerar o magic link de login (passwordless). */
+    onMagicLink?: (data: {
+        email: string;
+        magicUrl: string;
+        token: string;
+    }) => Promise<void>;
 }
 /** Bucket de rate-limit: pontos (requests) permitidos por janela de duração. */
 export interface RateLimitBucket {
@@ -153,6 +161,31 @@ export interface ResolvedDeviceFlowConfig {
     enabled: boolean;
 }
 export declare function resolveDeviceFlow(input?: DeviceFlowConfigInput): ResolvedDeviceFlowConfig;
+/**
+ * Uploads — usa o `@adonisjs/drive` JÁ configurado no app (mesmo princípio do
+ * mailer/limiter: a infra do host por padrão, sobreponível aqui). Hoje cobre o
+ * upload de avatar no console de conta. Se o drive estiver ausente, a feature
+ * degrada para o input de URL.
+ */
+export interface UploadsConfigInput {
+    avatars?: {
+        /** Disk do `@adonisjs/drive` a usar. Default: o disk DEFAULT do app. */
+        disk?: string;
+        /** Diretório/prefixo das chaves. Default: 'authkit/avatars'. */
+        directory?: string;
+        /** Tamanho máximo em MB. Default: 5. */
+        maxSizeMb?: number;
+    };
+}
+export interface ResolvedUploadsConfig {
+    avatars: {
+        /** Disk explícito; `undefined` = disk DEFAULT do app. */
+        disk?: string;
+        directory: string;
+        maxSizeMb: number;
+    };
+}
+export declare function resolveUploads(input?: UploadsConfigInput): ResolvedUploadsConfig;
 /**
  * DPoP — Demonstrating Proof of Possession (RFC 9449). Quando habilitado, o
  * oidc-provider aceita DPoP proofs e emite tokens sender-constrained
@@ -205,6 +238,29 @@ export interface ResolvedStepUpConfig {
     mfaAcr: string;
 }
 export declare function resolveStepUp(input?: StepUpConfigInput): ResolvedStepUpConfig;
+/**
+ * Login passwordless. Duas vias independentes e opcionais:
+ *   - `magicLink`: na tela de senha, oferece "me envie um link de login". Um token
+ *     de uso único e curta duração é enviado por e-mail; abrir o link finaliza o
+ *     login (amr `['email']`). Sempre responde "link enviado" (não vaza contas).
+ *   - `passkeyFirst`: na tela de senha, se a conta tem passkeys, oferece "entrar
+ *     com passkey" ANTES da senha. Verificar a passkey já conta como o 2º fator
+ *     (amr `['webauthn']`) — não pede senha nem MFA.
+ *
+ * Ambas exigem que o accountStore implemente a capacidade correspondente
+ * (MagicLinkCapability / WebauthnCapability), senão a opção fica oculta.
+ */
+export interface PasswordlessConfigInput {
+    /** Liga o login por magic link (e-mail). Default: false. */
+    magicLink?: boolean;
+    /** Liga o "entrar com passkey" antes da senha. Default: false. */
+    passkeyFirst?: boolean;
+}
+export interface ResolvedPasswordlessConfig {
+    magicLink: boolean;
+    passkeyFirst: boolean;
+}
+export declare function resolvePasswordless(input?: PasswordlessConfigInput): ResolvedPasswordlessConfig;
 /**
  * Console admin opt-in do IdP (B6). Quando habilitado, monta o grupo `/admin/*`
  * (dashboard, usuários/papéis, clients, audit) atrás de um guard que exige sessão
@@ -281,6 +337,13 @@ export interface AuthServerConfigInput {
     mail?: MailHooks;
     /** Sink de auditoria (best-effort). Opcional — quando ausente, auditoria é no-op. */
     audit?: AuditSink;
+    /**
+     * Eventos/webhooks: o host observa CADA evento de auditoria via callback
+     * in-process (`onEvent`) e/ou POST de webhook (`webhook`). Best-effort, nunca
+     * lança para a request. Quando setado, o `audit` resolvido vira um fan-out
+     * (sink original + onEvent + webhook).
+     */
+    events?: EventsConfigInput;
     /**
      * Label de issuer TOTP mostrado nos apps autenticadores (MFA). Default: 'AuthKit'.
      * O `lucidAccountStore` lê isso para montar o keyuri/QR.
@@ -299,12 +362,25 @@ export interface AuthServerConfigInput {
     dynamicRegistration?: DynamicRegistrationConfigInput;
     /** Device Authorization Grant (RFC 8628). Default: desligado. */
     deviceFlow?: DeviceFlowConfigInput;
+    /** Uploads (avatar) via o `@adonisjs/drive` do app. Default: drive default, 5MB. */
+    uploads?: UploadsConfigInput;
     /** DPoP — sender-constrained tokens (RFC 9449). Default: desligado. */
     dpop?: DpopConfigInput;
     /** Pushed Authorization Requests (RFC 9126). Default: desligado. */
     par?: ParConfigInput;
     /** Step-up auth via acr_values (MFA por requisição). Default: vazio (só o mfaAcr derivado). */
     stepUp?: StepUpConfigInput;
+    /**
+     * Trusted devices: pular o MFA neste dispositivo por N dias via cookie
+     * encriptado (appKey-backed), sem migração. Default: ligado, 30 dias. Step-up
+     * (acr_values) sempre ignora o cookie e força o MFA.
+     */
+    trustedDevices?: TrustedDevicesConfigInput;
+    /**
+     * Login passwordless (magic link por e-mail e/ou passkey-first). Default: ambos
+     * desligados. Exigem as capacidades correspondentes no accountStore.
+     */
+    passwordless?: PasswordlessConfigInput;
     /**
      * Console admin do IdP (B6). Default: desligado. Quando ligado, o host também
      * deve passar `admin: true` em {@link AuthHostOptions} no registro de rotas
@@ -352,12 +428,18 @@ export interface ResolvedServerConfig {
     dynamicRegistration: ResolvedDynamicRegistrationConfig;
     /** Device Authorization Grant resolvido (default desligado). */
     deviceFlow: ResolvedDeviceFlowConfig;
+    /** Uploads resolvido (avatar via drive do app; sempre presente). */
+    uploads: ResolvedUploadsConfig;
     /** DPoP resolvido (default desligado). */
     dpop: ResolvedDpopConfig;
     /** PAR resolvido (default desligado). */
     par: ResolvedParConfig;
     /** Step-up auth resolvido (mfaAcr sempre presente). */
     stepUp: ResolvedStepUpConfig;
+    /** Trusted devices resolvido (default ligado, 30 dias). */
+    trustedDevices: ResolvedTrustedDevicesConfig;
+    /** Passwordless resolvido (default tudo desligado). */
+    passwordless: ResolvedPasswordlessConfig;
     /** Console admin resolvido (sempre presente; default desligado). */
     admin: ResolvedAdminConfig;
     /** Catálogo de mensagens ativo (locale resolvido), pronto para os renderers. */

package/build/src/define_config.js

@@ -2,7 +2,9 @@ import { configProvider } from '@adonisjs/core';
 import { generateJwks } from './keys/jwks_manager.js';
 import { ensureKeystore } from './keys/keystore.js';
 import { adapters } from './adapters/factory.js';
+import { composeAuditSink, resolveEvents } from './events/dispatcher.js';
 import { resolveMessages } from './host/i18n.js';
+import { resolveTrustedDevices, } from './host/trusted_device.js';
 export { adapters };
 const RATE_LIMIT_DEFAULTS = {
     login: { points: 10, duration: '1 min' },
@@ -54,6 +56,15 @@ export function resolveDynamicRegistration(input) {
 export function resolveDeviceFlow(input) {
     return { enabled: input?.enabled ?? false };
 }
+export function resolveUploads(input) {
+    return {
+        avatars: {
+            disk: input?.avatars?.disk,
+            directory: input?.avatars?.directory ?? 'authkit/avatars',
+            maxSizeMb: input?.avatars?.maxSizeMb ?? 5,
+        },
+    };
+}
 export function resolveDpop(input) {
     return { enabled: input?.enabled ?? false };
 }
@@ -69,6 +80,12 @@ export function resolveStepUp(input) {
     const acrValues = Array.from(new Set([...(input?.acrValues ?? []), mfaAcr]));
     return { acrValues, mfaAcr };
 }
+export function resolvePasswordless(input) {
+    return {
+        magicLink: input?.magicLink ?? false,
+        passkeyFirst: input?.passkeyFirst ?? false,
+    };
+}
 export function resolveAdmin(input) {
     return {
         enabled: input?.enabled ?? false,
@@ -157,14 +174,20 @@ export function defineConfig(config) {
             lockout: resolveLockout(config.lockout),
             notifications: resolveNotifications(config.notifications),
             mail: config.mail,
-            audit: config.audit,
+            audit: (() => {
+                const events = resolveEvents(config.events);
+                return events ? composeAuditSink(config.audit, events) : config.audit;
+            })(),
             mfaIssuer: config.mfaIssuer ?? 'AuthKit',
             webauthn: resolveWebauthn(config.issuer, config.mfaIssuer ?? 'AuthKit', config.webauthn),
             dynamicRegistration: resolveDynamicRegistration(config.dynamicRegistration),
             deviceFlow: resolveDeviceFlow(config.deviceFlow),
+            uploads: resolveUploads(config.uploads),
             dpop: resolveDpop(config.dpop),
             par: resolvePar(config.par),
             stepUp: resolveStepUp(config.stepUp),
+            trustedDevices: resolveTrustedDevices(config.trustedDevices),
+            passwordless: resolvePasswordless(config.passwordless),
             admin: resolveAdmin(config.admin),
             messages: resolveMessages(config.i18n),
             locale: config.i18n?.locale ?? 'pt-BR',

package/build/src/doctor/checks.js

@@ -13,10 +13,10 @@ export function checkConfigResolves(input) {
     if (!input.authkitConfig) {
         return {
             level: 'error',
-            message: "config('authkit') não resolveu — config/authkit.ts está ausente ou inválido.",
+            message: "config('authkit') did not resolve — config/authkit.ts is missing or invalid.",
         };
     }
-    return { level: 'ok', message: "config('authkit') resolvido." };
+    return { level: 'ok', message: "config('authkit') resolved." };
 }
 /** issuer é uma URL válida e seu pathname casa com o mountPath. */
 export function checkIssuer(input) {
@@ -26,21 +26,21 @@ export function checkIssuer(input) {
     const issuer = cfg.issuer;
     const mountPath = cfg.mountPath ?? '/oidc';
     if (typeof issuer !== 'string' || issuer.length === 0) {
-        return [{ level: 'error', message: 'issuer ausente na config.' }];
+        return [{ level: 'error', message: 'issuer missing in config.' }];
     }
     let url;
     try {
         url = new URL(issuer);
     }
     catch {
-        return [{ level: 'error', message: `issuer não é uma URL válida: "${issuer}".` }];
+        return [{ level: 'error', message: `issuer is not a valid URL: "${issuer}".` }];
     }
-    const findings = [{ level: 'ok', message: `issuer válido: ${url.origin}${url.pathname}` }];
+    const findings = [{ level: 'ok', message: `valid issuer: ${url.origin}${url.pathname}` }];
     const normalize = (p) => (p.endsWith('/') ? p.slice(0, -1) : p) || '/';
     if (normalize(url.pathname) !== normalize(mountPath)) {
         findings.push({
             level: 'warn',
-            message: `O pathname do issuer ("${url.pathname}") difere do mountPath ("${mountPath}"). As rotas OIDC podem não casar com as URLs anunciadas no discovery.`,
+            message: `issuer pathname ("${url.pathname}") differs from mountPath ("${mountPath}"). OIDC routes may not match the URLs announced in discovery.`,
         });
     }
     return findings;
@@ -49,19 +49,19 @@ export function checkIssuer(input) {
 export function checkClients(input) {
     const cfg = input.authkitConfig;
     if (!cfg)
-        return { level: 'error', message: 'sem config para validar clients.' };
+        return { level: 'error', message: 'no config to validate clients.' };
     const clients = Array.isArray(cfg.clients) ? cfg.clients : [];
     if (clients.length === 0) {
-        return { level: 'error', message: 'nenhum client configurado em `clients`.' };
+        return { level: 'error', message: 'no client configured in `clients`.' };
     }
     const withRedirects = clients.filter((c) => Array.isArray(c?.redirectUris) && c.redirectUris.length > 0);
     if (withRedirects.length === 0) {
         return {
             level: 'error',
-            message: `${clients.length} client(s) configurado(s), mas nenhum tem redirectUris.`,
+            message: `${clients.length} client(s) configured, but none has redirectUris.`,
         };
     }
-    return { level: 'ok', message: `${withRedirects.length}/${clients.length} client(s) com redirectUris.` };
+    return { level: 'ok', message: `${withRedirects.length}/${clients.length} client(s) with redirectUris.` };
 }
 /** accountStore presente + quais capacidades implementa. */
 export function checkAccountStore(input) {
@@ -70,9 +70,9 @@ export function checkAccountStore(input) {
         return [];
     const store = cfg.accountStore;
     if (!store) {
-        return [{ level: 'error', message: 'accountStore ausente — obrigatório.' }];
+        return [{ level: 'error', message: 'accountStore missing — required.' }];
     }
-    const findings = [{ level: 'ok', message: 'accountStore presente.' }];
+    const findings = [{ level: 'ok', message: 'accountStore present.' }];
     const caps = [];
     if (has(store, 'getMfaState'))
         caps.push('MFA');
@@ -85,8 +85,8 @@ export function checkAccountStore(input) {
     findings.push({
         level: 'ok',
         message: caps.length
-            ? `Capacidades opcionais: ${caps.join(', ')}.`
-            : 'Apenas o núcleo do accountStore (sem MFA/passkeys/linking/security).',
+            ? `Optional capabilities: ${caps.join(', ')}.`
+            : 'accountStore core only (no MFA/passkeys/linking/security).',
     });
     return findings;
 }
@@ -96,19 +96,19 @@ export function checkSession(input) {
         return [
             {
                 level: 'error',
-                message: '@adonisjs/session não é importável — instale-o (peer obrigatório).',
+                message: '@adonisjs/session is not importable — install it (required peer).',
             },
         ];
     }
     if (!input.sessionConfig) {
-        return [{ level: 'warn', message: "config('session') ausente — o provider de sessão pode não estar configurado." }];
+        return [{ level: 'warn', message: "config('session') missing — the session provider may not be configured." }];
     }
-    const findings = [{ level: 'ok', message: 'provider de sessão configurado.' }];
+    const findings = [{ level: 'ok', message: 'session provider configured.' }];
     const driver = input.sessionConfig.store ?? input.sessionConfig.driver;
     if (driver === 'cookie') {
         findings.push({
             level: 'warn',
-            message: 'session store = cookie: token sets grandes podem estourar o limite de 4KB do cookie. Prefira `redis`/`file` em produção.',
+            message: 'session store = cookie: large token sets may exceed the 4KB cookie limit. Prefer `redis`/`file` in production.',
         });
     }
     return findings;
@@ -116,12 +116,12 @@ export function checkSession(input) {
 /** Hint de exceções de CSRF do shield para o mountPath. */
 export function checkShield(input) {
     if (!input.peers.shield) {
-        return { level: 'error', message: '@adonisjs/shield não é importável — instale-o (peer obrigatório).' };
+        return { level: 'error', message: '@adonisjs/shield is not importable — install it (required peer).' };
     }
     const mountPath = input.authkitConfig?.mountPath ?? '/oidc';
     return {
         level: 'warn',
-        message: `Garanta que as rotas POST do IdP sob "${mountPath}" estejam nas exceções de CSRF do shield (ex.: endpoint /token), senão chamadas server-to-server falham.`,
+        message: `Make sure the IdP POST routes under "${mountPath}" are in the shield CSRF exceptions (e.g. the /token endpoint), otherwise server-to-server calls fail.`,
     };
 }
 /** ally só é necessário quando social está configurado. */
@@ -129,12 +129,12 @@ export function checkAlly(input) {
     const social = input.authkitConfig?.social;
     const usesSocial = !!social && (Array.isArray(social.providers) ? social.providers.length > 0 : Object.keys(social).length > 0);
     if (!usesSocial) {
-        return { level: 'ok', message: 'login social não configurado — @adonisjs/ally é opcional.' };
+        return { level: 'ok', message: 'social login not configured — @adonisjs/ally is optional.' };
     }
     if (!input.peers.ally) {
-        return { level: 'error', message: 'login social configurado, mas @adonisjs/ally não é importável.' };
+        return { level: 'error', message: 'social login configured, but @adonisjs/ally is not importable.' };
     }
-    return { level: 'ok', message: 'login social configurado e @adonisjs/ally disponível.' };
+    return { level: 'ok', message: 'social login configured and @adonisjs/ally available.' };
 }
 /** rateLimit ligado mas @adonisjs/limiter ausente → warn. */
 export function checkRateLimit(input) {
@@ -142,15 +142,15 @@ export function checkRateLimit(input) {
     const rateLimit = cfg?.rateLimit;
     const enabled = rateLimit === undefined ? true : rateLimit?.enabled !== false;
     if (!enabled) {
-        return { level: 'ok', message: 'rate-limiting desligado por config.' };
+        return { level: 'ok', message: 'rate-limiting disabled by config.' };
     }
     if (!input.peers.limiter) {
         return {
             level: 'warn',
-            message: 'rate-limiting está ligado (default), mas @adonisjs/limiter não é importável — vira no-op (sem proteção anti-brute-force).',
+            message: 'rate-limiting is on (default), but @adonisjs/limiter is not importable — becomes a no-op (no anti-brute-force protection).',
         };
     }
-    return { level: 'ok', message: 'rate-limiting ligado e @adonisjs/limiter disponível.' };
+    return { level: 'ok', message: 'rate-limiting on and @adonisjs/limiter available.' };
 }
 /** admin.enabled mas sem roles → warn. */
 export function checkAdmin(input) {
@@ -161,10 +161,10 @@ export function checkAdmin(input) {
     if (roles.length === 0) {
         return {
             level: 'warn',
-            message: 'console admin ligado, mas sem `admin.roles` — ninguém terá acesso (default ["ADMIN"] não foi resolvido aqui).',
+            message: 'admin console on, but no `admin.roles` — nobody will have access (the default ["ADMIN"] was not resolved here).',
         };
     }
-    return { level: 'ok', message: `console admin ligado para roles: ${roles.join(', ')}.` };
+    return { level: 'ok', message: `admin console on for roles: ${roles.join(', ')}.` };
 }
 /** webauthn rpId deve casar com o host do issuer. */
 export function checkWebauthn(input) {
@@ -185,10 +185,10 @@ export function checkWebauthn(input) {
     if (webauthn.rpId !== host) {
         return {
             level: 'warn',
-            message: `webauthn.rpId ("${webauthn.rpId}") difere do host do issuer ("${host}") — as passkeys não validarão no browser.`,
+            message: `webauthn.rpId ("${webauthn.rpId}") differs from the issuer host ("${host}") — passkeys will not validate in the browser.`,
         };
     }
-    return { level: 'ok', message: `webauthn.rpId casa com o host do issuer (${host}).` };
+    return { level: 'ok', message: `webauthn.rpId matches the issuer host (${host}).` };
 }
 /** info sobre rotação quando jwks é managed. */
 export function checkJwks(input) {
@@ -198,10 +198,10 @@ export function checkJwks(input) {
     if (jwks.source === 'managed') {
         return {
             level: 'ok',
-            message: 'jwks managed — rotacione as chaves de assinatura com `node ace authkit:rotate-keys` (use --store para persistir entre boots).',
+            message: 'jwks managed — rotate the signing keys with `node ace authkit:rotate-keys` (use --store to persist across boots).',
         };
     }
-    return { level: 'ok', message: 'jwks fornecido inline (source=jwks).' };
+    return { level: 'ok', message: 'jwks provided inline (source=jwks).' };
 }
 /** Roda todos os checks e devolve a lista plana de findings. */
 export function runAllChecks(input) {

package/build/src/events/dispatcher.d.ts

@@ -0,0 +1,45 @@
+import type { AuditEvent, AuditSink } from '../audit/audit_sink.js';
+/**
+ * Configuração de eventos/webhooks para o host observar tudo que o IdP audita.
+ *
+ *   - `onEvent`: callback in-process disparado para CADA evento de auditoria
+ *     (best-effort, fire-and-forget). Útil para encaminhar a um bus interno.
+ *   - `webhook`: POST JSON do evento para uma URL externa. Quando `secret` é dado,
+ *     assina o corpo com HMAC-SHA256 no header `x-authkit-signature`.
+ *
+ * Nada aqui pode lançar para dentro do caminho da request: todo erro é engolido.
+ */
+export interface EventsConfigInput {
+    /** Callback in-process para cada evento auditado (best-effort). */
+    onEvent?: (event: AuditEvent) => void | Promise<void>;
+    /** Webhook HTTP: POST do evento em JSON. */
+    webhook?: {
+        /** URL de destino do POST. */
+        url: string;
+        /** Segredo opcional para assinar o corpo (HMAC-SHA256). */
+        secret?: string;
+    };
+}
+export interface ResolvedEventsConfig {
+    onEvent?: (event: AuditEvent) => void | Promise<void>;
+    webhook?: {
+        url: string;
+        secret?: string;
+    };
+}
+export declare function resolveEvents(input?: EventsConfigInput): ResolvedEventsConfig | undefined;
+/**
+ * Constrói o corpo JSON canônico do webhook a partir de um evento de auditoria.
+ * O `ts` é o instante do dispatch (ISO 8601).
+ */
+export declare function buildWebhookBody(event: AuditEvent): string;
+/** Calcula o header de assinatura `sha256=<hmac>` para um corpo + segredo. */
+export declare function signWebhookBody(body: string, secret: string): string;
+/**
+ * Decora um AuditSink (ou cria um do zero) num sink fan-out: cada `record`
+ * persiste no sink original (se houver) E dispara onEvent + webhook. Falhas em
+ * qualquer ramo são isoladas — uma não impede as outras nem a request.
+ *
+ * `list` é delegado ao sink original quando existir (preserva a consulta admin).
+ */
+export declare function composeAuditSink(original: AuditSink | undefined, events: ResolvedEventsConfig): AuditSink;

package/build/src/events/dispatcher.js

@@ -0,0 +1,92 @@
+import { createHmac } from 'node:crypto';
+export function resolveEvents(input) {
+    if (!input || (!input.onEvent && !input.webhook))
+        return undefined;
+    return {
+        onEvent: input.onEvent,
+        webhook: input.webhook,
+    };
+}
+/** Timeout (ms) do POST do webhook antes de abortar. */
+const WEBHOOK_TIMEOUT_MS = 5000;
+/**
+ * Constrói o corpo JSON canônico do webhook a partir de um evento de auditoria.
+ * O `ts` é o instante do dispatch (ISO 8601).
+ */
+export function buildWebhookBody(event) {
+    return JSON.stringify({
+        type: event.type,
+        accountId: event.accountId ?? null,
+        email: event.email ?? null,
+        clientId: event.clientId ?? null,
+        ip: event.ip ?? null,
+        metadata: event.metadata ?? {},
+        ts: new Date().toISOString(),
+    });
+}
+/** Calcula o header de assinatura `sha256=<hmac>` para um corpo + segredo. */
+export function signWebhookBody(body, secret) {
+    return 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
+}
+/**
+ * Dispara o webhook de forma fire-and-forget: timeout de 5s via AbortSignal,
+ * captura QUALQUER erro (rede, abort, HMAC) sem propagar. Nunca lança.
+ */
+async function dispatchWebhook(webhook, event) {
+    try {
+        const body = buildWebhookBody(event);
+        const headers = { 'content-type': 'application/json' };
+        if (webhook.secret) {
+            headers['x-authkit-signature'] = signWebhookBody(body, webhook.secret);
+        }
+        await fetch(webhook.url, {
+            method: 'POST',
+            headers,
+            body,
+            signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // best-effort: erro de webhook nunca quebra o caminho da request.
+    }
+}
+/**
+ * Decora um AuditSink (ou cria um do zero) num sink fan-out: cada `record`
+ * persiste no sink original (se houver) E dispara onEvent + webhook. Falhas em
+ * qualquer ramo são isoladas — uma não impede as outras nem a request.
+ *
+ * `list` é delegado ao sink original quando existir (preserva a consulta admin).
+ */
+export function composeAuditSink(original, events) {
+    const composed = {
+        async record(event) {
+            // Persistência original (best-effort, isolada).
+            if (original) {
+                try {
+                    await original.record(event);
+                }
+                catch {
+                    // sink original com defeito não impede os demais ramos.
+                }
+            }
+            // Callback in-process (best-effort, isolado).
+            if (events.onEvent) {
+                try {
+                    await events.onEvent(event);
+                }
+                catch {
+                    // onEvent com defeito não quebra a request.
+                }
+            }
+            // Webhook fire-and-forget (não aguardamos a entrega).
+            if (events.webhook) {
+                void dispatchWebhook(events.webhook, event);
+            }
+        },
+    };
+    // Preserva a capacidade de consulta do sink original (console admin).
+    if (original && typeof original.list === 'function') {
+        composed.list = original.list.bind(original);
+    }
+    return composed;
+}