@ibgib/node-gib 0.0.14 → 0.0.15

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

@@ -6,16 +6,17 @@
  * Looks up a primary identity keystone by username or email hash in the server's identity index.
  */
 
-import * as path from 'node:path';
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
-import { IdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
-import { getIdentityEmailHash } from '../../../identity-index/identity-index-helpers.mjs';
+import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../server-constants.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';
 import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
 
+const logalot = GLOBAL_LOG_A_LOT || true;
+
 /**
  * POST /api/keystone/lookup
  */
@@ -46,28 +47,23 @@ export class KeystoneLookupHandler extends ServeGibHandlerBase<undefined, undefi
                 return this.error(400, 'Identifier is required');
             }
 
-            const indexService = new IdentityIndexService({ baseDir: path.join(reqCtx.dataDir, 'index') });
+            const indexService = getIdentityIndexService();
+            if (logalot) { console.log(`${lc} identifier: ${identifier} (I: 1c417812d9781c5888090ae8d18d0826)`); }
             const record = await indexService.getEmailIndex({ email: identifier });
+            if (logalot) { console.log(`${lc} record: ${record ? pretty(record) : 'undefined'} (I: 7c6ce86b3ad8e3a138991211b5ec5826)`); }
 
             if (!record) {
                 console.log(`${lc} Lookup missed for identifier '${identifier}'`);
-                return this.error(404, `No registered identity found for '${identifier}'. Please check your username/email or create a new account.`);
+                return this.error(404, `No registered identity found for '${identifier}'. Please check your email or create a new account.`);
             }
 
             const { tjpAddr } = record;
-            const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: tjpAddr });
-            const domainGib = tjpGib || punctiliarHash;
-
-            if (!domainGib) {
-                console.error(`${lc} Could not extract domain identifier from tjpAddr: ${tjpAddr}`);
-                return this.error(500, `Internal server error locating primary identity.`);
-            }
 
             // Load primary keystone from domain space
             const metaspace = await bootstrapDomainMetaspace(tjpAddr, reqCtx.dataDir);
             const space = await metaspace.getLocalUserSpace({ lock: false });
             if (!space) {
-                console.error(`${lc} Could not load space for domain ${domainGib}`);
+                console.error(`${lc} Could not load space for domain ${tjpAddr}`);
                 return this.error(500, `Internal server error loading domain space.`);
             }
 

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

@@ -12,7 +12,7 @@ import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { KeystoneParams } from './keystone-handler-types.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT || true;
+const logalot = GLOBAL_LOG_A_LOT;
 
 /**
  * POST /api/keystone

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

@@ -1,13 +1,13 @@
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.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 { ServeGibHandlerBase } from '../../handler-base.mjs';
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
 import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT || true;
+const logalot = GLOBAL_LOG_A_LOT;
 
 let custodian: SsoCustodianService | undefined;
 function getCustodian(): SsoCustodianService {

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

@@ -1,17 +1,17 @@
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.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 { SsoProviderId } from '@ibgib/web-gib/dist/identity/sso/sso-types.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '../../../../identity/sso/sso-custodian-service.mjs';
+import { SsoProviderId } from '../../../../identity/sso/sso-types.mjs';
 import { isSsoProviderLinked } from '@ibgib/web-gib/dist/identity/sso/sso-helpers.mjs';
 import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-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, ServeGibHttpMethod } from '../../../types.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT || true;
+const logalot = GLOBAL_LOG_A_LOT;
 
 let custodian: SsoCustodianService | undefined;
 function getCustodian(): SsoCustodianService {
@@ -67,30 +67,30 @@ export class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams,
     protected async handleRouteImpl(reqCtx: RequestContext<LinkParams>): Promise<ResponseResult | undefined> {
         const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
         try {
-            if (logalot) { console.log(`${lc} starting...`); }
+            if (logalot) { console.log(`${lc} starting... (I: 8a4c1f930e7b2d5a6c1e9f8a3b5c7d1e)`); }
 
             if (!reqCtx.params) {
-                return this.error(400, 'Invalid parameters: parentTjpAddr missing');
+                return this.error(400, 'Invalid parameters: parentTjpAddr missing (E: c9f1a2b3d4e5f60718293a4b5c6d7e8f)');
             }
             if (!reqCtx.metaspace) {
-                return this.error(500, 'Metaspace not initialized');
+                return this.error(500, 'Metaspace not initialized (E: d0a1b2c3d4e5f6789a0b1c2d3e4f5a6b)');
             }
 
             let parsed: LinkBody;
             try {
                 parsed = JSON.parse(reqCtx.body);
             } catch {
-                return this.error(400, 'Request body must be valid JSON');
+                return this.error(400, 'Request body must be valid JSON (E: e1b2c3d4e5f67890a1b2c3d4e5f67890)');
             }
 
             const { code, providerId, parentTjpAddr, userNonce, redirectUri } = parsed;
             if (!code || !providerId || !parentTjpAddr || !userNonce || !redirectUri) {
-                return this.error(400, 'Body missing required parameters (code, providerId, parentTjpAddr, userNonce, redirectUri)');
+                return this.error(400, 'Body missing required parameters (code, providerId, parentTjpAddr, userNonce, redirectUri) (E: f2c3d4e5f6789012a3b4c5d6e7f89012)');
             }
 
             const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
             if (!space) {
-                return this.error(500, 'No local user space found in domain metaspace');
+                return this.error(500, 'No local user space found in domain metaspace (E: 03d4e5f678901234b5c6d7e8f9012345)');
             }
 
             // 0. Fetch target keystone and verify if already linked
@@ -101,17 +101,29 @@ export class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams,
                 space
             });
             if (!targetKeystone) {
-                return this.error(400, `Keystone not found for address: ${parentTjpAddr}`);
+                return this.error(400, `Keystone not found for address: ${parentTjpAddr} (E: 14e5f67890123456c7d8e9f012345678)`);
             }
 
             if (isSsoProviderLinked({ keystone: targetKeystone, providerId })) {
-                return this.error(400, `SSO provider "${providerId}" is already linked to this keystone.`);
+                return this.error(400, `SSO provider "${providerId}" is already linked to this keystone. (E: 25f6789012345678d9e0f12345678901)`);
             }
 
             // 1. Authenticate with provider and retrieve user info
             const service = getCustodian();
             const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
 
+            if (userInfo.email) {
+                try {
+                    await getIdentityIndexService().registerEmailIndex({
+                        email: userInfo.email,
+                        primaryTjpAddr: parentTjpAddr,
+                    });
+                    console.log(`(I: 9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c) Registered email index for SSO provider ${providerId}: ${userInfo.email}`);
+                } catch (err: any) {
+                    console.log(`${lc} Email index registration note for ${userInfo.email}: ${err.message} (I: 3607890123456789e0f1a23456789012)`);
+                }
+            }
+
             // 2. Generate the custodian foreign challenge pool
             const custodianPool = await service.createCustodianChallengePool({
                 providerId,
@@ -122,7 +134,7 @@ export class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams,
                 space
             });
 
-            console.log(`${lc} created custodian pool for: ${userInfo.providerKey}`);
+            console.log(`${lc} created custodian pool for: ${userInfo.providerKey} (I: 4718901234567890f1a2b34567890123)`);
 
             return this.ok({
                 success: true,
@@ -131,10 +143,10 @@ export class SsoLinkHandler extends ServeGibHandlerWithMetaspaceBase<LinkParams,
 
         } catch (error) {
             const emsg = extractErrorMsg(error);
-            console.error(`${lc} Link failed: ${emsg}`);
-            return this.error(500, `Link failed: ${emsg}`);
+            console.error(`${lc} Link failed: ${emsg} (E: 5829012345678901a2b3c45678901234)`);
+            return this.error(500, `Link failed: ${emsg} (E: 693a012345678901b2c3d45678901234)`);
         } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
+            if (logalot) { console.log(`${lc} complete. (I: 7a4b123456789012c3d4e56789012345)`); }
         }
     }
 }

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

@@ -1,18 +1,19 @@
 import { createHmac } from 'node:crypto';
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.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 { SsoProviderId } from '@ibgib/web-gib/dist/identity/sso/sso-types.mjs';
-import { POOL_ID_CUSTODIAN_MANAGE, KEYSTONE_VERB_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '../../../../identity/sso/sso-custodian-service.mjs';
+import { SsoProviderId } from '../../../../identity/sso/sso-types.mjs';
+import { KEYSTONE_VERB_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
 import { KeystoneStrategyFactory } from '@ibgib/core-gib/dist/keystone/strategy/keystone-strategy-factory.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.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, ServeGibHttpMethod } from '../../../types.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT || true;
+const logalot = GLOBAL_LOG_A_LOT;
 
 let custodian: SsoCustodianService | undefined;
 function getCustodian(): SsoCustodianService {
@@ -33,13 +34,13 @@ function signSessionToken(payload: any, secret: string): string {
 }
 
 interface LoginParams extends ParamsWithDomain {
-    parentTjpAddr: string;
+    parentTjpAddr?: string;
 }
 
 interface LoginBody {
     code: string;
     providerId: SsoProviderId;
-    parentTjpAddr: string;
+    parentTjpAddr?: string;
     userNonce: string;
     redirectUri: string;
 }
@@ -61,16 +62,21 @@ export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParam
         try {
             parsed = JSON.parse(reqCtx.body);
         } catch {
-            return undefined;
+            return { parentTjpAddr: undefined, domainInfo: undefined as any };
         }
         const parentTjpAddr = parsed?.parentTjpAddr;
-        if (!parentTjpAddr) { return undefined; }
         return {
             parentTjpAddr,
-            domainInfo: this.getDomainInfo({ domainAddr: parentTjpAddr })
+            domainInfo: parentTjpAddr ? this.getDomainInfo({ domainAddr: parentTjpAddr }) : (undefined as any)
         };
     }
 
+    protected override async initConcreteContext(reqCtx: RequestContext<LoginParams, any>): Promise<void> {
+        if (reqCtx.params?.domainInfo) {
+            await this.initAndPopulateDomainContext(reqCtx);
+        }
+    }
+
     protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
         return [];
     }
@@ -78,62 +84,75 @@ export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParam
     protected async handleRouteImpl(reqCtx: RequestContext<LoginParams>): Promise<ResponseResult | undefined> {
         const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
         try {
-            if (logalot) { console.log(`${lc} starting...`); }
-
-            if (!reqCtx.params) {
-                return this.error(400, 'Invalid parameters: parentTjpAddr missing');
-            }
-            if (!reqCtx.metaspace) {
-                return this.error(500, 'Metaspace not initialized');
-            }
+            if (logalot) { console.log(`${lc} starting... (I: 9b5d2a3c4e5f67890a1b2c3d4e5f6789)`); }
 
             let parsed: LoginBody;
             try {
                 parsed = JSON.parse(reqCtx.body);
             } catch {
-                return this.error(400, 'Request body must be valid JSON');
+                return this.error(400, 'Request body must be valid JSON (E: 0a1b2c3d4e5f67890a1b2c3d4e5f6789)');
             }
 
-            const { code, providerId, parentTjpAddr, userNonce, redirectUri } = parsed;
-            if (!code || !providerId || !parentTjpAddr || !userNonce || !redirectUri) {
-                return this.error(400, 'Body missing required parameters (code, providerId, parentTjpAddr, userNonce, redirectUri)');
-            }
-
-            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
-            if (!space) {
-                return this.error(500, 'No local user space found in domain metaspace');
+            const { code, providerId, userNonce, redirectUri } = parsed;
+            let parentTjpAddr = parsed?.parentTjpAddr;
+            if (!code || !providerId || !userNonce || !redirectUri) {
+                return this.error(400, 'Body missing required parameters (code, providerId, userNonce, redirectUri) (E: 1b2c3d4e5f678901b2c3d4e5f6789012)');
             }
 
             // 1. Authenticate with provider and retrieve user info
             const service = getCustodian();
             const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
 
+            let resolvedParentTjpAddr = parentTjpAddr;
+            if (!resolvedParentTjpAddr) {
+                if (!userInfo.email) {
+                    return this.error(404, 'No email returned from SSO provider to perform identity lookup. (E: 2c3d4e5f67890123c4d5e6f789012345)');
+                }
+                const lookup = await getIdentityIndexService().lookupIdentityByEmail({
+                    email: userInfo.email,
+                });
+                if (!lookup || !lookup.primaryTjpAddr) {
+                    return this.error(404, `No identity found linked to email ${userInfo.email} (E: 3d4e5f6789012345d6e7f89012345678)`);
+                }
+                resolvedParentTjpAddr = lookup.primaryTjpAddr;
+            }
+
+            // Ensure metaspace is initialized with resolvedParentTjpAddr
+            if (!reqCtx.metaspace) {
+                reqCtx.metaspace = await bootstrapDomainMetaspace(resolvedParentTjpAddr, reqCtx.dataDir);
+            }
+
+            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                return this.error(500, 'No local user space found in domain metaspace (E: 4e5f678901234567e8f9012345678901)');
+            }
+
             // 2. Derive custodian secret using providerKey and userNonce
             const custodianSecret = await service.deriveServerDelegateSecret(userInfo.providerKey, userNonce);
 
             // 3. Fetch latest parent keystone from metaspace
-            const latestParentAddr = await reqCtx.metaspace.getLatestAddr({ addr: parentTjpAddr, space });
+            const latestParentAddr = await reqCtx.metaspace.getLatestAddr({ addr: resolvedParentTjpAddr, space });
             if (!latestParentAddr) {
-                return this.error(404, `Parent identity keystone not found for address: ${parentTjpAddr}`);
+                return this.error(404, `Parent identity keystone not found for address: ${resolvedParentTjpAddr} (E: 5f67890123456789f0a1b23456789012)`);
             }
 
             const resGet = await reqCtx.metaspace.get({ addr: latestParentAddr, space });
             const parentKeystone = resGet.ibGibs?.[0];
             if (!parentKeystone) {
-                return this.error(404, `Parent identity keystone not found in space for address: ${latestParentAddr}`);
+                return this.error(404, `Parent identity keystone not found in space for address: ${latestParentAddr} (E: 6078901234567890a1b2c34567890123)`);
             }
 
             // 4. Resolve the custodian pool from the parent keystone using dynamic poolId
             const targetPoolId = `custodian-manage-${providerId}`;
             const custodianPool = parentKeystone.data?.challengePools?.find((p: any) => p.id === targetPoolId);
             if (!custodianPool) {
-                return this.error(401, `Unauthorized: Custodian pool '${targetPoolId}' is not registered in the parent identity keystone.`);
+                return this.error(401, `Unauthorized: Custodian pool '${targetPoolId}' is not registered in the parent identity keystone. (E: 7189012345678901b2c3d45678901234)`);
             }
 
             // 5. Assert allowed verbs contain KEYSTONE_VERB_MANAGE
             const allowedVerbs = custodianPool.config.allowedVerbs || [];
             if (!allowedVerbs.includes(KEYSTONE_VERB_MANAGE)) {
-                return this.error(401, `Unauthorized: Custodian pool does not have the required manage permission.`);
+                return this.error(401, `Unauthorized: Custodian pool does not have the required manage permission. (E: 8290123456789012c3d4e56789012345)`);
             }
 
             // 6. Cryptographically verify the custodian secret against the pool's challenges
@@ -148,13 +167,20 @@ export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParam
                 });
                 const hashValue = await strategy.generateChallenge({ solution });
                 if (hashValue.hash !== (challenge as any).hash) {
-                    return this.error(401, 'Unauthorized: Cryptographic verification of custodian pool challenges failed.');
+                    return this.error(401, 'Unauthorized: Cryptographic verification of custodian pool challenges failed. (E: 9301234567890123d4e5f67890123456)');
                 }
             }
 
+            // Fetch domain graph to return in response
+            const domainGraph = await reqCtx.metaspace.getDependencyGraph({
+                ibGibAddr: latestParentAddr,
+                live: false,
+                space,
+            });
+
             // 7. Issue secure HttpOnly session cookie
             const sessionPayload = {
-                parentTjpAddr,
+                parentTjpAddr: resolvedParentTjpAddr,
                 providerKey: userInfo.providerKey,
                 exp: Math.floor(Date.now() / 1000) + 24 * 3600 // 24-hour expiration
             };
@@ -166,14 +192,16 @@ export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParam
                 'Set-Cookie': `space_gib_session=${sessionToken}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`
             };
 
-            console.log(`${lc} login successful for parent: ${parentTjpAddr}, custodian providerKey: ${userInfo.providerKey}`);
+            console.log(`${lc} login successful for parent: ${resolvedParentTjpAddr}, custodian providerKey: ${userInfo.providerKey} (I: 0412345678901234e5f6a78901234567)`);
 
             return {
                 status: 200,
                 headers,
                 body: {
                     success: true,
-                    parentTjpAddr,
+                    parentTjpAddr: resolvedParentTjpAddr,
+                    domainGraph,
+                    token: sessionToken,
                     custodianPoolId: custodianPool.id
                 },
                 isJson: true
@@ -181,10 +209,11 @@ export class SsoLoginHandler extends ServeGibHandlerWithMetaspaceBase<LoginParam
 
         } catch (error) {
             const emsg = extractErrorMsg(error);
-            console.error(`${lc} Login failed: ${emsg}`);
-            return this.error(500, `Login failed: ${emsg}`);
+            console.error(`${lc} Login failed: ${emsg} (E: 1523456789012345f6a7b89012345678)`);
+            return this.error(500, `Login failed: ${emsg} (E: 2634567890123456a7b8c90123456789)`);
         } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
+            if (logalot) { console.log(`${lc} complete. (I: 3745678901234567b8c9d01234567890)`); }
         }
     }
 }
+

package/src/serve-gib/identity-index/identity-index-constants.mts

@@ -1,3 +1,6 @@
+import * as path from 'path';
+
 export const DEFAULT_IDENTITY_INDEX_DIR_NAME = 'identity_index';
-export const DEFAULT_EMAIL_HASHES_SUBDIR = 'email_hashes';
-export const DEFAULT_IDENTITY_INDEX_SALT = 'ibgib_identity_salt_default_v1';
+export const DEFAULT_EMAIL_HASHES_SUBDIR = path.join('email', 'hashes');
+export const DEFAULT_EMAIL_PENDING_SUBDIR = path.join('email', 'pending');
+export const DEFAULT_IDENTITY_INDEX_SALT = 'emailindex';

package/src/serve-gib/identity-index/identity-index-helpers.mts

@@ -1,8 +1,12 @@
 import * as path from 'path';
-import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { KEYSTONE_EMAIL_REGEXP } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../server-constants.mjs';
 import { DEFAULT_EMAIL_HASHES_SUBDIR, DEFAULT_IDENTITY_INDEX_SALT } from './identity-index-constants.mjs';
 
+const logalot = GLOBAL_LOG_A_LOT || true;
+
 /**
  * Validates an email address against length constraints and KEYSTONE_EMAIL_REGEXP.
  * Returns an array of error message strings (empty `[]` if valid).
@@ -68,18 +72,28 @@ export function getShardedIndexPath({
     baseDir: string;
     emailHash: string;
 }): { folderPath: string; filePath: string; filename: string } {
-    if (!emailHash || emailHash.length < 7) {
-        throw new Error(`Invalid email hash string '${emailHash}'. Must be at least 7 characters. (E: 7aeb7885a7f1b4576899db283516d826)`);
-    }
+    const lc = `[${getShardedIndexPath.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 3029e6a0fbf8b72988d694e8a0d53c26)`); }
 
-    const f1 = emailHash.slice(0, 2);
-    const f2 = emailHash.slice(2, 4);
-    const f3 = emailHash.slice(4, 6);
-    const remainingHash = emailHash.slice(6);
-    const filename = `${remainingHash}.json`;
+        if (!emailHash || emailHash.length < 7) {
+            throw new Error(`Invalid email hash string '${emailHash}'. Must be at least 7 characters. (E: 7aeb7885a7f1b4576899db283516d826)`);
+        }
 
-    const folderPath = path.join(baseDir, DEFAULT_EMAIL_HASHES_SUBDIR, f1, f2, f3);
-    const filePath = path.join(folderPath, filename);
+        const f1 = emailHash.slice(0, 2);
+        const f2 = emailHash.slice(2, 4);
+        const f3 = emailHash.slice(4, 6);
+        const remainingHash = emailHash.slice(6);
+        const filename = `${remainingHash}.json`;
 
-    return { folderPath, filePath, filename };
+        const folderPath = path.join(baseDir, DEFAULT_EMAIL_HASHES_SUBDIR, f1, f2, f3);
+        const filePath = path.join(folderPath, filename);
+
+        return { folderPath, filePath, filename };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }