@adonis-agora/authkit-server 1.0.0-rc.4 → 1.0.0-rc.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.6
+
+### Minor Changes
+
+- [#464](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/464) [`3250c35`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/3250c35eee328e8e3780df32001323be45fe1bae) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Developer tools over MCP. When the app runs `@adonis-agora/agent`'s dev tools endpoint (`/mcp/agora`), the admin console's data is served there with no config: `authkit_get_overview`, `authkit_list_users`, `authkit_get_user`, `authkit_list_user_sessions`, `authkit_list_user_grants`, `authkit_list_orgs`, `authkit_get_org`, `authkit_list_clients`, `authkit_list_audit`, and the destructive actions `authkit_revoke_user_sessions` and `authkit_disable_user` (hidden until the endpoint allows actions; audited with `mcp:<caller>` as actor). Access follows `admin.authorize`; when it allows the MCP request, `admin.roles` is not checked. Without `admin.authorize`, production refuses and other environments need an AuthKit sign-in holding one of `admin.roles`.
+  
+  `@adonis-agora/authkit-poppy` offers the `agora:dev` scope when the app serves those dev tools (`devTools` option to force it on or off). The consent screen never ticks it for the person, and Mediated Sign-In can't grant it. The personal-agent consent screen supports opt-in scopes (`optIn`, `descriptionKey` on each scope of `agents/consent`).
+
+## 1.0.0-rc.5
+
+### Minor Changes
+
+- [#463](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/463) [`e9f02d8`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/e9f02d8e6858f9ec8e5cdb2b77409fd0c31cb13d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. authkit registers its checks (every `authkit:doctor` finding under a stable id such as `authkit.issuer`, plus `authkit.signing-key-age`, `authkit.console-gate`, `authkit.peers` and `authkit.agora-siblings`). Flags: `--json`, `--strict`, `--deep`, `--lib`, `--only`, `--verbose`, `--no-boot`; exit `0` / `1` (error, or warning with `--strict`) / `2` (the doctor could not run). New `@adonis-agora/authkit-server/doctor` entry exports the checks for `--no-boot`. `authkit:doctor` is unchanged.
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/build/commands/agora_doctor.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. Exit code `0`
+ * when nothing is an error (`--strict`: nor a warning), `1` otherwise, `2` when the doctor itself
+ * cannot run.
+ */
+export default class AgoraDoctor extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    /** A `<lib>:doctor` alias sets this to pre-filter its lib. */
+    protected presetLib: string | undefined;
+    json: boolean;
+    lib?: string;
+    deep: boolean;
+    only?: string;
+    strict: boolean;
+    verbose: boolean;
+    boot: boolean;
+    run(): Promise<void>;
+}

package/build/commands/agora_doctor.js

@@ -0,0 +1,109 @@
+// agora-doctor command v1 — keep identical across libs
+// Revision 1.1 (see the canonical README for the changelog).
+// Every @adonis-agora lib ships this command (commands/agora_doctor.ts); whichever copy Ace loads
+// last wins, and they all behave the same. Each repo's CI checks its sha256 against the pinned
+// canonical one. Never edit a lib's copy: change the canonical copy, then re-copy it into every lib.
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { AgoraDoctorUsageError, discoverDoctorChecks, readDoctorChecks, renderAgoraDoctor, runAgoraDoctor, } from '../src/doctor/agora_doctor.js';
+/**
+ * `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. Exit code `0`
+ * when nothing is an error (`--strict`: nor a warning), `1` otherwise, `2` when the doctor itself
+ * cannot run.
+ */
+export default class AgoraDoctor extends BaseCommand {
+    static commandName = 'agora:doctor';
+    static description = 'Check the configuration of every installed @adonis-agora lib';
+    // The app is booted by `run()` itself, so `--no-boot` can skip it.
+    static options = { startApp: false };
+    /** A `<lib>:doctor` alias sets this to pre-filter its lib. */
+    presetLib = undefined;
+    async run() {
+        const err = (line) => process.stderr.write(`${line}\n`);
+        try {
+            let checks;
+            if (this.boot === false) {
+                checks = await discoverDoctorChecks(this.app);
+            }
+            else {
+                if (!this.app.isReady) {
+                    try {
+                        await this.app.boot();
+                        await this.app.start(() => { });
+                    }
+                    catch (error) {
+                        const reason = error instanceof Error ? error.message : String(error);
+                        throw new AgoraDoctorUsageError(`the app did not boot (${reason}). Fix the boot error, or run with --no-boot.`);
+                    }
+                }
+                checks = await readDoctorChecks(this.app.container);
+            }
+            const libs = (this.lib ?? this.presetLib)
+                ?.split(',')
+                .map((name) => name.trim())
+                .filter(Boolean);
+            const { report, exitCode } = await runAgoraDoctor(this.app, checks, {
+                ...(libs ? { libs } : {}),
+                ...(this.only ? { only: this.only } : {}),
+                deep: this.deep === true,
+                noBoot: this.boot === false,
+                strict: this.strict === true,
+            });
+            if (this.json) {
+                process.stdout.write(`${JSON.stringify(report)}\n`);
+            }
+            else {
+                const fancy = process.stdout.isTTY === true && !process.env.NO_COLOR;
+                const c = this.colors;
+                process.stdout.write(renderAgoraDoctor(report, {
+                    verbose: this.verbose === true,
+                    fancy,
+                    paint: {
+                        green: (t) => c.green(t),
+                        yellow: (t) => c.yellow(t),
+                        red: (t) => c.red(t),
+                        dim: (t) => c.dim(t),
+                        bold: (t) => c.bold(t),
+                    },
+                }));
+            }
+            this.exitCode = exitCode;
+        }
+        catch (error) {
+            if (!(error instanceof AgoraDoctorUsageError))
+                throw error;
+            err(`agora:doctor: ${error.message}`);
+            this.exitCode = 2;
+        }
+    }
+}
+__decorate([
+    flags.boolean({ description: 'Print one JSON object to stdout' })
+], AgoraDoctor.prototype, "json", void 0);
+__decorate([
+    flags.string({ description: 'Only these libs, comma separated (durable,payments)' })
+], AgoraDoctor.prototype, "lib", void 0);
+__decorate([
+    flags.boolean({ description: 'Also run checks that touch the database, Redis or the network' })
+], AgoraDoctor.prototype, "deep", void 0);
+__decorate([
+    flags.string({ description: 'Run one check by id' })
+], AgoraDoctor.prototype, "only", void 0);
+__decorate([
+    flags.boolean({ description: 'Fail (exit 1) on warnings too' })
+], AgoraDoctor.prototype, "strict", void 0);
+__decorate([
+    flags.boolean({ description: 'Show skipped checks and every message' })
+], AgoraDoctor.prototype, "verbose", void 0);
+__decorate([
+    flags.boolean({
+        description: 'Boot the app first; --no-boot checks the config only (when boot itself fails)',
+        default: true,
+        showNegatedVariantInHelp: true,
+    })
+], AgoraDoctor.prototype, "boot", void 0);

package/build/commands/commands.json

@@ -333,6 +333,70 @@
       "args": [],
       "options": { "startApp": true },
       "filePath": "expire_scan.js"
+    },
+    {
+      "commandName": "agora:doctor",
+      "description": "Check the configuration of every installed @adonis-agora lib",
+      "namespace": "agora",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Print one JSON object to stdout"
+        },
+        {
+          "name": "lib",
+          "flagName": "lib",
+          "required": false,
+          "type": "string",
+          "description": "Only these libs, comma separated (durable,payments)"
+        },
+        {
+          "name": "deep",
+          "flagName": "deep",
+          "required": false,
+          "type": "boolean",
+          "description": "Also run checks that touch the database, Redis or the network"
+        },
+        {
+          "name": "only",
+          "flagName": "only",
+          "required": false,
+          "type": "string",
+          "description": "Run one check by id"
+        },
+        {
+          "name": "strict",
+          "flagName": "strict",
+          "required": false,
+          "type": "boolean",
+          "description": "Fail (exit 1) on warnings too"
+        },
+        {
+          "name": "verbose",
+          "flagName": "verbose",
+          "required": false,
+          "type": "boolean",
+          "description": "Show skipped checks and every message"
+        },
+        {
+          "name": "boot",
+          "flagName": "boot",
+          "required": false,
+          "type": "boolean",
+          "description": "Boot the app first; --no-boot checks the config only (when boot itself fails)",
+          "default": true,
+          "showNegatedVariantInHelp": true
+        }
+      ],
+      "args": [],
+      "options": {
+        "startApp": false
+      },
+      "filePath": "agora_doctor.js"
     }
   ]
 }

package/build/commands/doctor.js

@@ -1,43 +1,6 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 import { BaseCommand } from '@adonisjs/core/ace';
-import { DatabaseAdapter } from '../src/adapters/database_adapter.js';
-import { resolveAuthkitConfig } from '../src/commands/resolve_config.js';
-import { defaultEncryptForStore } from '../src/define_config.js';
-import { hasErrors, runAllChecks, signingKeyAgeFinding, } from '../src/doctor/checks.js';
-import { signingKeyAgeDays } from '../src/keys/keystore.js';
-import { KeystoreCodec } from '../src/keys/keystore_codec.js';
-import { loadEncryptionService } from '../src/keys/keystore_crypto.js';
-import { KeystoreManager, resolveKeystoreVault } from '../src/keys/keystore_manager.js';
-/**
- * Tenta importar um peer; `true` se importável.
- *
- * Distingue "não instalado" de "instalado mas quebrado": só um erro de
- * módulo-não-encontrado (`ERR_MODULE_NOT_FOUND`/`MODULE_NOT_FOUND`) é tratado como
- * peer ausente (silencioso — é o caso esperado). Qualquer outro erro significa que
- * o peer ESTÁ presente mas falhou ao carregar (import circular, erro de sintaxe,
- * config inválida) — isso o doctor precisa gritar, senão um peer quebrado aparece
- * como "ausente" e o diagnóstico mente.
- */
-async function canImport(specifier, logger) {
-    try {
-        await import(__rewriteRelativeImportExtension(specifier));
-        return true;
-    }
-    catch (err) {
-        const code = err?.code;
-        if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND') {
-            logger?.warning(`⚠️  ${specifier} está instalado mas falhou ao carregar: ${err.message}`);
-        }
-        return false;
-    }
-}
+import { hasErrors, runAllChecks } from '../src/doctor/checks.js';
+import { buildDoctorInput, managedSigningKeyAgeFinding } from '../src/doctor/doctor_input.js';
 export default class AuthkitDoctor extends BaseCommand {
     static commandName = 'authkit:doctor';
     static description = 'Valida a configuração do AuthKit no host e imprime achados (✅/⚠️/❌). Sai com código !=0 se houver erros.';
@@ -48,50 +11,21 @@ export default class AuthkitDoctor extends BaseCommand {
     ];
     static options = { startApp: true };
     async run() {
-        const config = await this.app.container.make('config');
-        // `defineConfig` exporta um config provider — resolve antes de inspecionar,
-        // senão todo campo aparece como "ausente" (provider cru não tem issuer etc.).
-        let authkitConfig = null;
+        // `buildDoctorInput` resolve o config provider de `config/authkit.ts` antes de inspecionar.
+        let input;
         try {
-            authkitConfig = await resolveAuthkitConfig(this.app, config.get('authkit', null));
+            input = await buildDoctorInput(this.app, this.logger);
         }
         catch (error) {
             this.logger.logError(`❌ config/authkit.ts falhou ao resolver: ${error.message}`);
             this.exitCode = 1;
             return;
         }
-        const sessionConfig = config.get('session', null) ?? null;
-        const input = {
-            authkitConfig,
-            sessionConfig,
-            peers: {
-                session: await canImport('@adonisjs/session', this.logger),
-                shield: await canImport('@adonisjs/shield', this.logger),
-                ally: await canImport('@adonisjs/ally', this.logger),
-                limiter: await canImport('@adonisjs/limiter', this.logger),
-            },
-            __adapterClasses: { DatabaseAdapter },
-        };
         const findings = runAllChecks(input);
         // Adiciona o finding de idade da chave de assinatura managed (best-effort).
-        const jwksInput = (authkitConfig?.jwksConfig ?? authkitConfig?.jwks);
-        if (jwksInput?.source === 'managed' && jwksInput?.store) {
-            try {
-                const vault = resolveKeystoreVault(jwksInput.store, {
-                    makePath: (p) => this.app.makePath(p),
-                    container: this.app.container,
-                });
-                const encrypt = jwksInput.encrypt ?? defaultEncryptForStore(jwksInput.store);
-                const enc = encrypt ? await loadEncryptionService().catch(() => undefined) : undefined;
-                const mgr = new KeystoreManager(vault, new KeystoreCodec({ encrypt, enc }), jwksInput.algorithm ?? 'RS256');
-                const store = await mgr.read().catch(() => null);
-                const maxAge = jwksInput.rotationDays ?? 90;
-                findings.push(signingKeyAgeFinding(signingKeyAgeDays(store), maxAge));
-            }
-            catch {
-                /* idade é best-effort no doctor */
-            }
-        }
+        const keyAge = await managedSigningKeyAgeFinding(this.app, input.authkitConfig);
+        if (keyAge)
+            findings.push(keyAge);
         this.print(findings);
         if (hasErrors(findings)) {
             this.exitCode = 1;

package/build/host/views/agents/consent.edge

@@ -28,8 +28,17 @@
           <legend class="text-sm font-medium text-gray-900">{{ t('agents.consent.scopes_label') }}</legend>
           @each(scope in request.scopes)
             <label class="flex items-start gap-3 rounded-lg border border-gray-200 p-3">
-              <input type="checkbox" name="scope" value="{{ scope.id }}" checked class="mt-0.5">
-              <span class="text-sm text-gray-800">{{ scope.description }}</span>
+              @if(scope.optIn)
+                <input type="checkbox" name="scope" value="{{ scope.id }}" class="mt-0.5">
+              @else
+                <input type="checkbox" name="scope" value="{{ scope.id }}" checked class="mt-0.5">
+              @end
+              <span class="text-sm text-gray-800">
+                {{ scope.descriptionKey ? t(scope.descriptionKey) : scope.description }}
+                @if(scope.optIn)
+                  <span class="mt-1 block text-xs text-gray-500">{{ t('agents.consent.opt_in_hint') }}</span>
+                @end
+              </span>
             </label>
           @end
         </fieldset>

package/build/host/views/agents/done.edge

@@ -8,7 +8,7 @@
       <h1 class="text-xl font-semibold text-gray-900">{{ t('agents.done.approved_title', { agent: agentName }) }}</h1>
       <ul class="mt-4 space-y-1 text-sm text-gray-700">
         @each(scope in scopes)
-          <li>• {{ scope.description }}</li>
+          <li>• {{ scope.descriptionKey ? t(scope.descriptionKey) : scope.description }}</li>
         @end
       </ul>
       <p class="mt-4 text-sm text-gray-600">{{ t('agents.done.return') }}</p>

package/build/index.d.ts

@@ -117,7 +117,7 @@ export type { RuntimeSettingsOptions, SettingRow, SettingsCapability, } from './
 export { RuntimeSettings, supportsSettings } from './src/host/runtime_settings.js';
 export type { AuthMethodsCapabilities, AuthMethodsConfigOverride, AuthMethodsSetting, MaintenanceModeSetting, RegistrationSetting, RequireVerifiedEmailSetting, ResolvedAuthMethods, ResolvedMaintenanceMode, SettingKey, } from './src/host/runtime_toggles.js';
 export { configLockedAuthMethods, resolveEffectiveAuthMethods, resolveEffectiveMaintenanceMode, resolveEffectiveRegistration, resolveEffectiveRequireVerifiedEmail, SETTING_KEYS, } from './src/host/runtime_toggles.js';
-export type { AccountAppsProps, AccountOrg, AccountOrgsProps, AccountTokensProps, AgentConsentRequest, AgentsConsentProps, AgentsDoneProps, AuthkitScreen, AuthkitScreenProps, AuthkitScreenRenderer, ConsentProps, ConsentRequestParams, ConsentScope, ForgotProps, LoginAccount, LoginProps, MaintenanceProps, MfaChallengeCustomMethod, MfaChallengeProps, OtpUnlockProps, ResetProps, ScreenRenderProps, SessionExpiredProps, SignupProps, ThrottledProps, VerifyEmailProps, } from './src/host/screen_props.js';
+export type { AccountAppsProps, AccountOrg, AccountOrgsProps, AccountTokensProps, AgentConsentRequest, AgentConsentScope, AgentsConsentProps, AgentsDoneProps, AuthkitScreen, AuthkitScreenProps, AuthkitScreenRenderer, ConsentProps, ConsentRequestParams, ConsentScope, ForgotProps, LoginAccount, LoginProps, MaintenanceProps, MfaChallengeCustomMethod, MfaChallengeProps, OtpUnlockProps, ResetProps, ScreenRenderProps, SessionExpiredProps, SignupProps, ThrottledProps, VerifyEmailProps, } from './src/host/screen_props.js';
 export { enrichSessionsWithContext } from './src/host/session_context.js';
 export { sudoMethods } from './src/host/sudo/index.js';
 export { completeSudo, fail as failSudo, LAST_METHOD_SESSION_KEY, sudoContextFrom, } from './src/host/sudo/runtime.js';

package/build/providers/authkit_server_provider.js

@@ -17,6 +17,8 @@ import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { setBootedApp } from '../services/booted_app.js';
 import { defaultEncryptForStore } from '../src/define_config.js';
+import { authkitDoctorChecks } from '../src/doctor/agora_checks.js';
+import { registerDoctorChecks } from '../src/doctor/agora_doctor.js';
 import { resolveAppKey } from '../src/host/app_key.js';
 import { resolveEffectiveKeyRotation } from '../src/host/key_rotation.js';
 import { RuntimeSettings } from '../src/host/runtime_settings.js';
@@ -33,6 +35,9 @@ export default class AuthkitServerProvider {
         this.app = app;
     }
     async boot() {
+        // `node ace agora:doctor` reads these after boot, from the registry every @adonis-agora lib
+        // shares. Registered here rather than in `register()`, which AdonisJS does not await.
+        await registerDoctorChecks(this.app.container, authkitDoctorChecks());
         // EAGER + LOUD (fail-fast): se o host configurou `config/authkit.ts`, a
         // `appKey` é indispensável — o oidc-provider a usa para assinar TODOS os
         // cookies (keygrip). Antes, essa validação só rodava dentro do factory
@@ -154,6 +159,18 @@ export default class AuthkitServerProvider {
             const logger = await this.app.container.make('logger').catch(() => null);
             warnAdminConsoleUnauthorized(logger);
         }
+        // Agora dev tools over MCP: the admin console's tools join the hub `@adonis-agora/agent`
+        // binds at `'agora.devTools'` (no import of the agent; nothing happens without it).
+        if (config.admin.enabled) {
+            const { registerAuthkitDevTools } = await import('../src/dev_tools/register.js');
+            try {
+                await registerAuthkitDevTools(this.app, config);
+            }
+            catch (error) {
+                const logger = await this.app.container.make('logger').catch(() => null);
+                logger?.warn({ err: error }, 'authkit: could not register the Agora dev tools');
+            }
+        }
         // `personalAgents.extensions`: o boot de cada uma (slots globais, etc.).
         for (const extension of config.personalAgents?.extensions ?? []) {
             await extension.boot?.();

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[];