@ibgib/node-gib 0.0.9 → 0.0.13

package/dist/serve-gib/identity-index/identity-index-helpers.mjs

@@ -0,0 +1,69 @@
+import * as path from 'path';
+import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { KEYSTONE_EMAIL_REGEXP } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { DEFAULT_EMAIL_HASHES_SUBDIR, DEFAULT_IDENTITY_INDEX_SALT } from './identity-index-constants.mjs';
+/**
+ * Validates an email address against length constraints and KEYSTONE_EMAIL_REGEXP.
+ * Returns an array of error message strings (empty `[]` if valid).
+ */
+export function validateEmail({ email }) {
+    const errors = [];
+    if (!email || typeof email !== 'string') {
+        errors.push('Email must be a non-empty string.');
+        return errors;
+    }
+    const trimmed = email.trim();
+    if (trimmed.length < 3) {
+        errors.push('Email length must be at least 3 characters.');
+    }
+    if (trimmed.length > 254) {
+        errors.push('Email length must not exceed 254 characters.');
+    }
+    if (!KEYSTONE_EMAIL_REGEXP.test(trimmed)) {
+        errors.push(`Email '${trimmed}' is not a valid email format.`);
+    }
+    return errors;
+}
+/**
+ * Normalizes an email string (lowercased and trimmed).
+ */
+export function normalizeEmail(email) {
+    if (!email || typeof email !== 'string') {
+        return '';
+    }
+    return email.trim().toLowerCase();
+}
+/**
+ * Computes SHA256 privacy hash of an email string:
+ * `SHA256(normalizeEmail(email) + salt)` using `hash` from `@ibgib/helper-gib`.
+ */
+export async function getIdentityEmailHash({ email, salt = process.env.IDENTITY_INDEX_SALT || DEFAULT_IDENTITY_INDEX_SALT, }) {
+    const validationErrors = validateEmail({ email });
+    if (validationErrors.length > 0) {
+        throw new Error(`Invalid email address: ${validationErrors.join(', ')} (E: 69a68886b1dab2f4f85c3e884031d326)`);
+    }
+    const normalized = normalizeEmail(email);
+    const emailHash = await hash({ s: `${normalized}${salt}` });
+    return emailHash;
+}
+/**
+ * Returns the sharded directory path and truncated filename for an email hash.
+ *
+ * Full Hash (e.g. 64 chars): `abcdef12345...`
+ * Subfolders: `ab/cd/ef`
+ * Truncated filename: `12345....json` (strips the leading 6 characters that form the 3 subfolder pairs).
+ */
+export function getShardedIndexPath({ baseDir, emailHash, }) {
+    if (!emailHash || emailHash.length < 7) {
+        throw new Error(`Invalid email hash string '${emailHash}'. Must be at least 7 characters. (E: 7aeb7885a7f1b4576899db283516d826)`);
+    }
+    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`;
+    const folderPath = path.join(baseDir, DEFAULT_EMAIL_HASHES_SUBDIR, f1, f2, f3);
+    const filePath = path.join(folderPath, filename);
+    return { folderPath, filePath, filename };
+}
+//# sourceMappingURL=identity-index-helpers.mjs.map

package/dist/serve-gib/identity-index/identity-index-helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-helpers.mjs","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-helpers.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,iDAAiD,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAC7F,OAAO,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAE1G;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAE,KAAK,EAAkB;IACnD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,UAAU,OAAO,gCAAgC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IACxC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;IACvD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,EACvC,KAAK,EACL,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,2BAA2B,GAIxE;IACG,MAAM,gBAAgB,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,0BAA0B,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACnH,CAAC;IACD,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,EAAE,GAAG,UAAU,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;IAC5D,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAChC,OAAO,EACP,SAAS,GAIZ;IACG,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,yEAAyE,CAAC,CAAC;IACtI,CAAC;IAED,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjC,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,aAAa,OAAO,CAAC;IAEzC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,2BAA2B,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAEjD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC"}

package/dist/serve-gib/identity-index/identity-index-service.d.mts

@@ -0,0 +1,41 @@
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.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 declare class IdentityIndexService {
+    private baseDir;
+    private salt;
+    constructor({ baseDir, salt }: IdentityIndexServiceOptions);
+    /**
+     * 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.
+     */
+    registerEmailIndex({ email, tjpAddr, }: {
+        email: string;
+        tjpAddr: IbGibAddr;
+    }): Promise<RegisterEmailIndexResult>;
+    /**
+     * Retrieves the registered `IdentityIndexRecord` for an email address.
+     * Returns `undefined` if email is not indexed.
+     */
+    getEmailIndex({ email, }: {
+        email: string;
+    }): Promise<IdentityIndexRecord | undefined>;
+    /**
+     * Retrieves the registered `IdentityIndexRecord` directly by `emailHash`.
+     * Returns `undefined` if hash file does not exist.
+     */
+    getEmailIndexByHash({ emailHash, }: {
+        emailHash: string;
+    }): Promise<IdentityIndexRecord | undefined>;
+    /**
+     * Unindexes an email address (deletes the index JSON file).
+     * Returns `true` if unindexed, or `false` if file did not exist.
+     */
+    unregisterEmailIndex({ email, }: {
+        email: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=identity-index-service.d.mts.map

package/dist/serve-gib/identity-index/identity-index-service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-service.d.mts","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-service.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAGzD,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAExH;;GAEG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAS;IAErB,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,2BAA2B,EAIzD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,EACrB,KAAK,EACL,OAAO,GACV,EAAE;QACC,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,SAAS,CAAC;KACtB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAoBpC;IAED;;;OAGG;IACG,aAAa,CAAC,EAChB,KAAK,GACR,EAAE;QACC,KAAK,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAG3C;IAED;;;OAGG;IACG,mBAAmB,CAAC,EACtB,SAAS,GACZ,EAAE;QACC,SAAS,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAY3C;IAED;;;OAGG;IACG,oBAAoB,CAAC,EACvB,KAAK,GACR,EAAE;QACC,KAAK,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnB;CACJ"}

package/dist/serve-gib/identity-index/identity-index-service.mjs

@@ -0,0 +1,86 @@
+import * as fs from 'fs/promises';
+import { DEFAULT_IDENTITY_INDEX_SALT } from './identity-index-constants.mjs';
+import { getIdentityEmailHash, getShardedIndexPath } from './identity-index-helpers.mjs';
+/**
+ * Service managing atomic, sharded identity index files for backwards email -> primary identity tjpAddr lookups.
+ */
+export class IdentityIndexService {
+    baseDir;
+    salt;
+    constructor({ baseDir, salt }) {
+        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, }) {
+        const emailHash = await getIdentityEmailHash({ email, salt: this.salt });
+        const { folderPath, filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+        await fs.mkdir(folderPath, { recursive: true });
+        const record = {
+            tjpAddr,
+            createdAt: Date.now(),
+        };
+        try {
+            await fs.writeFile(filePath, JSON.stringify(record, null, 2), { flag: 'wx' });
+            return { emailHash, filePath, record };
+        }
+        catch (error) {
+            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, }) {
+        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, }) {
+        const { filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+        try {
+            const content = await fs.readFile(filePath, 'utf8');
+            const record = JSON.parse(content);
+            return record;
+        }
+        catch (error) {
+            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, }) {
+        const emailHash = await getIdentityEmailHash({ email, salt: this.salt });
+        const { filePath } = getShardedIndexPath({ baseDir: this.baseDir, emailHash });
+        try {
+            await fs.unlink(filePath);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=identity-index-service.mjs.map

package/dist/serve-gib/identity-index/identity-index-service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-service.mjs","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-service.mts"],"names":[],"mappings":"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"}

package/dist/serve-gib/identity-index/identity-index-service.respec.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=identity-index-service.respec.d.mts.map

package/dist/serve-gib/identity-index/identity-index-service.respec.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-service.respec.d.mts","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-service.respec.mts"],"names":[],"mappings":""}

package/dist/serve-gib/identity-index/identity-index-service.respec.mjs

@@ -0,0 +1,109 @@
+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) {
+            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();
+});
+//# sourceMappingURL=identity-index-service.respec.mjs.map

package/dist/serve-gib/identity-index/identity-index-service.respec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-service.respec.mjs","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-service.respec.mts"],"names":[],"mappings":"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"}

package/dist/serve-gib/identity-index/identity-index-types.d.mts

@@ -0,0 +1,31 @@
+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;
+}
+//# sourceMappingURL=identity-index-types.d.mts.map

package/dist/serve-gib/identity-index/identity-index-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-types.d.mts","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-types.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,6CAA6C;IAC7C,OAAO,EAAE,SAAS,CAAC;IACnB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,mBAAmB,CAAC;CAC/B"}

package/dist/serve-gib/identity-index/identity-index-types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=identity-index-types.mjs.map

package/dist/serve-gib/identity-index/identity-index-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-index-types.mjs","sourceRoot":"","sources":["../../../src/serve-gib/identity-index/identity-index-types.mts"],"names":[],"mappings":""}

package/dist/serve-gib/index.d.mts

@@ -0,0 +1,50 @@
+/**
+ * @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';
+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';
+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 declare function getStandardServeGibHandlers(opts?: StandardHandlersOptions): ServeGibHandler<any, any>[];
+//# sourceMappingURL=index.d.mts.map

package/dist/serve-gib/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/serve-gib/index.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,6CAA6C,CAAC;AAG5D,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,qDAAqD,CAAC;AACpE,cAAc,mDAAmD,CAAC;AAClE,cAAc,kDAAkD,CAAC;AACjE,cAAc,qDAAqD,CAAC;AACpE,cAAc,0DAA0D,CAAC;AACzE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,iDAAiD,CAAC;AAChE,cAAc,0CAA0C,CAAC;AACzD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgB9C,MAAM,WAAW,uBAAuB;IACpC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,uBAA4B,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAsB3G"}

package/dist/serve-gib/index.mjs

@@ -0,0 +1,80 @@
+/**
+ * @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 { 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';
+/**
+ * Returns the standard pipeline array of ibgib HTTP request handlers for serve-gib.
+ */
+export function getStandardServeGibHandlers(opts = {}) {
+    const handlers = [
+        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;
+}
+//# sourceMappingURL=index.mjs.map

package/dist/serve-gib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/serve-gib/index.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,6CAA6C,CAAC;AAE5D,WAAW;AACX,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,qDAAqD,CAAC;AACpE,cAAc,mDAAmD,CAAC;AAClE,cAAc,kDAAkD,CAAC;AACjE,cAAc,qDAAqD,CAAC;AACpE,cAAc,0DAA0D,CAAC;AACzE,cAAc,gDAAgD,CAAC;AAC/D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,iDAAiD,CAAC;AAChE,cAAc,0CAA0C,CAAC;AACzD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAGvD,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAC9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,qDAAqD,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qDAAqD,CAAC;AAC5F,OAAO,EAAE,yBAAyB,EAAE,MAAM,0DAA0D,CAAC;AACrG,OAAO,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,+CAA+C,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AACvF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAOlE;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAI,GAA4B,EAAE;IAC1E,MAAM,QAAQ,GAAgC;QAC1C,IAAI,aAAa,EAAE;QACnB,IAAI,YAAY,EAAE;QAClB,IAAI,sBAAsB,EAAE;QAC5B,IAAI,qBAAqB,EAAE;QAC3B,IAAI,mBAAmB,EAAE;QACzB,IAAI,kBAAkB,EAAE;QACxB,IAAI,qBAAqB,EAAE;QAC3B,IAAI,yBAAyB,EAAE;QAC/B,IAAI,cAAc,EAAE;QACpB,IAAI,eAAe,EAAE;QACrB,IAAI,gBAAgB,EAAE;QACtB,IAAI,mBAAmB,EAAE;QACzB,IAAI,oBAAoB,EAAE;KAC7B,CAAC;IAEF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,QAAQ,CAAC;AACpB,CAAC"}

package/dist/serve-gib/keystone-schema-helpers.d.mts

@@ -0,0 +1,50 @@
+/**
+ * Strict flatcase regex for individual tokens (username, role, deviceId, providerId).
+ * Lowercase alphanumeric characters only [a-z0-9], no hyphens or punctuation.
+ */
+export declare const FLATCASE_TOKEN_REGEXP: RegExp;
+/**
+ * Validates if a string token is strict flatcase ([a-z0-9]+).
+ */
+export declare function validateFlatcaseToken(token: string): boolean;
+/**
+ * Sanitizes an input string to strict flatcase ([a-z0-9]).
+ */
+export declare function sanitizeToken(input: string): string;
+/**
+ * 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 declare function validateKeystoneNameSchema(name: string): KeystoneNameSchemaResult;
+/**
+ * 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 declare function validateChallengePoolIdSchema(poolId: string): ChallengePoolIdSchemaResult;
+//# sourceMappingURL=keystone-schema-helpers.d.mts.map

package/dist/serve-gib/keystone-schema-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-schema-helpers.d.mts","sourceRoot":"","sources":["../../src/serve-gib/keystone-schema-helpers.mts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAEnD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,CA8BjF;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,2BAA2B,CA6BzF"}