@dudousxd/adonis-authkit-server 0.1.1 → 0.2.0

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

@@ -0,0 +1,48 @@
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import type { AuthAccount } from '../account_store.js';
+/**
+ * Encripta/decripta um valor (ex.: o segredo TOTP) em repouso. Mantém a lib
+ * desacoplada do serviço de encryption do app — qualquer implementação que
+ * faça round-trip serve (em prod, normalmente o `@adonisjs/core/services/encryption`).
+ * `decrypt` retorna `null` se o valor foi adulterado/é inválido.
+ */
+export interface AccountSecretEncrypter {
+    encrypt(value: string): string;
+    decrypt(value: string): string | null;
+}
+/**
+ * Funções das cerimônias WebAuthn. Espelham a assinatura do `@simplewebauthn/server`
+ * (subconjunto usado). Injetáveis via {@link LucidAccountStoreOptions.webauthnCeremonies}
+ * para testes.
+ */
+export interface WebauthnCeremonies {
+    generateRegistrationOptions: typeof generateRegistrationOptions;
+    verifyRegistrationResponse: typeof verifyRegistrationResponse;
+    generateAuthenticationOptions: typeof generateAuthenticationOptions;
+    verifyAuthenticationResponse: typeof verifyAuthenticationResponse;
+}
+/** RP (Relying Party) do WebAuthn usado nas cerimônias. */
+export interface ResolvedRp {
+    rpName: string;
+    rpId: string;
+    origin: string | string[];
+}
+/**
+ * Contexto compartilhado pelos builders de capacidade. Carrega o model principal,
+ * os helpers de segredo e (quando configurados) os models/parametros das capacidades.
+ */
+export interface LucidStoreContext {
+    Model: any;
+    mfaIssuer: string;
+    recoveryCodeCount: number;
+    /** Encripta o segredo antes de persistir (no-op sem encrypter). */
+    sealSecret(secret: string): string;
+    /** Decripta o segredo armazenado; null em falha/adulteração (no-op sem encrypter). */
+    openSecret(stored: string | null | undefined): string | null;
+    toAccount(row: any): AuthAccount;
+}
+export declare const sha256: (value: string) => string;
+/** Recovery code legível: 10 chars hex em duas metades (ex.: a1b2c-3d4e5). */
+export declare function generateRecoveryCode(): string;
+/** Comparação de hashes hex resistente a timing. */
+export declare function hashesEqual(a: string, b: string): boolean;

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

@@ -0,0 +1,15 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/** Recovery code legível: 10 chars hex em duas metades (ex.: a1b2c-3d4e5). */
+export function generateRecoveryCode() {
+    const raw = randomBytes(5).toString('hex');
+    return `${raw.slice(0, 5)}-${raw.slice(5, 10)}`;
+}
+/** Comparação de hashes hex resistente a timing. */
+export function hashesEqual(a, b) {
+    const ba = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ba.length !== bb.length)
+        return false;
+    return timingSafeEqual(ba, bb);
+}

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

@@ -0,0 +1,8 @@
+import type { WebauthnCapability } from '../account_store.js';
+import type { LucidStoreContext, ResolvedRp, WebauthnCeremonies } from './shared.js';
+/**
+ * Capacidade de passkeys / WebAuthn (2º fator alternativo ao TOTP). Só é montada
+ * quando o `webauthnCredentialModel` é fornecido — ausente, a capacidade inteira
+ * fica ABSENTE do store (a UI esconde a seção de passkeys).
+ */
+export declare function buildWebauthn(ctx: LucidStoreContext, Credential: any, webauthn: ResolvedRp, ceremonies: WebauthnCeremonies): WebauthnCapability;

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

@@ -0,0 +1,135 @@
+import { DateTime } from 'luxon';
+/**
+ * Capacidade de passkeys / WebAuthn (2º fator alternativo ao TOTP). Só é montada
+ * quando o `webauthnCredentialModel` é fornecido — ausente, a capacidade inteira
+ * fica ABSENTE do store (a UI esconde a seção de passkeys).
+ */
+export function buildWebauthn(ctx, Credential, webauthn, ceremonies) {
+    const { Model } = ctx;
+    return {
+        async generatePasskeyRegistrationOptions(accountId) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return null;
+            const existing = await Credential.query().where('accountId', accountId);
+            const options = await ceremonies.generateRegistrationOptions({
+                rpName: webauthn.rpName,
+                rpID: webauthn.rpId,
+                userName: row.email,
+                userDisplayName: row.fullName ?? row.email,
+                // Não pede attestation (privacidade); confia na verificação local.
+                attestationType: 'none',
+                // Evita registrar a mesma credencial duas vezes.
+                excludeCredentials: existing.map((c) => ({
+                    id: c.id,
+                    transports: (c.transports ?? undefined),
+                })),
+                authenticatorSelection: { residentKey: 'preferred', userVerification: 'preferred' },
+            });
+            return {
+                options: options,
+                challenge: options.challenge,
+            };
+        },
+        async verifyPasskeyRegistration(accountId, response, expectedChallenge) {
+            const row = await Model.find(accountId);
+            if (!row)
+                return false;
+            let verification;
+            try {
+                verification = await ceremonies.verifyRegistrationResponse({
+                    response: response,
+                    expectedChallenge,
+                    expectedOrigin: webauthn.origin,
+                    expectedRPID: webauthn.rpId,
+                });
+            }
+            catch {
+                return false;
+            }
+            if (!verification.verified || !verification.registrationInfo)
+                return false;
+            const { credential } = verification.registrationInfo;
+            // publicKey vem como Uint8Array → armazenamos como base64url (texto).
+            const publicKey = Buffer.from(credential.publicKey).toString('base64url');
+            await Credential.create({
+                id: credential.id,
+                accountId,
+                publicKey,
+                counter: credential.counter,
+                transports: credential.transports ?? null,
+                label: null,
+            });
+            // Registrar uma passkey também habilita o MFA (2º fator presente).
+            if (!row.mfaEnabledAt) {
+                row.mfaEnabledAt = DateTime.now();
+                await row.save();
+            }
+            return true;
+        },
+        async generatePasskeyAuthenticationOptions(accountId) {
+            const creds = await Credential.query().where('accountId', accountId);
+            if (creds.length === 0)
+                return null;
+            const options = await ceremonies.generateAuthenticationOptions({
+                rpID: webauthn.rpId,
+                allowCredentials: creds.map((c) => ({
+                    id: c.id,
+                    transports: (c.transports ?? undefined),
+                })),
+                userVerification: 'preferred',
+            });
+            return {
+                options: options,
+                challenge: options.challenge,
+            };
+        },
+        async verifyPasskeyAuthentication(accountId, response, expectedChallenge) {
+            const resp = response;
+            // O credential id vem na resposta (base64url) → acha a credencial da conta.
+            const cred = await Credential.query()
+                .where('accountId', accountId)
+                .where('id', resp?.id ?? '')
+                .first();
+            if (!cred)
+                return false;
+            let verification;
+            try {
+                verification = await ceremonies.verifyAuthenticationResponse({
+                    response: resp,
+                    expectedChallenge,
+                    expectedOrigin: webauthn.origin,
+                    expectedRPID: webauthn.rpId,
+                    credential: {
+                        id: cred.id,
+                        publicKey: new Uint8Array(Buffer.from(cred.publicKey, 'base64url')),
+                        counter: cred.counter,
+                        transports: (cred.transports ?? undefined),
+                    },
+                });
+            }
+            catch {
+                return false;
+            }
+            if (!verification.verified)
+                return false;
+            // Atualiza o signature counter (anti-replay).
+            cred.counter = verification.authenticationInfo.newCounter;
+            await cred.save();
+            return true;
+        },
+        async listPasskeys(accountId) {
+            const creds = await Credential.query()
+                .where('accountId', accountId)
+                .orderBy('createdAt', 'asc');
+            return creds.map((c) => ({
+                id: c.id,
+                label: c.label ?? undefined,
+                createdAt: c.createdAt?.toISO?.() ?? String(c.createdAt ?? ''),
+            }));
+        },
+        async removePasskey(accountId, credentialId) {
+            await Credential.query().where('accountId', accountId).where('id', credentialId).delete();
+        },
+    };
+}

package/build/src/define_config.d.ts

@@ -117,6 +117,12 @@ export interface ResolvedDynamicRegistrationConfig {
     initialAccessToken?: string;
     management: boolean;
 }
+/**
+ * Resolve a config de registro dinâmico e VALIDA invariantes em tempo de resolução.
+ * O Registration Management (RFC 7592) só faz sentido com o registro habilitado
+ * (RFC 7591) — `management: true` com `enabled: false` é um erro de configuração.
+ */
+export declare function resolveDynamicRegistration(input?: DynamicRegistrationConfigInput): ResolvedDynamicRegistrationConfig;
 /**
  * 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

package/build/src/define_config.js

@@ -26,6 +26,25 @@ export function resolveLockout(input) {
         store: input?.store,
     };
 }
+/**
+ * Resolve a config de registro dinâmico e VALIDA invariantes em tempo de resolução.
+ * O Registration Management (RFC 7592) só faz sentido com o registro habilitado
+ * (RFC 7591) — `management: true` com `enabled: false` é um erro de configuração.
+ */
+export function resolveDynamicRegistration(input) {
+    const enabled = input?.enabled ?? false;
+    const management = input?.management ?? false;
+    if (management && !enabled) {
+        throw new Error('authkit: dynamicRegistration.management (RFC 7592) requer ' +
+            'dynamicRegistration.enabled: true (RFC 7591). Habilite o registro dinâmico ' +
+            'ou desligue o management.');
+    }
+    return {
+        enabled,
+        initialAccessToken: input?.initialAccessToken,
+        management,
+    };
+}
 export function resolveAdmin(input) {
     return {
         enabled: input?.enabled ?? false,
@@ -102,11 +121,7 @@ export function defineConfig(config) {
             audit: config.audit,
             mfaIssuer: config.mfaIssuer ?? 'AuthKit',
             webauthn: resolveWebauthn(config.issuer, config.mfaIssuer ?? 'AuthKit', config.webauthn),
-            dynamicRegistration: {
-                enabled: config.dynamicRegistration?.enabled ?? false,
-                initialAccessToken: config.dynamicRegistration?.initialAccessToken,
-                management: config.dynamicRegistration?.management ?? false,
-            },
+            dynamicRegistration: resolveDynamicRegistration(config.dynamicRegistration),
             admin: resolveAdmin(config.admin),
             messages: resolveMessages(config.i18n),
             locale: config.i18n?.locale ?? 'pt-BR',

package/build/src/host/controllers/account_mfa_controller.js

@@ -2,6 +2,7 @@ import '../augmentations.js';
 import QRCode from 'qrcode';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
 import { translate } from '../i18n.js';
+import { supportsPasskeys } from '../../accounts/account_store.js';
 /** Desafio WebAuthn pendente (registro) guardado na sessão entre begin/finish. */
 const PASSKEY_REG_CHALLENGE_KEY = 'authkit_passkey_reg_challenge';
 /**
@@ -18,7 +19,7 @@ export default class AccountMfaController {
         const state = (await cfg.accountStore.getMfaState?.(userId)) ?? { enabled: false };
         const recoveryCodes = ctx.session.flashMessages.get('recoveryCodes');
         // Passkeys disponíveis quando o store as suporta (model de credenciais wired).
-        const passkeysSupported = typeof cfg.accountStore.listPasskeys === 'function';
+        const passkeysSupported = supportsPasskeys(cfg.accountStore);
         const passkeys = passkeysSupported ? await cfg.accountStore.listPasskeys(userId) : [];
         return render(ctx, 'account/mfa', {
             csrfToken: ctx.request.csrfToken,

package/build/src/host/controllers/account_session_controller.js

@@ -1,7 +1,7 @@
 import '../augmentations.js';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
 import { translate } from '../i18n.js';
-import { createAccountLockout } from '../account_lockout.js';
+import { attemptPasswordLogin } from '../login_attempt.js';
 export default class AccountSessionController {
     async show(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
@@ -18,27 +18,19 @@ export default class AccountSessionController {
         const render = cfg.render;
         const { email, password } = ctx.request.only(['email', 'password']);
         const ip = ctx.request.ip?.() ?? null;
-        const lockout = createAccountLockout(cfg.lockout);
-        // Bloqueio progressivo: se a conta está travada, nem verifica a senha.
-        const lock = await lockout.isLocked(email);
-        if (lock.locked) {
+        // Verificação + lockout + auditoria de falha centralizados (sem clientId no console).
+        const result = await attemptPasswordLogin(cfg, { email, password, ip });
+        if (!result.ok) {
             return render(ctx, 'account/login', {
                 csrfToken: ctx.request.csrfToken,
-                error: translate(cfg.messages, 'errors.account_locked', {
-                    seconds: lock.retryAfterSec ?? 0,
-                }),
+                error: result.locked
+                    ? translate(cfg.messages, 'errors.account_locked', {
+                        seconds: result.retryAfterSec ?? 0,
+                    })
+                    : translate(cfg.messages, 'errors.invalid_credentials'),
             });
         }
-        const acc = await cfg.accountStore.verifyCredentials(email, password);
-        if (!acc) {
-            await cfg.audit?.record({ type: 'login.failure', email, ip });
-            await lockout.recordFailure(email, { sink: cfg.audit, ip });
-            return render(ctx, 'account/login', {
-                csrfToken: ctx.request.csrfToken,
-                error: translate(cfg.messages, 'errors.invalid_credentials'),
-            });
-        }
-        await lockout.clearFailures(email);
+        const acc = result.account;
         ctx.session.put(ACCOUNT_SESSION_KEY, acc.id);
         await cfg.audit?.record({ type: 'login.success', accountId: acc.id, email, ip });
         return ctx.response.redirect('/account/tokens');

package/build/src/host/controllers/interaction_controller.js

@@ -1,7 +1,8 @@
 import '../augmentations.js';
 import { brandFor, isFirstParty } from '../branding.js';
 import { translate } from '../i18n.js';
-import { createAccountLockout } from '../account_lockout.js';
+import { attemptPasswordLogin } from '../login_attempt.js';
+import { supportsPasskeys } from '../../accounts/account_store.js';
 const SESSION_KEY = 'authkit_login_email';
 /** accountId aguardando o 2º fator depois da senha verificada. */
 const MFA_PENDING_KEY = 'authkit_mfa_pending';
@@ -80,35 +81,12 @@ export default class AuthInteractionController {
         const { password } = ctx.request.only(['password']);
         const ip = ctx.request.ip?.() ?? null;
         const clientId = details.params.client_id ?? null;
-        const lockout = createAccountLockout(cfg.lockout);
-        // Bloqueio progressivo (keyed por email da sessão): se travada, não verifica a senha.
-        const lock = await lockout.isLocked(email);
-        if (lock.locked) {
-            const found = await cfg.accountStore.findByEmail(email);
-            const account = found
-                ? { fullName: found.name ?? null, globalRoles: found.globalRoles ?? [] }
-                : null;
-            return render(ctx, 'login', {
-                uid: ctx.request.param('uid'),
-                csrfToken: ctx.request.csrfToken,
-                step: 'password',
-                email,
-                account,
-                error: translate(cfg.messages, 'errors.account_locked', {
-                    seconds: lock.retryAfterSec ?? 0,
-                }),
-                brand,
-            });
-        }
         // Verificamos as credenciais ANTES de finalizar a interaction, porque com MFA
         // ligado precisamos exigir o 2º fator e NÃO podemos chamar interactionFinished
-        // ainda. (`service.interactions.login` verifica E finaliza num passo só — por
-        // isso fazemos a verificação aqui via accountStore e finalizamos depois.)
-        const acc = await cfg.accountStore.verifyCredentials(email, password);
-        if (!acc) {
-            await cfg.audit?.record({ type: 'login.failure', email, ip, clientId });
-            await lockout.recordFailure(email, { sink: cfg.audit, ip });
-            // Re-render password step with error (keep email in session)
+        // ainda. A sequência verificação + lockout + auditoria de falha é centralizada
+        // em attemptPasswordLogin; a renderização (lookup p/ personalização) fica aqui.
+        const result = await attemptPasswordLogin(cfg, { email, password, ip, clientId });
+        if (!result.ok) {
             const found = await cfg.accountStore.findByEmail(email);
             const account = found
                 ? { fullName: found.name ?? null, globalRoles: found.globalRoles ?? [] }
@@ -119,12 +97,15 @@ export default class AuthInteractionController {
                 step: 'password',
                 email,
                 account,
-                error: translate(cfg.messages, 'errors.invalid_credentials'),
+                error: result.locked
+                    ? translate(cfg.messages, 'errors.account_locked', {
+                        seconds: result.retryAfterSec ?? 0,
+                    })
+                    : translate(cfg.messages, 'errors.invalid_credentials'),
                 brand,
             });
         }
-        // Senha correta: limpa o contador de falhas (o lockout protege a etapa de senha).
-        await lockout.clearFailures(email);
+        const acc = result.account;
         // MFA gate: se a conta tem TOTP ativo, NÃO finaliza a interaction agora —
         // guarda o accountId pendente na sessão e renderiza o desafio do 2º fator.
         const mfa = (await cfg.accountStore.getMfaState?.(acc.id)) ?? { enabled: false };
@@ -204,7 +185,7 @@ export default class AuthInteractionController {
     }
     /** true se o store suporta passkeys E a conta tem ao menos uma registrada. */
     async hasPasskeys(cfg, accountId) {
-        if (typeof cfg.accountStore.listPasskeys !== 'function')
+        if (!supportsPasskeys(cfg.accountStore))
             return false;
         const list = await cfg.accountStore.listPasskeys(accountId);
         return Array.isArray(list) && list.length > 0;

package/build/src/host/controllers/social_controller.js

@@ -1,5 +1,6 @@
 import '../augmentations.js';
 import { randomUUID } from 'node:crypto';
+import { supportsProviderIdentity } from '../../accounts/account_store.js';
 const UID_SESSION_KEY = 'authkit_social_uid';
 /**
  * `AllyService.use()` é tipado contra a interface `SocialProviders`, que só é
@@ -37,6 +38,12 @@ export default class AuthSocialController {
         const cfg = service.config;
         const store = cfg.accountStore;
         const email = profile.email ?? undefined;
+        // Account linking exige a capacidade de provider-identity (model wired no store).
+        // Ausente → não há como ligar a identidade; volta ao login em vez de quebrar.
+        if (!supportsProviderIdentity(store)) {
+            ctx.session.forget(UID_SESSION_KEY);
+            return ctx.response.redirect(backToLogin);
+        }
         // Precedência do account linking:
         //  1. Identidade de provider já ligada → loga essa conta.
         //  2. Senão, e-mail conhecido → acha por e-mail e LIGA a identidade (linking).

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

@@ -0,0 +1,39 @@
+import type { AuthAccount } from '../accounts/account_store.js';
+import type { ResolvedServerConfig } from '../define_config.js';
+/** Entrada de uma tentativa de login por senha (keyed por email). */
+export interface PasswordLoginInput {
+    email: string;
+    password: string;
+    /** IP da request (para auditoria + lockout). null quando indisponível. */
+    ip: string | null;
+    /**
+     * client_id da interaction OIDC, quando existir. Só é incluído no evento de
+     * auditoria nos fluxos que o têm (interaction); ausente no console de conta.
+     */
+    clientId?: string | null;
+}
+/** Resultado de {@link attemptPasswordLogin}. */
+export type PasswordLoginResult = {
+    ok: true;
+    account: AuthAccount;
+} | {
+    ok: false;
+    locked: boolean;
+    retryAfterSec?: number;
+};
+/**
+ * Sequência canônica de login por senha + bloqueio progressivo, compartilhada
+ * pelos dois fluxos que pedem senha (interaction OIDC e console de conta):
+ *
+ *   1. `lockout.isLocked(email)` — se travada, NÃO verifica a senha; devolve
+ *      `{ ok: false, locked: true, retryAfterSec }` (o controller renderiza o erro).
+ *   2. `verifyCredentials(email, password)` — em falha: emite `login.failure`
+ *      (com `clientId` apenas quando fornecido), registra a falha no lockout
+ *      (`{ sink: cfg.audit, ip }`) e devolve `{ ok: false, locked: false }`.
+ *   3. Em sucesso: limpa o contador de falhas e devolve `{ ok: true, account }`.
+ *
+ * O evento `login.success` e a finalização da sessão/interaction ficam a cargo de
+ * cada controller (os fluxos diferem: MFA gate na interaction, sessão no console),
+ * assim como toda a renderização.
+ */
+export declare function attemptPasswordLogin(cfg: ResolvedServerConfig, input: PasswordLoginInput): Promise<PasswordLoginResult>;

package/build/src/host/login_attempt.js

@@ -0,0 +1,37 @@
+import { createAccountLockout } from './account_lockout.js';
+/**
+ * Sequência canônica de login por senha + bloqueio progressivo, compartilhada
+ * pelos dois fluxos que pedem senha (interaction OIDC e console de conta):
+ *
+ *   1. `lockout.isLocked(email)` — se travada, NÃO verifica a senha; devolve
+ *      `{ ok: false, locked: true, retryAfterSec }` (o controller renderiza o erro).
+ *   2. `verifyCredentials(email, password)` — em falha: emite `login.failure`
+ *      (com `clientId` apenas quando fornecido), registra a falha no lockout
+ *      (`{ sink: cfg.audit, ip }`) e devolve `{ ok: false, locked: false }`.
+ *   3. Em sucesso: limpa o contador de falhas e devolve `{ ok: true, account }`.
+ *
+ * O evento `login.success` e a finalização da sessão/interaction ficam a cargo de
+ * cada controller (os fluxos diferem: MFA gate na interaction, sessão no console),
+ * assim como toda a renderização.
+ */
+export async function attemptPasswordLogin(cfg, input) {
+    const { email, password, ip } = input;
+    const lockout = createAccountLockout(cfg.lockout);
+    // Bloqueio progressivo (keyed por email): se travada, não verifica a senha.
+    const lock = await lockout.isLocked(email);
+    if (lock.locked) {
+        return { ok: false, locked: true, retryAfterSec: lock.retryAfterSec };
+    }
+    const account = await cfg.accountStore.verifyCredentials(email, password);
+    if (!account) {
+        // `clientId` só entra no evento quando o fluxo o fornece (interaction).
+        await cfg.audit?.record(input.clientId !== undefined
+            ? { type: 'login.failure', email, ip, clientId: input.clientId }
+            : { type: 'login.failure', email, ip });
+        await lockout.recordFailure(email, { sink: cfg.audit, ip });
+        return { ok: false, locked: false };
+    }
+    // Senha correta: limpa o contador de falhas (o lockout protege a etapa de senha).
+    await lockout.clearFailures(email);
+    return { ok: true, account };
+}

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

@@ -3,12 +3,25 @@ import type { AuthSocialConfig, RateLimitConfigInput } from '../define_config.js
 /**
  * Guard do console admin (B6). Como o `accountGuard`, é uma closure inline (forma
  * confiável do `.use()` num grupo). Exige:
+ *   0. `config.admin.enabled` ligado (senão → 404; ver nota de flag-drift abaixo);
  *   1. sessão de conta ativa (senão → /account/login);
  *   2. a conta logada com pelo menos UMA das `config.admin.roles` nas roles globais
  *      (senão → /account/tokens, evitando vazar a existência do /admin).
  * As roles permitidas são resolvidas em runtime do `authkit.server` (config lazy).
  */
 export declare const adminGuard: (ctx: any, next: () => Promise<void>) => Promise<any>;
+/**
+ * Opções de montagem das rotas do host-kit.
+ *
+ * NOTA (flag-drift): vários campos aqui (`social`, `rateLimit`, `admin`) ESPELHAM
+ * o config (`config/authkit.ts`) porque a decisão de MONTAR as rotas acontece em
+ * tempo de registro, antes de o config (lazy) resolver. Eles controlam apenas se
+ * as rotas existem; a fonte de verdade do COMPORTAMENTO continua sendo o config
+ * resolvido. Se um flag aqui divergir do config (ex.: `admin: true` aqui com
+ * `admin.enabled: false` no config), os guards das rotas são a rede de segurança
+ * (o `adminGuard` 404a quando `config.admin.enabled` é false). Mantenha-os em
+ * sincronia; os guards garantem que a divergência não vire um bypass.
+ */
 export interface AuthHostOptions {
     /** Onde o provider OIDC é montado (default '/oidc'). Deve casar com o final do issuer. */
     mountPath: string;

package/build/src/host/register_auth_host.js

@@ -16,18 +16,25 @@ const accountGuard = async (ctx, next) => {
 /**
  * Guard do console admin (B6). Como o `accountGuard`, é uma closure inline (forma
  * confiável do `.use()` num grupo). Exige:
+ *   0. `config.admin.enabled` ligado (senão → 404; ver nota de flag-drift abaixo);
  *   1. sessão de conta ativa (senão → /account/login);
  *   2. a conta logada com pelo menos UMA das `config.admin.roles` nas roles globais
  *      (senão → /account/tokens, evitando vazar a existência do /admin).
  * As roles permitidas são resolvidas em runtime do `authkit.server` (config lazy).
  */
 export const adminGuard = async (ctx, next) => {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    // Defesa contra flag-drift: as rotas são montadas com `admin: true` em tempo de
+    // registro, ANTES de o config resolver. Se o config tiver `admin.enabled: false`,
+    // as rotas existem mas o console deve estar desligado — 404 (não vaza a existência).
+    if (!cfg.admin.enabled) {
+        return ctx.response.notFound();
+    }
     const accountId = ctx.session?.get(ACCOUNT_SESSION_KEY);
     if (!accountId) {
         return ctx.response.redirect('/account/login');
     }
-    const service = await ctx.containerResolver.make('authkit.server');
-    const cfg = service.config;
     const allowed = cfg.admin.roles;
     const account = await cfg.accountStore.findById(accountId);
     const roles = account?.globalRoles ?? [];

package/build/src/mixins/json_column.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Serializer canônico de coluna JSON para os mixins. Centraliza o par
+ * `prepare`/`consume` (`JSON.stringify`/`JSON.parse`) que cada mixin escrevia à
+ * mão com tratamentos de null/default ligeiramente diferentes.
+ *
+ * As opções parametrizam exatamente as variações observadas entre os mixins, de
+ * modo que o comportamento por coluna fica IDÊNTICO ao código original:
+ *
+ * - `fallback`: valor devolvido por `consume` quando a coluna é null/undefined
+ *   (ex.: `[]` para `globalRoles`/`scopes`; `null` para `recoveryCodes`/`metadata`).
+ * - `emptyOnWrite`: o que `prepare` grava quando o valor é "vazio" (null/undefined,
+ *   ou — quando `treatEmptyArrayAsEmpty` — um array de length 0). `'null'` grava
+ *   `null` na coluna; `'serialize'` ainda serializa (ex.: `globalRoles` grava
+ *   `"[]"`). Default: `'null'`.
+ * - `treatEmptyArrayAsEmpty`: quando true, um array vazio também conta como "vazio"
+ *   no write (caso do `transports`, que grava null em `[]`). Default: false.
+ * - `passthroughParsed`: quando true, `consume` aceita um valor JÁ desserializado
+ *   (array/objeto) e o devolve sem reparsear — alguns dialetos/drivers entregam o
+ *   JSON já decodificado. Default: false.
+ */
+export interface JsonColumnOptions<T> {
+    /** Valor devolvido por `consume` quando a coluna está null/undefined. */
+    fallback: T;
+    /** O que `prepare` grava para valores vazios. Default: 'null'. */
+    emptyOnWrite?: 'null' | 'serialize';
+    /** Trata array vazio como "vazio" no write (grava null). Default: false. */
+    treatEmptyArrayAsEmpty?: boolean;
+    /** Aceita valor já desserializado em `consume` (passthrough). Default: false. */
+    passthroughParsed?: boolean;
+}
+/**
+ * Devolve o par `{ prepare, consume }` para usar num `@column({...})`.
+ * `T` é o tipo lógico da coluna (ex.: `string[]` ou `Record<string, unknown>`).
+ */
+export declare function jsonColumn<T>(opts: JsonColumnOptions<T>): {
+    prepare: (value: T | null | undefined) => string | null;
+    consume: (value: unknown) => T;
+};

package/build/src/mixins/json_column.js

@@ -0,0 +1,31 @@
+/**
+ * Devolve o par `{ prepare, consume }` para usar num `@column({...})`.
+ * `T` é o tipo lógico da coluna (ex.: `string[]` ou `Record<string, unknown>`).
+ */
+export function jsonColumn(opts) {
+    const emptyOnWrite = opts.emptyOnWrite ?? 'null';
+    const treatEmptyArrayAsEmpty = opts.treatEmptyArrayAsEmpty ?? false;
+    const passthroughParsed = opts.passthroughParsed ?? false;
+    const isEmpty = (value) => {
+        if (value === null || value === undefined)
+            return true;
+        if (treatEmptyArrayAsEmpty && Array.isArray(value) && value.length === 0)
+            return true;
+        return false;
+    };
+    return {
+        prepare: (value) => {
+            if (isEmpty(value)) {
+                return emptyOnWrite === 'serialize' ? JSON.stringify(opts.fallback) : null;
+            }
+            return JSON.stringify(value);
+        },
+        consume: (value) => {
+            if (value === null || value === undefined)
+                return opts.fallback;
+            if (passthroughParsed && Array.isArray(value))
+                return value;
+            return JSON.parse(value);
+        },
+    };
+}

package/build/src/mixins/with_audit_log.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { column } from '@adonisjs/lucid/orm';
+import { jsonColumn } from './json_column.js';
 export function withAuditLog() {
     return (superclass) => {
         class AuditLogMixin extends superclass {
@@ -28,10 +29,7 @@ export function withAuditLog() {
             column()
         ], AuditLogMixin.prototype, "ip", void 0);
         __decorate([
-            column({
-                prepare: (value) => value ? JSON.stringify(value) : null,
-                consume: (value) => (value ? JSON.parse(value) : null),
-            })
+            column(jsonColumn({ fallback: null }))
         ], AuditLogMixin.prototype, "metadata", void 0);
         __decorate([
             column.dateTime({ autoCreate: true })