@adonis-agora/authkit-server 1.0.0-rc.1 → 1.0.0-rc.10

package/build/src/agents/runtime.js

@@ -1,13 +1,9 @@
+import { getBootedApp } from '../../services/booted_app.js';
 import { supportsAccountStatus } from '../accounts/account_store.js';
 import { findMcpResource } from '../mcp/mcp_oauth.js';
 import { PersonalAgentVerifier } from './agent_identity.js';
 import { PersonalAgentDelegation } from './delegation_service.js';
 import { DelegationStore } from './delegation_store.js';
-import { PoppyClientRegistry } from './poppy/client_registry.js';
-import { hmacNonceSource } from './poppy/dpop.js';
-import { databaseReplayStore, memoryLimiter, memoryReplayStore, redisReplayStore, } from './poppy/replay.js';
-import { PoppyService, poppyUrls } from './poppy/service.js';
-import { PoppyStore } from './poppy/store.js';
 import { AgentRegistryStore } from './registry_store.js';
 import { keystoreSigner } from './signer.js';
 /**
@@ -27,9 +23,10 @@ export function personalAgentUrls(oidcIssuer, prefix) {
     };
 }
 const runtimes = new WeakMap();
-/** Ponte Poppy → oidc-provider: Bearer de MCP de Sessions logadas viram access tokens dele. */
-function mcpBridge(service, poppyApis) {
+/** Access tokens do oidc-provider para resources MCP (ver {@link PersonalAgentAccessTokens}). */
+function accessTokens(service) {
     return {
+        mcpEnabled: !!service.config.mcp?.enabled,
         isMcpResource(url) {
             try {
                 return findMcpResource(url, service.config.issuer, service.config.mcp) !== null;
@@ -42,11 +39,6 @@ function mcpBridge(service, poppyApis) {
             const provider = service.provider;
             if (!provider?.AccessToken || !provider?.Grant)
                 return null;
-            // Só faz sentido quando a integração MCP do authkit está ligada, ou o MCP é de `apis`.
-            if (!service.config.mcp?.enabled &&
-                !poppyApis.some((a) => a.type === 'mcp' && a.url.replace(/\/+$/, '') === input.resource.replace(/\/+$/, ''))) {
-                return null;
-            }
             const remaining = Math.max(60, Math.floor((input.grantExpiresAt.getTime() - Date.now()) / 1000));
             let grant = await provider.Grant.find(input.grantId);
             if (!grant) {
@@ -63,13 +55,13 @@ function mcpBridge(service, poppyApis) {
                 clientId: input.clientId,
                 grantId: input.grantId,
                 scope: input.scope,
-                gty: 'poppy',
+                gty: input.grantType,
                 expiresIn: input.expiresIn,
             });
             at.aud = input.resource;
             return at.save();
         },
-        async revoke(grantId) {
+        async revokeGrant(grantId) {
             const provider = service.provider;
             if (!provider?.Grant)
                 return;
@@ -80,18 +72,32 @@ function mcpBridge(service, poppyApis) {
         },
     };
 }
-async function resolveReplay(replay, conn, make) {
-    if (replay === 'memory')
-        return memoryReplayStore();
-    if (replay === 'database')
-        return databaseReplayStore(conn);
-    if (typeof replay.claim === 'function')
-        return replay;
-    const name = replay.redis;
-    if (!make)
-        throw new Error('authkit: personalAgents.poppy.replay { redis } exige o container.');
-    const redis = await make('redis');
-    return redisReplayStore(redis.connection(name));
+/** O ledger de grants visto por uma extension: só os ids com o prefixo dela. */
+function scopedLedger(store, prefix) {
+    const mine = (id) => typeof id === 'string' && id.startsWith(prefix);
+    return {
+        async insertGrant(grant) {
+            if (!mine(grant.id)) {
+                throw new Error(`authkit: grant "${grant.id}" fora do prefixo "${prefix}" da extension.`);
+            }
+            await store.insertGrant(grant);
+        },
+        async findGrant(id) {
+            return mine(id) ? store.findGrant(id) : null;
+        },
+        async listGrants(accountId) {
+            return (await store.listGrants(accountId)).filter((g) => mine(g.id));
+        },
+        async unrevokedGrantIdsOfClient(clientId) {
+            return (await store.unrevokedGrantIdsOfClient(clientId)).filter(mine);
+        },
+        async revokeGrantById(id, at) {
+            if (mine(id))
+                await store.revokeGrantById(id, at);
+        },
+        insertRefreshToken: (token) => store.insertRefreshToken(token),
+        findRefreshToken: (tokenHash) => store.findRefreshToken(tokenHash),
+    };
 }
 /**
  * Config com o registro do console por cima: um agente BLOQUEADO no console é
@@ -112,21 +118,7 @@ function withRegistry(config, registry) {
         }
         return null;
     };
-    const poppy = config.poppy;
-    return {
-        ...config,
-        resolveAgent,
-        poppy: poppy && {
-            ...poppy,
-            clients: {
-                ...poppy.clients,
-                isBlocked: async (id) => (await poppy.clients.isBlocked(id)) ||
-                    (await registry.find('poppy', id))?.status === 'blocked',
-                isRegistered: async (id) => (await poppy.clients.isRegistered(id)) ||
-                    (await registry.find('poppy', id))?.status === 'allowed',
-            },
-        },
-    };
+    return { ...config, resolveAgent };
 }
 /**
  * Monta (uma vez por `OidcService`) o runtime de personal agents. `null` quando
@@ -149,7 +141,7 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
             };
             let conn = null;
             const connection = service.config.schema.connection;
-            if (config.delegation || config.poppy) {
+            if (config.delegation || (config.extensions ?? []).length > 0) {
                 const db = await makeDb();
                 conn = () => (connection ? db.connection(connection) : db.connection());
             }
@@ -177,39 +169,53 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                     isAccountActive,
                 });
             }
-            let poppy = null;
-            if (effective.poppy && store && conn) {
-                const cfg = effective.poppy;
-                const limiter = cfg.rateLimit === false
-                    ? null
-                    : typeof cfg.rateLimit === 'function'
-                        ? cfg.rateLimit
-                        : memoryLimiter(cfg.rateLimit);
-                const secret = service.deriveSecret('poppy-dpop-nonce');
-                poppy = new PoppyService({
-                    cfg,
-                    urls: poppyUrls(service.config.issuer, cfg.prefix),
-                    store: new PoppyStore(conn),
-                    grants: store,
-                    registry: new PoppyClientRegistry(cfg, { fetchJson: options.fetchJson }),
-                    replay: await resolveReplay(cfg.replay, conn, options.make),
-                    limiter,
-                    nonces: hmacNonceSource(secret),
-                    isAccountActive,
-                    mcp: mcpBridge(service, cfg.apis),
-                    now: options.now,
-                });
+            const extensions = new Map();
+            const now = () => options.now?.() ?? new Date();
+            if (store && conn && registry) {
+                const db = conn;
+                const tokens = accessTokens(service);
+                for (const extension of config.extensions ?? []) {
+                    const runtime = await extension.setup({
+                        protocol: extension.id,
+                        issuer: service.config.issuer,
+                        db: () => db(),
+                        grants: scopedLedger(store, extension.grantIdPrefix),
+                        registryStatus: async (identifier) => (await registry.find(extension.id, identifier))?.status ?? null,
+                        deriveSecret: (label) => service.deriveSecret(label),
+                        isAccountActive,
+                        make: async (binding) => {
+                            if (!options.make) {
+                                throw new Error(`authkit: o binding "${binding}" exige o container do app.`);
+                            }
+                            return options.make(binding);
+                        },
+                        accessTokens: tokens,
+                        now,
+                    });
+                    extensions.set(extension.id, { extension, runtime });
+                }
             }
+            /** A extension dona de um grant, pelo prefixo do id. */
+            const ownerOf = (grantId) => {
+                for (const entry of extensions.values()) {
+                    if (grantId.startsWith(entry.extension.grantIdPrefix))
+                        return entry;
+                }
+                return null;
+            };
+            const isExtensionGrant = (grantId) => (config.extensions ?? []).some((e) => grantId.startsWith(e.grantIdPrefix));
             const revokeAgentGrant = async (accountId, grantId) => {
-                if (grantId.startsWith('pgrant_')) {
-                    return poppy ? poppy.revokeAccountGrant(accountId, grantId) : false;
+                if (isExtensionGrant(grantId)) {
+                    const owner = ownerOf(grantId);
+                    return owner ? owner.runtime.revokeAccountGrant(accountId, grantId) : false;
                 }
                 return delegation ? delegation.revokeGrant(accountId, grantId) : false;
             };
             const revokeAllAgentGrants = async (accountId) => {
                 let count = 0;
-                if (poppy)
-                    count += await poppy.revokeAllAccountGrants(accountId);
+                for (const { runtime } of extensions.values()) {
+                    count += await runtime.revokeAllAccountGrants(accountId);
+                }
                 if (delegation)
                     count += await delegation.revokeAllGrants(accountId);
                 return count;
@@ -222,10 +228,11 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                 // Expirado já não vale: revogar não muda nada (e não vira evento de auditoria).
                 if (!grant || grant.revokedAt || grant.expiresAt <= now)
                     return null;
-                if (grantId.startsWith('pgrant_')) {
-                    if (!poppy)
+                if (isExtensionGrant(grantId)) {
+                    const owner = ownerOf(grantId);
+                    if (!owner)
                         return null;
-                    await poppy.revokeGrant(grantId);
+                    await owner.runtime.revokeGrant(grantId);
                 }
                 else {
                     await store.revokeGrantById(grantId, now);
@@ -235,9 +242,11 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
             const disconnectAgent = async (protocol, identifier) => {
                 if (!store)
                     return 0;
-                if (protocol === 'poppy')
-                    return poppy ? poppy.disconnectClient(identifier) : 0;
-                const ids = (await store.unrevokedGrantIdsOfClient(identifier)).filter((id) => !id.startsWith('pgrant_'));
+                if (protocol !== 'pact') {
+                    const entry = extensions.get(protocol);
+                    return entry ? entry.runtime.disconnectAgent(identifier) : 0;
+                }
+                const ids = (await store.unrevokedGrantIdsOfClient(identifier)).filter((id) => !isExtensionGrant(id));
                 const at = options.now?.() ?? new Date();
                 for (const id of ids)
                     await store.revokeGrantById(id, at);
@@ -248,7 +257,7 @@ export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
                 urls,
                 verifier: new PersonalAgentVerifier(effective),
                 delegation,
-                poppy,
+                extensions,
                 revokeAgentGrant,
                 revokeAllAgentGrants,
                 registry,
@@ -270,3 +279,29 @@ export async function personalAgentsFor(ctx) {
         make: (binding) => ctx.containerResolver.make(binding),
     });
 }
+/**
+ * The runtime an extension's `setup` built (`personalAgents.extensions`), by protocol id. `null`
+ * when the extension is not configured (or there is no database). Takes the request, an explicit
+ * source (tests, scripts) or nothing (the booted app).
+ *
+ * Stable for 1.x — see `extension.ts`.
+ */
+export async function personalAgentExtensionRuntime(id, from) {
+    let runtime;
+    if (from && 'containerResolver' in from) {
+        runtime = await personalAgentsFor(from);
+    }
+    else if (from) {
+        const source = from;
+        runtime = await buildPersonalAgentsRuntime(source.service, () => source.db(), {
+            make: source.make ? (binding) => source.make(binding) : undefined,
+            now: source.now ? () => source.now() : undefined,
+        });
+    }
+    else {
+        const app = getBootedApp();
+        const service = (await app.container.make('authkit.server'));
+        runtime = await buildPersonalAgentsRuntime(service, () => app.container.make('lucid.db'), { make: (binding) => app.container.make(binding) });
+    }
+    return runtime?.extensions.get(id)?.runtime ?? null;
+}

package/build/src/audit/audit_sink.d.ts

@@ -8,7 +8,7 @@
  * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
  * emitido não está aqui.
  */
-export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'mfa.recovery_codes_regenerated', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated', 'agent.delegation_approved', 'agent.delegation_denied', 'agent.grant_revoked', 'agent.grant_revoked_by_admin', 'agent.allowed', 'agent.blocked', 'agent.registry_removed'];
+export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'mfa.recovery_codes_regenerated', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'client.disabled', 'client.enabled', 'service_tenant.token_issued', 'roles_catalog.updated', 'agent.delegation_approved', 'agent.delegation_denied', 'agent.grant_revoked', 'agent.grant_revoked_by_admin', 'agent.allowed', 'agent.blocked', 'agent.registry_removed', 'account.extension.redirect', 'account.extension.action'];
 /** Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP. */
 export type AuditEventType = (typeof AUDIT_EVENT_TYPES)[number];
 /**

package/build/src/audit/audit_sink.js

@@ -107,6 +107,11 @@ export const AUDIT_EVENT_TYPES = [
     'session.revoked',
     'account.signed_out_all',
     'client.secret_regenerated',
+    // A client was disabled (no new tokens) or enabled again.
+    'client.disabled',
+    'client.enabled',
+    // A service tenant got a token (`partition`, `resource`, `jti` in the metadata).
+    'service_tenant.token_issued',
     'roles_catalog.updated',
     // Personal agents (PACT §5): o usuário aprovou/negou a delegação pedida por um
     // agente, ou revogou um grant no console. `clientId` = issuer do agente.
@@ -114,9 +119,13 @@ export const AUDIT_EVENT_TYPES = [
     'agent.delegation_denied',
     'agent.grant_revoked',
     // Console admin: um admin revogou a conexão de um usuário, ou liberou/bloqueou um
-    // agente (PACT pelo `iss`, Poppy pelo `client_id`).
+    // agente (PACT pelo `iss`; uma extension pelo identificador dela).
     'agent.grant_revoked_by_admin',
     'agent.allowed',
     'agent.blocked',
     'agent.registry_removed',
+    // Console de conta: uma action de extension mandou o usuário para fora do app
+    // (`redirectTo.external`), ou uma action sensível (sudo/danger) rodou.
+    'account.extension.redirect',
+    'account.extension.action',
 ];

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;
+}