# Space-Gib

> [!TIP]
> **🚀 Building Applications with ibgib**:
> Space-Gib serves as the reference implementation for **Full-Stack (Archetype A)** ibgib applications. For a comprehensive overview of building downstream applications, see the **[Creating IbGib Applications Guide](../../docs/CREATING_IBGIB_APPS_GUIDE.md)**, **[Client Guide](../../docs/IBGIB_CLIENT_APPS_GUIDE.md)**, and **[Server Guide](../../docs/IBGIB_SERVER_APPS_GUIDE.md)**.

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.
```bash
npm run watch:space-gib
```

### Terminal 2: Run (Docker)
Start the Docker environment (Traefik + Node container).
```bash
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.
```bash
npm run restart:space-gib
```

## Directory Structure

* [`src/client/`](src/client/): The browser SPA frontend. [See Client README](src/client/README.md).
* [`src/server/`](src/server/): The Node.js server. [See Server README](src/server/README.md).
* [`src/common/`](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/`](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.