@adonis-agora/authkit-server 0.34.0

package/build/src/host/middleware/account_auth.js

@@ -0,0 +1,11 @@
+import '../augmentations.js';
+export const ACCOUNT_SESSION_KEY = 'account_user_id';
+export default class AccountAuthMiddleware {
+    async handle(ctx, next) {
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!userId) {
+            return ctx.response.redirect('/account/login');
+        }
+        return next();
+    }
+}

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

@@ -0,0 +1,103 @@
+/**
+ * OTP Lockout — trava o fator TOTP/recovery após N falhas consecutivas.
+ *
+ * Implementação paralela ao account_lockout.ts, mas keyed por accountId (não por
+ * e-mail) e limitando o FATOR (não a conta inteira). Usa a mesma infraestrutura do
+ * `@adonisjs/limiter` (peer/opt-in, fail-safe).
+ *
+ * Esquema de chaves (namespaced por accountId):
+ *   `authkit_otp_fail:<accountId>`    — contador de falhas TOTP/recovery.
+ *   `authkit_otp_lock:<accountId>`    — flag de travamento do fator OTP.
+ *
+ * Storage do token de desbloqueio: prefixo `ou:` no campo `passwordResetToken`
+ * do model do usuário (mesma abordagem de magic link `ml:` e email change `ec:`).
+ * Sem migração necessária — reutiliza coluna existente.
+ *
+ * No-op total quando o `@adonisjs/limiter` não está instalado.
+ */
+import type { AuditSink } from '../audit/audit_sink.js';
+import type { SettingsCapability } from './runtime_settings.js';
+export interface OtpLockoutSetting {
+    enabled?: boolean;
+    maxAttempts?: number;
+    unlockTtlHours?: number;
+}
+export interface ResolvedOtpLockoutSetting {
+    enabled: boolean;
+    maxAttempts: number;
+    unlockTtlHours: number;
+}
+export declare const OTP_LOCKOUT_DEFAULTS: ResolvedOtpLockoutSetting;
+/**
+ * Resolve a setting `otp_lockout` em runtime (fail-safe).
+ */
+export declare function resolveEffectiveOtpLockout(settings: SettingsCapability): Promise<ResolvedOtpLockoutSetting>;
+/** Prefixo do token de desbloqueio OTP no campo passwordResetToken. */
+export declare const OTP_UNLOCK_TOKEN_PREFIX = "ou:";
+/**
+ * Gera um token de desbloqueio OTP para armazenar no model do usuário.
+ * O token bruto vai no e-mail; o hash SHA-256 fica no DB (mesmo padrão
+ * de email_change e reset de senha).
+ *
+ * @returns `{ raw, prefix }` — `raw` vai na URL; `prefix + sha256(raw)` no DB.
+ */
+export declare function generateOtpUnlockToken(): {
+    raw: string;
+    dbValue: string;
+};
+/**
+ * Converte um token bruto recebido na URL no valor de DB correspondente.
+ */
+export declare function rawToDbOtpUnlockToken(raw: string): string;
+type LimiterService = any;
+/** Reaponta o loader (usado em testes). @internal */
+export declare function __setOtpLockoutLimiterLoaderForTests(fn: (() => Promise<LimiterService | null>) | undefined): void;
+export interface OtpLockoutAuditContext {
+    sink?: AuditSink;
+    ip?: string | null;
+}
+/**
+ * Logger mínimo (subconjunto do logger do AdonisJS) para observar as degradações
+ * fail-safe. Sem ele, os caminhos de erro continuam silenciosos (backward-compat).
+ */
+export interface OtpLockoutLogger {
+    warn(obj: unknown, msg?: string): void;
+}
+/**
+ * Gerencia o lockout do fator OTP (TOTP + recovery) por accountId.
+ * No-op quando o limiter não está disponível.
+ */
+export declare class OtpLockout {
+    private cfg;
+    private logger?;
+    constructor(cfg: ResolvedOtpLockoutSetting, logger?: OtpLockoutLogger | undefined);
+    private failKey;
+    private lockKey;
+    private limiter;
+    /** Store de contagem de falhas (janela = unlockTtlHours * 2 s). */
+    private failStore;
+    /** Store da flag de lock (requests=1, duration=unlockTtlHours). */
+    private lockStore;
+    /**
+     * Verifica se o fator OTP está travado para a conta.
+     * FAIL-SAFE: erro → `false` (nunca bloqueia por falha de infra).
+     */
+    isLocked(accountId: string): Promise<boolean>;
+    /**
+     * Registra uma falha de TOTP/recovery. Ao atingir maxAttempts, trava o fator.
+     * Emite `otp.locked` no audit (uma vez, na transição).
+     * FAIL-SAFE: erros do limiter nunca propagam.
+     */
+    recordFailure(accountId: string, audit?: OtpLockoutAuditContext): Promise<boolean>;
+    /**
+     * Limpa o estado de falhas OTP após um código correto.
+     * FAIL-SAFE: erros do limiter nunca propagam.
+     */
+    clearFailures(accountId: string): Promise<void>;
+    /**
+     * Zera o estado completo (falhas + lock) — chamado pelo `GET /auth/otp-unlock/:token`.
+     */
+    unlock(accountId: string): Promise<void>;
+}
+export declare function createOtpLockout(cfg: ResolvedOtpLockoutSetting, logger?: OtpLockoutLogger): OtpLockout;
+export {};

package/build/src/host/otp_lockout.js

@@ -0,0 +1,221 @@
+/**
+ * OTP Lockout — trava o fator TOTP/recovery após N falhas consecutivas.
+ *
+ * Implementação paralela ao account_lockout.ts, mas keyed por accountId (não por
+ * e-mail) e limitando o FATOR (não a conta inteira). Usa a mesma infraestrutura do
+ * `@adonisjs/limiter` (peer/opt-in, fail-safe).
+ *
+ * Esquema de chaves (namespaced por accountId):
+ *   `authkit_otp_fail:<accountId>`    — contador de falhas TOTP/recovery.
+ *   `authkit_otp_lock:<accountId>`    — flag de travamento do fator OTP.
+ *
+ * Storage do token de desbloqueio: prefixo `ou:` no campo `passwordResetToken`
+ * do model do usuário (mesma abordagem de magic link `ml:` e email change `ec:`).
+ * Sem migração necessária — reutiliza coluna existente.
+ *
+ * No-op total quando o `@adonisjs/limiter` não está instalado.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash, randomBytes } from 'node:crypto';
+import { SETTING_KEYS } from './runtime_toggles.js';
+export const OTP_LOCKOUT_DEFAULTS = {
+    enabled: true,
+    maxAttempts: 5,
+    unlockTtlHours: 24,
+};
+/**
+ * Resolve a setting `otp_lockout` em runtime (fail-safe).
+ */
+export async function resolveEffectiveOtpLockout(settings) {
+    try {
+        const raw = await settings.getSetting(SETTING_KEYS.OTP_LOCKOUT);
+        if (raw === null || raw === undefined)
+            return OTP_LOCKOUT_DEFAULTS;
+        if (typeof raw !== 'object' || Array.isArray(raw))
+            return OTP_LOCKOUT_DEFAULTS;
+        const s = raw;
+        return {
+            enabled: typeof s.enabled === 'boolean' ? s.enabled : OTP_LOCKOUT_DEFAULTS.enabled,
+            maxAttempts: typeof s.maxAttempts === 'number' && s.maxAttempts >= 1
+                ? Math.floor(s.maxAttempts)
+                : OTP_LOCKOUT_DEFAULTS.maxAttempts,
+            unlockTtlHours: typeof s.unlockTtlHours === 'number' && s.unlockTtlHours >= 1
+                ? Math.floor(s.unlockTtlHours)
+                : OTP_LOCKOUT_DEFAULTS.unlockTtlHours,
+        };
+    }
+    catch {
+        return OTP_LOCKOUT_DEFAULTS;
+    }
+}
+// ---------------------------------------------------------------------------
+// Token de desbloqueio (OTP unlock)
+// ---------------------------------------------------------------------------
+/** Prefixo do token de desbloqueio OTP no campo passwordResetToken. */
+export const OTP_UNLOCK_TOKEN_PREFIX = 'ou:';
+/**
+ * Gera um token de desbloqueio OTP para armazenar no model do usuário.
+ * O token bruto vai no e-mail; o hash SHA-256 fica no DB (mesmo padrão
+ * de email_change e reset de senha).
+ *
+ * @returns `{ raw, prefix }` — `raw` vai na URL; `prefix + sha256(raw)` no DB.
+ */
+export function generateOtpUnlockToken() {
+    const raw = randomBytes(32).toString('hex');
+    const hash = createHash('sha256').update(raw).digest('hex');
+    return { raw, dbValue: `${OTP_UNLOCK_TOKEN_PREFIX}${hash}` };
+}
+/**
+ * Converte um token bruto recebido na URL no valor de DB correspondente.
+ */
+export function rawToDbOtpUnlockToken(raw) {
+    const hash = createHash('sha256').update(raw).digest('hex');
+    return `${OTP_UNLOCK_TOKEN_PREFIX}${hash}`;
+}
+let limiterPromise;
+async function loadLimiter() {
+    if (!limiterPromise) {
+        const spec = '@adonisjs/limiter/services/main';
+        limiterPromise = import(__rewriteRelativeImportExtension(spec))
+            .then((m) => m.default ?? null)
+            .catch(() => null);
+    }
+    return limiterPromise;
+}
+/** Reaponta o loader (usado em testes). @internal */
+export function __setOtpLockoutLimiterLoaderForTests(fn) {
+    if (fn) {
+        limiterPromise = fn();
+    }
+    else {
+        limiterPromise = undefined;
+    }
+}
+/**
+ * Gerencia o lockout do fator OTP (TOTP + recovery) por accountId.
+ * No-op quando o limiter não está disponível.
+ */
+export class OtpLockout {
+    cfg;
+    logger;
+    constructor(cfg, logger) {
+        this.cfg = cfg;
+        this.logger = logger;
+    }
+    failKey(accountId) {
+        return `authkit_otp_fail:${accountId}`;
+    }
+    lockKey(accountId) {
+        return `authkit_otp_lock:${accountId}`;
+    }
+    async limiter() {
+        if (!this.cfg.enabled)
+            return null;
+        return loadLimiter();
+    }
+    /** Store de contagem de falhas (janela = unlockTtlHours * 2 s). */
+    failStore(l) {
+        const opts = { requests: this.cfg.maxAttempts, duration: this.cfg.unlockTtlHours * 3600 * 2 };
+        return l.use(opts);
+    }
+    /** Store da flag de lock (requests=1, duration=unlockTtlHours). */
+    lockStore(l) {
+        const opts = { requests: 1, duration: this.cfg.unlockTtlHours * 3600 };
+        return l.use(opts);
+    }
+    /**
+     * Verifica se o fator OTP está travado para a conta.
+     * FAIL-SAFE: erro → `false` (nunca bloqueia por falha de infra).
+     */
+    async isLocked(accountId) {
+        const l = await this.limiter();
+        if (!l || !accountId)
+            return false;
+        try {
+            return await this.lockStore(l).isBlocked(this.lockKey(accountId));
+        }
+        catch (err) {
+            // Falha do limiter NUNCA derruba o login — degrada para "não travado". Mas
+            // loga: enquanto o limiter estiver quebrado, o lockout de OTP fica desligado.
+            this.logger?.warn({ err, accountId }, 'authkit: OTP lockout isLocked check failed (limiter error) — degrading to unlocked (fail-safe); OTP lockout is effectively disabled until the limiter recovers.');
+            return false;
+        }
+    }
+    /**
+     * Registra uma falha de TOTP/recovery. Ao atingir maxAttempts, trava o fator.
+     * Emite `otp.locked` no audit (uma vez, na transição).
+     * FAIL-SAFE: erros do limiter nunca propagam.
+     */
+    async recordFailure(accountId, audit) {
+        const l = await this.limiter();
+        if (!l || !accountId)
+            return false;
+        try {
+            // Se já está travado, não conta de novo.
+            if (await this.lockStore(l).isBlocked(this.lockKey(accountId)))
+                return true;
+            const failStore = this.failStore(l);
+            const res = await failStore.increment(this.failKey(accountId));
+            const consumed = res?.consumed ?? 0;
+            if (consumed < this.cfg.maxAttempts)
+                return false;
+            // Transição para travado.
+            await this.lockStore(l).block(this.lockKey(accountId), this.cfg.unlockTtlHours * 3600);
+            await failStore.delete(this.failKey(accountId));
+            await audit?.sink?.record({
+                type: 'otp.locked',
+                accountId,
+                ip: audit?.ip ?? null,
+                metadata: { maxAttempts: this.cfg.maxAttempts },
+            });
+            return true;
+        }
+        catch (err) {
+            // Falha do limiter ao registrar a tentativa: a falha NÃO é contabilizada, o
+            // que enfraquece a proteção anti-brute-force do fator OTP. Nunca propaga (o
+            // login não pode quebrar por infra), mas loga para não ficar invisível.
+            this.logger?.warn({ err, accountId }, 'authkit: OTP lockout recordFailure failed (limiter error) — failure NOT counted; brute-force protection on the OTP factor is degraded until the limiter recovers.');
+            return false;
+        }
+    }
+    /**
+     * Limpa o estado de falhas OTP após um código correto.
+     * FAIL-SAFE: erros do limiter nunca propagam.
+     */
+    async clearFailures(accountId) {
+        const l = await this.limiter();
+        if (!l || !accountId)
+            return;
+        try {
+            await this.failStore(l).delete(this.failKey(accountId));
+        }
+        catch {
+            // no-op
+        }
+    }
+    /**
+     * Zera o estado completo (falhas + lock) — chamado pelo `GET /auth/otp-unlock/:token`.
+     */
+    async unlock(accountId) {
+        const l = await this.limiter();
+        if (!l || !accountId)
+            return;
+        try {
+            await this.failStore(l).delete(this.failKey(accountId));
+            await this.lockStore(l).delete(this.lockKey(accountId));
+        }
+        catch {
+            // no-op
+        }
+    }
+}
+export function createOtpLockout(cfg, logger) {
+    return new OtpLockout(cfg, logger);
+}

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

@@ -0,0 +1,39 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ResolvedRateLimitConfig } from '../define_config.js';
+/**
+ * Assinatura mínima de um middleware do AdonisJS. Evita acoplar o tipo concreto
+ * do `@adonisjs/limiter` (que pode não estar instalado no host).
+ */
+export type ThrottleMiddleware = (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Os throttles construídos para as rotas sensíveis do host-kit.
+ * - `login`: compartilhado por login/signup/forgot/reset (keyed por IP).
+ * - `introspection`: introspecção de PAT (keyed por IP ou pelo bearer secret).
+ */
+export interface AuthThrottles {
+    login: ThrottleMiddleware;
+    introspection: ThrottleMiddleware;
+    /**
+     * Throttle por IP do grupo admin-api (R6). Anti-brute-force REAL da Bearer key:
+     * diferente do `introspection` (keyed pelo próprio token, então cada key tentada
+     * cai em bucket distinto), este é keyed por `ctx.request.ip()` — limita o número
+     * de tentativas vindas do MESMO IP independentemente de qual key foi usada (M8).
+     */
+    adminIp: ThrottleMiddleware;
+}
+/**
+ * Service do `@adonisjs/limiter` resolvido de forma preguiçosa. Tipado como `any`
+ * de propósito: a lib NÃO depende do limiter em tempo de compilação (peer/opt-in).
+ */
+type LimiterService = any;
+/**
+ * Permite reapontar/limpar o loader do limiter (usado em testes).
+ * @internal
+ */
+export declare function __setLimiterLoaderForTests(fn: (() => Promise<LimiterService | null>) | undefined): void;
+/**
+ * Cria os throttles do host-kit a partir da config resolvida.
+ * Retorna `undefined` quando rate-limit está desligado (rotas montadas sem throttle).
+ */
+export declare function createAuthThrottles(config: ResolvedRateLimitConfig): AuthThrottles | undefined;
+export {};

package/build/src/host/rate_limit.js

@@ -0,0 +1,94 @@
+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 limiterServicePromise;
+/**
+ * Importa o service do limiter do HOST de forma preguiçosa e fail-safe.
+ * Se `@adonisjs/limiter` não estiver instalado/configurado, resolve `null`
+ * e o throttle vira no-op (não quebra o boot nem a request).
+ */
+async function loadLimiter() {
+    if (!limiterServicePromise) {
+        // Indireção via variável: o `@adonisjs/limiter` é peer/opcional e pode não
+        // estar instalado na lib, então o specifier não é resolvido em build-time.
+        const specifier = '@adonisjs/limiter/services/main';
+        limiterServicePromise = import(__rewriteRelativeImportExtension(specifier))
+            .then((mod) => mod.default ?? null)
+            .catch(() => null);
+    }
+    return limiterServicePromise;
+}
+/**
+ * Permite reapontar/limpar o loader do limiter (usado em testes).
+ * @internal
+ */
+export function __setLimiterLoaderForTests(fn) {
+    if (fn) {
+        limiterServicePromise = fn();
+    }
+    else {
+        limiterServicePromise = undefined;
+    }
+}
+/**
+ * Constrói um middleware de throttle preguiçoso. A configuração do limiter
+ * (`allowRequests().every().usingKey()`) só é resolvida na primeira request,
+ * porque o service do limiter é importado de forma assíncrona. Se o limiter
+ * não existir, o middleware passa adiante sem throttle (fail-safe).
+ */
+function buildThrottle(name, bucket, store, keyOf) {
+    let middleware;
+    return async (ctx, next) => {
+        if (!middleware) {
+            const limiter = await loadLimiter();
+            if (!limiter) {
+                // Limiter indisponível: degrada para no-op (sem quebrar a request).
+                middleware = async (_ctx, n) => n();
+            }
+            else {
+                middleware = limiter.define(name, (reqCtx) => {
+                    let b = limiter.allowRequests(bucket.points).every(bucket.duration);
+                    if (store)
+                        b = b.store(store);
+                    const key = keyOf?.(reqCtx);
+                    if (key)
+                        b = b.usingKey(key);
+                    return b;
+                });
+            }
+        }
+        return middleware(ctx, next);
+    };
+}
+/**
+ * Cria os throttles do host-kit a partir da config resolvida.
+ * Retorna `undefined` quando rate-limit está desligado (rotas montadas sem throttle).
+ */
+export function createAuthThrottles(config) {
+    if (!config.enabled)
+        return undefined;
+    return {
+        // Login/signup/forgot/reset: keyed por IP (default do HttpLimiter).
+        login: buildThrottle('authkit_login', config.login, config.store),
+        // Introspecção de PAT: keyed pelo bearer secret quando presente, senão por IP.
+        introspection: buildThrottle('authkit_pat_introspection', config.introspection, config.store, (ctx) => {
+            const auth = ctx.request.header('authorization');
+            if (auth && auth.toLowerCase().startsWith('bearer ')) {
+                return `bearer:${auth.slice(7).trim()}`;
+            }
+            return undefined;
+        }),
+        // Admin-api por IP: anti-brute-force REAL da Bearer key (M8). Keyed por IP —
+        // tentar muitas keys diferentes do mesmo IP cai no MESMO bucket, ao contrário
+        // do `introspection` (bucket por token). Camada adicional, não substitui o
+        // throttle de introspection nas rotas que o usam.
+        adminIp: buildThrottle('authkit_admin_ip', config.adminIp, config.store, (ctx) => {
+            return `admin-ip:${ctx.request.ip?.() ?? 'unknown'}`;
+        }),
+    };
+}

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

@@ -0,0 +1,97 @@
+import type { Router } from '@adonisjs/core/http';
+import type { AuthSocialConfig, RateLimitConfigInput } from '../define_config.js';
+/** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
+export declare const ACCOUNT_LAST_SEEN_KEY = "authkit_last_seen";
+/**
+ * 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. Deve casar com o final do issuer. OPCIONAL:
+     * quando omitido, vem do `config/authkit.ts` (lido no boot); default `/oidc`.
+     */
+    mountPath?: string;
+    /**
+     * Login social opt-in; quando presente, monta as rotas sociais (usam ctx.ally).
+     * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
+     * tomada em tempo de registro, antes do config (lazy) resolver.
+     */
+    social?: AuthSocialConfig;
+    /**
+     * Rate-limiting (anti-brute-force) das rotas sensíveis. Necessário aqui (e não
+     * só no config) porque a aplicação do throttle acontece em tempo de registro de
+     * rota. Ligado por default (mesma resolução do config). Espelhe o `rateLimit` de
+     * config/authkit.ts. Se `@adonisjs/limiter` não estiver configurado no host
+     * (config/limiter.ts), o throttle vira no-op (fail-safe).
+     */
+    rateLimit?: RateLimitConfigInput;
+    /**
+     * Console admin opt-in (B6).
+     *
+     * - `true` → comportamento padrão: monta as rotas sob o prefixo `/admin` (back-compat total);
+     *   modo UI `'react'` (SPA self-contained).
+     * - `{ prefix?: string }` → prefixo customizado.
+     *   O prefixo é normalizado: começa com `/`, sem trailing slash.
+     *   Quando `prefix` é omitido ou vazio, usa o default `/admin`.
+     *
+     * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
+     * tomada em tempo de registro, antes do config (lazy) resolver.
+     * Espelhe o `admin.enabled` de config/authkit.ts.
+     *
+     * @example
+     * // Prefixo padrão
+     * registerAuthHost(router, { mountPath: '/oidc', admin: true })
+     *
+     * // Prefixo customizado — console em /auth/admin
+     * registerAuthHost(router, { mountPath: '/oidc', admin: { prefix: '/auth/admin' } })
+     */
+    admin?: boolean | {
+        prefix?: string;
+    };
+    /**
+     * Admin REST API opt-in (R6).
+     *
+     * - `true` → comportamento padrão: monta o grupo sob `/api/authkit/v1` (back-compat total).
+     * - `{ prefix?: string }` → monta sob o prefixo fornecido, e.g. `{ prefix: '/authkit/api' }`.
+     *   O prefixo é normalizado: começa com `/`, sem trailing slash.
+     *   Quando `prefix` é omitido ou vazio, usa o default `/api/authkit/v1`.
+     *
+     * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
+     * tomada em tempo de registro, antes do config (lazy) resolver.
+     * Espelhe o `adminApi.enabled` de config/authkit.ts.
+     *
+     * @example
+     * // Prefixo padrão (back-compat)
+     * registerAuthHost(router, { mountPath: '/oidc', adminApi: true })
+     *
+     * // Prefixo customizado — API em /authkit/api
+     * registerAuthHost(router, { mountPath: '/oidc', adminApi: { prefix: '/authkit/api' } })
+     */
+    adminApi?: boolean | {
+        prefix?: string;
+    };
+}
+/**
+ * Monta todas as rotas do host-kit do Authorization Server numa chamada.
+ * Substitui registerOidcRoutes + o hand-wiring do start/routes.ts do host.
+ */
+export declare function registerAuthHost(router: Router, opts?: AuthHostOptions): void;