@ibgib/node-gib 0.0.9 → 0.0.13

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

@@ -0,0 +1,109 @@
+import * as fs from 'fs/promises';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { DEFAULT_IDENTITY_INDEX_SALT } from './identity-index-constants.mjs';
+import { getIdentityEmailHash, getShardedIndexPath } from './identity-index-helpers.mjs';
+import { IdentityIndexRecord, IdentityIndexServiceOptions, RegisterEmailIndexResult } from './identity-index-types.mjs';
+
+/**
+ * Service managing atomic, sharded identity index files for backwards email -> primary identity tjpAddr lookups.
+ */
+export class IdentityIndexService {
+    private baseDir: string;
+    private salt: string;
+
+    constructor({ baseDir, salt }: IdentityIndexServiceOptions) {
+        if (!baseDir) { throw new Error('baseDir must be provided to IdentityIndexService.'); }
+        this.baseDir = baseDir;
+        this.salt = salt || process.env.IDENTITY_INDEX_SALT || DEFAULT_IDENTITY_INDEX_SALT;
+    }
+
+    /**
+     * Registers an email to a primary identity tjpAddr.
+     * Uses atomic OS file creation (`flag: 'wx'`) to guarantee single-server ACID uniqueness.
+     * Throws `duplicate_identity_409` error if email is already registered.
+     */
+    async registerEmailIndex({
+        email,
+        tjpAddr,
+    }: {
+        email: string;
+        tjpAddr: IbGibAddr;
+    }): Promise<RegisterEmailIndexResult> {
+        const emailHash = await getIdentityEmailHash({ email, salt: this.salt });
+        const { folderPath, filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+
+        await fs.mkdir(folderPath, { recursive: true });
+
+        const record: IdentityIndexRecord = {
+            tjpAddr,
+            createdAt: Date.now(),
+        };
+
+        try {
+            await fs.writeFile(filePath, JSON.stringify(record, null, 2), { flag: 'wx' });
+            return { emailHash, filePath, record };
+        } catch (error: any) {
+            if (error.code === 'EEXIST') {
+                throw new Error(`Email is already registered (E: duplicate_identity_409)`);
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Retrieves the registered `IdentityIndexRecord` for an email address.
+     * Returns `undefined` if email is not indexed.
+     */
+    async getEmailIndex({
+        email,
+    }: {
+        email: string;
+    }): Promise<IdentityIndexRecord | undefined> {
+        const emailHash = await getIdentityEmailHash({ email, salt: this.salt });
+        return this.getEmailIndexByHash({ emailHash });
+    }
+
+    /**
+     * Retrieves the registered `IdentityIndexRecord` directly by `emailHash`.
+     * Returns `undefined` if hash file does not exist.
+     */
+    async getEmailIndexByHash({
+        emailHash,
+    }: {
+        emailHash: string;
+    }): Promise<IdentityIndexRecord | undefined> {
+        const { filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+        try {
+            const content = await fs.readFile(filePath, 'utf8');
+            const record: IdentityIndexRecord = JSON.parse(content);
+            return record;
+        } catch (error: any) {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Unindexes an email address (deletes the index JSON file).
+     * Returns `true` if unindexed, or `false` if file did not exist.
+     */
+    async unregisterEmailIndex({
+        email,
+    }: {
+        email: string;
+    }): Promise<boolean> {
+        const emailHash = await getIdentityEmailHash({ email, salt: this.salt });
+        const { filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+        try {
+            await fs.unlink(filePath);
+            return true;
+        } catch (error: any) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+}

package/src/serve-gib/identity-index/identity-index-service.respec.mts

@@ -0,0 +1,135 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { IdentityIndexService } from './identity-index-service.mjs';
+import { normalizeEmail, getIdentityEmailHash, getShardedIndexPath, validateEmail } from './identity-index-helpers.mjs';
+
+const sir = `[${import.meta.url}]`;
+const TEST_SALT = 'test_salt_12345';
+const TEST_BASE_DIR = path.join(process.cwd(), 'test-data-identity-index');
+
+await respecfully(sir, 'IdentityIndexService & Helpers', async () => {
+
+    // Cleanup test data directory before & after tests
+    const cleanupDir = async () => {
+        try {
+            await fs.rm(TEST_BASE_DIR, { recursive: true, force: true });
+        } catch { /* ignore */ }
+    };
+
+    await cleanupDir();
+
+    await ifWe(sir, 'normalize email strings correctly', async () => {
+        iReckon(sir, normalizeEmail('  Alice@Example.com ')).willEqual('alice@example.com');
+        iReckon(sir, normalizeEmail('BOB@DOMAIN.ORG')).willEqual('bob@domain.org');
+        iReckon(sir, normalizeEmail('')).willEqual('');
+    });
+
+    await ifWe(sir, 'validate email addresses accurately using validateEmail', async () => {
+        // Valid emails
+        iReckon(sir, validateEmail({ email: 'user@example.com' }).length).willEqual(0);
+        iReckon(sir, validateEmail({ email: 'user+tag@sub.domain.co.uk' }).length).willEqual(0);
+        iReckon(sir, validateEmail({ email: '  alice@company.org ' }).length).willEqual(0);
+
+        // Invalid emails
+        iReckon(sir, validateEmail({ email: '' }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: '   ' }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: null }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: undefined }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: 'no-at-sign.com' }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: 'user@no-dot' }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: 'user @space.com' }).length > 0).isGonnaBeTrue();
+        iReckon(sir, validateEmail({ email: '@domain.com' }).length > 0).isGonnaBeTrue();
+    });
+
+    await ifWe(sir, 'calculate consistent SHA256 email hashes with salt', async () => {
+        const hash1 = await getIdentityEmailHash({ email: 'Alice@Example.com', salt: TEST_SALT });
+        const hash2 = await getIdentityEmailHash({ email: 'alice@example.com', salt: TEST_SALT });
+        iReckon(sir, hash1).willEqual(hash2);
+        iReckon(sir, hash1.length > 30).isGonnaBeTrue();
+
+        const diffSaltHash = await getIdentityEmailHash({ email: 'alice@example.com', salt: 'different_salt' });
+        iReckon(sir, hash1).not.willEqual(diffSaltHash);
+    });
+
+    await ifWe(sir, 'calculate sharded folder paths and truncated filenames', async () => {
+        const fullHash = 'abcdef1234567890abcdef1234567890';
+        const { folderPath, filePath, filename } = getShardedIndexPath({ baseDir: TEST_BASE_DIR, emailHash: fullHash });
+
+        const expectedSubfolder = path.join(TEST_BASE_DIR, 'email_hashes', 'ab', 'cd', 'ef');
+        iReckon(sir, folderPath).willEqual(expectedSubfolder);
+
+        // Filename strips the leading 6 chars ('abcdef')
+        iReckon(sir, filename).willEqual('1234567890abcdef1234567890.json');
+        iReckon(sir, filePath).willEqual(path.join(expectedSubfolder, '1234567890abcdef1234567890.json'));
+    });
+
+    await ifWe(sir, 'register an email index and read it back', async () => {
+        const service = new IdentityIndexService({ baseDir: TEST_BASE_DIR, salt: TEST_SALT });
+        const email = 'user1@example.com';
+        const tjpAddr = 'keystone^AF5BB54AE1254FB499C434A2915C6BA08BC1D53936E57D19D415EA17FA3CE475';
+
+        const result = await service.registerEmailIndex({ email, tjpAddr });
+        iReckon(sir, result.emailHash).isGonnaBeTruthy();
+        iReckon(sir, result.record.tjpAddr).willEqual(tjpAddr);
+        iReckon(sir, result.record.createdAt > 0).isGonnaBeTrue();
+
+        const retrieved = await service.getEmailIndex({ email });
+        iReckon(sir, retrieved).isGonnaBeTruthy();
+        iReckon(sir, retrieved!.tjpAddr).willEqual(tjpAddr);
+    });
+
+    await ifWe(sir, 'atomically reject duplicate email registration with duplicate_identity_409', async () => {
+        const service = new IdentityIndexService({ baseDir: TEST_BASE_DIR, salt: TEST_SALT });
+        const email = 'duplicate@example.com';
+        const tjpAddr1 = 'keystone^1111111111111111111111111111111111111111111111111111111111111111';
+        const tjpAddr2 = 'keystone^2222222222222222222222222222222222222222222222222222222222222222';
+
+        await service.registerEmailIndex({ email, tjpAddr: tjpAddr1 });
+
+        let duplicateCaught = false;
+        try {
+            await service.registerEmailIndex({ email, tjpAddr: tjpAddr2 });
+        } catch (error: any) {
+            if (error.message.includes('duplicate_identity_409')) {
+                duplicateCaught = true;
+            }
+        }
+
+        iReckon(sir, duplicateCaught).asTo('duplicate registration rejected via flag wx EEXIST').isGonnaBeTrue();
+    });
+
+    await ifWe(sir, 'support multiple email hashes pointing to the same identity tjpAddr', async () => {
+        const service = new IdentityIndexService({ baseDir: TEST_BASE_DIR, salt: TEST_SALT });
+        const primaryTjp = 'keystone^3333333333333333333333333333333333333333333333333333333333333333';
+
+        const email1 = 'personal@example.com';
+        const email2 = 'work@company.com';
+
+        await service.registerEmailIndex({ email: email1, tjpAddr: primaryTjp });
+        await service.registerEmailIndex({ email: email2, tjpAddr: primaryTjp });
+
+        const record1 = await service.getEmailIndex({ email: email1 });
+        const record2 = await service.getEmailIndex({ email: email2 });
+
+        iReckon(sir, record1!.tjpAddr).willEqual(primaryTjp);
+        iReckon(sir, record2!.tjpAddr).willEqual(primaryTjp);
+    });
+
+    await ifWe(sir, 'unregister an email index cleanly', async () => {
+        const service = new IdentityIndexService({ baseDir: TEST_BASE_DIR, salt: TEST_SALT });
+        const email = 'delete-me@example.com';
+        const tjpAddr = 'keystone^4444444444444444444444444444444444444444444444444444444444444444';
+
+        await service.registerEmailIndex({ email, tjpAddr });
+        iReckon(sir, await service.getEmailIndex({ email })).isGonnaBeTruthy();
+
+        const unindexed = await service.unregisterEmailIndex({ email });
+        iReckon(sir, unindexed).isGonnaBeTrue();
+
+        const retrievedAfter = await service.getEmailIndex({ email });
+        iReckon(sir, retrievedAfter).isGonnaBeUndefined();
+    });
+
+    await cleanupDir();
+});

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

@@ -0,0 +1,33 @@
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+
+/**
+ * Record stored in the atomic sharded index JSON file.
+ */
+export interface IdentityIndexRecord {
+    /** Primary identity keystone TJP address. */
+    tjpAddr: IbGibAddr;
+    /** Creation timestamp (Date.now()) in epoch milliseconds. */
+    createdAt: number;
+}
+
+/**
+ * Configuration options for initializing IdentityIndexService.
+ */
+export interface IdentityIndexServiceOptions {
+    /** Base directory where index shards will be stored (e.g. `data/index`). */
+    baseDir: string;
+    /** Server salt for privacy email hashing. Defaults to `DEFAULT_IDENTITY_INDEX_SALT`. */
+    salt?: string;
+}
+
+/**
+ * Result returned upon successful email index registration.
+ */
+export interface RegisterEmailIndexResult {
+    /** Privacy hash derived from normalizeEmail(email) + salt. */
+    emailHash: string;
+    /** Absolute filesystem path of the atomic index JSON file. */
+    filePath: string;
+    /** The index record stored in the file. */
+    record: IdentityIndexRecord;
+}

package/src/serve-gib/index.mts

@@ -0,0 +1,92 @@
+/**
+ * @module serve-gib
+ *
+ * Minimalist, high-observability HTTP & WebSocket microframework for ibgib servers.
+ */
+
+export * from './types.mjs';
+export * from './constants.mjs';
+export * from './path-constants.mjs';
+export * from './path-helper.mjs';
+export * from './bootstrap-helper.mjs';
+export * from './serve-gib-helpers.mjs';
+export * from './serve-gib-v1.mjs';
+export * from './keystone-schema-helpers.mjs';
+export * from './identity-index/identity-index-types.mjs';
+export * from './identity-index/identity-index-constants.mjs';
+export * from './identity-index/identity-index-helpers.mjs';
+export * from './identity-index/identity-index-service.mjs';
+
+// Handlers
+export * from './handlers/handler-base.mjs';
+export * from './handlers/static-handler.mjs';
+export * from './handlers/error-handler.mjs';
+export * from './handlers/api/health.handler.mjs';
+export * from './handlers/api/ibgib/ibgib-handler-types.mjs';
+export * from './handlers/api/ibgib/ibgib.handler.mjs';
+export * from './handlers/api/keystone/keystone-handler-types.mjs';
+export * from './handlers/api/keystone/keystone-genesis.handler.mjs';
+export * from './handlers/api/keystone/keystone-evolve.handler.mjs';
+export * from './handlers/api/keystone/keystone-post.handler.mjs';
+export * from './handlers/api/keystone/keystone-get.handler.mjs';
+export * from './handlers/api/keystone/keystone-lookup.handler.mjs';
+export * from './handlers/api/keystone/keystone-check-email.handler.mjs';
+export * from './handlers/api/keystone/sso-config.handler.mjs';
+export * from './handlers/api/keystone/sso-link.handler.mjs';
+export * from './handlers/api/keystone/sso-login.handler.mjs';
+export * from './handlers/api/email/email-inbound.handler.mjs';
+export * from './handlers/api/email/email-outbound.handler.mjs';
+export * from './handlers/api/debug/ws-echo.handler.mjs';
+export * from './handlers/ws/ws-types.mjs';
+export * from './handlers/ws/ws-helper.mjs';
+export * from './handlers/ws/sync-upgrade-handler-base.mjs';
+export * from './handlers/ws/sync-upgrade.handler.mjs';
+
+import { ServeGibHandler } from './types.mjs';
+import { HealthHandler } from './handlers/api/health.handler.mjs';
+import { IbGibHandler } from './handlers/api/ibgib/ibgib.handler.mjs';
+import { KeystoneGenesisHandler } from './handlers/api/keystone/keystone-genesis.handler.mjs';
+import { KeystoneEvolveHandler } from './handlers/api/keystone/keystone-evolve.handler.mjs';
+import { KeystonePostHandler } from './handlers/api/keystone/keystone-post.handler.mjs';
+import { KeystoneGetHandler } from './handlers/api/keystone/keystone-get.handler.mjs';
+import { KeystoneLookupHandler } from './handlers/api/keystone/keystone-lookup.handler.mjs';
+import { KeystoneCheckEmailHandler } from './handlers/api/keystone/keystone-check-email.handler.mjs';
+import { SsoLinkHandler } from './handlers/api/keystone/sso-link.handler.mjs';
+import { SsoLoginHandler } from './handlers/api/keystone/sso-login.handler.mjs';
+import { SsoConfigHandler } from './handlers/api/keystone/sso-config.handler.mjs';
+import { EmailInboundHandler } from './handlers/api/email/email-inbound.handler.mjs';
+import { EmailOutboundHandler } from './handlers/api/email/email-outbound.handler.mjs';
+import { StaticFileHandler } from './handlers/static-handler.mjs';
+
+export interface StandardHandlersOptions {
+    /** Absolute path to the client SPA static assets directory. */
+    clientDir?: string;
+}
+
+/**
+ * Returns the standard pipeline array of ibgib HTTP request handlers for serve-gib.
+ */
+export function getStandardServeGibHandlers(opts: StandardHandlersOptions = {}): ServeGibHandler<any, any>[] {
+    const handlers: ServeGibHandler<any, any>[] = [
+        new HealthHandler(),
+        new IbGibHandler(),
+        new KeystoneGenesisHandler(),
+        new KeystoneEvolveHandler(),
+        new KeystonePostHandler(),
+        new KeystoneGetHandler(),
+        new KeystoneLookupHandler(),
+        new KeystoneCheckEmailHandler(),
+        new SsoLinkHandler(),
+        new SsoLoginHandler(),
+        new SsoConfigHandler(),
+        new EmailInboundHandler(),
+        new EmailOutboundHandler(),
+    ];
+
+    if (opts.clientDir) {
+        handlers.push(new StaticFileHandler(opts.clientDir));
+    }
+
+    return handlers;
+}
+

package/src/serve-gib/keystone-schema-helpers.mts

@@ -0,0 +1,120 @@
+/**
+ * Strict flatcase regex for individual tokens (username, role, deviceId, providerId).
+ * Lowercase alphanumeric characters only [a-z0-9], no hyphens or punctuation.
+ */
+export const FLATCASE_TOKEN_REGEXP = /^[a-z0-9]+$/;
+
+/**
+ * Validates if a string token is strict flatcase ([a-z0-9]+).
+ */
+export function validateFlatcaseToken(token: string): boolean {
+    if (!token || typeof token !== 'string') { return false; }
+    return FLATCASE_TOKEN_REGEXP.test(token);
+}
+
+/**
+ * Sanitizes an input string to strict flatcase ([a-z0-9]).
+ */
+export function sanitizeToken(input: string): string {
+    if (!input || typeof input !== 'string') { return ''; }
+    return input.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Keystone Name Schema validation result.
+ */
+export interface KeystoneNameSchemaResult {
+    valid: boolean;
+    type?: 'primary' | 'delegate';
+    username?: string;
+    role?: string;
+    deviceIdOrProviderId?: string;
+    error?: string;
+}
+
+/**
+ * Validates a keystone name string against the naming conventions:
+ * 1. Primary identity: `[username]` (e.g. `alice`)
+ * 2. Delegate: `[username]-[role]-[deviceIdOrProviderId]` (e.g. `alice-sync-browsera` or `alice-sync-google`)
+ *
+ * Enforces strict flatcase on all inner tokens (`[a-z0-9]+`).
+ */
+export function validateKeystoneNameSchema(name: string): KeystoneNameSchemaResult {
+    if (!name || typeof name !== 'string') {
+        return { valid: false, error: 'Keystone name must be a non-empty string.' };
+    }
+
+    const parts = name.split('-');
+    if (parts.length === 1) {
+        const username = parts[0];
+        if (!validateFlatcaseToken(username)) {
+            return { valid: false, error: `Invalid primary username token '${username}'. Must be flatcase [a-z0-9]+.` };
+        }
+        return { valid: true, type: 'primary', username };
+    } else if (parts.length === 3) {
+        const [username, role, deviceIdOrProviderId] = parts;
+        if (!validateFlatcaseToken(username)) {
+            return { valid: false, error: `Invalid username token '${username}'. Must be flatcase [a-z0-9]+.` };
+        }
+        if (!validateFlatcaseToken(role)) {
+            return { valid: false, error: `Invalid role token '${role}'. Must be flatcase [a-z0-9]+.` };
+        }
+        if (!validateFlatcaseToken(deviceIdOrProviderId)) {
+            return { valid: false, error: `Invalid deviceId/providerId token '${deviceIdOrProviderId}'. Must be flatcase [a-z0-9]+.` };
+        }
+        return { valid: true, type: 'delegate', username, role, deviceIdOrProviderId };
+    } else {
+        return {
+            valid: false,
+            error: `Invalid keystone name format '${name}'. Expected '[username]' or '[username]-[role]-[deviceId]' (3 hyphen-separated flatcase tokens).`
+        };
+    }
+}
+
+/**
+ * Challenge Pool ID Schema validation result.
+ */
+export interface ChallengePoolIdSchemaResult {
+    valid: boolean;
+    isForeign?: boolean;
+    who?: string;
+    what?: string;
+    providerId?: string;
+    error?: string;
+}
+
+/**
+ * Validates a challenge pool ID string against pool conventions:
+ * 1. Native/User-Owned pool: single flatcase word (e.g. `manage`, `default`, `revoke`, `sync`, `connect`).
+ * 2. Custodial/Foreign pool: `custodian-[what]-[providerId]` (e.g. `custodian-manage-google`, `custodian-revoke-github`).
+ */
+export function validateChallengePoolIdSchema(poolId: string): ChallengePoolIdSchemaResult {
+    if (!poolId || typeof poolId !== 'string') {
+        return { valid: false, error: 'Pool ID must be a non-empty string.' };
+    }
+
+    const parts = poolId.split('-');
+    if (parts.length === 1) {
+        if (!validateFlatcaseToken(parts[0])) {
+            return { valid: false, error: `Invalid native pool ID '${poolId}'. Must be flatcase [a-z0-9]+.` };
+        }
+        return { valid: true, isForeign: false };
+    } else if (parts.length === 3) {
+        const [who, what, providerId] = parts;
+        if (who !== 'custodian') {
+            return { valid: false, error: `Invalid foreign pool 'who' token '${who}'. Must be 'custodian'.` };
+        }
+        if (!['manage', 'sync', 'revoke'].includes(what)) {
+            return { valid: false, error: `Invalid foreign pool 'what' token '${what}'. Must be 'manage', 'sync', or 'revoke'.` };
+        }
+        if (!validateFlatcaseToken(providerId)) {
+            return { valid: false, error: `Invalid foreign pool providerId token '${providerId}'. Must be flatcase [a-z0-9]+.` };
+        }
+        return { valid: true, isForeign: true, who, what, providerId };
+    } else {
+        return {
+            valid: false,
+            error: `Invalid challenge pool ID '${poolId}'. Expected single flatcase word or 'custodian-[what]-[providerId]'.`
+        };
+    }
+}

package/src/serve-gib/keystone-schema-helpers.respec.mts

@@ -0,0 +1,85 @@
+import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import {
+    validateFlatcaseToken,
+    sanitizeToken,
+    validateKeystoneNameSchema,
+    validateChallengePoolIdSchema,
+} from './keystone-schema-helpers.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'Keystone Schema Helpers', async () => {
+
+    await ifWe(sir, 'validate flatcase tokens accurately', async () => {
+        iReckon(sir, validateFlatcaseToken('alice')).isGonnaBeTrue();
+        iReckon(sir, validateFlatcaseToken('bobbobbins')).isGonnaBeTrue();
+        iReckon(sir, validateFlatcaseToken('dev123')).isGonnaBeTrue();
+        iReckon(sir, validateFlatcaseToken('google')).isGonnaBeTrue();
+
+        // Invalid: hyphens, uppercase, spaces, special chars
+        iReckon(sir, validateFlatcaseToken('alice-bob')).isGonnaBeFalse();
+        iReckon(sir, validateFlatcaseToken('Alice')).isGonnaBeFalse();
+        iReckon(sir, validateFlatcaseToken('user_name')).isGonnaBeFalse();
+        iReckon(sir, validateFlatcaseToken('user@domain')).isGonnaBeFalse();
+        iReckon(sir, validateFlatcaseToken('')).isGonnaBeFalse();
+    });
+
+    await ifWe(sir, 'sanitize tokens to clean flatcase', async () => {
+        iReckon(sir, sanitizeToken('Alice_Bob-123!')).willEqual('alicebob123');
+        iReckon(sir, sanitizeToken('user.name@example.com')).willEqual('usernameexamplecom');
+        iReckon(sir, sanitizeToken('GOOGLE-auth')).willEqual('googleauth');
+    });
+
+    await ifWe(sir, 'validate primary and delegate keystone names', async () => {
+        // Happy path primary identity
+        const resPrimary = validateKeystoneNameSchema('alice');
+        iReckon(sir, resPrimary.valid).isGonnaBeTrue();
+        iReckon(sir, resPrimary.type).willEqual('primary');
+        iReckon(sir, resPrimary.username).willEqual('alice');
+
+        // Happy path local device delegate
+        const resDelegateDev = validateKeystoneNameSchema('alice-sync-dev123');
+        iReckon(sir, resDelegateDev.valid).isGonnaBeTrue();
+        iReckon(sir, resDelegateDev.type).willEqual('delegate');
+        iReckon(sir, resDelegateDev.username).willEqual('alice');
+        iReckon(sir, resDelegateDev.role).willEqual('sync');
+        iReckon(sir, resDelegateDev.deviceIdOrProviderId).willEqual('dev123');
+
+        // Happy path SSO custodial delegate
+        const resDelegateSSO = validateKeystoneNameSchema('alice-sync-google');
+        iReckon(sir, resDelegateSSO.valid).isGonnaBeTrue();
+        iReckon(sir, resDelegateSSO.type).willEqual('delegate');
+        iReckon(sir, resDelegateSSO.username).willEqual('alice');
+        iReckon(sir, resDelegateSSO.role).willEqual('sync');
+        iReckon(sir, resDelegateSSO.deviceIdOrProviderId).willEqual('google');
+
+        // Sad paths: invalid token casing or hyphen counts
+        iReckon(sir, validateKeystoneNameSchema('alice-sync-dev-123').valid).isGonnaBeFalse(); // 4 parts
+        iReckon(sir, validateKeystoneNameSchema('Alice-sync-dev123').valid).isGonnaBeFalse(); // Uppercase
+        iReckon(sir, validateKeystoneNameSchema('alice_bob').valid).isGonnaBeFalse(); // Underscore not allowed in flatcase token
+    });
+
+    await ifWe(sir, 'validate native and foreign challenge pool IDs', async () => {
+        // Happy path native pools
+        const resManage = validateChallengePoolIdSchema('manage');
+        iReckon(sir, resManage.valid).isGonnaBeTrue();
+        iReckon(sir, resManage.isForeign).isGonnaBeFalse();
+
+        const resDefault = validateChallengePoolIdSchema('default');
+        iReckon(sir, resDefault.valid).isGonnaBeTrue();
+        iReckon(sir, resDefault.isForeign).isGonnaBeFalse();
+
+        // Happy path custodial foreign pool
+        const resForeign = validateChallengePoolIdSchema('custodian-manage-google');
+        iReckon(sir, resForeign.valid).isGonnaBeTrue();
+        iReckon(sir, resForeign.isForeign).isGonnaBeTrue();
+        iReckon(sir, resForeign.who).willEqual('custodian');
+        iReckon(sir, resForeign.what).willEqual('manage');
+        iReckon(sir, resForeign.providerId).willEqual('google');
+
+        // Sad paths: invalid who/what/providerId
+        iReckon(sir, validateChallengePoolIdSchema('user-manage-google').valid).isGonnaBeFalse(); // who must be 'custodian'
+        iReckon(sir, validateChallengePoolIdSchema('custodian-invalidverb-google').valid).isGonnaBeFalse(); // invalid verb
+        iReckon(sir, validateChallengePoolIdSchema('custodian-manage-Google').valid).isGonnaBeFalse(); // non-flatcase providerId
+    });
+});