@ibgib/space-gib 0.0.1

package/src/common/keystone-policies.mts

@@ -0,0 +1,159 @@
+/**
+ * @module common/keystone-policies
+ *
+ * Centralized identity and security policies for the space-gib application.
+ * Defines standard configurations for both persistent (Domain) and ephemeral (Session) keystones.
+ *
+ * ## important
+ *
+ * This file is part of the `src/common` layer. It MUST NEVER import from
+ * `src/client` or `src/server`.
+ */
+
+import { HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import {
+    KeystoneReplenishStrategy,
+    KeystoneChallengeType,
+    KeystoneIbGib_V1,
+    KeystoneSolution
+} from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { KeystoneStrategyFactory } from '@ibgib/core-gib/dist/keystone/strategy/keystone-strategy-factory.mjs';
+
+// ---------------------------------------------------------------------------
+// 1. Session Keystone (S) Policies
+// ---------------------------------------------------------------------------
+
+/**
+ * Default configurations for short-lived session keystones (S^Stjp).
+ * These values match the real-world usage in the space-gib client.
+ */
+export const SESSION_KEYSTONE_POLICY = {
+    /**
+     * Shared parameters across all session pools
+     */
+    COMMON: {
+        ALGO: HashAlgorithm.sha_256,
+        TYPE: KeystoneChallengeType.hash_reveal_v1,
+        ROUNDS: 2,
+        REPLENISH: KeystoneReplenishStrategy.topUp,
+    },
+
+    /**
+     * The primary authorization pool for sync actions (e.g. putting/getting ibgibs).
+     */
+    DEFAULT_POOL: {
+        ID: 'default',
+        SIZE: 20,
+        SELECT_SEQUENTIALLY: 2,
+        SELECT_RANDOMLY: 2,
+        /**
+         * We want more for this, with future implementations we will not have
+         * resource exhaustion.
+         */
+        TARGET_BINDING_CHARS: 3,
+    },
+
+    /**
+     * Dedicated pool for the WebSocket sync protocol handshake.
+     */
+    HANDSHAKE_POOL: {
+        ID: 'handshake',
+        VERB: 'handshake',
+        SIZE: 10,
+        SELECT_SEQUENTIALLY: 2,
+        SELECT_RANDOMLY: 2,
+        TARGET_BINDING_CHARS: 0,
+        /** Number of IDs the server should demand during the handshake. */
+        SERVER_DEMAND_COUNT: 3,
+    }
+} as const;
+
+
+// ---------------------------------------------------------------------------
+// 2. Domain/Identity Keystone (I) Policies
+// ---------------------------------------------------------------------------
+
+/**
+ * Server-side minimum requirements for long-lived primary identity keystones.
+ *
+ * [Nag] These are initial placeholder standards and should be reviewed for
+ * production hardening.
+ */
+export const DOMAIN_KEYSTONE_SECURITY_STANDARDS = {
+    MIN_DEFAULT_POOL_SIZE: 50,
+    ALLOWED_ALGORITHMS: [
+        HashAlgorithm.sha_256,
+        HashAlgorithm.sha_512
+    ],
+} as const;
+
+
+// ---------------------------------------------------------------------------
+// 3. Upfront Picket-Fence Handshake Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the lexicographically first challenge from the session keystone's
+ * 'handshake' pool to be used as a deterministic, dynamic upfront pre-filter challenge.
+ */
+export function getHandshakeChallenge(keystone: KeystoneIbGib_V1): { challengeId: string; challenge: any } {
+    const handshakePool = (keystone.data?.challengePools ?? []).find(
+        (p) => p.id === SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID
+    );
+    if (!handshakePool) {
+        throw new Error(`Keystone missing "${SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID}" pool`);
+    }
+
+    const challengeIds = Object.keys(handshakePool.challenges).sort();
+    if (challengeIds.length === 0) {
+        throw new Error(`Handshake pool has no challenges`);
+    }
+
+    const challengeId = challengeIds[0];
+    const challenge = handshakePool.challenges[challengeId];
+    return { challengeId, challenge };
+}
+
+/**
+ * Cryptographically validates the upfront picket-fence solution against the session keystone.
+ * Verifies that the client solved the lexicographically first challenge from the 'handshake' pool.
+ */
+export async function checkHandshakeSolution(
+    keystone: KeystoneIbGib_V1,
+    solutionValue: string
+): Promise<boolean> {
+    const handshakePool = (keystone.data?.challengePools ?? []).find(
+        (p) => p.id === SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID
+    );
+    if (!handshakePool) {
+        return false;
+    }
+
+    const { challengeId, challenge } = getHandshakeChallenge(keystone);
+    const strategy = KeystoneStrategyFactory.create({ config: handshakePool.config });
+    const solution: KeystoneSolution = {
+        type: 'hash-reveal-v1',
+        challengeId,
+        poolId: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID,
+        value: solutionValue
+    };
+
+    return await strategy.validateSolution({ solution, challenge });
+}
+
+// this is what we had by default inside the sync saga coordinator
+// const primaryPoolConfig: KeystonePoolConfig_HashV1 = {
+//     allowedVerbs: [KEYSTONE_VERB_MANAGE],
+//     id: SESSION_IDENTITY_KEYSTONE_PRIMARY_POOL_ID,
+//     salt: sagaId,
+//     behavior: {
+//         size: SESSION_IDENTITY_KEYSTONE_CONFIG_SIZE,  // Large pool for many signatures
+//         replenish: SESSION_IDENTITY_KEYSTONE_CONFIG_REPLENISH_STRATEGY,
+//         selectSequentially: SESSION_IDENTITY_KEYSTONE_CONFIG_SEQUENTIAL,
+//         selectRandomly: SESSION_IDENTITY_KEYSTONE_CONFIG_RANDOM,
+//         targetBindingChars: SESSION_IDENTITY_KEYSTONE_CONFIG_TARGET_BINDING,
+//     },
+//     type: KeystoneChallengeType.hash_reveal_v1,
+//     algo: SESSION_IDENTITY_KEYSTONE_CONFIG_ALGO,
+//     rounds: SESSION_IDENTITY_KEYSTONE_CONFIG_ROUNDS,
+// };

package/src/respec-gib.node.mts

@@ -0,0 +1,6 @@
+import { RespecNodeRunner } from '@ibgib/helper-gib/dist/respec-gib/respec-node-runner.mjs';
+
+const runner = new RespecNodeRunner({
+    respecFileRegExp: /\.respec/,
+});
+await runner.run();

package/src/server/README.md

@@ -0,0 +1,18 @@
+# Space-Gib Server
+
+This directory contains the Node.js server implementation for `space-gib`. 
+
+The server is built on a custom microframework called `serve-gib`. For details on how routing, contexts, and request handling work within the framework, please refer to the [serve-gib Microframework Guide](serve-gib/README.md).
+
+## Architecture
+
+* **Framework**: Uses the minimalist `serve-gib` microframework instead of Express to maintain strict control over routing and IbGib multitenant contexts.
+* **Hosting**: The server runs inside a Docker container orchestrated via `docker-compose`.
+* **Build**: Compiled and bundled by `esbuild` using the monorepo's shared `build-space-gib.mts` script.
+
+## Core Files
+* `server.mts`: The main entry point that initializes the server, handles WebSocket upgrades, and defines the HTTP routing pipeline.
+* `path-constants.mts`: Canonical definitions for all API regex routes.
+* `bootstrap-helper.mts`: Logic for initializing domain-isolated multitenant metaspaces.
+
+For local development commands, please refer to the [Root space-gib README](../../README.md).

package/src/server/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 '@ibgib/node-gib/dist/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 '@ibgib/node-gib/dist/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 '@ibgib/node-gib/dist/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/server/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)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+    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/server/metaspace-nodeindexedspace/metaspace-nodeindexedspace.mts

@@ -0,0 +1,85 @@
+/**
+ * @module node-metaspace driven by a node+fs storage substrate
+ *
+ * a metaspace is a space of spaces. it adds/removes spaces and does
+ * inter-spatial composition related things. it's similar to what people think
+ * of in terms of a node in a p2p network.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { IbGibCacheService } from '@ibgib/core-gib/dist/common/cache/cache-types.mjs';
+import { MetaspaceBase } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-base.mjs';
+import { MetaspaceFactory } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+
+import { GLOBAL_LOG_A_LOT, GLOBAL_TIMER_NAME } from '../server-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ *
+ */
+export class Metaspace_Nodeindexedspace extends MetaspaceBase {
+
+  // we won't get an object back, only a DTO ibGib essentially
+  protected lc: string = `[${Metaspace_Nodeindexedspace.name}]`;
+
+  get zeroSpace(): IbGibSpaceAny {
+    const lc = `[${this.lc}][get zeroSpace]`;
+    if (this.metaspaceFactory.fnZeroSpaceFactory) {
+      return this.metaspaceFactory.fnZeroSpaceFactory();
+    } else {
+      throw new Error(`${lc} (UNEXPECTED) this.metaspaceFactory.fnZeroSpaceFactory falsy. not initialized? (E: 9e6c6954dacd868b18c9f34a71e63523)`);
+    }
+  }
+
+  constructor(
+    // public modalController: ModalController,
+    // public alertController: AlertController,
+    protected cacheSvc: IbGibCacheService | undefined,
+    // private latestCacheSvc: IonicStorageLatestIbgibCacheService,
+  ) {
+    super(cacheSvc);
+    const lc = `${this.lc}[ctor]`;
+    if (logalot) {
+      console.log(`${lc}${GLOBAL_TIMER_NAME}`);
+      console.timeLog(GLOBAL_TIMER_NAME);
+      console.log(`${lc} created. (I: 5690dc2ebf774df3a442bd463dee7455)`);
+    }
+
+  }
+
+  protected async initializeMetaspaceFactory({ metaspaceFactory }: {
+    metaspaceFactory: MetaspaceFactory,
+  }): Promise<void> {
+    const lc = `[${this.initializeMetaspaceFactory.name}]`;
+    try {
+      if (logalot) { console.log(`${lc} starting... (I: 5a29670439ac47634dcdfe25225c8223)`); }
+      if (!metaspaceFactory) { throw new Error(`(UNEXPECTED) metaspaceFactory falsy? space-gib server initialization should have guaranteed this to be truthy (E: f305356c2978cf0ee8062fd818940826)`); }
+      if (!metaspaceFactory.fnDefaultLocalSpaceFactory) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnDefaultLocalSpaceFactory? space-gib server initialization should have guaranteed this to be truthy (E: 884281e5251bd65528eb7b3f48737826)`); }
+      if (!metaspaceFactory.fnDtoToSpace) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnDtoToSpace? space-gib server initialization should have guaranteed this to be truthy (E: 885b7828606f36f9183bb9e687e25826)`); }
+      if (!metaspaceFactory.fnZeroSpaceFactory) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnZeroSpaceFactory? space-gib server initialization should have guaranteed this to be truthy (E: 336cf6655758bad4aaeea8ce08d8c826)`); }
+
+      await super.initializeMetaspaceFactory({ metaspaceFactory });
+    } catch (error) {
+      console.error(`${lc} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot) { console.log(`${lc} complete.`); }
+    }
+  }
+
+  // async initializeZeroSpace(): Promise<void> {
+  //   const lc = `[${this.initializeZeroSpace.name}]`;
+  //   try {
+  //     if (logalot) { console.log(`${lc} starting... (I: a3364e9601c70c8163e67868e5d67723)`); }
+
+  //   } catch (error) {
+  //     console.error(`${lc} ${extractErrorMsg(error)}`);
+  //     throw error;
+  //   } finally {
+  //     if (logalot) { console.log(`${lc} complete.`); }
+  //   }
+  // }
+
+}

package/src/server/path-constants.mts

@@ -0,0 +1,89 @@
+/** Maximum allowed path length to prevent DoS. */
+export const MAX_PATH_LENGTH = 2048;
+
+/**
+ * Blacklisted patterns for any incoming path.
+ * We iterate through these for a quick security check.
+ */
+export const FORBIDDEN_PATTERNS = [
+    /\.\./,      // No directory traversal
+    /\/\//,      // No redundant slashes
+    /\0/,        // No null bytes
+    /(^|\/)\./,  // No hidden/dot-files (e.g. .env, .git)
+];
+
+/**
+ * Regex for valid API paths.
+ *
+ * IMPORTANT: See IMPLEMENTATION.md for overall path schema documentation.
+ *
+ * Paths are URL encoded. The `ib` and `gib` portions of addresses are captured explicitly
+ * by splitting on `%5E` or `^`.
+ */
+export const API_PATH_REGEXES = {
+    /**
+     * /api/health
+     */
+    HEALTH: /^\/api\/health\/?$/,
+
+    /**
+     * /api/ibgib/graph/:domainAddr/:ibgibAddr
+     */
+    IBGIB_GRAPH: /^\/api\/ibgib\/graph\/([^\/]+?)(?:%5E|\^)([^\/]+)\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/ibgib/:domainAddr/:ibgibAddr
+     */
+    IBGIB_ADDR: /^\/api\/ibgib\/([^\/]+?)(?:%5E|\^)([^\/]+)\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/keystone
+     */
+    KEYSTONE: /^\/api\/keystone\/?$/,
+
+    /**
+     * /api/keystone/:domainAddr
+     */
+    KEYSTONE_ADDR: /^\/api\/keystone\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/ibgib
+     */
+    IBGIB_BASE: /^\/api\/ibgib\/?$/,
+
+    /**
+     * /api/keystone/evolve/:domainAddr
+     */
+    KEYSTONE_EVOLVE: /^\/api\/keystone\/evolve\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/keystone/genesis
+     *
+     * Accepts a single genesis-frame keystone ibgib and creates a new
+     * domain-isolated metaspace for it. No `:domainAddr` in the URL because
+     * the server derives the domain from the incoming keystone ibgib itself.
+     *
+     * Parallel to /api/keystone/evolve.
+     */
+    KEYSTONE_GENESIS: /^\/api\/keystone\/genesis\/?$/,
+
+    /**
+     * /api/debug/ws-echo
+     *
+     * Minimal WebSocket echo endpoint for validating WS plumbing (Traefik
+     * passthrough, server upgrade handling, client connectivity) before
+     * integrating real sync logic.
+     *
+     * ## intent
+     *
+     * NOT for production use. Remove or gate behind a flag once WS sync is
+     * confirmed working end-to-end.
+     */
+    DEBUG_WS_ECHO: /^\/api\/debug\/ws-echo\/?$/,
+    /**
+     * /api/sync/ws/:domainAddr
+     */
+    SYNC_WS: /^\/api\/sync\/ws\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+};
+
+export const VALID_STATIC_PATH_REGEX = /^\/[a-zA-Z0-9\-_\.\/]*$/;