225 lines
7.4 KiB
Markdown
225 lines
7.4 KiB
Markdown
# GreenCoast
|
||
|
||
A privacy-first, shardable social backend + minimalist client. **Zero PII**, **zero passwords**, optional **E2EE per post**, and **public-key accounts**. Includes **DPoP-style proof-of-possession**, **Discord SSO with PKCE**, and a tiny static client.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **Zero-trust by design**: server stores no emails or passwords.
|
||
- **Accounts = public keys** (Ed25519 or P-256). No usernames required.
|
||
- **Proof-of-possession (PoP)** on every authenticated API call.
|
||
- **Short-lived tokens** (HMAC “gc2”) bound to device keys.
|
||
- **Shardable storage** (mTLS or signed shard requests).
|
||
- **No fingerprinting**: no IP/UA logs; coarse timestamps optional.
|
||
- **Static client** with strong CSP; optional E2EE per post.
|
||
- **Discord SSO (PKCE)** as an *optional* convenience.
|
||
- **Filesystem storage** supports both **flat** and **nested** object layouts.
|
||
|
||
---
|
||
|
||
## Architecture (brief)
|
||
|
||
- **Shard**: stateless API + local FS object store + in-memory index.
|
||
- **Client**: static files (HTML/JS/CSS) served by the shard or any static host.
|
||
- **Identity**: device key (P-256/Ed25519) or passkey; server mints short-lived **gc2** tokens bound to the device key (`cnf` claim).
|
||
- **Privacy**: objects can be plaintext (public) or client-encrypted (private).
|
||
|
||
---
|
||
|
||
## Security posture
|
||
|
||
- **Zero-trust**: no passwords/emails; optional SSO is *linking*, not source-of-truth.
|
||
- **DPoP-style PoP** on requests:
|
||
- Client sends:
|
||
- `Authorization: Bearer gc2.…`
|
||
- `X-GC-Key: p256:<base64-raw>` (or `ed25519:…`)
|
||
- `X-GC-TS: <unix seconds>`
|
||
- `X-GC-Proof: sig( METHOD "\n" URL "\n" TS "\n" SHA256(body) )`
|
||
- Server verifies `gc2` signature, key binding (`cnf`), timestamp window, and replay cache.
|
||
- **Replay protection**: 10-minute proof cache.
|
||
- **No fingerprinting/logging**: no IPs, no UAs.
|
||
- **Strict CSP** for client: blocks XSS/token theft.
|
||
- **Limits**: request body limits (default 10 MiB), simple per-account rate limiting.
|
||
- **Shard↔shard**: mTLS or per-shard signatures with timestamp + replay cache.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- Go 1.21+
|
||
- Docker (optional)
|
||
- A signing key for tokens: `GC_SIGNING_SECRET_HEX` (32+ bytes hex)
|
||
- (Optional) Discord OAuth app (Client ID/Secret + redirect URI)
|
||
- (Optional) Cloudflare Tunnel or other TLS reverse proxy
|
||
|
||
---
|
||
|
||
## Environment variables
|
||
|
||
GC_HTTP_ADDR=:9080
|
||
GC_HTTPS_ADDR= # optional
|
||
GC_TLS_CERT= # optional
|
||
GC_TLS_KEY= # optional
|
||
|
||
GC_STATIC_ADDR=:9082
|
||
GC_STATIC_DIR=/opt/greencoast/client
|
||
|
||
GC_DATA_DIR=/var/lib/greencoast
|
||
GC_ZERO_TRUST=true
|
||
GC_COARSE_TS=false
|
||
|
||
GC_SIGNING_SECRET_HEX=<64+ hex chars> # required for gc2 tokens
|
||
GC_REQUIRE_POP=true # default true; set false for first-run
|
||
|
||
# Dev convenience (testing only; disable for production)
|
||
GC_DEV_ALLOW_UNAUTH=false
|
||
GC_DEV_BEARER=
|
||
|
||
# Discord SSO (optional)
|
||
GC_DISCORD_CLIENT_ID=
|
||
GC_DISCORD_CLIENT_SECRET=
|
||
GC_DISCORD_REDIRECT_URI=https://greencoast.example.com/auth-callback.html
|
||
|
||
---
|
||
|
||
## Quickstart (Docker)
|
||
|
||
Minimal compose for local testing (PoP disabled + dev unauth allowed for first run):
|
||
|
||
services:
|
||
shard-test:
|
||
build: .
|
||
environment:
|
||
- GC_HTTP_ADDR=:9080
|
||
- GC_STATIC_ADDR=:9082
|
||
- GC_STATIC_DIR=/opt/greencoast/client
|
||
- GC_DATA_DIR=/var/lib/greencoast
|
||
- GC_ZERO_TRUST=true
|
||
- GC_SIGNING_SECRET_HEX=7f6e1a0f2b4d7e3a... # replace with your secret
|
||
- GC_REQUIRE_POP=false # easier first-run
|
||
- GC_DEV_ALLOW_UNAUTH=true
|
||
volumes:
|
||
- ./testdata:/var/lib/greencoast
|
||
- ./client:/opt/greencoast/client:ro
|
||
ports:
|
||
- "9080:9080"
|
||
- "9082:9082"
|
||
|
||
Open `http://localhost:9082` → set the Shard URL (`http://localhost:9080`) → publish a test post.
|
||
|
||
When ready, **turn PoP on** by removing `GC_REQUIRE_POP=false` and disabling `GC_DEV_ALLOW_UNAUTH`.
|
||
|
||
---
|
||
|
||
## Cloudflare Tunnel example
|
||
|
||
ingress:
|
||
- hostname: greencoast.example.com
|
||
service: http://shard-test:9082
|
||
- hostname: api-gc.greencoast.example.com
|
||
service: http://shard-test:9080
|
||
- service: http_status:404
|
||
|
||
Use “Full (strict)” TLS and ensure your cert covers both hosts.
|
||
|
||
---
|
||
|
||
## Client usage
|
||
|
||
- **Shard URL**: set it in the top “Connect” section (or use `?api=` query or `<meta name="gc-api-base">`).
|
||
- **Device key sign-in (no OAuth)**:
|
||
1) Client generates/stores a P-256 device key in the browser.
|
||
2) Client calls `/v1/auth/key/challenge` then `/v1/auth/key/verify` to obtain a **gc2** token bound to that key.
|
||
- **Discord SSO (optional)**:
|
||
- Requires `GC_DISCORD_CLIENT_*` env vars and a valid `GC_DISCORD_REDIRECT_URI`.
|
||
- Uses PKCE (`S256`) and binds the minted **gc2** token to the device key presented at `/start`.
|
||
|
||
---
|
||
|
||
## API (overview)
|
||
|
||
- `GET /healthz` – liveness
|
||
- `PUT /v1/object` – upload blob (headers: optional `X-GC-Private: 1`, `X-GC-TZ`)
|
||
- `GET /v1/object/{hash}` – download blob
|
||
- `DELETE /v1/object/{hash}` – delete blob
|
||
- `GET /v1/index` – list indexed entries (latest first)
|
||
- `GET /v1/index/stream` – SSE updates
|
||
- `POST /v1/admin/reindex` – rebuild index from disk
|
||
- **Auth**
|
||
- `POST /v1/auth/key/challenge` → `{nonce, exp}`
|
||
- `POST /v1/auth/key/verify` `{nonce, alg, pub, sig}` → `{bearer, sub, exp}`
|
||
- `POST /v1/auth/discord/start` (requires `X-GC-3P-Assent: 1` and `X-GC-Key`)
|
||
- `GET /v1/auth/discord/callback` → redirects with `#bearer=…`
|
||
- **GDPR**
|
||
- `GET /v1/gdpr/policy` – current data-handling posture
|
||
|
||
> When `GC_REQUIRE_POP=true`, all authenticated endpoints require PoP headers.
|
||
|
||
### PoP header format (pseudocode)
|
||
|
||
Authorization: Bearer gc2.<claims>.<sig>
|
||
X-GC-Key: p256:<base64-raw> # or ed25519:<base64-raw>
|
||
X-GC-TS: <unix seconds>
|
||
X-GC-Proof: base64(
|
||
Sign_device_key(
|
||
UPPER(METHOD) + "\n" + URL + "\n" + X-GC-TS + "\n" + SHA256(body)
|
||
)
|
||
)
|
||
|
||
---
|
||
|
||
## Storage layout & migration
|
||
|
||
- **Writes** are flat: `objects/<hash>`
|
||
- **Reads** (and reindex) also support:
|
||
- `objects/<hash>/blob|data|content`
|
||
- `objects/<hash>/<single file>`
|
||
- `objects/<prefix>/<hash>` (two-level prefix)
|
||
- To **restore** data into a fresh container:
|
||
1) Mount your objects at `/var/lib/greencoast/objects`
|
||
2) Call `POST /v1/admin/reindex` (with auth+PoP or enable dev unauth briefly)
|
||
|
||
---
|
||
|
||
## Reindex examples
|
||
|
||
Unauth (dev only):
|
||
|
||
curl -X POST https://api-gc.yourdomain/v1/admin/reindex
|
||
|
||
With bearer + PoP (placeholders):
|
||
|
||
curl -X POST https://api-gc.yourdomain/v1/admin/reindex ^
|
||
-H "Authorization: Bearer <gc2_token>" ^
|
||
-H "X-GC-Key: p256:<base64raw>" ^
|
||
-H "X-GC-TS: <unix>" ^
|
||
-H "X-GC-Proof: <base64sig>"
|
||
|
||
---
|
||
|
||
## Hardening checklist (prod)
|
||
|
||
- Set `GC_REQUIRE_POP=true`, remove dev bypass.
|
||
- Keep access token TTL ≤ 8h; rotate signing key periodically.
|
||
- Static client served with strong CSP (already enabled).
|
||
- Containers run non-root, read-only FS, `no-new-privileges`, `cap_drop: ["ALL"]`.
|
||
- Edge WAF/rate limits; 10 MiB default request cap (tunable).
|
||
- Commit `go.sum`; run `go mod verify` in CI.
|
||
|
||
---
|
||
|
||
## GDPR
|
||
|
||
- Server stores **no PII** (no emails, no IP/UA logs).
|
||
- Timestamps are UTC (or coarse UTC if enabled).
|
||
- `/v1/gdpr/policy` exposes current posture.
|
||
- Roadmap: `/v1/gdpr/export` and `/v1/gdpr/delete` to enumerate/remove blobs signed by a given key.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is licensed under **The Unlicense**. See `LICENSE` for details.
|
||
|