@ibgib/node-gib 0.0.10 → 0.0.14

package/src/serve-gib/bootstrap-helper.mts

@@ -0,0 +1,141 @@
+import { join } from 'node:path';
+
+import { clone, getUUID, } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getGib, getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import {
+    MetaspaceFactory, MetaspaceService, ZeroSpaceFactoryFunction,
+    LocalSpaceFactoryFunction, DtoToSpaceFunction
+} from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { NodeIndexedFilesystemSpace_V1 } from '../witness/space/node-filesystem-space/node-indexed-filesystem-space/node-indexed-filesystem-space-v1.mjs';
+import {
+    NodeFilesystemSpaceData_V1, DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1,
+} from '../witness/space/node-filesystem-space/node-filesystem-space-types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from './server-constants.mjs';
+import { NodeIndexedFilesystemSpaceData_V1, NodeIndexedFilesystemSpaceRel8ns_V1 } from '../witness/space/node-filesystem-space/node-indexed-filesystem-space/node-indexed-filesystem-space-types.mjs';
+import { Metaspace_Nodeindexedspace } from './metaspace-nodeindexedspace/metaspace-nodeindexedspace.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Deterministically calculates the physical filesystem path for a domain
+ * based on its keystone's tjpGib.
+ *
+ * @param tjpGib The TJP hash of the keystone defining the domain.
+ * @param baseDataDir The root directory for all ibgib spaces on the server.
+ * @returns The absolute path to the domain's isolated root.
+ */
+export function getDomainRootPath(tjpGib: string, baseDataDir: string): string {
+    // We use the first 2 characters as subfolders to balance the OS filesystem entries.
+    // e.g. /data/spaces/ab/c1/defg...
+    const sub1 = tjpGib.slice(0, 2);
+    const sub2 = tjpGib.slice(2, 4);
+    const remaining = tjpGib;
+
+    return join(baseDataDir, 'domains', sub1, sub2, remaining);
+}
+
+/**
+ * Creates a MetaspaceFactory using the "Factory Closure Pattern" to isolate
+ * all space operations within the given domainRootPath.
+ *
+ * @param domainRootPath The physical root directory for this domain.
+ * @returns A MetaspaceFactory pre-configured for this domain.
+ */
+export function getDomainFactory(domainRootPath: string): MetaspaceFactory {
+    const lc = `[${getDomainFactory.name}]`;
+
+    const fnZeroSpaceFactory: ZeroSpaceFactoryFunction = () => {
+        const zeroSpaceData: NodeIndexedFilesystemSpaceData_V1 = {
+            ...clone(DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1),
+            classname: NodeIndexedFilesystemSpace_V1.name,
+            baseDir: domainRootPath,
+        };
+
+        const zeroSpace = new NodeIndexedFilesystemSpace_V1(zeroSpaceData);
+        zeroSpace.gib = 'gib'; // Primitive zero space
+        return zeroSpace;
+    };
+
+    const fnDefaultLocalSpaceFactory: LocalSpaceFactoryFunction = async (opts) => {
+        // Ensure we don't prompt for a name during server bootstrap
+        // opts.spaceName ||= `default_${pickRandom_Letters({ count: 5 })}`;
+        opts.spaceName ||= `default`;
+
+        const spaceData: NodeFilesystemSpaceData_V1 = {
+            ...clone(DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1),
+            classname: NodeIndexedFilesystemSpace_V1.name,
+            uuid: await getUUID(),
+            baseDir: domainRootPath,
+            name: opts.spaceName,
+            spaceSubPath: opts.spaceName,
+            baseSubPath: 'ibgib',
+            binSubPath: 'bin',
+            dnaSubPath: 'dna',
+            ibgibsSubPath: 'ibgibs',
+            metaSubPath: 'meta',
+            isTjp: true,
+        };
+        if (logalot) { console.log(`${lc}[${fnDefaultLocalSpaceFactory.name}] spaceData.classname: ${spaceData.classname} (I: b60da661e9282e1253101e08765eb226)`); }
+
+        const space = new NodeIndexedFilesystemSpace_V1(spaceData);
+        space.gib = await getGib({ ibGib: space as any, hasTjp: true });
+
+        return space;
+    };
+
+    const fnDtoToSpace: DtoToSpaceFunction = async (spaceDto: IbGib_V1) => {
+        if (!spaceDto) { throw new Error(`spaceDto required (E: 30ede52f9c974591dac980a810510e26)`); }
+        if (!spaceDto.data) { throw new Error(`spaceDto.data required (E: 867b08a9c998e95028396f283d1d4826)`); }
+        if (!spaceDto.data.classname) { throw new Error(`spaceDto.data.classname required (E: 95a68813e64e68e6c84296d8dbaeb826)`); }
+        if (spaceDto.data.classname !== NodeIndexedFilesystemSpace_V1.name) {
+            throw new Error(`spaceDto.data.classname (${spaceDto.data.classname}) expeced to be ${NodeIndexedFilesystemSpace_V1.name} (E: 68aaa875ff22b92f57a0a3189da4b826)`);
+        }
+
+        const space = await NodeIndexedFilesystemSpace_V1.createFromDto(
+            spaceDto as IbGib_V1<NodeIndexedFilesystemSpaceData_V1, NodeIndexedFilesystemSpaceRel8ns_V1>
+        );
+        return space;
+    };
+
+
+    return {
+        fnZeroSpaceFactory,
+        fnDefaultLocalSpaceFactory,
+        fnDtoToSpace,
+    };
+}
+
+/**
+ * Orchestrates the bootstrapping of a domain-isolated metaspace.
+ *
+ * @param keystoneAddr The full address of the keystone defining the domain.
+ * @param baseDataDir The server's root data directory.
+ * @returns An initialized MetaspaceService scoped to the domain.
+ */
+export async function bootstrapDomainMetaspace(
+    keystoneAddr: string,
+    baseDataDir: string
+): Promise<MetaspaceService> {
+    const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: keystoneAddr });
+    const domainGib = tjpGib || punctiliarHash;
+    if (!domainGib) {
+        throw new Error(`Could not extract tjpGib from keystone address: ${keystoneAddr}`);
+    }
+
+    const domainRootPath = getDomainRootPath(domainGib, baseDataDir);
+    const factory = getDomainFactory(domainRootPath);
+
+    const metaspace = new Metaspace_Nodeindexedspace(/*cacheSvc*/ undefined);
+
+    await metaspace.initialize({
+        metaspaceFactory: factory,
+        // For server-side, these prompts should probably be non-interactive or log errors.
+        getFnAlert: () => async (arg) => console.log(`[ALERT] ${arg.title}: ${arg.msg}`),
+        getFnPrompt: () => async (arg) => { throw new Error(`Interactive prompt (${arg.title}) not supported in server bootstrap.`); },
+        getFnPromptPassword: () => async (title) => { throw new Error(`Password prompt (${title}) not supported in server bootstrap.`); },
+    });
+
+    return metaspace;
+}

package/src/serve-gib/bootstrap-helper.respec.mts

@@ -0,0 +1,100 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+
+import { respecfully, iReckon, ifWe } 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 './server-constants.mjs';
+import { getDomainRootPath, bootstrapDomainMetaspace } from './bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+
+/**
+ * Minimal mock to satisfy KeystoneService requirements during genesis.
+ */
+class MockMetaspace {
+    async getLocalUserSpace() { return new MockSpace(); }
+    async put() { }
+    async registerNewIbGib() { }
+}
+class MockSpace {
+    async witness() { return { data: { success: true } }; }
+}
+
+await respecfully(sir, 'bootstrap-helper', async () => {
+    const lc = `[bootstrap-helper.respec.mts][bootstrap-helper]`;
+    const testDataDir = './test-data';
+    console.log(`${lc} testDataDir: ${testDataDir} (I: c9f39853a57a5af97ab8ff7882c49826)`);
+
+    // Clean and recreate test-data directory
+    if (existsSync(testDataDir)) {
+        try { rmSync(testDataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* ignore */ }
+    }
+    mkdirSync(testDataDir, { recursive: true });
+
+    await ifWe(sir, 'calculate balanced domain root paths', async () => {
+        const tjpGib = 'abcde1234567890';
+        const root = getDomainRootPath(tjpGib, testDataDir);
+
+        // Should be: testDataDir/domains/ab/cd/abcde1234567890
+        iReckon(sir, root).includes(join('domains', 'ab', 'cd', tjpGib));
+    });
+
+    await ifWe(sir, 'bootstrap a domain metaspace and create the directory', async () => {
+        const keystoneAddr = 'keystone_alice^abcde1234567890';
+        const metaspace = await bootstrapDomainMetaspace(keystoneAddr, testDataDir);
+
+        iReckon(sir, metaspace).isGonnaBe(metaspace);
+        iReckon(sir, metaspace.initialized).isGonnaBe(true);
+
+        const expectedPath = getDomainRootPath('abcde1234567890', testDataDir);
+        iReckon(sir, existsSync(expectedPath)).isGonnaBe(true);
+
+        // The ibgib framework uses a specific subdirectory structure for the bootstrap
+        const bootstrapFile = join(expectedPath, 'ibgib', '000_zerospace', 'gib', 'bootstrap.json');
+        iReckon(sir, existsSync(bootstrapFile)).isGonnaBe(true);
+
+        // Also check that the default space was created
+        const defaultSpaceDir = join(expectedPath, 'ibgib', 'default');
+        iReckon(sir, existsSync(defaultSpaceDir)).isGonnaBe(true);
+    });
+
+    await ifWe(sir, 'integrate with KeystoneService and bootstrap 5 unique domains', async () => {
+        const keystoneService = new KeystoneService_V1();
+        const mockMetaspace = new MockMetaspace() as any;
+        const mockSpace = new MockSpace() as any;
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+
+        const identities = ['Alice', 'Bob', 'Charlie', 'Dave', 'Eve'];
+
+        for (const name of identities) {
+            // 1. Generate an actual genesis keystone for this identity
+            const keystone = await keystoneService.genesis({
+                masterSecret: `SecretFor_${name}`,
+                configs: [config],
+                metaspace: mockMetaspace,
+                space: mockSpace,
+            });
+            const addr = getIbGibAddr({ ibGib: keystone });
+            const tjpGib = keystone.gib!;
+
+            if (logalot) { console.log(`[test] Bootstrapping domain for ${name}: ${addr} (I: 7ba45828f2719ca578a1f078ff16e126)`); }
+
+            // 2. Drive the bootstrap logic
+            const metaspace = await bootstrapDomainMetaspace(addr, testDataDir);
+            iReckon(sir, metaspace.initialized).isGonnaBe(true);
+
+            // 3. Verify the unique path
+            const expectedPath = getDomainRootPath(tjpGib, testDataDir);
+            iReckon(sir, existsSync(expectedPath)).isGonnaBe(true);
+
+            const bootstrapFile = join(expectedPath, 'ibgib', '000_zerospace', 'gib', 'bootstrap.json');
+            iReckon(sir, existsSync(bootstrapFile)).isGonnaBe(true);
+        }
+    });
+});

package/src/serve-gib/constants.mts

@@ -0,0 +1 @@
+export { GLOBAL_LOG_A_LOT } from '../constants.mjs';

package/src/serve-gib/handlers/api/debug/ws-echo.handler.mts

@@ -0,0 +1,105 @@
+/**
+ * @module handlers/api/debug/ws-echo.handler
+ *
+ * Minimal WebSocket echo handler for validating end-to-end WebSocket
+ * plumbing: Traefik passthrough → Node.js upgrade event → browser client.
+ *
+ * ## intent
+ *
+ * This is a diagnostic-only endpoint. The goal is to confirm that:
+ *   1. Traefik correctly forwards WS upgrade requests to the container
+ *   2. The Node.js `upgrade` event fires and we can accept the connect handshake
+ *   3. The browser client can open a wss:// connection and exchange frames
+ *
+ * Once WS sync is confirmed end-to-end, this handler can be removed or
+ * gated behind an env flag.
+ *
+ * ## endpoint
+ *
+ * `GET /api/debug/ws-echo` (with Upgrade: websocket header)
+ *
+ * On connect: server sends `{"status":"connected","msg":"ws-echo ready"}`
+ * On message: server echoes `{"echo":<original message>}`
+ * On close: server logs and cleans up
+ */
+
+import { IncomingMessage } from 'node:http';
+import { Socket } from 'node:net';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import {
+    encodeTextFrame, decodeTextFrame, encodeCloseFrame, performConnect,
+    WebSocketFrameDecoder
+} from '../../ws/ws-helper.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+const lc = `[WsEchoHandler]`;
+
+
+// ---------------------------------------------------------------------------
+// Public handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if this request is a WebSocket upgrade to the debug echo path.
+ * Call this from the server's `upgrade` event listener.
+ */
+export function canHandleWsUpgrade(req: IncomingMessage): boolean {
+    const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+    return API_PATH_REGEXES.DEBUG_WS_ECHO.test(pathname);
+}
+
+/**
+ * Accepts the WebSocket upgrade and sets up the echo loop.
+ *
+ * Client will receive a JSON `{status:"connected"}` on open, and
+ * `{echo:<msg>}` for every message it sends.
+ */
+export function handleWsEchoUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): void {
+    const lc_fn = `${lc}[handleWsEchoUpgrade]`;
+    try {
+        if (logalot) { console.log(`${lc_fn} starting...`); }
+
+        const ok = performConnect(req, socket);
+        if (!ok) { return; }
+
+        // Send the "connected" greeting
+        socket.write(encodeTextFrame(JSON.stringify({ status: 'connected', msg: 'ws-echo ready' })));
+
+        // Echo loop
+        const decoder = new WebSocketFrameDecoder();
+        socket.on('data', (data: Buffer) => {
+            try {
+                decoder.addChunk(data);
+                let frameText = decoder.nextFrame();
+                while (frameText !== null) {
+                    if (logalot) { console.log(`${lc_fn} echo: ${frameText}`); }
+                    socket.write(encodeTextFrame(JSON.stringify({ echo: frameText })));
+                    frameText = decoder.nextFrame();
+                }
+            } catch (error) {
+                console.error(`${lc_fn} error in data handler: ${extractErrorMsg(error)}`);
+                socket.write(encodeCloseFrame(1000));
+                socket.end();
+            }
+        });
+
+        socket.on('error', (error) => {
+            console.error(`${lc_fn} socket error: ${extractErrorMsg(error)}`);
+        });
+
+        socket.on('close', () => {
+            if (logalot) { console.log(`${lc_fn} socket closed.`); }
+        });
+
+    } catch (error) {
+        console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+        socket.destroy();
+    } finally {
+        if (logalot) { console.log(`${lc_fn} complete.`); }
+    }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * @module serve-gib/handlers/api/email/email-inbound
+ *
+ * Handler for POST /api/email/inbound
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { EmailReceiverAws } from '../../../../email/aws/email-receiver-aws.mjs';
+import { EmailReceiver } from '../../../../email/email-types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+
+export interface EmailInboundHandlerOptions {
+    receiver?: EmailReceiver;
+}
+
+/**
+ * POST /api/email/inbound
+ * Parses incoming email webhook payloads (e.g. AWS SES SNS/S3 webhook), evaluates spam verdicts,
+ * and yields normalized inbound email.
+ */
+export class EmailInboundHandler extends ServeGibHandlerBase {
+    protected override lc = `[${EmailInboundHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.EMAIL_INBOUND;
+
+    private receiver: EmailReceiver;
+
+    constructor(options: EmailInboundHandlerOptions = {}) {
+        super();
+        this.receiver = options.receiver || new EmailReceiverAws();
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty');
+            }
+
+            let payload: any;
+            try {
+                payload = JSON.parse(reqCtx.body);
+            } catch {
+                payload = reqCtx.body;
+            }
+
+            const inboundEmail = await this.receiver.parseInboundPayload(payload);
+
+            console.log(`${lc} Successfully processed inbound email msgId: ${inboundEmail.messageId}, folder: ${inboundEmail.folder} (I: 890123456789abcdef8a9b0c1d2e3f4a)`);
+
+            return this.ok({
+                success: true,
+                email: inboundEmail,
+            });
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} Inbound email handling failed: ${emsg} (E: 90123456789abcdef9a0b1c2d3e4f5a6)`);
+            return this.error(500, `Inbound email error: ${emsg}`);
+        }
+    }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * @module serve-gib/handlers/api/email/email-outbound
+ *
+ * Handler for POST /api/email/send
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { EmailSenderAws } from '../../../../email/aws/email-sender-aws.mjs';
+import { EmailSender, OutboundEmail } from '../../../../email/email-types.mjs';
+import { EmailSenderMock } from '../../../../email/mock/email-sender-mock.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+
+export interface EmailOutboundHandlerOptions {
+    sender?: EmailSender;
+}
+
+/**
+ * POST /api/email/send
+ * Validates request payload and dispatches outbound email via the active EmailSender driver.
+ */
+export class EmailOutboundHandler extends ServeGibHandlerBase {
+    protected override lc = `[${EmailOutboundHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.EMAIL_SEND;
+
+    private sender: EmailSender;
+
+    constructor(options: EmailOutboundHandlerOptions = {}) {
+        super();
+
+        if (options.sender) {
+            this.sender = options.sender;
+        } else {
+            const mode = process.env.EMAIL_MODE || 'mock';
+            if (mode === 'aws') {
+                this.sender = new EmailSenderAws({
+                    accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
+                    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+                    region: process.env.AWS_REGION || 'us-east-1',
+                });
+            } else {
+                this.sender = new EmailSenderMock();
+            }
+        }
+    }
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty');
+            }
+
+            let emailData: OutboundEmail;
+            try {
+                emailData = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON');
+            }
+
+            const sendResult = await this.sender.sendEmail(emailData);
+
+            if (sendResult.success) {
+                console.log(`${lc} Successfully dispatched outbound email msgId: ${sendResult.messageId} (I: 0123456789abcdef0a1b2c3d4e5f6a7b)`);
+                return this.ok(sendResult, sendResult.statusCode || 200);
+            } else {
+                console.error(`${lc} Failed to send email: ${sendResult.error} (E: 123456789abcdef1a2b3c4d5e6f7a8b9)`);
+                return this.error(sendResult.statusCode || 500, sendResult.error || 'Failed to send email');
+            }
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} Outbound email error: ${emsg} (E: 23456789abcdef2a3b4c5d6e7f8a9b0c)`);
+            return this.error(500, `Outbound email error: ${emsg}`);
+        }
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @module serve-gib/handlers/api/health
+ */
+
+import { ServeGibHandlerBase } from '../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../types.mjs';
+import { API_PATH_REGEXES } from '../../path-constants.mjs';
+
+/**
+ * GET /api/health
+ */
+export class HealthHandler extends ServeGibHandlerBase {
+    protected override method: ServeGibHttpMethod = 'ALL';
+    protected override regex = API_PATH_REGEXES.HEALTH;
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        if (reqCtx.method === 'GET') {
+            return this.ok({ status: 'ok', timestamp: new Date().toISOString() });
+        } else {
+            throw new Error(`info.method !== 'GET' in ${HealthHandler.name} (E: bfff3c547b5827ca7845277804057f26)`);
+        }
+    }
+}

package/src/serve-gib/handlers/api/health.respec.mts

@@ -0,0 +1,51 @@
+import { respecfully, iReckon, ifWe, ifWeMight } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { ServeGib_V1 } from '../../serve-gib-v1.mjs';
+import { HealthHandler } from './health.handler.mjs';
+import { ErrorHandler } from '../error-handler.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'Health Handler Integration', async () => {
+    const testDataDir = './test-data-health';
+    const port = 3002;
+
+    await ifWe(sir, 'get a 200 OK from /api/health', async () => {
+        // 1. Setup ServeGib_V1
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [new HealthHandler()],
+            errorHandler: new ErrorHandler()
+        });
+
+        // 2. Mock GET Request
+        const req: any = {
+            url: '/api/health',
+            method: 'GET',
+            headers: {},
+            on: (event: string, cb: any) => {
+                if (event === 'end') { cb(); }
+            }
+        };
+
+        let capturedStatus: number = 0;
+        let capturedBody: any = null;
+        const res: any = {
+            writeHead: (status: number) => {
+                capturedStatus = status;
+            },
+            end: (body: string) => {
+                capturedBody = JSON.parse(body);
+            },
+            statusCode: 0
+        };
+
+        // 3. Handle
+        await serveGib.handleRequest(req, res);
+
+        // 4. Verify
+        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(200);
+        iReckon(sir, capturedBody.status).asTo('captured body status').isGonnaBe('ok');
+        iReckon(sir, capturedBody.timestamp).asTo('captured body timestamp').isGonnaBe(capturedBody.timestamp);
+    });
+});

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

@@ -0,0 +1,49 @@
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+
+import { DomainInfo } from "../../../types.mjs";
+
+export interface IbGibParams {
+    domainInfo: DomainInfo;
+    ibGibIb: string;
+    ibGibGib: string;
+    ibGibAddr: IbGibAddr;
+}
+
+// #region IbGibGetQueryParams
+export const DEFAULT_QUERY_PARAMS_GET_IBGIB = {
+    /**
+     * If true, will get the latest ibgib.
+     */
+    getLatest: false, // Default to false for regular ibgibs
+    /**
+     * If true, will get the ibgib's entire dependency graph
+     */
+    getGraph: false, // Default to false for regular ibgibs
+    /**
+     * If true, returns only the resolved address (addr) rather than the full
+     * ibgib or graph body. Useful for a lightweight "tip check" before initiating
+     * a full sync: client compares `latestAddr` with its locally known addr.
+     *
+     * ## notes
+     *
+     * Typically combined with `getLatest: true` to ask "what is the server's
+     * current tip for this timeline?" without paying the cost of fetching the
+     * full ibgib body or graph.
+     *
+     * When `getLatest: false` and `addrOnly: true`, returns the addr as-is
+     * (i.e., confirms the given addr exists on the server).
+     */
+    addrOnly: false,
+};
+/**
+ * @see {@link DEFAULT_QUERY_PARAMS_GET_IBGIB} key/values for jsdocs
+ */
+export type IbGibGetQueryParams = Partial<typeof DEFAULT_QUERY_PARAMS_GET_IBGIB>;
+export type KNOWN_QUERY_PARAMS_IBGIB_GET = keyof IbGibGetQueryParams;
+export const KNOWN_QUERY_PARAMS_IBGIB_GET = Object.keys(DEFAULT_QUERY_PARAMS_GET_IBGIB) as KNOWN_QUERY_PARAMS_IBGIB_GET[];
+export function isKnownQueryParamsKey_IbGibGet(key: any): key is KNOWN_QUERY_PARAMS_IBGIB_GET {
+    return !!key && typeof key === 'string' ?
+        KNOWN_QUERY_PARAMS_IBGIB_GET.includes(key as any) :
+        false;
+}
+// #endregion IbGibGetQueryParams