# 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.