@portaidentity/server 1.7.0

package/dist/auth/recovery-worker.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Bounded lifecycle owner for durable account-recovery jobs.
+ *
+ * The worker has a single claim loop, processes one claimed batch sequentially, and never permits
+ * overlapping polls. Repository ownership checks fence every transition. Product-specific token
+ * and mail work is injected through a processor so the scheduler can be tested without coupling
+ * its concurrency rules to route or template implementation.
+ */
+import { type BeginRecoveryJobAttemptInput, type ClaimRecoveryJobsInput, type ClaimedRecoveryJob, type FinishRecoveryJobInput, type RecoveryJob, type RetryRecoveryJobInput } from './recovery-job-repository.js';
+/** Poll interval used when no enqueue wake-up arrives. */
+export declare const RECOVERY_WORKER_POLL_MILLISECONDS = 1000;
+/** Lease age after which another worker may recover a crashed claim. */
+export declare const RECOVERY_WORKER_LEASE_MILLISECONDS = 300000;
+/** Maximum graceful-shutdown wait for the active worker cycle. */
+export declare const RECOVERY_WORKER_SHUTDOWN_MILLISECONDS = 30000;
+/** Four delays between the five permitted processing attempts. */
+export declare const RECOVERY_WORKER_RETRY_DELAYS_MILLISECONDS: readonly [1000, 10000, 60000, 300000];
+/** Closed privacy-safe worker failure reasons. */
+export declare const RECOVERY_WORKER_FAILURE_REASONS: readonly ['database_unavailable', 'smtp_unavailable', 'smtp_outcome_unknown', 'invalid_protected_input', 'template_unavailable', 'lease_exhausted', 'processing_failed'];
+/** Privacy-safe reason accepted by recovery retry and terminal transitions. */
+export type RecoveryWorkerFailureReason = (typeof RECOVERY_WORKER_FAILURE_REASONS)[number];
+/** Durable transitions required by the worker scheduler. */
+export interface RecoveryWorkerRepository {
+    /** Atomically claim one bounded available or expired-lease batch. */
+    claimAvailable(input: ClaimRecoveryJobsInput): Promise<readonly ClaimedRecoveryJob[]>;
+    /** Charge one attempt immediately before account-specific processing begins. */
+    beginAttempt(input: BeginRecoveryJobAttemptInput): Promise<RecoveryJob | null>;
+    /** Return an owned transient failure to the queue. */
+    scheduleRetry(input: RetryRecoveryJobInput): Promise<boolean>;
+    /** Complete an owned claim. */
+    markCompleted(input: FinishRecoveryJobInput): Promise<boolean>;
+    /** Terminally close an owned claim. */
+    markTerminalFailure(input: FinishRecoveryJobInput): Promise<boolean>;
+}
+/** Result returned by account-specific recovery processing. */
+export type RecoveryJobProcessingResult = 'completed' | 'no_op';
+/** Product-specific processor invoked only after a durable claim succeeds. */
+export interface RecoveryJobProcessor {
+    /**
+     * Process one claimed job.
+     *
+     * @param job - Owner-fenced durable claim.
+     * @returns Whether the job produced an intended effect or completed as a private no-op.
+     */
+    process(job: ClaimedRecoveryJob): Promise<RecoveryJobProcessingResult>;
+}
+/** Clock/timer boundary used for deterministic worker tests. */
+export interface RecoveryWorkerClock {
+    /** Read the repository clock. */
+    now(): Date;
+    /** Schedule a callback after a bounded delay. */
+    setTimeout(callback: () => void, milliseconds: number): ReturnType<typeof setTimeout>;
+    /** Cancel a previously scheduled callback. */
+    clearTimeout(timer: ReturnType<typeof setTimeout>): void;
+}
+/** Privacy-safe lifecycle event exposed to owned test and metrics observers. */
+export interface RecoveryWorkerEvent {
+    /** Closed event category. */
+    readonly event: 'claimed' | 'completed' | 'no_op' | 'retry_scheduled' | 'lease_reclaimed' | 'terminal_failure' | 'shutdown_started' | 'shutdown_settled' | 'shutdown_timeout';
+    /** Job identity for an in-process observer; the default logger never emits it. */
+    readonly jobId?: string;
+    /** Processing attempt when applicable. */
+    readonly attempt?: number;
+    /** Retry delay when applicable. */
+    readonly delayMilliseconds?: number;
+    /** Closed failure reason when applicable. */
+    readonly reason?: RecoveryWorkerFailureReason;
+}
+/** Optional observer for metrics and implementation tests. */
+export type RecoveryWorkerObserver = (event: RecoveryWorkerEvent) => void;
+/** Construction dependencies for a recovery worker. */
+export interface RecoveryWorkerOptions {
+    /** Durable repository used for every ownership transition. */
+    readonly repository: RecoveryWorkerRepository;
+    /** Account-specific processor. */
+    readonly processor: RecoveryJobProcessor;
+    /** Stable worker-process UUID; defaults to a fresh UUID. */
+    readonly workerId?: string;
+    /** Deterministic clock/timer boundary. */
+    readonly clock?: RecoveryWorkerClock;
+    /** Optional in-process event observer. */
+    readonly observer?: RecoveryWorkerObserver;
+}
+/** Typed processing failure with a closed public reason and retry policy. */
+export declare class RecoveryJobProcessingError extends Error {
+    /** Closed privacy-safe reason. */
+    readonly reason: RecoveryWorkerFailureReason;
+    /** Whether another bounded attempt may succeed. */
+    readonly retryable: boolean;
+    /**
+     * Create a worker-visible processing failure.
+     *
+     * @param reason - Closed privacy-safe failure reason.
+     * @param retryable - Whether the job may be rescheduled below the attempt limit.
+     */
+    constructor(reason: RecoveryWorkerFailureReason, retryable: boolean);
+}
+/**
+ * Create a bounded recovery worker.
+ *
+ * @param options - Repository, processor, and optional deterministic boundaries.
+ * @returns Stopped worker ready for explicit lifecycle ownership.
+ */
+export declare function createRecoveryWorker(options: RecoveryWorkerOptions): RecoveryWorker;
+/** Single-flight scheduler for durable recovery work. */
+export declare class RecoveryWorker {
+    /** Durable transition repository. */
+    protected readonly repository: RecoveryWorkerRepository;
+    /** Account-specific processing boundary. */
+    protected readonly processor: RecoveryJobProcessor;
+    /** Stable owner identity persisted with every claim. */
+    protected readonly workerId: string;
+    /** Clock and timer owner. */
+    protected readonly clock: RecoveryWorkerClock;
+    /** Optional metrics/test observer. */
+    protected readonly observer?: RecoveryWorkerObserver;
+    /** Whether the worker accepts polls and enqueue wake-ups. */
+    protected running: boolean;
+    /** Scheduled next poll, if any. */
+    protected timer: ReturnType<typeof setTimeout> | null;
+    /** Current single-flight claim/process cycle. */
+    protected activeCycle: Promise<void> | null;
+    /** Wake-up received while a cycle was already active. */
+    protected wakePending: boolean;
+    /**
+     * Create a stopped worker.
+     *
+     * @param options - Required and optional lifecycle boundaries.
+     */
+    constructor(options: RecoveryWorkerOptions);
+    /** Start polling immediately. Repeated calls are idempotent. */
+    start(): void;
+    /** Wake the worker after a successful enqueue without creating an overlapping cycle. */
+    wake(): void;
+    /**
+     * Stop claiming and wait a bounded time for the active cycle.
+     *
+     * @returns True when active work settled before the shutdown deadline.
+     */
+    stop(): Promise<boolean>;
+    /** Schedule the next single-flight cycle. */
+    protected schedule(milliseconds: number): void;
+    /** Cancel the owned next-poll timer. */
+    protected clearScheduledPoll(): void;
+    /** Begin one cycle or record a pending wake when another cycle owns execution. */
+    protected beginCycle(): void;
+    /** Claim and process one bounded batch. */
+    protected runCycle(): Promise<void>;
+    /** Process one claim and finish, retry, or terminally close it. */
+    protected processClaim(job: ClaimedRecoveryJob): Promise<void>;
+    /** Reschedule an owned transient failure with its exact attempt delay. */
+    protected retry(job: ClaimedRecoveryJob, reason: RecoveryWorkerFailureReason): Promise<void>;
+    /** Terminally close an owned claim without exposing raw failure data. */
+    protected finishTerminal(job: ClaimedRecoveryJob, reason: RecoveryWorkerFailureReason): Promise<void>;
+    /** Notify the optional in-process observer without letting it break processing. */
+    protected emit(event: RecoveryWorkerEvent): void;
+}
+//# sourceMappingURL=recovery-worker.d.ts.map

package/dist/auth/recovery-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-worker.d.ts","sourceRoot":"","sources":["../../src/auth/recovery-worker.ts"],"names":[],"mappings":"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"}

package/dist/auth/recovery-worker.js

@@ -0,0 +1,306 @@
+/**
+ * Bounded lifecycle owner for durable account-recovery jobs.
+ *
+ * The worker has a single claim loop, processes one claimed batch sequentially, and never permits
+ * overlapping polls. Repository ownership checks fence every transition. Product-specific token
+ * and mail work is injected through a processor so the scheduler can be tested without coupling
+ * its concurrency rules to route or template implementation.
+ */
+import { randomUUID } from 'node:crypto';
+import { logger } from '../lib/logger.js';
+import { RECOVERY_JOB_ATTEMPT_LIMIT, RECOVERY_JOB_CLAIM_LIMIT, } from './recovery-job-repository.js';
+/** Poll interval used when no enqueue wake-up arrives. */
+export const RECOVERY_WORKER_POLL_MILLISECONDS = 1_000;
+/** Lease age after which another worker may recover a crashed claim. */
+export const RECOVERY_WORKER_LEASE_MILLISECONDS = 300_000;
+/** Maximum graceful-shutdown wait for the active worker cycle. */
+export const RECOVERY_WORKER_SHUTDOWN_MILLISECONDS = 30_000;
+/** Four delays between the five permitted processing attempts. */
+export const RECOVERY_WORKER_RETRY_DELAYS_MILLISECONDS = [1_000, 10_000, 60_000, 300_000];
+/** Closed privacy-safe worker failure reasons. */
+export const RECOVERY_WORKER_FAILURE_REASONS = [
+    'database_unavailable',
+    'smtp_unavailable',
+    'smtp_outcome_unknown',
+    'invalid_protected_input',
+    'template_unavailable',
+    'lease_exhausted',
+    'processing_failed',
+];
+/** Typed processing failure with a closed public reason and retry policy. */
+export class RecoveryJobProcessingError extends Error {
+    /** Closed privacy-safe reason. */
+    reason;
+    /** Whether another bounded attempt may succeed. */
+    retryable;
+    /**
+     * Create a worker-visible processing failure.
+     *
+     * @param reason - Closed privacy-safe failure reason.
+     * @param retryable - Whether the job may be rescheduled below the attempt limit.
+     */
+    constructor(reason, retryable) {
+        super(reason);
+        this.name = 'RecoveryJobProcessingError';
+        this.reason = reason;
+        this.retryable = retryable;
+    }
+}
+const systemClock = {
+    now: () => new Date(),
+    setTimeout: (callback, milliseconds) => setTimeout(callback, milliseconds),
+    clearTimeout: (timer) => clearTimeout(timer),
+};
+/**
+ * Create a bounded recovery worker.
+ *
+ * @param options - Repository, processor, and optional deterministic boundaries.
+ * @returns Stopped worker ready for explicit lifecycle ownership.
+ */
+export function createRecoveryWorker(options) {
+    return new RecoveryWorker(options);
+}
+/** Single-flight scheduler for durable recovery work. */
+export class RecoveryWorker {
+    /** Durable transition repository. */
+    repository;
+    /** Account-specific processing boundary. */
+    processor;
+    /** Stable owner identity persisted with every claim. */
+    workerId;
+    /** Clock and timer owner. */
+    clock;
+    /** Optional metrics/test observer. */
+    observer;
+    /** Whether the worker accepts polls and enqueue wake-ups. */
+    running = false;
+    /** Scheduled next poll, if any. */
+    timer = null;
+    /** Current single-flight claim/process cycle. */
+    activeCycle = null;
+    /** Wake-up received while a cycle was already active. */
+    wakePending = false;
+    /**
+     * Create a stopped worker.
+     *
+     * @param options - Required and optional lifecycle boundaries.
+     */
+    constructor(options) {
+        this.repository = options.repository;
+        this.processor = options.processor;
+        this.workerId = options.workerId ?? randomUUID();
+        this.clock = options.clock ?? systemClock;
+        this.observer = options.observer;
+    }
+    /** Start polling immediately. Repeated calls are idempotent. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule(0);
+    }
+    /** Wake the worker after a successful enqueue without creating an overlapping cycle. */
+    wake() {
+        if (!this.running)
+            return;
+        if (this.activeCycle) {
+            this.wakePending = true;
+            return;
+        }
+        this.schedule(0);
+    }
+    /**
+     * Stop claiming and wait a bounded time for the active cycle.
+     *
+     * @returns True when active work settled before the shutdown deadline.
+     */
+    async stop() {
+        if (!this.running && !this.activeCycle)
+            return true;
+        this.running = false;
+        this.wakePending = false;
+        this.clearScheduledPoll();
+        this.emit({ event: 'shutdown_started' });
+        const active = this.activeCycle;
+        if (!active) {
+            this.emit({ event: 'shutdown_settled' });
+            return true;
+        }
+        let timeout = null;
+        const settled = await Promise.race([
+            active.then(() => true),
+            new Promise((resolve) => {
+                timeout = this.clock.setTimeout(() => resolve(false), RECOVERY_WORKER_SHUTDOWN_MILLISECONDS);
+            }),
+        ]);
+        if (timeout)
+            this.clock.clearTimeout(timeout);
+        this.emit({ event: settled ? 'shutdown_settled' : 'shutdown_timeout' });
+        return settled;
+    }
+    /** Schedule the next single-flight cycle. */
+    schedule(milliseconds) {
+        if (!this.running)
+            return;
+        this.clearScheduledPoll();
+        this.timer = this.clock.setTimeout(() => {
+            this.timer = null;
+            this.beginCycle();
+        }, milliseconds);
+    }
+    /** Cancel the owned next-poll timer. */
+    clearScheduledPoll() {
+        if (!this.timer)
+            return;
+        this.clock.clearTimeout(this.timer);
+        this.timer = null;
+    }
+    /** Begin one cycle or record a pending wake when another cycle owns execution. */
+    beginCycle() {
+        if (!this.running)
+            return;
+        if (this.activeCycle) {
+            this.wakePending = true;
+            return;
+        }
+        const cycle = this.runCycle();
+        this.activeCycle = cycle;
+        void cycle
+            .catch(() => {
+            logger.error({ event: 'recovery_worker_cycle_failed' }, 'Recovery worker cycle failed');
+        })
+            .finally(() => {
+            if (this.activeCycle === cycle)
+                this.activeCycle = null;
+            if (!this.running)
+                return;
+            const runImmediately = this.wakePending;
+            this.wakePending = false;
+            this.schedule(runImmediately ? 0 : RECOVERY_WORKER_POLL_MILLISECONDS);
+        });
+    }
+    /** Claim and process one bounded batch. */
+    async runCycle() {
+        const now = this.clock.now();
+        const jobs = await this.repository.claimAvailable({
+            workerId: this.workerId,
+            now,
+            leaseExpiredBefore: new Date(now.getTime() - RECOVERY_WORKER_LEASE_MILLISECONDS),
+            limit: RECOVERY_JOB_CLAIM_LIMIT,
+        });
+        for (const job of jobs) {
+            if (job.claimDisposition === 'lease_exhausted') {
+                this.emit({ event: 'claimed', jobId: job.id, attempt: job.attemptCount });
+                await this.finishTerminal(job, 'lease_exhausted');
+                continue;
+            }
+            const started = await this.repository.beginAttempt({
+                jobId: job.id,
+                workerId: this.workerId,
+                now: this.clock.now(),
+            });
+            if (!started) {
+                logger.warn({ event: 'recovery_worker_claim_lost' }, 'Recovery worker claim was lost');
+                continue;
+            }
+            const startedClaim = {
+                ...started,
+                claimDisposition: job.claimDisposition,
+            };
+            this.emit({ event: 'claimed', jobId: startedClaim.id, attempt: startedClaim.attemptCount });
+            if (startedClaim.claimDisposition === 'lease_reclaimed') {
+                this.emit({
+                    event: 'lease_reclaimed',
+                    jobId: startedClaim.id,
+                    attempt: startedClaim.attemptCount,
+                });
+            }
+            await this.processClaim(startedClaim);
+        }
+        if (jobs.length === RECOVERY_JOB_CLAIM_LIMIT)
+            this.wakePending = true;
+    }
+    /** Process one claim and finish, retry, or terminally close it. */
+    async processClaim(job) {
+        try {
+            const result = await this.processor.process(job);
+            const completed = await this.repository.markCompleted({
+                jobId: job.id,
+                workerId: this.workerId,
+                now: this.clock.now(),
+            });
+            if (!completed) {
+                logger.warn({ event: 'recovery_worker_claim_lost' }, 'Recovery worker claim was lost');
+                return;
+            }
+            this.emit({
+                event: result === 'no_op' ? 'no_op' : 'completed',
+                jobId: job.id,
+                attempt: job.attemptCount,
+            });
+        }
+        catch (error) {
+            const failure = error instanceof RecoveryJobProcessingError
+                ? error
+                : new RecoveryJobProcessingError('processing_failed', true);
+            if (failure.retryable && job.attemptCount < RECOVERY_JOB_ATTEMPT_LIMIT) {
+                await this.retry(job, failure.reason);
+                return;
+            }
+            await this.finishTerminal(job, failure.reason);
+        }
+    }
+    /** Reschedule an owned transient failure with its exact attempt delay. */
+    async retry(job, reason) {
+        const delay = RECOVERY_WORKER_RETRY_DELAYS_MILLISECONDS[job.attemptCount - 1];
+        if (delay === undefined) {
+            await this.finishTerminal(job, reason);
+            return;
+        }
+        const now = this.clock.now();
+        const scheduled = await this.repository.scheduleRetry({
+            jobId: job.id,
+            workerId: this.workerId,
+            availableAt: new Date(now.getTime() + delay),
+            reason,
+            now,
+        });
+        if (!scheduled) {
+            logger.warn({ event: 'recovery_worker_claim_lost' }, 'Recovery worker claim was lost');
+            return;
+        }
+        this.emit({
+            event: 'retry_scheduled',
+            jobId: job.id,
+            attempt: job.attemptCount,
+            delayMilliseconds: delay,
+            reason,
+        });
+    }
+    /** Terminally close an owned claim without exposing raw failure data. */
+    async finishTerminal(job, reason) {
+        const finished = await this.repository.markTerminalFailure({
+            jobId: job.id,
+            workerId: this.workerId,
+            now: this.clock.now(),
+            reason,
+        });
+        if (!finished) {
+            logger.warn({ event: 'recovery_worker_claim_lost' }, 'Recovery worker claim was lost');
+            return;
+        }
+        this.emit({ event: 'terminal_failure', jobId: job.id, attempt: job.attemptCount, reason });
+    }
+    /** Notify the optional in-process observer without letting it break processing. */
+    emit(event) {
+        if (!this.observer)
+            return;
+        try {
+            this.observer(event);
+        }
+        catch {
+            logger.warn({ event: 'recovery_worker_observer_failed' }, 'Recovery worker observer failed');
+        }
+    }
+}
+//# sourceMappingURL=recovery-worker.js.map

package/dist/auth/recovery-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-worker.js","sourceRoot":"","sources":["../../src/auth/recovery-worker.ts"],"names":[],"mappings":"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"}

package/dist/auth/template-engine.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Handlebars-based page template engine for auth workflow pages.
+ *
+ * Renders server-side HTML pages using a layout + page template pattern.
+ * Supports per-organization template overrides:
+ *   1. Try: templates/{orgSlug}/pages/{pageName}.hbs
+ *   2. Fall back: templates/default/pages/{pageName}.hbs
+ *
+ * The engine pre-registers partials (header, footer, flash-messages) and
+ * compiles the base layout at startup. Page templates are compiled on
+ * demand and injected into the layout's {{{body}}} placeholder.
+ *
+ * @example
+ *   await initTemplateEngine();
+ *   const html = await renderPage('login', {
+ *     branding: { logoUrl: null, faviconUrl: null, primaryColor: '#3B82F6', companyName: 'Acme', customCss: null },
+ *     locale: 'en',
+ *     t: translationFn,
+ *     csrfToken: 'abc123',
+ *     orgSlug: 'acme-corp',
+ *   });
+ */
+import type { LoginMethod } from '../clients/types.js';
+/**
+ * Context passed to every page template and layout.
+ *
+ * Contains branding, i18n, CSRF, flash messages, and page-specific data.
+ * The `t` function is the i18n translation function (used by the {{t}} helper).
+ */
+export interface TemplateContext {
+    /** Organization branding for visual customization */
+    branding: {
+        logoUrl: string | null;
+        faviconUrl: string | null;
+        /** CSS primary color (default: '#3B82F6') */
+        primaryColor: string;
+        /** Company name displayed in header/footer */
+        companyName: string;
+        /** Optional custom CSS injected into layout <head> */
+        customCss: string | null;
+    };
+    /** Current locale for the page (e.g., 'en') */
+    locale: string;
+    /** Translation function (injected into Handlebars context for {{t}} helper) */
+    t: (key: string, options?: Record<string, unknown>) => string;
+    /** OIDC interaction details (present when in an OIDC flow) */
+    interaction?: {
+        uid: string;
+        prompt: string;
+        params: Record<string, unknown>;
+        client: {
+            clientName: string;
+        };
+    };
+    /** Flash messages for success/error/info feedback */
+    flash?: {
+        success?: string;
+        error?: string;
+        info?: string;
+    };
+    /** CSRF token for form protection */
+    csrfToken: string;
+    /** Organization slug for route building and template overrides */
+    orgSlug: string;
+    /**
+     * Whether to render the password login form on the login page.
+     *
+     * Derived from `resolveLoginMethods(org, client)` — true when 'password'
+     * is in the effective login methods. Only set on login-page renders.
+     */
+    showPassword?: boolean;
+    /**
+     * Whether to render the magic-link button on the login page.
+     *
+     * Derived from `resolveLoginMethods(org, client)` — true when 'magic_link'
+     * is in the effective login methods. Only set on login-page renders.
+     */
+    showMagicLink?: boolean;
+    /**
+     * Whether to render the "or" divider between password + magic-link forms.
+     *
+     * True only when BOTH methods are enabled; the divider is omitted for
+     * single-method configurations to avoid an awkward one-sided divider.
+     */
+    showDivider?: boolean;
+    /**
+     * Effective login methods resolved for the current client/org.
+     *
+     * Included for template debugging and future extensibility (e.g., showing
+     * a method-specific header or help text). Not currently rendered in the
+     * default template.
+     */
+    loginMethods?: LoginMethod[];
+    /**
+     * Pre-filled email hint from the OIDC `login_hint` authorization parameter.
+     *
+     * Sanitized (trimmed + length-capped at RFC 5321 max of 320 chars) by the
+     * interaction handler. Templates inject this into `value="..."` of email
+     * inputs; Handlebars HTML-escapes by default so XSS via `login_hint` is
+     * blocked at the template boundary.
+     */
+    emailHint?: string;
+    /** Page-specific data (varies by page) */
+    [key: string]: unknown;
+}
+/**
+ * Initialize the Handlebars template engine.
+ *
+ * Registers all default partials (header, footer, flash-messages),
+ * registers custom helpers (eq, ifCond), and compiles the base layout.
+ * Must be called once at application startup before renderPage is used.
+ *
+ * @throws Error if layout template or required partials cannot be loaded
+ */
+export declare function initTemplateEngine(): Promise<void>;
+/**
+ * Render a page template with layout, branding, and i18n.
+ *
+ * Template resolution order:
+ *   1. templates/{orgSlug}/pages/{pageName}.hbs (org override)
+ *   2. templates/default/pages/{pageName}.hbs (default)
+ *
+ * The page content is rendered first, then injected into the base layout's
+ * {{{body}}} placeholder. Both the page and layout receive the full context,
+ * so they can access branding, i18n, CSRF, and page-specific data.
+ *
+ * @param pageName - Page template name (e.g., 'login', 'consent', 'error')
+ * @param context - Template context with branding, i18n, CSRF, flash, and page data
+ * @returns Rendered HTML string (complete page with layout)
+ * @throws Error if the template engine hasn't been initialized
+ * @throws Error if the page template cannot be found
+ */
+export declare function renderPage(pageName: string, context: TemplateContext): Promise<string>;
+//# sourceMappingURL=template-engine.d.ts.map

package/dist/auth/template-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-engine.d.ts","sourceRoot":"","sources":["../../src/auth/template-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAgBvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,6CAA6C;QAC7C,YAAY,EAAE,MAAM,CAAC;QACrB,8CAA8C;QAC9C,WAAW,EAAE,MAAM,CAAC;QACpB,sDAAsD;QACtD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IAEF,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IAEf,+EAA+E;IAC/E,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IAE9D,8DAA8D;IAC9D,WAAW,CAAC,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC,CAAC;IAEF,qDAAqD;IACrD,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IAEF,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAElB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAexD;AA4FD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAsDjB"}