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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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

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

@@ -159,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[];

package/build/src/dev_tools/tools.js

@@ -0,0 +1,384 @@
+import { supportsAccountStatus, supportsMfa, supportsProviderIdentity, } from '../accounts/account_store.js';
+import { AdminOrgsService } from '../host/admin_api/admin_orgs_service.js';
+import { AdminUsersService } from '../host/admin_api/admin_users_service.js';
+import { auditDto, orgDetailDto, orgDto, sessionDto, userDtoWithRoles, } from '../host/admin_api/dto.js';
+import { AdminClientsService } from '../host/admin_clients_service.js';
+import { AdminSessionsService } from '../host/admin_sessions_service.js';
+import { computeAdminStats } from '../host/admin_stats_service.js';
+import { enrichSessionsWithContext } from '../host/session_context.js';
+import { LIST_FIRST_PAGE } from '../pagination.js';
+/** Rows a list tool returns when `limit` is omitted. */
+export const DEV_TOOLS_DEFAULT_LIMIT = 20;
+/** The largest `limit` a list tool accepts. */
+export const DEV_TOOLS_MAX_LIMIT = 100;
+const page = {
+    type: 'integer',
+    minimum: 1,
+    description: 'Page number, 1-based (default 1). The result says the next one in `next`.',
+};
+const limit = {
+    type: 'integer',
+    minimum: 1,
+    maximum: DEV_TOOLS_MAX_LIMIT,
+    description: `Rows per page (default ${DEV_TOOLS_DEFAULT_LIMIT}, max ${DEV_TOOLS_MAX_LIMIT}).`,
+};
+const accountId = { type: 'string', description: 'The account id.' };
+function pageOf(input) {
+    const p = Math.trunc(Number(input.page));
+    const l = Math.trunc(Number(input.limit));
+    return {
+        page: Number.isFinite(p) && p >= LIST_FIRST_PAGE ? p : LIST_FIRST_PAGE,
+        limit: Number.isFinite(l) && l >= 1 ? Math.min(l, DEV_TOOLS_MAX_LIMIT) : DEV_TOOLS_DEFAULT_LIMIT,
+    };
+}
+function nextPage(current, size, total) {
+    return current * size < total ? current + 1 : null;
+}
+/** One page of an array the service returns whole. */
+function slice(rows, p) {
+    const start = (p.page - 1) * p.limit;
+    return {
+        items: rows.slice(start, start + p.limit),
+        total: rows.length,
+        next: nextPage(p.page, p.limit, rows.length),
+    };
+}
+function text(input, key) {
+    const value = input[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function required(input, key) {
+    const value = text(input, key);
+    if (value === undefined)
+        throw new Error(`"${key}" is required`);
+    return value;
+}
+/** A session as the console shows it, without its id (an id is a handle on the session). */
+function sessionView(session) {
+    const { id: _id, ...rest } = sessionDto(session);
+    return rest;
+}
+function grantView(grant) {
+    return {
+        accountId: grant.accountId,
+        clientId: grant.clientId ?? null,
+        accessTokens: grant.accessTokens,
+        refreshTokens: grant.refreshTokens,
+    };
+}
+/** The audit actor of an action taken over MCP. */
+function mcpActor(call) {
+    return `mcp:${call.caller.id}`;
+}
+/**
+ * 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 function authkitDevTools(deps = {}) {
+    const service = (ctx) => deps.service ? deps.service(ctx) : ctx.containerResolver.make('authkit.server');
+    const sessions = (svc) => deps.sessions ? deps.sessions(svc) : new AdminSessionsService(svc);
+    const clients = (svc) => (deps.clients ? deps.clients(svc) : new AdminClientsService(svc));
+    async function findAccount(cfg, id) {
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            throw new Error(`No account with id "${id}"`);
+        return account;
+    }
+    return [
+        {
+            name: 'authkit_get_overview',
+            kind: 'read',
+            description: 'Identity provider summary: total users, active sessions, monthly active users, sign-ins and sign-ups per day (last 30 days), number of OIDC clients, audit total and the 5 latest audit events.',
+            input: { type: 'object', properties: {} },
+            async run(_input, call) {
+                const svc = await service(call.ctx);
+                const cfg = svc.config;
+                const stats = await computeAdminStats(cfg, sessions(svc));
+                const clientSvc = clients(svc);
+                const clientsCount = clientSvc.canList ? (await clientSvc.list()).length : 0;
+                const recent = typeof cfg.audit?.list === 'function'
+                    ? await cfg.audit.list({ page: LIST_FIRST_PAGE, size: 5 })
+                    : null;
+                return {
+                    usersTotal: stats.totalUsers,
+                    activeSessions: stats.activeSessions,
+                    mau: stats.mau,
+                    signInsTotal: stats.signInsTotal,
+                    signUpsTotal: stats.signUpsTotal,
+                    signInsPerDay: stats.signInsPerDay,
+                    signUpsPerDay: stats.signUpsPerDay,
+                    windowDays: stats.windowDays,
+                    auditSupported: stats.auditSupported,
+                    clientsCount,
+                    auditTotal: recent?.total ?? 0,
+                    recentEvents: (recent?.data ?? []).map(auditDto),
+                };
+            },
+        },
+        {
+            name: 'authkit_list_users',
+            kind: 'read',
+            description: 'Accounts, newest first as the admin console lists them: id, email, name, stored global roles, effective roles and whether the account is disabled. `search` filters by email. Returns { items, total, next }.',
+            input: {
+                type: 'object',
+                properties: {
+                    search: { type: 'string', description: 'Part of an email address.' },
+                    page,
+                    limit,
+                },
+            },
+            async run(input, call) {
+                const cfg = (await service(call.ctx)).config;
+                const p = pageOf(input);
+                const result = await cfg.accountStore.listAccounts({
+                    search: text(input, 'search') ?? '',
+                    page: p.page,
+                    size: p.limit,
+                });
+                const users = new AdminUsersService(cfg);
+                const items = await Promise.all(result.data.map(async (u) => userDtoWithRoles(cfg, u, await users.isDisabled(u.id))));
+                return { items, total: result.total, next: nextPage(p.page, p.limit, result.total) };
+            },
+        },
+        {
+            name: 'authkit_get_user',
+            kind: 'read',
+            description: 'One account: profile, stored and effective roles, disabled flag, MFA on/off (and whether an authenticator app is set up), linked sign-in providers, and how many active sessions and app grants it has. No session ids.',
+            input: { type: 'object', properties: { id: accountId }, required: ['id'] },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const cfg = svc.config;
+                const id = required(input, 'id');
+                const account = await findAccount(cfg, id);
+                const users = new AdminUsersService(cfg);
+                const store = cfg.accountStore;
+                const sessionSvc = sessions(svc);
+                const [disabled, mfa, identities, sessionList, grants] = await Promise.all([
+                    users.isDisabled(id),
+                    supportsMfa(store) ? store.getMfaState(id) : Promise.resolve(null),
+                    supportsProviderIdentity(store) ? store.listProviderIdentities(id) : Promise.resolve([]),
+                    sessionSvc.canList ? sessionSvc.listSessions(id) : Promise.resolve(null),
+                    sessionSvc.canList ? sessionSvc.listGrants(id) : Promise.resolve(null),
+                ]);
+                return {
+                    ...(await userDtoWithRoles(cfg, account, disabled)),
+                    mfa: mfa === null ? null : { enabled: mfa.enabled, totp: mfa.totp ?? null },
+                    identities: identities.map((i) => ({
+                        provider: i.provider,
+                        providerUserId: i.providerUserId,
+                        email: i.email ?? null,
+                    })),
+                    sessionCount: sessionList === null ? null : sessionList.length,
+                    grantCount: grants === null ? null : grants.length,
+                    statusSupported: supportsAccountStatus(store),
+                };
+            },
+        },
+        {
+            name: 'authkit_list_user_sessions',
+            kind: 'read',
+            description: "An account's active sign-in sessions as the admin console shows them: sign-in time, methods (amr), browser, OS, IP and approximate location. No session ids. Returns { supported, items, total, next }.",
+            input: {
+                type: 'object',
+                properties: { accountId, page, limit },
+                required: ['accountId'],
+            },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const id = required(input, 'accountId');
+                await findAccount(svc.config, id);
+                const sessionSvc = sessions(svc);
+                if (!sessionSvc.canList)
+                    return { supported: false, items: [], total: 0, next: null };
+                const raw = await sessionSvc.listSessions(id);
+                const enriched = await enrichSessionsWithContext(svc.config, id, raw);
+                return { supported: true, ...slice(enriched.map(sessionView), pageOf(input)) };
+            },
+        },
+        {
+            name: 'authkit_list_user_grants',
+            kind: 'read',
+            description: 'The apps (OIDC clients) an account granted access to, with how many access and refresh tokens are live for each. Token values are never returned. Returns { supported, items, total, next }.',
+            input: {
+                type: 'object',
+                properties: { accountId, page, limit },
+                required: ['accountId'],
+            },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const id = required(input, 'accountId');
+                await findAccount(svc.config, id);
+                const sessionSvc = sessions(svc);
+                if (!sessionSvc.canList)
+                    return { supported: false, items: [], total: 0, next: null };
+                const grants = await sessionSvc.listGrants(id);
+                return { supported: true, ...slice(grants.map(grantView), pageOf(input)) };
+            },
+        },
+        {
+            name: 'authkit_list_orgs',
+            kind: 'read',
+            description: 'Organizations with their member count. Returns { supported, items, total, next }; `supported: false` when the account store has no organizations.',
+            input: { type: 'object', properties: { page, limit } },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const orgs = new AdminOrgsService(svc.config, svc);
+                if (!orgs.supported)
+                    return { supported: false, items: [], total: 0, next: null };
+                const result = await orgs.listOrgs();
+                if (!Array.isArray(result))
+                    return { supported: false, items: [], total: 0, next: null };
+                return {
+                    supported: true,
+                    ...slice(result.map((o) => orgDto(o)), pageOf(input)),
+                };
+            },
+        },
+        {
+            name: 'authkit_get_org',
+            kind: 'read',
+            description: 'One organization: name, slug, members (account id, email, role, joined at) and pending invitations.',
+            input: {
+                type: 'object',
+                properties: { id: { type: 'string', description: 'The organization id.' } },
+                required: ['id'],
+            },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const orgs = new AdminOrgsService(svc.config, svc);
+                if (!orgs.supported)
+                    throw new Error('The account store has no organizations');
+                const result = await orgs.getOrg(required(input, 'id'));
+                if ('ok' in result && result.ok === false) {
+                    throw new Error(result.reason === 'not_found'
+                        ? `No organization with id "${input.id}"`
+                        : 'The account store has no organizations');
+                }
+                return orgDetailDto(result);
+            },
+        },
+        {
+            name: 'authkit_list_clients',
+            kind: 'read',
+            description: 'OIDC clients (apps that sign in through this identity provider): client id, name, confidential or public, grant types, redirect URIs, auth method, disabled flag. Never the client secret. Returns { supported, items, total, next }.',
+            input: { type: 'object', properties: { page, limit } },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const clientSvc = clients(svc);
+                if (!clientSvc.canList)
+                    return { supported: false, items: [], total: 0, next: null };
+                const list = await clientSvc.list();
+                const items = list.map((c) => ({
+                    clientId: c.clientId,
+                    clientName: c.clientName ?? null,
+                    confidential: c.confidential,
+                    applicationType: c.applicationType ?? null,
+                    grantTypes: c.grantTypes ?? [],
+                    redirectUris: c.redirectUris ?? [],
+                    postLogoutRedirectUris: c.postLogoutRedirectUris ?? [],
+                    authMethod: c.tokenEndpointAuthMethod ?? null,
+                    backchannelLogoutUri: c.backchannelLogoutUri ?? null,
+                    logoUri: c.logoUri ?? null,
+                    disabled: c.disabled === true,
+                    serviceTenant: c.serviceTenant ?? null,
+                }));
+                return { supported: true, ...slice(items, pageOf(input)) };
+            },
+        },
+        {
+            name: 'authkit_list_audit',
+            kind: 'read',
+            description: 'The audit log, newest first: event type, account, actor, client, IP, metadata, time. Filter by `type` (e.g. "login.failure") and `subject` (an account id). Returns { supported, items, total, next }.',
+            input: {
+                type: 'object',
+                properties: {
+                    type: { type: 'string', description: 'Event type, e.g. "login.success".' },
+                    subject: { type: 'string', description: 'Account id the events are about.' },
+                    page,
+                    limit,
+                },
+            },
+            async run(input, call) {
+                const cfg = (await service(call.ctx)).config;
+                const sink = cfg.audit;
+                if (!sink || typeof sink.list !== 'function') {
+                    return { supported: false, items: [], total: 0, next: null };
+                }
+                const p = pageOf(input);
+                const result = await sink.list({
+                    page: p.page,
+                    size: p.limit,
+                    type: text(input, 'type'),
+                    subject: text(input, 'subject'),
+                });
+                return {
+                    supported: true,
+                    items: result.data.map(auditDto),
+                    total: result.total,
+                    next: nextPage(p.page, p.limit, result.total),
+                };
+            },
+        },
+        {
+            name: 'authkit_revoke_user_sessions',
+            kind: 'action',
+            destructive: true,
+            description: "Signs an account out everywhere: ends every session and revokes every app grant and its tokens. Recorded in authkit's audit log (session.revoked_all) with the MCP caller as actor. Returns the counts revoked.",
+            input: { type: 'object', properties: { accountId }, required: ['accountId'] },
+            async run(input, call) {
+                const svc = await service(call.ctx);
+                const cfg = svc.config;
+                const id = required(input, 'accountId');
+                await findAccount(cfg, id);
+                const result = await sessions(svc).revokeAll(id);
+                await cfg.audit?.record({
+                    type: 'session.revoked_all',
+                    accountId: id,
+                    actorId: mcpActor(call),
+                    ip: call.ctx.request?.ip?.() ?? null,
+                    metadata: {
+                        sessions: result.sessions,
+                        grants: result.grants,
+                        accessTokens: result.accessTokens,
+                        refreshTokens: result.refreshTokens,
+                        source: 'mcp',
+                        actor: 'mcp',
+                    },
+                });
+                return { ok: true, accountId: id, ...result };
+            },
+        },
+        {
+            name: 'authkit_disable_user',
+            kind: 'action',
+            destructive: true,
+            description: "Disables an account: it can no longer sign in (re-enable it from the admin console). Recorded in authkit's audit log (user.disabled) with the MCP caller as actor. Only listed when the account store supports disabling accounts.",
+            input: { type: 'object', properties: { accountId }, required: ['accountId'] },
+            async available() {
+                if (!deps.resolve)
+                    return true;
+                try {
+                    return supportsAccountStatus((await deps.resolve()).config.accountStore);
+                }
+                catch {
+                    return false;
+                }
+            },
+            async run(input, call) {
+                const cfg = (await service(call.ctx)).config;
+                const id = required(input, 'accountId');
+                await findAccount(cfg, id);
+                const applied = await new AdminUsersService(cfg).setStatus(id, true, {
+                    actorId: mcpActor(call),
+                    ip: call.ctx.request?.ip?.() ?? null,
+                    source: 'mcp',
+                });
+                if (!applied)
+                    throw new Error('The account store cannot disable accounts');
+                return { ok: true, accountId: id, disabled: true };
+            },
+        },
+    ];
+}

package/build/src/host/admin_api/admin_users_service.d.ts

@@ -8,8 +8,11 @@ import type { SettingsCapability } from '../runtime_settings.js';
 export interface AdminActor {
     actorId: string | null;
     ip: string | null;
-    /** Marca metadata da auditoria — 'admin-api' nas escritas via REST, 'admin' no console HTML. */
-    source?: 'admin-api' | 'admin';
+    /**
+     * Marca metadata da auditoria — 'admin-api' nas escritas via REST, 'admin' no console HTML,
+     * 'mcp' nas ações dos dev tools (endpoint MCP do Agora).
+     */
+    source?: 'admin-api' | 'admin' | 'mcp';
 }
 /** Resultado da deleção via admin: false quando o store não suporta hard delete. */
 export type DeleteUserResult = {

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

@@ -0,0 +1,8 @@
+import { type ConsoleAuthorize, type ConsoleAuthorizeDecision } from '../console_authorize.js';
+/**
+ * Whether the app runs in production. Unknown (the provider did not register the
+ * app) counts as production, so an omitted `admin.authorize` fails closed.
+ */
+export declare function appInProduction(): boolean;
+/** The resolved `admin.authorize` checker (memoized per configured value). Never throws. */
+export declare function adminAuthorizeChecker(authorize: ConsoleAuthorize): (ctx: any) => Promise<ConsoleAuthorizeDecision>;

package/build/src/host/admin_authorize.js

@@ -0,0 +1,25 @@
+import { getBootedApp } from '../../services/booted_app.js';
+import { resolveConsoleAuthorize, } from '../console_authorize.js';
+/**
+ * Whether the app runs in production. Unknown (the provider did not register the
+ * app) counts as production, so an omitted `admin.authorize` fails closed.
+ */
+export function appInProduction() {
+    try {
+        return getBootedApp().inProduction !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/** One checker per configured `admin.authorize`, so a lazy import runs once. */
+const adminAuthorizeCheckers = new WeakMap();
+/** The resolved `admin.authorize` checker (memoized per configured value). Never throws. */
+export function adminAuthorizeChecker(authorize) {
+    let checker = adminAuthorizeCheckers.get(authorize);
+    if (!checker) {
+        checker = resolveConsoleAuthorize(authorize);
+        adminAuthorizeCheckers.set(authorize, checker);
+    }
+    return checker;
+}

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

@@ -191,6 +191,7 @@ export declare const DEFAULT_MESSAGES: {
     'agents.consent.body': string;
     'agents.consent.signed_in_as': string;
     'agents.consent.scopes_label': string;
+    'agents.consent.opt_in_hint': string;
     'agents.consent.code': string;
     'agents.consent.allow': string;
     'agents.consent.deny': string;
@@ -944,6 +945,7 @@ export declare const PT_BR_MESSAGES: {
     'agents.consent.body': string;
     'agents.consent.signed_in_as': string;
     'agents.consent.scopes_label': string;
+    'agents.consent.opt_in_hint': string;
     'agents.consent.code': string;
     'agents.consent.allow': string;
     'agents.consent.deny': string;

package/build/src/host/i18n.js

@@ -200,6 +200,7 @@ export const DEFAULT_MESSAGES = {
     'agents.consent.body': 'The request came from {origin}. Choose what it can do — you can revoke access at any time.',
     'agents.consent.signed_in_as': 'Signed in as {email}',
     'agents.consent.scopes_label': 'Allow it to:',
+    'agents.consent.opt_in_hint': 'Not selected for you: tick it only if you want to allow it.',
     'agents.consent.code': 'Request code: {code}. Make sure it matches the code your assistant shows.',
     'agents.consent.allow': 'Allow',
     'agents.consent.deny': 'Deny',
@@ -1040,6 +1041,7 @@ export const PT_BR_MESSAGES = {
     'agents.consent.body': 'O pedido veio de {origin}. Escolha o que ele pode fazer — você pode revogar o acesso quando quiser.',
     'agents.consent.signed_in_as': 'Conectado como {email}',
     'agents.consent.scopes_label': 'Permitir que ele:',
+    'agents.consent.opt_in_hint': 'Não vem marcado: marque só se quiser permitir.',
     'agents.consent.code': 'Código do pedido: {code}. Confira se é o mesmo que o seu assistente mostra.',
     'agents.consent.allow': 'Permitir',
     'agents.consent.deny': 'Negar',

package/build/src/host/register_auth_host.js

@@ -1,5 +1,3 @@
-import { getBootedApp } from '../../services/booted_app.js';
-import { resolveConsoleAuthorize, } from '../console_authorize.js';
 import { resolveRateLimit } from '../define_config.js';
 import { accountHome } from './account_home.js';
 import { getAccountLoginUrl, setAccountLoginUrl } from './account_login_url.js';
@@ -7,6 +5,7 @@ import { accountPath, accountPathsMap, accountPrefix, joinAccountPath, setAccoun
 import { resolveAccountRoles } from './account_roles.js';
 import { ACCOUNT_SESSION_KEY } from './account_session_key.js';
 import { adminApiGuard } from './admin_api/admin_api_guard.js';
+import { adminAuthorizeChecker, appInProduction } from './admin_authorize.js';
 import { normalizeAdminApiPrefix, normalizeAdminPrefix, setAdminApiPrefix, setAdminPrefix, } from './admin_prefix.js';
 import { getAuthHostConfig, markAuthHostAutoMounted, wasAuthHostAutoMounted, } from './auth_host_config.js';
 import { consoleDeniedPage } from './console_denied_page.js';
@@ -238,18 +237,6 @@ export const adminGuard = async (ctx, next) => {
         return consoleDenied(ctx, decision);
     return next();
 };
-/**
- * Whether the app runs in production. Unknown (the provider did not register the
- * app) counts as production, so an omitted `admin.authorize` fails closed.
- */
-function appInProduction() {
-    try {
-        return getBootedApp().inProduction !== false;
-    }
-    catch {
-        return true;
-    }
-}
 /** The response for an `admin.authorize` denial: same rules in every `@adonis-agora` console. */
 function consoleDenied(ctx, decision) {
     const json = wantsJson(ctx);
@@ -272,16 +259,6 @@ function consoleDenied(ctx, decision) {
     ctx.response.header('Content-Type', 'text/html; charset=utf-8');
     return ctx.response.status(403).send(consoleDeniedPage(403));
 }
-/** One checker per configured `admin.authorize`, so a lazy import runs once. */
-const adminAuthorizeCheckers = new WeakMap();
-function adminAuthorizeChecker(authorize) {
-    let checker = adminAuthorizeCheckers.get(authorize);
-    if (!checker) {
-        checker = resolveConsoleAuthorize(authorize);
-        adminAuthorizeCheckers.set(authorize, checker);
-    }
-    return checker;
-}
 const C = {
     oidc: () => import('../controllers/oidc_callback_controller.js'),
     authorizationServerMetadata: () => import('../controllers/authorization_server_metadata_controller.js'),

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

@@ -183,16 +183,22 @@ export interface ThrottledProps extends WithMessages {
     retryUrl: string;
 }
 /** The agent asking for access, on `agents/consent`. */
+/** One scope on the personal-agent consent screen. */
+export interface AgentConsentScope {
+    id: string;
+    description: string;
+    /** i18n key shown instead of `description` (an extension's message). */
+    descriptionKey?: string;
+    /** Not ticked for the person: granted only if they tick it themselves. */
+    optIn?: boolean;
+}
 export interface AgentConsentRequest {
     /** Device-flow user code, when the agent uses it. */
     userCode?: string;
     agentName: string | null;
     agentOrigin: string | null;
     logoUri?: string | null;
-    scopes: Array<{
-        id: string;
-        description: string;
-    }>;
+    scopes: Array<AgentConsentScope>;
     /** Extra hidden form fields to send back. */
     hidden?: Array<{
         name: string;
@@ -216,10 +222,7 @@ export interface AgentsConsentProps extends WithMessages {
 export interface AgentsDoneProps extends WithMessages {
     status: 'approved' | 'denied' | 'expired' | 'invalid';
     agentName: string | null;
-    scopes: Array<{
-        id: string;
-        description: string;
-    }>;
+    scopes: Array<AgentConsentScope>;
 }
 /** `account/apps` — apps and personal agents with access to the account. */
 export interface AccountAppsProps extends WithMessages {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",