@adonis-agora/authkit-server 1.0.0-rc.7 → 1.0.0-rc.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.8
+
+### Minor Changes
+
+- [#467](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/467) [`65dea93`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/65dea936568e24a450f64834cae8d1e5885dde57) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Admin console: switch between the `@adonis-agora` consoles. The admin console registers itself in the shared `agora.consoles` registry (title "Identity"); the sidebar brand becomes a menu of the other consoles the viewer may open, the Overview page shows them as a "Consoles" grid, and Ctrl/Cmd-K searches users and organizations plus every other console the viewer may open. New routes `GET {prefix}/api/consoles` and `GET {prefix}/api/consoles/search?q=`. `registerAgoraConsole` is exported for consoles you mount yourself, and `isAgoraProbe(ctx)` tells an auditing `authorize` that another console is only checking access (the structural `ctx.agoraProbe` marker). Nothing to configure.
+
 ## 1.0.0-rc.7
 
 ### Minor Changes

package/build/index.d.ts

@@ -25,6 +25,8 @@ export type { AuditEvent, AuditEventType, AuditPage, AuditSink, ListAuditParams,
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export type { ConsoleAuthorize, ConsoleAuthorizeResult, ConsoleAuthorizer, ConsoleAuthorizerClass, } from './src/console_authorize.js';
 export { authorizeByToken } from './src/console_authorize.js';
+export type { AgoraConsoleDecision, AgoraConsoleEntry, AgoraConsoleIcon, AgoraConsoleRegistry, AgoraConsoleSearchHit, } from './src/console_switcher.js';
+export { AGORA_CONSOLES_BINDING, isAgoraProbe, registerAgoraConsole, } from './src/console_switcher.js';
 export type { AdminApiConfigInput, AdminConfigInput, AuthHostRenderer, AuthMethodsConfigInput, AuthServerConfigInput, AuthSocialConfig, DynamicRegistrationConfigInput, LoginConfigInput, OrganizationsConfigInput, PasswordlessConfigInput, RateLimitBucket, RateLimitConfigInput, RegistrationConfigInput, ResolvedAdminApiConfig, ResolvedAdminConfig, ResolvedAuthMethodsConfig, ResolvedDynamicRegistrationConfig, ResolvedLoginConfig, ResolvedNotificationsConfig, ResolvedOrganizationsConfig, ResolvedPasswordlessConfig, ResolvedRateLimitConfig, ResolvedRegistrationConfig, ResolvedServerConfig, ResolvedWebauthnConfig, WebauthnConfigInput, } from './src/define_config.js';
 export { adapters, defineConfig, resolveAdmin, resolveAdminApi, resolveAuthMethodsConfig, resolveDynamicRegistration, resolveLogin, resolveNotifications, resolveOrganizations, resolvePasswordless, resolveRateLimit, resolveRegistration, resolveWebauthn, toSeconds, } from './src/define_config.js';
 export type { EventsConfigInput, ResolvedEventsConfig } from './src/events/dispatcher.js';

package/build/index.js

@@ -14,6 +14,7 @@ export { pact, pactProtocol } from './src/agents/protocol.js';
 export { personalAgentExtensionRuntime, } from './src/agents/runtime.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export { authorizeByToken } from './src/console_authorize.js';
+export { AGORA_CONSOLES_BINDING, isAgoraProbe, registerAgoraConsole, } from './src/console_switcher.js';
 export { adapters, defineConfig, resolveAdmin, resolveAdminApi, resolveAuthMethodsConfig, resolveDynamicRegistration, resolveLogin, resolveNotifications, resolveOrganizations, resolvePasswordless, resolveRateLimit, resolveRegistration, resolveWebauthn, toSeconds, } from './src/define_config.js';
 export { buildWebhookBody, composeAuditSink, resolveEvents, signWebhookBody, } from './src/events/dispatcher.js';
 export { inProcessAccessTokenVerifier, remoteAccessTokenVerifier, } from './src/host/access_token_verifier.js';

package/build/src/console_switcher.d.ts

@@ -0,0 +1,132 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * The console switcher contract, version 1.
+ *
+ * Every `@adonis-agora` console registers itself into ONE data-only registry bound as a value at
+ * `'agora.consoles'` (created by whichever lib boots first). Each console then shows a switcher to
+ * the other consoles the viewer may open. The types are declared locally in every lib (TypeScript is
+ * structural), so no lib imports another.
+ */
+/** The container binding the registry lives at. */
+export declare const AGORA_CONSOLES_BINDING = "agora.consoles";
+/** Bound as a VALUE under `'agora.consoles'`. Data only, so every lib's copy is identical. */
+export interface AgoraConsoleRegistry {
+    readonly version: 1;
+    readonly entries: AgoraConsoleEntry[];
+}
+export type AgoraConsoleIcon = 'workflow' | 'telescope' | 'media' | 'payments' | 'agent' | 'identity' | 'generic';
+/** The decision a console's gate returns. Never throws. */
+export interface AgoraConsoleDecision {
+    allowed: boolean;
+    reason?: string;
+    redirectTo?: string;
+}
+/** One search hit. `href` is a same-origin absolute path. */
+export interface AgoraConsoleSearchHit {
+    title: string;
+    subtitle?: string;
+    href: string;
+}
+export interface AgoraConsoleEntry {
+    /** `/^[a-z][a-z0-9-]*$/`: `'durable'`, `'telescope'`, `'authkit'`, … */
+    id: string;
+    /** Product title (`'Identity'`). */
+    title: string;
+    /** Package name, shown as secondary text (`'@adonis-agora/authkit-server'`). */
+    package?: string;
+    /** Unknown values render as `'generic'`. */
+    icon: AgoraConsoleIcon;
+    /** Same-origin absolute path of the console shell (`'/admin'`). */
+    path: string;
+    /** Lower first. durable 10, telescope 20, agent 30, payments 40, media 50, authkit 90. */
+    order: number;
+    /**
+     * The console's resolved gate (the one its own routes run). While a switcher runs it for another
+     * console, ``ctx.agoraProbe` is `true` (see `isAgoraProbe`), so an authorizer that writes an audit entry per call can skip.
+     */
+    authorize(ctx: HttpContext): Promise<AgoraConsoleDecision>;
+    /** Global search provider. Only called after `authorize` allowed the viewer. */
+    search?(ctx: HttpContext, query: string, limit: number): Promise<AgoraConsoleSearchHit[]>;
+}
+/** What `GET <console api>/consoles` answers. */
+export interface VisibleConsoles {
+    version: 1;
+    current: string;
+    consoles: Array<{
+        id: string;
+        title: string;
+        package?: string;
+        icon: AgoraConsoleIcon;
+        href: string;
+    }>;
+}
+/** What `GET <console api>/consoles/search?q=` answers. */
+export interface ConsoleSearchResults {
+    version: 1;
+    query: string;
+    groups: Array<{
+        id: string;
+        title: string;
+        icon: AgoraConsoleIcon;
+        hits: AgoraConsoleSearchHit[];
+    }>;
+}
+/** Default time each console's `authorize` (and `search`) gets before it counts as hidden. */
+export declare const CONSOLE_PROBE_TIMEOUT_MS = 300;
+/** Hits returned per console by the global search. */
+export declare const CONSOLE_SEARCH_LIMIT = 5;
+interface ContainerLike {
+    hasBinding(binding: string): boolean;
+    bindValue(binding: string, value: unknown): void;
+    make(binding: string): Promise<unknown>;
+}
+interface AppLike {
+    container: ContainerLike;
+}
+interface LoggerLike {
+    warn(message: string): void;
+    debug?(message: string): void;
+}
+/** A same-origin absolute path: starts with `/`, not `//`, no backslash, no control characters. */
+export declare function isSameOriginPath(value: unknown): value is string;
+/**
+ * Add a console to the shared `'agora.consoles'` registry, creating it when absent. Skips (never
+ * throws) a registry of another version; warns and skips a duplicate id. Throws on an invalid `id`
+ * or `path`: that is a programming error. Apps can call it to register a console they mount by hand.
+ *
+ * ```ts
+ * await registerAgoraConsole(app, { id: 'reports', title: 'Reports', icon: 'generic', path: '/reports',
+ *   order: 100, authorize: async (ctx) => ({ allowed: await isStaff(ctx) }) })
+ * ```
+ */
+export declare function registerAgoraConsole(app: AppLike, entry: AgoraConsoleEntry, logger?: LoggerLike): Promise<boolean>;
+/** The registry, when one is bound and is version 1. */
+export declare function readAgoraConsoles(app: AppLike): Promise<AgoraConsoleRegistry | null>;
+/** How many consoles besides `selfId` are registered (the shell's `switcher.others`). */
+export declare function countOtherConsoles(registry: AgoraConsoleRegistry | null, selfId: string): number;
+/**
+ * Whether a console switcher is running this `authorize` on behalf of another console (it only asks
+ * whether to list it). The marker is `ctx.agoraProbe === true`, set structurally by every
+ * `@adonis-agora` console; an authorizer that audits every call can skip then.
+ */
+export declare function isAgoraProbe(ctx: unknown): boolean;
+/**
+ * The consoles (other than `selfId`) the viewer may open: every `authorize` runs in parallel, each
+ * raced against 300 ms; a timeout, a rejection or anything but `allowed: true` hides the console.
+ */
+export declare function listVisibleConsoles(registry: AgoraConsoleRegistry | null, selfId: string, ctx: HttpContext, options?: {
+    timeoutMs?: number;
+    logger?: LoggerLike;
+}): Promise<VisibleConsoles>;
+/**
+ * Global search across the consoles the viewer may open. The current console (`selfId`, already
+ * authorized by its own route guard) is searched without re-running its gate; the others only after
+ * their `authorize` allowed. Each `search` gets `timeoutMs` and returns at most `limit` hits; a hit
+ * whose `href` is not a same-origin path is dropped.
+ */
+export declare function searchConsoles(registry: AgoraConsoleRegistry | null, selfId: string, ctx: HttpContext, query: string, options?: {
+    timeoutMs?: number;
+    limit?: number;
+    logger?: LoggerLike;
+}): Promise<ConsoleSearchResults>;
+export {};

package/build/src/console_switcher.js

@@ -0,0 +1,206 @@
+/**
+ * The console switcher contract, version 1.
+ *
+ * Every `@adonis-agora` console registers itself into ONE data-only registry bound as a value at
+ * `'agora.consoles'` (created by whichever lib boots first). Each console then shows a switcher to
+ * the other consoles the viewer may open. The types are declared locally in every lib (TypeScript is
+ * structural), so no lib imports another.
+ */
+/** The container binding the registry lives at. */
+export const AGORA_CONSOLES_BINDING = 'agora.consoles';
+const CONSOLE_ID = /^[a-z][a-z0-9-]*$/;
+const ICONS = [
+    'workflow',
+    'telescope',
+    'media',
+    'payments',
+    'agent',
+    'identity',
+    'generic',
+];
+/** Default time each console's `authorize` (and `search`) gets before it counts as hidden. */
+export const CONSOLE_PROBE_TIMEOUT_MS = 300;
+/** Hits returned per console by the global search. */
+export const CONSOLE_SEARCH_LIMIT = 5;
+/** A same-origin absolute path: starts with `/`, not `//`, no backslash, no control characters. */
+export function isSameOriginPath(value) {
+    return (typeof value === 'string' &&
+        value.startsWith('/') &&
+        !value.startsWith('//') &&
+        !value.includes('\\') &&
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control characters is the point
+        !/[\u0000-\u001f\u007f]/.test(value));
+}
+/**
+ * Add a console to the shared `'agora.consoles'` registry, creating it when absent. Skips (never
+ * throws) a registry of another version; warns and skips a duplicate id. Throws on an invalid `id`
+ * or `path`: that is a programming error. Apps can call it to register a console they mount by hand.
+ *
+ * ```ts
+ * await registerAgoraConsole(app, { id: 'reports', title: 'Reports', icon: 'generic', path: '/reports',
+ *   order: 100, authorize: async (ctx) => ({ allowed: await isStaff(ctx) }) })
+ * ```
+ */
+export async function registerAgoraConsole(app, entry, logger) {
+    if (typeof entry?.id !== 'string' || !CONSOLE_ID.test(entry.id)) {
+        throw new Error(`registerAgoraConsole: console id ${JSON.stringify(entry?.id)} must match /^[a-z][a-z0-9-]*$/`);
+    }
+    if (!isSameOriginPath(entry.path)) {
+        throw new Error(`registerAgoraConsole: console "${entry.id}" path ${JSON.stringify(entry.path)} must be a same-origin absolute path`);
+    }
+    if (typeof entry.authorize !== 'function') {
+        throw new Error(`registerAgoraConsole: console "${entry.id}" needs an authorize(ctx)`);
+    }
+    const container = app.container;
+    if (!container.hasBinding(AGORA_CONSOLES_BINDING)) {
+        container.bindValue(AGORA_CONSOLES_BINDING, { version: 1, entries: [] });
+    }
+    const registry = (await container.make(AGORA_CONSOLES_BINDING));
+    if (registry?.version !== 1 || !Array.isArray(registry.entries))
+        return false;
+    if (registry.entries.some((e) => e.id === entry.id)) {
+        logger?.warn(`[@adonis-agora/authkit-server] console id "${entry.id}" already registered`);
+        return false;
+    }
+    registry.entries.push(entry);
+    return true;
+}
+/** The registry, when one is bound and is version 1. */
+export async function readAgoraConsoles(app) {
+    if (!app.container.hasBinding(AGORA_CONSOLES_BINDING))
+        return null;
+    const registry = (await app.container.make(AGORA_CONSOLES_BINDING));
+    if (registry?.version !== 1 || !Array.isArray(registry.entries))
+        return null;
+    return registry;
+}
+/** How many consoles besides `selfId` are registered (the shell's `switcher.others`). */
+export function countOtherConsoles(registry, selfId) {
+    return registry ? registry.entries.filter((e) => e.id !== selfId).length : 0;
+}
+function sortEntries(entries) {
+    return [...entries].sort((a, b) => a.order - b.order || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+function iconOf(icon) {
+    return ICONS.includes(icon) ? icon : 'generic';
+}
+const TIMED_OUT = Symbol('timed out');
+/** Resolves to `TIMED_OUT` when `promise` takes longer than `ms`, or `undefined` when it rejects. */
+async function race(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(promise),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(TIMED_OUT), ms);
+            }),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Whether a console switcher is running this `authorize` on behalf of another console (it only asks
+ * whether to list it). The marker is `ctx.agoraProbe === true`, set structurally by every
+ * `@adonis-agora` console; an authorizer that audits every call can skip then.
+ */
+export function isAgoraProbe(ctx) {
+    return ctx?.agoraProbe === true;
+}
+/** Runs `fn` with `ctx.agoraProbe = true`, restoring the previous value afterwards. */
+async function probing(ctx, fn) {
+    const holder = ctx;
+    const previous = holder.agoraProbe;
+    holder.agoraProbe = true;
+    try {
+        return await fn();
+    }
+    finally {
+        if (previous === undefined)
+            delete holder.agoraProbe;
+        else
+            holder.agoraProbe = previous;
+    }
+}
+/** Runs every other console's gate in parallel (each raced against `timeoutMs`); keeps the allowed. */
+async function allowedEntries(entries, ctx, timeoutMs, logger) {
+    return probing(ctx, async () => {
+        const decisions = await Promise.all(entries.map(async (entry) => {
+            const decision = await race(() => entry.authorize(ctx), timeoutMs);
+            if (decision === TIMED_OUT || decision === undefined) {
+                logger?.debug?.(`[@adonis-agora/authkit-server] console "${entry.id}" hidden: authorize ${decision === TIMED_OUT ? 'timed out' : 'failed'}`);
+                return false;
+            }
+            return decision?.allowed === true;
+        }));
+        return entries.filter((_, i) => decisions[i]);
+    });
+}
+/**
+ * The consoles (other than `selfId`) the viewer may open: every `authorize` runs in parallel, each
+ * raced against 300 ms; a timeout, a rejection or anything but `allowed: true` hides the console.
+ */
+export async function listVisibleConsoles(registry, selfId, ctx, options = {}) {
+    const others = sortEntries((registry?.entries ?? []).filter((e) => e.id !== selfId));
+    const allowed = await allowedEntries(others, ctx, options.timeoutMs ?? CONSOLE_PROBE_TIMEOUT_MS, options.logger);
+    return {
+        version: 1,
+        current: selfId,
+        consoles: allowed
+            .filter((e) => isSameOriginPath(e.path))
+            .map((e) => ({
+            id: e.id,
+            title: e.title,
+            ...(typeof e.package === 'string' ? { package: e.package } : {}),
+            icon: iconOf(e.icon),
+            href: e.path,
+        })),
+    };
+}
+/**
+ * Global search across the consoles the viewer may open. The current console (`selfId`, already
+ * authorized by its own route guard) is searched without re-running its gate; the others only after
+ * their `authorize` allowed. Each `search` gets `timeoutMs` and returns at most `limit` hits; a hit
+ * whose `href` is not a same-origin path is dropped.
+ */
+export async function searchConsoles(registry, selfId, ctx, query, options = {}) {
+    const q = query.trim().slice(0, 200);
+    const result = { version: 1, query: q, groups: [] };
+    if (q.length === 0 || !registry)
+        return result;
+    const timeoutMs = options.timeoutMs ?? CONSOLE_PROBE_TIMEOUT_MS;
+    const limit = options.limit ?? CONSOLE_SEARCH_LIMIT;
+    const searchable = sortEntries(registry.entries.filter((e) => typeof e.search === 'function'));
+    const self = searchable.filter((e) => e.id === selfId);
+    const others = await allowedEntries(searchable.filter((e) => e.id !== selfId), ctx, timeoutMs, options.logger);
+    const targets = sortEntries([...self, ...others]);
+    // Real searches by the viewer: run without the probe marker.
+    const hits = await Promise.all(targets.map((entry) => race(() => entry.search(ctx, q, limit), timeoutMs)));
+    targets.forEach((entry, i) => {
+        const found = hits[i];
+        if (!Array.isArray(found))
+            return;
+        const safe = found
+            .filter((h) => h && typeof h.title === 'string' && isSameOriginPath(h.href))
+            .slice(0, limit)
+            .map((h) => ({
+            title: h.title,
+            ...(typeof h.subtitle === 'string' ? { subtitle: h.subtitle } : {}),
+            href: h.href,
+        }));
+        if (safe.length > 0) {
+            result.groups.push({
+                id: entry.id,
+                title: entry.title,
+                icon: iconOf(entry.icon),
+                hits: safe,
+            });
+        }
+    });
+    return result;
+}

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

@@ -0,0 +1,14 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import { type AgoraConsoleEntry, type AgoraConsoleRegistry, type AgoraConsoleSearchHit } from '../../console_switcher.js';
+/** The admin console's id in the `'agora.consoles'` registry. */
+export declare const ADMIN_CONSOLE_ID = "authkit";
+/** The `'agora.consoles'` registry, or `null` (none bound, or no booted app). */
+export declare function consoleRegistry(): Promise<AgoraConsoleRegistry | null>;
+/**
+ * Global search of the admin console: users by email (as the account store's `listAccounts`
+ * search matches them), and organizations by name or slug.
+ * Each hit opens the matching drawer in the console.
+ */
+export declare function searchAdminConsole(ctx: HttpContext, adminPrefix: string, query: string, limit: number): Promise<AgoraConsoleSearchHit[]>;
+/** The admin console's registry entry, for the shell mounted at `adminPrefix`. */
+export declare function adminConsoleEntry(adminPrefix: string, authorize: AgoraConsoleEntry['authorize']): AgoraConsoleEntry;

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

@@ -0,0 +1,80 @@
+import { getBootedApp } from '../../../services/booted_app.js';
+import { supportsOrganizations } from '../../accounts/account_store.js';
+import { readAgoraConsoles, } from '../../console_switcher.js';
+/** The admin console's id in the `'agora.consoles'` registry. */
+export const ADMIN_CONSOLE_ID = 'authkit';
+/** The `'agora.consoles'` registry, or `null` (none bound, or no booted app). */
+export async function consoleRegistry() {
+    try {
+        return await readAgoraConsoles(getBootedApp());
+    }
+    catch {
+        return null;
+    }
+}
+const ORG_CACHE_MS = 30_000;
+const orgCache = new WeakMap();
+/** The store's organizations, cached for 30 s per store so a search session does one query. */
+function cachedOrgs(store, load) {
+    const hit = orgCache.get(store);
+    if (hit && Date.now() - hit.at < ORG_CACHE_MS)
+        return hit.rows;
+    const rows = load();
+    orgCache.set(store, { at: Date.now(), rows });
+    rows.catch(() => orgCache.delete(store));
+    return rows;
+}
+/**
+ * Global search of the admin console: users by email (as the account store's `listAccounts`
+ * search matches them), and organizations by name or slug.
+ * Each hit opens the matching drawer in the console.
+ */
+export async function searchAdminConsole(ctx, adminPrefix, query, limit) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const store = service.config.accountStore;
+    const hits = [];
+    const accounts = await store.listAccounts({ search: query, page: 1, size: limit });
+    for (const account of accounts.data.slice(0, limit)) {
+        hits.push({
+            title: account.email,
+            subtitle: account.name ? `User · ${account.name}` : 'User',
+            href: `${adminPrefix}?view=users&user=${encodeURIComponent(account.id)}`,
+        });
+    }
+    // Organizations only from a store that lists them in one query, for queries of 2+ characters,
+    // from a list cached briefly per process: search runs on every (debounced) keystroke.
+    if (hits.length < limit && query.length >= 2 && supportsOrganizations(store)) {
+        const listAll = store
+            .listAllOrgsWithMemberCount;
+        if (typeof listAll === 'function') {
+            const needle = query.toLowerCase();
+            const orgs = await cachedOrgs(store, () => listAll.call(store));
+            for (const org of orgs) {
+                if (hits.length >= limit)
+                    break;
+                if (!org.name.toLowerCase().includes(needle) && !org.slug.toLowerCase().includes(needle)) {
+                    continue;
+                }
+                hits.push({
+                    title: org.name,
+                    subtitle: `Organization · ${org.slug}`,
+                    href: `${adminPrefix}?view=orgs&org=${encodeURIComponent(org.id)}`,
+                });
+            }
+        }
+    }
+    return hits;
+}
+/** The admin console's registry entry, for the shell mounted at `adminPrefix`. */
+export function adminConsoleEntry(adminPrefix, authorize) {
+    return {
+        id: ADMIN_CONSOLE_ID,
+        title: 'Identity',
+        package: '@adonis-agora/authkit-server',
+        icon: 'identity',
+        path: adminPrefix,
+        order: 90,
+        authorize,
+        search: (ctx, query, limit) => searchAdminConsole(ctx, adminPrefix, query, limit),
+    };
+}

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

@@ -1,8 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
+import { countOtherConsoles } from '../../console_switcher.js';
 import { accountPath } from '../account_paths.js';
 import { resolveAccountRoles, rolesManagedExternally } from '../account_roles.js';
 import { getAdminPrefix } from '../admin_prefix.js';
+import { ADMIN_CONSOLE_ID, consoleRegistry } from './admin_console_entry.js';
 // ─── Shell HTML cache ─────────────────────────────────────────────────────────
 /**
  * Points to the Vite-built index.html inside build/host/ui-dist/.
@@ -141,6 +143,9 @@ export default class AdminShellController {
             }
         }
         const adminBase = getAdminPrefix();
+        // Console switcher: only announced when other `@adonis-agora` consoles are registered; the SPA
+        // then asks the endpoint which of them this viewer may open.
+        const others = countOtherConsoles(await consoleRegistry(), ADMIN_CONSOLE_ID);
         const authkitConfig = {
             adminBase,
             csrfToken: ctx.request.csrfToken ?? null,
@@ -152,6 +157,9 @@ export default class AdminShellController {
                 // Confirmação de identidade (sudo) das ações destrutivas.
                 confirm: accountPath('confirm'),
             },
+            ...(others > 0 ? { switcher: { endpoint: `${adminBase}/api/consoles`, others } } : {}),
+            // Global search (Ctrl/Cmd-K) across this console and every other one the viewer may open.
+            search: { endpoint: `${adminBase}/api/consoles/search` },
             features: {
                 // A página de personal agents só aparece com `personalAgents` no config.
                 personalAgents: !!cfg.personalAgents,

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

@@ -0,0 +1,11 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * The console switcher endpoints of the admin console (behind the admin console's own guard).
+ *
+ * GET {prefix}/api/consoles           → the other consoles this viewer may open
+ * GET {prefix}/api/consoles/search?q= → hits from every console this viewer may open
+ */
+export default class ConsoleSwitcherController {
+    index(ctx: HttpContext): Promise<import("../../console_switcher.js").VisibleConsoles>;
+    search(ctx: HttpContext): Promise<import("../../console_switcher.js").ConsoleSearchResults>;
+}

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

@@ -0,0 +1,23 @@
+import { listVisibleConsoles, searchConsoles } from '../../console_switcher.js';
+import { ADMIN_CONSOLE_ID, consoleRegistry } from './admin_console_entry.js';
+/**
+ * The console switcher endpoints of the admin console (behind the admin console's own guard).
+ *
+ * GET {prefix}/api/consoles           → the other consoles this viewer may open
+ * GET {prefix}/api/consoles/search?q= → hits from every console this viewer may open
+ */
+export default class ConsoleSwitcherController {
+    async index(ctx) {
+        const body = await listVisibleConsoles(await consoleRegistry(), ADMIN_CONSOLE_ID, ctx, {
+            logger: ctx.logger,
+        });
+        ctx.response.header('Cache-Control', 'private, no-store');
+        return body;
+    }
+    async search(ctx) {
+        const q = ctx.request.input('q', '');
+        const body = await searchConsoles(await consoleRegistry(), ADMIN_CONSOLE_ID, ctx, typeof q === 'string' ? q : '', { logger: ctx.logger });
+        ctx.response.header('Cache-Control', 'private, no-store');
+        return body;
+    }
+}

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

@@ -25,6 +25,14 @@ export declare function wantsJson(ctx: any): boolean;
  * As roles permitidas são resolvidas em runtime do `authkit.server` (config lazy).
  */
 export declare const adminGuard: (ctx: any, next: () => Promise<void>) => Promise<any>;
+/**
+ * The admin console gate as the console switcher reads it: `{ allowed }`, never a response, never a
+ * throw. Used as the `authorize` of the admin console's `'agora.consoles'` entry.
+ */
+export declare function adminConsoleDecision(ctx: any): Promise<{
+    allowed: boolean;
+    reason?: 'unauthenticated' | 'forbidden';
+}>;
 /**
  * Opções de montagem das rotas do host-kit.
  *