@ibgib/node-gib 0.0.14 → 0.0.17

package/src/email/email-helpers.mts

@@ -20,7 +20,6 @@ export function validateEmailAddress(email: string): boolean {
     return validateEmail(email);
 }
 
-
 /**
  * Sanitizes header values by stripping carriage return (\r) and newline (\n) characters
  * to prevent MIME header injection.

package/src/email/index.mts

@@ -5,6 +5,9 @@
 export * from './email-constants.mjs';
 export * from './email-types.mjs';
 export * from './email-helpers.mjs';
+export * from './verify/email-verify-constants.mjs';
+export * from './verify/email-verify-types.mjs';
+export * from './verify/email-verify-helpers.mjs';
 export * from './email-sender.mjs';
 export * from './email-receiver.mjs';
 export * from './aws/index.mjs';

package/src/email/verify/email-verify-constants.mts

@@ -0,0 +1,3 @@
+
+/** Default TTL for magic link tokens: 15 minutes in ms. */
+export const DEFAULT_MAGIC_LINK_TTL_MS = 15 * 60 * 1000;

package/src/email/verify/email-verify-helpers.mts

@@ -0,0 +1,466 @@
+import { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { EmailSender, OutboundEmail } from '../email-types.mjs';
+import { EmailSenderAws } from '../aws/email-sender-aws.mjs';
+import { EmailSenderMock } from '../mock/email-sender-mock.mjs';
+import { validateEmail } from '../email-helpers.mjs';
+import { normalizeEmail } from '../../serve-gib/identity-index/identity-index-helpers.mjs';
+import { DEFAULT_IDENTITY_INDEX_SALT, DEFAULT_IDENTITY_INDEX_DIR_NAME } from '../../serve-gib/identity-index/identity-index-constants.mjs';
+import { DEFAULT_MAGIC_LINK_TTL_MS } from './email-verify-constants.mjs';
+import { CreateMagicLinkTokenOptions, MagicLinkTokenPayload, PendingStagingDirInfo, SavePendingStagingKeystoneOptions, SavePendingStagingKeystoneResult, VerifyMagicLinkTokenOptions, VerifyMagicLinkTokenResult } from './email-verify-types.mjs';
+
+/** In-memory store for tracking single-use nonces mapped to expiration timestamps. */
+const consumedNonces = new Map<string, number>();
+
+/**
+ * Gets the secret key used for signing and verifying magic link tokens.
+ */
+export function getMagicLinkSecret(): string {
+    return process.env.MAGIC_LINK_SECRET || process.env.IDENTITY_INDEX_SALT || DEFAULT_IDENTITY_INDEX_SALT;
+}
+
+/**
+ * Generates a signed, single-use 15-minute verification token containing email and primaryTjpAddr.
+ */
+export function createMagicLinkToken({
+    email,
+    primaryTjpAddr,
+    ttlMs = DEFAULT_MAGIC_LINK_TTL_MS,
+    secret,
+    nonce,
+}: CreateMagicLinkTokenOptions): string {
+    if (!email || !validateEmail(email)) {
+        throw new Error(`Invalid email address provided for magic link token creation: ${email} (E: a9b8c7d6e5f43210123456789abcdef0)`);
+    }
+    if (!primaryTjpAddr) {
+        throw new Error(`primaryTjpAddr is required for magic link token creation (E: b8c7d6e5f43210123456789abcdef01)`);
+    }
+
+    const exp = Date.now() + ttlMs;
+    const tokenNonce = nonce || randomUUID();
+
+    const payload: MagicLinkTokenPayload = {
+        email,
+        primaryTjpAddr,
+        exp,
+        nonce: tokenNonce,
+    };
+
+    const payloadJson = JSON.stringify(payload);
+    const payloadBase64 = Buffer.from(payloadJson, 'utf-8').toString('base64url');
+
+    const signingSecret = secret || getMagicLinkSecret();
+    const signature = createHmac('sha256', signingSecret)
+        .update(payloadBase64)
+        .digest('base64url');
+
+    return `${payloadBase64}.${signature}`;
+}
+
+/**
+ * Verifies a magic link token's HMAC signature, expiration time, and single-use status.
+ */
+export function verifyMagicLinkToken({
+    token,
+    secret,
+}: VerifyMagicLinkTokenOptions): VerifyMagicLinkTokenResult {
+    try {
+        if (!token || typeof token !== 'string') {
+            return { valid: false, error: 'Token must be a non-empty string. (E: c7d6e5f43210123456789abcdef012)' };
+        }
+
+        const parts = token.split('.');
+        if (parts.length !== 2) {
+            return { valid: false, error: 'Malformed token structure. Expected two dot-separated parts. (E: d6e5f43210123456789abcdef0123)' };
+        }
+
+        const [payloadBase64, providedSignature] = parts;
+        const signingSecret = secret || getMagicLinkSecret();
+
+        const expectedSignature = createHmac('sha256', signingSecret)
+            .update(payloadBase64)
+            .digest('base64url');
+
+        // Timing-safe signature comparison
+        const sigBufA = Buffer.from(providedSignature, 'utf-8');
+        const sigBufB = Buffer.from(expectedSignature, 'utf-8');
+
+        if (sigBufA.length !== sigBufB.length || !timingSafeEqual(sigBufA, sigBufB)) {
+            return { valid: false, error: 'Invalid token signature. (E: e5f43210123456789abcdef01234)' };
+        }
+
+        const payloadJson = Buffer.from(payloadBase64, 'base64url').toString('utf-8');
+        const payload: MagicLinkTokenPayload = JSON.parse(payloadJson);
+
+        if (!payload.email || !payload.primaryTjpAddr || !payload.exp || !payload.nonce) {
+            return { valid: false, error: 'Missing required fields in token payload. (E: f43210123456789abcdef012345)' };
+        }
+
+        if (Date.now() > payload.exp) {
+            return { valid: false, error: 'Token has expired. (E: 43210123456789abcdef0123456)' };
+        }
+
+        if (isNonceUsed(payload.nonce)) {
+            return { valid: false, error: 'Token has already been used. (E: 3210123456789abcdef01234567)' };
+        }
+
+        return { valid: true, payload };
+    } catch (error) {
+        return { valid: false, error: `Failed to verify token: ${extractErrorMsg(error)} (E: 210123456789abcdef012345678)` };
+    }
+}
+
+/**
+ * Checks if a token nonce has already been consumed.
+ */
+export function isNonceUsed(nonce: string): boolean {
+    pruneExpiredNonces();
+    return consumedNonces.has(nonce);
+}
+
+/**
+ * Marks a token nonce as consumed, preventing replay.
+ */
+export function markNonceUsed(nonce: string, exp?: number): void {
+    const expiresAt = exp || Date.now() + DEFAULT_MAGIC_LINK_TTL_MS;
+    consumedNonces.set(nonce, expiresAt);
+}
+
+/**
+ * Helper for tests to reset consumed nonces state.
+ */
+export function clearConsumedNonces(): void {
+    consumedNonces.clear();
+}
+
+/**
+ * Internal helper to clean up expired nonces from memory.
+ */
+function pruneExpiredNonces(): void {
+    const now = Date.now();
+    for (const [nonce, exp] of consumedNonces.entries()) {
+        if (now > exp) {
+            consumedNonces.delete(nonce);
+        }
+    }
+}
+
+/**
+ * Saves or updates a pending staging directory for an unverified keystone and its associated emails.
+ *
+ * Folder structure created:
+ * `<dataDir>/identity_index/email/pending/<expiryTicks>_<tjpHash>/`
+ *   ├── keystone.json (serialized keystone DTO if provided)
+ *   └── emails/
+ *       └── <emailHash>.json ({ email, verified: false, verifiedAt: null })
+ */
+export async function savePendingStagingKeystone({
+    keystone,
+    emails,
+    dataDir,
+    ttlMs = DEFAULT_MAGIC_LINK_TTL_MS,
+    primaryTjpAddr: inputPrimaryTjpAddr,
+}: SavePendingStagingKeystoneOptions): Promise<SavePendingStagingKeystoneResult> {
+    if (!dataDir) {
+        throw new Error('dataDir is required for savePendingStagingKeystone (E: 87123456789abcdef0123456789a0123)');
+    }
+    if (!emails || !Array.isArray(emails) || emails.length === 0) {
+        throw new Error('emails array must be a non-empty array of strings (E: 98123456789abcdef0123456789a0124)');
+    }
+
+    const targetTjpAddr = inputPrimaryTjpAddr || keystone?.data?.tjpAddr || keystone?.ib;
+    if (!targetTjpAddr) {
+        throw new Error('Primary identity TJP address could not be derived from options or keystone (E: 09123456789abcdef0123456789a0125)');
+    }
+
+    const tjpHash = await hash({ s: `emailindex${targetTjpAddr}` });
+    const expiryTicks = Date.now() + ttlMs;
+
+    const pendingBaseDir = path.join(dataDir, DEFAULT_IDENTITY_INDEX_DIR_NAME, 'email', 'pending');
+
+    // Remove any existing pending directory for this tjpHash to maintain a single active staging entry
+    try {
+        if (existsSync(pendingBaseDir)) {
+            const entries = await fs.readdir(pendingBaseDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory() && entry.name.endsWith(`_${tjpHash}`)) {
+                    const oldDir = path.join(pendingBaseDir, entry.name);
+                    await fs.rm(oldDir, { recursive: true, force: true });
+                }
+            }
+        }
+    } catch { /* ignore directory reading errors */ }
+
+    const pendingDir = path.join(pendingBaseDir, `${expiryTicks}_${tjpHash}`);
+    const emailsDir = path.join(pendingDir, 'emails');
+
+    await fs.mkdir(emailsDir, { recursive: true });
+
+    if (keystone) {
+        const keystonePath = path.join(pendingDir, 'keystone.json');
+        await fs.writeFile(keystonePath, JSON.stringify(keystone, null, 2), 'utf-8');
+    }
+
+    for (const email of emails) {
+        const normEmail = normalizeEmail(email);
+        const emailHash = await hash({ s: `emailindex${normEmail}` });
+        const emailMetaPath = path.join(emailsDir, `${emailHash}.json`);
+        const meta = {
+            email: normEmail,
+            verified: false,
+            verifiedAt: null,
+        };
+        await fs.writeFile(emailMetaPath, JSON.stringify(meta, null, 2), 'utf-8');
+    }
+
+    return {
+        pendingDir,
+        expiryTicks,
+        tjpHash,
+    };
+}
+
+/**
+ * Generates a 6-digit numeric verification code string (e.g. "482901").
+ */
+export function generateVerificationCode(): string {
+    const codeNum = Math.floor(100000 + Math.random() * 900000);
+    return codeNum.toString();
+}
+
+export interface SavePendingCodeRecordOptions {
+    pendingDir: string;
+    code: string;
+    maxAttempts?: number;
+    ttlMs?: number;
+}
+
+export interface PendingCodeRecord {
+    codeHash: string;
+    attempts: number;
+    maxAttempts: number;
+    expiresAt: number;
+}
+
+/**
+ * Saves a hashed 6-digit verification code record to `code.json` in the pending staging directory.
+ */
+export async function savePendingCodeRecord({
+    pendingDir,
+    code,
+    maxAttempts = 5,
+    ttlMs = DEFAULT_MAGIC_LINK_TTL_MS,
+}: SavePendingCodeRecordOptions): Promise<void> {
+    const codeHash = await hash({ s: `verificationcode${code}` });
+    const record: PendingCodeRecord = {
+        codeHash,
+        attempts: 0,
+        maxAttempts,
+        expiresAt: Date.now() + ttlMs,
+    };
+    const codeFilePath = path.join(pendingDir, 'code.json');
+    await fs.writeFile(codeFilePath, JSON.stringify(record, null, 2), 'utf-8');
+}
+
+/**
+ * Creates a default EmailSender instance based on process.env.EMAIL_MODE and NODE_ENV.
+ */
+export function createDefaultEmailSender(): EmailSender {
+    const isProd = process.env.NODE_ENV === 'production';
+    const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
+    if (mode === 'aws') {
+        return new EmailSenderAws({
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+            region: process.env.AWS_REGION || 'us-east-1',
+        });
+    } else if (mode === 'mock') {
+        if (isProd) {
+            throw new Error('EMAIL_MODE=mock is prohibited when NODE_ENV=production. (E: 897a6b5c4d3e2f10987654321fedcba0)');
+        }
+        return new EmailSenderMock();
+    } else {
+        throw new Error(`Unsupported EMAIL_MODE '${mode}'. Must be 'aws' or 'mock'. (E: 987a6b5c4d3e2f10987654321fedcba1)`);
+    }
+}
+
+/**
+ * Generates a 6-digit OTP code, writes `code.json` to the pending staging directory,
+ * and dispatches an email via the active `EmailSender` driver.
+ */
+export async function dispatchVerificationCode({
+    email,
+    primaryTjpAddr,
+    pendingDir,
+    sender,
+}: {
+    email: string;
+    primaryTjpAddr: string;
+    pendingDir: string;
+    sender?: EmailSender;
+}): Promise<{ success: boolean; code?: string; messageId?: string; error?: string }> {
+    const code = generateVerificationCode();
+    await savePendingCodeRecord({ pendingDir, code });
+
+    const activeSender = sender || createDefaultEmailSender();
+    const outboundEmail: OutboundEmail = {
+        from: process.env.AWS_SES_FROM_EMAIL || 'noreply@ibgib.com',
+        to: [email],
+        subject: 'Verify your Ibgib Identity Email',
+        textBody: `Hello,\n\nYour 6-digit verification code for your Ibgib identity is:\n\n${code}\n\nThis code will expire in 15 minutes.\n\nIf you did not request this, please ignore this email.`,
+        htmlBody: `<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; border: 1px solid #e0e0e0; border-radius: 8px;">
+<h2>Verify your Ibgib Identity Email</h2>
+<p>Your 6-digit verification code is:</p>
+<h1 style="font-family: monospace; font-size: 36px; letter-spacing: 6px; color: #4f46e5; margin: 24px 0;">${code}</h1>
+<p style="font-size: 12px; color: #999;">This code will expire in 15 minutes.</p>
+</div>`,
+    };
+
+    const sendResult = await activeSender.sendEmail(outboundEmail);
+
+    const isProd = process.env.NODE_ENV === 'production';
+    const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
+    if (sendResult.success && (mode === 'mock' || !isProd)) {
+        console.log(`✉️ [EmailSenderMock] Verification Code for ${email}: ${code} (I: c123456789abcdef0123456789abcdef)`);
+    }
+
+    return {
+        success: sendResult.success,
+        code,
+        messageId: sendResult.messageId,
+        error: sendResult.error,
+    };
+}
+
+export interface VerifyPendingCodeOptions {
+    pendingDir: string;
+    code: string;
+}
+
+export interface VerifyPendingCodeResult {
+    valid: boolean;
+    error?: string;
+    reason?: 'expired' | 'too_many_attempts' | 'invalid_code';
+}
+
+/**
+ * Validates a 6-digit verification code against `code.json` in the pending staging directory.
+ * Increments `attempts`. Enforces 5-attempt rate limit.
+ */
+export async function verifyPendingCode({
+    pendingDir,
+    code,
+}: VerifyPendingCodeOptions): Promise<VerifyPendingCodeResult> {
+    const codeFilePath = path.join(pendingDir, 'code.json');
+    if (!existsSync(codeFilePath)) {
+        return { valid: false, error: 'Verification code record not found. Please click "Resend Code" to request a new code.', reason: 'invalid_code' };
+    }
+
+    const raw = await fs.readFile(codeFilePath, 'utf-8');
+    const record: PendingCodeRecord = JSON.parse(raw);
+
+    if (Date.now() > record.expiresAt) {
+        return { valid: false, error: 'Verification code has expired. Please click "Resend Code" for a new code.', reason: 'expired' };
+    }
+
+    if (record.attempts >= record.maxAttempts) {
+        return { valid: false, error: 'Too many incorrect attempts. Please click "Resend Code" for a new code.', reason: 'too_many_attempts' };
+    }
+
+    record.attempts += 1;
+    await fs.writeFile(codeFilePath, JSON.stringify(record, null, 2), 'utf-8');
+
+    const inputHash = await hash({ s: `verificationcode${code.trim()}` });
+    if (inputHash !== record.codeHash) {
+        const remaining = record.maxAttempts - record.attempts;
+        if (remaining <= 0) {
+            return { valid: false, error: 'Too many incorrect attempts. Please click "Resend Code" for a new code.', reason: 'too_many_attempts' };
+        }
+        return { valid: false, error: `Incorrect verification code. (${remaining} attempt${remaining === 1 ? '' : 's'} remaining)`, reason: 'invalid_code' };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Helper to derive consistent tjpHash for email staging quarantine directories.
+ */
+export async function getPendingTjpHash(primaryTjpAddr: string): Promise<string> {
+    return await hash({ s: `emailindex${primaryTjpAddr}` });
+}
+
+/**
+ * Locates the pending staging directory for a given tjpHash under `<dataDir>/identity_index/email/pending/`.
+ */
+export async function getPendingStagingDir({
+    dataDir,
+    tjpHash,
+}: {
+    dataDir: string;
+    tjpHash: string;
+}): Promise<PendingStagingDirInfo | undefined> {
+    const pendingBaseDir = path.join(dataDir, DEFAULT_IDENTITY_INDEX_DIR_NAME, 'email', 'pending');
+    try {
+        const entries = await fs.readdir(pendingBaseDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.endsWith(`_${tjpHash}`)) {
+                const parts = entry.name.split('_');
+                const expiryTicks = parseInt(parts[0], 10);
+                const pendingDir = path.join(pendingBaseDir, entry.name);
+                const isExpired = Date.now() > expiryTicks;
+                return { pendingDir, expiryTicks, tjpHash, isExpired };
+            }
+        }
+        return undefined;
+    } catch (err: any) {
+        if (err.code === 'ENOENT') {
+            return undefined;
+        }
+        throw err;
+    }
+}
+
+/**
+ * Executes garbage collection on expired staging directories using an OS atomic lockfile (`.gc.lock` with `flag: 'wx'`).
+ */
+export async function performPendingGc({ dataDir }: { dataDir: string }): Promise<number> {
+    const pendingBaseDir = path.join(dataDir, DEFAULT_IDENTITY_INDEX_DIR_NAME, 'email', 'pending');
+    const lockFile = path.join(pendingBaseDir, '.gc.lock');
+    let lockAcquired = false;
+
+    try {
+        await fs.mkdir(pendingBaseDir, { recursive: true });
+        await fs.writeFile(lockFile, JSON.stringify({ pid: process.pid, lockedAt: Date.now() }), { flag: 'wx' });
+        lockAcquired = true;
+
+        const entries = await fs.readdir(pendingBaseDir, { withFileTypes: true });
+        const now = Date.now();
+        let cleanedCount = 0;
+
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.includes('_')) {
+                const parts = entry.name.split('_');
+                const expiryTicks = parseInt(parts[0], 10);
+                if (!isNaN(expiryTicks) && now > expiryTicks) {
+                    const dirToRemove = path.join(pendingBaseDir, entry.name);
+                    await fs.rm(dirToRemove, { recursive: true, force: true });
+                    cleanedCount++;
+                }
+            }
+        }
+        return cleanedCount;
+    } catch (err: any) {
+        if (err.code === 'EEXIST') {
+            // Lockfile already exists, another process is executing GC
+            return 0;
+        }
+        throw err;
+    } finally {
+        if (lockAcquired) {
+            try { await fs.unlink(lockFile); } catch { /* ignore */ }
+        }
+    }
+}

package/src/email/verify/email-verify-types.mts

@@ -0,0 +1,47 @@
+
+export interface MagicLinkTokenPayload {
+    email: string;
+    primaryTjpAddr: string;
+    exp: number;
+    nonce: string;
+}
+
+export interface CreateMagicLinkTokenOptions {
+    email: string;
+    primaryTjpAddr: string;
+    ttlMs?: number;
+    secret?: string;
+    nonce?: string;
+}
+
+export interface VerifyMagicLinkTokenOptions {
+    token: string;
+    secret?: string;
+}
+
+export interface VerifyMagicLinkTokenResult {
+    valid: boolean;
+    error?: string;
+    payload?: MagicLinkTokenPayload;
+}
+
+export interface SavePendingStagingKeystoneOptions {
+    keystone?: any;
+    emails: string[];
+    dataDir: string;
+    ttlMs?: number;
+    primaryTjpAddr?: string;
+}
+
+export interface SavePendingStagingKeystoneResult {
+    pendingDir: string;
+    expiryTicks: number;
+    tjpHash: string;
+}
+
+export interface PendingStagingDirInfo {
+    pendingDir: string;
+    expiryTicks: number;
+    tjpHash: string;
+    isExpired: boolean;
+}

package/src/identity/sso/custodian-auth-helpers.mts

@@ -0,0 +1,146 @@
+import { getUUID, hash, HashAlgorithm, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { kdf_recursiveSaltWrap } from '@ibgib/core-gib/dist/keystone/kdf/kdf-helpers.mjs';
+import { KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+import { CustodianRequirements } from './sso-types.mjs';
+
+/**
+ * Derives a deterministic single-turn authorization code using the server's private KDF secret
+ * and the JSON-stringified `custodianReqs` (excluding `authCode` itself) as salt.
+ *
+ * @param custodianReqsOmitAuthCode The custodian requirements object omitting the `authCode` property.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export async function deriveCustodianAuthCode({
+    custodianReqsOmitAuthCode,
+    serverSecret,
+}: {
+    custodianReqsOmitAuthCode: Omit<CustodianRequirements, 'authCode'>;
+    serverSecret: string;
+}): Promise<string> {
+    const lc = `[${deriveCustodianAuthCode.name}]`;
+    try {
+        if (!serverSecret) {
+            throw new Error('serverSecret required for custodian auth code derivation (E: a1b2c3d4e5f67890123456789abcdef0)');
+        }
+
+        const salt = await hash({
+            s: JSON.stringify(custodianReqsOmitAuthCode),
+            algorithm: HashAlgorithm.sha_512
+        });
+
+        return await kdf_recursiveSaltWrap({
+            masterSecret: serverSecret,
+            salt,
+            rounds: 1000,
+            algorithm: HashAlgorithm.sha_512
+        });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Generates a full `CustodianRequirements` object containing single-turn nonce,
+ * expiration timestamp, permitted verbs, and derived auth code.
+ *
+ * @param primaryTjpAddr Primary identity keystone TJP address (`ib^gib`).
+ * @param ttlMs Time-to-live duration in milliseconds. Defaults to 15 minutes.
+ * @param allowedVerbs Permitted keystone verbs. Defaults to `['sync', 'connect']`.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export async function generateCustodianRequirements({
+    primaryTjpAddr,
+    ttlMs = 15 * 60 * 1000,
+    allowedVerbs = [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT],
+    serverSecret,
+}: {
+    primaryTjpAddr: string;
+    ttlMs?: number;
+    allowedVerbs?: string[];
+    serverSecret: string;
+}): Promise<CustodianRequirements> {
+    const lc = `[${generateCustodianRequirements.name}]`;
+    try {
+        if (!primaryTjpAddr) {
+            throw new Error('primaryTjpAddr is required to generate custodian requirements (E: b2c3d4e5f67890123456789abcdef01)');
+        }
+        if (!serverSecret) {
+            throw new Error('serverSecret is required to generate custodian requirements (E: c3d4e5f67890123456789abcdef012)');
+        }
+
+        const nonce = await getUUID();
+        const expiresAt = Date.now() + ttlMs;
+
+        const custodianReqsOmitAuthCode: Omit<CustodianRequirements, 'authCode'> = {
+            primaryTjpAddr,
+            nonce,
+            expiresAt,
+            allowedVerbs,
+        };
+
+        const authCode = await deriveCustodianAuthCode({
+            custodianReqsOmitAuthCode,
+            serverSecret
+        });
+
+        return {
+            ...custodianReqsOmitAuthCode,
+            authCode
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Computes the deterministic index hash (`authCustodianIndex`) over the full `CustodianRequirements` object
+ * used for atomic file reservation tracking on the server filesystem.
+ */
+export async function getAuthCustodianIndex({
+    custodianReqs,
+}: {
+    custodianReqs: CustodianRequirements;
+}): Promise<string> {
+    return await hash({
+        s: JSON.stringify(custodianReqs),
+        algorithm: HashAlgorithm.sha_256
+    });
+}
+
+/**
+ * Cryptographically verifies a `CustodianRequirements` object against expiration and server KDF authCode match.
+ */
+export async function verifyCustodianRequirements({
+    custodianReqs,
+    serverSecret,
+}: {
+    custodianReqs: CustodianRequirements;
+    serverSecret: string;
+}): Promise<{ valid: boolean; error?: string }> {
+    try {
+        if (!custodianReqs || !custodianReqs.authCode || !custodianReqs.nonce || !custodianReqs.expiresAt || !custodianReqs.primaryTjpAddr) {
+            return { valid: false, error: 'Malformed custodian requirements structure. (E: d4e5f67890123456789abcdef0123)' };
+        }
+
+        if (Date.now() > custodianReqs.expiresAt) {
+            return { valid: false, error: 'Custodian requirements have expired. (E: e5f67890123456789abcdef01234)' };
+        }
+
+        const { authCode, ...custodianReqsOmitAuthCode } = custodianReqs;
+        const expectedAuthCode = await deriveCustodianAuthCode({
+            custodianReqsOmitAuthCode,
+            serverSecret
+        });
+
+        if (authCode !== expectedAuthCode) {
+            return { valid: false, error: 'Cryptographic authCode mismatch. Requirement payload tampered or invalid. (E: f67890123456789abcdef012345)' };
+        }
+
+        return { valid: true };
+    } catch (error) {
+        return { valid: false, error: `Verification failed: ${extractErrorMsg(error)} (E: 7890123456789abcdef0123456)` };
+    }
+}