@ibgib/node-gib 0.0.15 → 0.0.18

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

@@ -269,12 +269,23 @@ export async function savePendingCodeRecord({
  * Creates a default EmailSender instance based on process.env.EMAIL_MODE and NODE_ENV.
  */
 export function createDefaultEmailSender(): EmailSender {
+    const rawMode = process.env.EMAIL_MODE;
+    if (!rawMode || !rawMode.trim()) {
+        throw new Error('EMAIL_MODE environment variable is missing. Expected "aws" or "mock". (E: 7a8b9c0d1e2f3456789abcdef0123456)');
+    }
+
+    const mode = rawMode.trim().toLowerCase();
     const isProd = process.env.NODE_ENV === 'production';
-    const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
+
     if (mode === 'aws') {
+        const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+        const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+        if (!accessKeyId || !secretAccessKey) {
+            throw new Error('EMAIL_MODE=aws requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. (E: 5e6f7890123456789abcdef5a6b7c8d9)');
+        }
         return new EmailSenderAws({
-            accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
-            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+            accessKeyId,
+            secretAccessKey,
             region: process.env.AWS_REGION || 'us-east-1',
         });
     } else if (mode === 'mock') {

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)` };
+    }
+}

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

@@ -0,0 +1,97 @@
+import {
+    respecfully,
+    iReckon,
+    ifWe
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import {
+    deriveCustodianAuthCode,
+    generateCustodianRequirements,
+    getAuthCustodianIndex,
+    verifyCustodianRequirements
+} from './custodian-auth-helpers.mjs';
+
+const maam = `[${import.meta.url}]`, sir = maam;
+
+await respecfully(sir, 'CustodianAuthHelpers', async () => {
+    const serverSecret = 'test-server-kdf-secret-123456789';
+    const primaryTjpAddr = 'keystone^1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+
+    await ifWe(sir, 'generate custodian requirements cleanly with derived auth code', async () => {
+        const reqs = await generateCustodianRequirements({
+            primaryTjpAddr,
+            serverSecret,
+            ttlMs: 60 * 1000,
+            allowedVerbs: ['sync', 'connect']
+        });
+
+        iReckon(sir, reqs).not.isGonnaBeUndefined();
+        iReckon(sir, reqs.primaryTjpAddr).isGonnaBe(primaryTjpAddr);
+        iReckon(sir, reqs.allowedVerbs).willEqual(['sync', 'connect']);
+        iReckon(sir, reqs.nonce.length > 10).isGonnaBeTrue();
+        iReckon(sir, reqs.authCode.length > 20).isGonnaBeTrue();
+        iReckon(sir, reqs.expiresAt > Date.now()).isGonnaBeTrue();
+    });
+
+    await ifWe(sir, 'verify valid custodian requirements successfully', async () => {
+        const reqs = await generateCustodianRequirements({
+            primaryTjpAddr,
+            serverSecret,
+        });
+
+        const verifyRes = await verifyCustodianRequirements({
+            custodianReqs: reqs,
+            serverSecret
+        });
+
+        iReckon(sir, verifyRes.valid).isGonnaBeTrue();
+        iReckon(sir, verifyRes.error).isGonnaBeUndefined();
+    });
+
+    await ifWe(sir, 'fail verification if payload or authCode is tampered', async () => {
+        const reqs = await generateCustodianRequirements({
+            primaryTjpAddr,
+            serverSecret,
+        });
+
+        // Tamper with allowedVerbs
+        const tamperedReqs = { ...reqs, allowedVerbs: ['sync', 'connect', 'manage'] };
+
+        const verifyRes = await verifyCustodianRequirements({
+            custodianReqs: tamperedReqs,
+            serverSecret
+        });
+
+        iReckon(sir, verifyRes.valid).isGonnaBeFalse();
+        iReckon(sir, verifyRes.error).includes('mismatch');
+    });
+
+    await ifWe(sir, 'fail verification if requirements are expired', async () => {
+        const expiredReqs = await generateCustodianRequirements({
+            primaryTjpAddr,
+            serverSecret,
+            ttlMs: -1000 // expired 1s ago
+        });
+
+        const verifyRes = await verifyCustodianRequirements({
+            custodianReqs: expiredReqs,
+            serverSecret
+        });
+
+        iReckon(sir, verifyRes.valid).isGonnaBeFalse();
+        iReckon(sir, verifyRes.error).includes('expired');
+    });
+
+    await ifWe(sir, 'calculate deterministic authCustodianIndex for atomic file reservation', async () => {
+        const reqs = await generateCustodianRequirements({
+            primaryTjpAddr,
+            serverSecret,
+        });
+
+        const index1 = await getAuthCustodianIndex({ custodianReqs: reqs });
+        const index2 = await getAuthCustodianIndex({ custodianReqs: reqs });
+
+        iReckon(sir, index1).isGonnaBe(index2);
+        iReckon(sir, index1.length).isGonnaBe(64); // SHA-256 hash length
+    });
+});

package/src/identity/sso/sso-types.mts

@@ -42,3 +42,39 @@ export interface OAuthUserInfo {
     name?: string;
     picture?: string;
 }
+
+/**
+ * Single-turn authorization requirements object issued by the custodian server
+ * after successful passwordless SSO/Email authentication.
+ *
+ * Placed in `delegateKeystone.data.frameDetails.custodianReqs` when registering
+ * a client delegate keystone via passwordless onboarding.
+ */
+export interface CustodianRequirements {
+    /**
+     * The primary identity keystone TJP address (`ib^gib`) to which the delegate keystone will be registered.
+     * Prevents Man-In-The-Middle reuse of authorization requirements across different primary identities.
+     */
+    primaryTjpAddr: string;
+
+    /**
+     * High-entropy, single-turn random nonce generated by the server.
+     * Prevents replay attacks when registering delegate keystones.
+     */
+    nonce: string;
+
+    /**
+     * Single-turn authorization code computed by the server over `Omit<CustodianRequirements, 'authCode'>`.
+     */
+    authCode: string;
+
+    /**
+     * Expiration timestamp in epoch milliseconds after which this requirements object is invalid.
+     */
+    expiresAt: number;
+
+    /**
+     * Explicit list of permitted keystone verbs allowed for the delegate keystone (e.g., `['sync', 'connect']`).
+     */
+    allowedVerbs: string[];
+}

package/src/index.mts

@@ -50,5 +50,6 @@ export type * from './email/email-types.mjs';
 // identity & SSO custodian infrastructure
 export * from './identity/sso/sso-custodian-service.mjs';
 export * from './identity/sso/sso-config-helper.mjs';
+export * from './identity/sso/custodian-auth-helpers.mjs';
 export type * from './identity/sso/sso-types.mjs';
 

package/src/serve-gib/handlers/api/email/email-outbound.handler.mts

@@ -5,9 +5,8 @@
  */
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { EmailSenderAws } from '../../../../email/aws/email-sender-aws.mjs';
 import { EmailSender, OutboundEmail } from '../../../../email/email-types.mjs';
-import { EmailSenderMock } from '../../../../email/mock/email-sender-mock.mjs';
+import { createDefaultEmailSender } from '../../../../email/verify/email-verify-helpers.mjs';
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
 import { ServeGibHandlerBase } from '../../handler-base.mjs';
@@ -29,27 +28,7 @@ export class EmailOutboundHandler extends ServeGibHandlerBase {
 
     constructor(options: EmailOutboundHandlerOptions = {}) {
         super();
-
-        if (options.sender) {
-            this.sender = options.sender;
-        } else {
-            const isProd = process.env.NODE_ENV === 'production';
-            const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
-            if (mode === 'aws') {
-                this.sender = 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)');
-                }
-                this.sender = new EmailSenderMock();
-            } else {
-                throw new Error(`Unsupported EMAIL_MODE '${mode}'. Must be 'aws' or 'mock'. (E: 987a6b5c4d3e2f10987654321fedcba1)`);
-            }
-        }
+        this.sender = options.sender || createDefaultEmailSender();
     }
 
     protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {

package/src/serve-gib/handlers/api/email/email-verification-code.handler.mts

@@ -13,8 +13,9 @@ import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
 import { ServeGibHandlerBase } from '../../handler-base.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
-import { generateVerificationCode, getPendingStagingDir, getPendingTjpHash, savePendingCodeRecord } from '../../../../email/verify/email-verify-helpers.mjs';
+import { createDefaultEmailSender, generateVerificationCode, getPendingStagingDir, getPendingTjpHash, savePendingCodeRecord, savePendingStagingKeystone } from '../../../../email/verify/email-verify-helpers.mjs';
 import { validateEmail } from '../../../../email/email-helpers.mjs';
+import { normalizeEmail } from '../../../identity-index/identity-index-helpers.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || true;
 
@@ -24,7 +25,7 @@ export interface EmailMagicLinkHandlerOptions {
 
 export interface EmailMagicLinkRequestBody {
     email: string;
-    primaryTjpAddr: string;
+    primaryTjpAddr?: string;
     keystone?: any;
 }
 
@@ -41,27 +42,7 @@ export class EmailVerificationCodeHandler extends ServeGibHandlerBase {
 
     constructor(options: EmailMagicLinkHandlerOptions = {}) {
         super();
-
-        if (options.sender) {
-            this.sender = options.sender;
-        } else {
-            const isProd = process.env.NODE_ENV === 'production';
-            const mode = (process.env.EMAIL_MODE || (isProd ? 'aws' : 'mock')).toLowerCase();
-            if (mode === 'aws') {
-                this.sender = 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)');
-                }
-                this.sender = new EmailSenderMock();
-            } else {
-                throw new Error(`Unsupported EMAIL_MODE '${mode}'. Must be 'aws' or 'mock'. (E: 987a6b5c4d3e2f10987654321fedcba1)`);
-            }
-        }
+        this.sender = options.sender || createDefaultEmailSender();
     }
 
     protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
@@ -94,20 +75,28 @@ export class EmailVerificationCodeHandler extends ServeGibHandlerBase {
                 return this.error(400, 'Invalid email address format (E: e3f4a5b67890123456789abcdef012)');
             }
 
-            if (!primaryTjpAddr || typeof primaryTjpAddr !== 'string') {
-                return this.error(400, 'primaryTjpAddr is required (E: f4a5b67890123456789abcdef0123)');
-            }
-
-            const tjpHash = await getPendingTjpHash(primaryTjpAddr);
+            const normEmail = normalizeEmail(email);
+            const effectivePrimaryTjpAddr = primaryTjpAddr || `pending:${normEmail}`;
+            const tjpHash = await getPendingTjpHash(effectivePrimaryTjpAddr);
 
             const code = generateVerificationCode();
             if (reqCtx.dataDir && tjpHash) {
-                const info = await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash });
+                let info = await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash });
+                if (!info) {
+                    // Create pending staging directory for this email if not yet present
+                    await savePendingStagingKeystone({
+                        dataDir: reqCtx.dataDir,
+                        primaryTjpAddr: effectivePrimaryTjpAddr,
+                        emails: [normEmail],
+                    });
+                    info = await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash });
+                }
+
                 if (info) {
                     await savePendingCodeRecord({ pendingDir: info.pendingDir, code });
                     if (logalot) { console.timeLog(timestampUUID, 'code record saved to pending staging'); }
                 } else {
-                    console.warn(`${lc} Pending staging directory not found for tjpHash ${tjpHash}`);
+                    console.warn(`${lc} Failed to create or access pending staging directory for tjpHash ${tjpHash}`);
                 }
             }
 

package/src/serve-gib/handlers/api/email/email-verify.respec.mts

@@ -2,17 +2,18 @@ import { join } from 'node:path';
 import { existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
 
 import {
-    respecfully, iReckon, ifWe
+    respecfully, iReckon, ifWe, firstOfAll, ifWeMight // don't remove unused ifWe or ifWeMight
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 const sir = `[${import.meta.url}]`;
 
 import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
 import {
     createMagicLinkToken, verifyMagicLinkToken, markNonceUsed,
     clearConsumedNonces, savePendingStagingKeystone, savePendingCodeRecord,
     performPendingGc,
 } from '../../../../email/index.mjs';
-import { IdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { getIdentityIndexService, IdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
 import { EmailVerifyCodeOnetimeHandler } from './email-verify-code-onetime.handler.mjs';
 import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
 import { ErrorHandler } from '../../error-handler.mjs';
@@ -21,13 +22,18 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
     const testDataDir = './test-data-verify';
     const port = 3002;
 
+    let identityIndexSvc: IdentityIndexService;
+    firstOfAll(sir, async () => {
+        identityIndexSvc = getIdentityIndexService();
+    });
+
     // Clean test data directory
     if (existsSync(testDataDir)) {
         try { rmSync(testDataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* ignore */ }
     }
     mkdirSync(testDataDir, { recursive: true });
 
-    await ifWe(sir, 'generate, verify, and enforce expiration & single-use rules on magic link tokens', async () => {
+    await ifWeMight(sir, 'generate, verify, and enforce expiration & single-use rules on magic link tokens', async () => {
         clearConsumedNonces();
         const email = 'alice@example.com';
         const primaryTjpAddr = 'keystone^ABC123DEF456_TJP';
@@ -63,7 +69,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         }
     });
 
-    await ifWe(sir, 'create pending staging quarantine folder and AOT metadata files', async () => {
+    await ifWeMight(sir, 'create pending staging quarantine folder and AOT metadata files', async () => {
         clearConsumedNonces();
         const primaryTjpAddr = 'keystone^STAGING123_TJP';
         const mockKeystone = {
@@ -96,7 +102,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         iReckon(sir, meta1.verified).asTo('meta1 initial verified status').isGonnaBeFalse();
     });
 
-    await ifWe(sir, 'handle 6-digit OTP code verification and promote identity upon verification', async () => {
+    await ifWeMight(sir, 'handle 6-digit OTP code verification and promote identity upon verification', async () => {
         clearConsumedNonces();
         const primaryTjpAddr = 'keystone^MULTIEMAIL_TJP';
         const email = 'multi1@example.com';
@@ -152,11 +158,11 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         iReckon(sir, status).asTo('email verify code status').isGonnaBe(200);
 
         // Verify reverse index registered in official space
-        const record = await IdentityIndexService.lookupIdentityByEmail({ email, dataDir: testDataDir });
+        const record = await identityIndexSvc.lookupIdentityByEmail({ email });
         iReckon(sir, record?.primaryTjpAddr).asTo('record primaryTjpAddr').isGonnaBe(primaryTjpAddr);
     });
 
-    await ifWe(sir, 'execute atomic GC lockfile cleanup on expired staging directories', async () => {
+    await ifWeMight(sir, 'execute atomic GC lockfile cleanup on expired staging directories', async () => {
         clearConsumedNonces();
         const expiredTjpAddr = 'keystone^EXPIRED_TJP';
         const mockKeystone = { ib: expiredTjpAddr, data: { tjpAddr: expiredTjpAddr } };