@ibgib/node-gib 0.0.10 → 0.0.14

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

@@ -0,0 +1,198 @@
+/**
+ * @module serve-gib/handlers/api/keystone
+ */
+
+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 { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { validateKeystoneGraph } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
+import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { IbGibSpaceResultData, IbGibSpaceResultIbGib, IbGibSpaceResultRel8ns } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import {
+    DEFAULT_QUERY_PARAMS_GET_KEYSTONE, isKnownQueryParamsKey_KeystoneGet,
+    KeystoneGetQueryParams, KeystoneParams, KNOWN_QUERY_PARAMS_KEYSTONE_GET
+} from './keystone-handler-types.mjs';
+import { validateAndCoerceBooleanQueryParam } from '../../../serve-gib-helpers.mjs';
+
+export interface KeystoneGetResponseBody {
+    domainGraph: Record<string, KeystoneIbGib_V1>;
+}
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * GET /api/keystone/:domainAddr
+ * GET /api/keystone/:domainAddr&getLatest=true
+ */
+export class KeystoneGetHandler extends ServeGibHandlerWithMetaspaceBase<KeystoneParams, KeystoneGetQueryParams> {
+    protected override lc: string = `[${KeystoneGetHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_ADDR;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<KeystoneParams, KeystoneGetQueryParams>): Promise<KeystoneParams | 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: 02c868316604c7c26823380885b79c26)`); }
+
+            const domainIb = decodeURIComponent(match[1]);
+            const domainGib = decodeURIComponent(match[2]);
+            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
+            return {
+                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... (I: f619e8121988498cd8e8928986663826)`); }
+
+            const errors: string[] = [];
+
+            // strict checking
+            const queryParamsKeys = Object.keys(queryParams);
+            const invalidKeys: string[] = queryParamsKeys.filter(x => !isKnownQueryParamsKey_KeystoneGet(x));
+            if (invalidKeys.length > 0) {
+                throw new Error(`invalid query params keys: ${invalidKeys.join(', ')}. valid query params keys: ${KNOWN_QUERY_PARAMS_KEYSTONE_GET.join(', ')} (E: f9642823b568a1cfe89e0401567ac826)`);
+            }
+
+            // Enforce that EVERY key must have a validation function mapping
+            type ValidationFn = () => Promise<void>;
+            const ValidationFns: Record<KNOWN_QUERY_PARAMS_KEYSTONE_GET, ValidationFn> = {
+                getLatest: async () => {
+                    validateAndCoerceBooleanQueryParam(queryParams, 'getLatest', errors);
+                },
+                getGraph: async () => {
+                    validateAndCoerceBooleanQueryParam(queryParams, 'getGraph', 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<KeystoneParams, KeystoneGetQueryParams>): Promise<ResponseResult | undefined> {
+        const lc = `[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const { metaspace } = reqCtx;
+            if (!metaspace) { throw new Error(`(UNEXPECTED) reqCtx.metaspace falsy? (E: 871a396f7e824989981a1508d0d17826)`); }
+
+            const { domainInfo } = reqCtx.params as KeystoneParams;
+            if (!domainInfo) { throw new Error(`(UNEXPECTED) reqCtx.params.domainInfo falsy? at this point, we've passed canHandleRoute so this should be truthy (E: 5d3e96d9f8d8f65258d530af0e223826)`); }
+            const { addr: domainAddr } = domainInfo;
+
+            // if (!domainIb || !domainGib) { return this.error(400, 'Keystone address required'); }
+            // const addr = `${domainIb}^${domainGib}`;
+
+            if (logalot) { console.log(`${lc} domainAddr: ${domainAddr} (I: ea08786359e85481a89c77d84e8f0826)`); }
+
+            // there are two paths for this: getLatest or not (get exact given addr)
+            // this should be driven by queryParams
+
+            const queryParams = {
+                ...DEFAULT_QUERY_PARAMS_GET_KEYSTONE,
+                ...(reqCtx.queryParams ?? {}),
+            }
+
+            const { getLatest, getGraph } = queryParams;
+
+            if (!getLatest) { throw new Error(`"getLatest: false" not implemented yet. currently this always returns the graph. (E: befd28156438a0b538cf107872e89b26)`); }
+            if (!getGraph) { throw new Error(`"getGraph: false" not implemented yet. currently this always returns the graph. (E: 84c8a88fdb28e72d884addb8f43fc826)`); }
+
+            /**
+             * get the default local user space that corresponds to the current
+             * keystone domain (which is what the metaspace was initialized
+             * with).
+             */
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`(UNEXPECTED) space falsy? we couldn't get the default local userspace from the metaspace for the addr (${domainAddr}) (E: 934551f1845f94c8320a8a980025c526)`); }
+
+
+            // use this code later if we de
+            let domainAddr_latest: IbGibAddr = domainAddr;
+            if (getLatest) {
+                const latestAddr = await metaspace.getLatestAddr({ addr: domainAddr, space });
+                if (latestAddr) { domainAddr_latest = latestAddr; }
+            }
+
+
+            const domainGraph = await metaspace.getDependencyGraph({
+                ibGibAddr: domainAddr_latest,
+                /**
+                 * since domain is a keystone, "live" is not needed because the
+                 * entire graph is composed of stones with no timelines.
+                 */
+                live: false,
+                space,
+            });
+
+            let keystoneIbGib: KeystoneIbGib_V1 = domainGraph[domainAddr_latest] as KeystoneIbGib_V1;
+            if (!keystoneIbGib) {
+                const errorMsg_addrInfo = domainAddr_latest === domainAddr ?
+                    `domainAddr: ${domainAddr}` :
+                    `domainAddr: ${domainAddr}, domainAddr_latest: `
+                return this.error(404, `Keystone not found. ${errorMsg_addrInfo} (E: 0238c85f94889607088220a324db1826)`); /* <<<< returns early */
+            }
+
+            // go ahead and validate even though we just pulled this (should be
+            // valid or it shouldn't have been persisted)
+
+            const keystoneValidationErrors = await validateKeystoneGraph({
+                keystoneIbGib,
+                getLatest,
+                invalidIfMoreRecentKeystoneFoundInSpace: getLatest,
+                space,
+            });
+
+            if (keystoneValidationErrors.length > 0) {
+                const errorMsg_addrInfo = domainAddr_latest === domainAddr ?
+                    `domainAddr: ${domainAddr}` :
+                    `domainAddr: ${domainAddr}, domainAddr_latest: `
+
+                return this.error(404, `Keystone invalid for ${errorMsg_addrInfo}. validationErrors: ${keystoneValidationErrors.join('|')}`); /* <<<< returns early */
+            }
+
+            // valid keystone graph
+            const responseBody: KeystoneGetResponseBody = {
+                domainGraph: domainGraph as Record<string, KeystoneIbGib_V1>,
+            };
+            return this.ok(responseBody);
+
+        } catch (error) {
+            const emsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(emsg);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/serve-gib/handlers/api/keystone/keystone-get.respec.mts

@@ -0,0 +1,106 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync } from 'node:fs';
+
+import {
+    respecfully, iReckon, ifWe, ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const sir = `[${import.meta.url}]`;
+
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { createStandardPoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
+import { POOL_ID_DEFAULT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
+import { KeystonePostHandler } from './keystone-post.handler.mjs';
+import { KeystoneGetHandler } from './keystone-get.handler.mjs';
+import { ErrorHandler } from '../../error-handler.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+class MockMetaspace {
+    async getLocalUserSpace() { return new MockSpace(); }
+    async put() { }
+    async registerNewIbGib() { }
+}
+class MockSpace {
+    async witness() { return { data: { success: true } }; }
+}
+
+await respecfully(sir, 'Keystone GET Integration', async () => {
+    const testDataDir = './test-data-get';
+    const port = 3003;
+
+    // Clean test data
+    if (existsSync(testDataDir)) {
+        try { rmSync(testDataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* ignore */ }
+    }
+    mkdirSync(testDataDir, { recursive: true });
+
+    await ifWe(sir, 'retrieve a keystone chain via GET /api/keystone/:addr', async () => {
+        const keystoneService = new KeystoneService_V1();
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+
+        // 1. Setup ServeGib_V1 with both POST and GET handlers
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [
+                new KeystonePostHandler(),
+                new KeystoneGetHandler(),
+            ],
+            errorHandler: new ErrorHandler()
+        });
+
+        // 2. Generate and POST genesis
+        const genesis = await keystoneService.genesis({
+            masterSecret: 'AliceSecret',
+            configs: [config],
+            metaspace: new MockMetaspace() as any,
+            space: new MockSpace() as any,
+        });
+        const addr = getIbGibAddr({ ibGib: genesis });
+
+        const postReq: any = {
+            url: '/api/keystone',
+            method: 'POST',
+            headers: { 'ibgib-domain': addr, 'content-type': 'application/json' },
+            on: (event: string, cb: any) => {
+                if (event === 'data') { cb(Buffer.from(JSON.stringify({ ibGibs: [genesis] }))); }
+                if (event === 'end') { cb(); }
+            }
+        };
+        const postRes: any = {
+            writeHead: () => { },
+            end: () => { },
+        };
+        await serveGib.handleRequest(postReq, postRes);
+
+        // 3. Mock GET Request
+        const getReq: any = {
+            url: `/api/keystone/${encodeURIComponent(addr)}`,
+            method: 'GET',
+            headers: { 'ibgib-domain': addr },
+            on: (event: string, cb: any) => {
+                if (event === 'end') { cb(); }
+            }
+        };
+
+        let capturedStatus: number = 0;
+        let capturedBody: any = null;
+        const getRes: any = {
+            writeHead: (status: number) => { capturedStatus = status; },
+            end: (body: string) => { capturedBody = JSON.parse(body); },
+        };
+
+        // 4. Handle GET
+        await serveGib.handleRequest(getReq, getRes);
+
+        // 5. Verify
+        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(200);
+        iReckon(sir, capturedBody.domainGraph).asTo('captured body domainGraph').isGonnaBeTruthy();
+        const graphKeys = Object.keys(capturedBody.domainGraph || {});
+        iReckon(sir, graphKeys.length > 0).asTo('domainGraph has keys').isGonnaBe(true);
+    });
+});

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

@@ -0,0 +1,29 @@
+import { DomainInfo } from "../../../types.mjs";
+
+export interface KeystoneParams {
+    domainInfo: DomainInfo;
+}
+
+// #region KeystoneGetQueryParams
+export const DEFAULT_QUERY_PARAMS_GET_KEYSTONE = {
+    /**
+     * If true, will get the latest keystone frame.
+     */
+    getLatest: true,
+    /**
+     * If true, will get the keystone's entire dependency graph
+     */
+    getGraph: true,
+};
+/**
+ * @see {@link DEFAULT_QUERY_PARAMS_GET_KEYSTONE} key/values for jsdocs
+ */
+export type KeystoneGetQueryParams = Partial<typeof DEFAULT_QUERY_PARAMS_GET_KEYSTONE>;
+export type KNOWN_QUERY_PARAMS_KEYSTONE_GET = keyof KeystoneGetQueryParams;
+export const KNOWN_QUERY_PARAMS_KEYSTONE_GET = Object.keys(DEFAULT_QUERY_PARAMS_GET_KEYSTONE) as KNOWN_QUERY_PARAMS_KEYSTONE_GET[];
+export function isKnownQueryParamsKey_KeystoneGet(key: any): key is KNOWN_QUERY_PARAMS_KEYSTONE_GET {
+    return !!key && typeof key === 'string' ?
+        KNOWN_QUERY_PARAMS_KEYSTONE_GET.includes(key as any) :
+        false;
+}
+// #endregion KeystoneGetQueryParams

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

@@ -0,0 +1,95 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-lookup.handler
+ *
+ * POST /api/keystone/lookup
+ *
+ * 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 { 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';
+
+/**
+ * POST /api/keystone/lookup
+ */
+export class KeystoneLookupHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneLookupHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_LOOKUP;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, undefined>
+    ): 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));
+            let parsed: any;
+            try {
+                parsed = JSON.parse(reqCtx.body);
+            } catch {
+                console.error(`${lc} Rejecting request: body must be valid JSON.`);
+                return this.error(400, 'Request body must be valid JSON');
+            }
+
+            const identifier = (parsed.identifier || '').trim();
+            if (!identifier) {
+                console.error(`${lc} Rejecting lookup: identifier missing or empty.`);
+                return this.error(400, 'Identifier is required');
+            }
+
+            const indexService = new IdentityIndexService({ baseDir: path.join(reqCtx.dataDir, 'index') });
+            const record = await indexService.getEmailIndex({ email: identifier });
+
+            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.`);
+            }
+
+            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}`);
+                return this.error(500, `Internal server error loading domain space.`);
+            }
+
+            const latestAddr = await metaspace.getLatestAddr({ addr: tjpAddr, space }) ?? tjpAddr;
+            const resGet = await metaspace.get({ addr: latestAddr, space });
+            const primaryKeystone = resGet?.ibGibs?.[0];
+
+            if (!primaryKeystone) {
+                console.error(`${lc} Primary keystone ${latestAddr} indexed but not found in domain space.`);
+                return this.error(404, `Primary identity keystone not found in space.`);
+            }
+
+            console.log(`${lc} Found latest primary identity keystone for '${identifier}': ${latestAddr} (tjp: ${tjpAddr})`);
+            return this.ok({
+                success: true,
+                tjpAddr,
+                primaryKeystoneIbGib: primaryKeystone
+            });
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @module serve-gib/handlers/api/keystone
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { validateAndRegisterPostKeystones } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+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;
+
+/**
+ * POST /api/keystone
+ */
+export class KeystonePostHandler extends ServeGibHandlerWithMetaspaceBase<KeystoneParams, any> { // todo: keystone post query params if needed?
+    protected override lc: string = `[${KeystonePostHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<KeystoneParams, any>): Promise<KeystoneParams | undefined> {
+        let domainAddr = reqCtx.headers?.['ibgib-domain'] as string;
+        if (!domainAddr) {
+            let bodyJson: any;
+            try { bodyJson = JSON.parse(reqCtx.body); } catch { /* ignore */ }
+            if (bodyJson?.ibGibs?.[0]) {
+                domainAddr = getIbGibAddr({ ibGib: bodyJson.ibGibs[0] });
+            }
+        }
+        if (!domainAddr) { return undefined; }
+        return {
+            domainInfo: this.getDomainInfo({ domainAddr }),
+        };
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
+        return [];
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext<KeystoneParams, any>): Promise<ResponseResult | undefined> {
+        const lc = `[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 63bab8214834cb6e383e0fc364ee8826)`); }
+
+            const { metaspace } = reqCtx;
+            if (!metaspace) { throw new Error(`(UNEXPECTED) reqCtx.metaspace falsy? (E: 3d03027ea7f6f237980e511801255826)`); }
+
+            const { ibGibs } = JSON.parse(reqCtx.body) as { ibGibs: any[] };
+            if (!Array.isArray(ibGibs)) return this.error(400, 'ibGibs array required');
+
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`No local user space found`); }
+
+            // Delegate all intrinsic validation, keystone-specific checks, registration, and persistence to core-gib
+            await validateAndRegisterPostKeystones({
+                ibGibs,
+                metaspace,
+                space
+            });
+
+            return { status: 201, body: { success: true }, isJson: true };
+
+        } catch (error) {
+            const emsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(emsg);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

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

@@ -0,0 +1,130 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync, readdirSync } from 'node:fs';
+
+import {
+    respecfully, iReckon, ifWe, ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const sir = `[${import.meta.url}]`;
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { createStandardPoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
+import { POOL_ID_DEFAULT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
+import { KeystonePostHandler } from './keystone-post.handler.mjs';
+import { ErrorHandler } from '../../error-handler.mjs';
+import { getDomainRootPath } from '../../../bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+if (logalot) { console.log(`[test] keystone-post.respec.mts top-level entry`); }
+
+class MockMetaspace {
+    async getLocalUserSpace() { return new MockSpace(); }
+    async put() { }
+    async registerNewIbGib() { }
+}
+class MockSpace {
+    async witness() { return { data: { success: true } }; }
+}
+
+await respecfully(sir, 'Keystone POST Integration', async () => {
+    const testDataDir = './test-data-post';
+    const port = 3001;
+
+    // Clean test data
+    if (existsSync(testDataDir)) {
+        try { rmSync(testDataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* ignore */ }
+    }
+    mkdirSync(testDataDir, { recursive: true });
+
+    await ifWe(sir, 'bootstrap a new domain via POST /api/keystone', async () => {
+        const keystoneService = new KeystoneService_V1();
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+
+        // 1. Generate real genesis
+        const genesis = await keystoneService.genesis({
+            masterSecret: 'AliceSecret',
+            configs: [config],
+            metaspace: new MockMetaspace() as any,
+            space: new MockSpace() as any,
+        });
+        const addr = getIbGibAddr({ ibGib: genesis });
+
+        if (logalot) { console.log(`[test] Generated genesis: ${addr}`); }
+
+        // 2. Setup ServeGib_V1
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [new KeystonePostHandler()],
+            errorHandler: new ErrorHandler()
+        });
+
+        if (logalot) { console.log(`[test] ServeGib_V1 setup. Posting to /api/keystone...`); }
+
+        // 3. Mock POST Request
+        const req: any = {
+            url: '/api/keystone',
+            method: 'POST',
+            headers: {
+                'ibgib-domain': addr,
+                'content-type': 'application/json'
+            },
+            on: (event: string, cb: any) => {
+                if (event === 'data') {
+                    if (logalot) { console.log(`[test] sending data chunk...`); }
+                    cb(Buffer.from(JSON.stringify({ ibGibs: [genesis] })));
+                }
+                if (event === 'end') {
+                    if (logalot) { console.log(`[test] end of request.`); }
+                    cb();
+                }
+            }
+        };
+
+        let capturedStatus: number = 0;
+        let capturedBody: any = null;
+        const res: any = {
+            writeHead: (status: number) => {
+                if (logalot) { console.log(`[test] writeHead: ${status}`); }
+                capturedStatus = status;
+            },
+            end: (body: string) => {
+                if (logalot) { console.log(`[test] res.end called with body length: ${body?.length}`); }
+                capturedBody = JSON.parse(body);
+            },
+            statusCode: 0
+        };
+
+        // 4. Handle
+        if (logalot) { console.log(`[test] Calling handleRequest...`); }
+        await serveGib.handleRequest(req, res);
+        if (logalot) { console.log(`[test] handleRequest completed.`); }
+
+        // 5. Verify
+        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(201);
+        iReckon(sir, capturedBody.success).asTo(`Handler failed: ${capturedBody.message || 'no message'}`).isGonnaBe(true);
+
+        const domainPath = getDomainRootPath(genesis.gib!, testDataDir);
+        iReckon(sir, existsSync(domainPath)).asTo('domain path exists').isGonnaBe(true);
+
+        // Verify the ibgib actually exists in the new domain's storage
+        // With indexed storage, it's in a bucketed subpath: ibgib/default/ibgibs/B1/B2/
+        const bucket1 = genesis.gib!.substring(0, 3).toUpperCase();
+        const bucket2 = genesis.gib!.substring(3, 6).toUpperCase();
+        const bucketPath = join(domainPath, 'ibgib', 'default', 'ibgibs', bucket1, bucket2);
+
+        iReckon(sir, existsSync(bucketPath)).asTo(`Bucket path does not exist: ${bucketPath}`).isGonnaBe(true);
+
+        // We don't know the random filename, but we know it's a .json file in that bucket
+        try {
+            const files = readdirSync(bucketPath).filter(f => f.endsWith('.json'));
+            iReckon(sir, files.length > 0).asTo(`No .json files found in bucket: ${bucketPath}`).isGonnaBe(true);
+        } catch (error) {
+            iReckon(sir, true).asTo(`error trying to readdir ${bucketPath}: ${extractErrorMsg(error)}`).isGonnaBe(true);
+        }
+    });
+});