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

package/build/src/account/mount.js

@@ -0,0 +1,171 @@
+import { getBootedApp } from '../../services/booted_app.js';
+import { accountPathsMap, accountPrefix, joinAccountPath } from '../host/account_paths.js';
+import { AccountExtensionRegistryImpl } from './registry.js';
+import { RemoteAccountExtensions } from './remote.js';
+import { accountExtensionPages, remoteAccountPageBySegment, 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;
+}
+/** The IdP's issuer and signing keys, from the OIDC service of the booted app. */
+async function signingSource() {
+    const service = (await getBootedApp().container.make('authkit.server'));
+    return { issuer: service.config.issuer, signingJwks: service.signingJwks };
+}
+/**
+ * A route matcher that only accepts the segments remote pages currently use, so the catch-all
+ * routes never shadow another route under the account prefix.
+ */
+function liveSegmentMatcher() {
+    const matcher = /^[a-z0-9][a-z0-9-]{0,63}$/;
+    Object.defineProperty(matcher, 'test', {
+        value: (segment) => remoteAccountPageBySegment(segment) !== undefined,
+    });
+    return matcher;
+}
+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 remote = options.remote && options.remote.length > 0
+        ? new RemoteAccountExtensions(options.remote, {
+            signing: signingSource,
+            pathOf: (segment) => joinAccountPath(segment),
+            production: inProduction(),
+            ...(options.actionTimeoutMs !== undefined
+                ? { actionTimeoutMs: options.actionTimeoutMs }
+                : {}),
+        })
+        : null;
+    const pushEntries = (pages) => {
+        for (const page of pages) {
+            if (page.page.nav === false)
+                continue;
+            if (options.entries.some((entry) => entry.id === page.page.id))
+                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,
+            });
+        }
+    };
+    const mountRemote = () => {
+        if (!remote)
+            return;
+        const segment = { xsegment: { match: liveSegmentMatcher() } };
+        const page = (ctx) => remoteAccountPageBySegment(String(ctx.params.xsegment));
+        router
+            .group(() => {
+            router
+                .get(joinAccountPath(':xsegment'), async (ctx) => (await H()).showRemotePage(ctx, page(ctx)))
+                .where('xsegment', segment.xsegment);
+            router
+                .get(joinAccountPath(':xsegment/actions/:action/confirm'), async (ctx) => (await H()).showRemoteActionStep(ctx, page(ctx)))
+                .where('xsegment', segment.xsegment);
+            const post = router
+                .post(joinAccountPath(':xsegment/actions/:action'), async (ctx) => (await H()).postRemoteAction(ctx, page(ctx)))
+                .where('xsegment', segment.xsegment);
+            if (options.throttle)
+                post.use([options.throttle.html]);
+        })
+            .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,
+            remote,
+            builtinSegments: builtinSegments(),
+            ...(options.overrides ? { overrides: options.overrides } : {}),
+        });
+        mountRemote();
+        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]);
+        pushEntries(pages);
+    };
+    // Remote manifests: fetched when the app starts (bounded), refreshed in the background after.
+    const startRemote = async () => {
+        if (!remote)
+            return;
+        await remote.start();
+        pushEntries(accountExtensionPages().filter((page) => page.remote !== undefined));
+    };
+    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);
+        if (remote)
+            app.starting(startRemote);
+    }
+    else {
+        mountPages();
+        if (remote)
+            void startRemote();
+    }
+}

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

@@ -0,0 +1,41 @@
+import { AccountExtensionError, BaseAccountExtensionRegistry, validateAccountExtension } from '@adonis-agora/authkit-core';
+import type { AccountExtensionOverride, AccountPage } from './extension.js';
+export { AccountExtensionError, validateAccountExtension };
+/** A page as the console serves it, after host overrides. */
+export interface RegisteredAccountPage {
+    extensionId: string;
+    page: AccountPage;
+    segment: string;
+    order: number;
+    scriptOrigins: readonly string[];
+    /** Client id of the app serving it, for a remote page. */
+    remote?: string;
+}
+/** Thrown for an invalid extension; the message names it. */
+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 extends BaseAccountExtensionRegistry {
+    #private;
+    protected beforeRegister(extension: {
+        id?: unknown;
+    }): void;
+    get frozen(): boolean;
+    /**
+     * 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[];
+}

package/build/src/account/registry.js

@@ -0,0 +1,81 @@
+import { ACCOUNT_RESERVED_SEGMENTS, ACCOUNT_SEGMENT, AccountExtensionError, BaseAccountExtensionRegistry, failAccountExtension as fail, validateAccountExtension, } from '@adonis-agora/authkit-core';
+export { AccountExtensionError, validateAccountExtension };
+/**
+ * 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 extends BaseAccountExtensionRegistry {
+    #pages = null;
+    beforeRegister(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.`);
+        }
+    }
+    get frozen() {
+        return this.#pages !== null;
+    }
+    /**
+     * 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.registered) {
+            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 (!ACCOUNT_SEGMENT.test(segment) || ACCOUNT_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.registered.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/remote.d.ts

@@ -0,0 +1,72 @@
+import { type AccountExtension, type AccountExtensionOverride } from '@adonis-agora/authkit-core';
+import type { RegisteredAccountPage } from './registry.js';
+/**
+ * One app that signs in through this IdP and contributes account console pages
+ * (`accountConsole.remote` in `config/authkit.ts`).
+ */
+export interface RemoteAccountExtensionSource {
+    /** The app's OIDC client id: the `aud` of every token this IdP sends it. */
+    clientId: string;
+    /** Base URL the app serves `/.well-known/agora-account-extensions` under (`https://app.example.com`). */
+    url: string;
+    /** How long a fetched manifest is reused, in ms. Default 300 000 (5 min). */
+    ttlMs?: number;
+    /** Budget of one call to the app, in ms. Default 5000 (actions: `actionTimeoutMs`). */
+    timeoutMs?: number;
+}
+/** Where the IdP's issuer and signing keys come from (the OIDC service; read on every call). */
+export interface RemoteSigningSource {
+    issuer: string;
+    signingJwks: {
+        keys: Record<string, any>[];
+    };
+}
+export interface RemoteAccountExtensionsDeps {
+    signing: () => RemoteSigningSource | Promise<RemoteSigningSource>;
+    fetch?: typeof fetch;
+    now?: () => number;
+    log?: (message: string) => void;
+    /** Same-origin path of a page segment (`billing` → `/account/billing`). */
+    pathOf: (segment: string) => string;
+    actionTimeoutMs?: number;
+}
+/** Signs a remote-extension token with the IdP's current signing key. */
+export declare function signRemoteExtensionToken(signing: RemoteSigningSource, claims: {
+    audience: string;
+    subject: string;
+    bodyHash?: string;
+    ttlSec?: number;
+    now?: number;
+}): Promise<string>;
+/** Thrown when an app answers a call with an error or cannot be reached. */
+export declare class RemoteAccountExtensionError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * 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 declare class RemoteAccountExtensions {
+    #private;
+    constructor(sources: readonly RemoteAccountExtensionSource[], deps: RemoteAccountExtensionsDeps & {
+        production?: boolean;
+    });
+    get size(): number;
+    /** Fetches every manifest now; resolves when all settled or after `timeoutMs`. */
+    start(timeoutMs?: number): Promise<void>;
+    /** Every remote extension currently known (for the message catalogs). */
+    extensions(): AccountExtension[];
+    /**
+     * 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: {
+        taken: ReadonlySet<string>;
+        /** Ids of the in-process extensions. */
+        takenIds: ReadonlySet<string>;
+        overrides?: Readonly<Record<string, AccountExtensionOverride>>;
+    }): readonly RegisteredAccountPage[];
+}