@ibgib/node-gib 0.0.10 → 0.0.14

package/src/serve-gib/handlers/api/ibgib/ibgib.handler.mts

@@ -0,0 +1,176 @@
+/**
+ * @module serve-gib/handlers/api/ibgib
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { validateAddressSegment } from '../../../path-helper.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import {
+    DEFAULT_QUERY_PARAMS_GET_IBGIB, IbGibGetQueryParams, IbGibParams,
+    isKnownQueryParamsKey_IbGibGet, KNOWN_QUERY_PARAMS_IBGIB_GET
+} from './ibgib-handler-types.mjs';
+import { validateAndCoerceBooleanQueryParam } from '../../../serve-gib-helpers.mjs';
+
+export interface IbGibGraphResponseBody {
+    addr: string;
+    count: number;
+    graph: Record<string, IbGib_V1>;
+}
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * GET /api/ibgib/:domainAddr/:ibGibAddr
+ */
+export class IbGibHandler extends ServeGibHandlerWithMetaspaceBase<IbGibParams, IbGibGetQueryParams> {
+    protected override lc: string = `[${IbGibHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = API_PATH_REGEXES.IBGIB_ADDR;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<IbGibParams, IbGibGetQueryParams>): Promise<IbGibParams | undefined> {
+        const lc = `${this.lc}[${this.parseParamsImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+            const match = reqCtx.pathname.match(this.regex);
+            if (!match) { throw new Error(`(UNEXPECTED) match falsy for regex? at this point, we have passed canHandleRoute, so this should parse correctly. (E: 8ce0810a3a88f420639bf8286df1d826)`); }
+            const domainIb = decodeURIComponent(match[1]);
+            const domainGib = decodeURIComponent(match[2]);
+            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
+            const ibGibIb = decodeURIComponent(match[3]);
+            const ibGibGib = decodeURIComponent(match[4]);
+            const ibGibAddr = getIbGibAddr({ ib: ibGibIb, gib: ibGibGib });
+            return {
+                ibGibIb, ibGibGib, ibGibAddr,
+                domainInfo: this.getDomainInfo({ domainAddr }),
+            };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
+        const lc = `${this.lc}[${this.validateQueryParams.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const errors: string[] = [];
+
+            // strict checking
+            const queryParamsKeys = Object.keys(queryParams);
+            const invalidKeys: string[] = queryParamsKeys.filter(x => !isKnownQueryParamsKey_IbGibGet(x));
+            if (invalidKeys.length > 0) {
+                throw new Error(`invalid query params keys: ${invalidKeys.join(', ')}. valid query params keys: ${KNOWN_QUERY_PARAMS_IBGIB_GET.join(', ')} (E: b7e8a9f2c1d34e56b89a01d4f2e7c326)`);
+            }
+
+            // Enforce that EVERY key must have a validation function mapping
+            type ValidationFn = () => Promise<void>;
+            const ValidationFns: Record<KNOWN_QUERY_PARAMS_IBGIB_GET, ValidationFn> = {
+                getLatest: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getLatest', errors),
+                getGraph: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getGraph', errors),
+                addrOnly: async () => validateAndCoerceBooleanQueryParam(queryParams, 'addrOnly', errors),
+            };
+
+            // execute all validation functions
+            for (const fn of Object.values(ValidationFns)) {
+                await fn();
+            }
+
+            return errors;
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext<IbGibParams, IbGibGetQueryParams>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
+
+            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
+            if (!reqCtx.metaspace) { throw new Error(`(UNEXPECTED) metaspace falsy? we should have initialized it by now since this is a domain-dependent handler (E: 864661c668d2aa1918b7ee677a7d9c26)`); }
+
+            const { ibGibIb, ibGibGib } = reqCtx.params as IbGibParams;
+            if (!ibGibIb || !ibGibGib) { return undefined; }
+
+            // Reconstruct addr from params
+            const rawAddr = `${ibGibIb}^${ibGibGib}`;
+            if (!validateAddressSegment(rawAddr)) return this.error(400, 'Invalid address format');
+            const addr = rawAddr;
+
+            const queryParams = {
+                ...DEFAULT_QUERY_PARAMS_GET_IBGIB,
+                ...(reqCtx.queryParams ?? {}),
+            };
+
+            const { getLatest, getGraph, addrOnly } = queryParams;
+
+            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`(UNEXPECTED) couldn't get default local user space? (E: ec6161ea3a08892ad8bfd1b7b0d79826)`); }
+
+            let addr_latest: string = addr;
+            if (getLatest) {
+                const latestAddr = await reqCtx.metaspace.getLatestAddr({ addr, space });
+                if (latestAddr) { addr_latest = latestAddr; }
+            }
+
+            // Lightweight tip-check: return only the resolved address.
+            // Client uses this to decide whether a full sync is necessary
+            // without incurring the cost of fetching the full ibgib or graph.
+            if (addrOnly && !getGraph) {
+                return this.ok({ addr: addr_latest, clientAddr: addr });
+            } /* <<<<< returns early */
+
+            if (getGraph) {
+                const resGraph = await reqCtx.metaspace.getDependencyGraph({
+                    ibGibAddr: addr_latest,
+                    space,
+                    live: getLatest,
+                });
+                const addrs = Object.keys(resGraph);
+                if (addrs.length > 0) {
+                    if (addrOnly) {
+                        // Return only the address list for delta negotiation (smart diff):
+                        // client compares these against what it already has to determine
+                        // the minimal set it needs to fetch.
+                        return this.ok({ addr: addr_latest, clientAddr: addr, addrs });
+                    } else {
+                        const responseBody: IbGibGraphResponseBody = {
+                            addr: addr_latest,
+                            count: addrs.length,
+                            graph: resGraph
+                        };
+                        return this.ok(responseBody);
+                    }
+                } else {
+                    return this.notFound(`Graph not found for ${addr_latest} (E: 89b259f13ae5e4f0d8287f6c0475a826)`);
+                }
+            } else {
+                const resGet = await reqCtx.metaspace.get({ space, addr: addr_latest });
+                if (resGet.success && resGet.ibGibs?.length === 1) {
+                    const ibGib = resGet.ibGibs[0];
+                    return this.ok(ibGib);
+                } else {
+                    return this.notFound(`IbGib not found for ${addr_latest} (E: 017621e0a8086832ff06cfc884b8c426)`);
+                }
+            }
+        } catch (error) {
+            if (logalot) { console.error(extractErrorMsg(error)) }
+            return this.error(500, extractErrorMsg(error));
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-check-email.handler
+ *
+ * GET /api/keystone/check-email?email=foo@example.com
+ *
+ * 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 { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+
+/**
+ * GET /api/keystone/check-email
+ */
+export class KeystoneCheckEmailHandler extends ServeGibHandlerBase<undefined, { email?: string }> {
+    protected override lc: string = `[${KeystoneCheckEmailHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_CHECK_EMAIL;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, { email?: string }>
+    ): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            // Anti-timing side-channel protection: add bounded random jitter delay (150ms-350ms)
+            const jitterMs = Math.floor(Math.random() * 200) + 150;
+            await new Promise(resolve => setTimeout(resolve, jitterMs));
+            const email = (reqCtx.queryParams?.email || '').trim();
+            if (!email) {
+                console.error(`${lc} Check-email request missing email query parameter.`);
+                return this.error(400, 'Query param email is required');
+            }
+
+            const indexService = new IdentityIndexService({ baseDir: path.join(reqCtx.dataDir, 'index') });
+            const record = await indexService.getEmailIndex({ email });
+
+            if (record) {
+                console.log(`${lc} Email '${email}' is already registered.`);
+                return this.ok({
+                    available: false,
+                    message: 'Email/Identity already registered'
+                });
+            }
+
+            console.log(`${lc} Email '${email}' is available.`);
+            return this.ok({
+                available: true
+            });
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        }
+    }
+}

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

@@ -0,0 +1,150 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-evolve.handler
+ *
+ * PUT /api/keystone/evolve/:domainAddr
+ *
+ * Receives an evolved domain keystone (`I^I1.Itjp`) and any related
+ * ibgibs (e.g., the `S^Stjp` session keystone).
+ *
+ * Validates the evolution, verifies the `S` session keystone, and persists
+ * them to the domain metaspace to authorize the sync session.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+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 { GLOBAL_LOG_A_LOT } from '../../../constants.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;
+
+interface EvolveParams extends ParamsWithDomain {
+    domainAddr: string;
+}
+
+/**
+ * Body payload for the Keystone Evolve REST API request.
+ */
+interface EvolveBody {
+    /** The main evolved keystone frame. */
+    keystoneIbGib: KeystoneIbGib_V1;
+    /**
+     * Array of other keystone frames related to this evolution.
+     * Ephemeral session keystones for sync, or persistent delegate keystones for manage.
+     */
+    relatedKeystoneIbGibs?: IbGib_V1[];
+    /** Optional map of providerId to token to revoke during unlinking. */
+    revokeTokens?: Record<string, string>;
+}
+
+export class KeystoneEvolveHandler extends ServeGibHandlerWithMetaspaceBase<EvolveParams, EvolveBody> {
+    protected override lc: string = `[${KeystoneEvolveHandler.name}]`;
+    protected override method: 'PUT' = 'PUT';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_EVOLVE;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<EvolveParams, any>): Promise<EvolveParams | undefined> {
+        const match = reqCtx.pathname.match(this.regex);
+        if (match && match.length >= 3) {
+            const domainIb = decodeURIComponent(match[1]);
+            const domainGib = decodeURIComponent(match[2]);
+            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
+            return {
+                domainAddr,
+                domainInfo: this.getDomainInfo({ domainAddr })
+            };
+        } else {
+            return undefined;
+        }
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
+        return []; // We don't expect any query parameters for evolution
+    }
+
+    protected override async handleRouteImpl(reqCtx: RequestContext<EvolveParams>): Promise<ResponseResult> {
+        const lc = `${this.lc}[handleRouteImpl]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!reqCtx.params) { return this.error(400, 'Invalid parameters'); }
+            if (!reqCtx.metaspace) { return this.error(500, 'Metaspace not initialized'); }
+
+            const { domainAddr } = reqCtx.params;
+            const bodyStr = reqCtx.body;
+            if (!bodyStr) { return this.error(400, 'Empty body'); }
+
+            let parsed: EvolveBody;
+            try {
+                parsed = JSON.parse(bodyStr);
+            } catch (err) {
+                return this.error(400, 'Invalid request JSON body: bodyStr does NOT parse. (E: 2f81c8c80a6884ff32b877671e92f326)');
+            }
+
+            const { keystoneIbGib, relatedKeystoneIbGibs = [] } = parsed;
+            if (!keystoneIbGib) {
+                return this.error(400, 'Invalid request. Body must contain keystoneIbGib (E: e234647f79282982c8012fe8015f5826)');
+            }
+
+            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                return this.error(500, 'No local user space found (E: a1144e5d6cd9641fb82d6b359f131126)');
+            }
+
+            // Delegate all intrinsic checks, transition rules, pool restrictions, and registration/persistence to core-gib helper
+            await validateAndRegisterEvolveKeystone({
+                domainAddr,
+                keystoneIbGib,
+                relatedKeystoneIbGibs,
+                metaspace: reqCtx.metaspace,
+                space
+            });
+
+            // Post-Evolution Hook: Handle SSO provider unlinking
+            const claim = keystoneIbGib.data?.proofs?.[0]?.claim;
+            if (claim?.details?.type === 'remove-pool') {
+                const removeInfo = claim.details.info;
+                if (removeInfo && Array.isArray(removeInfo.remove)) {
+                    // Lazy-load custodian service config
+                    const config = loadSsoServerConfig();
+                    const custodian = new SsoCustodianService(config);
+
+                    for (const poolId of removeInfo.remove) {
+                        if (poolId.startsWith('custodian-manage-')) {
+                            const providerId = poolId.replace('custodian-manage-', '');
+                            console.log(`${lc} Evolved keystone removed custodian pool: ${poolId}. Performing unlink cleanup for provider: ${providerId}`);
+
+                            // Revoke token if supplied by the client
+                            const token = parsed.revokeTokens?.[providerId];
+                            if (token) {
+                                try {
+                                    await custodian.revokeToken(providerId as any, token);
+                                } catch (e) {
+                                    console.warn(`${lc} Failed to revoke token for provider ${providerId}: ${extractErrorMsg(e)}`);
+                                }
+                            } else {
+                                console.log(`${lc} No OAuth token supplied by client for revocation of provider: ${providerId}`);
+                            }
+                        }
+                    }
+                }
+            }
+
+            return this.ok({
+                message: `Successfully evolved domain keystone with session keystone`,
+            });
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            return this.error(422, `Evolve validation/persistence failed: ${extractErrorMsg(error)}`);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

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

@@ -0,0 +1,171 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-genesis.handler
+ *
+ * POST /api/keystone/genesis
+ *
+ * Accepts a single genesis-frame keystone ibgib from the client and
+ * bootstraps a new domain-isolated metaspace for it.
+ *
+ * ## request body
+ *
+ * ```json
+ * { "keystoneIbGib": <KeystoneIbGib_V1> }
+ * ```
+ *
+ * ## validation steps
+ *
+ * 1. Body contains `keystoneIbGib` (single ibgib, not an array).
+ * 2. Intrinsic hash validation passes (`validateIbGibIntrinsically`).
+ * 3. Structural keystone check: `ib` starts with `"keystone"`, no `past` in
+ *    `rel8ns` (genesis = TJP frame, no prior timeline).
+ * 4. Domain uniqueness: the path derived from the keystone's tjpGib must not
+ *    already exist on disk — if it does, return 409 Conflict.
+ * 5. Bootstrap: call `bootstrapDomainMetaspace` to create folders + metaspace.
+ * 6. Persist the keystone ibgib into the newly created domain space.
+ *
+ * ## notes
+ *
+ * Unlike domain-scoped handlers, this handler does NOT rely on
+ * `reqCtx.metaspace` (which is undefined when no domain exists yet). It
+ * creates the metaspace itself using `bootstrapDomainMetaspace`.
+ */
+
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+
+import { extractErrorMsg, 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';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { getDomainRootPath } from '../../../bootstrap-helper.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+
+
+
+/**
+ * POST /api/keystone/genesis
+ *
+ * No path params — the domain is derived from the incoming keystone ibgib.
+ */
+export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneGenesisHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_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: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
+
+            // ----------------------------------------------------------------
+            // 1. Parse body — expect { keystoneIbGib }
+            // ----------------------------------------------------------------
+            let parsed: any;
+            try {
+                parsed = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: dd8618857568f8fc5e9c62b8ed135826)');
+            }
+
+            const { keystoneIbGib } = parsed;
+            if (!keystoneIbGib) {
+                return this.error(400, 'Body must contain keystoneIbGib (E: 9c8c5d979d7842cd716ba64f69349c26)');
+            }
+
+            // ----------------------------------------------------------------
+            // 2. Intrinsic hash validation
+            // ----------------------------------------------------------------
+            const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: keystoneIbGib });
+            if (intrinsicErrors) {
+                return this.error(422, 'Intrinsic keystone validation failed (E: 76d388e198f23a87dd6596f59c36e826)', { errors: intrinsicErrors });
+            }
+
+            // ----------------------------------------------------------------
+            // 3. Structural keystone + genesis-frame checks
+            // ----------------------------------------------------------------
+            const keystoneService = new KeystoneService_V1();
+            const keystoneErrors = await keystoneService.validateGenesisKeystone({
+                keystoneIbGib
+            });
+            if (keystoneErrors && keystoneErrors.length > 0) {
+                return this.error(422, `Keystone genesis validation failed. Errors: ${keystoneErrors} (E: 8384285be7a8ab0d41cfd1df2e2aa826)`, { errors: keystoneErrors });
+            }
+
+            // ----------------------------------------------------------------
+            // 4. Domain uniqueness & Email Index Registration
+            // ----------------------------------------------------------------
+            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+            const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: addr });
+            const domainGib = tjpGib || punctiliarHash;
+            if (!domainGib) {
+                return this.error(422, `Could not extract domain identifier from keystone address: ${addr} (E: 2758588a6d7cc77f078e97989feed326)`);
+            }
+
+            const domainRootPath = getDomainRootPath(domainGib, reqCtx.dataDir);
+            if (existsSync(domainRootPath)) {
+                return this.error(409, `Domain already exists for this keystone (tjpGib: ${domainGib}). Use PUT /api/keystone/evolve/:domainAddr to evolve. (E: 1c56c8885781c86df89cbdfc1b310626)`);
+            }
+
+            // 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;
+                }
+            }
+
+            // ----------------------------------------------------------------
+            // 5. Bootstrap the new domain metaspace (creates folders)
+            // ----------------------------------------------------------------
+            const metaspace = await bootstrapDomainMetaspace(addr, reqCtx.dataDir);
+
+            // ----------------------------------------------------------------
+            // 6. Persist the genesis keystone into the new domain space
+            // ----------------------------------------------------------------
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                throw new Error(`(UNEXPECTED) Could not get local user space after bootstrapping domain for ${addr} (E: b1c2d3e4f5a6b7c8d9e0f1a2b3c4d526)`);
+            }
+
+            await metaspace.put({ ibGibs: [keystoneIbGib], space });
+            await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space });
+
+            console.log(`${lc} domain created and keystone persisted: ${addr}`);
+            // if (logalot) { console.log(`${lc} keystoneIbGib: ${pretty(keystoneIbGib)} (I: d598c6ff7a48997d585b84c19c464826)`); }
+            return this.ok({ success: true, addr }, 201);
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}