Space-Gib

Space-Gib is the multitenant synchronization peer and hosting environment for the IbGib ecosystem. It features a Node.js Express/serve-gib backend and a dynamic SPA client frontend.

🔒 Intrinsic App Capabilities: Personal Notes & Password Manager

Beyond its role as a provider/sync host for identity networks, Space-Gib is built to serve as a high-security, local-first utility for the user:

• Personal Organizer: A secure notebook for comments, text, and personal memos.
• Password Manager: A zero-knowledge vault for credentials, site logins, and secrets.
• Email Infrastructure: Service-agnostic email sender/receiver architecture supporting AWS SES REST API and local mock drivers (/api/email/inbound, /api/email/send).
• Zero-Knowledge Architecture: All personal notes and credential vaults are encrypted client-side using strong AES-GCM keys derived deterministically from the user's active Keystone identity secrets. The hosting server and sync peers only see encrypted blobs and can never read the user's notes or credentials.

Local Development Workflow

The local development environment uses a dual-target esbuild watch process and Docker for hosting the Node.js server behind a Traefik reverse proxy.

To run the full development loop, open three separate terminal windows:

Terminal 1: Watch (Client & Server)

Run the watch process to continuously type-check and bundle both client and server source files.

npm run watch:space-gib

Terminal 2: Run (Docker)

Start the Docker environment (Traefik + Node container).

npm run docker:space-gib

Once started, the application is available at https://space-gib.localhost

Terminal 3: Restart (As needed)

Because the Node.js process runs inside Docker, hot-reloading the server code requires restarting the container.

• Client changes: Auto-reload when you refresh the browser.
• Server changes: Run this command to load your newly compiled server code.

npm run restart:space-gib

Directory Structure

• src/client/: The browser SPA frontend. See Client README.
• src/server/: The Node.js server. See Server README.
• src/common/: Shared logic, types, and constants used by both client and server.

  [!IMPORTANT] STRICT RULE: src/common MUST NEVER import from src/client or src/server. This ensures the shared layer remains portable and prevents circular dependencies.

• dist/: The output directory where esbuild writes the bundled client (dist/client/) and server (dist/server/) code.

Debugging the Server

You can attach the VS Code debugger directly to the Node.js process running inside Docker.

1. The server runs with the --inspect=0.0.0.0:9229 flag.
2. docker-compose.yml maps port 9229 to your host machine.
3. Use the VS Code launch configuration Docker: Attach to Space-Gib to attach breakpoints.

🛡️ Long-Term Decentralized Security & Threat Modeling

As space-gib transitions from the V1 single-server model to a fully decentralized, peer-to-peer architecture, the following security threats (inherently mitigated by the centralized nature of V1) must be addressed:

1. The Revocation Sync Gap (Stale Parent State)

• The Threat: In a multi-peer network, if a user revokes a delegate keystone on Peer A (evolving $K_{\text{domain}}$ to remove the delegate), Peer B may not immediately sync the revocation frame. If an attacker presents the compromised delegate to Peer B before it syncs the parent's latest state, Peer B will accept it.
• Decentralized Mitigation: Peers must require cryptographic proof of freshness (epochs, sequence checks) or query a quorum of sync space hubs to verify $K_{\text{domain}}$'s latest tip before executing high-value operations.

2. Cross-Origin Identity Federation (Same-Origin Policy Limitations)

• The Threat: Browser Same-Origin Policy (SOP) isolates IndexedDB and local storage by domain. If a user stores their primary identity keys on space-gib.localhost (Site A), script running on a different client app origin other-ibgib-app.localhost (Site B) cannot access Site A's IndexedDB to sign claims.
• Relationship to Sync Remotes: While ibgib's sync protocol allows Site B to act as a Git-like remote that we push to and pull from via network requests, the SOP limitation applies to the browser frontend client running on Site B. To boot a local repository on Site B that can interact with the remote, Site B needs its own local delegate keys.
• Decentralized Mitigation: We must establish a secure cross-origin handshake (e.g., standardizing a redirect/popup or postMessage flow) where Site A authenticates the user and securely transfers a restricted, site-scoped delegate keystone to Site B's local IndexedDB. Once Site B has this delegate, it can sync natively with other peers.

Future Enhancements & Todo

• Notification Broadcast System: Implement a secure notification broadcast system to alert the user immediately via UI notifications when any challenge pool modification or administrative evolution occurs on their identity keystone.