# Igloo Server

Server‑based signing device and personal ephemeral relay for the FROSTR protocol. Igloo provides an always‑on signing node with an optional web UI for configuration and monitoring. Built on @frostr/igloo-core.

Looking to deploy quickly? Start with the one-click options in `docs/DEPLOY.md` (Umbrel App Store or Docker/Compose).

[▶ Watch the umbrel demo](https://plebdevs-bucket.nyc3.cdn.digitaloceanspaces.com/videos/random/igloo-server-umbrel-announcement.mp4)

## What It Is
- Threshold Schnorr signing for Nostr using your FROSTR shares (k‑of‑n). The full private key is never reconstructed.
- Two modes: Database (multi‑user, encrypted creds, web UI) or Headless (env‑only, API‑first, no UI).
- Includes an in‑memory relay for dev/tests; use production relays in real deployments.

## Features
- Always‑on signer built on igloo‑core with multi‑relay support
- Web UI (React + Tailwind) for setup, monitoring, recovery
- Persisted UI event log (DB mode) with pagination and NDJSON export download
- REST + WebSocket APIs with API‑key, Basic, or session auth
- Health monitor + auto‑restart on repeated failures
- Works as a single node or part of a k‑of‑n signer group
- Ephemeral relay for testing and local development (not for production data)

## Documentation
- [docs/DEPLOY.md](docs/DEPLOY.md) — Umbrel, Docker/Compose, and cloud deployment steps
- [docs/SECURITY.md](docs/SECURITY.md) — hardening, CSP, headers, and rate limiting guidance
- [docs/CONFIG.md](docs/CONFIG.md) — environment variables and operational tuning (CORS vs WS Origin, timeouts, restart/circuit knobs)
- [docs/AUTH_MATRIX.md](docs/AUTH_MATRIX.md) — which endpoints exist in which mode + what bypasses the global auth gate
- [docs/PEER_POLICIES.md](docs/PEER_POLICIES.md) — peer policy schema, precedence, and persistence
- [docs/RELEASE.md](docs/RELEASE.md) — release workflow, automation, and emergency fixes
- [docs/openapi/openapi.yaml](docs/openapi/openapi.yaml) — OpenAPI spec (served at `/api/docs`)

## Quick Start

### Prerequisites
- Bun runtime (uses Bun APIs like `bun:sqlite`).
- FROSTR group/share credentials or add them later via UI/API.

### Start Locally (Database mode – default)
```bash
git clone https://github.com/FROSTR-ORG/igloo-server.git
cd igloo-server && bun install && bun run build
export ADMIN_SECRET=$(openssl rand -hex 32)
bun run start
# http://localhost:8002 → enter ADMIN_SECRET → create admin → Configure tab → add GROUP_CRED + SHARE_CRED
```

### Start Locally (Headless)
```bash
export HEADLESS=true
export GROUP_CRED="bfgroup1..." ; export SHARE_CRED="bfshare1..."
export RELAYS='["wss://relay.primal.net","wss://relay.damus.io"]'
export AUTH_ENABLED=false ; export API_KEY=dev-local-key  # /api/env still requires auth
bun run start
```

## Configure & Deploy Fast

### Pick a Mode
- Database (recommended): multi‑user, AES‑encrypted creds, admin onboarding via `ADMIN_SECRET`, SQLite at `./data/igloo.db` (override with `DB_PATH`).
- Headless: env‑only config, API‑first, UI disabled. Supports `PEER_POLICIES` blocks (see `docs/PEER_POLICIES.md`) and API key auth.

### Deployment Options

#### Umbrel (1.1.0+)
1. In Umbrel, open the App Store → click the `…` menu (top‑right) → **Community App Stores**.
2. Add `https://github.com/frostr-org/igloo-server-store` and save, then install **Igloo Server**.
3. First launch: Umbrel injects `ADMIN_SECRET` (its app password) and the package sets `SKIP_ADMIN_SECRET_VALIDATION=true`, so you go straight to creating the first admin user. Follow the instructions screen, create your admin, then add `GROUP_CRED` / `SHARE_CRED`.
4. If the install reports data-dir permission errors, fix volume ownership once (see Umbrel note in docs/DEPLOY.md) and restart from the Umbrel dashboard.
5. Updates arrive via the store; start/stop from the Umbrel dashboard.

#### Docker / Compose
```bash
# one‑off
docker build -t igloo-server .
docker run -p 8002:8002 \
  -e NODE_ENV=production -e HOST_NAME=0.0.0.0 \
  -e ADMIN_SECRET=... -e AUTH_ENABLED=true -e RATE_LIMIT_ENABLED=true \
  -v $(pwd)/data:/app/data igloo-server

# compose (see compose.yml)
docker compose up -d --build
```

Reverse proxy (nginx) and cloud steps are in docs/DEPLOY.md.

### Production Checklist
- `NODE_ENV=production`, persist `/app/data`, set strong `ADMIN_SECRET` (keep set after onboarding).
- Explicit `ALLOWED_ORIGINS` (WebSocket Origin checks support `@self` for “whatever host the user connects through”; host match, port-agnostic), `TRUST_PROXY=true` behind a proxy; forward WS upgrade headers.
- Auth on (`AUTH_ENABLED=true`), rate limit on (`RATE_LIMIT_ENABLED=true`); optional `SESSION_SECRET` (auto‑gen if absent).
- Timeouts: tune `FROSTR_SIGN_TIMEOUT` or `SIGN_TIMEOUT_MS` (1000–120000ms).

## API & Docs
- Swagger UI: http://localhost:8002/api/docs (self‑hosted; run `bun run docs:vendor` if assets missing).
- OpenAPI: docs/openapi/openapi.yaml or `/api/docs/openapi.{json|yaml}`.
- Auth: API Key, Basic, or session; WS `/api/events` supports subprotocol hints (`apikey.<TOKEN>`, `bearer.<TOKEN>`, `session.<ID>`).
- Validate spec: `bun run docs:validate`.

### API Keys
- Headless: set a single `API_KEY` in env; HTTP cannot rotate it.
- Database mode: manage multiple keys via the UI or admin endpoints. Admin APIs accept either `Authorization: Bearer <ADMIN_SECRET>` or an authenticated admin session.
  - CLI helpers: `bun run api:test:get`, `bun run api:test:ws`, `bun run api:test:nip` (see `scripts/api/README.md`).

## Operations
- Health monitor: periodic connectivity checks; auto‑recreate node on repeated failures; status at `/api/status`.
- Error circuit breaker: `ERROR_CIRCUIT_WINDOW_MS` (default 60000), `ERROR_CIRCUIT_THRESHOLD` (default 10), `ERROR_CIRCUIT_EXIT_CODE` (default 1).
- Headless env management requires auth even with `AUTH_ENABLED=false` (`/api/env*`).

## Security Quick Setup
Production defaults:
```bash
AUTH_ENABLED=true
RATE_LIMIT_ENABLED=true
ALLOWED_ORIGINS=https://yourdomain.example
TRUST_PROXY=true
# Provide ADMIN_SECRET; SESSION_SECRET auto‑generates if absent
```
Data directory hardening (example):
```bash
chmod 700 ./data
chmod 600 ./data/igloo.db ./data/.session-secret 2>/dev/null || true
```

See docs/SECURITY.md for hardening and CSP details.

## Troubleshooting
- UI assets missing/outdated: run `bun run build` to regenerate `static/app.js` and `static/styles.css`.
- UI not updating: prod caches assets; rebuild + restart. Dev disables cache.
- Cred/relay issues: verify `bfgroup1...` / `bfshare1...` and reachable relays.
- More: docs/SECURITY.md (hardening), docs/DEPLOY.md (proxy/cloud), docs/openapi/openapi.yaml (API).

## Development
```bash
bun run dev   # frontend watch
bun run start # server
bun test      # backend tests
```

## Contributing & License
MIT (see LICENSE). PRs welcome—use Conventional Commits and verify: `bun run build`, `bun test`, `bun run docs:validate`.