@portaidentity/server 1.7.0

package/dist/applications/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Application and ApplicationModule types and interfaces.
+ *
+ * Defines the data structures for the application model, including
+ * the full database record, input types for create/update, and
+ * pagination helpers. Also provides mapping functions to convert
+ * snake_case database rows to camelCase TypeScript objects.
+ *
+ * Applications are platform-wide (not scoped to organizations).
+ * They represent SaaS products (e.g., "BusinessSuite") that
+ * organizations subscribe to. Each application can have modules
+ * (e.g., "CRM", "Invoicing") used for permission namespacing.
+ *
+ * These types are the foundation that all other application modules
+ * depend on (repository, cache, service, routes).
+ */
+export type { PaginatedResult } from '../organizations/types.js';
+/** Application status values — matches the DB CHECK constraint */
+export type ApplicationStatus = 'active' | 'inactive' | 'archived';
+/** Module status values — matches the DB CHECK constraint */
+export type ModuleStatus = 'active' | 'inactive';
+/**
+ * Full application record as stored in the database.
+ * Maps to the `applications` table columns (see migration 003).
+ */
+export interface Application {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: ApplicationStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Full application module record as stored in the database.
+ * Maps to the `application_modules` table columns (see migration 003).
+ * Module slugs are unique within their parent application (composite key).
+ */
+export interface ApplicationModule {
+    id: string;
+    applicationId: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: ModuleStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Input for creating a new application.
+ * Slug is auto-generated from name if not provided.
+ */
+export interface CreateApplicationInput {
+    name: string;
+    slug?: string;
+    description?: string;
+}
+/** Input for updating an existing application (partial). */
+export interface UpdateApplicationInput {
+    name?: string;
+    description?: string | null;
+}
+/** Input for creating a module within an application. */
+export interface CreateModuleInput {
+    name: string;
+    slug?: string;
+    description?: string;
+}
+/** Input for updating an existing module (partial). */
+export interface UpdateModuleInput {
+    name?: string;
+    description?: string | null;
+}
+/** Options for listing applications (paginated). */
+export interface ListApplicationsOptions {
+    page: number;
+    pageSize: number;
+    status?: ApplicationStatus;
+    search?: string;
+    sortBy?: 'name' | 'created_at';
+    sortOrder?: 'asc' | 'desc';
+}
+/** Raw database row from the applications table (snake_case columns). */
+export interface ApplicationRow {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: string;
+    created_at: Date;
+    updated_at: Date;
+}
+/** Raw database row from the application_modules table (snake_case columns). */
+export interface ApplicationModuleRow {
+    id: string;
+    application_id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    status: string;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Map a database row to an Application object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `ApplicationStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the applications table
+ * @returns Mapped Application object with camelCase properties
+ */
+export declare function mapRowToApplication(row: ApplicationRow): Application;
+/**
+ * Map a database row to an ApplicationModule object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `ModuleStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the application_modules table
+ * @returns Mapped ApplicationModule object with camelCase properties
+ */
+export declare function mapRowToModule(row: ApplicationModuleRow): ApplicationModule;
+//# sourceMappingURL=types.d.ts.map

package/dist/applications/types.d.ts.map

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

package/dist/applications/types.js

@@ -0,0 +1,62 @@
+/**
+ * Application and ApplicationModule types and interfaces.
+ *
+ * Defines the data structures for the application model, including
+ * the full database record, input types for create/update, and
+ * pagination helpers. Also provides mapping functions to convert
+ * snake_case database rows to camelCase TypeScript objects.
+ *
+ * Applications are platform-wide (not scoped to organizations).
+ * They represent SaaS products (e.g., "BusinessSuite") that
+ * organizations subscribe to. Each application can have modules
+ * (e.g., "CRM", "Invoicing") used for permission namespacing.
+ *
+ * These types are the foundation that all other application modules
+ * depend on (repository, cache, service, routes).
+ */
+/**
+ * Map a database row to an Application object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `ApplicationStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the applications table
+ * @returns Mapped Application object with camelCase properties
+ */
+export function mapRowToApplication(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        slug: row.slug,
+        description: row.description,
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Map a database row to an ApplicationModule object.
+ *
+ * Converts snake_case column names from PostgreSQL to camelCase
+ * TypeScript properties. The `status` string is cast to
+ * `ModuleStatus` — the DB CHECK constraint guarantees it
+ * is one of the valid values.
+ *
+ * @param row - Raw database row from the application_modules table
+ * @returns Mapped ApplicationModule object with camelCase properties
+ */
+export function mapRowToModule(row) {
+    return {
+        id: row.id,
+        applicationId: row.application_id,
+        name: row.name,
+        slug: row.slug,
+        description: row.description,
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/applications/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/applications/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA+HH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACrD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,GAAG,CAAC,MAA2B;QACvC,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,GAAyB;IACtD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,GAAG,CAAC,MAAsB;QAClC,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/auth/csrf.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CSRF token generation and verification.
+ *
+ * Provides cookie-based synchronized token protection for server-rendered forms.
+ * Tokens are generated with crypto.randomBytes and verified using
+ * crypto.timingSafeEqual to prevent timing attacks.
+ *
+ * Pattern:
+ *   1. On GET (render form): generate token → set HttpOnly SameSite=Lax cookie
+ *      → embed same token in hidden form field `_csrf`
+ *   2. On POST (process form): read `_csrf` from cookie → read `_csrf` from
+ *      form body → compare with verifyCsrfToken(cookieValue, formValue)
+ *   3. Reject if mismatch (CSRF attack) or missing
+ *
+ * @example
+ *   // In route handler (render form):
+ *   const token = generateCsrfToken();
+ *   setCsrfCookie(ctx, token);
+ *   await renderPage('login', { csrfToken: token });
+ *
+ *   // In route handler (process form):
+ *   const valid = verifyCsrfToken(getCsrfFromCookie(ctx), ctx.request.body._csrf);
+ *   if (!valid) ctx.throw(403, 'Invalid CSRF token');
+ */
+import type { Context } from 'koa';
+/**
+ * Generate a cryptographically secure CSRF token.
+ *
+ * Returns a base64url-encoded string suitable for embedding in HTML forms
+ * and storing in session data.
+ *
+ * @returns Base64url-encoded CSRF token string
+ */
+export declare function generateCsrfToken(): string;
+/**
+ * Verify a CSRF token using constant-time comparison.
+ *
+ * Uses crypto.timingSafeEqual to prevent timing side-channel attacks
+ * that could allow an attacker to guess the token byte-by-byte.
+ *
+ * Returns false (rather than throwing) for any mismatch, missing value,
+ * or length difference — the caller decides whether to throw 403.
+ *
+ * @param expected - The token stored in the user's session (trusted)
+ * @param actual - The token submitted in the form field (untrusted)
+ * @returns true if tokens match, false otherwise
+ */
+export declare function verifyCsrfToken(expected: string | undefined, actual: string | undefined): boolean;
+/**
+ * Set the CSRF token as an HttpOnly cookie on the response.
+ * Call this in every GET handler that renders a form.
+ *
+ * The cookie uses:
+ *  - `httpOnly: true` — prevents JavaScript access (XSS safe)
+ *  - `sameSite: 'lax'` — blocks cross-site POST but allows navigational GET
+ *  - `secure` — HTTPS-only when the connection is secure (direct TLS or behind proxy)
+ *  - `path: '/'` — available to all routes
+ *
+ * @param ctx - Koa context
+ * @param token - CSRF token (from generateCsrfToken())
+ */
+export declare function setCsrfCookie(ctx: Context, token: string): void;
+/**
+ * Read the CSRF token from the request cookie.
+ * Call this in every POST handler to get the "expected" (trusted) token.
+ *
+ * @param ctx - Koa context
+ * @returns The CSRF token from the cookie, or undefined if not set
+ */
+export declare function getCsrfFromCookie(ctx: Context): string | undefined;
+//# sourceMappingURL=csrf.d.ts.map

package/dist/auth/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/auth/csrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAgBnC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAgBjG;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQ/D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE"}

package/dist/auth/csrf.js

@@ -0,0 +1,112 @@
+/**
+ * CSRF token generation and verification.
+ *
+ * Provides cookie-based synchronized token protection for server-rendered forms.
+ * Tokens are generated with crypto.randomBytes and verified using
+ * crypto.timingSafeEqual to prevent timing attacks.
+ *
+ * Pattern:
+ *   1. On GET (render form): generate token → set HttpOnly SameSite=Lax cookie
+ *      → embed same token in hidden form field `_csrf`
+ *   2. On POST (process form): read `_csrf` from cookie → read `_csrf` from
+ *      form body → compare with verifyCsrfToken(cookieValue, formValue)
+ *   3. Reject if mismatch (CSRF attack) or missing
+ *
+ * @example
+ *   // In route handler (render form):
+ *   const token = generateCsrfToken();
+ *   setCsrfCookie(ctx, token);
+ *   await renderPage('login', { csrfToken: token });
+ *
+ *   // In route handler (process form):
+ *   const valid = verifyCsrfToken(getCsrfFromCookie(ctx), ctx.request.body._csrf);
+ *   if (!valid) ctx.throw(403, 'Invalid CSRF token');
+ */
+import crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Number of random bytes for CSRF tokens (32 bytes = 256 bits of entropy) */
+const CSRF_TOKEN_BYTES = 32;
+/** Cookie name for CSRF token */
+const CSRF_COOKIE_NAME = '_csrf';
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a cryptographically secure CSRF token.
+ *
+ * Returns a base64url-encoded string suitable for embedding in HTML forms
+ * and storing in session data.
+ *
+ * @returns Base64url-encoded CSRF token string
+ */
+export function generateCsrfToken() {
+    return crypto.randomBytes(CSRF_TOKEN_BYTES).toString('base64url');
+}
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify a CSRF token using constant-time comparison.
+ *
+ * Uses crypto.timingSafeEqual to prevent timing side-channel attacks
+ * that could allow an attacker to guess the token byte-by-byte.
+ *
+ * Returns false (rather than throwing) for any mismatch, missing value,
+ * or length difference — the caller decides whether to throw 403.
+ *
+ * @param expected - The token stored in the user's session (trusted)
+ * @param actual - The token submitted in the form field (untrusted)
+ * @returns true if tokens match, false otherwise
+ */
+export function verifyCsrfToken(expected, actual) {
+    // Both must be present and non-empty
+    if (!expected || !actual) {
+        return false;
+    }
+    // Convert to buffers for timingSafeEqual
+    const expectedBuf = Buffer.from(expected, 'utf-8');
+    const actualBuf = Buffer.from(actual, 'utf-8');
+    // timingSafeEqual requires equal-length buffers — different lengths = guaranteed mismatch
+    if (expectedBuf.length !== actualBuf.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(expectedBuf, actualBuf);
+}
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+/**
+ * Set the CSRF token as an HttpOnly cookie on the response.
+ * Call this in every GET handler that renders a form.
+ *
+ * The cookie uses:
+ *  - `httpOnly: true` — prevents JavaScript access (XSS safe)
+ *  - `sameSite: 'lax'` — blocks cross-site POST but allows navigational GET
+ *  - `secure` — HTTPS-only when the connection is secure (direct TLS or behind proxy)
+ *  - `path: '/'` — available to all routes
+ *
+ * @param ctx - Koa context
+ * @param token - CSRF token (from generateCsrfToken())
+ */
+export function setCsrfCookie(ctx, token) {
+    ctx.cookies.set(CSRF_COOKIE_NAME, token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        secure: ctx.secure,
+        overwrite: true,
+    });
+}
+/**
+ * Read the CSRF token from the request cookie.
+ * Call this in every POST handler to get the "expected" (trusted) token.
+ *
+ * @param ctx - Koa context
+ * @returns The CSRF token from the cookie, or undefined if not set
+ */
+export function getCsrfFromCookie(ctx) {
+    return ctx.cookies.get(CSRF_COOKIE_NAME) ?? undefined;
+}
+//# sourceMappingURL=csrf.js.map

package/dist/auth/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../../src/auth/csrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,8EAA8E;AAC9E,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B,iCAAiC;AACjC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAEjC,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACpE,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,QAA4B,EAAE,MAA0B;IACtF,qCAAqC;IACrC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yCAAyC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C,0FAA0F;IAC1F,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,KAAa;IACvD,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,EAAE;QACvC,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,GAAG;QACT,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,SAAS,CAAC;AACxD,CAAC"}

package/dist/auth/email-renderer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Email template renderer using Handlebars.
+ *
+ * Renders HTML and plaintext email templates with organization branding
+ * and i18n context. Supports per-organization template overrides:
+ *   1. Try: templates/{orgSlug}/emails/{templateName}.hbs
+ *   2. Fall back: templates/default/emails/{templateName}.hbs
+ *
+ * Both .hbs (HTML) and .txt.hbs (plaintext) variants are rendered.
+ *
+ * @example
+ *   const { html, text } = await renderEmail('magic-link', 'acme-corp', {
+ *     userName: 'Alice',
+ *     magicLinkUrl: 'https://...',
+ *     branding: { logoUrl: '...', primaryColor: '#3B82F6', companyName: 'Acme' },
+ *   });
+ */
+/**
+ * Render an email template (HTML + plaintext) with the given context.
+ *
+ * Template resolution order:
+ *   1. templates/{orgSlug}/emails/{templateName}.hbs (org override)
+ *   2. templates/default/emails/{templateName}.hbs (default)
+ *
+ * Automatically adds `year` to the context for footer copyright.
+ *
+ * @param templateName - Email template name (e.g., 'magic-link', 'password-reset')
+ * @param orgSlug - Organization slug for template override lookup
+ * @param context - Template variables (userName, branding, URLs, etc.)
+ * @returns Object with rendered `html` and `text` strings
+ * @throws Error if the HTML template cannot be found
+ */
+export declare function renderEmail(templateName: string, orgSlug: string, context: Record<string, unknown>): Promise<{
+    html: string;
+    text: string;
+}>;
+//# sourceMappingURL=email-renderer.d.ts.map

package/dist/auth/email-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-renderer.d.ts","sourceRoot":"","sources":["../../src/auth/email-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgEH;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCzC"}

package/dist/auth/email-renderer.js

@@ -0,0 +1,116 @@
+/**
+ * Email template renderer using Handlebars.
+ *
+ * Renders HTML and plaintext email templates with organization branding
+ * and i18n context. Supports per-organization template overrides:
+ *   1. Try: templates/{orgSlug}/emails/{templateName}.hbs
+ *   2. Fall back: templates/default/emails/{templateName}.hbs
+ *
+ * Both .hbs (HTML) and .txt.hbs (plaintext) variants are rendered.
+ *
+ * @example
+ *   const { html, text } = await renderEmail('magic-link', 'acme-corp', {
+ *     userName: 'Alice',
+ *     magicLinkUrl: 'https://...',
+ *     branding: { logoUrl: '...', primaryColor: '#3B82F6', companyName: 'Acme' },
+ *   });
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import Handlebars from 'handlebars';
+import { logger } from '../lib/logger.js';
+import { getTemplatesDirectory } from '../lib/runtime-paths.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Absolute directory containing templates shipped with the server package. */
+const TEMPLATES_DIR = getTemplatesDirectory();
+// ---------------------------------------------------------------------------
+// Template resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a template file path with org-override support.
+ *
+ * Checks for an organization-specific template first, then falls back
+ * to the default template. Returns null if neither exists.
+ *
+ * @param orgSlug - Organization slug for override lookup
+ * @param templatePath - Relative path within the emails directory (e.g., 'magic-link.hbs')
+ * @returns Absolute path to the template file, or null if not found
+ */
+async function resolveTemplatePath(orgSlug, templatePath) {
+    // Try org-specific template first
+    const orgPath = path.join(TEMPLATES_DIR, orgSlug, 'emails', templatePath);
+    try {
+        await fs.access(orgPath);
+        return orgPath;
+    }
+    catch {
+        // Org-specific template doesn't exist — fall through to default
+    }
+    // Fall back to default template
+    const defaultPath = path.join(TEMPLATES_DIR, 'default', 'emails', templatePath);
+    try {
+        await fs.access(defaultPath);
+        return defaultPath;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load and compile a Handlebars template from the file system.
+ *
+ * @param filePath - Absolute path to the template file
+ * @returns Compiled Handlebars template function
+ */
+async function loadTemplate(filePath) {
+    const source = await fs.readFile(filePath, 'utf-8');
+    return Handlebars.compile(source);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Render an email template (HTML + plaintext) with the given context.
+ *
+ * Template resolution order:
+ *   1. templates/{orgSlug}/emails/{templateName}.hbs (org override)
+ *   2. templates/default/emails/{templateName}.hbs (default)
+ *
+ * Automatically adds `year` to the context for footer copyright.
+ *
+ * @param templateName - Email template name (e.g., 'magic-link', 'password-reset')
+ * @param orgSlug - Organization slug for template override lookup
+ * @param context - Template variables (userName, branding, URLs, etc.)
+ * @returns Object with rendered `html` and `text` strings
+ * @throws Error if the HTML template cannot be found
+ */
+export async function renderEmail(templateName, orgSlug, context) {
+    // Resolve HTML template (required)
+    const htmlPath = await resolveTemplatePath(orgSlug, `${templateName}.hbs`);
+    if (!htmlPath) {
+        throw new Error(`Email template not found: ${templateName}.hbs (checked ${orgSlug}/ and default/)`);
+    }
+    // Resolve plaintext template (optional — fall back to empty string)
+    const textPath = await resolveTemplatePath(orgSlug, `${templateName}.txt.hbs`);
+    // Enrich context with common variables
+    const enrichedContext = {
+        ...context,
+        year: new Date().getFullYear(),
+    };
+    // Render HTML
+    const htmlTemplate = await loadTemplate(htmlPath);
+    const html = htmlTemplate(enrichedContext);
+    // Render plaintext (if template exists)
+    let text = '';
+    if (textPath) {
+        const textTemplate = await loadTemplate(textPath);
+        text = textTemplate(enrichedContext);
+    }
+    else {
+        logger.debug({ templateName, orgSlug }, 'No plaintext email template found — using empty text body');
+    }
+    return { html, text };
+}
+//# sourceMappingURL=email-renderer.js.map

package/dist/auth/email-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-renderer.js","sourceRoot":"","sources":["../../src/auth/email-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,+EAA+E;AAC/E,MAAM,aAAa,GAAG,qBAAqB,EAAE,CAAC;AAE9C,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,KAAK,UAAU,mBAAmB,CAAC,OAAe,EAAE,YAAoB;IACtE,kCAAkC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC1E,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IAED,gCAAgC;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;IAChF,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC7B,OAAO,WAAW,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,YAAY,CAAC,QAAgB;IAC1C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,YAAoB,EACpB,OAAe,EACf,OAAgC;IAEhC,mCAAmC;IACnC,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,GAAG,YAAY,MAAM,CAAC,CAAC;IAC3E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,6BAA6B,YAAY,iBAAiB,OAAO,iBAAiB,CACnF,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,GAAG,YAAY,UAAU,CAAC,CAAC;IAE/E,uCAAuC;IACvC,MAAM,eAAe,GAAG;QACtB,GAAG,OAAO;QACV,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC/B,CAAC;IAEF,cAAc;IACd,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;IAE3C,wCAAwC;IACxC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CACV,EAAE,YAAY,EAAE,OAAO,EAAE,EACzB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}