siftlode/docs/deployment-plan.md

# Siftlode — Public Deployment Plan (v1)

Status: **approved (planning)** — 2026-06-13. Goal: share the current Siftlode
build with one trusted tester (both users in Hungary), on safe public
infrastructure, with a clean and trustworthy Google sign-in experience.

This is a planning document. No implementation is started until each phase is
explicitly greenlit.

---

## 1. Confirmed decisions

| Topic | Decision |
|---|---|
| Google verification level | **Production (unverified)** — not full verification for now |
| Sign-in / scopes | **Incremental authorization via an onboarding wizard** (see §2) |
| Hosting | **All on the asgard VPS** (UI + backend + DB) |
| Cloudflare in front | **No** for now (invite-only, unadvertised URL → tiny attack surface) |
| Repo visibility to tester | **Private repo + read access** for the friend |
| Security review timing | **Hybrid**: baseline audit early (folded into Phase A), focused review before publish |

### Why not full verification (yet)
The "Google hasn't verified this app" warning is removed **only** by full
verification (homepage on a verified domain, privacy policy + ToS, app logo,
demo video, scope justification, ~10-day review). For a 2-person test that is
overkill. **Production-unverified** keeps a single one-time click-through
warning per user but removes the painful Testing-mode behaviour (7-day refresh
token expiry → weekly re-login). Full verification stays as an optional later
phase (§6).

Sources: Google "Sensitive scope verification", "Verification requirements"
(support 13464321), "Manage App Audience" (15549945, the 7-day rule),
"Unverified apps" (7454865).

---

## 2. Onboarding wizard — incremental scopes (core design)

**Key insight:** `openid email profile` are **non-sensitive** scopes. An app
that requests only these shows **no unverified warning at all**, and the grant
**does not expire after 7 days even in Testing mode**. The sensitive
`youtube.readonly` (and the optional `youtube` write) are what trigger the
warning.

Therefore:

1. **Base login** requests only `openid email profile` → user signs in with a
   clean, familiar Google screen, no warning, lands in the app.
2. **Onboarding wizard** (first login, also reachable later from settings)
   walks the user through *optional, explained, one-at-a-time* grants:
   - **Step — read access (`youtube.readonly`)**: explains it is needed to read
     your subscriptions and build the feed; pre-warns about the Google
     "unverified app" screen and how to proceed (Advanced → Continue). Button →
     incremental consent. Skippable.
   - **Step — write access (`youtube`)**: optional; needed to unsubscribe from
     within Siftlode; same pre-warning. Button → incremental consent. Skippable.
3. App **degrades gracefully**: no read scope → no feed (UI explains why); no
   write scope → no unsubscribe button.

**Why this design:** the tester consciously grants each permission, with a
rationale, and can revoke on Google's side anytime — the cleanest answer to "I
don't fully trust an AI-written app." It is also Google's recommended
"incremental authorization" / "narrowest scope" best practice, which makes a
future verification submission cleaner.

### Code implications (Phase A)
- `backend/app/auth.py`: split current `READ_SCOPES` into `BASE_SCOPES`
  (`openid email profile`, used at `/auth/login`) and the YouTube scopes
  (granted via incremental upgrade). Reuse/extend the existing `/auth/upgrade`.
- Add `has_read_scope()` alongside `has_write_scope()`.
- Scope-gate the feed/import endpoints; expose `/api/me/scopes` so the frontend
  knows when to show the wizard / which cards to render.
- Frontend: wizard UI + explanatory copy + pre-warning about the Google screen.

---

## 3. Infrastructure — all on asgard

```
User browser ──HTTPS──> Caddy (asgard :443, siftlode.b1fr0st.eu)
                            │  reverse_proxy 127.0.0.1:8080
                            ▼
                   siftlode-api (FastAPI + built SPA, Docker)
                            │  internal docker network only
                            ▼
                   siftlode-db (Postgres 16 — never published)
```

- **DNS**: `porkbun add b1fr0st.eu A siftlode 88.218.78.254` (+ AAAA). Agent-owned
  via `/usr/local/bin/porkbun` on the PVE host.
- **TLS**: Caddy DNS-01 (porkbun plugin), same as forge/pages — auto cert for
  `siftlode.b1fr0st.eu`.
- **Caddy**: new vhost block `siftlode.b1fr0st.eu { reverse_proxy 127.0.0.1:8080 }`
  inheriting the existing security-header set (HSTS, X-Frame-Options, etc.).
- **OAuth redirect URI**: `https://siftlode.b1fr0st.eu/auth/callback` →
  `OAUTH_REDIRECT_URL`. Registered in the Google OAuth client.
- **Stack**: dedicated prod compose at `/srv/siftlode/`; app bound to
  **127.0.0.1:8080 only** (behind Caddy, never a public port); Postgres on the
  internal docker network only (no host port).

### Resource limits (critical on the 3.3 GB box)
- `siftlode-api`: `mem_limit: 768m`, `cpus: 1.0`, `pids_limit: 256`,
  `no-new-privileges`, `cap_drop: ALL`, read-only rootfs + tmpfs `/tmp`,
  non-root user.
- `siftlode-db`: `mem_limit: 512m`, `cpus: 0.75`, tuned
  `shared_buffers`/`work_mem`.

---

## 4. Security — layered defence

Baseline already in place on asgard (from infra notes): UFW (80/443/2222/222
only), fail2ban (sshd + caddy + forgejo, with home-IP DDNS auto-whitelist),
sysctl hardening, Docker daemon hardening (no-new-privileges, userland-proxy
off, icc off, log caps), auditd, key-only SSH, swap.

| Threat | Mitigation |
|---|---|
| **Bot registration spam** | Strongest control already built: invite/allowlist-only. Set `ALLOWED_EMAILS` to exactly the two emails → no open registration; double gate (Google login + email allowlist). Do **not** open registration during the test. |
| **App breach / OAuth token theft** | Tokens already encrypted at rest (Fernet). Strong prod `SECRET_KEY` / `TOKEN_ENCRYPTION_KEY`. Verify session cookie flags (Secure/HttpOnly/SameSite); audit OAuth `state`/CSRF; check SSRF in the YouTube client. |
| **Server kill (resource exhaustion / OOM)** | Container hard-limits above; Caddy per-IP rate limit on `/auth/*` and API; Postgres connection cap. |
| **DDoS** | Honest limit: a small VPS can't absorb a large volumetric DDoS. Realistic layers: Caddy rate-limit + fail2ban on Caddy access log (present). Cloudflare free declined for now (re-evaluate if attacked). |
| **AI-written code flaws** | Dedicated security review of the codebase (§5). |

- **Backups**: extend the existing `asgard-snapshot` timer with a `pg_dump` of
  the siftlode DB (rides the nightly tar.zst; pulled to the home array by
  `pull-asgard-backups`).
- **Monitoring**: Prometheus blackbox probe for `siftlode.b1fr0st.eu` +
  container-up alert, mirroring the Forgejo probes.

---

## 5. Trust-building for the tester

- Minimal default scope (the wizard) → zero YouTube access and zero warning at
  sign-in.
- Private repo **read access** for the friend → he can inspect exactly which
  scopes are requested and what the app does with tokens.
- Permissions granted voluntarily, step by step, with rationale; revocable on
  Google's side anytime (the wizard says so).
- Optional: self-host — the app is fully Dockerized; the friend could run his
  own instance (ultimate trust option; offered, not required).

---

## 6. Deploy pipeline (Forgejo Actions, near one-click)

The runner already runs **on the same asgard host** as the app:

1. Push to a **private Forgejo repo** at `forge.b1fr0st.eu` (Siftlode is
   currently local-git only).
2. **Actions workflow** on tag push: multi-stage Docker build → push to the
   built-in registry (`forge.b1fr0st.eu/peter/siftlode:<tag>`).
3. **Deploy step** in the same workflow: `cd /srv/siftlode && docker compose pull
   && docker compose up -d` (local, since the runner is on asgard); migrations
   run via the entrypoint's `alembic upgrade head`.

Result: `git tag vX && git push --tags` → live in minutes.

---

## 7. Work packages (phased)

**Phase 0 — baseline security audit (do early; fold fixes into Phase A)**
- OAuth flow, token storage, session cookies, secret handling, dependency audit
  (`pip-audit` + `npm audit`), Caddy headers. Since Phase A refactors auth,
  findings here are fixed during that refactor (avoids re-auditing churned code).

**Phase A — required for sharing**
1. Onboarding wizard + scope split (§2): `auth.py` base/incremental scopes,
   `has_read_scope()`, scope-gated endpoints, `/api/me/scopes`, wizard UI + copy.
2. Public **landing/about**, **Privacy Policy**, **Terms of Service** pages
   (reachable without login). Privacy Policy references the YouTube ToS
   (https://www.youtube.com/t/terms) and Google Privacy Policy, includes the
   Limited Use disclosure.
3. Prod config: strong secrets, `OAUTH_REDIRECT_URL`, `ALLOWED_EMAILS` = the two
   emails, set `YOUTUBE_API_KEY` (decouples backfill from user tokens),
   `FRONTEND_ORIGIN` empty in prod.
4. Google Cloud Console: OAuth consent screen (app name, logo, support email,
   authorized domain `b1fr0st.eu`, privacy/ToS/homepage links), declare scopes,
   **Publish app → Production**, verify domain in Search Console (TXT added via
   the porkbun CLI by the agent).
5. Infra: DNS record, Caddy vhost, `/srv/siftlode/` compose stack with limits,
   backup hook, monitoring probe. Forgejo repo + Actions pipeline.

**Phase B — focused security review before publish**
- Review the new/changed code (wizard, new pages) right before the tester gets
  a live token.

**Phase C — optional, later**
- Full Google verification (demo video + scope justification) if the warning
  must be removed entirely or 100+ users are expected.

---

## 8. Open / external steps (need the user or browser)

- Google Cloud Console actions (OAuth client, consent screen, publish, Search
  Console) are behind login — the user clicks them per the agent's instructions,
  or the agent drives via Claude-in-Chrome.
- DNS + asgard-side infra + deploy pipeline are agent-handled.

## Notes / assumptions
- YouTube video playback streams from Google (embedded player), not through our
  server → server bandwidth ≈ SPA bundle (cached) + JSON API; the asgard 5 TB/mo
  cap is a non-issue for 2 users.
- YouTube Data API quota is 10,000 units/day per project (app already manages a
  9,000 budget) — ample for 2 users.