@ibgib/node-gib 0.0.14 → 0.0.17

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,183 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+
+import {
+    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 { 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';
+
+await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', async () => {
+    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 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';
+
+        // 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 ifWeMight(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 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';
+        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 identityIndexSvc.lookupIdentityByEmail({ email });
+        iReckon(sir, record?.primaryTjpAddr).asTo('record primaryTjpAddr').isGonnaBe(primaryTjpAddr);
+    });
+
+    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 } };
+
+        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/identity/keystone-custodian-genesis.handler.mts

@@ -0,0 +1,233 @@
+/**
+ * @module serve-gib/handlers/api/identity/keystone-custodian-genesis.handler
+ *
+ * POST /api/identity/custodian/genesis
+ *
+ * Single-turn passwordless onboarding & custodian genesis endpoint.
+ * Returns the primary identity keystone (or primaryTjpAddr) along with a fresh,
+ * single-turn `CustodianRequirements` payload containing `authCode` and single-use `nonce`.
+ */
+
+import * as fs from 'node:fs/promises';
+import { extractErrorMsg, hash, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getTjpAddr } from '@ibgib/core-gib/dist/common/other/ibgib-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 { 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 { validateEmail } from '@ibgib/core-gib/dist/keystone/keystone-helpers.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 { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { normalizeEmail } from '../../../identity-index/identity-index-helpers.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { generateCustodianRequirements } from '../../../../identity/sso/custodian-auth-helpers.mjs';
+import { CustodianRequirements } from '../../../../identity/sso/sso-types.mjs';
+import { getPendingStagingDir, getPendingTjpHash, verifyPendingCode } from '../../../../email/verify/email-verify-helpers.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+export interface CustodianGenesisRequestBody {
+    email: string;
+    code?: string;
+    username?: string;
+}
+
+export interface CustodianGenesisResponseBody {
+    success: boolean;
+    isNewIdentity: boolean;
+    primaryTjpAddr: string;
+    primaryKeystone?: any;
+    primaryGraph?: FlatIbGibGraph;
+    custodianReqs: CustodianRequirements;
+    message?: string;
+}
+
+/**
+ * POST /api/identity/custodian/genesis
+ */
+export class KeystoneCustodianGenesisHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneCustodianGenesisHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_CUSTODIAN_GENESIS;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, undefined>
+    ): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: a123456789abcdef0123456789b0001)`); }
+
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty (E: b123456789abcdef0123456789b0002)');
+            }
+
+            let body: CustodianGenesisRequestBody;
+            try {
+                body = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: c123456789abcdef0123456789b0003)');
+            }
+
+            const { email, username, code } = body;
+            if (!email || !validateEmail(email)) {
+                return this.error(400, 'Invalid email address format (E: d123456789abcdef0123456789b0004)');
+            }
+
+            const normEmail = normalizeEmail(email);
+            const indexService = getIdentityIndexService();
+            const ssoConfig = loadSsoServerConfig();
+            const serverSecret = ssoConfig.ssoServerKdfSecret;
+
+            const existing = await indexService.lookupIdentityByEmail({ email: normEmail });
+            const effectivePrimaryTjpAddr = existing ? existing.primaryTjpAddr : `pending:${normEmail}`;
+
+            // Verify 6-digit OTP code if provided or if staging record exists
+            if (code || !existing) {
+                if (!code || typeof code !== 'string' || code.trim().length !== 6) {
+                    return this.error(400, '6-digit verification code is required (E: e123456789abcdef0123456789b0009)');
+                }
+
+                const tjpHash = await getPendingTjpHash(effectivePrimaryTjpAddr);
+                const pendingInfo = reqCtx.dataDir && tjpHash ? await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash }) : undefined;
+
+                if (!pendingInfo || pendingInfo.isExpired) {
+                    return this.error(400, 'Verification record missing or expired. Please request a new verification code. (E: f123456789abcdef0123456789b0010)');
+                }
+
+                const codeVerifyResult = await verifyPendingCode({
+                    pendingDir: pendingInfo.pendingDir,
+                    code,
+                });
+
+                if (!codeVerifyResult.valid) {
+                    return this.error(400, codeVerifyResult.error || 'Invalid verification code (E: g123456789abcdef0123456789b0011)');
+                }
+            }
+
+            let primaryTjpAddr: string;
+            let primaryKeystone: any | undefined;
+            let isNewIdentity = false;
+
+            if (existing) {
+                // Identity already exists — retrieve primary identity info
+                primaryTjpAddr = existing.primaryTjpAddr;
+                console.log(`${lc} Found existing identity for ${normEmail}: ${primaryTjpAddr} (I: e123456789abcdef0123456789b0005)`);
+
+                // Bootstrap domain space to fetch primary keystone frame
+                const metaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
+                const space = await metaspace.getLocalUserSpace({ lock: false });
+                if (space) {
+                    const latestAddr = await metaspace.getLatestAddr({ addr: primaryTjpAddr, space }) ?? primaryTjpAddr;
+                    const getRes = await metaspace.get({ addrs: [latestAddr], space });
+                    primaryKeystone = getRes.ibGibs?.[0];
+                }
+            } else {
+                // New custodian identity creation
+                isNewIdentity = true;
+                console.log(`${lc} Creating new custodian primary identity for ${normEmail} (I: f123456789abcdef0123456789b0006)`);
+
+                const defaultUsername = username || normEmail.split('@')[0];
+                const primaryBuilder = KeystoneProfileBuilder.buildKeystone('sync')
+                    .withUsername(defaultUsername)
+                    .withDescription(`Full Custodian Primary Identity for ${normEmail}`)
+                    .withDetails({
+                        emails: [normEmail],
+                        custodyMode: 'full',
+                    });
+
+                const configs = await primaryBuilder.compileConfigs();
+                const primarySecret = await hash({ s: `${serverSecret}_custodian_${normEmail}` });
+
+                // Bootstrap temporary domain metaspace to perform genesis
+                const tempMetaspace = await bootstrapDomainMetaspace(`temp^${await getUUID()}`, reqCtx.dataDir);
+                const tempSpace = await tempMetaspace.getLocalUserSpace({ lock: false });
+                if (!tempSpace) {
+                    throw new Error(`Failed to create temp domain space for new primary identity (E: 123456789abcdef0123456789b0007)`);
+                }
+
+                const keystoneService = new KeystoneService_V1();
+                primaryKeystone = await keystoneService.genesis({
+                    masterSecret: primarySecret,
+                    emails: [normEmail],
+                    frameDetails: primaryBuilder.getFrameDetails(),
+                    configs,
+                    metaspace: tempMetaspace,
+                    space: tempSpace,
+                    isPrimary: true
+                });
+
+                primaryTjpAddr = getTjpAddr({ ibGib: primaryKeystone, defaultIfNone: 'incomingAddr' })!;
+
+                // Bootstrap permanent domain space for primaryTjpAddr and persist primary keystone
+                const metaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
+                const space = await metaspace.getLocalUserSpace({ lock: false });
+                if (!space) {
+                    throw new Error(`Failed to create domain space for new primary identity ${primaryTjpAddr} (E: 123456789abcdef0123456789b0008)`);
+                }
+
+                await metaspace.put({ ibGibs: [primaryKeystone], space });
+                await metaspace.registerNewIbGib({ ibGib: primaryKeystone, space });
+
+                // Register in identity reverse index
+                await indexService.registerEmailIndex({
+                    email: normEmail,
+                    primaryTjpAddr
+                });
+
+                // Clean up pending staging directory if present
+                const tjpHash = await getPendingTjpHash(effectivePrimaryTjpAddr);
+                const pendingInfo = reqCtx.dataDir && tjpHash ? await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash }) : undefined;
+                if (pendingInfo?.pendingDir) {
+                    try { await fs.rm(pendingInfo.pendingDir, { recursive: true, force: true }); } catch { }
+                }
+            }
+
+            // Generate single-turn CustodianRequirements for client delegate registration
+            const custodianReqs = await generateCustodianRequirements({
+                primaryTjpAddr,
+                serverSecret
+            });
+
+            // Extract complete primary keystone dependency graph
+            let primaryGraph: FlatIbGibGraph | undefined;
+            if (primaryKeystone) {
+                const domainMetaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
+                const domainSpace = await domainMetaspace.getLocalUserSpace({ lock: false });
+                if (domainSpace) {
+                    primaryGraph = await getDependencyGraph({
+                        ibGib: primaryKeystone,
+                        space: domainSpace,
+                        live: false
+                    });
+                }
+            }
+
+            const responseBody: CustodianGenesisResponseBody = {
+                success: true,
+                isNewIdentity,
+                primaryTjpAddr,
+                primaryKeystone,
+                primaryGraph,
+                custodianReqs,
+                message: isNewIdentity ? 'Custodian primary identity created.' : 'Custodian identity located.'
+            };
+
+            return this.ok(responseBody, isNewIdentity ? 201 : 200);
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}