@ibgib/space-gib 0.0.1

package/src/server/path-helper.mts

@@ -0,0 +1,101 @@
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { validateIbGibAddr } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from './server-constants.mjs';
+import { FORBIDDEN_PATTERNS, MAX_PATH_LENGTH, VALID_STATIC_PATH_REGEX } from './path-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * little helper function just to DRY out code.
+ */
+export function runtimeErrorValidationStrings(lc: string, error: any): string[] {
+    const emsg = `${lc} ${extractErrorMsg(error)}`;
+    console.error(emsg);
+    return [`runtime error: ${emsg}`];
+}
+
+/**
+ * Validates that a path is safe from common attacks and under max length.
+ */
+export function validateRawPath(rawPath: string): string[] {
+    const lc = `[${validateRawPath.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 80bd6f63e6c83b8e943b90383e044826)`); }
+
+        const errors: string[] = [];
+
+        if (!rawPath || rawPath.length > MAX_PATH_LENGTH) {
+            errors.push(`path too long. MAX_PATH_LENGTH: ${MAX_PATH_LENGTH}, incoming path length: ${rawPath.length}`);
+        }
+
+        for (const pattern of FORBIDDEN_PATTERNS) {
+            if (pattern.test(rawPath)) {
+                errors.push(`invalid path. contains forbidden pattern.source: ${pattern.source} (E: 56a228fb9473a086b83d0088b5af1826)`);
+            }
+        }
+
+        return errors;
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * simple boolean wrapper for {@link validateRawPath}
+ */
+export function isSafePath(path: string): boolean {
+    const errors = validateRawPath(path);
+    return errors.length === 0;
+}
+
+export function validateStaticPath(path: string): string[] {
+    const lc = `[${validateStaticPath.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 4f9cf8ffd528c7dd88324529528eeb26)`); }
+
+        const errors: string[] = [];
+
+        if (!VALID_STATIC_PATH_REGEX.test(path)) {
+            errors.push(`static path fails to match VALID_STATIC_PATH_REGEX of ${VALID_STATIC_PATH_REGEX} (E: dfdf38a0439d4d09186e6fa81ab66826) `);
+        }
+
+        return errors;
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Validates a static file path.
+ */
+export function isValidStaticPath(path: string): boolean {
+    if (!isSafePath(path)) { return false; }
+    const errors = validateStaticPath(path);
+    return errors.length === 0;
+}
+
+/**
+ * Decodes and validates a single ibGib address segment from a URL path.
+ * Uses the library's internal validateIbGibAddr for deep checking.
+ */
+export function validateAddressSegment(encodedAddr: string): string[] {
+    const lc = `[${validateAddressSegment.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 1bb9ff7e1aefb77b670b2519658cc126)`); }
+        if (!encodedAddr) {
+            throw new Error(`(UNEXPECTED) falsy encodedAddr? We're expecting to have already guaranteed there are no double-slashes (i.e. no empty segments) (E: 7be7668e7b8c9fbbdf56f0fe19f92e26)`);
+        }
+        const addr = decodeURIComponent(encodedAddr);
+        const errors = validateIbGibAddr({ addr });
+        return errors ?? [];
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/server/path-helper.respec.mts

@@ -0,0 +1,94 @@
+import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { isSafePath, isValidStaticPath, API_PATHS, getPathParams, MAX_PATH_LENGTH, validateAddressSegment } from './path-helper.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'Path Helper Validation', async () => {
+
+    await respecfully(sir, 'isSafePath', async () => {
+        await ifWe(sir, 'valid simple paths', async () => {
+            iReckon(sir, isSafePath('/api/health')).isGonnaBeTrue();
+            iReckon(sir, isSafePath('/index.html')).isGonnaBeTrue();
+        });
+
+        await ifWe(sir, 'too long paths', async () => {
+            const longPath = '/'.repeat(MAX_PATH_LENGTH + 1);
+            iReckon(sir, isSafePath(longPath)).isGonnaBeFalse();
+        });
+
+        await ifWe(sir, 'directory traversal attempts', async () => {
+            iReckon(sir, isSafePath('/../etc/passwd')).isGonnaBeFalse();
+            iReckon(sir, isSafePath('/api/../../etc/passwd')).isGonnaBeFalse();
+        });
+
+        await ifWe(sir, 'null bytes', async () => {
+            iReckon(sir, isSafePath('/api/health\0')).isGonnaBeFalse();
+        });
+
+        await ifWe(sir, 'redundant slashes', async () => {
+            iReckon(sir, isSafePath('/api//health')).isGonnaBeFalse();
+        });
+
+        await ifWe(sir, 'dot-file access', async () => {
+            iReckon(sir, isSafePath('/.env')).isGonnaBeFalse();
+            iReckon(sir, isSafePath('/scripts/.hidden')).isGonnaBeFalse();
+            iReckon(sir, isSafePath('/.git/config')).isGonnaBeFalse();
+        });
+    });
+
+    await respecfully(sir, 'validateAddressSegment', async () => {
+        await ifWe(sir, 'valid encoded addresses', async () => {
+            const validGib = 'a'.repeat(64);
+            iReckon(sir, validateAddressSegment(`someib%5E${validGib}`)).isGonnaBeTrue();
+            // gib with dots (common in sha256.sha256)
+            const dotGib = `${validGib}.${validGib}`;
+            iReckon(sir, validateAddressSegment(`someib%5E${dotGib}`)).isGonnaBeTrue();
+        });
+
+        await ifWe(sir, 'invalid encoded addresses', async () => {
+            iReckon(sir, validateAddressSegment('no_delim')).isGonnaBeFalse();
+            iReckon(sir, validateAddressSegment('%5Estarts_with_delim')).isGonnaBeFalse();
+            iReckon(sir, validateAddressSegment('too%5Emany%5Edelims')).isGonnaBeFalse();
+            iReckon(sir, validateAddressSegment('too%5Emany..dots')).isGonnaBeFalse();
+            iReckon(sir, validateAddressSegment('invalid_chars_!%5Eabc')).isGonnaBeFalse();
+        });
+    });
+
+    await respecfully(sir, 'API_PATHS Regexes', async () => {
+        await ifWe(sir, 'HEALTH regex', async () => {
+            iReckon(sir, API_PATHS.HEALTH.test('/api/health')).isGonnaBeTrue();
+            iReckon(sir, API_PATHS.HEALTH.test('/api/health/')).isGonnaBeTrue();
+            iReckon(sir, API_PATHS.HEALTH.test('/api/health/more')).isGonnaBeFalse();
+        });
+
+        await ifWe(sir, 'IBGIB_ADDR regex', async () => {
+            // valid encoded addr: someib%5Esomegib
+            const addr = '/api/ibgib/someib%5Esomegib';
+            iReckon(sir, API_PATHS.IBGIB_ADDR.test(addr)).isGonnaBeTrue();
+            
+            const params = getPathParams(addr, API_PATHS.IBGIB_ADDR);
+            iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+        });
+
+        await ifWe(sir, 'IBGIB_GRAPH regex', async () => {
+            const path = '/api/ibgib/graph/someib%5Esomegib';
+            iReckon(sir, API_PATHS.IBGIB_GRAPH.test(path)).isGonnaBeTrue();
+            
+            const params = getPathParams(path, API_PATHS.IBGIB_GRAPH);
+            iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+        });
+
+        await ifWe(sir, 'KEYSTONE regex', async () => {
+            iReckon(sir, API_PATHS.KEYSTONE.test('/api/keystone')).isGonnaBeTrue();
+            iReckon(sir, API_PATHS.KEYSTONE.test('/api/keystone/')).isGonnaBeTrue();
+        });
+
+        await ifWe(sir, 'KEYSTONE_EVOLVE regex', async () => {
+            const path = '/api/keystone/evolve/someib%5Esomegib';
+            iReckon(sir, API_PATHS.KEYSTONE_EVOLVE.test(path)).isGonnaBeTrue();
+            
+            const params = getPathParams(path, API_PATHS.KEYSTONE_EVOLVE);
+            iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+        });
+    });
+});

package/src/server/serve-gib/CHANGELOG.md

@@ -0,0 +1,29 @@
+# serve-gib changelog
+
+_note: as you implement features/fixes/etc., please document them here under the "Working Version" section._
+
+## Working Version
+
+* impl: initial core infrastructure
+  * defined `RouteInfo`, `ResponseResult`, and `ServeGibHandler` foundational types.
+  * implemented `ServeGib_V1` with pipeline-based request processing.
+  * added robust `try..catch..finally` pattern with built-in access logging and timing.
+* impl: handler "pit of success" plumbing
+  * implemented `ServeGibHandlerBase` abstract class to reduce boilerplate.
+  * automated route matching via `canHandleRoute` and `regex` properties.
+  * implemented `handleRouteImpl` pattern to separate plumbing from business logic.
+  * added generic `TQueryParams` support with automated parsing via `parseQueryParams`.
+* feat: hierarchical handler organization
+  * established folder-based grouping mirroring URL paths (e.g., `handlers/api/ibgib/`).
+  * enforced "one handler per hard route" and "one handler per file" architectural guidelines.
+* feat: concrete core handlers
+  * `HealthHandler`: Simple liveness probe.
+  * `IbGibHandler`: Single ibGib address resolution.
+  * `IbGibGraphHandler`: Complex graph/BFS retrieval.
+  * `KeystoneHandler`: Genesis and evolution turn persistence.
+  * `StaticFileHandler`: High-performance asset serving with SPA history fallback.
+  * `ErrorHandler`: Standardized 404 and fatal error reporting.
+* docs: architectural guidance
+  * created `README.md` with detailed guidance on handler philosophy and plumbing usage.
+* test: validation suite
+  * implemented `serve-gib.respec.mts` verifying orchestrator pipeline and `RouteInfo` construction.

package/src/server/serve-gib/README.md

@@ -0,0 +1,34 @@
+# serve-gib Microframework
+
+A minimalist, high-observability HTTP microframework for ibgib servers.
+
+## Architecture & Guidance
+
+### 1. Handler Philosophy
+*   **One handler per "hard" route**: A handler should correspond to a unique URL path pattern, disregarding query parameters.
+*   **One regex per handler**: Concrete handlers should ideally define a single `regex` property for routing.
+*   **One handler per file**: Each route handler should live in its own file within the `handlers/` directory (e.g., `handlers/api/health.handler.mts`).
+  * The subfolders should match the hard route of the handler, e.g., `api/ibgib` route should be in the `handlers/api/ibgib` subfolder.
+
+### 2. The "Pit of Success" Plumbing
+The `ServeGibHandlerBase` class provides built-in plumbing to reduce boilerplate:
+*   **`handleRoute` (Plumbing)**: Automatically checks `canHandleRoute`, parses query parameters, and provides a top-level `try..catch` block for logging and error reporting.
+*   **`handleRouteImpl` (Implementation)**: This is where the core logic of the handler resides.
+*   **`canHandleRoute`**: Defaults to a regex match on `info.pathname`. Override this for more complex routing logic.
+
+### 3. Query Parameters
+Query parameters are handled via the `parseQueryParams` method in the base class.
+*   By default, it parses URL search params into a key-value object.
+*   Handlers can override this method to perform custom parsing or validation (e.g., parsing JSON strings from query params).
+*   The base class is generic: `ServeGibHandlerBase<TQueryParams = any>`.
+
+### 4. RouteInfo
+The `RouteInfo` object provides an enriched view of the incoming request:
+*   `decodedPathSegments`: Pre-split and decoded path parts.
+*   `protocol`, `method`, `body`: Basic HTTP info.
+*   `queryParams`: The result of the handler's `parseQueryParams` call.
+
+## Pipeline Order
+The `ServeGib_V1` executes handlers in the order they are provided in the `handlers` array. The first handler to return a non-undefined `ResponseResult` wins.
+*   **Tip**: Order specific routes (like `/api/ibgib/graph`) before more general ones (like `/api/ibgib`).
+*   **Fallback**: The `ErrorHandler` is used as a final catch-all for 404s and fatal errors.

package/src/server/serve-gib/constants.mts

@@ -0,0 +1 @@
+export const GLOBAL_LOG_A_LOT = false;

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

@@ -0,0 +1,104 @@
+/**
+ * @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 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, performHandshake
+} 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 = performHandshake(req, socket);
+        if (!ok) { return; }
+
+        // Send the "connected" greeting
+        socket.write(encodeTextFrame(JSON.stringify({ status: 'connected', msg: 'ws-echo ready' })));
+
+        // Echo loop
+        socket.on('data', (data: Buffer) => {
+            try {
+                const text = decodeTextFrame(data);
+                if (text === null) {
+                    // Close frame or unsupported opcode — send close and end
+                    socket.write(encodeCloseFrame(1000));
+                    socket.end();
+                    return;
+                }
+                if (logalot) { console.log(`${lc_fn} echo: ${text}`); }
+                socket.write(encodeTextFrame(JSON.stringify({ echo: text })));
+            } catch (error) {
+                console.error(`${lc_fn} error in data handler: ${extractErrorMsg(error)}`);
+                socket.destroy();
+            }
+        });
+
+        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/server/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/server/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/server/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

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

@@ -0,0 +1,176 @@
+/**
+ * @module serve-gib/handlers/api/ibgib
+ */
+
+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 { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { validateAddressSegment } from '../../../../path-helper.mjs';
+import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
+import {
+    DEFAULT_QUERY_PARAMS_GET_IBGIB, IbGibGetQueryParams, IbGibParams,
+    isKnownQueryParamsKey_IbGibGet, KNOWN_QUERY_PARAMS_IBGIB_GET
+} from './ibgib-handler-types.mjs';
+import { validateAndCoerceBooleanQueryParam } from '../../../serve-gib-helpers.mjs';
+
+export interface IbGibGraphResponseBody {
+    addr: string;
+    count: number;
+    graph: Record<string, IbGib_V1>;
+}
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * GET /api/ibgib/:domainAddr/:ibGibAddr
+ */
+export class IbGibHandler extends ServeGibHandlerWithMetaspaceBase<IbGibParams, IbGibGetQueryParams> {
+    protected override lc: string = `[${IbGibHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = API_PATH_REGEXES.IBGIB_ADDR;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<IbGibParams, IbGibGetQueryParams>): Promise<IbGibParams | 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: 8ce0810a3a88f420639bf8286df1d826)`); }
+            const domainIb = decodeURIComponent(match[1]);
+            const domainGib = decodeURIComponent(match[2]);
+            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
+            const ibGibIb = decodeURIComponent(match[3]);
+            const ibGibGib = decodeURIComponent(match[4]);
+            const ibGibAddr = getIbGibAddr({ ib: ibGibIb, gib: ibGibGib });
+            return {
+                ibGibIb, ibGibGib, ibGibAddr,
+                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...`); }
+
+            const errors: string[] = [];
+
+            // strict checking
+            const queryParamsKeys = Object.keys(queryParams);
+            const invalidKeys: string[] = queryParamsKeys.filter(x => !isKnownQueryParamsKey_IbGibGet(x));
+            if (invalidKeys.length > 0) {
+                throw new Error(`invalid query params keys: ${invalidKeys.join(', ')}. valid query params keys: ${KNOWN_QUERY_PARAMS_IBGIB_GET.join(', ')} (E: b7e8a9f2c1d34e56b89a01d4f2e7c326)`);
+            }
+
+            // Enforce that EVERY key must have a validation function mapping
+            type ValidationFn = () => Promise<void>;
+            const ValidationFns: Record<KNOWN_QUERY_PARAMS_IBGIB_GET, ValidationFn> = {
+                getLatest: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getLatest', errors),
+                getGraph: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getGraph', errors),
+                addrOnly: async () => validateAndCoerceBooleanQueryParam(queryParams, 'addrOnly', 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<IbGibParams, IbGibGetQueryParams>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
+
+            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
+            if (!reqCtx.metaspace) { throw new Error(`(UNEXPECTED) metaspace falsy? we should have initialized it by now since this is a domain-dependent handler (E: 864661c668d2aa1918b7ee677a7d9c26)`); }
+
+            const { ibGibIb, ibGibGib } = reqCtx.params as IbGibParams;
+            if (!ibGibIb || !ibGibGib) { return undefined; }
+
+            // Reconstruct addr from params
+            const rawAddr = `${ibGibIb}^${ibGibGib}`;
+            if (!validateAddressSegment(rawAddr)) return this.error(400, 'Invalid address format');
+            const addr = rawAddr;
+
+            const queryParams = {
+                ...DEFAULT_QUERY_PARAMS_GET_IBGIB,
+                ...(reqCtx.queryParams ?? {}),
+            };
+
+            const { getLatest, getGraph, addrOnly } = queryParams;
+
+            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`(UNEXPECTED) couldn't get default local user space? (E: ec6161ea3a08892ad8bfd1b7b0d79826)`); }
+
+            let addr_latest: string = addr;
+            if (getLatest) {
+                const latestAddr = await reqCtx.metaspace.getLatestAddr({ addr, space });
+                if (latestAddr) { addr_latest = latestAddr; }
+            }
+
+            // Lightweight tip-check: return only the resolved address.
+            // Client uses this to decide whether a full sync is necessary
+            // without incurring the cost of fetching the full ibgib or graph.
+            if (addrOnly && !getGraph) {
+                return this.ok({ addr: addr_latest, clientAddr: addr });
+            } /* <<<<< returns early */
+
+            if (getGraph) {
+                const resGraph = await reqCtx.metaspace.getDependencyGraph({
+                    ibGibAddr: addr_latest,
+                    space,
+                    live: getLatest,
+                });
+                const addrs = Object.keys(resGraph);
+                if (addrs.length > 0) {
+                    if (addrOnly) {
+                        // Return only the address list for delta negotiation (smart diff):
+                        // client compares these against what it already has to determine
+                        // the minimal set it needs to fetch.
+                        return this.ok({ addr: addr_latest, clientAddr: addr, addrs });
+                    } else {
+                        const responseBody: IbGibGraphResponseBody = {
+                            addr: addr_latest,
+                            count: addrs.length,
+                            graph: resGraph
+                        };
+                        return this.ok(responseBody);
+                    }
+                } else {
+                    return this.notFound(`Graph not found for ${addr_latest} (E: 89b259f13ae5e4f0d8287f6c0475a826)`);
+                }
+            } else {
+                const resGet = await reqCtx.metaspace.get({ space, addr: addr_latest });
+                if (resGet.success && resGet.ibGibs?.length === 1) {
+                    const ibGib = resGet.ibGibs[0];
+                    return this.ok(ibGib);
+                } else {
+                    return this.notFound(`IbGib not found for ${addr_latest} (E: 017621e0a8086832ff06cfc884b8c426)`);
+                }
+            }
+        } catch (error) {
+            if (logalot) { console.error(extractErrorMsg(error)) }
+            return this.error(500, extractErrorMsg(error));
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}