@portaidentity/server 1.7.0

package/dist/auth/token-repository.js

@@ -0,0 +1,475 @@
+/**
+ * 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 { getPool } from '../lib/database.js';
+import { logger } from '../lib/logger.js';
+// ---------------------------------------------------------------------------
+// Allowlist validation
+// ---------------------------------------------------------------------------
+/** Set of valid token table names for runtime validation */
+const VALID_TABLES = new Set([
+    'magic_link_tokens',
+    'password_reset_tokens',
+    'invitation_tokens',
+]);
+/**
+ * Validate that the table name is in the allowlist.
+ * Throws immediately on invalid names — this is a programming error, not a user error.
+ *
+ * @param table - Table name to validate
+ * @throws Error if table name is not in the allowlist
+ */
+function assertValidTable(table) {
+    if (!VALID_TABLES.has(table)) {
+        throw new Error(`Invalid token table: "${table}". Must be one of: ${[...VALID_TABLES].join(', ')}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Row mapping
+// ---------------------------------------------------------------------------
+/**
+ * Map a snake_case database row to a camelCase TokenRecord.
+ *
+ * @param row - Raw database row
+ * @returns Mapped TokenRecord with camelCase properties
+ */
+function mapRowToToken(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        tokenHash: row.token_hash,
+        expiresAt: row.expires_at,
+        usedAt: row.used_at,
+        createdAt: row.created_at,
+    };
+}
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function insertToken(table, userId, tokenHash, expiresAt) {
+    assertValidTable(table);
+    const pool = getPool();
+    await pool.query(`INSERT INTO ${table} (user_id, token_hash, expires_at)
+     VALUES ($1, $2, $3)`, [userId, tokenHash, expiresAt]);
+    logger.debug({ table, userId }, 'Token inserted');
+}
+/**
+ * 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 async function ensureRecoveryJobToken(input) {
+    assertValidTable(input.table);
+    const pool = getPool();
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const lockedUser = await client.query('SELECT id FROM users WHERE id = $1 FOR UPDATE', [
+            input.userId,
+        ]);
+        if (lockedUser.rowCount !== 1) {
+            throw new Error('Recovery artifact user disappeared before issuance');
+        }
+        const jobOrder = await client.query('SELECT created_at FROM auth_recovery_jobs WHERE id = $1', [input.recoveryJobId]);
+        const currentJob = jobOrder.rows[0];
+        if (!currentJob) {
+            throw new Error('Recovery job disappeared before artifact issuance');
+        }
+        if (input.table === 'magic_link_tokens') {
+            const clientMatches = input.interactionUid === null && input.clientId === null
+                ? true
+                : input.interactionUid !== null &&
+                    input.clientId !== null &&
+                    (await lockActiveClientAuthority(client, input.clientId, input.organizationId));
+            if (!clientMatches) {
+                await client.query('COMMIT');
+                return 'superseded';
+            }
+        }
+        const existing = await client.query(`SELECT used_at IS NULL AND expires_at > NOW() AS active
+       FROM ${input.table}
+       WHERE recovery_job_id = $1`, [input.recoveryJobId]);
+        if (existing.rows[0]) {
+            await client.query('COMMIT');
+            return existing.rows[0].active ? 'active' : 'superseded';
+        }
+        const newestArtifact = await client.query(`SELECT token.recovery_job_id, job.created_at
+       FROM ${input.table} AS token
+       JOIN auth_recovery_jobs AS job ON job.id = token.recovery_job_id
+       WHERE token.user_id = $1
+         AND token.recovery_job_id IS NOT NULL
+       ORDER BY job.created_at DESC, job.id DESC
+       LIMIT 1`, [input.userId]);
+        const newest = newestArtifact.rows[0];
+        const currentCreatedAt = currentJob.created_at.getTime();
+        const newerArtifactExists = newest !== undefined &&
+            (newest.created_at.getTime() > currentCreatedAt ||
+                (newest.created_at.getTime() === currentCreatedAt &&
+                    newest.recovery_job_id > input.recoveryJobId));
+        if (newerArtifactExists) {
+            await client.query('COMMIT');
+            return 'superseded';
+        }
+        await client.query(`UPDATE ${input.table}
+       SET used_at = NOW()
+       WHERE user_id = $1 AND used_at IS NULL AND expires_at > NOW()`, [input.userId]);
+        if (input.table === 'magic_link_tokens') {
+            await client.query(`INSERT INTO magic_link_tokens
+           (user_id, token_hash, expires_at, recovery_job_id, organization_id, interaction_uid)
+         VALUES ($1, $2, $3, $4, $5, $6)`, [
+                input.userId,
+                input.tokenHash,
+                input.expiresAt,
+                input.recoveryJobId,
+                input.organizationId,
+                input.interactionUid,
+            ]);
+        }
+        else {
+            await client.query(`INSERT INTO password_reset_tokens (user_id, token_hash, expires_at, recovery_job_id)
+         VALUES ($1, $2, $3, $4)`, [input.userId, input.tokenHash, input.expiresAt, input.recoveryJobId]);
+        }
+        await client.query('COMMIT');
+        return 'active';
+    }
+    catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Lock and validate the current client tenant inside an artifact transaction.
+ *
+ * Client ownership is checked in the same transaction that inserts or consumes the artifact so a
+ * concurrent revocation cannot pass an earlier route-only check and then gain authority.
+ *
+ * @param client - Active PostgreSQL transaction.
+ * @param clientId - Public OIDC client identifier resolved from the live interaction.
+ * @param organizationId - Tenant which must currently own the active client.
+ * @returns True only when one current active client row is locked.
+ */
+async function lockActiveClientAuthority(client, clientId, organizationId) {
+    const result = await client.query(`SELECT id
+     FROM clients
+     WHERE client_id = $1
+       AND organization_id = $2
+       AND status = 'active'
+     FOR SHARE`, [clientId, organizationId]);
+    return result.rowCount === 1;
+}
+/**
+ * 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 async function findValidToken(table, tokenHash) {
+    assertValidTable(table);
+    const pool = getPool();
+    const result = await pool.query(`SELECT id, user_id, token_hash, expires_at, used_at, created_at
+     FROM ${table}
+     WHERE token_hash = $1
+       AND used_at IS NULL
+       AND expires_at > NOW()`, [tokenHash]);
+    if (result.rows.length === 0) {
+        return null;
+    }
+    return mapRowToToken(result.rows[0]);
+}
+/**
+ * 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 async function findValidTokenForOrganization(table, tokenHash, organizationId) {
+    assertValidTable(table);
+    const pool = getPool();
+    const result = await pool.query(`SELECT token.id, token.user_id, token.token_hash,
+            token.expires_at, token.used_at, token.created_at
+     FROM ${table} AS token
+     JOIN users AS account ON account.id = token.user_id
+     WHERE token.token_hash = $1
+       AND account.organization_id = $2
+       AND token.used_at IS NULL
+       AND token.expires_at > NOW()`, [tokenHash, organizationId]);
+    return result.rows[0] ? mapRowToToken(result.rows[0]) : 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 async function findAndLockMagicLinkToken(client, tokenHash, organizationId) {
+    const result = await client.query(`SELECT token.id, token.user_id, token.token_hash, token.expires_at, token.used_at,
+            token.created_at, token.organization_id, token.interaction_uid,
+            account.status AS account_status
+     FROM magic_link_tokens AS token
+     JOIN users AS account
+       ON account.id = token.user_id
+      AND account.organization_id = token.organization_id
+     WHERE token.token_hash = $1
+       AND token.organization_id = $2
+       AND token.authority_bound = TRUE
+       AND token.used_at IS NULL
+       AND token.expires_at > NOW()
+     FOR UPDATE OF token, account`, [tokenHash, organizationId]);
+    const row = result.rows[0];
+    if (!row)
+        return null;
+    return {
+        ...mapRowToToken(row),
+        organizationId: row.organization_id,
+        interactionUid: row.interaction_uid,
+        accountStatus: row.account_status,
+    };
+}
+/**
+ * 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 async function consumeLockedMagicLinkToken(client, tokenId) {
+    const result = await client.query(`UPDATE magic_link_tokens
+     SET used_at = NOW()
+     WHERE id = $1
+       AND used_at IS NULL
+       AND expires_at > NOW()
+     RETURNING id`, [tokenId]);
+    return result.rowCount === 1;
+}
+/**
+ * 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 async function consumeAuthorizedMagicLink(input) {
+    const client = await getPool().connect();
+    try {
+        await client.query('BEGIN');
+        const clientMatches = input.interactionUid === null && input.clientId === null
+            ? true
+            : input.interactionUid !== null &&
+                input.clientId !== null &&
+                (await lockActiveClientAuthority(client, input.clientId, input.organizationId));
+        if (!clientMatches) {
+            await client.query('ROLLBACK');
+            return null;
+        }
+        const token = await findAndLockMagicLinkToken(client, input.tokenHash, input.organizationId);
+        const authorityMatches = token !== null &&
+            token.accountStatus === 'active' &&
+            token.interactionUid === input.interactionUid;
+        if (!authorityMatches) {
+            await client.query('ROLLBACK');
+            return null;
+        }
+        const consumed = await consumeLockedMagicLinkToken(client, token.id);
+        if (!consumed) {
+            await client.query('ROLLBACK');
+            return null;
+        }
+        const accountUpdate = await client.query(`UPDATE users
+       SET email_verified = TRUE,
+           last_login_at = NOW(),
+           login_count = login_count + 1,
+           failed_login_count = 0,
+           last_failed_login_at = NULL
+       WHERE id = $1
+         AND organization_id = $2
+         AND status = 'active'
+       RETURNING id`, [token.userId, input.organizationId]);
+        if (accountUpdate.rowCount !== 1) {
+            await client.query('ROLLBACK');
+            return null;
+        }
+        await client.query(`INSERT INTO audit_log (
+         organization_id, user_id, event_type, event_category, description,
+         metadata, ip_address
+       )
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`, [
+            input.organizationId,
+            token.userId,
+            'user.login.magic_link',
+            'authentication',
+            'Magic link login successful',
+            '{}',
+            input.ipAddress ?? null,
+        ]);
+        await client.query('COMMIT');
+        return { userId: token.userId, interactionUid: token.interactionUid };
+    }
+    catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * 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 async function markTokenUsed(table, tokenId) {
+    assertValidTable(table);
+    const pool = getPool();
+    await pool.query(`UPDATE ${table} SET used_at = NOW() WHERE id = $1`, [tokenId]);
+    logger.debug({ table, tokenId }, 'Token marked as used');
+}
+/**
+ * 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 async function deleteExpiredTokens(table, olderThan) {
+    assertValidTable(table);
+    const pool = getPool();
+    const result = await pool.query(`DELETE FROM ${table}
+     WHERE expires_at < $1
+        OR (used_at IS NOT NULL AND used_at < $1)`, [olderThan]);
+    const count = result.rowCount ?? 0;
+    if (count > 0) {
+        logger.info({ table, count, olderThan: olderThan.toISOString() }, 'Expired tokens cleaned up');
+    }
+    return count;
+}
+/**
+ * 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 async function invalidateUserTokens(table, userId) {
+    assertValidTable(table);
+    const pool = getPool();
+    const result = await pool.query(`UPDATE ${table}
+     SET used_at = NOW()
+     WHERE user_id = $1
+       AND used_at IS NULL`, [userId]);
+    const count = result.rowCount ?? 0;
+    if (count > 0) {
+        logger.debug({ table, userId, count }, 'User tokens invalidated');
+    }
+}
+// ---------------------------------------------------------------------------
+// Invitation-specific operations
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function insertInvitationToken(userId, tokenHash, expiresAt, details, invitedBy) {
+    const pool = getPool();
+    await pool.query(`INSERT INTO invitation_tokens (user_id, token_hash, expires_at, details, invited_by)
+     VALUES ($1, $2, $3, $4, $5)`, [userId, tokenHash, expiresAt, details ? JSON.stringify(details) : null, invitedBy ?? null]);
+    logger.debug({ userId, hasDetails: !!details }, 'Invitation token inserted');
+}
+/**
+ * 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 async function findValidInvitationToken(tokenHash) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT id, user_id, token_hash, expires_at, used_at, created_at, details, invited_by
+     FROM invitation_tokens
+     WHERE token_hash = $1
+       AND used_at IS NULL
+       AND expires_at > NOW()`, [tokenHash]);
+    if (result.rows.length === 0) {
+        return null;
+    }
+    const row = result.rows[0];
+    return {
+        id: row.id,
+        userId: row.user_id,
+        tokenHash: row.token_hash,
+        expiresAt: row.expires_at,
+        usedAt: row.used_at,
+        createdAt: row.created_at,
+        details: row.details,
+        invitedBy: row.invited_by,
+    };
+}
+//# sourceMappingURL=token-repository.js.map

package/dist/auth/token-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-repository.js","sourceRoot":"","sources":["../../src/auth/token-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAiJ1C,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS;IACnC,mBAAmB;IACnB,uBAAuB;IACvB,mBAAmB;CACpB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,yBAAyB,KAAK,sBAAsB,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,aAAa,CAAC,GAAa;IAClC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAA8B,EAC9B,MAAc,EACd,SAAiB,EACjB,SAAe;IAEf,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,IAAI,CAAC,KAAK,CACd,eAAe,KAAK;yBACC,EACrB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAC/B,CAAC;IAEF,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,KAA+B;IAE/B,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,+CAA+C,EAAE;YACrF,KAAK,CAAC,MAAM;SACb,CAAC,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,CACjC,yDAAyD,EACzD,CAAC,KAAK,CAAC,aAAa,CAAC,CACtB,CAAC;QACF,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,KAAK,mBAAmB,EAAE,CAAC;YACxC,MAAM,aAAa,GACjB,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBACtD,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,KAAK,CAAC,cAAc,KAAK,IAAI;oBAC7B,KAAK,CAAC,QAAQ,KAAK,IAAI;oBACvB,CAAC,MAAM,yBAAyB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;YACtF,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC7B,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,CACjC;cACQ,KAAK,CAAC,KAAK;kCACS,EAC5B,CAAC,KAAK,CAAC,aAAa,CAAC,CACtB,CAAC;QACF,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC;QAC3D,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,KAAK,CACvC;cACQ,KAAK,CAAC,KAAK;;;;;eAKV,EACT,CAAC,KAAK,CAAC,MAAM,CAAC,CACf,CAAC;QACF,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,gBAAgB,GAAG,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACzD,MAAM,mBAAmB,GACvB,MAAM,KAAK,SAAS;YACpB,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,gBAAgB;gBAC7C,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,gBAAgB;oBAC/C,MAAM,CAAC,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;QACrD,IAAI,mBAAmB,EAAE,CAAC;YACxB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,MAAM,MAAM,CAAC,KAAK,CAChB,UAAU,KAAK,CAAC,KAAK;;qEAE0C,EAC/D,CAAC,KAAK,CAAC,MAAM,CAAC,CACf,CAAC;QACF,IAAI,KAAK,CAAC,KAAK,KAAK,mBAAmB,EAAE,CAAC;YACxC,MAAM,MAAM,CAAC,KAAK,CAChB;;yCAEiC,EACjC;gBACE,KAAK,CAAC,MAAM;gBACZ,KAAK,CAAC,SAAS;gBACf,KAAK,CAAC,SAAS;gBACf,KAAK,CAAC,aAAa;gBACnB,KAAK,CAAC,cAAc;gBACpB,KAAK,CAAC,cAAc;aACrB,CACF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,KAAK,CAChB;iCACyB,EACzB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CACtE,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC/B,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,yBAAyB,CACtC,MAAkB,EAClB,QAAgB,EAChB,cAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B;;;;;eAKW,EACX,CAAC,QAAQ,EAAE,cAAc,CAAC,CAC3B,CAAC;IACF,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAiB,EACjB,SAAiB;IAEjB,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;YACQ,KAAK;;;8BAGa,EAC1B,CAAC,SAAS,CAAC,CACZ,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,KAAiB,EACjB,SAAiB,EACjB,cAAsB;IAEtB,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;YAEQ,KAAK;;;;;oCAKmB,EAChC,CAAC,SAAS,EAAE,cAAc,CAAC,CAC5B,CAAC;IAEF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAkB,EAClB,SAAiB,EACjB,cAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B;;;;;;;;;;;;kCAY8B,EAC9B,CAAC,SAAS,EAAE,cAAc,CAAC,CAC5B,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO;QACL,GAAG,aAAa,CAAC,GAAG,CAAC;QACrB,cAAc,EAAE,GAAG,CAAC,eAAe;QACnC,cAAc,EAAE,GAAG,CAAC,eAAe;QACnC,aAAa,EAAE,GAAG,CAAC,cAAc;KAClC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAkB,EAClB,OAAe;IAEf,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B;;;;;kBAKc,EACd,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAAsC;IAEtC,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,aAAa,GACjB,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;YACtD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,CAAC,cAAc,KAAK,IAAI;gBAC7B,KAAK,CAAC,QAAQ,KAAK,IAAI;gBACvB,CAAC,MAAM,yBAAyB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;QACtF,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,yBAAyB,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;QAC7F,MAAM,gBAAgB,GACpB,KAAK,KAAK,IAAI;YACd,KAAK,CAAC,aAAa,KAAK,QAAQ;YAChC,KAAK,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc,CAAC;QAChD,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,2BAA2B,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,KAAK,CACtC;;;;;;;;;oBASc,EACd,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CACrC,CAAC;QACF,IAAI,aAAa,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,CAAC,KAAK,CAChB;;;;2CAIqC,EACrC;YACE,KAAK,CAAC,cAAc;YACpB,KAAK,CAAC,MAAM;YACZ,uBAAuB;YACvB,gBAAgB;YAChB,6BAA6B;YAC7B,IAAI;YACJ,KAAK,CAAC,SAAS,IAAI,IAAI;SACxB,CACF,CAAC;QACF,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC/B,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAiB,EAAE,OAAe;IACpE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,KAAK,oCAAoC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEjF,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,sBAAsB,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAAiB,EAAE,SAAe;IAC1E,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,eAAe,KAAK;;kDAE0B,EAC9C,CAAC,SAAS,CAAC,CACZ,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,EAAE,2BAA2B,CAAC,CAAC;IACjG,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAiB,EAAE,MAAc;IAC1E,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,UAAU,KAAK;;;2BAGQ,EACvB,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,yBAAyB,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,SAAiB,EACjB,SAAe,EACf,OAAwC,EACxC,SAAyB;IAEzB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,IAAI,CAAC,KAAK,CACd;iCAC6B,EAC7B,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,CAAC,CAC5F,CAAC;IAEF,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,2BAA2B,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,SAAiB;IAEjB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;;;8BAI0B,EAC1B,CAAC,SAAS,CAAC,CACZ,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/auth/tokens.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Token generation and hashing utilities.
+ *
+ * Used by all token-based auth flows: magic links, password resets, and invitations.
+ * Tokens are generated as cryptographically secure random bytes, then hashed with
+ * SHA-256 for storage. The plaintext goes in the email/URL; only the hash is stored
+ * in the database — so a DB breach never leaks usable tokens.
+ *
+ * @example
+ *   const { plaintext, hash } = generateToken();
+ *   // plaintext → email link
+ *   // hash → INSERT INTO magic_link_tokens (token_hash, ...)
+ *
+ *   // Later, when verifying:
+ *   const lookupHash = hashToken(plaintextFromUrl);
+ *   // SELECT ... WHERE token_hash = lookupHash
+ */
+/** Result of generating a new token — plaintext for the URL, hash for the DB */
+export interface GeneratedToken {
+    /** Base64url-encoded plaintext — included in the email/URL sent to the user */
+    plaintext: string;
+    /** SHA-256 hex digest — stored in the database for lookup */
+    hash: string;
+}
+/**
+ * Generate a cryptographically secure token.
+ *
+ * Returns both the plaintext (for the email/URL) and the SHA-256 hash (for DB storage).
+ * Uses 32 bytes of randomness (256 bits) which provides ample collision resistance
+ * and brute-force protection.
+ *
+ * @returns Object with `plaintext` (base64url) and `hash` (hex SHA-256)
+ */
+export declare function generateToken(): GeneratedToken;
+/**
+ * Hash a plaintext token for database lookup.
+ *
+ * Used during verification — the user provides the plaintext via URL, we hash it
+ * and look up the matching row in the token table.
+ *
+ * @param plaintext - The base64url token string from the URL
+ * @returns SHA-256 hex digest for database lookup
+ */
+export declare function hashToken(plaintext: string): string;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,cAAc,CAI9C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/auth/tokens.js

@@ -0,0 +1,51 @@
+/**
+ * Token generation and hashing utilities.
+ *
+ * Used by all token-based auth flows: magic links, password resets, and invitations.
+ * Tokens are generated as cryptographically secure random bytes, then hashed with
+ * SHA-256 for storage. The plaintext goes in the email/URL; only the hash is stored
+ * in the database — so a DB breach never leaks usable tokens.
+ *
+ * @example
+ *   const { plaintext, hash } = generateToken();
+ *   // plaintext → email link
+ *   // hash → INSERT INTO magic_link_tokens (token_hash, ...)
+ *
+ *   // Later, when verifying:
+ *   const lookupHash = hashToken(plaintextFromUrl);
+ *   // SELECT ... WHERE token_hash = lookupHash
+ */
+import crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Token generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a cryptographically secure token.
+ *
+ * Returns both the plaintext (for the email/URL) and the SHA-256 hash (for DB storage).
+ * Uses 32 bytes of randomness (256 bits) which provides ample collision resistance
+ * and brute-force protection.
+ *
+ * @returns Object with `plaintext` (base64url) and `hash` (hex SHA-256)
+ */
+export function generateToken() {
+    const plaintext = crypto.randomBytes(32).toString('base64url');
+    const hash = crypto.createHash('sha256').update(plaintext).digest('hex');
+    return { plaintext, hash };
+}
+// ---------------------------------------------------------------------------
+// Token hashing
+// ---------------------------------------------------------------------------
+/**
+ * Hash a plaintext token for database lookup.
+ *
+ * Used during verification — the user provides the plaintext via URL, we hash it
+ * and look up the matching row in the token table.
+ *
+ * @param plaintext - The base64url token string from the URL
+ * @returns SHA-256 hex digest for database lookup
+ */
+export function hashToken(plaintext) {
+    return crypto.createHash('sha256').update(plaintext).digest('hex');
+}
+//# sourceMappingURL=tokens.js.map

package/dist/auth/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAcjC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/dist/cli/bootstrap.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CLI bootstrap — direct-DB execution mode for infrastructure commands.
+ *
+ * Provides `withBootstrap()` for commands that need direct database/Redis
+ * access (init, migrate, seed, health --direct, user 2fa --direct).
+ *
+ * These commands run before or without the HTTP server, so they connect
+ * directly to PostgreSQL + Redis. The HTTP-based admin commands have been
+ * extracted to the standalone `@portaidentity/cli` package.
+ *
+ * Uses dynamic imports so that the config module (which validates env vars
+ * at load time) isn't triggered until bootstrap() is called. This allows
+ * CLI flag overrides (--database-url, --redis-url) to set process.env
+ * BEFORE config parses, making the overrides effective.
+ *
+ * @module cli/bootstrap
+ */
+import 'dotenv/config';
+import type { GlobalOptions } from './index.js';
+/**
+ * Bootstrap the CLI environment: load dotenv, connect DB + Redis.
+ *
+ * CLI flags (--database-url, --redis-url) override env vars if provided.
+ * The overrides are applied to process.env BEFORE the config module loads,
+ * so they propagate through to connectDatabase() and connectRedis().
+ *
+ * @param argv - Parsed CLI global options from yargs
+ */
+export declare function bootstrap(argv: GlobalOptions): Promise<void>;
+/**
+ * Clean shutdown: disconnect Redis then DB.
+ *
+ * Redis is disconnected first because some operations may flush
+ * cache entries to the database during shutdown.
+ */
+export declare function shutdown(): Promise<void>;
+/**
+ * Convenience wrapper: bootstrap → run command → shutdown.
+ *
+ * Ensures cleanup happens even if the command throws an error.
+ * This is the recommended way for command handlers to use bootstrap:
+ *
+ * ```typescript
+ * await withBootstrap(argv, async () => {
+ *   const orgs = await listOrganizations(pool);
+ *   printTable(headers, rows);
+ * });
+ * ```
+ *
+ * @param argv - Parsed CLI global options from yargs
+ * @param fn - The command handler function to execute
+ * @returns The return value of the command handler
+ */
+export declare function withBootstrap<T>(argv: GlobalOptions, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/cli/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BlE;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAOZ"}