@adonis-agora/authkit-server 1.0.0-rc.8 → 1.0.0-rc.9

package/build/src/account/http.js

@@ -0,0 +1,369 @@
+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);
+}

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

@@ -0,0 +1,35 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { AccountExtensionOverride } from './extension.js';
+import { AccountExtensionRegistryImpl } from './registry.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[];
+}
+/**
+ * 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 {};

package/build/src/account/mount.js

@@ -0,0 +1,99 @@
+import { getBootedApp } from '../../services/booted_app.js';
+import { accountPathsMap, accountPrefix, joinAccountPath } from '../host/account_paths.js';
+import { AccountExtensionRegistryImpl } from './registry.js';
+import { accountExtensionPages, setAccountConsoleState } from './runtime.js';
+function inProduction() {
+    try {
+        return getBootedApp().inProduction === true;
+    }
+    catch {
+        return false;
+    }
+}
+function lifecycleApp() {
+    try {
+        return getBootedApp();
+    }
+    catch {
+        return null;
+    }
+}
+let registry = null;
+/** The process registry bound at `authkit.accountExtensions`. */
+export function accountExtensionRegistry() {
+    registry ??= new AccountExtensionRegistryImpl({ production: inProduction });
+    return registry;
+}
+/** A fresh registry (tests). */
+export function resetAccountExtensionRegistry(next) {
+    registry = next ?? null;
+}
+const H = () => import('./http.js');
+function builtinSegments() {
+    const prefix = accountPrefix() === '/' ? '' : accountPrefix();
+    return Object.values(accountPathsMap()).map((path) => (path.startsWith(`${prefix}/`) ? path.slice(prefix.length + 1) : path).split('/')[0] ?? '');
+}
+/**
+ * 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 function mountAccountExtensions(router, options) {
+    const apiBase = joinAccountPath('api');
+    const withJsonThrottle = (route) => {
+        if (options.throttle)
+            route.use([options.throttle.json]);
+        return route;
+    };
+    router
+        .group(() => {
+        router.get(`${apiBase}/extensions`, async (ctx) => (await H()).apiExtensions(ctx));
+        router.get(`${apiBase}/x/:pageId`, async (ctx) => (await H()).apiPage(ctx));
+        withJsonThrottle(router.post(`${apiBase}/x/:pageId/actions/:action`, async (ctx) => (await H()).apiAction(ctx)));
+    })
+        .use([options.guard]);
+    const mountPages = () => {
+        const reg = accountExtensionRegistry();
+        const pages = reg.freeze({
+            overrides: options.overrides,
+            builtinSegments: builtinSegments(),
+            production: inProduction(),
+        });
+        setAccountConsoleState({ pages, builtins: options.builtins, registry: reg });
+        if (pages.length === 0)
+            return;
+        router
+            .group(() => {
+            for (const page of pages) {
+                const base = joinAccountPath(page.segment);
+                router.get(base, async (ctx) => (await H()).showPage(ctx, page));
+                router.get(`${base}/actions/:action/confirm`, async (ctx) => (await H()).showActionStep(ctx, page));
+                const post = router.post(`${base}/actions/:action`, async (ctx) => (await H()).postAction(ctx, page));
+                if (options.throttle)
+                    post.use([options.throttle.html]);
+            }
+        })
+            .use([options.guard]);
+        for (const page of accountExtensionPages()) {
+            if (page.page.nav === false)
+                continue;
+            const label = page.page.nav?.label ?? page.page.title;
+            options.entries.push({
+                id: page.page.id,
+                href: joinAccountPath(page.segment),
+                label: typeof label === 'string' ? label : label.key,
+                order: page.order,
+            });
+        }
+    };
+    setAccountConsoleState({ builtins: options.builtins, registry: accountExtensionRegistry() });
+    // During the providers' boot (auto-mount from `config.routes`) contributors may not have
+    // registered yet: mount the pages when the app starts, before the preloads and the router commit.
+    const app = lifecycleApp();
+    if (app && app.isBooted === false && typeof app.starting === 'function') {
+        app.starting(mountPages);
+    }
+    else {
+        mountPages();
+    }
+}

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

@@ -0,0 +1,48 @@
+import { type AccountExtension, type AccountExtensionOverride, type AccountExtensionRegistry, type AccountPage } from './extension.js';
+/** A page as the console serves it, after host overrides. */
+export interface RegisteredAccountPage {
+    extensionId: string;
+    page: AccountPage;
+    segment: string;
+    order: number;
+    scriptOrigins: readonly string[];
+}
+/** Thrown for an invalid extension; the message names it. */
+export declare class AccountExtensionError extends Error {
+}
+/** Validates an extension's own shape (no knowledge of the other extensions). */
+export declare function validateAccountExtension(extension: AccountExtension): void;
+export interface FreezeOptions {
+    /** `accountConsole.extensions` from `config/authkit.ts`. */
+    overrides?: Readonly<Record<string, AccountExtensionOverride>>;
+    /** Segments of the mounted built-in screens (after `accountRoutes` renames). */
+    builtinSegments?: readonly string[];
+    /** `true` → an invalid extension is skipped and logged instead of thrown. */
+    production: boolean;
+    log?: (message: string) => void;
+}
+/**
+ * The registry bound at `authkit.accountExtensions`. Contributors call `register()` from their
+ * provider's `boot()`; authkit freezes it when it mounts the console routes.
+ */
+export declare class AccountExtensionRegistryImpl implements AccountExtensionRegistry {
+    #private;
+    readonly contract = 1;
+    readonly blockKinds: readonly string[];
+    constructor(options?: {
+        production?: () => boolean;
+        log?: (message: string) => void;
+    });
+    /** Adds an extension. Throws outside production on an invalid one; skips it in production. */
+    register(extension: AccountExtension): void;
+    get frozen(): boolean;
+    /** The registered extensions, in registration order. */
+    extensions(): readonly AccountExtension[];
+    /**
+     * Applies the host overrides, checks the segments against the mounted screens and freezes the
+     * registry. Returns the pages to serve. Idempotent.
+     */
+    freeze(options: FreezeOptions): RegisteredAccountPage[];
+    /** The served pages (empty until frozen). */
+    pages(): readonly RegisteredAccountPage[];
+}