@adonis-agora/authkit-server 0.34.0

package/build/src/host/admin_console/console_settings_controller.d.ts

@@ -0,0 +1,47 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Endpoints JSON de runtime settings do console admin React.
+ *
+ * GET    {prefix}/api/settings                       → lista settings globais
+ * GET    {prefix}/api/settings?organizationId={id}   → lista settings da org
+ * PUT    {prefix}/api/settings/:key                  → upsert de setting global
+ * PUT    {prefix}/api/settings/:key?organizationId=  → upsert de setting org-scoped
+ * DELETE {prefix}/api/settings/:key                  → remover setting global
+ * DELETE {prefix}/api/settings/:key?organizationId=  → remover setting org-scoped
+ *
+ * 404 honesto (`capability_unsupported`) quando a tabela auth_settings está ausente.
+ *
+ * Keys org-scopáveis: `organizations_policy`, `roles_catalog`.
+ */
+export default class ConsoleSettingsController {
+    /** GET {prefix}/api/settings */
+    index(ctx: HttpContext): Promise<void | {
+        data: {
+            lockedBy?: "config" | undefined;
+            key: string;
+            organizationId: string | null;
+            value: unknown;
+            updatedAt: string | null;
+            updatedBy: string | null;
+            locked: boolean;
+        }[];
+        locked: string[];
+    }>;
+    /** PUT {prefix}/api/settings/:key — body: { value: any } */
+    upsert(ctx: HttpContext): Promise<void | {
+        lockedBy?: "config" | undefined;
+        key: string;
+        organizationId: string | null;
+        value: unknown;
+        updatedAt: string | null;
+        updatedBy: string | null;
+        locked: boolean;
+    }>;
+    /** DELETE {prefix}/api/settings/:key */
+    destroy(ctx: HttpContext): Promise<void | {
+        key: string;
+        organizationId: string | null;
+        deleted: boolean;
+    }>;
+}

package/build/src/host/admin_console/console_settings_controller.js

@@ -0,0 +1,115 @@
+import '../augmentations.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { settingDto, apiError } from '../admin_api/dto.js';
+import { isSettingLocked, lockedSettingKeys, SettingLockedError } from '../config_locks.js';
+/** 423 Locked: setting travada via defineConfig. */
+function lockedResponse(ctx, err) {
+    return ctx.response
+        .status(423)
+        .send(apiError('setting_locked', err.message, { key: err.key, lockedBy: 'config' }));
+}
+function notSupported(ctx) {
+    return ctx.response.notFound(apiError('capability_unsupported', 'Runtime settings não é suportado nesta instalação (tabela auth_settings ausente).'));
+}
+/** Extrai organizationId do query string. undefined = não foi passado (usa global null). */
+function resolveOrgId(ctx) {
+    const qs = ctx.request.qs();
+    if ('organizationId' in qs) {
+        const v = qs['organizationId'];
+        return v && v.trim() ? v.trim() : null;
+    }
+    return null;
+}
+/**
+ * Endpoints JSON de runtime settings do console admin React.
+ *
+ * GET    {prefix}/api/settings                       → lista settings globais
+ * GET    {prefix}/api/settings?organizationId={id}   → lista settings da org
+ * PUT    {prefix}/api/settings/:key                  → upsert de setting global
+ * PUT    {prefix}/api/settings/:key?organizationId=  → upsert de setting org-scoped
+ * DELETE {prefix}/api/settings/:key                  → remover setting global
+ * DELETE {prefix}/api/settings/:key?organizationId=  → remover setting org-scoped
+ *
+ * 404 honesto (`capability_unsupported`) quando a tabela auth_settings está ausente.
+ *
+ * Keys org-scopáveis: `organizations_policy`, `roles_catalog`.
+ */
+export default class ConsoleSettingsController {
+    /** GET {prefix}/api/settings */
+    async index(ctx) {
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        const orgId = resolveOrgId(ctx);
+        const rows = await svc.listSettings(orgId);
+        return { data: rows.map(settingDto), locked: lockedSettingKeys() };
+    }
+    /** PUT {prefix}/api/settings/:key — body: { value: any } */
+    async upsert(ctx) {
+        const key = ctx.request.param('key');
+        const body = ctx.request.body();
+        if (!body || !('value' in body)) {
+            return ctx.response.badRequest(apiError('invalid_request', 'O campo `value` é obrigatório.'));
+        }
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        if (isSettingLocked(key))
+            return lockedResponse(ctx, new SettingLockedError(key));
+        const orgId = resolveOrgId(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        try {
+            await svc.setSetting(key, body.value, null, orgId);
+        }
+        catch (err) {
+            if (err instanceof SettingLockedError)
+                return lockedResponse(ctx, err);
+            throw err;
+        }
+        await cfg.audit?.record({
+            type: 'settings.updated',
+            actorId: null,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { key, value: body.value, source: 'admin-console', organizationId: orgId },
+        });
+        const saved = await svc.getSetting(key, orgId);
+        return settingDto({ key, organizationId: orgId, value: saved, updatedAt: new Date(), updatedBy: null });
+    }
+    /** DELETE {prefix}/api/settings/:key */
+    async destroy(ctx) {
+        const key = ctx.request.param('key');
+        const svc = await resolveRuntimeSettings(ctx);
+        if (!svc)
+            return notSupported(ctx);
+        const tablePresent = await svc.isTablePresent();
+        if (!tablePresent)
+            return notSupported(ctx);
+        if (isSettingLocked(key))
+            return lockedResponse(ctx, new SettingLockedError(key));
+        const orgId = resolveOrgId(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        try {
+            await svc.deleteSetting(key, orgId);
+        }
+        catch (err) {
+            if (err instanceof SettingLockedError)
+                return lockedResponse(ctx, err);
+            throw err;
+        }
+        await cfg.audit?.record({
+            type: 'settings.updated',
+            actorId: null,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { key, action: 'deleted', source: 'admin-console', organizationId: orgId },
+        });
+        return { key, organizationId: orgId, deleted: true };
+    }
+}

package/build/src/host/admin_console/console_users_controller.d.ts

@@ -0,0 +1,110 @@
+import "../augmentations.js";
+import type { HttpContext } from "@adonisjs/core/http";
+/**
+ * Endpoints JSON de usuários do console admin React.
+ *
+ * GET  {prefix}/api/users?search=&page=&perPage=  → lista paginada + roles
+ * GET  {prefix}/api/users/:id                     → detalhe + sessões + identidades + MFA status
+ * POST {prefix}/api/users                         → criar usuário
+ * PATCH {prefix}/api/users/:id/roles              → substituir roles globais
+ * POST {prefix}/api/users/:id/disable             → desabilitar conta
+ * POST {prefix}/api/users/:id/enable              → reabilitar conta
+ * POST {prefix}/api/users/:id/reset-password      → emitir token de reset + enviar e-mail
+ * DELETE {prefix}/api/users/:id                   → deleção completa (cascade)
+ *
+ * Todos os mutating endpoints retornam 403 sem sessão/role (adminGuard upstream).
+ * CSRF: o `adminGuard` não aplica CSRF por si só — o shield do AdonisJS protege
+ * automaticamente POST/PATCH/DELETE; o shell injeta `csrfToken` na SPA.
+ */
+export default class ConsoleUsersController {
+    #private;
+    /** GET {prefix}/api/users */
+    index(ctx: HttpContext): Promise<{
+        data: any[];
+        total: any;
+        page: number;
+        perPage: number;
+    }>;
+    /** GET {prefix}/api/users/:id */
+    show(ctx: HttpContext): Promise<void | {
+        sessionsSupported: boolean;
+        sessions: {
+            id: string;
+            accountId: string;
+            email: string | null;
+            loginTs: number | null;
+            amr: string[];
+            userAgent: string | null;
+            browser: string | null;
+            os: string | null;
+            ip: string | null;
+            location: string | null;
+        }[];
+        grants: {
+            id: string;
+            accountId: string;
+            clientId: string | null;
+            accessTokens: number;
+            refreshTokens: number;
+        }[];
+        statusSupported: boolean;
+        deletionSupported: boolean;
+        catalogRoles: {
+            name: string;
+            description?: string;
+        }[];
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST {prefix}/api/users */
+    store(ctx: HttpContext): Promise<void | {
+        invited: boolean;
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** PATCH {prefix}/api/users/:id/roles */
+    updateRoles(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST {prefix}/api/users/:id/disable */
+    disable(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST {prefix}/api/users/:id/enable */
+    enable(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST {prefix}/api/users/:id/reset-password */
+    resetPassword(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        email: string;
+    }>;
+    /** DELETE {prefix}/api/users/:id */
+    destroy(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        deleted: string;
+    }>;
+}

package/build/src/host/admin_console/console_users_controller.js

@@ -0,0 +1,212 @@
+import "../augmentations.js";
+import { AdminUsersService } from "../admin_api/admin_users_service.js";
+import { AdminSessionsService } from "../admin_sessions_service.js";
+import { enrichSessionsWithContext } from "../session_context.js";
+import { resolveRuntimeSettings } from "../runtime_settings.js";
+import { resolveEffectiveRolesCatalog } from "../runtime_toggles.js";
+import { userDto, sessionDto, grantDto, apiError } from "../admin_api/dto.js";
+import { ACCOUNT_SESSION_KEY } from "../middleware/account_auth.js";
+import { supportsAccountDeletion, supportsAccountStatus, } from "../../accounts/account_store.js";
+import { adminUserCreateValidator, adminUserRolesValidator, } from "../admin_validators.js";
+const PAGE_SIZE = 20;
+/**
+ * Endpoints JSON de usuários do console admin React.
+ *
+ * GET  {prefix}/api/users?search=&page=&perPage=  → lista paginada + roles
+ * GET  {prefix}/api/users/:id                     → detalhe + sessões + identidades + MFA status
+ * POST {prefix}/api/users                         → criar usuário
+ * PATCH {prefix}/api/users/:id/roles              → substituir roles globais
+ * POST {prefix}/api/users/:id/disable             → desabilitar conta
+ * POST {prefix}/api/users/:id/enable              → reabilitar conta
+ * POST {prefix}/api/users/:id/reset-password      → emitir token de reset + enviar e-mail
+ * DELETE {prefix}/api/users/:id                   → deleção completa (cascade)
+ *
+ * Todos os mutating endpoints retornam 403 sem sessão/role (adminGuard upstream).
+ * CSRF: o `adminGuard` não aplica CSRF por si só — o shield do AdonisJS protege
+ * automaticamente POST/PATCH/DELETE; o shell injeta `csrfToken` na SPA.
+ */
+export default class ConsoleUsersController {
+    /** GET {prefix}/api/users */
+    async index(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const search = ctx.request.input("search", "").trim();
+        const page = Math.max(1, Number.parseInt(ctx.request.input("page", "1"), 10) || 1);
+        const perPage = Math.max(1, Math.min(100, Number.parseInt(ctx.request.input("perPage", String(PAGE_SIZE)), 10) ||
+            PAGE_SIZE));
+        const result = await cfg.accountStore.listAccounts({
+            search,
+            page,
+            limit: perPage,
+        });
+        const users = new AdminUsersService(cfg);
+        const data = await Promise.all(result.data.map(async (u) => userDto(u, await users.isDisabled(u.id))));
+        return { data, total: result.total, page, perPage };
+    }
+    /** GET {prefix}/api/users/:id */
+    async show(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const id = ctx.request.param("id");
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        const users = new AdminUsersService(cfg);
+        const disabled = await users.isDisabled(id);
+        // Sessões ativas (degradam quando adapter não enumera).
+        const sessions = new AdminSessionsService(service);
+        const rawSessions = sessions.canList ? await sessions.listSessions(id) : [];
+        const enriched = await enrichSessionsWithContext(cfg, id, rawSessions);
+        const grants = sessions.canList ? await sessions.listGrants(id) : [];
+        // Catálogo de roles (fail-safe).
+        let catalogRoles = [];
+        try {
+            const rs = await resolveRuntimeSettings(ctx);
+            if (rs) {
+                const catalog = await resolveEffectiveRolesCatalog(rs);
+                catalogRoles = catalog.roles;
+            }
+        }
+        catch {
+            // fail-safe
+        }
+        return {
+            ...userDto(account, disabled),
+            sessionsSupported: sessions.canList,
+            sessions: enriched.map(sessionDto),
+            grants: grants.map(grantDto),
+            statusSupported: supportsAccountStatus(cfg.accountStore),
+            deletionSupported: supportsAccountDeletion(cfg.accountStore),
+            catalogRoles,
+        };
+    }
+    /** POST {prefix}/api/users */
+    async store(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
+        const ip = ctx.request.ip?.() ?? null;
+        const { email, name, password, invite } = await ctx.request.validateUsing(adminUserCreateValidator);
+        const users = new AdminUsersService(cfg);
+        const result = await users.create(ctx, {
+            email,
+            name: name ?? null,
+            password: password ?? null,
+            invite: invite ?? false,
+        }, { actorId, ip, source: "admin" });
+        if (!result.ok) {
+            if (result.reason === "password_policy") {
+                return ctx.response.badRequest(apiError("password_policy", cfg.messages[result.messageKey] ?? result.messageKey));
+            }
+            return ctx.response.conflict(apiError("email_taken", "Já existe uma conta com este e-mail."));
+        }
+        ctx.response.status(201);
+        return { ...userDto(result.account), invited: result.invited };
+    }
+    /** PATCH {prefix}/api/users/:id/roles */
+    async updateRoles(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const id = ctx.request.param("id");
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
+        const { roles: rolesInput } = await ctx.request.validateUsing(adminUserRolesValidator);
+        const roles = Array.from(new Set((rolesInput ?? []).map((r) => r.trim()).filter(Boolean)));
+        const users = new AdminUsersService(cfg);
+        // Proteções de escalonamento/lockout: último admin + auto-rebaixamento.
+        const guard = await users.guardGlobalRolesChange(id, roles, actorId);
+        if (guard === "last_admin") {
+            return ctx.response
+                .status(409)
+                .send(apiError("last_admin", "Não é possível remover a última conta com a role de administrador."));
+        }
+        if (guard === "cannot_self_demote") {
+            return ctx.response
+                .status(409)
+                .send(apiError("cannot_self_demote", "Você não pode remover a sua própria role de administrador."));
+        }
+        // Resolve RuntimeSettings para validação contra catálogo (fail-safe).
+        const runtimeSettings = await resolveRuntimeSettings(ctx);
+        const errorKey = await users.setGlobalRolesValidated(id, roles, runtimeSettings);
+        if (errorKey) {
+            return ctx.response.badRequest(apiError("invalid_role", cfg.messages[errorKey] ?? errorKey));
+        }
+        const updated = await cfg.accountStore.findById(id);
+        const disabled = await users.isDisabled(id);
+        return userDto(updated, disabled);
+    }
+    /** POST {prefix}/api/users/:id/disable */
+    async disable(ctx) {
+        return this.#setStatus(ctx, true);
+    }
+    /** POST {prefix}/api/users/:id/enable */
+    async enable(ctx) {
+        return this.#setStatus(ctx, false);
+    }
+    async #setStatus(ctx, disable) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
+        const ip = ctx.request.ip?.() ?? null;
+        const id = ctx.request.param("id");
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        const users = new AdminUsersService(cfg);
+        const applied = await users.setStatus(id, disable, {
+            actorId,
+            ip,
+            source: "admin",
+        });
+        if (!applied) {
+            return ctx.response
+                .status(409)
+                .send(apiError("capability_unsupported", "O store não suporta habilitar/desabilitar contas."));
+        }
+        const updated = await cfg.accountStore.findById(id);
+        const disabled = await users.isDisabled(id);
+        return userDto(updated, disabled);
+    }
+    /** POST {prefix}/api/users/:id/reset-password */
+    async resetPassword(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
+        const ip = ctx.request.ip?.() ?? null;
+        const id = ctx.request.param("id");
+        const users = new AdminUsersService(cfg);
+        const account = await users.resetPassword(ctx, id, {
+            actorId,
+            ip,
+            source: "admin",
+        });
+        if (!account)
+            return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+        return { ok: true, email: account.email };
+    }
+    /** DELETE {prefix}/api/users/:id */
+    async destroy(ctx) {
+        const service = await ctx.containerResolver.make("authkit.server");
+        const cfg = service.config;
+        const actorId = ctx.session?.get(ACCOUNT_SESSION_KEY) ?? null;
+        const ip = ctx.request.ip?.() ?? null;
+        const id = ctx.request.param("id");
+        const users = new AdminUsersService(cfg);
+        // OPT-IN durável: passa o enqueue (cascade async); senão delete() roda síncrono.
+        const enqueue = cfg.accountLifecycle?.durable
+            ? (await import("../durable/index.js")).enqueueDeletionVia(ctx.containerResolver)
+            : undefined;
+        const outcome = await users.delete(service, id, { actorId, ip, source: "admin" }, enqueue);
+        if (!outcome.ok) {
+            if (outcome.reason === "not_found") {
+                return ctx.response.notFound(apiError("not_found", "Usuário não encontrado."));
+            }
+            return ctx.response
+                .status(409)
+                .send(apiError("capability_unsupported", "O store não suporta deleção de contas."));
+        }
+        return { ok: true, deleted: id };
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Prefixo do console admin e da Admin REST API — singletons de processo.
+ *
+ * Definidos em tempo de registro das rotas (`registerAuthHost`) e lidos em
+ * runtime pelos controllers e pelo `adminGuard`. Garantia de normalização:
+ * começa com '/', sem trailing slash, defaults '/admin' e '/api/authkit/v1'.
+ *
+ * Por que módulos singleton e não bindings do container?
+ * O container do AdonisJS só está disponível no ciclo de vida de uma request;
+ * os prefixos precisam estar disponíveis ANTES da primeira request (ex.: na
+ * closure do `adminGuard`, que é construída em tempo de registro) e DENTRO de
+ * cada request. Um módulo ESM é inicializado uma vez por processo — perfeito
+ * para configuração imutável definida no boot.
+ */
+/**
+ * Normaliza o prefixo: começa com '/', sem trailing slash.
+ * `'/'` → `''` (raiz) é improvável mas seguro.
+ */
+export declare function normalizeAdminPrefix(raw: string): string;
+/**
+ * Define o prefixo do console admin para este processo.
+ * Chamado UMA VEZ por `registerAuthHost` no boot da aplicação.
+ *
+ * @param prefix  Caminho base do console (ex.: `'/admin'`, `'/auth/admin'`).
+ *                Normalizado automaticamente.
+ */
+export declare function setAdminPrefix(prefix: string): void;
+/**
+ * Retorna o prefixo do console admin (default `'/admin'`).
+ * Usado pelos controllers e pelo `adminGuard` para construir redirects/links.
+ */
+export declare function getAdminPrefix(): string;
+/**
+ * Normaliza o prefixo da Admin REST API: começa com '/', sem trailing slash.
+ * Mesma semântica de `normalizeAdminPrefix`.
+ */
+export declare function normalizeAdminApiPrefix(raw: string): string;
+/**
+ * Define o prefixo da Admin REST API para este processo.
+ * Chamado UMA VEZ por `registerAuthHost` no boot da aplicação.
+ *
+ * @param prefix  Caminho base da API (ex.: `'/api/authkit/v1'`, `'/authkit/api'`).
+ *                Normalizado automaticamente.
+ */
+export declare function setAdminApiPrefix(prefix: string): void;
+/**
+ * Retorna o prefixo da Admin REST API (default `'/api/authkit/v1'`).
+ * Usado pelo `adminApiGuard` e pelo SDK remoto para construir as URLs.
+ */
+export declare function getAdminApiPrefix(): string;

package/build/src/host/admin_prefix.js

@@ -0,0 +1,77 @@
+/**
+ * Prefixo do console admin e da Admin REST API — singletons de processo.
+ *
+ * Definidos em tempo de registro das rotas (`registerAuthHost`) e lidos em
+ * runtime pelos controllers e pelo `adminGuard`. Garantia de normalização:
+ * começa com '/', sem trailing slash, defaults '/admin' e '/api/authkit/v1'.
+ *
+ * Por que módulos singleton e não bindings do container?
+ * O container do AdonisJS só está disponível no ciclo de vida de uma request;
+ * os prefixos precisam estar disponíveis ANTES da primeira request (ex.: na
+ * closure do `adminGuard`, que é construída em tempo de registro) e DENTRO de
+ * cada request. Um módulo ESM é inicializado uma vez por processo — perfeito
+ * para configuração imutável definida no boot.
+ */
+// ─── Console admin ───────────────────────────────────────────────────────────
+const DEFAULT_ADMIN_PREFIX = '/admin';
+let _prefix = DEFAULT_ADMIN_PREFIX;
+/**
+ * Normaliza o prefixo: começa com '/', sem trailing slash.
+ * `'/'` → `''` (raiz) é improvável mas seguro.
+ */
+export function normalizeAdminPrefix(raw) {
+    let p = raw.trim();
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    p = p.replace(/\/+$/, '');
+    return p || '/';
+}
+/**
+ * Define o prefixo do console admin para este processo.
+ * Chamado UMA VEZ por `registerAuthHost` no boot da aplicação.
+ *
+ * @param prefix  Caminho base do console (ex.: `'/admin'`, `'/auth/admin'`).
+ *                Normalizado automaticamente.
+ */
+export function setAdminPrefix(prefix) {
+    _prefix = normalizeAdminPrefix(prefix);
+}
+/**
+ * Retorna o prefixo do console admin (default `'/admin'`).
+ * Usado pelos controllers e pelo `adminGuard` para construir redirects/links.
+ */
+export function getAdminPrefix() {
+    return _prefix;
+}
+// ─── Admin REST API ───────────────────────────────────────────────────────────
+const DEFAULT_ADMIN_API_PREFIX = '/api/authkit/v1';
+let _apiPrefix = DEFAULT_ADMIN_API_PREFIX;
+/**
+ * Normaliza o prefixo da Admin REST API: começa com '/', sem trailing slash.
+ * Mesma semântica de `normalizeAdminPrefix`.
+ */
+export function normalizeAdminApiPrefix(raw) {
+    let p = raw.trim();
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    p = p.replace(/\/+$/, '');
+    return p || '/';
+}
+/**
+ * Define o prefixo da Admin REST API para este processo.
+ * Chamado UMA VEZ por `registerAuthHost` no boot da aplicação.
+ *
+ * @param prefix  Caminho base da API (ex.: `'/api/authkit/v1'`, `'/authkit/api'`).
+ *                Normalizado automaticamente.
+ */
+export function setAdminApiPrefix(prefix) {
+    _apiPrefix = normalizeAdminApiPrefix(prefix);
+}
+/**
+ * Retorna o prefixo da Admin REST API (default `'/api/authkit/v1'`).
+ * Usado pelo `adminApiGuard` e pelo SDK remoto para construir as URLs.
+ */
+export function getAdminApiPrefix() {
+    return _apiPrefix;
+}
+// ─── Admin UI mode ────────────────────────────────────────────────────────────