@ibgib/node-gib 0.0.15 → 0.0.17

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

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

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

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