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

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/define_config.d.ts

@@ -1,5 +1,6 @@
 import type { AccessTokenFormat, AccessTokensConfig, JwksConfig, KeystoreStoreConfig, ObservabilityConfig, TtlConfig } from '@adonis-agora/authkit-core';
 import type { HttpContext } from '@adonisjs/core/http';
+import type { AccountConsoleConfig } from './account/runtime.js';
 import type { AccountStore, AuthAccount } from './accounts/account_store.js';
 import { type AdapterFactory, adapters, type OidcAdapterClass } from './adapters/factory.js';
 import { type PersonalAgentsConfigInput, type ResolvedPersonalAgentsConfig } from './agents/config.js';
@@ -22,6 +23,7 @@ import type { WhatsappCodeSenderBinding } from './host/whatsapp_code_sender.js';
 import { type McpOAuthConfigInput, type ResolvedMcpOAuthConfig } from './mcp/mcp_oauth.js';
 import type { PatStore } from './pat/pat_store.js';
 import { type RedirectUriPolicy, type ResolvedRedirectUriPolicy, type ValidateRegistrationHook } from './provider/registration_policy.js';
+import { type ResolvedServiceTenantsConfig, type ServiceTenantsConfigInput } from './service_tenants/config.js';
 export type { AuthAccount };
 export { adapters };
 export type AuthHostRenderer = (ctx: HttpContext, view: string, props: Record<string, unknown>) => unknown;
@@ -112,18 +114,6 @@ export interface MailHooks {
         email: string;
         sudoUrl: string;
     }) => Promise<void>;
-    /**
-     * Código do Mediated Sign-In pronto do Poppy (`poppyEmailCodeSignIn`): um personal
-     * agent quer entrar na conta e a pessoa precisa dar o código a ele. Sem o hook, o
-     * host-kit envia pelo mailer default, com branding e i18n.
-     */
-    onPoppySignInCode?: (data: {
-        email: string;
-        code: string;
-        /** Nome do agente (metadata dele, ou o host do `client_id`). */
-        agentName: string;
-        expiresInMinutes: number;
-    }) => Promise<void>;
     /**
      * Disparado num login bem-sucedido a partir de um IP NOVO para a conta (nenhum
      * `login.success` anterior desse IP no audit sink), quando `notifications.newLoginEmail`
@@ -322,6 +312,11 @@ export interface ResolvedRateLimitConfig {
      * force ANTES do lockout por interaction (contador persistido no slot do código).
      */
     otpLogin: RateLimitBucket;
+    /**
+     * Bucket das actions das páginas de extension do console de conta
+     * (`POST /account/<página>/actions/*`), keyed pela CONTA. Default 30/min.
+     */
+    accountActions?: RateLimitBucket;
     store?: string;
 }
 export declare function resolveRateLimit(input?: RateLimitConfigInput): ResolvedRateLimitConfig;
@@ -1125,6 +1120,19 @@ export interface AuthServerConfigInput {
      * `resources` mapeia resource indicators (RFC 8707) para audiences/scopes/formato/TTL por API.
      */
     accessTokens?: AccessTokensConfig;
+    /**
+     * Service tenants: confidential `client_credentials` clients that act as a partition of
+     * a resource server (e.g. a durable control plane). `resources` lists the resource
+     * indicators (RFC 8707) that issue their JWT access tokens (RFC 9068), each with an
+     * optional `expiresIn` (seconds, default 600), `audience` and `scopes`:
+     *
+     * ```ts
+     * serviceTenants: { resources: { 'urn:agora:durable': { expiresIn: 600 } } }
+     * ```
+     *
+     * Turns on the `client_credentials` grant. Default: off.
+     */
+    serviceTenants?: ServiceTenantsConfigInput;
     /**
      * Login OAuth de clientes MCP (Claude Code, Claude, ChatGPT, VS Code, Cursor): `true` liga o
      * registro dinâmico restrito aos redirects deles, o refresh token desses clientes e os
@@ -1182,7 +1190,10 @@ export interface AuthServerConfigInput {
      *   adiciona colunas novas (aditivo — nunca dropa nem altera tipos).
      * - `autoManage: false`: nada roda no boot; gerencie o schema você mesmo —
      *   de preferência chamando `ensureAuthkitSchema(this.db)` numa migration.
-     * - `connection`: conexão Lucid a usar (default: primária).
+     * - `connection`: a conexão Lucid de TODAS as tabelas do authkit (default:
+     *   primária) — as acima, o `authkit_keystore`, as de extensions e a do
+     *   `adapters.database()`/keystore `lucid` quando eles não declaram a própria.
+     *   A tabela da conta NÃO entra: fica na conexão do model da conta.
      */
     schema?: {
         autoManage?: boolean;
@@ -1249,6 +1260,16 @@ export interface AuthServerConfigInput {
     accountSession?: {
         acceptIdpSession?: boolean;
     };
+    /**
+     * Account console extensions: the pages other packages add to `/account/*`.
+     *
+     * - `subject(account, { activeOrg, tenant })`: who the account is in the app (default
+     *   `{ type: 'User', id: account.id }`); every extension receives it as `ctx.subject`.
+     * - `extensions`: turn off, rename or reorder pages, by extension id
+     *   (`{ payments: { pages: { 'payments.invoices': { segment: 'faturas' } } } }`).
+     * - `loadTimeoutMs`: budget of one page's `load()` (default 5000).
+     */
+    accountConsole?: AccountConsoleConfig;
 }
 export interface ResolvedServerConfig {
     customLoginMethods?: CustomLoginMethods;
@@ -1367,6 +1388,8 @@ export interface ResolvedServerConfig {
     registration: ResolvedRegistrationConfig;
     /** Access Tokens resolvido (RFC 9068; default opaque). */
     accessTokens: ResolvedAccessTokensConfig;
+    /** Service tenants (always present; `enabled: false` when no resource is declared). */
+    serviceTenants: ResolvedServiceTenantsConfig;
     mcp: ResolvedMcpOAuthConfig;
     /** Console admin resolvido (sempre presente; default desligado). */
     admin: ResolvedAdminConfig;
@@ -1409,6 +1432,8 @@ export interface ResolvedServerConfig {
     accountSession: {
         acceptIdpSession: boolean;
     };
+    /** Account console extensions. Ver {@link AuthServerConfigInput.accountConsole}. */
+    accountConsole?: AccountConsoleConfig;
 }
 export declare function toSeconds(value: string | number | undefined, fallback: number): number;
 /**

package/build/src/define_config.js

@@ -6,7 +6,7 @@ import { composeAuditSink, resolveEvents } from './events/dispatcher.js';
 import { resolveBotProtection, } from './host/bot_protection.js';
 import { resolveBranding } from './host/branding.js';
 import { deriveLockedRouteOptions, deriveLockedSettingKeys, } from './host/config_locks.js';
-import { resolveMessages } from './host/i18n.js';
+import { registerExtensionMessages, resolveMessages, } from './host/i18n.js';
 import { resolveOtpLoginConfig, } from './host/otp_login.js';
 import { edgeRenderer } from './host/renderers/edge_renderer.js';
 import { warnUnsatisfiableSudoConfig } from './host/sudo/satisfiability.js';
@@ -17,6 +17,8 @@ import { loadEncryptionService } from './keys/keystore_crypto.js';
 import { KeystoreManager, resolveKeystoreVault } from './keys/keystore_manager.js';
 import { mcpClientRegistration, resolveMcpOAuth, } from './mcp/mcp_oauth.js';
 import { OPEN_REGISTRATION_REDIRECT_POLICY, resolveRedirectUriPolicy, } from './provider/registration_policy.js';
+import { bindTablesLocation } from './schema/tables_location.js';
+import { resolveServiceTenants, } from './service_tenants/config.js';
 export { adapters };
 const RATE_LIMIT_DEFAULTS = {
     login: { points: 10, duration: '1 min' },
@@ -26,6 +28,8 @@ const RATE_LIMIT_DEFAULTS = {
     sudo: { points: 10, duration: '1 min' },
     // Mais apertado que o login — verificação de código adivinhável.
     otpLogin: { points: 5, duration: '1 min' },
+    // Actions das extensions do console de conta, por conta.
+    accountActions: { points: 30, duration: '1 min' },
 };
 export function resolveRateLimit(input) {
     const enabled = input?.enabled ?? true;
@@ -36,6 +40,7 @@ export function resolveRateLimit(input) {
         adminIp: RATE_LIMIT_DEFAULTS.adminIp,
         sudo: RATE_LIMIT_DEFAULTS.sudo,
         otpLogin: RATE_LIMIT_DEFAULTS.otpLogin,
+        accountActions: RATE_LIMIT_DEFAULTS.accountActions,
         store: input?.store,
     };
 }
@@ -280,15 +285,20 @@ export function defineConfig(config) {
         (!Number.isInteger(requiredFactors) || requiredFactors < 2 || requiredFactors > 8)) {
         throw new Error('mfa.requiredFactors must be an integer between 2 and 8');
     }
+    // Toda tabela do AuthKit vive em `schema.connection` — inclusive as que o store da
+    // conta lê (auth_mfa, auth_password_history, organizations), que antes seguiam a
+    // conexão do model da conta.
+    bindTablesLocation(config.accountStore, { connection: config.schema?.connection });
     return configProvider.create(async (app) => {
-        const AdapterClass = await config.adapter.resolver(app);
+        const tablesContext = { connection: config.schema?.connection };
+        const AdapterClass = await config.adapter.resolver(app, tablesContext);
         // `session.adapter` ausente ⇒ mesma classe do default (back-compat: o
         // dispatcher vira identidade e tudo continua no adapter único de hoje).
         const SessionAdapterClass = config.session?.adapter
-            ? await config.session.adapter.resolver(app)
+            ? await config.session.adapter.resolver(app, tablesContext)
             : AdapterClass;
         // `jwks: 'auto'` → resolve env-aware: AUTHKIT_JWKS inline, senão managed em arquivo.
-        const jwksConfig = config.jwks === 'auto'
+        const jwksInput = config.jwks === 'auto'
             ? process.env.AUTHKIT_JWKS
                 ? {
                     source: 'jwks',
@@ -300,6 +310,14 @@ export function defineConfig(config) {
                     store: 'tmp/authkit_jwks.json',
                 }
             : config.jwks;
+        // Keystore no Lucid sem conexão própria fica na conexão das tabelas do authkit.
+        const jwksStore = jwksInput.store;
+        const jwksConfig = jwksStore?.driver === 'lucid' && !jwksStore.connection && config.schema?.connection
+            ? {
+                ...jwksInput,
+                store: { ...jwksStore, connection: config.schema.connection },
+            }
+            : jwksInput;
         if (config.jwks === 'auto' && !process.env.AUTHKIT_JWKS) {
             const warning = jwksAutoFallbackWarning(jwksConfig.store ?? null);
             if (warning) {
@@ -343,7 +361,7 @@ export function defineConfig(config) {
         }
         // Personal agents com delegação assinam tokens e recibos com este keystore,
         // e o PACT só admite ES256/RS256 — falha no boot, não na primeira troca de token.
-        const personalAgents = resolvePersonalAgentsConfig(config.personalAgents);
+        const personalAgents = resolvePersonalAgentsConfig(config.personalAgents, config.issuer);
         if (personalAgents?.delegation)
             assertDelegationSigningKey(jwks);
         // Debaixo do mountPath, a rota curinga do oidc-provider (`${mount}/*`)
@@ -355,11 +373,13 @@ export function defineConfig(config) {
             (personalAgents.prefix === oidcMount || personalAgents.prefix.startsWith(`${oidcMount}/`))) {
             throw new Error(`authkit: personalAgents.prefix "${personalAgents.prefix}" não pode ficar debaixo do mountPath do OIDC ("${oidcMount}").`);
         }
-        const poppyPrefix = personalAgents?.poppy?.prefix;
-        if (poppyPrefix &&
-            oidcMount &&
-            (poppyPrefix === oidcMount || poppyPrefix.startsWith(`${oidcMount}/`))) {
-            throw new Error(`authkit: personalAgents.poppy.prefix "${poppyPrefix}" não pode ficar debaixo do mountPath do OIDC ("${oidcMount}").`);
+        for (const extension of personalAgents?.extensions ?? []) {
+            if (extension.messages)
+                registerExtensionMessages(extension.messages);
+            if (oidcMount &&
+                (extension.prefix === oidcMount || extension.prefix.startsWith(`${oidcMount}/`))) {
+                throw new Error(`authkit: o prefixo "${extension.prefix}" de personalAgents.extensions "${extension.id}" não pode ficar debaixo do mountPath do OIDC ("${oidcMount}").`);
+            }
         }
         // BACKSTOP DE SUDO. Um host cujo `sudo.methods` não tem um único método
         // satisfazível por conta sem senha fica bricado para TODA operação sob
@@ -473,6 +493,7 @@ export function defineConfig(config) {
                 : undefined,
             registration: resolveRegistration(config.registration),
             accessTokens: resolveAccessTokens(config.issuer, config.accessTokens),
+            serviceTenants: resolveServiceTenants(config.serviceTenants, config.accessTokens?.resources),
             mcp: resolveMcpOAuth(config.mcp),
             admin: resolveAdmin(config.admin),
             adminApi: resolveAdminApi(config.adminApi),
@@ -498,6 +519,7 @@ export function defineConfig(config) {
             // Opt-in: ausente = authkit nunca toca `ctx.auth` (comportamento de sempre).
             adonisAuth: config.adonisAuth,
             accountSession: { acceptIdpSession: config.accountSession?.acceptIdpSession !== false },
+            accountConsole: config.accountConsole,
         };
     });
 }

package/build/src/dev_tools/contract.d.ts

@@ -0,0 +1,72 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * The Agora dev-tools registration contract, version 1, declared here STRUCTURALLY.
+ *
+ * `@adonis-agora/agent`'s `mcp_provider` binds a hub at `'agora.devTools'` in its `register()`; every
+ * lib with a console registers its developer tools into it from its own `boot()`, and the agent
+ * serves them all on one MCP endpoint (`/mcp/agora`). authkit never imports the agent: the only
+ * coupling is the binding name and these shapes.
+ */
+/** The container binding the hub lives at. */
+export declare const DEV_TOOLS_BINDING = "agora.devTools";
+/** The hub a lib registers into. */
+export interface DevToolsHub {
+    readonly version: number;
+    register(lib: DevToolsLib): void;
+}
+/** One lib's tools and the gate that decides who may use them. */
+export interface DevToolsLib {
+    lib: string;
+    title: string;
+    authorize(ctx: HttpContext): Promise<DevToolsDecision>;
+    tools: DevTool[];
+}
+/** What `authorize` answers. */
+export type DevToolsDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+    error?: unknown;
+};
+/** One developer tool. */
+export interface DevTool {
+    /** `authkit_<verb>_<noun>`. */
+    name: string;
+    kind: 'read' | 'action';
+    description: string;
+    input: DevToolInputSchema;
+    destructive?: boolean;
+    available?(): boolean | Promise<boolean>;
+    run(input: Record<string, unknown>, call: DevToolCall): Promise<unknown>;
+}
+/** What a tool's `run` receives besides its input. */
+export interface DevToolCall {
+    ctx: HttpContext;
+    caller: {
+        id: string;
+        via: 'token' | 'session' | 'open';
+    };
+    limits: {
+        maxRows: number;
+        maxBytes: number;
+    };
+}
+/** One property of a {@link DevToolInputSchema}. */
+export interface DevToolInputProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    description?: string;
+    enum?: readonly string[];
+    items?: {
+        type: 'string';
+    };
+    minimum?: number;
+    maximum?: number;
+}
+/** An object of scalar / enum / array-of-string properties. */
+export interface DevToolInputSchema {
+    type: 'object';
+    properties: Record<string, DevToolInputProperty>;
+    required?: string[];
+}

package/build/src/dev_tools/contract.js

@@ -0,0 +1,10 @@
+/**
+ * The Agora dev-tools registration contract, version 1, declared here STRUCTURALLY.
+ *
+ * `@adonis-agora/agent`'s `mcp_provider` binds a hub at `'agora.devTools'` in its `register()`; every
+ * lib with a console registers its developer tools into it from its own `boot()`, and the agent
+ * serves them all on one MCP endpoint (`/mcp/agora`). authkit never imports the agent: the only
+ * coupling is the binding name and these shapes.
+ */
+/** The container binding the hub lives at. */
+export const DEV_TOOLS_BINDING = 'agora.devTools';

package/build/src/dev_tools/gate.d.ts

@@ -0,0 +1,17 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { DevToolsDecision } from './contract.js';
+/** Options for {@link authkitDevToolsAuthorize} (tests inject `inProduction`). */
+export interface DevToolsGateOptions {
+    inProduction?: () => boolean;
+}
+/**
+ * The gate of authkit's dev tools on the Agora dev MCP endpoint. Never throws.
+ *
+ * - `admin.enabled: false` → forbidden.
+ * - `admin.authorize` set → its verdict alone decides: when it allows the MCP request, `admin.roles`
+ *   is NOT checked (an MCP client has no console session; `authorize` is the app's explicit rule).
+ * - `admin.authorize` omitted → forbidden in production. Outside production the caller must be
+ *   signed in through authkit (MCP OAuth sign-in, or a personal agent granted `agora:dev`) as an
+ *   active account holding one of `admin.roles`; signed out → unauthenticated.
+ */
+export declare function authkitDevToolsAuthorize(options?: DevToolsGateOptions): (ctx: HttpContext) => Promise<DevToolsDecision>;

package/build/src/dev_tools/gate.js

@@ -0,0 +1,69 @@
+import { supportsAccountStatus } from '../accounts/account_store.js';
+import { resolveAccountRoles } from '../host/account_roles.js';
+import { adminAuthorizeChecker, appInProduction } from '../host/admin_authorize.js';
+function fromConsoleDecision(decision) {
+    if (decision.allowed)
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: decision.status === 401 ? 'unauthenticated' : 'forbidden',
+        ...(decision.redirectTo !== undefined ? { redirectTo: decision.redirectTo } : {}),
+    };
+}
+/** The account signed in on this request through authkit (`ctx.authkit`), or `null`. */
+async function signedInAccountId(ctx) {
+    const authenticator = ctx.authkit;
+    if (typeof authenticator?.getIdentity !== 'function')
+        return null;
+    try {
+        const identity = await authenticator.getIdentity();
+        return typeof identity?.userId === 'string' && identity.userId !== '' ? identity.userId : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The gate of authkit's dev tools on the Agora dev MCP endpoint. Never throws.
+ *
+ * - `admin.enabled: false` → forbidden.
+ * - `admin.authorize` set → its verdict alone decides: when it allows the MCP request, `admin.roles`
+ *   is NOT checked (an MCP client has no console session; `authorize` is the app's explicit rule).
+ * - `admin.authorize` omitted → forbidden in production. Outside production the caller must be
+ *   signed in through authkit (MCP OAuth sign-in, or a personal agent granted `agora:dev`) as an
+ *   active account holding one of `admin.roles`; signed out → unauthenticated.
+ */
+export function authkitDevToolsAuthorize(options = {}) {
+    const inProduction = options.inProduction ?? appInProduction;
+    return async (ctx) => {
+        try {
+            const service = await ctx.containerResolver.make('authkit.server');
+            const cfg = service.config;
+            if (!cfg.admin?.enabled)
+                return { allowed: false, reason: 'forbidden' };
+            if (cfg.admin.authorize) {
+                return fromConsoleDecision(await adminAuthorizeChecker(cfg.admin.authorize)(ctx));
+            }
+            if (inProduction())
+                return { allowed: false, reason: 'forbidden' };
+            const accountId = await signedInAccountId(ctx);
+            if (accountId === null)
+                return { allowed: false, reason: 'unauthenticated' };
+            const account = await cfg.accountStore.findById(accountId);
+            if (!account)
+                return { allowed: false, reason: 'unauthenticated' };
+            const store = cfg.accountStore;
+            if (supportsAccountStatus(store) && (await store.isDisabled(accountId))) {
+                return { allowed: false, reason: 'forbidden' };
+            }
+            const allowedRoles = (cfg.admin.roles ?? []);
+            const roles = await resolveAccountRoles(cfg, account);
+            return roles.some((role) => allowedRoles.includes(role))
+                ? { allowed: true }
+                : { allowed: false, reason: 'forbidden' };
+        }
+        catch (error) {
+            return { allowed: false, reason: 'forbidden', error };
+        }
+    };
+}

package/build/src/dev_tools/register.d.ts

@@ -0,0 +1,11 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Registers authkit's developer tools into the Agora dev MCP hub (`'agora.devTools'`, bound by
+ * `@adonis-agora/agent`'s `mcp_provider`). No-op when the hub is not bound, speaks another contract
+ * version, or the admin console is off. Returns whether it registered.
+ */
+export declare function registerAuthkitDevTools(app: Pick<ApplicationService, 'container'>, config: {
+    admin?: {
+        enabled?: boolean;
+    } | null;
+}): Promise<boolean>;

package/build/src/dev_tools/register.js

@@ -0,0 +1,25 @@
+import { DEV_TOOLS_BINDING } from './contract.js';
+import { authkitDevToolsAuthorize } from './gate.js';
+import { authkitDevTools } from './tools.js';
+/**
+ * Registers authkit's developer tools into the Agora dev MCP hub (`'agora.devTools'`, bound by
+ * `@adonis-agora/agent`'s `mcp_provider`). No-op when the hub is not bound, speaks another contract
+ * version, or the admin console is off. Returns whether it registered.
+ */
+export async function registerAuthkitDevTools(app, config) {
+    if (!config.admin?.enabled)
+        return false;
+    const container = app.container;
+    if (!container.hasBinding(DEV_TOOLS_BINDING))
+        return false;
+    const hub = (await container.make(DEV_TOOLS_BINDING));
+    if (hub?.version !== 1 || typeof hub.register !== 'function')
+        return false;
+    hub.register({
+        lib: 'authkit',
+        title: 'Identity (authkit admin)',
+        authorize: authkitDevToolsAuthorize(),
+        tools: authkitDevTools({ resolve: () => container.make('authkit.server') }),
+    });
+    return true;
+}

package/build/src/dev_tools/tools.d.ts

@@ -0,0 +1,24 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import { AdminClientsService } from '../host/admin_clients_service.js';
+import { AdminSessionsService } from '../host/admin_sessions_service.js';
+import type { DevTool } from './contract.js';
+/** Rows a list tool returns when `limit` is omitted. */
+export declare const DEV_TOOLS_DEFAULT_LIMIT = 20;
+/** The largest `limit` a list tool accepts. */
+export declare const DEV_TOOLS_MAX_LIMIT = 100;
+/** What the tools need from the app; tests replace any of it. */
+export interface AuthkitDevToolsDeps {
+    /** The `authkit.server` service. Default: resolved from the request's container. */
+    service?(ctx: HttpContext): Promise<any>;
+    sessions?(service: any): Pick<AdminSessionsService, 'canList' | 'countActiveSessions' | 'listSessions' | 'listGrants' | 'revokeAll'>;
+    clients?(service: any): Pick<AdminClientsService, 'canList' | 'list' | 'find'>;
+    /** The `authkit.server` service outside a request, for `available()`. */
+    resolve?(): Promise<any>;
+}
+/**
+ * authkit's developer tools for the Agora dev MCP endpoint: the admin console's reads, and two
+ * destructive actions (revoke sessions, disable a user) that the app must opt into on the endpoint.
+ * Every tool goes through the same services as the console; outputs never carry session ids, client
+ * secrets, key material, token values or MFA secrets.
+ */
+export declare function authkitDevTools(deps?: AuthkitDevToolsDeps): DevTool[];