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

package/build/index.js

@@ -10,16 +10,11 @@ export { lucidStores } from './src/accounts/lucid_stores.js';
 export { ProviderIdentities, ProviderIdentitiesUnsupportedError, } from './src/accounts/provider_identities.js';
 export { PersonalAgentVerifier } from './src/agents/agent_identity.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
-export { accessTokenHash, hmacNonceSource, verifyDpopProof, } from './src/agents/poppy/dpop.js';
-export { maskEmail, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
-export { PoppyError } from './src/agents/poppy/errors.js';
-export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
-export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';
-export { isBlockedAddress, SafeFetchError, safeFetchJson, } from './src/agents/poppy/safe_fetch.js';
-export { poppyWebSession, poppyWebSessionOf, } from './src/agents/poppy/web_session.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
+export { personalAgentExtensionRuntime, } from './src/agents/runtime.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export { authorizeByToken } from './src/console_authorize.js';
+export { AGORA_CONSOLES_BINDING, isAgoraProbe, registerAgoraConsole, } from './src/console_switcher.js';
 export { adapters, defineConfig, resolveAdmin, resolveAdminApi, resolveAuthMethodsConfig, resolveDynamicRegistration, resolveLogin, resolveNotifications, resolveOrganizations, resolvePasswordless, resolveRateLimit, resolveRegistration, resolveWebauthn, toSeconds, } from './src/define_config.js';
 export { buildWebhookBody, composeAuditSink, resolveEvents, signWebhookBody, } from './src/events/dispatcher.js';
 export { inProcessAccessTokenVerifier, remoteAccessTokenVerifier, } from './src/host/access_token_verifier.js';
@@ -39,6 +34,7 @@ export { AccountExportService } from './src/host/account_export_service.js';
  */
 export { accountPath, accountPrefix, joinAccountPath, } from './src/host/account_paths.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/account_session_key.js';
+export { signInAccountSession, signOutAccountSession, } from './src/host/account_session_sign_in.js';
 // Organizations (multi-tenancy)
 export { ACTIVE_ORG_COOKIE, ACTIVE_ORG_COOKIE_TTL, decodeActiveOrgCookie, encodeActiveOrgCookie, readActiveOrgFromKoaCtx, } from './src/host/active_org_cookie.js';
 export { AdminOrgsService } from './src/host/admin_api/admin_orgs_service.js';
@@ -65,6 +61,7 @@ export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from
 export { authkitCsrfExceptions } from './src/host/csrf.js';
 export { authenticateCustomLogin, beginCustomLogin, completeCustomLogin, } from './src/host/custom_login.js';
 export { beginCustomMfa, customMfaViewProps, verifyCustomMfa } from './src/host/custom_mfa.js';
+export { sendAuthkitCodeEmail } from './src/host/default_mailer.js';
 export { normalizeEmailIdentifier } from './src/host/email_identifier.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
@@ -89,7 +86,6 @@ export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 // Login por OTP (código digitável): config + helpers puros.
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, resolveOtpLoginConfig, } from './src/host/otp_login.js';
 export { endRpSession } from './src/host/persistent_rp_session.js';
-export { POPPY_WEB_SESSION_KEY } from './src/host/poppy_session_key.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
@@ -140,5 +136,7 @@ export { generatePatToken, hashPatToken } from './src/pat/pat_tokens.js';
 export { OidcService } from './src/provider/oidc_service.js';
 export { checkClientRegistration, classifyRedirect, RegistrationPolicyError, } from './src/provider/registration_policy.js';
 export { registerOidcRoutes } from './src/register_routes.js';
-export { ensureAuthkitSchema } from './src/schema/ensure.js';
+export { ensureAuthkitSchema, ensureAuthkitTables } from './src/schema/ensure.js';
+export { AuthkitTenantVerifier, authkitTenantVerifier, } from './src/service_tenants/tenant_verifier.js';
+export { authkitTenantLabels, } from './src/tenancy/tenant_labels.js';
 export { stubsRoot } from './stubs/main.js';

package/build/providers/authkit_server_provider.js

@@ -16,7 +16,10 @@ import { fileURLToPath } from 'node:url';
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { setBootedApp } from '../services/booted_app.js';
+import { accountExtensionRegistry } from '../src/account/mount.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 +36,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
@@ -131,11 +137,12 @@ export default class AuthkitServerProvider {
             routes: typeof config.routes === 'object' ? config.routes : undefined,
             lockedRouteOptions: config.lockedRouteOptions,
             consoleNeedsLoginUrl: config.accountSession?.acceptIdpSession === false && config.authMethods?.password === false,
+            accountConsole: config.accountConsole,
             personalAgents: config.personalAgents
                 ? {
                     prefix: config.personalAgents.prefix,
-                    ...(config.personalAgents.poppy
-                        ? { poppyPrefix: config.personalAgents.poppy.prefix }
+                    ...(config.personalAgents.extensions?.length
+                        ? { extensions: config.personalAgents.extensions }
                         : {}),
                 }
                 : undefined,
@@ -154,12 +161,21 @@ export default class AuthkitServerProvider {
             const logger = await this.app.container.make('logger').catch(() => null);
             warnAdminConsoleUnauthorized(logger);
         }
-        // Poppy: o slot global que o `@adonis-agora/agent` usa para autenticar o endpoint de
-        // conversas (e o MCP) sem importar este pacote — o contrato é o símbolo.
-        if (config.personalAgents?.poppy) {
-            const { installPoppySlots } = await import('../src/agents/poppy/resource.js');
-            const { poppyUrls } = await import('../src/agents/poppy/service.js');
-            installPoppySlots(poppyUrls(config.issuer, config.personalAgents.poppy.prefix).issuer);
+        // 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?.();
         }
         // Auto-montagem das rotas (`config.routes`). Chama a MESMA função exportada que o
         // `start/routes.ts` chamaria; não há segunda implementação. "As rotas não subiram" não pode
@@ -177,6 +193,9 @@ export default class AuthkitServerProvider {
         // que o `bin/server` bootou — dual-package hazard do core (ver
         // `services/booted_app.ts`).
         setBootedApp(this.app);
+        // Account console extensions: other packages register pages here from their `boot()`. No
+        // config to resolve, so `hasBinding` + `make` never boots the auth server.
+        this.app.container.singleton('authkit.accountExtensions', async () => accountExtensionRegistry());
         this.app.container.singleton('authkit.server', async () => {
             const configProviderValue = this.app.config.get('authkit');
             const config = (await configProvider.resolve(this.app, configProviderValue));
@@ -268,6 +287,7 @@ export default class AuthkitServerProvider {
             const report = await ensureAuthkitSchema(db, {
                 connection: config.schema.connection,
                 accountTable: config.accountStore?.accountTable,
+                tables: config.personalAgents?.extensions?.flatMap((e) => e.tables ?? []),
             });
             const logger = await this.app.container.make('logger').catch(() => null);
             if (report.created.length > 0) {

package/build/src/account/extension.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Account console extensions — the surface another package (or the app) uses to add pages to the
+ * signed-in user's own console (`/account/*`).
+ *
+ * **Stable for all of 1.x.** Types and constants only (the same ones `@adonis-agora/authkit-client`
+ * binds for an app whose IdP runs elsewhere), so a contributor can `import type` it from an
+ * internal module without a runtime dependency on authkit.
+ */
+export type { AccountAction, AccountActionField, AccountActionResult, AccountActiveOrg, AccountBlockKind, AccountExtension, AccountExtensionContext, AccountExtensionOverride, AccountExtensionRegistry, AccountPage, AccountPageNav, AccountPageView, AccountSubject, AccountTenantLevel, AccountTenantRef, ActionRef, Block, ComponentScript, ListItem, Text, Value, } from '@adonis-agora/authkit-core';
+export { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, ACCOUNT_EXTENSIONS_BINDING, } from '@adonis-agora/authkit-core';

package/build/src/account/extension.js

@@ -0,0 +1,9 @@
+/**
+ * Account console extensions — the surface another package (or the app) uses to add pages to the
+ * signed-in user's own console (`/account/*`).
+ *
+ * **Stable for all of 1.x.** Types and constants only (the same ones `@adonis-agora/authkit-client`
+ * binds for an app whose IdP runs elsewhere), so a contributor can `import type` it from an
+ * internal module without a runtime dependency on authkit.
+ */
+export { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, ACCOUNT_EXTENSIONS_BINDING, } from '@adonis-agora/authkit-core';

package/build/src/account/http.d.ts

@@ -0,0 +1,77 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { AccountAction, Text } from './extension.js';
+import type { RegisteredAccountPage } from './registry.js';
+/** The confirmation step of an action, as the view renders it. */
+export interface ResolvedActionStep {
+    action: string;
+    title: string;
+    text: string | null;
+    tone: 'default' | 'danger';
+    sudo: boolean;
+    /** POST target of the form. */
+    href: string;
+    target: string | null;
+    cancelHref: string;
+    submitLabel: string;
+    fields: Array<{
+        name: string;
+        label: string;
+        kind: 'text' | 'select' | 'textarea';
+        required: boolean;
+        maxLength: number | null;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+        value: string;
+    }>;
+}
+/** An action as the JSON API describes it. */
+export interface ResolvedActionDefinition {
+    label: string;
+    tone: 'default' | 'danger';
+    confirm: string | null;
+    sudo: boolean;
+    fields: ResolvedActionStep['fields'];
+}
+/** Validates the posted fields against the action's declaration. */
+export declare function validateActionInput(action: AccountAction, raw: {
+    target?: unknown;
+    fields?: unknown;
+}, t: (text: Text | undefined | null) => string): {
+    ok: true;
+    target: string | null;
+    fields: Record<string, string>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The `<script>` tag of a `component` block's script: the response's CSP nonce when shield set
+ * one, `integrity` + `crossorigin` when the block gave one, `type="module"` when asked.
+ */
+export declare function componentScriptTag(script: {
+    src: string;
+    integrity: string | null;
+    module: boolean;
+}, nonce: string | null): string;
+/** `GET {prefix}/{segment}` — renders an extension page. */
+export declare function showPage(ctx: HttpContext, page: RegisteredAccountPage): Promise<unknown>;
+/** `GET {prefix}/{segment}/actions/:action/confirm` — the no-JS confirmation step. */
+export declare function showActionStep(ctx: HttpContext, page: RegisteredAccountPage): Promise<unknown>;
+/** The CSP nonce shield put on this response, when there is one. */
+export declare function cspNonceOf(ctx: HttpContext): string | null;
+/** `POST {prefix}/{segment}/actions/:action` — a form submission (`_csrf` checked by shield). */
+export declare function postAction(ctx: HttpContext, page: RegisteredAccountPage): Promise<unknown>;
+/** `GET {prefix}/api/extensions` — the navigation for React hosts. */
+export declare function apiExtensions(ctx: HttpContext): Promise<void>;
+/** `GET {prefix}/api/x/:pageId` — one page, resolved. */
+export declare function apiPage(ctx: HttpContext): Promise<void>;
+/** `POST {prefix}/api/x/:pageId/actions/:action` — runs an action, answers JSON. */
+export declare function apiAction(ctx: HttpContext): Promise<void>;
+/** A remote app's page (mounted on the catch-all route; `undefined` when it went away). */
+export declare function showRemotePage(ctx: HttpContext, page: RegisteredAccountPage | undefined): Promise<unknown>;
+/** The confirmation step of a remote app's action. */
+export declare function showRemoteActionStep(ctx: HttpContext, page: RegisteredAccountPage | undefined): Promise<unknown>;
+/** Runs a remote app's action. */
+export declare function postRemoteAction(ctx: HttpContext, page: RegisteredAccountPage | undefined): Promise<unknown>;

package/build/src/account/http.js

@@ -0,0 +1,381 @@
+import { accountPath } from '../host/account_paths.js';
+import { redirectExact } from '../host/redirect_exact.js';
+import { resolveRuntimeSettings } from '../host/runtime_settings.js';
+import { isSudoSatisfied } from '../host/sudo_mode.js';
+import { accountExtensionPages, buildAccountNav, consoleRequest, extensionContext, findPageById, isPageVisible, loadResolvedPage, logExtensionError, pageHref, resolveAction, safeHref, translatorFor, validatedQuery, withTimeout, } from './runtime.js';
+/** Flash key of an action's outcome. */
+const FLASH_KEY = 'authkit_account_extension';
+function apiError(code, message, extra = {}) {
+    return { error: { code, message, ...extra } };
+}
+function notFound(ctx, json) {
+    if (json)
+        return ctx.response.status(404).send(apiError('not_found', 'Not found.'));
+    return ctx.response.status(404).send('Not found');
+}
+async function requestOr404(ctx, page, json) {
+    const request = await consoleRequest(ctx);
+    if (!request || !page || !(await isPageVisible(request, page))) {
+        notFound(ctx, json);
+        return null;
+    }
+    return { request, page };
+}
+function actionOf(page, name) {
+    const actions = page.page.actions ?? {};
+    return Object.hasOwn(actions, name) ? (actions[name] ?? null) : null;
+}
+function resolveFields(action, t, values = {}) {
+    return (action.fields ?? []).map((field) => ({
+        name: field.name,
+        label: t(field.label),
+        kind: field.kind,
+        required: field.required === true,
+        maxLength: typeof field.maxLength === 'number' ? field.maxLength : null,
+        options: (field.options ?? []).map((o) => ({ value: o.value, label: t(o.label) })),
+        value: values[field.name] ?? '',
+    }));
+}
+function definitionOf(action, t) {
+    return {
+        label: t(action.label),
+        tone: action.tone === 'danger' ? 'danger' : 'default',
+        confirm: action.confirm !== undefined ? t(action.confirm) : null,
+        sudo: action.sudo === true,
+        fields: resolveFields(action, t),
+    };
+}
+const DEFAULT_MAX_LENGTH = 2000;
+/** Validates the posted fields against the action's declaration. */
+export function validateActionInput(action, raw, t) {
+    const target = typeof raw.target === 'string' && raw.target !== '' && raw.target.length <= 512
+        ? raw.target
+        : null;
+    const posted = (raw.fields && typeof raw.fields === 'object' ? raw.fields : {});
+    const fields = {};
+    for (const field of action.fields ?? []) {
+        const value = posted[field.name];
+        const text = typeof value === 'string' ? value : '';
+        const name = t(field.label);
+        if (field.required && text.trim() === '') {
+            return {
+                ok: false,
+                error: t({ key: 'account.extension.field_required', params: { field: name } }),
+            };
+        }
+        if (text.length > (field.maxLength ?? DEFAULT_MAX_LENGTH)) {
+            return {
+                ok: false,
+                error: t({ key: 'account.extension.field_too_long', params: { field: name } }),
+            };
+        }
+        if (field.kind === 'select' &&
+            text !== '' &&
+            !(field.options ?? []).some((o) => o.value === text)) {
+            return {
+                ok: false,
+                error: t({ key: 'account.extension.field_invalid', params: { field: name } }),
+            };
+        }
+        fields[field.name] = text;
+    }
+    return { ok: true, target, fields };
+}
+/** The page's flash (set by the last action), read once. */
+function takeFlash(ctx) {
+    try {
+        const flash = ctx.session?.flashMessages?.get(FLASH_KEY);
+        if (flash && typeof flash.text === 'string') {
+            return { tone: flash.tone === 'danger' ? 'danger' : 'success', text: flash.text };
+        }
+    }
+    catch {
+        /* no session */
+    }
+    return null;
+}
+function flash(ctx, tone, text) {
+    try {
+        ctx.session.flash(FLASH_KEY, { tone, text });
+    }
+    catch {
+        /* no session */
+    }
+}
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/**
+ * The `<script>` tag of a `component` block's script: the response's CSP nonce when shield set
+ * one, `integrity` + `crossorigin` when the block gave one, `type="module"` when asked.
+ */
+export function componentScriptTag(script, nonce) {
+    const attrs = [`src="${escapeAttr(script.src)}"`];
+    if (script.module)
+        attrs.push('type="module"');
+    else
+        attrs.push('defer');
+    if (nonce)
+        attrs.push(`nonce="${escapeAttr(nonce)}"`);
+    if (script.integrity) {
+        attrs.push(`integrity="${escapeAttr(script.integrity)}"`, 'crossorigin="anonymous"');
+    }
+    return `<script ${attrs.join(' ')}></script>`;
+}
+async function render(ctx, request, props) {
+    const render = request.cfg.render;
+    const nonce = cspNonceOf(ctx);
+    return render(ctx, 'account/extension', {
+        csrfToken: ctx.request.csrfToken ?? '',
+        cspNonce: nonce,
+        htmlLang: request.locale.toLowerCase(),
+        scriptTag: (script) => componentScriptTag(script, nonce),
+        ...props,
+    });
+}
+/** `GET {prefix}/{segment}` — renders an extension page. */
+export async function showPage(ctx, page) {
+    const found = await requestOr404(ctx, page, false);
+    if (!found)
+        return;
+    const query = validatedQuery(ctx.request.qs());
+    const resolved = await loadResolvedPage(found.request, found.page, query);
+    return render(ctx, found.request, {
+        page: resolved,
+        step: null,
+        flash: takeFlash(ctx),
+    });
+}
+/** `GET {prefix}/{segment}/actions/:action/confirm` — the no-JS confirmation step. */
+export async function showActionStep(ctx, page) {
+    const found = await requestOr404(ctx, page, false);
+    if (!found)
+        return;
+    const name = String(ctx.request.param('action') ?? '');
+    const action = actionOf(found.page, name);
+    if (!action)
+        return notFound(ctx, false);
+    const t = translatorFor(found.request, found.page);
+    const target = typeof ctx.request.qs().target === 'string' ? ctx.request.qs().target : null;
+    const button = resolveAction(found.page, { action: name, ...(target ? { target } : {}) }, t);
+    const step = {
+        action: name,
+        title: t(action.label),
+        text: action.confirm !== undefined ? t(action.confirm) : null,
+        tone: action.tone === 'danger' ? 'danger' : 'default',
+        sudo: action.sudo === true,
+        href: button ? button.href.replace(/\/confirm(\?.*)?$/, '') : pageHref(found.page),
+        target,
+        cancelHref: pageHref(found.page),
+        submitLabel: t(action.label),
+        fields: resolveFields(action, t),
+    };
+    const resolved = {
+        id: found.page.page.id,
+        extension: found.page.extensionId,
+        title: t(found.page.page.title),
+        href: pageHref(found.page),
+        tabs: [],
+        blocks: [],
+    };
+    return render(ctx, found.request, {
+        page: resolved,
+        step,
+        flash: takeFlash(ctx),
+    });
+}
+/** The CSP nonce shield put on this response, when there is one. */
+export function cspNonceOf(ctx) {
+    const nonce = ctx.response?.nonce;
+    return typeof nonce === 'string' && nonce !== '' ? nonce : null;
+}
+async function runAction(ctx, request, page, name, raw, json) {
+    const t = translatorFor(request, page);
+    const action = actionOf(page, name);
+    const back = pageHref(page);
+    if (!action) {
+        const text = t({ key: 'account.extension.action_not_found' });
+        return {
+            status: 404,
+            body: { ok: false, error: apiError('not_found', text).error },
+            location: back,
+            flash: { tone: 'danger', text },
+        };
+    }
+    const sensitive = action.sudo === true || action.tone === 'danger';
+    if (sensitive && request.base.impersonatedBy !== null) {
+        const text = t({ key: 'account.extension.impersonation_refused' });
+        return {
+            status: 403,
+            body: { ok: false, error: apiError('impersonation_refused', text).error },
+            location: back,
+            flash: { tone: 'danger', text },
+        };
+    }
+    if (action.sudo === true) {
+        const settings = await resolveRuntimeSettings(ctx);
+        if (!(await isSudoSatisfied(ctx, settings)))
+            return 'sudo';
+    }
+    const input = validateActionInput(action, raw, t);
+    // The step keeps the posted target even when the fields were refused, so the user can fix them.
+    const rawTarget = typeof raw.target === 'string' && raw.target !== '' && raw.target.length <= 512
+        ? raw.target
+        : null;
+    const button = resolveAction(page, { action: name, ...(rawTarget ? { target: rawTarget } : {}) }, t);
+    const stepHref = button?.step ? button.href : back;
+    if (!input.ok) {
+        return {
+            status: 422,
+            body: { ok: false, error: apiError('invalid_input', input.error).error },
+            location: stepHref,
+            flash: { tone: 'danger', text: input.error },
+        };
+    }
+    let result;
+    try {
+        result = await withTimeout(action.handle(extensionContext(request, {}), { target: input.target, fields: input.fields }), request.config.actionTimeoutMs ?? 15_000, 'handle()');
+    }
+    catch (error) {
+        logExtensionError(page, `actions.${name}.handle`, error);
+        result = { ok: false, error: { key: 'account.extension.action_failed' } };
+    }
+    const audit = async (type, extra = {}) => {
+        try {
+            await request.cfg.audit?.record({
+                type,
+                accountId: request.base.account.id,
+                ip: ctx.request.ip?.() ?? null,
+                metadata: { page: page.page.id, action: name, target: input.target, ...extra },
+            });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    if (sensitive)
+        await audit('account.extension.action', { ok: result?.ok === true });
+    if (!result || result.ok !== true) {
+        const failure = result;
+        const text = t(failure?.error ?? { key: 'account.extension.action_failed' });
+        const status = [400, 403, 404, 409].includes(failure?.status ?? 0)
+            ? failure?.status
+            : 400;
+        return {
+            status,
+            body: { ok: false, error: apiError('action_failed', text).error },
+            location: json ? back : button?.step ? stepHref : back,
+            flash: { tone: 'danger', text },
+        };
+    }
+    let location = back;
+    let external = false;
+    const redirectTo = result.redirectTo;
+    if (redirectTo && 'page' in redirectTo) {
+        const other = findPageById(redirectTo.page);
+        if (other)
+            location = pageHref(other);
+    }
+    else if (redirectTo && 'external' in redirectTo) {
+        const href = safeHref(redirectTo.external, true);
+        if (href) {
+            location = href;
+            external = true;
+            await audit('account.extension.redirect', { url: href });
+        }
+    }
+    const text = t(result.flash ?? { key: 'account.extension.done' });
+    return {
+        status: 200,
+        body: { ok: true, flash: text, redirectTo: location === back ? null : location, external },
+        location,
+        flash: external ? null : { tone: 'success', text },
+    };
+}
+function sudoUrl(returnTo) {
+    return `${accountPath('confirm')}?return_to=${encodeURIComponent(returnTo)}`;
+}
+/** `POST {prefix}/{segment}/actions/:action` — a form submission (`_csrf` checked by shield). */
+export async function postAction(ctx, page) {
+    const found = await requestOr404(ctx, page, false);
+    if (!found)
+        return;
+    const name = String(ctx.request.param('action') ?? '');
+    const body = ctx.request.body();
+    const fields = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (key.startsWith('field_'))
+            fields[key.slice('field_'.length)] = value;
+    }
+    const outcome = await runAction(ctx, found.request, found.page, name, { target: body.target, fields }, false);
+    if (outcome === 'sudo') {
+        const t = translatorFor(found.request, found.page);
+        const target = typeof body.target === 'string' ? body.target : undefined;
+        const button = resolveAction(found.page, { action: name, ...(target ? { target } : {}) }, t);
+        return redirectExact(ctx.response, sudoUrl(button?.step ? button.href : pageHref(found.page)));
+    }
+    if (outcome.flash)
+        flash(ctx, outcome.flash.tone, outcome.flash.text);
+    return redirectExact(ctx.response, outcome.location);
+}
+// ── JSON API ──────────────────────────────────────────────────────────────────────────────────────
+/** `GET {prefix}/api/extensions` — the navigation for React hosts. */
+export async function apiExtensions(ctx) {
+    const nav = await buildAccountNav(ctx, null);
+    const ids = new Set(accountExtensionPages().map((p) => p.page.id));
+    return ctx.response.send({
+        nav,
+        pages: nav
+            .filter((entry) => ids.has(entry.id))
+            .map(({ id, label, href, order, group }) => ({ id, label, href, order, group })),
+    });
+}
+/** `GET {prefix}/api/x/:pageId` — one page, resolved. */
+export async function apiPage(ctx) {
+    const found = await requestOr404(ctx, findPageById(String(ctx.request.param('pageId'))), true);
+    if (!found)
+        return;
+    const query = validatedQuery(ctx.request.qs());
+    const page = await loadResolvedPage(found.request, found.page, query);
+    const t = translatorFor(found.request, found.page);
+    const actions = {};
+    for (const [name, action] of Object.entries(found.page.page.actions ?? {})) {
+        actions[name] = definitionOf(action, t);
+    }
+    return ctx.response.header('cache-control', 'private, no-store').send({ page, actions });
+}
+/** `POST {prefix}/api/x/:pageId/actions/:action` — runs an action, answers JSON. */
+export async function apiAction(ctx) {
+    const found = await requestOr404(ctx, findPageById(String(ctx.request.param('pageId'))), true);
+    if (!found)
+        return;
+    const name = String(ctx.request.param('action') ?? '');
+    const body = ctx.request.body();
+    const outcome = await runAction(ctx, found.request, found.page, name, body, true);
+    if (outcome === 'sudo') {
+        // Back to the action's confirmation step (target included) when it has one, like the forms.
+        const t = translatorFor(found.request, found.page);
+        const target = typeof body.target === 'string' && body.target !== '' ? body.target : undefined;
+        const button = resolveAction(found.page, { action: name, ...(target ? { target } : {}) }, t);
+        return ctx.response.status(403).send(apiError('sudo_required', 'Identity confirmation required.', {
+            confirmUrl: sudoUrl(button?.step ? button.href : pageHref(found.page)),
+        }));
+    }
+    return ctx.response.status(outcome.status).send(outcome.body);
+}
+/** A remote app's page (mounted on the catch-all route; `undefined` when it went away). */
+export async function showRemotePage(ctx, page) {
+    return page ? showPage(ctx, page) : notFound(ctx, false);
+}
+/** The confirmation step of a remote app's action. */
+export async function showRemoteActionStep(ctx, page) {
+    return page ? showActionStep(ctx, page) : notFound(ctx, false);
+}
+/** Runs a remote app's action. */
+export async function postRemoteAction(ctx, page) {
+    return page ? postAction(ctx, page) : notFound(ctx, false);
+}

package/build/src/account/mount.d.ts

@@ -0,0 +1,40 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { AccountExtensionOverride } from './extension.js';
+import { AccountExtensionRegistryImpl } from './registry.js';
+import { type RemoteAccountExtensionSource } from './remote.js';
+import { type BuiltinNavId } from './runtime.js';
+type Middleware = (ctx: HttpContext, next: () => Promise<void>) => Promise<unknown>;
+/** The process registry bound at `authkit.accountExtensions`. */
+export declare function accountExtensionRegistry(): AccountExtensionRegistryImpl;
+/** A fresh registry (tests). */
+export declare function resetAccountExtensionRegistry(next?: AccountExtensionRegistryImpl): void;
+/** One extension page in {@link AuthHostRouteMap}. */
+export interface AccountExtensionRouteEntry {
+    id: string;
+    href: string;
+    label: string;
+    order: number;
+}
+export interface MountAccountExtensionsOptions {
+    guard: Middleware;
+    /** Per-account bucket for action POSTs: `[html, json]` variants (same count). */
+    throttle?: {
+        html: Middleware;
+        json: Middleware;
+    };
+    overrides?: Readonly<Record<string, AccountExtensionOverride>>;
+    builtins: Partial<Record<BuiltinNavId, string>>;
+    /** Filled in place once the routes are mounted. */
+    entries: AccountExtensionRouteEntry[];
+    /** `accountConsole.remote`: apps that serve pages for this console. */
+    remote?: readonly RemoteAccountExtensionSource[];
+    /** `accountConsole.actionTimeoutMs`. */
+    actionTimeoutMs?: number;
+}
+/**
+ * Mounts the JSON API of the extensions now, and the page routes once every provider booted
+ * (contributors register from their `boot()`; pages mount when the app starts), then freezes the
+ * registry.
+ */
+export declare function mountAccountExtensions(router: any, options: MountAccountExtensionsOptions): void;
+export {};