@ibgib/node-gib 0.0.14 → 0.0.17

package/src/serve-gib/handlers/api/identity/keystone-custodian-genesis.respec.mts

@@ -0,0 +1,93 @@
+import { existsSync, rmSync } from 'node:fs';
+
+import {
+    respecfully,
+    iReckon,
+    ifWe
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { KeystoneCustodianGenesisHandler } from './keystone-custodian-genesis.handler.mjs';
+import { verifyCustodianRequirements } from '../../../../identity/sso/custodian-auth-helpers.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'KeystoneCustodianGenesisHandler', async () => {
+    const testDataDir = './test-data-custodian-genesis';
+
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+
+    const origDataDir = process.env.DATA_DIR;
+    process.env.DATA_DIR = testDataDir;
+
+    const handler = new KeystoneCustodianGenesisHandler();
+
+    await ifWe(sir, 'reject request with 400 if email is missing or invalid', async () => {
+        const reqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({ email: 'invalid-email' }),
+            dataDir: testDataDir
+        };
+
+        const res = await handler.handleRoute(reqCtx);
+        iReckon(sir, res?.status).isGonnaBe(400);
+    });
+
+    await ifWe(sir, 'create new custodian primary identity and return custodianReqs for new email', async () => {
+        const reqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({ email: 'alice.custodian@example.com', username: 'alice' }),
+            dataDir: testDataDir
+        };
+
+        const res = await handler.handleRoute(reqCtx);
+        iReckon(sir, res?.status).isGonnaBe(201);
+
+        const body = JSON.parse(res?.body || '{}');
+        iReckon(sir, body.success).isGonnaBeTrue();
+        iReckon(sir, body.isNewIdentity).isGonnaBeTrue();
+        iReckon(sir, body.primaryTjpAddr).includes('keystone^');
+        iReckon(sir, body.primaryKeystone).not.isGonnaBeUndefined();
+        iReckon(sir, body.custodianReqs).not.isGonnaBeUndefined();
+
+        // Verify returned custodianReqs authCode signature
+        const serverSecret = loadSsoServerConfig().ssoServerKdfSecret;
+        const verifyRes = await verifyCustodianRequirements({
+            custodianReqs: body.custodianReqs,
+            serverSecret
+        });
+        iReckon(sir, verifyRes.valid).isGonnaBeTrue();
+    });
+
+    await ifWe(sir, 'retrieve existing primary identity and return fresh custodianReqs for existing email', async () => {
+        const reqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({ email: 'alice.custodian@example.com' }),
+            dataDir: testDataDir
+        };
+
+        const res = await handler.handleRoute(reqCtx);
+        iReckon(sir, res?.status).isGonnaBe(200);
+
+        const body = JSON.parse(res?.body || '{}');
+        iReckon(sir, body.success).isGonnaBeTrue();
+        iReckon(sir, body.isNewIdentity).isGonnaBeFalse();
+        iReckon(sir, body.primaryTjpAddr).includes('keystone^');
+        iReckon(sir, body.custodianReqs).not.isGonnaBeUndefined();
+
+        const serverSecret = loadSsoServerConfig().ssoServerKdfSecret;
+        const verifyRes = await verifyCustodianRequirements({
+            custodianReqs: body.custodianReqs,
+            serverSecret
+        });
+        iReckon(sir, verifyRes.valid).isGonnaBeTrue();
+    });
+
+    // Cleanup
+    process.env.DATA_DIR = origDataDir;
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+});

package/src/serve-gib/handlers/api/identity/keystone-custodian-register-delegate.handler.mts

@@ -0,0 +1,210 @@
+/**
+ * @module serve-gib/handlers/api/identity/keystone-custodian-register-delegate.handler
+ *
+ * POST /api/identity/custodian/register-delegate
+ *
+ * Validates a client delegate keystone containing single-turn `custodianReqs`,
+ * enforces single-use nonce reservation, verifies cryptographic `authCode`,
+ * evolves the server-held primary identity keystone to link the delegate,
+ * and returns the updated `evolvedPrimaryKeystone`.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { getDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+import { FlatIbGibGraph } from '@ibgib/core-gib/dist/common/other/graph-types.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { getAuthCustodianIndex, verifyCustodianRequirements } from '../../../../identity/sso/custodian-auth-helpers.mjs';
+import { CustodianRequirements } from '../../../../identity/sso/sso-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+export interface CustodianRegisterDelegateRequestBody {
+    delegateKeystone: any;
+}
+
+export interface CustodianRegisterDelegateResponseBody {
+    success: boolean;
+    primaryTjpAddr: string;
+    evolvedPrimaryKeystone: any;
+    primaryGraph?: FlatIbGibGraph;
+    message?: string;
+}
+
+/**
+ * POST /api/identity/custodian/register-delegate
+ */
+export class KeystoneCustodianRegisterDelegateHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneCustodianRegisterDelegateHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_CUSTODIAN_REGISTER_DELEGATE;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, undefined>
+    ): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        let authFilePathToClean: string | undefined;
+
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: a23456789abcdef0123456789c0001)`); }
+
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty (E: b23456789abcdef0123456789c0002)');
+            }
+
+            let body: CustodianRegisterDelegateRequestBody;
+            try {
+                body = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: c23456789abcdef0123456789c0003)');
+            }
+
+            const { delegateKeystone } = body;
+            if (!delegateKeystone) {
+                return this.error(400, 'Request body must contain delegateKeystone (E: d23456789abcdef0123456789c0004)');
+            }
+
+            // 1. Intrinsic hash validation on delegate keystone
+            const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: delegateKeystone });
+            if (intrinsicErrors && intrinsicErrors.length > 0) {
+                return this.error(422, 'Intrinsic validation failed for delegateKeystone', { errors: intrinsicErrors });
+            }
+
+            // 2. Structural keystone validation
+            const keystoneService = new KeystoneService_V1();
+            const genesisErrors = await keystoneService.validateGenesisKeystone({ keystoneIbGib: delegateKeystone });
+            if (genesisErrors && genesisErrors.length > 0) {
+                return this.error(422, 'Delegate keystone structure validation failed', { errors: genesisErrors });
+            }
+
+            // 3. Extract and check custodianReqs from frameDetails
+            const frameDetails = delegateKeystone.data?.frameDetails || delegateKeystone.data;
+            const custodianReqs: CustodianRequirements | undefined = frameDetails?.custodianReqs;
+            if (!custodianReqs) {
+                return this.error(400, 'Missing custodianReqs payload in delegate keystone frameDetails (E: e23456789abcdef0123456789c0005)');
+            }
+
+            const delegatePrimaryTjpAddr: string | undefined = frameDetails?.primaryTjpAddr;
+            if (delegatePrimaryTjpAddr && delegatePrimaryTjpAddr !== custodianReqs.primaryTjpAddr) {
+                return this.error(400, 'Primary TJP address mismatch between delegate frameDetails and custodianReqs (E: f23456789abcdef0123456789c0006)');
+            }
+
+            // 4. Verify cryptographic signature & expiration of custodianReqs
+            const ssoConfig = loadSsoServerConfig();
+            const serverSecret = ssoConfig.ssoServerKdfSecret;
+            const verifyRes = await verifyCustodianRequirements({ custodianReqs, serverSecret });
+            if (!verifyRes.valid) {
+                return this.error(401, verifyRes.error || 'Invalid custodian requirements payload');
+            }
+
+            // 5. Atomic Single-Turn Nonce Reservation Check (`{ flag: 'wx' }`)
+            const authCustodianIndex = await getAuthCustodianIndex({ custodianReqs });
+            const dataDir = reqCtx.dataDir || process.env.DATA_DIR || 'data';
+            const authDir = path.join(dataDir, 'identity_index', 'auth_custodian');
+            await fs.mkdir(authDir, { recursive: true });
+
+            authFilePathToClean = path.join(authDir, `${authCustodianIndex}.json`);
+            try {
+                await fs.writeFile(authFilePathToClean, JSON.stringify({
+                    usedAt: Date.now(),
+                    primaryTjpAddr: custodianReqs.primaryTjpAddr,
+                    nonce: custodianReqs.nonce
+                }), { flag: 'wx' });
+            } catch (fileErr: any) {
+                if (fileErr.code === 'EEXIST') {
+                    return this.error(409, 'Custodian requirements payload has already been used. Nonce single-turn reservation violation.');
+                }
+                throw fileErr;
+            }
+
+            // 6. Evolve Server-Held Primary Identity Keystone
+            const metaspace = await bootstrapDomainMetaspace(custodianReqs.primaryTjpAddr, reqCtx.dataDir);
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                return this.error(500, `Could not load domain space for primary identity ${custodianReqs.primaryTjpAddr}`);
+            }
+
+            const latestPrimaryAddr = await metaspace.getLatestAddr({ addr: custodianReqs.primaryTjpAddr, space }) ?? custodianReqs.primaryTjpAddr;
+            const getRes = await metaspace.get({ addrs: [latestPrimaryAddr], space });
+            const parentKeystone = getRes.ibGibs?.[0] as KeystoneIbGib_V1 | undefined;
+
+            if (!parentKeystone) {
+                return this.error(404, `Primary identity keystone not found for address ${custodianReqs.primaryTjpAddr}`);
+            }
+
+            // Derive server's primary custodian secret
+            const primaryEmail: string = parentKeystone.data?.emails?.[0]
+                || parentKeystone.data?.frameDetails?.emails?.[0]
+                || frameDetails?.email
+                || '';
+
+            if (!primaryEmail) {
+                return this.error(500, `Could not determine primary email for identity ${custodianReqs.primaryTjpAddr}`);
+            }
+
+            const primarySecret = await hash({ s: `${serverSecret}_custodian_${primaryEmail}` });
+
+            // Execute primary keystone evolution linking the new delegate
+            const evolvedPrimaryKeystone = await keystoneService.registerDelegate({
+                parentKeystone,
+                delegateKeystone,
+                masterSecret: primarySecret,
+                metaspace,
+                space,
+                allowedVerbs: custodianReqs.allowedVerbs || [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT],
+                deviceName: frameDetails?.deviceTag || 'client-delegate'
+            });
+
+            // Persist delegate keystone in domain space
+            await metaspace.put({ ibGibs: [delegateKeystone], space });
+            await metaspace.registerNewIbGib({ ibGib: delegateKeystone, space });
+
+            // Extract complete primary keystone dependency graph
+            const primaryGraph = await getDependencyGraph({
+                ibGib: evolvedPrimaryKeystone,
+                space,
+                live: false
+            });
+
+            const responseBody: CustodianRegisterDelegateResponseBody = {
+                success: true,
+                primaryTjpAddr: custodianReqs.primaryTjpAddr,
+                evolvedPrimaryKeystone,
+                primaryGraph,
+                message: 'Custodian delegate keystone registered and primary identity evolved successfully.'
+            };
+
+            return this.ok(responseBody, 200);
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        } finally {
+            // Clean up single-turn reservation file after processing
+            if (authFilePathToClean) {
+                try {
+                    await fs.unlink(authFilePathToClean);
+                } catch {
+                    // Ignore unlinking errors if already cleaned up
+                }
+            }
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/serve-gib/handlers/api/identity/keystone-custodian-register-delegate.respec.mts

@@ -0,0 +1,112 @@
+import { existsSync, rmSync } from 'node:fs';
+
+import {
+    respecfully,
+    iReckon,
+    ifWe
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { KeystoneCustodianGenesisHandler } from './keystone-custodian-genesis.handler.mjs';
+import { KeystoneCustodianRegisterDelegateHandler } from './keystone-custodian-register-delegate.handler.mjs';
+import { KeystoneProfileBuilder } from '@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { deriveLocalCustodianDelegateSecret } from '@ibgib/web-gib/dist/identity/custodian-delegate-helper.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'KeystoneCustodianRegisterDelegateHandler', async () => {
+    const testDataDir = './test-data-custodian-register';
+
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+
+    const origDataDir = process.env.DATA_DIR;
+    process.env.DATA_DIR = testDataDir;
+
+    const genesisHandler = new KeystoneCustodianGenesisHandler();
+    const registerHandler = new KeystoneCustodianRegisterDelegateHandler();
+
+    await ifWe(sir, 'reject request with 400 if delegateKeystone or custodianReqs is missing', async () => {
+        const reqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({}),
+            dataDir: testDataDir
+        };
+
+        const res = await registerHandler.handleRoute(reqCtx);
+        iReckon(sir, res?.status).isGonnaBe(400);
+    });
+
+    await ifWe(sir, 'successfully register delegate keystone and evolve primary identity keystone', async () => {
+        // Step 1: Genesis via custodian genesis handler
+        const genesisReqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({ email: 'bob.custodian@example.com', username: 'bob' }),
+            dataDir: testDataDir
+        };
+
+        const genesisRes = await genesisHandler.handleRoute(genesisReqCtx);
+        iReckon(sir, genesisRes?.status).isGonnaBe(201);
+
+        const genesisBody = JSON.parse(genesisRes?.body || '{}');
+        const primaryTjpAddr = genesisBody.primaryTjpAddr;
+        const custodianReqs = genesisBody.custodianReqs;
+
+        iReckon(sir, primaryTjpAddr).not.isGonnaBeUndefined();
+        iReckon(sir, custodianReqs).not.isGonnaBeUndefined();
+
+        // Step 2: Build client delegate keystone containing custodianReqs
+        const delegateSecret = await deriveLocalCustodianDelegateSecret({ primaryTjpAddr });
+        const delegateBuilder = KeystoneProfileBuilder.buildKeystone('sync')
+            .withUsername('bob-sync-phone')
+            .withDescription('Sync Delegate for bob on phone')
+            .withDetails({
+                client: 'space-gib-web',
+                role: 'sync-delegate',
+                deviceTag: 'phone',
+                primaryTjpAddr,
+                custodianReqs,
+            });
+
+        const configs = await delegateBuilder.compileConfigs();
+        const metaspace = await bootstrapDomainMetaspace(primaryTjpAddr, testDataDir);
+        const space = await metaspace.getLocalUserSpace({ lock: false });
+
+        const keystoneService = new KeystoneService_V1();
+        const delegateKeystone = await keystoneService.genesis({
+            masterSecret: delegateSecret,
+            configs,
+            metaspace,
+            space: space!,
+            frameDetails: delegateBuilder.getFrameDetails(),
+            isPrimary: false
+        });
+
+        // Step 3: Register delegate keystone with server
+        const registerReqCtx: any = {
+            method: 'POST',
+            body: JSON.stringify({ delegateKeystone }),
+            dataDir: testDataDir
+        };
+
+        const registerRes = await registerHandler.handleRoute(registerReqCtx);
+        iReckon(sir, registerRes?.status).isGonnaBe(200);
+
+        const registerBody = JSON.parse(registerRes?.body || '{}');
+        iReckon(sir, registerBody.success).isGonnaBeTrue();
+        iReckon(sir, registerBody.primaryTjpAddr).isGonnaBe(primaryTjpAddr);
+        iReckon(sir, registerBody.evolvedPrimaryKeystone).not.isGonnaBeUndefined();
+
+        // Verify primary keystone frame n=1 has been evolved
+        const evolvedPrimary = registerBody.evolvedPrimaryKeystone;
+        iReckon(sir, evolvedPrimary.data?.n).isGonnaBe(1);
+    });
+
+    // Cleanup
+    process.env.DATA_DIR = origDataDir;
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+});

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