@ibgib/node-gib 0.0.14 → 0.0.15

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/sso-config-helper.mts

@@ -0,0 +1,52 @@
+import { SsoServerConfig, SsoProviderServerConfig, SsoProviderId } from './sso-types.mjs';
+
+/**
+ * Loads the SSO configuration from environment variables.
+ * Parses active OAuth2 providers dynamically based on their environment keys.
+ */
+export function loadSsoServerConfig(): SsoServerConfig {
+    const ssoServerKdfSecret = process.env.SSO_SERVER_KDF_SECRET;
+    const sessionSecret = process.env.SESSION_SECRET;
+
+    if (!ssoServerKdfSecret) {
+        throw new Error(
+            `SSO_SERVER_KDF_SECRET is missing from environment. (E: 840899ab4fdfd23e89cfae1889cfae12)`
+        );
+    }
+    if (!sessionSecret) {
+        throw new Error(
+            `SESSION_SECRET is missing from environment. (E: bfa899ab4fdfd23e89cfae23)`
+        );
+    }
+
+    const providers: Partial<Record<SsoProviderId, SsoProviderServerConfig>> = {};
+
+    // Load Google Provider if configured
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        providers.google = {
+            providerId: 'google',
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+            tokenUrl: 'https://oauth2.googleapis.com/token',
+            userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+            jwksUrl: 'https://www.googleapis.com/oauth2/v3/certs'
+        };
+    }
+
+    // Load GitHub Provider if configured
+    if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+        providers.github = {
+            providerId: 'github',
+            clientId: process.env.GITHUB_CLIENT_ID,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET,
+            tokenUrl: 'https://github.com/login/oauth/access_token',
+            userInfoUrl: 'https://api.github.com/user'
+        };
+    }
+
+    return {
+        ssoServerKdfSecret,
+        sessionSecret,
+        providers
+    };
+}