@ibgib/node-gib 0.0.14 → 0.0.15

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

@@ -0,0 +1,231 @@
+/**
+ * @module serve-gib/handlers/api/email/email-verify-code-onetime
+ *
+ * Handler for POST /api/email/verify-code-onetime (and alias /api/email/verify-code)
+ */
+
+import * as fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+
+import { extractErrorMsg, getUUID, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import {
+    getPendingStagingDir,
+    getPendingTjpHash,
+    verifyPendingCode,
+    validateEmail
+} from '../../../../email/index.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { normalizeEmail } from '../../../identity-index/identity-index-helpers.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+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';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+export interface EmailVerifyCodeRequestBody {
+    email: string;
+    primaryTjpAddr: string;
+    code: string;
+}
+
+/**
+ * POST /api/email/verify-code-onetime
+ * Validates a 6-digit verification code, updates staging email verification state,
+ * promotes verified keystones to official space once 100% verified, and returns JSON.
+ */
+export class EmailVerifyCodeOnetimeHandler extends ServeGibHandlerBase {
+    protected override lc = `[${EmailVerifyCodeOnetimeHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.EMAIL_VERIFY_CODE || /^\/api\/email\/(?:verify-code-onetime|verify-code)\/?$/i;
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        const timestampUUID = `${lc}[${(await getUUID()).substring(0, 8)}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: e123456789abcdef0123456789a0001)`); }
+            if (logalot) { console.time(timestampUUID); }
+
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty (E: 123456789abcdef0123456789a0001)');
+            }
+
+            let body: EmailVerifyCodeRequestBody;
+            try {
+                body = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: 123456789abcdef0123456789a0002)');
+            }
+
+            if (logalot) { console.timeLog(timestampUUID, 'parse complete'); }
+
+            const { email, primaryTjpAddr, code } = body;
+
+            if (!email || !validateEmail(email)) {
+                return this.error(400, 'Invalid email address format (E: 123456789abcdef0123456789a0003)');
+            }
+            if (!primaryTjpAddr || typeof primaryTjpAddr !== 'string') {
+                return this.error(400, 'primaryTjpAddr is required (E: 123456789abcdef0123456789a0004)');
+            }
+            if (!code || typeof code !== 'string' || code.trim().length !== 6) {
+                return this.error(400, 'Invalid 6-digit verification code format (E: 123456789abcdef0123456789a0005)');
+            }
+
+            const normEmail = normalizeEmail(email);
+            const tjpHash = await getPendingTjpHash(primaryTjpAddr);
+
+            if (!tjpHash || !reqCtx.dataDir) {
+                return this.error(400, 'Could not determine identity tjpHash (E: 123456789abcdef0123456789a0006)');
+            }
+
+            const pendingInfo = await getPendingStagingDir({
+                dataDir: reqCtx.dataDir,
+                tjpHash,
+            });
+
+            if (logalot) { console.timeLog(timestampUUID, 'pending staging lookup complete'); }
+
+            if (!pendingInfo || pendingInfo.isExpired) {
+                // Check if email is already indexed in official space
+                const existing = await getIdentityIndexService().lookupIdentityByEmail({
+                    email: normEmail,
+                });
+
+                if (existing && existing.primaryTjpAddr === primaryTjpAddr) {
+                    return this.ok({
+                        success: true,
+                        message: 'Email address is already verified and linked.',
+                        alreadyVerified: true,
+                        primaryTjpAddr,
+                    });
+                }
+
+                return this.error(400, 'Verification record missing or expired. Please request a new verification code. (E: 123456789abcdef0123456789a0007)');
+            }
+
+            const pendingDir = pendingInfo.pendingDir;
+            const codeVerifyResult = await verifyPendingCode({
+                pendingDir,
+                code,
+            });
+
+            if (logalot) { console.timeLog(timestampUUID, 'code verification check complete'); }
+
+            if (!codeVerifyResult.valid) {
+                const isRateLimited = codeVerifyResult.reason === 'too_many_attempts';
+                const statusCode = isRateLimited ? 429 : 400;
+                console.error(`${lc} Code verification failed for ${normEmail}: ${codeVerifyResult.error} (E: 123456789abcdef0123456789a0008)`);
+                return this.error(statusCode, codeVerifyResult.error || 'Incorrect verification code.');
+            }
+
+            // Mark email as verified in pending staging
+            const emailsDir = path.join(pendingDir, 'emails');
+            const emailHash = await hash({ s: `emailindex${normEmail}` });
+            const emailMetaPath = path.join(emailsDir, `${emailHash}.json`);
+
+            await fs.writeFile(
+                emailMetaPath,
+                JSON.stringify({ email: normEmail, verified: true, verifiedAt: Date.now() }, null, 2),
+                'utf-8'
+            );
+
+            if (logalot) { console.timeLog(timestampUUID, 'email metadata marked verified'); }
+
+            // Read all email metadata files to check 100% verification completion
+            const emailFiles = await fs.readdir(emailsDir);
+            const verifiedEmails: string[] = [];
+            let allVerified = true;
+
+            for (const file of emailFiles) {
+                if (file.endsWith('.json')) {
+                    try {
+                        const content = await fs.readFile(path.join(emailsDir, file), 'utf-8');
+                        const meta = JSON.parse(content);
+                        if (meta.verified === true && meta.email) {
+                            verifiedEmails.push(meta.email);
+                        } else {
+                            allVerified = false;
+                        }
+                    } catch {
+                        allVerified = false;
+                    }
+                }
+            }
+
+            if (allVerified) {
+                // 1. Promote keystone.json if present
+                const keystonePath = path.join(pendingDir, 'keystone.json');
+                if (existsSync(keystonePath)) {
+                    try {
+                        const keystoneContent = await fs.readFile(keystonePath, 'utf-8');
+                        const keystone = JSON.parse(keystoneContent);
+                        const addr = getIbGibAddr({ ibGib: keystone });
+                        const metaspace = await bootstrapDomainMetaspace(addr, reqCtx.dataDir);
+                        if (logalot) { console.timeLog(timestampUUID, 'domain metaspace bootstrap complete'); }
+
+                        const space = await metaspace.getLocalUserSpace({ lock: false });
+                        if (space) {
+                            await metaspace.put({ ibGibs: [keystone], space });
+                            await metaspace.registerNewIbGib({ ibGib: keystone, space });
+                        }
+                        if (logalot) { console.timeLog(timestampUUID, 'keystone promoted to domain space'); }
+                    } catch (promoErr: any) {
+                        console.error(`${lc} Failed to promote keystone.json to official space: ${extractErrorMsg(promoErr)} (E: 123456789abcdef0123456789a0009)`);
+                    }
+                }
+
+                // 2. Register official reverse indices for verified emails
+                for (const ve of verifiedEmails) {
+                    try {
+                        await getIdentityIndexService().registerEmailIndex({
+                            email: ve,
+                            primaryTjpAddr,
+                        });
+                    } catch (indexErr: any) {
+                        if (!indexErr?.message?.includes('duplicate_identity_409') && indexErr?.code !== 'EEXIST') {
+                            console.error(`${lc} Failed to register official email index for ${ve}: ${extractErrorMsg(indexErr)} (E: 123456789abcdef0123456789a0010)`);
+                        }
+                    }
+                }
+                if (logalot) { console.timeLog(timestampUUID, 'official email indices registered'); }
+
+                // 3. Remove pending staging directory
+                try {
+                    await fs.rm(pendingDir, { recursive: true, force: true });
+                } catch { /* ignore */ }
+                if (logalot) { console.timeLog(timestampUUID, 'pending staging directory cleaned'); }
+
+                console.log(`${lc} 100% verification achieved via 6-digit code. Promoted identity & registered indices for ${primaryTjpAddr} (I: 123456789abcdef0123456789a0011)`);
+
+                return this.ok({
+                    success: true,
+                    message: 'Email verified & account activated successfully!',
+                    primaryTjpAddr,
+                });
+            } else {
+                return this.ok({
+                    success: true,
+                    message: 'Code verified for email. Remaining inboxes pending.',
+                    primaryTjpAddr,
+                });
+            }
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} Error verifying code: ${emsg} (E: 123456789abcdef0123456789a0012)`);
+            return this.error(500, `Code verification error: ${emsg}`);
+        } finally {
+            if (logalot) {
+                console.log(`${lc} complete.`);
+                console.timeEnd(timestampUUID);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,177 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+
+import {
+    respecfully, iReckon, ifWe
+} 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 { EmailVerifyCodeOnetimeHandler } from './email-verify-code-onetime.handler.mjs';
+import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
+import { ErrorHandler } from '../../error-handler.mjs';
+
+await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', async () => {
+    const testDataDir = './test-data-verify';
+    const port = 3002;
+
+    // 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 () => {
+        clearConsumedNonces();
+        const email = 'alice@example.com';
+        const primaryTjpAddr = 'keystone^ABC123DEF456_TJP';
+
+        // 1. Create valid token
+        const token = createMagicLinkToken({ email, primaryTjpAddr });
+        iReckon(sir, token).asTo('magic link token').isGonnaBeTruthy();
+
+        // 2. Verify valid token
+        const verifyRes = verifyMagicLinkToken({ token });
+        iReckon(sir, verifyRes.valid).asTo('valid token verification').isGonnaBeTrue();
+        iReckon(sir, verifyRes.payload?.email).asTo('token email').isGonnaBe(email);
+        iReckon(sir, verifyRes.payload?.primaryTjpAddr).asTo('token primaryTjpAddr').isGonnaBe(primaryTjpAddr);
+
+        // 3. Reject expired token
+        const expiredToken = createMagicLinkToken({ email, primaryTjpAddr, ttlMs: -1000 });
+        const expiredRes = verifyMagicLinkToken({ token: expiredToken });
+        iReckon(sir, expiredRes.valid).asTo('expired token valid').isGonnaBeFalse();
+        iReckon(sir, expiredRes.error).includes('expired');
+
+        // 4. Reject tampered token
+        const parts = token.split('.');
+        const tamperedToken = `${parts[0]}.invalid_signature`;
+        const tamperedRes = verifyMagicLinkToken({ token: tamperedToken });
+        iReckon(sir, tamperedRes.valid).asTo('tampered signature valid').isGonnaBeFalse();
+
+        // 5. Enforce single-use nonce
+        if (verifyRes.payload) {
+            markNonceUsed(verifyRes.payload.nonce);
+            const reusedRes = verifyMagicLinkToken({ token });
+            iReckon(sir, reusedRes.valid).asTo('reused token valid').isGonnaBeFalse();
+            iReckon(sir, reusedRes.error).includes('already been used');
+        }
+    });
+
+    await ifWe(sir, 'create pending staging quarantine folder and AOT metadata files', async () => {
+        clearConsumedNonces();
+        const primaryTjpAddr = 'keystone^STAGING123_TJP';
+        const mockKeystone = {
+            ib: primaryTjpAddr,
+            gib: 'gib123',
+            data: { tjpAddr: primaryTjpAddr, username: 'staginguser' },
+        };
+        const emails = ['stage1@example.com', 'stage2@example.com'];
+
+        const saveRes = await savePendingStagingKeystone({
+            keystone: mockKeystone,
+            emails,
+            dataDir: testDataDir,
+            ttlMs: 60000,
+        });
+
+        iReckon(sir, existsSync(saveRes.pendingDir)).asTo('pending dir exists').isGonnaBeTrue();
+        iReckon(sir, existsSync(join(saveRes.pendingDir, 'keystone.json'))).asTo('keystone.json exists').isGonnaBeTrue();
+
+        const salt = 'emailindex';
+        const tjpHash = await hash({ s: `${salt}${primaryTjpAddr}` });
+        iReckon(sir, saveRes.tjpHash).asTo('tjpHash matches').isGonnaBe(tjpHash);
+
+        const emailHash1 = await hash({ s: `${salt}stage1@example.com` });
+        const emailMetaPath1 = join(saveRes.pendingDir, 'emails', `${emailHash1}.json`);
+        iReckon(sir, existsSync(emailMetaPath1)).asTo('emailHash1 meta file exists').isGonnaBeTrue();
+
+        const meta1 = JSON.parse(readFileSync(emailMetaPath1, 'utf-8'));
+        iReckon(sir, meta1.email).asTo('meta1 email').isGonnaBe('stage1@example.com');
+        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 () => {
+        clearConsumedNonces();
+        const primaryTjpAddr = 'keystone^MULTIEMAIL_TJP';
+        const email = 'multi1@example.com';
+        const mockKeystone = {
+            ib: primaryTjpAddr,
+            gib: 'gib_multi',
+            data: { tjpAddr: primaryTjpAddr, emails: [email] },
+        };
+
+        const saveRes = await savePendingStagingKeystone({
+            keystone: mockKeystone,
+            emails: [email],
+            primaryTjpAddr,
+            dataDir: testDataDir,
+        });
+
+        const testCode = '482901';
+        await savePendingCodeRecord({ pendingDir: saveRes.pendingDir, code: testCode });
+
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [new EmailVerifyCodeOnetimeHandler()],
+            errorHandler: new ErrorHandler(),
+        });
+
+        const payload = JSON.stringify({
+            email,
+            primaryTjpAddr,
+            code: testCode,
+        });
+
+        const req: any = {
+            url: '/api/email/verify-code',
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            on: (event: string, cb: any) => {
+                if (event === 'data') { cb(Buffer.from(payload)); }
+                if (event === 'end') { cb(); }
+            },
+        };
+
+        let status = 0;
+        let body = '';
+        const res: any = {
+            writeHead: (st: number) => { status = st; },
+            end: (b: string) => { body = b; },
+            statusCode: 0,
+        };
+
+        await serveGib.handleRequest(req, res);
+
+        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 });
+        iReckon(sir, record?.primaryTjpAddr).asTo('record primaryTjpAddr').isGonnaBe(primaryTjpAddr);
+    });
+
+    await ifWe(sir, 'execute atomic GC lockfile cleanup on expired staging directories', async () => {
+        clearConsumedNonces();
+        const expiredTjpAddr = 'keystone^EXPIRED_TJP';
+        const mockKeystone = { ib: expiredTjpAddr, data: { tjpAddr: expiredTjpAddr } };
+
+        const saveRes = await savePendingStagingKeystone({
+            keystone: mockKeystone,
+            emails: ['expired@example.com'],
+            dataDir: testDataDir,
+            ttlMs: -5000, // Expired 5 seconds ago
+        });
+
+        iReckon(sir, existsSync(saveRes.pendingDir)).asTo('expired pending dir created').isGonnaBeTrue();
+
+        const cleanedCount = await performPendingGc({ dataDir: testDataDir });
+        iReckon(sir, cleanedCount).asTo('GC cleaned expired dir count').isGonnaBe(1);
+        iReckon(sir, existsSync(saveRes.pendingDir)).asTo('expired pending dir removed').isGonnaBeFalse();
+    });
+});

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

@@ -6,10 +6,8 @@
  * Checks whether an email address is already registered in the server identity index.
  */
 
-import * as path from 'node:path';
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { IdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
-import { getIdentityEmailHash } from '../../../identity-index/identity-index-helpers.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
 import { ServeGibHandlerBase } from '../../handler-base.mjs';
 import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
@@ -36,7 +34,7 @@ export class KeystoneCheckEmailHandler extends ServeGibHandlerBase<undefined, {
                 return this.error(400, 'Query param email is required');
             }
 
-            const indexService = new IdentityIndexService({ baseDir: path.join(reqCtx.dataDir, 'index') });
+            const indexService = getIdentityIndexService();
             const record = await indexService.getEmailIndex({ email });
 
             if (record) {

package/src/serve-gib/handlers/api/keystone/keystone-evolve.handler.mts

@@ -15,15 +15,17 @@ import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { validateAndRegisterEvolveKeystone } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
 import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
-import { loadSsoServerConfig } from '@ibgib/web-gib/dist/identity/sso/sso-config-helper.mjs';
-import { SsoCustodianService } from '@ibgib/web-gib/dist/identity/sso/sso-custodian-service.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '../../../../identity/sso/sso-custodian-service.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { savePendingStagingKeystone, dispatchVerificationCode } from '../../../../email/verify/email-verify-helpers.mjs';
 import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { ParamsWithDomain, RequestContext, ResponseResult } from '../../../types.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT || true;
+const logalot = GLOBAL_LOG_A_LOT;
 
 interface EvolveParams extends ParamsWithDomain {
     domainAddr: string;
@@ -97,6 +99,43 @@ export class KeystoneEvolveHandler extends ServeGibHandlerWithMetaspaceBase<Evol
                 return this.error(500, 'No local user space found (E: a1144e5d6cd9641fb82d6b359f131126)');
             }
 
+            // Check for any new unverified email addresses attached to the evolved keystone
+            const incomingEmails: string[] = keystoneIbGib.data?.emails ?? keystoneIbGib.data?.frameDetails?.emails ?? [];
+            if (incomingEmails.length > 0) {
+                const unverifiedEmails: string[] = [];
+                for (const email of incomingEmails) {
+                    const record = await getIdentityIndexService().lookupIdentityByEmail({ email });
+                    if (!record || record.primaryTjpAddr !== domainAddr) {
+                        unverifiedEmails.push(email);
+                    }
+                }
+
+                if (unverifiedEmails.length > 0) {
+                    console.log(`${lc} Evolved keystone contains unverified email(s): ${unverifiedEmails.join(', ')}. Staging evolution in quarantine area.`);
+                    const saveRes = await savePendingStagingKeystone({
+                        keystone: keystoneIbGib,
+                        emails: unverifiedEmails,
+                        primaryTjpAddr: domainAddr,
+                        dataDir: reqCtx.dataDir
+                    });
+
+                    // Immediately dispatch 6-digit verification code email for first unverified email
+                    const primaryEmail = unverifiedEmails[0];
+                    await dispatchVerificationCode({
+                        email: primaryEmail,
+                        primaryTjpAddr: domainAddr,
+                        pendingDir: saveRes.pendingDir,
+                    });
+
+                    return this.ok({
+                        success: true,
+                        pending: true,
+                        addr: domainAddr,
+                        message: 'Evolved keystone quarantined in pending staging area. 6-digit verification code sent to your email.'
+                    }, 202);
+                }
+            }
+
             // Delegate all intrinsic checks, transition rules, pool restrictions, and registration/persistence to core-gib helper
             await validateAndRegisterEvolveKeystone({
                 domainAddr,

package/src/serve-gib/handlers/api/keystone/keystone-genesis.handler.mts

@@ -33,12 +33,11 @@
 import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 
-import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, getUUID, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
 import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
-import { IdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
 import { ServeGibHandlerBase } from '../../handler-base.mjs';
@@ -46,12 +45,11 @@ import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../typ
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { getDomainRootPath } from '../../../bootstrap-helper.mjs';
 import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+import { savePendingStagingKeystone, dispatchVerificationCode } from '../../../../email/verify/email-verify-helpers.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || true;
 
 
-
-
 /**
  * POST /api/keystone/genesis
  *
@@ -66,8 +64,11 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
         reqCtx: RequestContext<undefined, undefined>
     ): Promise<ResponseResult | undefined> {
         const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        const timestampUUID = `${lc}${[(await getUUID()).substring(0, 8)]}`;
         try {
-            if (logalot) { console.log(`${lc} starting... (I: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
+            if (logalot) { console.log(`${lc} starting... (I: 866db89dfcb947c7353a1a8849bb2826)`); }
+
+            if (logalot) { console.time(timestampUUID); }
 
             // ----------------------------------------------------------------
             // 1. Parse body — expect { keystoneIbGib }
@@ -79,6 +80,8 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
                 return this.error(400, 'Request body must be valid JSON (E: dd8618857568f8fc5e9c62b8ed135826)');
             }
 
+            if (logalot) { console.timeLog(timestampUUID, 'parse complete') }
+
             const { keystoneIbGib } = parsed;
             if (!keystoneIbGib) {
                 return this.error(400, 'Body must contain keystoneIbGib (E: 9c8c5d979d7842cd716ba64f69349c26)');
@@ -92,6 +95,8 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
                 return this.error(422, 'Intrinsic keystone validation failed (E: 76d388e198f23a87dd6596f59c36e826)', { errors: intrinsicErrors });
             }
 
+            if (logalot) { console.timeLog(timestampUUID, 'intrinsic validation complete') }
+
             // ----------------------------------------------------------------
             // 3. Structural keystone + genesis-frame checks
             // ----------------------------------------------------------------
@@ -102,11 +107,14 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
             if (keystoneErrors && keystoneErrors.length > 0) {
                 return this.error(422, `Keystone genesis validation failed. Errors: ${keystoneErrors} (E: 8384285be7a8ab0d41cfd1df2e2aa826)`, { errors: keystoneErrors });
             }
+            if (logalot) { console.timeLog(timestampUUID, 'keystone validation complete') }
 
             // ----------------------------------------------------------------
             // 4. Domain uniqueness & Email Index Registration
             // ----------------------------------------------------------------
             const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+            const primaryTjpAddr = addr;
+            if (logalot) { console.log(`${lc} primaryTjpAddr: ${primaryTjpAddr} (I: c09d68025348261ac8ccec8ebe59d626)`); }
             const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: addr });
             const domainGib = tjpGib || punctiliarHash;
             if (!domainGib) {
@@ -120,31 +128,42 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
 
             // Extract email addresses attached to primary identity keystone (if present)
             const emails: string[] = keystoneIbGib.data?.emails ?? keystoneIbGib.data?.frameDetails?.emails ?? [];
-            const indexService = new IdentityIndexService({ baseDir: path.join(reqCtx.dataDir, 'index') });
-            const registeredHashes: string[] = [];
 
             if (emails.length > 0) {
-                try {
-                    for (const email of emails) {
-                        const { emailHash } = await indexService.registerEmailIndex({ email, tjpAddr: addr });
-                        registeredHashes.push(emailHash);
-                    }
-                } catch (err: any) {
-                    if (err.message.includes('duplicate_identity_409')) {
-                        // Roll back any hashes registered in this transaction before throwing
-                        for (const emailHash of registeredHashes) {
-                            try { await indexService.getEmailIndexByHash({ emailHash }); } catch { /* ignore */ }
-                        }
-                        return this.error(409, `Email/Identity already registered (E: duplicate_identity_409)`);
-                    }
-                    throw err;
-                }
+                // Staging Quarantine: Save keystone & email records to email/pending/
+                console.log(`${lc} Staging genesis keystone with unverified email(s): ${emails.join(', ')} (I: c123456789abcdef0123456789abcdef)`);
+                const saveRes = await savePendingStagingKeystone({
+                    keystone: keystoneIbGib,
+                    emails,
+                    primaryTjpAddr: addr,
+                    dataDir: reqCtx.dataDir
+                });
+
+                // Immediately dispatch 6-digit verification code email for primary email
+                const primaryEmail = emails[0];
+                await dispatchVerificationCode({
+                    email: primaryEmail,
+                    primaryTjpAddr: addr,
+                    pendingDir: saveRes.pendingDir,
+                });
+
+                if (logalot) { console.timeLog(timestampUUID, `quarantine staging complete & code dispatched to ${primaryEmail}`); }
+
+                // EARLY RETURN 202 Accepted — do NOT bootstrap domain space or write to email/hashes/ until email is verified!
+                return this.ok({
+                    success: true,
+                    pending: true,
+                    addr,
+                    message: 'Genesis keystone quarantined in pending staging area. 6-digit verification code sent to your email.'
+                }, 202);
             }
+            if (logalot) { console.timeLog(timestampUUID, 'emails complete') }
 
             // ----------------------------------------------------------------
             // 5. Bootstrap the new domain metaspace (creates folders)
             // ----------------------------------------------------------------
             const metaspace = await bootstrapDomainMetaspace(addr, reqCtx.dataDir);
+            if (logalot) { console.timeLog(timestampUUID, 'metaspace bootstrap complete') }
 
             // ----------------------------------------------------------------
             // 6. Persist the genesis keystone into the new domain space
@@ -158,6 +177,7 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
             await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space });
 
             console.log(`${lc} domain created and keystone persisted: ${addr}`);
+            if (logalot) { console.timeLog(timestampUUID, 'domain created complete') }
             // if (logalot) { console.log(`${lc} keystoneIbGib: ${pretty(keystoneIbGib)} (I: d598c6ff7a48997d585b84c19c464826)`); }
             return this.ok({ success: true, addr }, 201);
         } catch (error) {
@@ -165,7 +185,10 @@ export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undef
             console.error(`${lc} ${emsg}`);
             return this.error(500, emsg);
         } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
+            if (logalot) {
+                console.log(`${lc} complete.`);
+                console.timeEnd(timestampUUID);
+            }
         }
     }
 }