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

package/build/src/account/registry.js

@@ -0,0 +1,229 @@
+import { ACCOUNT_BLOCK_KINDS, ACCOUNT_EXTENSION_CONTRACT, } from './extension.js';
+const EXTENSION_ID = /^[a-z0-9-]{2,16}$/;
+const PAGE_LOCAL_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const SEGMENT = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ACTION_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const FIELD_NAME = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+/** Segments authkit itself uses under the account prefix, whatever the host renames. */
+const RESERVED_SEGMENTS = new Set([
+    'api',
+    'login',
+    'logout',
+    'security',
+    'mfa',
+    'confirm',
+    'tokens',
+    'apps',
+    'orgs',
+    'email',
+    'x',
+    'assets',
+]);
+/** Built-in screen keys (an extension id may not shadow one). */
+const BUILTIN_IDS = new Set([
+    'login',
+    'logout',
+    'security',
+    'mfa',
+    'confirm',
+    'tokens',
+    'apps',
+    'orgs',
+    'account',
+    'authkit',
+]);
+/** Thrown for an invalid extension; the message names it. */
+export class AccountExtensionError extends Error {
+}
+function fail(id, message) {
+    throw new AccountExtensionError(`authkit: account extension "${id}" — ${message}`);
+}
+function validateAction(id, pageId, name, action) {
+    if (!ACTION_NAME.test(name))
+        fail(id, `page "${pageId}" has an invalid action name "${name}".`);
+    if (typeof action?.handle !== 'function') {
+        fail(id, `action "${pageId}.${name}" has no handle().`);
+    }
+    for (const field of action.fields ?? []) {
+        if (!FIELD_NAME.test(field?.name ?? '')) {
+            fail(id, `action "${pageId}.${name}" has an invalid field name "${String(field?.name)}".`);
+        }
+        if (!['text', 'select', 'textarea'].includes(field.kind)) {
+            fail(id, `field "${field.name}" of "${pageId}.${name}" has an unknown kind.`);
+        }
+        if (field.kind === 'select' && !(field.options && field.options.length > 0)) {
+            fail(id, `select field "${field.name}" of "${pageId}.${name}" needs options.`);
+        }
+    }
+}
+/** Validates an extension's own shape (no knowledge of the other extensions). */
+export function validateAccountExtension(extension) {
+    const id = String(extension?.id);
+    if (!EXTENSION_ID.test(id) || BUILTIN_IDS.has(id)) {
+        fail(id, 'invalid id (2–16 of a-z, 0-9, -; not a built-in screen).');
+    }
+    if (typeof extension.contract !== 'number' || !Number.isInteger(extension.contract)) {
+        fail(id, 'contract must be the major it was written against (1).');
+    }
+    if (extension.contract > ACCOUNT_EXTENSION_CONTRACT) {
+        fail(id, `written against contract ${extension.contract}; this authkit implements ${ACCOUNT_EXTENSION_CONTRACT}. Upgrade @adonis-agora/authkit-server.`);
+    }
+    for (const [locale, catalog] of Object.entries(extension.messages ?? {})) {
+        for (const key of Object.keys(catalog ?? {})) {
+            if (!key.startsWith(`${id}.`)) {
+                fail(id, `message key "${key}" (${locale}) must start with "${id}.".`);
+            }
+        }
+    }
+    for (const origin of extension.scriptOrigins ?? []) {
+        let parsed = null;
+        try {
+            parsed = new URL(origin);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed || parsed.protocol !== 'https:' || parsed.origin !== origin) {
+            fail(id, `scriptOrigins entry "${origin}" must be an https origin (no path).`);
+        }
+    }
+    if (!Array.isArray(extension.pages) || extension.pages.length === 0) {
+        fail(id, 'needs at least one page.');
+    }
+    const pageIds = new Set();
+    const segments = new Set();
+    for (const page of extension.pages) {
+        const pageId = String(page?.id);
+        const [prefix, local, ...rest] = pageId.split('.');
+        if (prefix !== id || !local || rest.length > 0 || !PAGE_LOCAL_ID.test(local)) {
+            fail(id, `page id "${pageId}" must be "${id}.<page>" (a-z, 0-9, -).`);
+        }
+        if (pageIds.has(pageId))
+            fail(id, `page "${pageId}" is listed twice.`);
+        pageIds.add(pageId);
+        if (!SEGMENT.test(String(page.segment)) || RESERVED_SEGMENTS.has(page.segment)) {
+            fail(id, `page "${pageId}" has an invalid or reserved segment "${String(page.segment)}".`);
+        }
+        if (segments.has(page.segment))
+            fail(id, `segment "${page.segment}" is used twice.`);
+        segments.add(page.segment);
+        if (typeof page.load !== 'function')
+            fail(id, `page "${pageId}" has no load().`);
+        for (const [name, action] of Object.entries(page.actions ?? {})) {
+            validateAction(id, pageId, name, action);
+        }
+    }
+}
+/**
+ * The registry bound at `authkit.accountExtensions`. Contributors call `register()` from their
+ * provider's `boot()`; authkit freezes it when it mounts the console routes.
+ */
+export class AccountExtensionRegistryImpl {
+    contract = ACCOUNT_EXTENSION_CONTRACT;
+    blockKinds = ACCOUNT_BLOCK_KINDS;
+    #extensions = [];
+    #pages = null;
+    #production;
+    #log;
+    constructor(options = {}) {
+        this.#production = options.production ?? (() => false);
+        this.#log = options.log ?? ((message) => console.error(message));
+    }
+    /** Adds an extension. Throws outside production on an invalid one; skips it in production. */
+    register(extension) {
+        if (this.#pages !== null) {
+            throw new AccountExtensionError(`authkit: account extension "${String(extension?.id)}" registered after the account console routes were mounted. Register it from your provider's boot(), not from a preload.`);
+        }
+        try {
+            validateAccountExtension(extension);
+            if (this.#extensions.some((e) => e.id === extension.id)) {
+                fail(extension.id, 'is registered twice.');
+            }
+            for (const other of this.#extensions) {
+                for (const page of extension.pages) {
+                    if (other.pages.some((p) => p.segment === page.segment)) {
+                        fail(extension.id, `segment "${page.segment}" is already used by "${other.id}".`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (!this.#production())
+                throw error;
+            this.#log(`${error.message} The extension is skipped.`);
+            return;
+        }
+        this.#extensions.push(extension);
+    }
+    get frozen() {
+        return this.#pages !== null;
+    }
+    /** The registered extensions, in registration order. */
+    extensions() {
+        return this.#extensions;
+    }
+    /**
+     * Applies the host overrides, checks the segments against the mounted screens and freezes the
+     * registry. Returns the pages to serve. Idempotent.
+     */
+    freeze(options) {
+        if (this.#pages !== null)
+            return this.#pages;
+        const log = options.log ?? this.#log;
+        const builtin = new Set(options.builtinSegments ?? []);
+        const used = new Map();
+        const out = [];
+        for (const extension of this.#extensions) {
+            const override = options.overrides?.[extension.id];
+            if (override === false)
+                continue;
+            const pages = [];
+            try {
+                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 (!SEGMENT.test(segment) || RESERVED_SEGMENTS.has(segment)) {
+                        fail(extension.id, `accountConsole.extensions renames "${page.id}" to an invalid segment "${segment}".`);
+                    }
+                    if (builtin.has(segment)) {
+                        fail(extension.id, `segment "${segment}" of "${page.id}" collides with a built-in screen.`);
+                    }
+                    const owner = used.get(segment);
+                    if (owner)
+                        fail(extension.id, `segment "${segment}" of "${page.id}" is already used by "${owner}".`);
+                    used.set(segment, page.id);
+                    const nav = page.nav === false ? undefined : page.nav;
+                    pages.push({
+                        extensionId: extension.id,
+                        page,
+                        segment,
+                        order: pageOverride?.order ?? nav?.order ?? 100,
+                        scriptOrigins: extension.scriptOrigins ?? [],
+                    });
+                }
+            }
+            catch (error) {
+                for (const page of pages)
+                    used.delete(page.segment);
+                if (!options.production)
+                    throw error;
+                log(`${error.message} The extension is skipped.`);
+                continue;
+            }
+            out.push(...pages);
+        }
+        for (const id of Object.keys(options.overrides ?? {})) {
+            if (!this.#extensions.some((e) => e.id === id)) {
+                log(`authkit: accountConsole.extensions names "${id}", which no installed package registered.`);
+            }
+        }
+        this.#pages = out;
+        return out;
+    }
+    /** The served pages (empty until frozen). */
+    pages() {
+        return this.#pages ?? [];
+    }
+}

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

@@ -0,0 +1,277 @@
+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';
+/** `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;
+}
+/** 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;
+}
+/** 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[];
+/** 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 {};