@portaidentity/server 1.7.0

package/dist/auth/template-engine.js

@@ -0,0 +1,225 @@
+/**
+ * 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 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();
+/** Default template set name */
+const DEFAULT_SET = 'default';
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+/** Compiled base layout template (loaded at init) */
+let layoutTemplate = null;
+/** Whether the engine has been initialized */
+let initialized = false;
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function initTemplateEngine() {
+    // Register partials from the default set
+    const partialsDir = path.join(TEMPLATES_DIR, DEFAULT_SET, 'partials');
+    await registerPartials(partialsDir);
+    // Register custom Handlebars helpers
+    registerHelpers();
+    // Compile the base layout
+    const layoutPath = path.join(TEMPLATES_DIR, DEFAULT_SET, 'layouts', 'main.hbs');
+    const layoutSource = await fs.readFile(layoutPath, 'utf-8');
+    layoutTemplate = Handlebars.compile(layoutSource);
+    initialized = true;
+    logger.info({ templatesDir: TEMPLATES_DIR }, 'Template engine initialized');
+}
+/**
+ * Register all .hbs files in a directory as Handlebars partials.
+ *
+ * Partial names are derived from filenames without extension:
+ * e.g., 'header.hbs' → partial name 'header' (used as {{> header}}).
+ *
+ * @param partialsDir - Absolute path to the partials directory
+ */
+async function registerPartials(partialsDir) {
+    try {
+        const files = await fs.readdir(partialsDir);
+        const hbsFiles = files.filter((f) => f.endsWith('.hbs'));
+        for (const file of hbsFiles) {
+            const name = path.basename(file, '.hbs');
+            const source = await fs.readFile(path.join(partialsDir, file), 'utf-8');
+            Handlebars.registerPartial(name, source);
+            logger.debug({ partial: name }, 'Registered Handlebars partial');
+        }
+    }
+    catch (error) {
+        logger.warn({ error, partialsDir }, 'Failed to register partials — directory may not exist');
+    }
+}
+/**
+ * Register custom Handlebars helpers used across templates.
+ *
+ * Helpers:
+ *   - {{eq a b}}: Strict equality check (useful in {{#if (eq status "active")}})
+ *   - {{year}}: Current year (for copyright footers)
+ */
+function registerHelpers() {
+    // Equality helper — {{#if (eq prompt "login")}}
+    Handlebars.registerHelper('eq', function (a, b) {
+        return a === b;
+    });
+    // Current year helper — {{year}}
+    Handlebars.registerHelper('year', function () {
+        return new Date().getFullYear();
+    });
+    // String concatenation helper — {{concat "prefix_" value}}
+    Handlebars.registerHelper('concat', function (...args) {
+        // Last argument is the Handlebars options object — exclude it
+        return args.slice(0, -1).join('');
+    });
+}
+// ---------------------------------------------------------------------------
+// Template resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a page template path with org-override support.
+ *
+ * Checks for an organization-specific page template first, then falls
+ * back to the default. Returns null if neither exists.
+ *
+ * @param pageName - Page template name (e.g., 'login', 'consent')
+ * @param orgSlug - Organization slug for override lookup
+ * @returns Absolute path to the template file, or null if not found
+ */
+async function resolvePageTemplatePath(pageName, orgSlug) {
+    // Try org-specific page template first
+    const orgPath = path.join(TEMPLATES_DIR, orgSlug, 'pages', `${pageName}.hbs`);
+    try {
+        await fs.access(orgPath);
+        return orgPath;
+    }
+    catch {
+        // Org-specific page doesn't exist — fall through to default
+    }
+    // Fall back to default page template
+    const defaultPath = path.join(TEMPLATES_DIR, DEFAULT_SET, 'pages', `${pageName}.hbs`);
+    try {
+        await fs.access(defaultPath);
+        return defaultPath;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function renderPage(pageName, context) {
+    if (!initialized || !layoutTemplate) {
+        throw new Error('Template engine not initialized — call initTemplateEngine() first');
+    }
+    // Resolve the page template (with org-override support)
+    const templatePath = await resolvePageTemplatePath(pageName, context.orgSlug);
+    if (!templatePath) {
+        throw new Error(`Page template not found: ${pageName}.hbs (checked ${context.orgSlug}/ and default/)`);
+    }
+    // Load and compile the page template
+    const pageSource = await fs.readFile(templatePath, 'utf-8');
+    const pageTemplate = Handlebars.compile(pageSource);
+    // Build the full context with additional layout properties
+    const fullContext = {
+        ...context,
+        // Add pageTitle for the <title> tag — use pageName capitalized as default
+        pageTitle: context.pageTitle ?? capitalize(pageName.replace(/-/g, ' ')),
+        year: new Date().getFullYear(),
+    };
+    // Register `t` as a runtime helper so templates can use subexpressions
+    // like {{t (concat "prefix_" value)}}. Context functions only work for
+    // simple {{t "key"}} calls; subexpressions require a registered helper.
+    // Runtime helpers are per-render (no global mutation, concurrent-safe).
+    //
+    // IMPORTANT: Handlebars helpers receive (key, HelperOptions) where hash
+    // arguments (e.g., clientName=interaction.client.clientName) are in
+    // options.hash — NOT as top-level properties. The raw context.t function
+    // expects a flat options object, so we extract .hash here.
+    const tFn = context.t;
+    const runtimeOptions = {
+        helpers: {
+            t(key, options) {
+                const hash = options?.hash ?? {};
+                return tFn(key, hash);
+            },
+        },
+    };
+    // Render the page body first
+    const pageBody = pageTemplate(fullContext, runtimeOptions);
+    // Inject the page body into the layout
+    const layoutContext = {
+        ...fullContext,
+        body: pageBody,
+    };
+    return layoutTemplate(layoutContext, runtimeOptions);
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @param str - Input string
+ * @returns String with first letter uppercased
+ */
+function capitalize(str) {
+    if (!str)
+        return str;
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+//# sourceMappingURL=template-engine.js.map

package/dist/auth/template-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-engine.js","sourceRoot":"","sources":["../../src/auth/template-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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;AAGhE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,+EAA+E;AAC/E,MAAM,aAAa,GAAG,qBAAqB,EAAE,CAAC;AAE9C,gCAAgC;AAChC,MAAM,WAAW,GAAG,SAAS,CAAC;AAmG9B,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,qDAAqD;AACrD,IAAI,cAAc,GAAsC,IAAI,CAAC;AAE7D,8CAA8C;AAC9C,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,yCAAyC;IACzC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAEpC,qCAAqC;IACrC,eAAe,EAAE,CAAC;IAElB,0BAA0B;IAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5D,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAElD,WAAW,GAAG,IAAI,CAAC;IACnB,MAAM,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE,6BAA6B,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACjD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAEzD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACxE,UAAU,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,+BAA+B,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,uDAAuD,CAAC,CAAC;IAC/F,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe;IACtB,gDAAgD;IAChD,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,CAAU,EAAE,CAAU;QAC9D,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,iCAAiC;IACjC,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE;QAChC,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,UAAU,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAe;QAC9D,8DAA8D;QAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,KAAK,UAAU,uBAAuB,CACpC,QAAgB,EAChB,OAAe;IAEf,uCAAuC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC;IAC9E,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;IAED,qCAAqC;IACrC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC;IACtF,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,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,OAAwB;IAExB,IAAI,CAAC,WAAW,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,wDAAwD;IACxD,MAAM,YAAY,GAAG,MAAM,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,4BAA4B,QAAQ,iBAAiB,OAAO,CAAC,OAAO,iBAAiB,CACtF,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAEpD,2DAA2D;IAC3D,MAAM,WAAW,GAAG;QAClB,GAAG,OAAO;QACV,0EAA0E;QAC1E,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACvE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC/B,CAAC;IAEF,uEAAuE;IACvE,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,EAAE;IACF,wEAAwE;IACxE,oEAAoE;IACpE,yEAAyE;IACzE,2DAA2D;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;IACtB,MAAM,cAAc,GAA8B;QAChD,OAAO,EAAE;YACP,CAAC,CAAC,GAAW,EAAE,OAAiC;gBAC9C,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;gBACjC,OAAO,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACxB,CAAC;SACF;KACF,CAAC;IAEF,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAE3D,uCAAuC;IACvC,MAAM,aAAa,GAAG;QACpB,GAAG,WAAW;QACd,IAAI,EAAE,QAAQ;KACf,CAAC;IAEF,OAAO,cAAc,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;AACvD,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/auth/token-repository.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Token repository — PostgreSQL CRUD for all three token tables.
+ *
+ * Password-reset and invitation tokens use shared allowlisted helpers. Magic-link issuance and
+ * consumption use dedicated authority-aware transactions so callers cannot omit tenant, live
+ * client, or interaction validation.
+ *
+ * Token lifecycle:
+ *   1. insertToken()          → store hash + expiry for a user
+ *   2. findValidToken()       → look up unused, non-expired token by hash
+ *   3. markTokenUsed()        → set used_at = NOW() after successful verification
+ *   4. invalidateUserTokens() → expire all active tokens for a user (when new token issued)
+ *   5. deleteExpiredTokens()  → cleanup old rows (housekeeping)
+ */
+import type { PoolClient } from 'pg';
+import type { UserStatus } from '../users/types.js';
+/** Allowed token table names — used as an allowlist to prevent SQL injection */
+export type TokenTable = 'magic_link_tokens' | 'password_reset_tokens' | 'invitation_tokens';
+/** Token tables whose rows do not require magic-link tenant and interaction authority. */
+export type GenericInsertTokenTable = Exclude<TokenTable, 'magic_link_tokens'>;
+/** Row shape returned from any of the three token tables */
+export interface TokenRecord {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    expiresAt: Date;
+    usedAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Extended token record for invitation tokens with optional details.
+ *
+ * The details JSONB column stores pre-assignment metadata (roles, claims,
+ * personal message) that should be applied when the invitation is accepted.
+ */
+export interface InvitationTokenRecord extends TokenRecord {
+    /** JSONB details stored with the invitation (roles, claims, personalMessage, inviterName) */
+    details: Record<string, unknown> | null;
+    /** User ID of the admin who created this invitation */
+    invitedBy: string | null;
+}
+/** Input for idempotently creating a recovery-job-owned token. */
+interface EnsureRecoveryTokenBaseInput {
+    /** Token table selected by the closed recovery job type. */
+    /** Durable recovery job UUID. */
+    readonly recoveryJobId: string;
+    /** Eligible account UUID. */
+    readonly userId: string;
+    /** Hash of the deterministic plaintext token. */
+    readonly tokenHash: string;
+    /** Expiration instant fixed by the first successful artifact transaction. */
+    readonly expiresAt: Date;
+}
+/** Recovery-token input whose durable authority belongs to one OIDC tenant and interaction. */
+export interface EnsureMagicLinkRecoveryTokenInput extends EnsureRecoveryTokenBaseInput {
+    /** Select the magic-link artifact table and its authority-aware insert path. */
+    readonly table: 'magic_link_tokens';
+    /** Organization that owns the artifact and resolved user. */
+    readonly organizationId: string;
+    /** Exact OIDC interaction authority, or null for an explicitly standalone artifact. */
+    readonly interactionUid: string | null;
+    /** Current OIDC client resolved from the provider-owned interaction. */
+    readonly clientId: string | null;
+}
+/** Recovery-token input for password reset, which has no OIDC interaction authority. */
+export interface EnsurePasswordResetRecoveryTokenInput extends EnsureRecoveryTokenBaseInput {
+    /** Select the password-reset artifact table. */
+    readonly table: 'password_reset_tokens';
+}
+/** Closed recovery-token input union that prevents authority-free magic-link insertion. */
+export type EnsureRecoveryTokenInput = EnsureMagicLinkRecoveryTokenInput | EnsurePasswordResetRecoveryTokenInput;
+/** Durable artifact decision returned by idempotent recovery-token issuance. */
+export type EnsureRecoveryTokenResult = 'active' | 'superseded';
+/** Magic-link artifact whose persisted authority was selected under a database row lock. */
+export interface LockedMagicLinkToken extends TokenRecord {
+    /** Organization persisted when the artifact was issued. */
+    readonly organizationId: string;
+    /** Exact persisted interaction, or null for a standalone artifact. */
+    readonly interactionUid: string | null;
+    /** Lifecycle state observed while the owning account row is locked. */
+    readonly accountStatus: UserStatus;
+}
+/** Inputs required to validate and consume one magic-link artifact transactionally. */
+export interface ConsumeAuthorizedMagicLinkInput {
+    /** SHA-256 digest of the presented bearer artifact. */
+    readonly tokenHash: string;
+    /** Organization resolved from the public route. */
+    readonly organizationId: string;
+    /** Exact transport interaction, or null when the public request supplied none. */
+    readonly interactionUid: string | null;
+    /** Current interaction client, or null only for an explicitly standalone artifact. */
+    readonly clientId: string | null;
+    /** Validated request address retained only in the successful audit row. */
+    readonly ipAddress?: string;
+}
+/** Successful authority decision returned after the database transaction commits. */
+export interface ConsumedAuthorizedMagicLink {
+    /** Account authorized and updated by the consumed artifact. */
+    readonly userId: string;
+    /** Persisted interaction authority, or null for a standalone artifact. */
+    readonly interactionUid: string | null;
+}
+/**
+ * Insert a new token into the specified table.
+ *
+ * @param table - Target token table (magic_link_tokens | password_reset_tokens | invitation_tokens)
+ * @param userId - UUID of the user this token belongs to
+ * @param tokenHash - SHA-256 hex hash of the plaintext token
+ * @param expiresAt - When this token expires
+ */
+export declare function insertToken(table: GenericInsertTokenTable, userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+/**
+ * Create or observe the single token artifact owned by a recovery job.
+ *
+ * A transaction locks the user row as the shared serialization authority, reuses an existing job
+ * artifact, or invalidates an older artifact and inserts exactly one new row. A retry from an older
+ * job cannot replace authority created by any newer job, even after that authority is consumed or
+ * expires. SQL identifiers come exclusively from the closed table union.
+ *
+ * @param input - Recovery-job token authority and deterministic token facts.
+ */
+export declare function ensureRecoveryJobToken(input: EnsureRecoveryTokenInput): Promise<EnsureRecoveryTokenResult>;
+/**
+ * Find a valid (unused, not expired) token by its hash.
+ *
+ * Checks both `used_at IS NULL` and `expires_at > NOW()` in a single query
+ * for efficiency. Returns null if no matching valid token exists.
+ *
+ * @param table - Target token table
+ * @param tokenHash - SHA-256 hex hash to look up
+ * @returns The token record if valid, or null if not found/expired/used
+ */
+export declare function findValidToken(table: TokenTable, tokenHash: string): Promise<TokenRecord | null>;
+/**
+ * Find a valid token only when its user belongs to the resolved organization.
+ *
+ * Tenant binding is enforced in the lookup itself so a valid token presented under another
+ * tenant is indistinguishable from an invalid token and cannot reach account mutation.
+ *
+ * @param table - Target token table.
+ * @param tokenHash - SHA-256 token digest.
+ * @param organizationId - Tenant authority resolved from the public route.
+ * @returns The valid tenant-owned token, or null.
+ */
+export declare function findValidTokenForOrganization(table: TokenTable, tokenHash: string, organizationId: string): Promise<TokenRecord | null>;
+/**
+ * Lock one valid magic-link artifact together with its tenant-owned user.
+ *
+ * Legacy rows without persisted organization authority do not match. The caller must keep the
+ * supplied client transaction open while validating interaction authority and applying all
+ * successful state changes.
+ *
+ * @param client - Active PostgreSQL transaction client.
+ * @param tokenHash - SHA-256 digest of the presented artifact.
+ * @param organizationId - Organization resolved from the public route.
+ * @returns The locked authority record, or null for every invalid authority state.
+ */
+export declare function findAndLockMagicLinkToken(client: PoolClient, tokenHash: string, organizationId: string): Promise<LockedMagicLinkToken | null>;
+/**
+ * Conditionally consume a previously locked magic-link artifact.
+ *
+ * The predicates are repeated at mutation time so expiry or accidental prior consumption cannot
+ * be converted into a successful use. The caller must roll back when this function returns false.
+ *
+ * @param client - Active PostgreSQL transaction client that owns the artifact lock.
+ * @param tokenId - UUID of the locked magic-link artifact.
+ * @returns True only when exactly one still-valid row was consumed.
+ */
+export declare function consumeLockedMagicLinkToken(client: PoolClient, tokenId: string): Promise<boolean>;
+/**
+ * Validate all durable authority and apply one magic-link login in a single transaction.
+ *
+ * The artifact and account rows remain locked from lookup through consumption, account update,
+ * and audit insertion. Every authority mismatch rolls back before mutation, including a missing,
+ * changed, or unexpectedly supplied interaction identifier. Cache and Redis continuation work
+ * deliberately happen after this durable transaction because they are separate stores.
+ *
+ * @param input - Route tenant, presented interaction, artifact digest, and safe request metadata.
+ * @returns The committed account authority, or null for every public rejection condition.
+ */
+export declare function consumeAuthorizedMagicLink(input: ConsumeAuthorizedMagicLinkInput): Promise<ConsumedAuthorizedMagicLink | null>;
+/**
+ * Mark a token as used by setting used_at = NOW().
+ *
+ * Called after successful token verification to prevent reuse.
+ * This is a single-use pattern — once marked, the token cannot be found by findValidToken.
+ *
+ * @param table - Target token table
+ * @param tokenId - UUID of the token row to mark
+ */
+export declare function markTokenUsed(table: TokenTable, tokenId: string): Promise<void>;
+/**
+ * Delete expired or used tokens older than a given cutoff date.
+ *
+ * Housekeeping function to prevent token tables from growing indefinitely.
+ * Removes tokens where expires_at < cutoff OR (used_at IS NOT NULL AND used_at < cutoff).
+ *
+ * @param table - Target token table
+ * @param olderThan - Cutoff date — tokens expired/used before this are deleted
+ * @returns Number of rows deleted
+ */
+export declare function deleteExpiredTokens(table: TokenTable, olderThan: Date): Promise<number>;
+/**
+ * Invalidate all unused tokens for a user in a table.
+ *
+ * Sets used_at = NOW() on all active (unused, non-expired) tokens.
+ * Called when a new token is issued to ensure only the latest token is valid.
+ * This prevents token accumulation and confusion from multiple active tokens.
+ *
+ * @param table - Target token table
+ * @param userId - UUID of the user whose tokens should be invalidated
+ */
+export declare function invalidateUserTokens(table: TokenTable, userId: string): Promise<void>;
+/**
+ * Insert an invitation token with optional details and inviter metadata.
+ *
+ * Unlike the generic insertToken(), this stores additional JSONB details
+ * (pre-assigned roles, claims, personal message) and tracks who sent the invite.
+ *
+ * @param userId - UUID of the invited user
+ * @param tokenHash - SHA-256 hex hash of the plaintext token
+ * @param expiresAt - When this invitation expires
+ * @param details - Optional JSONB details (roles, claims, personalMessage, inviterName)
+ * @param invitedBy - Optional UUID of the admin who created this invitation
+ */
+export declare function insertInvitationToken(userId: string, tokenHash: string, expiresAt: Date, details?: Record<string, unknown> | null, invitedBy?: string | null): Promise<void>;
+/**
+ * Find a valid invitation token with its details metadata.
+ *
+ * Returns the full InvitationTokenRecord including the details JSONB
+ * column, which stores pre-assignment metadata for roles, claims, etc.
+ *
+ * @param tokenHash - SHA-256 hex hash to look up
+ * @returns The invitation token record with details, or null if not found/expired/used
+ */
+export declare function findValidInvitationToken(tokenHash: string): Promise<InvitationTokenRecord | null>;
+export {};
+//# sourceMappingURL=token-repository.d.ts.map

package/dist/auth/token-repository.d.ts.map

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