# Space-Gib Client

This directory contains the browser single-page application (SPA) frontend for `space-gib`.

## Architecture

* **Framework**: Built on top of `web-gib`, utilizing IbGib's vanilla web component architecture (no React/Vue/Angular).
* **Styling**: Vanilla CSS utilizing dark glassmorphism and modern variables.
* **State**: Interacts with the backend via a REST API bridge (`SpaceGibApiBridge`) and directly connects to the Node.js WebSocket endpoint for live peer synchronization.
* **Build**: Bundled by `esbuild` using the monorepo's shared `build-space-gib.mts` script.

## Core Structure
* `index.html` & `style.css`: The static entry points.
* `index.mts`: The JS entry point that initializes the global context and bootstraps the SPA.
* `components/`: Contains dynamic UI components (`keystone-creator`, etc.).
* `api/`: REST and WebSocket API communication layers (including email send/inbound handlers).
* `dev-tools.mts`: Utilities for rendering the local development test panel.

## Mobile Device Testing (Android via ADB over Wi-Fi & USB)

To test the mobile client with full hardware Passkey/WebAuthn support (fingerprint sensors, Face Unlock) against your local Dockerized Traefik server:

### 1. Initial Setup (via USB Cable)
1. Ensure **Developer Options** and **USB Debugging** are enabled on your Android phone.
2. Connect your phone to your laptop via USB.
3. Verify connection:
   ```powershell
   adb devices
   ```
   *(Tap "Always allow from this computer" if prompted on the phone).*

### 2. Wireless Wi-Fi Mode (Untethered)
1. Enable TCP/IP mode on port 5555 while still plugged in:
   ```powershell
   adb tcpip 5555
   ```
2. Find your phone's Wi-Fi IP address on your local network (e.g. *Settings → About Phone → Status Information → IP Address*, such as `192.168.86.42`).
3. Unplug the USB cable.
4. Connect wirelessly:
   ```powershell
   adb connect 192.168.86.42:5555
   ```
5. Apply the reverse port tunnel:
   ```powershell
   adb reverse tcp:8443 tcp:443
   ```
   *(Note: Android requires non-root ports ≥ 1024, so port 8443 on the phone tunnels into port 443 on your laptop).*

### 3. Open in Mobile Chrome
Navigate to:
```
https://local.ibgib.space:8443
```
*(Accept the self-signed SSL warning if prompted).*

### 4. Reconnecting after Laptop or Phone Restart
* If only the laptop restarts (phone was not rebooted):
  ```powershell
  adb connect <phone-ip>:5555
  adb reverse tcp:8443 tcp:443
  ```
* If the phone reboots: Android turns off TCP/IP mode on port 5555 for security. Briefly plug in the USB cable, run `adb tcpip 5555`, unplug, and reconnect via Wi-Fi.

## Passkey Testing with Chrome DevTools (Virtual Authenticators)

You can test full hardware Passkey and WebAuthn PRF functionality without needing physical biometrics or YubiKeys by using Chrome's built-in **Virtual Authenticator Environment**.

### 1. Enable the WebAuthn DevTools Tab
1. Open Chrome and navigate to `https://space-gib.localhost` (or `https://local.ibgib.space`).
2. Open Chrome DevTools (`F12` or `Ctrl+Shift+I` / `Cmd+Option+I`).
3. Click the three vertical dots (`⋮`) at top-right of DevTools $\to$ **More tools** $\to$ **WebAuthn**.
4. Check the box **"Enable Virtual Authenticator Environment"**.

---

### 2. Recommended Virtual Devices to Test (Up to 3 Configurations)

You can add multiple virtual devices simultaneously to test different transport badges and multi-credential selection:

#### Device 1: Built-in Platform Biometrics (Touch ID / Windows Hello / Android)
* **Protocol**: `ctap2`
* **Transport**: `internal`
* **Checkboxes**:
  * [x] `Supports resident keys`
  * [x] `Supports user verification`
  * [x] `Supports hmac-secret` *(enables WebAuthn PRF)*
* **Purpose**: Simulates built-in biometric hardware for zero-password account genesis and sovereign device delegation.

#### Device 2: Roaming USB Security Key (YubiKey 5Ci)
* **Protocol**: `ctap2`
* **Transport**: `usb`
* **Checkboxes**:
  * [x] `Supports resident keys`
  * [x] `Supports user verification`
  * [x] `Supports hmac-secret` *(enables WebAuthn PRF)*
* **Purpose**: Simulates an external USB hardware key to test multi-key registration, `🔑 USB Key` transport badges, and key removal/revocation.

#### Device 3: Roaming NFC Security Key
* **Protocol**: `ctap2`
* **Transport**: `nfc`
* **Checkboxes**:
  * [x] `Supports resident keys`
  * [x] `Supports user verification`
  * [x] `Supports hmac-secret` *(enables WebAuthn PRF)*
* **Purpose**: Tests contactless transport badges (`📶 NFC`) and dropdown credential selection in authorization dialogs.

---

### 3. Quick Test Flow

1. **Test Genesis (Zero-Password Onboarding)**:
   * Navigate to **New Identity**.
   * Click **Tab 2: 🛡️ Passkey / Hardware**.
   * Enter a username and click **🛡️ Create Sovereign Identity with Passkey**.
   * The active virtual authenticator will respond automatically, creating the identity and sovereign sync delegate with 0 passwords typed!
   * In DevTools WebAuthn panel, you will see the generated resident credential ID and private key appear.

2. **Test Multi-Passkey Registration & Badges**:
   * Navigate to **Identity Details** $\to$ Scroll to the **Passkeys & Hardware Authenticators** card.
   * Verify your genesis passkey shows the `💻 Touch ID / Built-in` badge.
   * Switch the active virtual authenticator in DevTools to **Device 2 (USB)**.
   * Click **🛡️ Register New Passkey / Security Key**.
   * Enter your password or authorize via DevTools $\to$ A new passkey appears with the `🔑 USB Key` badge!

3. **Test Hybrid Dialog Authorization**:
   * In **Identity Details**, click **Remove** on one of the passkeys (or click an SSO provider to unlink).
   * Notice the prompt dialog displays the **`[ 🛡️ Touch ID / Security Key ]`** action button alongside the password field.
   * Click the button to authorize with the virtual authenticator instantly without entering a password.

---

For local development commands, please refer to the [Root space-gib README](../../README.md).