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

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

@@ -0,0 +1,15 @@
+import type { AgoraDoctorCheck, AgoraDoctorResult } from './agora_doctor.js';
+import { type DoctorInput, type Finding } from './checks.js';
+export declare const AUTHKIT_DOCTOR_DOCS = "https://davidecarvalho.github.io/agora/docs/authkit/health-check";
+type CheckFn = (input: DoctorInput) => Finding | Finding[] | null;
+/**
+ * The `authkit:doctor` checks, in `runAllChecks` order, with their frozen `agora:doctor` ids
+ * (`authkit.` + the function name without `check`, in kebab case). Ids are public: never rename.
+ */
+export declare const AUTHKIT_DOCTOR_TABLE: ReadonlyArray<readonly [id: string, title: string, fn: CheckFn]>;
+export declare const AUTHKIT_DOCTOR_PACKAGE = "@adonis-agora/authkit-server";
+/** `admin.authorize` omitted: open outside production, denies every request in production. */
+export declare function consoleGateResult(authkitConfig: Record<string, any> | null, inProduction: boolean): AgoraDoctorResult;
+/** The checks authkit registers into `agora:doctor`. */
+export declare function authkitDoctorChecks(): AgoraDoctorCheck[];
+export {};

package/build/src/doctor/agora_checks.js

@@ -0,0 +1,150 @@
+import { checkAccessTokens, checkAccountExpiration, checkAccountStore, checkAccountStoreColumns, checkAdapterVolatility, checkAdmin, checkAlly, checkAuthMethodsSetting, checkBotProtection, checkClients, checkConfigResolves, checkConsoleSignIn, checkEmailChange, checkFirstPartyClients, checkIssuer, checkJwks, checkOrganizations, checkOtpLockout, checkPasskeyAutofill, checkPasswordExpiration, checkPasswordHistory, checkPasswordPepper, checkPasswordPolicy, checkRateLimit, checkRequireVerifiedEmail, checkRolesCatalog, checkSecurityNotifications, checkSession, checkSessionPolicy, checkSettings, checkShield, checkSudoMode, checkWebauthn, } from './checks.js';
+export const AUTHKIT_DOCTOR_DOCS = 'https://davidecarvalho.github.io/agora/docs/authkit/health-check';
+/**
+ * The `authkit:doctor` checks, in `runAllChecks` order, with their frozen `agora:doctor` ids
+ * (`authkit.` + the function name without `check`, in kebab case). Ids are public: never rename.
+ */
+export const AUTHKIT_DOCTOR_TABLE = [
+    ['authkit.config-resolves', 'config/authkit.ts resolves', checkConfigResolves],
+    ['authkit.issuer', 'Issuer and mount path', checkIssuer],
+    ['authkit.clients', 'OIDC clients', checkClients],
+    ['authkit.adapter-volatility', 'Persistent adapter', checkAdapterVolatility],
+    ['authkit.account-store', 'Account store capabilities', checkAccountStore],
+    ['authkit.account-store-columns', 'Account store columns', checkAccountStoreColumns],
+    ['authkit.session', 'Session', checkSession],
+    ['authkit.shield', 'Shield (CSRF)', checkShield],
+    ['authkit.ally', 'Social login (ally)', checkAlly],
+    ['authkit.rate-limit', 'Rate limiting', checkRateLimit],
+    ['authkit.admin', 'Admin console', checkAdmin],
+    ['authkit.require-verified-email', 'Verified e-mail gate', checkRequireVerifiedEmail],
+    ['authkit.bot-protection', 'Bot protection', checkBotProtection],
+    ['authkit.webauthn', 'Passkeys (WebAuthn)', checkWebauthn],
+    ['authkit.password-policy', 'Password policy', checkPasswordPolicy],
+    ['authkit.jwks', 'Signing keys (JWKS)', checkJwks],
+    ['authkit.access-tokens', 'Access tokens', checkAccessTokens],
+    ['authkit.organizations', 'Organizations', checkOrganizations],
+    ['authkit.settings', 'Runtime settings', checkSettings],
+    ['authkit.auth-methods-setting', 'Sign-in methods setting', checkAuthMethodsSetting],
+    ['authkit.email-change', 'E-mail change', checkEmailChange],
+    ['authkit.security-notifications', 'Security notifications', checkSecurityNotifications],
+    ['authkit.password-pepper', 'Password pepper', checkPasswordPepper],
+    ['authkit.password-history', 'Password history', checkPasswordHistory],
+    ['authkit.password-expiration', 'Password expiration', checkPasswordExpiration],
+    ['authkit.session-policy', 'Session policy', checkSessionPolicy],
+    ['authkit.roles-catalog', 'Roles catalog', checkRolesCatalog],
+    ['authkit.otp-lockout', 'OTP lockout', checkOtpLockout],
+    ['authkit.sudo-mode', 'Sudo mode', checkSudoMode],
+    ['authkit.account-expiration', 'Account expiration', checkAccountExpiration],
+    ['authkit.passkey-autofill', 'Passkey autofill', checkPasskeyAutofill],
+    ['authkit.first-party-clients', 'First-party clients', checkFirstPartyClients],
+    ['authkit.console-sign-in', 'Console sign-in', checkConsoleSignIn],
+];
+export const AUTHKIT_DOCTOR_PACKAGE = '@adonis-agora/authkit-server';
+/** One input per app per doctor run: every check reads the same resolved config. */
+const prepared = new WeakMap();
+function prepare(app) {
+    let entry = prepared.get(app);
+    const state = app.getState?.();
+    if (state === 'created' || state === 'initiated') {
+        return Promise.resolve({ input: null, error: null, notBooted: true });
+    }
+    if (!entry) {
+        // Loaded on demand: the provider imports this module, and the input builder pulls in adapters.
+        entry = import('./doctor_input.js')
+            .then(({ buildDoctorInput }) => buildDoctorInput(app))
+            .then((input) => ({ input, error: null }), (error) => ({
+            input: null,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        prepared.set(app, entry);
+    }
+    return entry;
+}
+function toResults(found) {
+    const list = found === null ? [] : Array.isArray(found) ? found : [found];
+    if (list.length === 0)
+        return [{ status: 'skip', message: 'not applicable to this config' }];
+    return list.map((finding) => ({
+        status: finding.level,
+        message: finding.message,
+        ...(finding.level === 'ok' ? {} : { docs: AUTHKIT_DOCTOR_DOCS }),
+    }));
+}
+/** `admin.authorize` omitted: open outside production, denies every request in production. */
+export function consoleGateResult(authkitConfig, inProduction) {
+    const admin = authkitConfig?.admin;
+    if (!admin || admin.enabled !== true) {
+        return { status: 'skip', message: 'admin console is off' };
+    }
+    if (admin.authorize) {
+        return { status: 'ok', message: 'admin console has `admin.authorize`' };
+    }
+    const fix = 'Set `admin.authorize` in config/authkit.ts';
+    return inProduction
+        ? {
+            status: 'error',
+            message: 'admin console has no `admin.authorize`: it denies every request in production',
+            fix,
+            docs: AUTHKIT_DOCTOR_DOCS,
+        }
+        : {
+            status: 'warn',
+            message: 'admin console has no `admin.authorize`: open here, denies every request in production',
+            fix,
+            docs: AUTHKIT_DOCTOR_DOCS,
+        };
+}
+/** The checks authkit registers into `agora:doctor`. */
+export function authkitDoctorChecks() {
+    const checks = AUTHKIT_DOCTOR_TABLE.map(([id, title, fn]) => ({
+        id,
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title,
+        async run(app) {
+            const { input, error, notBooted } = await prepare(app);
+            if (notBooted)
+                return [{ status: 'skip', message: 'needs a booted app (run without --no-boot)' }];
+            if (input === null) {
+                return id === 'authkit.config-resolves'
+                    ? [
+                        {
+                            status: 'error',
+                            message: `config/authkit.ts failed to resolve: ${error}`,
+                            docs: AUTHKIT_DOCTOR_DOCS,
+                        },
+                    ]
+                    : [{ status: 'skip', message: 'config/authkit.ts did not resolve' }];
+            }
+            return toResults(fn(input));
+        },
+    }));
+    checks.push({
+        id: 'authkit.signing-key-age',
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title: 'Signing key age',
+        async run(app) {
+            const { input, notBooted } = await prepare(app);
+            if (notBooted) {
+                return { status: 'skip', message: 'needs a booted app (run without --no-boot)' };
+            }
+            if (!input)
+                return toResults(null);
+            const { managedSigningKeyAgeFinding } = await import('./doctor_input.js');
+            return toResults(await managedSigningKeyAgeFinding(app, input.authkitConfig));
+        },
+    }, {
+        id: 'authkit.console-gate',
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title: 'Admin console access in production',
+        async run(app) {
+            const { input, notBooted } = await prepare(app);
+            if (notBooted)
+                return { status: 'skip', message: 'needs a booted app (run without --no-boot)' };
+            return consoleGateResult(input?.authkitConfig ?? null, app.inProduction);
+        },
+    });
+    return checks;
+}

package/build/src/doctor/agora_doctor.d.ts

@@ -0,0 +1,115 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/** The container binding the registry lives at. */
+export declare const AGORA_DOCTOR_BINDING = "agora.doctor";
+/** Bound as a VALUE under `'agora.doctor'`. Data only. */
+export interface AgoraDoctorRegistry {
+    readonly version: 1;
+    readonly checks: AgoraDoctorCheck[];
+}
+export type AgoraDoctorStatus = 'ok' | 'warn' | 'error' | 'skip';
+export interface AgoraDoctorCheck {
+    /** `'<lib>.<kebab>'`, unique and frozen for 1.x: `'durable.verify-tenant'`. */
+    id: string;
+    /** `'durable'`. The package is `@adonis-agora/<lib>` unless {@link package} says otherwise. */
+    lib: string;
+    /** The npm package, when it is not `@adonis-agora/<lib>`. */
+    package?: string;
+    title: string;
+    /** `'cheap'` (default) reads config, env and files only; `'deep'` touches a DB, Redis or the network. */
+    cost?: 'cheap' | 'deep';
+    run(app: ApplicationService): AgoraDoctorResult | AgoraDoctorResult[] | Promise<AgoraDoctorResult | AgoraDoctorResult[]>;
+}
+export interface AgoraDoctorResult {
+    status: AgoraDoctorStatus;
+    /** One line, no secrets, no stack. */
+    message: string;
+    /** One line: the exact change to make. */
+    fix?: string;
+    /** Absolute URL of the lib docs page. */
+    docs?: string;
+}
+/** One reported result. */
+export interface AgoraDoctorReportEntry extends AgoraDoctorResult {
+    id: string;
+    lib: string;
+    title: string;
+    ms: number;
+}
+/** What `agora:doctor --json` prints. */
+export interface AgoraDoctorReport {
+    version: 1;
+    env: string;
+    summary: Record<AgoraDoctorStatus, number>;
+    libs: Array<{
+        lib: string;
+        package: string;
+        version: string | null;
+    }>;
+    results: AgoraDoctorReportEntry[];
+}
+export interface AgoraDoctorOptions {
+    libs?: string[];
+    only?: string;
+    deep?: boolean;
+    /** The app was not booted (`--no-boot`): deep checks are reported as skipped, never run. */
+    noBoot?: boolean;
+    strict?: boolean;
+    /** Per-check budget in ms (default 5000, deep checks 15000). */
+    timeoutMs?: number;
+    deepTimeoutMs?: number;
+}
+/** A doctor problem that stops the run itself (exit 2). */
+export declare class AgoraDoctorUsageError extends Error {
+}
+interface ContainerLike {
+    hasBinding(binding: string): boolean;
+    bindValue(binding: string, value: unknown): void;
+    make(binding: string): Promise<unknown>;
+}
+/**
+ * Add a lib's checks to the app's doctor registry, creating it when absent. Call it from a provider's
+ * `boot()` (Adonis does not await `register()`, so an async registration there can be lost). A
+ * registry of another version is left alone; a duplicate id is skipped.
+ */
+export declare function registerDoctorChecks(container: ContainerLike, checks: readonly AgoraDoctorCheck[]): Promise<void>;
+/** The registered checks; throws {@link AgoraDoctorUsageError} on a registry of another version. */
+export declare function readDoctorChecks(container: ContainerLike): Promise<AgoraDoctorCheck[]>;
+/**
+ * The checks of every installed `@adonis-agora/*` package that publishes a `./doctor` entry
+ * (`export const agoraDoctorChecks`), imported from the app root without booting providers. A
+ * package whose entry fails to load is reported as an error (`<lib>.doctor-entry`), never skipped.
+ */
+export declare function discoverDoctorChecks(app: ApplicationService): Promise<AgoraDoctorCheck[]>;
+/** The directory of `name` as Node would find it from `from` (walking up `node_modules`), real path. */
+export declare function packageDir(name: string, from: string): Promise<string | null>;
+/** The installed version of `name` resolved from `from`, or `null` when it is not installed. */
+export declare function installedVersion(name: string, from: string): Promise<string | null>;
+/**
+ * Whether `version` satisfies `range`, with node-semver's grammar and prereleases included (like
+ * `semver.satisfies(version, range, { includePrerelease: true })`). An unparsable range is `false`.
+ */
+export declare function satisfies(version: string, range: string): boolean;
+/**
+ * The environment shown in the report, from the app itself: `production` when `app.inProduction`,
+ * `test` when `app.inTest`, else the app's node environment, and `development` when that is unset.
+ */
+export declare function environmentOf(app: Pick<ApplicationService, 'inProduction' | 'inTest' | 'nodeEnvironment'>): string;
+/** Run the checks and build the report. Throws {@link AgoraDoctorUsageError} for an unknown `--only`. */
+export declare function runAgoraDoctor(app: ApplicationService, registered: readonly AgoraDoctorCheck[], options?: AgoraDoctorOptions): Promise<{
+    report: AgoraDoctorReport;
+    exitCode: 0 | 1;
+}>;
+export interface Paint {
+    green(text: string): string;
+    yellow(text: string): string;
+    red(text: string): string;
+    dim(text: string): string;
+    bold(text: string): string;
+}
+/** The human report. `fancy` = colors and symbols (a TTY without `NO_COLOR`). */
+export declare function renderAgoraDoctor(report: AgoraDoctorReport, options?: {
+    verbose?: boolean;
+    fancy?: boolean;
+    paint?: Paint;
+}): string;
+export {};