@ibgib/space-gib 0.0.1

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

@@ -0,0 +1,261 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-evolve.handler
+ *
+ * PUT /api/keystone/evolve/:domainAddr
+ *
+ * Receives an evolved domain keystone (`I^I1.Itjp`) and any related
+ * ibgibs (e.g., the `S^Stjp` session keystone).
+ *
+ * Validates the evolution, verifies the `S` session keystone, and persists
+ * them to the domain metaspace to authorize the sync session.
+ */
+
+import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-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 { API_PATH_REGEXES } from '../../../../path-constants.mjs';
+import { DomainInfo, ParamsWithDomain, RequestContext, ResponseResult } from '../../../types.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+interface EvolveParams extends ParamsWithDomain {
+    domainAddr: string;
+}
+
+interface EvolveBody {
+    keystoneIbGib: KeystoneIbGib_V1;
+    relatedIbGibs?: IbGib_V1[];
+}
+
+export class KeystoneEvolveHandler extends ServeGibHandlerWithMetaspaceBase<EvolveParams, EvolveBody> {
+    protected override lc: string = `[${KeystoneEvolveHandler.name}]`;
+    protected override method: 'PUT' = 'PUT';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_EVOLVE;
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<EvolveParams, any>): Promise<EvolveParams | undefined> {
+        const match = reqCtx.pathname.match(this.regex);
+        if (match && match.length >= 3) {
+            const domainIb = decodeURIComponent(match[1]);
+            const domainGib = decodeURIComponent(match[2]);
+            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
+            return {
+                domainAddr,
+                domainInfo: this.getDomainInfo({ domainAddr })
+            };
+        }
+        return undefined;
+    }
+
+    protected override async validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
+        return []; // We don't expect any query parameters for evolution
+    }
+
+    protected override async handleRouteImpl(reqCtx: RequestContext<EvolveParams>): Promise<ResponseResult> {
+        const lc = `${this.lc}[handleRouteImpl]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!reqCtx.params) { return this.error(400, 'Invalid parameters'); }
+            if (!reqCtx.metaspace) { return this.error(500, 'Metaspace not initialized'); }
+
+            const { domainAddr } = reqCtx.params;
+            const bodyStr = reqCtx.body;
+            if (!bodyStr) { return this.error(400, 'Empty body'); }
+
+            let parsed: EvolveBody;
+            try {
+                parsed = JSON.parse(bodyStr);
+            } catch (err) {
+                return this.error(400, 'Invalid request JSON body: bodyStr does NOT parse. (E: 2f81c8c80a6884ff32b877671e92f326)');
+            }
+
+            const { keystoneIbGib, relatedIbGibs = [] } = parsed;
+            if (!keystoneIbGib) {
+                return this.error(400, 'Invalid request. Body must contain keystoneIbGib (E: e234647f79282982c8012fe8015f5826)');
+            }
+
+            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+
+            // 1. Intrinsic hash validation
+            const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: keystoneIbGib });
+            if (intrinsicErrors && intrinsicErrors.length > 0) {
+                return this.error(422, 'Intrinsic keystone validation failed. (E: 6efeb756cb0fb6c3187c8448c5035826)', { errors: intrinsicErrors });
+            }
+
+            // 2. Verify URL :domainAddr matches the keystone's tjp
+            const { tjpGib } = getGibInfo({ ibGibAddr: addr });
+            const expectedTjpGib = getGibInfo({ ibGibAddr: domainAddr }).punctiliarHash;
+            if (tjpGib !== expectedTjpGib) {
+                return this.error(422, `Keystone tjpGib (${tjpGib}) does not match URL domainAddr tjpGib (${expectedTjpGib}) (E: 703d3c64b7382f21f863c1e83533c826)`);
+            }
+
+            // 3. Load previous frame (the current tip in metaspace)
+            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                return this.error(500, 'No local user space found (E: a1144e5d6cd9641fb82d6b359f131126)');
+            }
+            const keystoneService = new KeystoneService_V1();
+            let prevIbGib: KeystoneIbGib_V1;
+            try {
+                prevIbGib = await keystoneService.getLatestKeystone({
+                    addr: domainAddr,
+                    metaspace: reqCtx.metaspace,
+                    space
+                });
+            } catch (error) {
+                return this.error(422, `Could not retrieve previous keystone tip for ${domainAddr} (E: bc2da8fb4dbda2c65851de9dd0b0eb26)`, { error: extractErrorMsg(error) });
+            }
+
+            // 4. Validate Evolution Transition
+            const validationErrors = await keystoneService.validate({
+                currentIbGib: keystoneIbGib,
+                prevIbGib
+            });
+            if (validationErrors && validationErrors.length > 0) {
+                return this.error(422, 'Keystone evolution validation failed', { errors: validationErrors });
+            }
+
+            // 5. Check Single Pool Restriction
+            const restrictionError = this.validateSinglePoolRestriction(keystoneIbGib);
+            if (restrictionError) {
+                return this.error(422, restrictionError); /* <<<< returns early */
+            }
+
+            // 6. Route by claim verb
+            const proofs = keystoneIbGib.data?.proofs ?? [];
+            if (proofs.length !== 1) { throw new Error(`(UNEXPECTED) evolving keystone with proofs.length !== 1? we just checked that the length of proofs was exactly 1 in checkSinglePoolRestriction (E: 3021bb0ce9783e27c8e3492820aeb926)`); }
+            const { claim } = proofs[0];
+            if (!claim) { throw new Error(`proof.claim is falsy (E: e1dd983db341185528a75768919ea826)`); }
+            const { verb } = claim;
+            if (!verb) { throw new Error(`(UNEXPECTED) claim.verb falsy? atow (05/15/2026) I thought all claims should have a verb. I could be wrong of course as it's still early days. (E: 933a9856d6625b547d7ec158d678a826)`); }
+
+            switch (verb) {
+                case 'sync':
+                    return await this.handleSyncEvolution(reqCtx, keystoneIbGib, relatedIbGibs, space);
+                default:
+                    throw new Error(`non-sync keystone evolution not yet implemented (E: 83cb29bf67d681542bfd486d0f91e726)`);
+                // return await this.handleDefaultEvolution(reqCtx, keystoneIbGib, space);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            return this.error(500, `Internal error evolving keystone`, { details: extractErrorMsg(error) });
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected validateSinglePoolRestriction(keystoneIbGib: KeystoneIbGib_V1): string | undefined {
+        const proofs = keystoneIbGib.data?.proofs ?? [];
+        if (proofs.length === 0) {
+            return 'No proofs found in evolved keystone data';
+        }
+
+        const poolIds = new Set<string>();
+        for (const proof of proofs) {
+            for (const solution of proof.solutions || []) {
+                if (solution.poolId) {
+                    poolIds.add(solution.poolId);
+                }
+            }
+        }
+
+        if (poolIds.size > 1) {
+            return `Multiple pools evolved (${Array.from(poolIds).join(', ')}). Only one pool evolution allowed at a time.`;
+        }
+
+        return undefined; // no error
+    }
+
+    protected async handleSyncEvolution(
+        reqCtx: RequestContext<EvolveParams>,
+        keystoneIbGib: KeystoneIbGib_V1,
+        relatedIbGibs: IbGib_V1[],
+        space: IbGibSpaceAny
+    ): Promise<ResponseResult> {
+        const lc = `${this.lc}[${this.handleSyncEvolution.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 80cf7ba10a781fad87171b747de10826)`); }
+
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const proofs = keystoneIbGib.data?.proofs ?? [];
+            if (proofs.length !== 1) { throw new Error(`(UNEXPECTED) proofs.length !== 1? (E: ac9748a187f87455bc01fdeeb4363826)`); }
+            const claim = proofs[0].claim;
+            const sAddr = claim?.target;
+            if (!sAddr) {
+                return this.error(422, 'No target address found in sync claim');
+            }
+
+            // Validate S^Stjp (session keystone ibgib) from relatedIbGibs
+            const sIbGib = relatedIbGibs.find(ibGib => getIbGibAddr({ ibGib }) === sAddr) as KeystoneIbGib_V1 | undefined;
+            if (!sIbGib) {
+                return this.error(422, `Session keystone ${sAddr} must be provided in relatedIbGibs`);
+            }
+
+            const sIntrinsicErrors = await validateIbGibIntrinsically({ ibGib: sIbGib });
+            if (sIntrinsicErrors && sIntrinsicErrors.length > 0) {
+                return this.error(422, 'Intrinsic validation failed for S^Stjp', { errors: sIntrinsicErrors });
+            }
+
+            const keystoneService = new KeystoneService_V1();
+            const sGenesisErrors = await keystoneService.validateGenesisKeystone({ keystoneIbGib: sIbGib });
+            if (sGenesisErrors && sGenesisErrors.length > 0) {
+                return this.error(422, 'Genesis validation failed for S^Stjp', { errors: sGenesisErrors });
+            }
+
+            // Persist both I and S
+            await reqCtx.metaspace!.put({ ibGibs: [keystoneIbGib, sIbGib], space });
+            await reqCtx.metaspace!.registerNewIbGib({ ibGib: keystoneIbGib, space });
+            await reqCtx.metaspace!.registerNewIbGib({ ibGib: sIbGib, space });
+
+            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+            if (logalot) { console.log(`${lc} domain evolution stored and registered: ${addr}`); }
+
+            return this.ok({
+                message: `Successfully evolved domain keystone with session keystone`,
+            });
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async handleDefaultEvolution(
+        reqCtx: RequestContext<EvolveParams>,
+        keystoneIbGib: KeystoneIbGib_V1,
+        space: IbGibSpaceAny
+    ): Promise<ResponseResult> {
+        const lc = `${this.lc}[${this.handleDefaultEvolution.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 8b755b4087b16c0d760d3ca397fad726)`); }
+
+            // Persist only I
+            await reqCtx.metaspace!.put({ ibGibs: [keystoneIbGib], space });
+            await reqCtx.metaspace!.registerNewIbGib({ ibGib: keystoneIbGib, space });
+
+            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+            if (logalot) { console.log(`${lc} domain evolution stored and registered: ${addr} (I: 990d686a19d645afaa624e386caac826)`); }
+
+            return this.ok({
+                message: `Successfully evolved domain keystone. (I: 4cd058a08a171069982a7f3808cbe826)`,
+            });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+}

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

@@ -0,0 +1,146 @@
+/**
+ * @module serve-gib/handlers/api/keystone/keystone-genesis.handler
+ *
+ * POST /api/keystone/genesis
+ *
+ * Accepts a single genesis-frame keystone ibgib from the client and
+ * bootstraps a new domain-isolated metaspace for it.
+ *
+ * ## request body
+ *
+ * ```json
+ * { "keystoneIbGib": <KeystoneIbGib_V1> }
+ * ```
+ *
+ * ## validation steps
+ *
+ * 1. Body contains `keystoneIbGib` (single ibgib, not an array).
+ * 2. Intrinsic hash validation passes (`validateIbGibIntrinsically`).
+ * 3. Structural keystone check: `ib` starts with `"keystone"`, no `past` in
+ *    `rel8ns` (genesis = TJP frame, no prior timeline).
+ * 4. Domain uniqueness: the path derived from the keystone's tjpGib must not
+ *    already exist on disk — if it does, return 409 Conflict.
+ * 5. Bootstrap: call `bootstrapDomainMetaspace` to create folders + metaspace.
+ * 6. Persist the keystone ibgib into the newly created domain space.
+ *
+ * ## notes
+ *
+ * Unlike domain-scoped handlers, this handler does NOT rely on
+ * `reqCtx.metaspace` (which is undefined when no domain exists yet). It
+ * creates the metaspace itself using `bootstrapDomainMetaspace`.
+ */
+
+import { existsSync } from 'node:fs';
+
+import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
+import { getDomainRootPath } from '../../../../bootstrap-helper.mjs';
+import { bootstrapDomainMetaspace } from '../../../../bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+
+
+
+/**
+ * POST /api/keystone/genesis
+ *
+ * No path params — the domain is derived from the incoming keystone ibgib.
+ */
+export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneGenesisHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_GENESIS;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, undefined>
+    ): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
+
+            // ----------------------------------------------------------------
+            // 1. Parse body — expect { keystoneIbGib }
+            // ----------------------------------------------------------------
+            let parsed: any;
+            try {
+                parsed = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON');
+            }
+
+            const { keystoneIbGib } = parsed;
+            if (!keystoneIbGib) {
+                return this.error(400, 'Body must contain keystoneIbGib');
+            }
+
+            // ----------------------------------------------------------------
+            // 2. Intrinsic hash validation
+            // ----------------------------------------------------------------
+            const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: keystoneIbGib });
+            if (intrinsicErrors) {
+                return this.error(422, 'Intrinsic keystone validation failed', { errors: intrinsicErrors });
+            }
+
+            // ----------------------------------------------------------------
+            // 3. Structural keystone + genesis-frame checks
+            // ----------------------------------------------------------------
+            const keystoneService = new KeystoneService_V1();
+            const keystoneErrors = await keystoneService.validateGenesisKeystone({
+                keystoneIbGib
+            });
+            if (keystoneErrors && keystoneErrors.length > 0) {
+                return this.error(422, 'Keystone genesis validation failed', { errors: keystoneErrors });
+            }
+
+            // ----------------------------------------------------------------
+            // 4. Domain uniqueness check — 409 if the domain already exists
+            // ----------------------------------------------------------------
+            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
+            const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: addr });
+            const domainGib = tjpGib || punctiliarHash;
+            if (!domainGib) {
+                return this.error(422, `Could not extract domain identifier from keystone address: ${addr}`);
+            }
+
+            const domainRootPath = getDomainRootPath(domainGib, reqCtx.dataDir);
+            if (existsSync(domainRootPath)) {
+                return this.error(409, `Domain already exists for this keystone (tjpGib: ${domainGib}). Use PUT /api/keystone/evolve/:domainAddr to evolve.`);
+            }
+
+            // ----------------------------------------------------------------
+            // 5. Bootstrap the new domain metaspace (creates folders)
+            // ----------------------------------------------------------------
+            const metaspace = await bootstrapDomainMetaspace(addr, reqCtx.dataDir);
+
+            // ----------------------------------------------------------------
+            // 6. Persist the genesis keystone into the new domain space
+            // ----------------------------------------------------------------
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                throw new Error(`(UNEXPECTED) Could not get local user space after bootstrapping domain for ${addr} (E: b1c2d3e4f5a6b7c8d9e0f1a2b3c4d526)`);
+            }
+
+            await metaspace.put({ ibGibs: [keystoneIbGib], space });
+            await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space });
+
+            console.log(`${lc} domain created and keystone persisted: ${addr}`);
+            if (logalot) { console.log(`${lc} keystoneIbGib: ${pretty(keystoneIbGib)} (I: d598c6ff7a48997d585b84c19c464826)`); }
+            return this.ok({ success: true, addr }, 201);
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/server/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.`); }
+        }
+    }
+}