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

package/build/src/account/remote.js

@@ -0,0 +1,406 @@
+import { ACCOUNT_EXTENSION_CONTRACT, ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT, ACCOUNT_EXTENSIONS_SCOPE, ACCOUNT_EXTENSIONS_TOKEN_TYP, ACCOUNT_EXTENSIONS_WELL_KNOWN, ACCOUNT_EXTENSIONS_WIRE_VERSION, ACCOUNT_RESERVED_SEGMENTS, ACCOUNT_SEGMENT, accountExtensionsBodyHash, validateAccountExtension, } from '@adonis-agora/authkit-core';
+import { importJWK, SignJWT } from 'jose';
+const SIGNING_ALGS = new Set([
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+]);
+function algOf(jwk) {
+    if (typeof jwk.alg === 'string')
+        return SIGNING_ALGS.has(jwk.alg) ? jwk.alg : null;
+    if (jwk.kty === 'RSA')
+        return 'RS256';
+    if (jwk.kty === 'EC' && jwk.crv === 'P-256')
+        return 'ES256';
+    if (jwk.kty === 'EC' && jwk.crv === 'P-384')
+        return 'ES384';
+    if (jwk.kty === 'OKP')
+        return 'EdDSA';
+    return null;
+}
+/** Signs a remote-extension token with the IdP's current signing key. */
+export async function signRemoteExtensionToken(signing, claims) {
+    const jwk = signing.signingJwks.keys.find((key) => algOf(key) !== null && key.d !== undefined);
+    if (!jwk)
+        throw new Error('authkit: no signing key can sign remote account extension tokens.');
+    const alg = algOf(jwk);
+    const key = await importJWK(jwk, alg);
+    const iat = Math.floor((claims.now ?? Date.now()) / 1000);
+    const payload = {
+        scope: ACCOUNT_EXTENSIONS_SCOPE,
+        jti: crypto.randomUUID(),
+    };
+    if (claims.bodyHash !== undefined)
+        payload.bh = claims.bodyHash;
+    return new SignJWT(payload)
+        .setProtectedHeader({
+        alg,
+        typ: ACCOUNT_EXTENSIONS_TOKEN_TYP,
+        ...(typeof jwk.kid === 'string' ? { kid: jwk.kid } : {}),
+    })
+        .setIssuer(signing.issuer)
+        .setAudience(claims.audience)
+        .setSubject(claims.subject)
+        .setIssuedAt(iat)
+        .setExpirationTime(iat + (claims.ttlSec ?? 60))
+        .sign(key);
+}
+/** Thrown when an app answers a call with an error or cannot be reached. */
+export class RemoteAccountExtensionError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'RemoteAccountExtensionError';
+    }
+}
+function baseUrl(source) {
+    return `${source.url.replace(/\/+$/, '')}${ACCOUNT_EXTENSIONS_WELL_KNOWN}`;
+}
+function validSource(source, production) {
+    if (!source || typeof source.clientId !== 'string' || source.clientId === '') {
+        return 'needs a clientId';
+    }
+    let url;
+    try {
+        url = new URL(source.url);
+    }
+    catch {
+        return `has an invalid url "${String(source.url)}"`;
+    }
+    if (url.protocol !== 'https:' && (production || url.protocol !== 'http:')) {
+        return `url "${source.url}" must be https`;
+    }
+    return null;
+}
+/**
+ * The remote account extensions of this IdP: fetches each app's manifest (cached for `ttlMs`,
+ * refreshed in the background), turns it into extensions whose `visible`, `load` and actions call
+ * the app, and serves their pages next to the in-process ones. An app that is down keeps its last
+ * manifest (its pages then show the load-failure notice) or, never reached, contributes nothing.
+ */
+export class RemoteAccountExtensions {
+    #entries;
+    #deps;
+    #visible = new WeakMap();
+    #warned = new Set();
+    #pagesKey = '';
+    #pages = [];
+    constructor(sources, deps) {
+        this.#deps = deps;
+        const seen = new Set();
+        this.#entries = [];
+        for (const source of sources) {
+            const problem = validSource(source, deps.production === true);
+            if (problem) {
+                throw new Error(`authkit: accountConsole.remote entry ${problem}.`);
+            }
+            if (seen.has(source.clientId)) {
+                throw new Error(`authkit: accountConsole.remote lists the client "${source.clientId}" twice.`);
+            }
+            seen.add(source.clientId);
+            this.#entries.push({
+                source,
+                extensions: [],
+                fetchedAt: 0,
+                version: 0,
+                inflight: null,
+                retryAt: 0,
+            });
+        }
+    }
+    get size() {
+        return this.#entries.length;
+    }
+    #now() {
+        return this.#deps.now?.() ?? Date.now();
+    }
+    #log(message) {
+        (this.#deps.log ?? ((m) => console.error(m)))(message);
+    }
+    /** Fetches every manifest now; resolves when all settled or after `timeoutMs`. */
+    async start(timeoutMs = 3000) {
+        let timer;
+        await Promise.race([
+            Promise.allSettled(this.#entries.map((entry) => this.#refresh(entry))),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+            }),
+        ]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+    /** Starts a background refresh of every stale manifest (never awaits, never throws). */
+    #refreshStale() {
+        const now = this.#now();
+        for (const entry of this.#entries) {
+            const ttl = entry.source.ttlMs ?? 300_000;
+            if (entry.inflight || now < entry.retryAt)
+                continue;
+            if (entry.fetchedAt !== 0 && now - entry.fetchedAt < ttl)
+                continue;
+            void this.#refresh(entry);
+        }
+    }
+    #refresh(entry) {
+        if (entry.inflight)
+            return entry.inflight;
+        entry.inflight = (async () => {
+            try {
+                const manifest = await this.#fetchManifest(entry.source);
+                entry.extensions = this.#toExtensions(entry.source, manifest);
+                entry.fetchedAt = this.#now();
+                entry.version += 1;
+                entry.retryAt = 0;
+            }
+            catch (error) {
+                // Keep the last good manifest; try again in 30 s.
+                entry.retryAt = this.#now() + 30_000;
+                this.#log(`authkit: remote account extensions of "${entry.source.clientId}" could not be fetched: ${error.message}`);
+            }
+            finally {
+                entry.inflight = null;
+            }
+        })();
+        return entry.inflight;
+    }
+    async #request(source, init) {
+        const signing = await this.#deps.signing();
+        const token = await signRemoteExtensionToken(signing, {
+            audience: source.clientId,
+            subject: init.subject,
+            ...(init.body !== undefined ? { bodyHash: accountExtensionsBodyHash(init.body) } : {}),
+            now: this.#now(),
+        });
+        const doFetch = this.#deps.fetch ?? fetch;
+        const response = await doFetch(baseUrl(source), {
+            method: init.body === undefined ? 'GET' : 'POST',
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'application/json',
+                ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(init.body !== undefined ? { body: init.body } : {}),
+            redirect: 'error',
+            signal: AbortSignal.timeout(init.timeoutMs),
+        });
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            const message = typeof payload?.error?.message === 'string'
+                ? payload.error.message
+                : `HTTP ${response.status}`;
+            throw new RemoteAccountExtensionError(message, response.status);
+        }
+        return payload;
+    }
+    async #fetchManifest(source) {
+        const payload = (await this.#request(source, {
+            subject: ACCOUNT_EXTENSIONS_MANIFEST_SUBJECT,
+            timeoutMs: source.timeoutMs ?? 5000,
+        }));
+        if (!payload ||
+            payload.version !== ACCOUNT_EXTENSIONS_WIRE_VERSION ||
+            !Array.isArray(payload.extensions)) {
+            throw new Error('the manifest is not a version 1 account extensions manifest');
+        }
+        return payload;
+    }
+    /** Builds proxy extensions from a manifest; an invalid extension is skipped and logged. */
+    #toExtensions(source, manifest) {
+        const out = [];
+        for (const remote of manifest.extensions) {
+            const extension = {
+                id: remote?.id,
+                contract: Math.min(remote?.contract ?? 1, ACCOUNT_EXTENSION_CONTRACT),
+                messages: remote?.messages ?? {},
+                scriptOrigins: Array.isArray(remote?.scriptOrigins) ? remote.scriptOrigins : [],
+                pages: (Array.isArray(remote?.pages) ? remote.pages : []).map((page) => this.#toPage(source, page)),
+            };
+            try {
+                if (typeof remote?.contract === 'number' && remote.contract > ACCOUNT_EXTENSION_CONTRACT) {
+                    throw new Error(`"${remote.id}" was written against contract ${remote.contract}; this authkit implements ${ACCOUNT_EXTENSION_CONTRACT}.`);
+                }
+                validateAccountExtension(extension);
+                out.push(extension);
+            }
+            catch (error) {
+                this.#log(`authkit: remote account extension from "${source.clientId}" skipped: ${error.message}`);
+            }
+        }
+        return out;
+    }
+    #call(source, call, timeoutMs) {
+        const body = JSON.stringify(call);
+        return this.#request(source, { subject: call.account.id, body, timeoutMs });
+    }
+    #base(source, ctx) {
+        const urls = {};
+        for (const page of this.#pages) {
+            if (page.remote === source.clientId)
+                urls[page.page.id] = this.#deps.pathOf(page.segment);
+        }
+        return {
+            account: {
+                id: ctx.account.id,
+                email: ctx.account.email,
+                name: ctx.account.name,
+                roles: [...ctx.account.roles],
+            },
+            activeOrg: ctx.activeOrg,
+            tenant: ctx.tenant ?? null,
+            impersonatedBy: ctx.impersonatedBy,
+            locale: ctx.locale,
+            urls,
+        };
+    }
+    /** The visible conditional pages of `source` for this account, once per request. */
+    #visibleSet(source, ctx) {
+        const key = ctx.account;
+        let perRequest = this.#visible.get(key);
+        if (!perRequest) {
+            perRequest = new Map();
+            this.#visible.set(key, perRequest);
+        }
+        let decided = perRequest.get(source.clientId);
+        if (!decided) {
+            const pageIds = this.#pages
+                .filter((page) => page.remote === source.clientId && page.page.visible)
+                .map((page) => page.page.id);
+            decided = (async () => {
+                try {
+                    const payload = (await this.#call(source, { ...this.#base(source, ctx), op: 'visible', pageIds }, source.timeoutMs ?? 5000));
+                    return new Set(Array.isArray(payload?.visible)
+                        ? payload.visible.filter((id) => typeof id === 'string')
+                        : []);
+                }
+                catch (error) {
+                    // The app cannot answer: keep its pages listed, so each shows the "could not be
+                    // loaded" notice instead of vanishing (a page body never loads without the app).
+                    this.#log(`authkit: remote account extensions of "${source.clientId}" did not answer visible(): ${error.message}`);
+                    return new Set(pageIds);
+                }
+            })();
+            perRequest.set(source.clientId, decided);
+        }
+        return decided;
+    }
+    #toPage(source, remote) {
+        const pageId = String(remote?.id);
+        const actions = {};
+        for (const [name, action] of Object.entries((remote?.actions ?? {}))) {
+            actions[name] = {
+                label: action?.label ?? name,
+                tone: action?.tone === 'danger' ? 'danger' : 'default',
+                ...(action?.confirm ? { confirm: action.confirm } : {}),
+                sudo: action?.sudo === true,
+                fields: Array.isArray(action?.fields) ? action.fields : [],
+                handle: async (ctx, input) => {
+                    const payload = (await this.#call(source, {
+                        ...this.#base(source, ctx),
+                        op: 'action',
+                        pageId,
+                        action: name,
+                        query: ctx.query,
+                        input,
+                    }, this.#deps.actionTimeoutMs ?? 15_000));
+                    if (!payload?.result || typeof payload.result.ok !== 'boolean') {
+                        throw new Error('the app answered the action without a result');
+                    }
+                    return payload.result;
+                },
+            };
+        }
+        return {
+            id: pageId,
+            segment: String(remote?.segment),
+            title: remote?.title ?? pageId,
+            nav: remote?.nav === false ? false : (remote?.nav ?? {}),
+            ...(remote?.conditional === true
+                ? {
+                    visible: async (ctx) => (await this.#visibleSet(source, ctx)).has(pageId),
+                }
+                : {}),
+            load: async (ctx) => {
+                const payload = (await this.#call(source, { ...this.#base(source, ctx), op: 'load', pageId, query: ctx.query }, source.timeoutMs ?? 5000));
+                if (!payload?.view || !Array.isArray(payload.view.blocks)) {
+                    throw new Error('the app answered the page without a view');
+                }
+                return payload.view;
+            },
+            actions,
+        };
+    }
+    /** Every remote extension currently known (for the message catalogs). */
+    extensions() {
+        return this.#entries.flatMap((entry) => entry.extensions);
+    }
+    /**
+     * The remote pages to serve now, after host overrides, minus any whose segment collides with a
+     * built-in screen, an in-process page or an earlier app (skipped and logged once).
+     */
+    pages(context) {
+        this.#refreshStale();
+        const key = this.#entries.map((e) => e.version).join(',');
+        if (key === this.#pagesKey)
+            return this.#pages;
+        const used = new Set(context.taken);
+        const usedIds = new Set(context.takenIds);
+        const out = [];
+        for (const entry of this.#entries) {
+            for (const extension of entry.extensions) {
+                const override = context.overrides?.[extension.id];
+                if (override === false)
+                    continue;
+                if (usedIds.has(extension.id)) {
+                    this.#warnOnce(`${entry.source.clientId}:${extension.id}`, `authkit: remote account extension "${extension.id}" from "${entry.source.clientId}" is skipped: the id is already used.`);
+                    continue;
+                }
+                usedIds.add(extension.id);
+                for (const page of extension.pages) {
+                    const pageOverride = override ? override.pages?.[page.id] : undefined;
+                    if (pageOverride === false)
+                        continue;
+                    const segment = pageOverride?.segment ?? page.segment;
+                    if (!ACCOUNT_SEGMENT.test(segment) ||
+                        ACCOUNT_RESERVED_SEGMENTS.has(segment) ||
+                        used.has(segment)) {
+                        this.#warnOnce(`${entry.source.clientId}:${page.id}:${segment}`, `authkit: remote account page "${page.id}" from "${entry.source.clientId}" is skipped: the segment "${segment}" is reserved or already used.`);
+                        continue;
+                    }
+                    used.add(segment);
+                    const nav = page.nav === false ? undefined : page.nav;
+                    out.push({
+                        extensionId: extension.id,
+                        page,
+                        segment,
+                        order: pageOverride?.order ?? nav?.order ?? 100,
+                        scriptOrigins: extension.scriptOrigins ?? [],
+                        remote: entry.source.clientId,
+                    });
+                }
+            }
+        }
+        this.#pagesKey = key;
+        this.#pages = out;
+        return out;
+    }
+    #warnOnce(key, message) {
+        if (this.#warned.has(key))
+            return;
+        this.#warned.add(key);
+        this.#log(message);
+    }
+}

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

@@ -0,0 +1,289 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { AccountActiveOrg, AccountExtensionContext, AccountExtensionOverride, AccountPageView, AccountSubject, AccountTenantRef, ActionRef, Block, Text, Value } from './extension.js';
+import type { AccountExtensionRegistryImpl, RegisteredAccountPage } from './registry.js';
+import type { RemoteAccountExtensionSource, RemoteAccountExtensions } from './remote.js';
+/** `accountConsole` in `config/authkit.ts`. */
+export interface AccountConsoleConfig {
+    /**
+     * Maps the signed-in account to the app's subject (what billing, media and agents key on).
+     * Default `{ type: 'User', id: account.id }`. Every extension receives it as `ctx.subject`.
+     */
+    subject?: (account: {
+        id: string;
+        email: string | null;
+        name: string | null;
+        roles: readonly string[];
+    }, context: {
+        activeOrg: AccountActiveOrg | null;
+        tenant: AccountTenantRef | null;
+    }) => AccountSubject | Promise<AccountSubject>;
+    /** Turn off, rename or reorder extension pages, by extension id. */
+    extensions?: Record<string, AccountExtensionOverride>;
+    /** Budget of one page's `load()`, in ms. Default 5000. */
+    loadTimeoutMs?: number;
+    /** Budget of one action's `handle()`, in ms. Default 15000. */
+    actionTimeoutMs?: number;
+    /**
+     * Apps that sign in through this IdP and serve their own pages (billing, files…) for this
+     * console. Each must turn on `accountConsole.remote` in its `config/authkit_client.ts`.
+     */
+    remote?: RemoteAccountExtensionSource[];
+}
+/** Built-in screens in the navigation, with their fixed order. */
+export declare const BUILTIN_NAV: readonly [{
+    readonly id: 'security';
+    readonly order: 10;
+    readonly label: 'account.security.title';
+}, {
+    readonly id: 'mfa';
+    readonly order: 20;
+    readonly label: 'account.mfa.title';
+}, {
+    readonly id: 'tokens';
+    readonly order: 30;
+    readonly label: 'account.tokens.title';
+}, {
+    readonly id: 'apps';
+    readonly order: 40;
+    readonly label: 'account.apps.title';
+}, {
+    readonly id: 'orgs';
+    readonly order: 50;
+    readonly label: 'account.orgs.title';
+}];
+export type BuiltinNavId = (typeof BUILTIN_NAV)[number]['id'];
+interface ConsoleState {
+    pages: readonly RegisteredAccountPage[];
+    builtins: Partial<Record<BuiltinNavId, string>>;
+    registry: AccountExtensionRegistryImpl | null;
+    remote: RemoteAccountExtensions | null;
+    /** Segments of the mounted built-in screens. */
+    builtinSegments: readonly string[];
+    overrides?: Readonly<Record<string, AccountExtensionOverride>>;
+}
+/** Called by `registerAuthHost` with the mounted screens and the frozen pages. */
+export declare function setAccountConsoleState(next: Partial<ConsoleState>): void;
+/** The served extension pages. */
+export declare function accountExtensionPages(): readonly RegisteredAccountPage[];
+/** The remote pages currently served (for the catch-all routes). */
+export declare function remoteAccountPageBySegment(segment: string): RegisteredAccountPage | undefined;
+/** Resets the process state (tests). */
+export declare function resetAccountConsoleState(): void;
+export declare function findPageById(pageId: string): RegisteredAccountPage | undefined;
+export declare function findPageBySegment(segment: string): RegisteredAccountPage | undefined;
+/** Same-origin path of an extension page. */
+export declare function pageHref(page: RegisteredAccountPage, query?: Record<string, string>): string;
+/** Looks up a message: host catalog (overrides win), then the extension's own catalogs. */
+export declare function makeTranslator(hostMessages: Record<string, string>, locale: string, catalogs: readonly (Readonly<Record<string, Readonly<Record<string, string>>>> | undefined)[]): (text: Text | undefined | null) => string;
+/** A value ready to show: `text` is formatted for the locale. */
+export interface ResolvedValue {
+    type: Value['type'];
+    text: string;
+    tone?: 'neutral' | 'success' | 'warning' | 'danger';
+    /** ISO timestamp of a date value. */
+    iso?: string;
+    amount?: number;
+    currency?: string;
+    value?: number;
+}
+export declare function formatValue(value: Value, t: (text: Text | undefined) => string, locale: string, now: Date): ResolvedValue;
+/**
+ * A safe href: an https URL when `external`, else a same-origin path (`/…`, never `//…` nor
+ * `/\…`). Anything else (`javascript:`, `data:`, protocol-relative) is `null`.
+ */
+export declare function safeHref(href: unknown, external?: boolean): string | null;
+/** A script `src` a component block may load: same-origin, or https on an allowed origin. */
+export declare function safeScriptSrc(src: unknown, origins: readonly string[]): string | null;
+/** A button for an {@link ActionRef}. */
+export interface ResolvedAction {
+    action: string;
+    target: string | null;
+    label: string;
+    tone: 'default' | 'danger';
+    sudo: boolean;
+    /** `confirm` or `fields`: the button opens the confirmation step (`href`, GET). */
+    step: boolean;
+    /** POST target (no step) or the confirmation step (step). */
+    href: string;
+    /** Always the POST target of the action (forms that collect the fields themselves). */
+    postHref: string;
+    /** JSON endpoint for this action. */
+    apiHref: string;
+}
+export type ResolvedBlock = {
+    kind: 'notice';
+    tone: 'info' | 'success' | 'warning' | 'danger';
+    text: string;
+} | {
+    kind: 'keyValue';
+    title: string | null;
+    rows: Array<{
+        label: string;
+        value: ResolvedValue;
+    }>;
+    actions: ResolvedAction[];
+} | {
+    kind: 'list';
+    title: string | null;
+    empty: string;
+    items: Array<{
+        title: string;
+        subtitle: string | null;
+        meta: ResolvedValue[];
+        badge: ResolvedValue | null;
+        href: string | null;
+        external: boolean;
+        actions: ResolvedAction[];
+    }>;
+    nextHref: string | null;
+    nextCursor: string | null;
+} | {
+    kind: 'table';
+    title: string | null;
+    empty: string;
+    columns: Array<{
+        id: string;
+        label: string;
+    }>;
+    rows: Array<{
+        cells: ResolvedValue[];
+        actions: ResolvedAction[];
+    }>;
+    hasActions: boolean;
+    nextHref: string | null;
+    nextCursor: string | null;
+} | {
+    kind: 'meter';
+    label: string;
+    used: number;
+    limit: number | null;
+    percent: number | null;
+    text: string;
+    resetsAt: ResolvedValue | null;
+} | {
+    kind: 'actions';
+    items: ResolvedAction[];
+} | {
+    kind: 'link';
+    label: string;
+    href: string;
+    external: boolean;
+} | {
+    kind: 'toolPreview';
+    title: string;
+    tool: string | null;
+    subtitle: string | null;
+    args: Array<{
+        label: string;
+        value: ResolvedValue;
+    }>;
+    body: {
+        format: 'json' | 'text';
+        content: string;
+    } | null;
+    actions: ResolvedAction[];
+} | {
+    kind: 'component';
+    provider: string;
+    mountId: string;
+    scripts: Array<{
+        src: string;
+        integrity: string | null;
+        module: boolean;
+    }>;
+    /** The props, serialized for a `<script type="application/json">` (`<` escaped). */
+    propsJson: string;
+    props: Record<string, unknown>;
+    submit: ResolvedAction | null;
+    fallback: {
+        label: string;
+        href: string;
+        external: boolean;
+    } | null;
+};
+export interface ResolvedAccountPage {
+    id: string;
+    extension: string;
+    title: string;
+    href: string;
+    tabs: Array<{
+        id: string;
+        label: string;
+        href: string;
+        active: boolean;
+    }>;
+    blocks: ResolvedBlock[];
+}
+/** JSON for a `<script type="application/json">`: never closes the tag, never runs. */
+export declare function jsonForDataBlock(value: unknown): string;
+export interface ResolveInput {
+    page: RegisteredAccountPage;
+    view: AccountPageView;
+    t: (text: Text | undefined | null) => string;
+    locale: string;
+    now: Date;
+    query: {
+        cursor?: string;
+        tab?: string;
+    };
+}
+/** The button for `ref`, or `null` when the page has no such action. */
+export declare function resolveAction(page: RegisteredAccountPage, ref: ActionRef, t: (text: Text | undefined | null) => string): ResolvedAction | null;
+/** Resolves one block; an unknown or malformed block becomes a warning notice. */
+export declare function resolveBlock(input: ResolveInput, block: Block): ResolvedBlock;
+export declare function resolvePageView(input: ResolveInput): ResolvedAccountPage;
+export interface ConsoleRequest {
+    /** The base context (no `query`); each page call gets its own. */
+    base: Omit<AccountExtensionContext, 'query'>;
+    hostMessages: Record<string, string>;
+    locale: string;
+    config: AccountConsoleConfig;
+    cfg: any;
+    /** Memoized `visible()` per page id. */
+    visible: Map<string, Promise<boolean>>;
+}
+/** The console context of this request, built once. `null` without a signed-in account. */
+export declare function consoleRequest(ctx: HttpContext): Promise<ConsoleRequest | null>;
+/** Validated query: `cursor` and `tab` only. */
+export declare function validatedQuery(raw: Record<string, unknown>): {
+    cursor?: string;
+    tab?: string;
+};
+export declare function extensionContext(request: ConsoleRequest, query: {
+    cursor?: string;
+    tab?: string;
+}): AccountExtensionContext;
+/** The translator for one page (its extension's catalogs). */
+export declare function translatorFor(request: ConsoleRequest, page: RegisteredAccountPage | null): (text: Text | undefined | null) => string;
+/** `page.visible(ctx)`, once per request; a throw hides the page. */
+export declare function isPageVisible(request: ConsoleRequest, page: RegisteredAccountPage): Promise<boolean>;
+export declare function logExtensionError(page: RegisteredAccountPage, where: string, error: unknown): void;
+/** Runs `fn` with a time budget. */
+export declare function withTimeout<T>(work: Promise<T>, ms: number, what: string): Promise<T>;
+/** Loads and resolves a page; a throw or timeout becomes a danger notice. */
+export declare function loadResolvedPage(request: ConsoleRequest, page: RegisteredAccountPage, query: {
+    cursor?: string;
+    tab?: string;
+}): Promise<ResolvedAccountPage>;
+/** One navigation entry of the account console. */
+export interface AccountNavEntry {
+    id: string;
+    label: string;
+    href: string;
+    active: boolean;
+    group: 'account' | 'billing' | 'ai' | 'content';
+    order: number;
+}
+/** Mounted built-in screens (id → path). */
+export declare function mountedBuiltins(): Partial<Record<BuiltinNavId, string>>;
+/**
+ * The account console navigation: mounted built-in screens plus the extension pages visible to
+ * this account, sorted by `(group, order, id)`.
+ */
+export declare function buildAccountNav(ctx: HttpContext, activeId: string | null): Promise<AccountNavEntry[]>;
+/**
+ * The `accountNav` prop of an account screen (`null` for other views). Never throws: a broken
+ * extension leaves the built-in entries.
+ */
+export declare function accountNavFor(ctx: HttpContext, view: string, props: Record<string, unknown>): Promise<AccountNavEntry[] | null>;
+export {};