@adonis-agora/authkit-server 0.34.0

package/build/src/host/avatar_storage.js

@@ -0,0 +1,166 @@
+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;
+};
+let driveServicePromise;
+/**
+ * Importa o service de drive do HOST de forma preguiçosa e fail-safe.
+ * Se `@adonisjs/drive` não estiver instalado, resolve `null`.
+ */
+async function loadDrive() {
+    if (!driveServicePromise) {
+        // Indireção via variável: o `@adonisjs/drive` é peer/opcional e pode não estar
+        // instalado na lib, então o specifier não é resolvido em build-time.
+        const specifier = '@adonisjs/drive/services/main';
+        driveServicePromise = import(__rewriteRelativeImportExtension(specifier))
+            .then((mod) => mod.default ?? null)
+            .catch(() => null);
+    }
+    return driveServicePromise;
+}
+/**
+ * Permite reapontar/limpar o loader do drive (usado em testes).
+ * @internal
+ */
+export function __setDriveLoaderForTests(fn) {
+    if (fn) {
+        driveServicePromise = fn();
+    }
+    else {
+        driveServicePromise = undefined;
+    }
+}
+/** Extensões aceitas para o avatar (imagem raster comum). */
+const ALLOWED_EXTNAMES = ['jpg', 'jpeg', 'png', 'webp'];
+/** Erro de validação do upload (mensagem já localizada no controller). */
+export class AvatarUploadError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'AvatarUploadError';
+    }
+}
+/**
+ * Indica se o drive do app está disponível (para a view decidir mostrar o input
+ * de arquivo). Best-effort: nunca lança.
+ */
+export async function isDriveAvailable() {
+    return (await loadDrive()) !== null;
+}
+/**
+ * Resolve a extensão validada do arquivo enviado.
+ * Lança {@link AvatarUploadError} se ext/size forem inválidos.
+ */
+function validate(file, cfg, messages) {
+    const ext = (file.extname ?? '').toLowerCase().replace(/^\./, '');
+    if (!ALLOWED_EXTNAMES.includes(ext)) {
+        throw new AvatarUploadError('extname', messages.extname);
+    }
+    const maxBytes = cfg.avatars.maxSizeMb * 1024 * 1024;
+    if (typeof file.size === 'number' && file.size > maxBytes) {
+        throw new AvatarUploadError('size', messages.size);
+    }
+    return ext;
+}
+/**
+ * Gera uma chave única para o avatar dentro do diretório configurado.
+ * `${directory}/${accountId}-${random}.${ext}`
+ */
+function buildKey(cfg, accountId, ext) {
+    const random = Math.random().toString(36).slice(2, 10);
+    return `${cfg.avatars.directory}/${accountId}-${random}.${ext}`;
+}
+/**
+ * Armazena o avatar no drive do host e retorna a URL pública.
+ *
+ * - Valida extensão (jpg/jpeg/png/webp) e tamanho (≤ maxSizeMb) — lança
+ *   {@link AvatarUploadError} se inválido (o controller traduz/flasha).
+ * - Usa o disk configurado em `uploads.avatars.disk` ou o disk DEFAULT do app.
+ * - Se o drive estiver ausente/não-configurado → retorna `null` (degrada para URL).
+ *
+ * Nunca lança por causa de drive ausente; só lança em validação.
+ */
+export async function storeAvatar(_ctx, cfg, file, accountId, messages) {
+    const drive = await loadDrive();
+    if (!drive)
+        return null;
+    const ext = validate(file, cfg, messages);
+    // Resolve o disk: o configurado, ou o DEFAULT do drive do app.
+    let disk;
+    try {
+        disk = cfg.avatars.disk ? drive.use(cfg.avatars.disk) : drive.use();
+    }
+    catch {
+        // disk inválido/não-configurado — degrada para URL.
+        return null;
+    }
+    if (!disk)
+        return null;
+    const key = buildKey(cfg, accountId || 'account', ext);
+    // API @adonisjs/drive v3+: o file de multipart move-se direto para o disk.
+    // `moveToDisk` lê do tmpPath e usa o disk informado (ou o default da config).
+    if (typeof file.moveToDisk === 'function') {
+        await file.moveToDisk(key, cfg.avatars.disk ? { disk: cfg.avatars.disk } : undefined);
+    }
+    else if (file.tmpPath) {
+        // Fallback: lê do tmpPath e escreve via putStream no disk resolvido.
+        const fs = await import('node:fs');
+        await disk.putStream(key, fs.createReadStream(file.tmpPath));
+    }
+    else {
+        return null;
+    }
+    try {
+        return await disk.getUrl(key);
+    }
+    catch {
+        // disk sem getUrl público — retorna a key como referência relativa.
+        return key;
+    }
+}
+/**
+ * Deleta (best-effort, fail-safe) o avatar de uma conta no drive do host, a partir
+ * da URL/key armazenada. Usado pela deleção de conta (LGPD): apaga o arquivo se
+ * conseguirmos derivar a key dentro do diretório configurado.
+ *
+ * NUNCA lança: drive ausente, key não reconhecida ou erro de I/O → no-op. A key é
+ * derivada da `storedUrlOrKey` pegando o trecho a partir de `directory/` (cobre
+ * tanto uma key relativa quanto uma URL pública que contenha o caminho).
+ */
+export async function deleteAvatar(cfg, storedUrlOrKey) {
+    if (!storedUrlOrKey)
+        return false;
+    const drive = await loadDrive();
+    if (!drive)
+        return false;
+    // Deriva a key: trecho a partir de `<directory>/`. Se não bater, aborta (não
+    // arriscamos deletar algo fora do nosso diretório).
+    const dir = cfg.avatars.directory.replace(/\/+$/, '');
+    const marker = `${dir}/`;
+    const idx = storedUrlOrKey.indexOf(marker);
+    if (idx < 0)
+        return false;
+    // Remove querystring/fragment de uma URL pública.
+    const key = storedUrlOrKey.slice(idx).split(/[?#]/)[0];
+    let disk;
+    try {
+        disk = cfg.avatars.disk ? drive.use(cfg.avatars.disk) : drive.use();
+    }
+    catch {
+        return false;
+    }
+    if (!disk || typeof disk.delete !== 'function')
+        return false;
+    try {
+        await disk.delete(key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,187 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ResolvedServerConfig } from '../define_config.js';
+import type { SettingsCapability } from './runtime_settings.js';
+/**
+ * Bot protection plugável (CAPTCHA / challenge), agnóstica de vendor.
+ *
+ * O HOST fornece o verificador (`verify`); a lib só ORQUESTRA: injeta o widget
+ * nas telas afetadas (login/signup/reset) e, no POST correspondente, extrai o
+ * token do body e chama `verify` ANTES de processar credenciais. Nenhuma
+ * dependência de Cloudflare Turnstile / hCaptcha / reCAPTCHA é trazida pela lib —
+ * o host escreve o `verify` (um fetch ao endpoint do provedor) no `config/authkit.ts`.
+ *
+ * Decisão de disponibilidade (FAIL-SAFE): se `verify` LANÇAR ou estourar o
+ * timeout, o fluxo PROSSEGUE (a verificação é tratada como "passou") e um warning
+ * é logado. Disponibilidade > proteção: um provedor de CAPTCHA fora do ar não pode
+ * derrubar o login de todo mundo. Apenas um `verify` que retorna `false`
+ * explicitamente rejeita a request.
+ *
+ * @example Cloudflare Turnstile (código do HOST, sem dependência nova na lib):
+ * ```ts
+ * // config/authkit.ts
+ * botProtection: {
+ *   on: ['login', 'signup', 'reset'],
+ *   widget: {
+ *     scriptUrl: 'https://challenges.cloudflare.com/turnstile/v0/api.js',
+ *     // Container renderizado nas telas; o script do Turnstile o "hidrata".
+ *     html: '<div class="cf-turnstile" data-sitekey="0xAAAA..."></div>',
+ *   },
+ *   async verify({ token, ip }) {
+ *     if (!token) return false
+ *     const res = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/x-www-form-urlencoded' },
+ *       body: new URLSearchParams({
+ *         secret: process.env.TURNSTILE_SECRET!,
+ *         response: token,
+ *         ...(ip ? { remoteip: ip } : {}),
+ *       }),
+ *     })
+ *     const data = (await res.json()) as { success: boolean }
+ *     return data.success === true
+ *   },
+ * }
+ * ```
+ *
+ * @example hCaptcha (código do HOST):
+ * ```ts
+ * botProtection: {
+ *   tokenFields: ['h-captcha-response'], // sobrescreve a lista default
+ *   widget: {
+ *     scriptUrl: 'https://js.hcaptcha.com/1/api.js',
+ *     html: '<div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>',
+ *   },
+ *   async verify({ token, ip }) {
+ *     if (!token) return false
+ *     const res = await fetch('https://api.hcaptcha.com/siteverify', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/x-www-form-urlencoded' },
+ *       body: new URLSearchParams({
+ *         secret: process.env.HCAPTCHA_SECRET!,
+ *         response: token,
+ *         ...(ip ? { remoteip: ip } : {}),
+ *       }),
+ *     })
+ *     const data = (await res.json()) as { success: boolean }
+ *     return data.success === true
+ *   },
+ * }
+ * ```
+ */
+/** Ação protegida pelo bot protection (mapeia 1:1 com as telas/POSTs sensíveis). */
+export type BotProtectionAction = 'login' | 'signup' | 'reset';
+/** Contexto passado ao `verify` do host. */
+export interface BotProtectionVerifyInput {
+    /** Token do widget extraído do body (null quando ausente). */
+    token: string | null;
+    /** IP da request (best-effort; pode ser undefined). */
+    ip?: string;
+    /** Ação que disparou a verificação. */
+    action: BotProtectionAction;
+}
+/** Markup/script do widget injetado nas telas (Turnstile, hCaptcha, etc.). */
+export interface BotProtectionWidget {
+    /** URL do script externo do provedor (carregado uma vez, async). */
+    scriptUrl: string;
+    /**
+     * HTML do container do widget (renderizado RAW no form). Tipicamente um
+     * `<div>` com a classe/atributos do provedor (ex.: `class="cf-turnstile"
+     * data-sitekey="..."`). Como é config-trusted (do host), é injetado sem escape.
+     */
+    html: string;
+}
+/**
+ * Campos de body onde o token do widget costuma vir. Cobre os provedores comuns
+ * por padrão; o host pode sobrescrever via `tokenFields`.
+ *   - `cf-turnstile-response` (Cloudflare Turnstile)
+ *   - `h-captcha-response`    (hCaptcha)
+ *   - `g-recaptcha-response`  (Google reCAPTCHA)
+ *   - `authkit-bot-token`     (genérico, p/ widgets custom)
+ */
+export declare const DEFAULT_BOT_TOKEN_FIELDS: readonly ["cf-turnstile-response", "h-captcha-response", "g-recaptcha-response", "authkit-bot-token"];
+/** Config de entrada do bot protection (em `config/authkit.ts`). */
+export interface BotProtectionConfigInput {
+    /**
+     * Verificador fornecido pelo HOST. Recebe o token do widget + contexto e
+     * resolve `true` (humano/ok) ou `false` (bot/rejeitar). LANÇAR/timeout é
+     * tratado como FAIL-SAFE (permite + warning) — ver {@link verifyBotProtection}.
+     */
+    verify: (input: BotProtectionVerifyInput) => Promise<boolean>;
+    /** Ações protegidas. Default: `['login', 'signup']`. */
+    on?: BotProtectionAction[];
+    /** Widget injetado nas telas (script + container). Opcional. */
+    widget?: BotProtectionWidget;
+    /**
+     * Nomes de campo de body onde procurar o token, em ordem. Default:
+     * {@link DEFAULT_BOT_TOKEN_FIELDS}. O host pode passar uma lista própria.
+     */
+    tokenFields?: string[];
+    /**
+     * Timeout (ms) do `verify`. Estourar = FAIL-SAFE (permite). Default: 5000.
+     */
+    timeoutMs?: number;
+}
+/** Config resolvida do bot protection (sempre com defaults aplicados). */
+export interface ResolvedBotProtectionConfig {
+    verify: (input: BotProtectionVerifyInput) => Promise<boolean>;
+    on: BotProtectionAction[];
+    widget?: BotProtectionWidget;
+    tokenFields: string[];
+    timeoutMs: number;
+}
+/**
+ * Resolve a config do bot protection aplicando os defaults. Retorna `undefined`
+ * quando o host não configura `botProtection` (feature totalmente desligada).
+ */
+export declare function resolveBotProtection(input?: BotProtectionConfigInput): ResolvedBotProtectionConfig | undefined;
+/** `true` se o bot protection está ligado para `action`. */
+export declare function botProtectionApplies(cfg: ResolvedBotProtectionConfig | undefined, action: BotProtectionAction): boolean;
+/** Extrai o token do widget do body, testando os campos configurados em ordem. */
+export declare function extractBotToken(ctx: HttpContext, fields: string[]): string | null;
+/**
+ * Roda o `verify` do host com timeout e semântica FAIL-SAFE:
+ *   - `verify` resolve `false`  → `false` (rejeitar a request).
+ *   - `verify` resolve `true`   → `true`  (prosseguir).
+ *   - `verify` LANÇA            → `true`  (FAIL-SAFE) + warning.
+ *   - `verify` estoura o timeout→ `true`  (FAIL-SAFE) + warning.
+ *
+ * NUNCA lança para o caminho da request. Disponibilidade > proteção.
+ */
+export declare function verifyBotProtection(ctx: HttpContext, cfg: ResolvedBotProtectionConfig, action: BotProtectionAction): Promise<boolean>;
+/**
+ * Verifica o bot protection para `action` e, em rejeição, AUDITA
+ * `bot_protection.rejected` (sem o token). Retorna `false` quando a request deve
+ * ser bloqueada (bot detectado). Best-effort: usado pelos controllers antes de
+ * processar credenciais. Quando a feature não se aplica à ação, retorna `true`.
+ */
+export declare function guardBotProtection(ctx: HttpContext, cfg: ResolvedServerConfig, action: BotProtectionAction, meta?: {
+    email?: string | null;
+    clientId?: string | null;
+}): Promise<boolean>;
+/** Shape da setting `bot_protection` em `auth_settings`. */
+export interface BotProtectionSetting {
+    /** Liga/desliga em runtime. */
+    enabled: boolean;
+    /**
+     * Ações protegidas. Se omitido, herda do config. Só é considerado
+     * quando `enabled: true`.
+     */
+    on?: BotProtectionAction[];
+}
+/**
+ * Resolve a config EFETIVA do bot protection considerando o runtime setting
+ * armazenado em `auth_settings` (via `RuntimeSettings` / `SettingsCapability`).
+ *
+ * Regras:
+ *   - config ausente (host não configurou `botProtection`) → `undefined` sempre
+ *     (a feature não existe; settings são ignoradas).
+ *   - config presente + setting ausente/erro → retorna `config` intacto.
+ *   - config presente + setting `{ enabled: false }` → retorna `undefined`
+ *     (desligado em runtime).
+ *   - config presente + setting `{ enabled: true }` → retorna config com
+ *     `on` substituído pelo `setting.on` (se definido) ou pelo `config.on`.
+ *   - O `verify` NUNCA vem da setting (é código do host, não serializável).
+ *
+ * FAIL-SAFE: se `getSetting` retornar null (tabela ausente/erro), usa o config.
+ */
+export declare function resolveEffectiveBotProtection(config: ResolvedBotProtectionConfig | undefined, settings: SettingsCapability): Promise<ResolvedBotProtectionConfig | undefined>;

package/build/src/host/bot_protection.js

@@ -0,0 +1,132 @@
+/**
+ * Campos de body onde o token do widget costuma vir. Cobre os provedores comuns
+ * por padrão; o host pode sobrescrever via `tokenFields`.
+ *   - `cf-turnstile-response` (Cloudflare Turnstile)
+ *   - `h-captcha-response`    (hCaptcha)
+ *   - `g-recaptcha-response`  (Google reCAPTCHA)
+ *   - `authkit-bot-token`     (genérico, p/ widgets custom)
+ */
+export const DEFAULT_BOT_TOKEN_FIELDS = [
+    'cf-turnstile-response',
+    'h-captcha-response',
+    'g-recaptcha-response',
+    'authkit-bot-token',
+];
+/**
+ * Resolve a config do bot protection aplicando os defaults. Retorna `undefined`
+ * quando o host não configura `botProtection` (feature totalmente desligada).
+ */
+export function resolveBotProtection(input) {
+    if (!input)
+        return undefined;
+    const on = input.on && input.on.length > 0 ? input.on : ['login', 'signup'];
+    const tokenFields = input.tokenFields && input.tokenFields.length > 0
+        ? input.tokenFields
+        : [...DEFAULT_BOT_TOKEN_FIELDS];
+    return {
+        verify: input.verify,
+        on,
+        widget: input.widget,
+        tokenFields,
+        timeoutMs: input.timeoutMs && input.timeoutMs > 0 ? input.timeoutMs : 5000,
+    };
+}
+/** `true` se o bot protection está ligado para `action`. */
+export function botProtectionApplies(cfg, action) {
+    return !!cfg && cfg.on.includes(action);
+}
+/** Extrai o token do widget do body, testando os campos configurados em ordem. */
+export function extractBotToken(ctx, fields) {
+    for (const field of fields) {
+        const value = ctx.request.input(field);
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return null;
+}
+/**
+ * Roda o `verify` do host com timeout e semântica FAIL-SAFE:
+ *   - `verify` resolve `false`  → `false` (rejeitar a request).
+ *   - `verify` resolve `true`   → `true`  (prosseguir).
+ *   - `verify` LANÇA            → `true`  (FAIL-SAFE) + warning.
+ *   - `verify` estoura o timeout→ `true`  (FAIL-SAFE) + warning.
+ *
+ * NUNCA lança para o caminho da request. Disponibilidade > proteção.
+ */
+export async function verifyBotProtection(ctx, cfg, action) {
+    const token = extractBotToken(ctx, cfg.tokenFields);
+    const ip = ctx.request.ip?.() ?? undefined;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(true), cfg.timeoutMs);
+    });
+    try {
+        const result = await Promise.race([cfg.verify({ token, ip, action }), timeout]);
+        return result;
+    }
+    catch (error) {
+        // FAIL-SAFE: erro no verificador do host NÃO bloqueia o login.
+        ctx.logger.warn({ err: error, action }, 'authkit: bot protection verify lançou — fail-safe (request permitida)');
+        return true;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Verifica o bot protection para `action` e, em rejeição, AUDITA
+ * `bot_protection.rejected` (sem o token). Retorna `false` quando a request deve
+ * ser bloqueada (bot detectado). Best-effort: usado pelos controllers antes de
+ * processar credenciais. Quando a feature não se aplica à ação, retorna `true`.
+ */
+export async function guardBotProtection(ctx, cfg, action, meta) {
+    const bot = cfg.botProtection;
+    if (!botProtectionApplies(bot, action))
+        return true;
+    const ok = await verifyBotProtection(ctx, bot, action);
+    if (ok)
+        return true;
+    // Rejeitado: audita SEM o token (apenas action + ip + contexto mínimo).
+    await cfg.audit?.record({
+        type: 'bot_protection.rejected',
+        email: meta?.email ?? null,
+        ip: ctx.request.ip?.() ?? null,
+        clientId: meta?.clientId ?? null,
+        metadata: { action },
+    });
+    return false;
+}
+/**
+ * Resolve a config EFETIVA do bot protection considerando o runtime setting
+ * armazenado em `auth_settings` (via `RuntimeSettings` / `SettingsCapability`).
+ *
+ * Regras:
+ *   - config ausente (host não configurou `botProtection`) → `undefined` sempre
+ *     (a feature não existe; settings são ignoradas).
+ *   - config presente + setting ausente/erro → retorna `config` intacto.
+ *   - config presente + setting `{ enabled: false }` → retorna `undefined`
+ *     (desligado em runtime).
+ *   - config presente + setting `{ enabled: true }` → retorna config com
+ *     `on` substituído pelo `setting.on` (se definido) ou pelo `config.on`.
+ *   - O `verify` NUNCA vem da setting (é código do host, não serializável).
+ *
+ * FAIL-SAFE: se `getSetting` retornar null (tabela ausente/erro), usa o config.
+ */
+export async function resolveEffectiveBotProtection(config, settings) {
+    if (!config)
+        return undefined;
+    const raw = await settings.getSetting('bot_protection');
+    if (raw === null || raw === undefined)
+        return config;
+    // Valida a shape mínima da setting.
+    if (typeof raw !== 'object' || typeof raw.enabled !== 'boolean') {
+        return config; // shape inválida → fallback
+    }
+    const setting = raw;
+    if (!setting.enabled)
+        return undefined; // runtime off
+    // enabled: true — on pode sobrescrever
+    const on = Array.isArray(setting.on) && setting.on.length > 0 ? setting.on : config.on;
+    return { ...config, on };
+}

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

@@ -0,0 +1,19 @@
+export interface ClientBrand {
+    /** Client id (OIDC) que iniciou o fluxo — chave estável pra escolher tema/tela por produto. */
+    clientId?: string;
+    appName: string;
+    accent: string;
+    accentSoft: string;
+    tagline: string;
+    company?: string;
+    audienceLabel?: string;
+}
+export interface BrandingConfig {
+    company: string;
+    clients: Record<string, Omit<ClientBrand, 'company' | 'audienceLabel'>>;
+    default: Omit<ClientBrand, 'company' | 'audienceLabel'>;
+    firstParty: string[];
+    audienceLabels?: Record<string, string>;
+}
+export declare function isFirstParty(cfg: BrandingConfig, clientId: string | undefined): boolean;
+export declare function brandFor(cfg: BrandingConfig, clientId: string | undefined, audience?: string): ClientBrand;

package/build/src/host/branding.js

@@ -0,0 +1,8 @@
+export function isFirstParty(cfg, clientId) {
+    return !!clientId && cfg.firstParty.includes(clientId);
+}
+export function brandFor(cfg, clientId, audience) {
+    const base = (clientId && cfg.clients[clientId]) || cfg.default;
+    const label = audience ? cfg.audienceLabels?.[audience] : undefined;
+    return { ...base, clientId, company: cfg.company, ...(label ? { audienceLabel: label } : {}) };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Config locks — quando uma feature/política é definida explicitamente no
+ * `defineConfig`, ela fica TRAVADA: o valor do config manda e a UI/Admin API NÃO
+ * pode mais alterá-la em runtime. Quando NÃO está no config, a UI controla
+ * livremente o valor (runtime setting em `auth_settings`).
+ *
+ * Mecânica (elegante, sem tocar nos ~20 resolvers):
+ *   - `RuntimeSettings.getSetting` retorna `null` para keys travadas → cada
+ *     `resolveEffective*` cai no `configDefault` (= o valor do config). Logo, config vence.
+ *   - `RuntimeSettings.setSetting`/`deleteSetting` lançam {@link SettingLockedError}
+ *     para keys travadas → o write path da Admin API/console rejeita com 423.
+ *   - A UI lê a lista de keys travadas (`lockedSettingKeys()`) e desabilita o
+ *     controle + mostra o aviso "definido via defineConfig".
+ *
+ * O registro é MODULE-LEVEL e setado uma vez no boot do provider — o IdP é um por
+ * processo e os locks vêm de config estático (imutável pós-boot).
+ */
+/**
+ * Deriva as keys de `auth_settings` travadas a partir dos campos EXPLICITAMENTE
+ * presentes no input do `defineConfig`. Só mapeia keys que têm contraparte tanto
+ * em config quanto na UI (runtime setting); features sem campo de config nunca
+ * travam (UI sempre controla).
+ */
+export declare function deriveLockedSettingKeys(config: Record<string, any>): string[];
+/** Erro lançado ao tentar gravar/remover uma setting travada via `defineConfig`. */
+export declare class SettingLockedError extends Error {
+    readonly code = "E_SETTING_LOCKED";
+    readonly key: string;
+    constructor(key: string);
+}
+/** Define o conjunto de keys travadas (chamado uma vez no boot do provider). */
+export declare function setLockedSettingKeys(keys: Iterable<string>): void;
+/** Limpa os locks — uso em testes. */
+export declare function resetLockedSettingKeys(): void;
+/** A setting `key` está travada por config? */
+export declare function isSettingLocked(key: string): boolean;
+/** Lista (snapshot) das keys travadas — consumida pelo read path da UI. */
+export declare function lockedSettingKeys(): string[];

package/build/src/host/config_locks.js

@@ -0,0 +1,70 @@
+/**
+ * Config locks — quando uma feature/política é definida explicitamente no
+ * `defineConfig`, ela fica TRAVADA: o valor do config manda e a UI/Admin API NÃO
+ * pode mais alterá-la em runtime. Quando NÃO está no config, a UI controla
+ * livremente o valor (runtime setting em `auth_settings`).
+ *
+ * Mecânica (elegante, sem tocar nos ~20 resolvers):
+ *   - `RuntimeSettings.getSetting` retorna `null` para keys travadas → cada
+ *     `resolveEffective*` cai no `configDefault` (= o valor do config). Logo, config vence.
+ *   - `RuntimeSettings.setSetting`/`deleteSetting` lançam {@link SettingLockedError}
+ *     para keys travadas → o write path da Admin API/console rejeita com 423.
+ *   - A UI lê a lista de keys travadas (`lockedSettingKeys()`) e desabilita o
+ *     controle + mostra o aviso "definido via defineConfig".
+ *
+ * O registro é MODULE-LEVEL e setado uma vez no boot do provider — o IdP é um por
+ * processo e os locks vêm de config estático (imutável pós-boot).
+ */
+import { SETTING_KEYS } from './runtime_toggles.js';
+/**
+ * Deriva as keys de `auth_settings` travadas a partir dos campos EXPLICITAMENTE
+ * presentes no input do `defineConfig`. Só mapeia keys que têm contraparte tanto
+ * em config quanto na UI (runtime setting); features sem campo de config nunca
+ * travam (UI sempre controla).
+ */
+export function deriveLockedSettingKeys(config) {
+    const locked = [];
+    const add = (present, key) => {
+        if (present)
+            locked.push(key);
+    };
+    add(config.registration !== undefined, SETTING_KEYS.REGISTRATION);
+    add(config.login?.requireVerifiedEmail !== undefined, SETTING_KEYS.REQUIRE_VERIFIED_EMAIL);
+    add(config.lockout !== undefined, SETTING_KEYS.LOCKOUT);
+    add(config.rateLimit !== undefined, SETTING_KEYS.RATE_LIMIT);
+    add(config.trustedDevices !== undefined, SETTING_KEYS.TRUSTED_DEVICES);
+    add(config.botProtection !== undefined, SETTING_KEYS.BOT_PROTECTION);
+    add(config.organizations !== undefined, SETTING_KEYS.ORGANIZATIONS_POLICY);
+    add(config.admin?.impersonation !== undefined, SETTING_KEYS.ADMIN_IMPERSONATION);
+    add(config.ttl !== undefined, SETTING_KEYS.TOKEN_TTL);
+    return locked;
+}
+/** Erro lançado ao tentar gravar/remover uma setting travada via `defineConfig`. */
+export class SettingLockedError extends Error {
+    code = 'E_SETTING_LOCKED';
+    key;
+    constructor(key) {
+        super(`A setting "${key}" foi definida via defineConfig() e está travada — ` +
+            `não pode ser alterada em runtime (console/Admin API). ` +
+            `Remova-a do defineConfig para liberar a edição pela UI.`);
+        this.name = 'SettingLockedError';
+        this.key = key;
+    }
+}
+let lockedKeys = new Set();
+/** Define o conjunto de keys travadas (chamado uma vez no boot do provider). */
+export function setLockedSettingKeys(keys) {
+    lockedKeys = new Set(keys);
+}
+/** Limpa os locks — uso em testes. */
+export function resetLockedSettingKeys() {
+    lockedKeys = new Set();
+}
+/** A setting `key` está travada por config? */
+export function isSettingLocked(key) {
+    return lockedKeys.has(key);
+}
+/** Lista (snapshot) das keys travadas — consumida pelo read path da UI. */
+export function lockedSettingKeys() {
+    return [...lockedKeys];
+}

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

@@ -0,0 +1,27 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Helpers públicos para integrar a sessão do console do AuthKit com
+ * qualquer coisa fora do pacote (ex.: proteger o dashboard do
+ * adonis-telescope, rotas administrativas próprias, etc).
+ *
+ * Use estes helpers em vez de ler `ctx.session` com a key interna —
+ * eles são contrato público e continuam funcionando se o mecanismo de
+ * sessão mudar.
+ */
+/**
+ * Retorna o id da conta logada no console (ou `null` quando não há
+ * sessão).
+ */
+export declare function getAccountId(ctx: HttpContext): string | null;
+/**
+ * `true` quando o request carrega uma sessão de conta do console.
+ */
+export declare function hasAccountSession(ctx: HttpContext): boolean;
+/**
+ * URL do login do console, com `return_to` opcional de volta ao destino
+ * original após autenticar.
+ *
+ * @example
+ * consoleLoginUrl('/telescope') // => '/account/login?return_to=%2Ftelescope'
+ */
+export declare function consoleLoginUrl(returnTo?: string): string;