furtka/docs/remote-access.md

# Remote access — user-hosted gateway design

**Status: Draft for review — Daniel/Robert meeting 2026-08-24.**
Supersedes the remote-access paths of [wizard-flow.md](wizard-flow.md) S5/S6
(the NS-delegation / `*.furtka.cloud` design) for v1; the managed-DNS ideas
there move to a later hosted phase (see §9). Builds on Robert's proxy-stack
proposal from 2026-04-18.

---

## 1. Goals & non-goals

**Goal:** a Furtka box owner can reach their apps from anywhere at
`https://jellyfin.example.de` — real Let's Encrypt certificates, no browser
warnings, no port forwarding on the home router, no CGNAT pain — while the
whole chain stays self-hosted end to end (DSGVO/ethos: no central Furtka
service in the traffic path).

The UX bar is the usual one: *dein Vater soll das einrichten können* — with
the one honest caveat that v1 requires renting a cheap VPS and owning a
domain. That caveat is what the later managed phase removes.

**Non-goals for v1 (explicit OUT list):**

- Furtka-operated gateway hosting (managed/multi-tenant *operation*)
- Furtka-run DNS (`ns1/ns2.furtka.org`, NS delegation, DNS-01 wildcards)
- Authentik / SSO / forward-auth (§7 keeps the door open)
- Exposing the Furtka admin UI itself
- Multi-box setups behind one gateway
- Non-HTTP protocols (SMB, MQTT — TCP passthrough is a later Caddy `layer4`
  exercise; SMB never goes on the public internet)
- Road-warrior WireGuard profiles for family devices (the WG server will
  already be there; one obvious future step)
- E-mail/MX anything, metrics dashboards, HA/failover

## 2. Inherited decisions

Decided 2026-08-23/24 (Daniel):

1. **Hybrid trajectory.** v1 is a stack the *user* hosts on their own VPS.
   The same stack must be designed so Furtka could later operate it as a
   hosted offering — multi-tenant *capable* in design (§9), not built.
2. **Bring-your-own domain in v1.** The user points a wildcard A/AAAA record
   at their VPS. No Furtka DNS involvement.
3. Deliverable of this step: this document + the phased plan (§11).

**Relationship to Robert's 2026-04-18 proposal** — the shape survives intact
(user-hosted compose stack on a VPS, WireGuard tunnel, pairing code, per-app
subdomains). Three deliberate changes, argued in this doc:

| Proposal | This design | Why |
|---|---|---|
| Traefik | Caddy (§3) | consistency with the box, On-Demand TLS fits BYO-domain perfectly, Traefik's label-config advantage doesn't apply (apps run on the box, not the VPS) |
| Three components (proxy + WG + web/router glue) | Two: Caddy + `gatewayd` (§3) | the "pairing web page" is a TOFU/phishing trap on a not-yet-certed IP; the VPS console is the correct trust anchor |
| VPS *displays* code on a page, user enters VPS address first | code printed by the install command / `gatewayctl code`; one screen, two fields (domain + code) | fewer round trips, no public pairing page, respects the "max 3 technical things per page" UX rule |

## 3. Architecture

Two deployable sides:

```
 user's VPS (public IP, wildcard DNS)          Furtka box (home LAN, NAT/CGNAT)
┌──────────────────────────────────┐          ┌────────────────────────────────┐
│ furtka-gateway (docker compose)  │          │                                │
│                                  │          │  wg-quick@furtka-gw (client)   │
│  ┌────────┐   admin api  ┌─────┐ │ WireGuard│    10.88.x.y/32                │
│  │ caddy  │◄────/load────│gate-│ │◄═════════│                                │
│  │ :443   │──ask────────►│wayd │ │  tunnel  │  apps publish host ports       │
│  └────────┘              └─────┘ │ (box     │  (jellyfin :8096, HA :8123, …) │
│      │                     │     │  initiates│                               │
│      │ reverse_proxy       │state│  outbound)│  furtka/remote.py             │
│      ▼                     ▼     │          │  /var/lib/furtka/remote.json   │
│  10.88.x.y:8096   state/tenants/ │          │  nftables rules on wg iface    │
└──────────────────────────────────┘          └────────────────────────────────┘
```

- **Caddy** (official image) terminates TLS on `:443`/`:80`. Certificates per
  subdomain via **On-Demand TLS**: no wildcard cert, no DNS-01, no registrar
  API — Caddy mints `jellyfin.example.de` on first request, gated by an `ask`
  endpoint served by gatewayd from the tenant/route state. Unknown hostnames
  are refused *before* ACME fires, which doubles as cert-mint DoS protection.
- **gatewayd** — one small stdlib-only Python service (same zero-dependency
  discipline as `furtka/`): pairing endpoint, route sync, WireGuard peer
  management (`wg` via subprocess, NET_ADMIN), Caddyfile rendering pushed via
  Caddy's admin API (`POST /load`) on the internal compose network. No docker
  socket mount. gatewayd re-pushes config on boot, so a Caddy restart or
  container recreation converges. Ships a `gatewayctl` CLI (`code`, `status`,
  `revoke <tenant>`).
- **Box side**: new `furtka/remote.py` + `furtka remote` CLI + settings card.
  The box is a plain WireGuard *client* (`wg-quick@furtka-gw`) and initiates
  everything — outbound-only, `PersistentKeepalive = 25` — so NAT and CGNAT
  are non-issues and the gateway never needs to reach into the LAN uninvited.

**Data path.** `https://jellyfin.example.de` → VPS Caddy (TLS ends here) →
plain HTTP over the WG tunnel (WG is the encryption layer) →
`<box-wg-ip>:8096`. This works **today** with zero box networking changes:
every web app in the catalog already publishes a host port (it-tools 8080,
home-assistant 8123, jellyfin 8096, uptime-kuma 3001, zigbee2mqtt 8084) — the
missing shared app network (dependency gap #2) does not block remote access
and stays uncoupled. Caddy's `reverse_proxy` handles WebSockets natively
(Home Assistant needs them) and sets `X-Forwarded-For`/`X-Forwarded-Proto`.
Evolution note: once box-side per-app routing exists, the gateway can target
the box's Caddy `:80` with the Host header preserved instead of raw ports —
the route-map schema (§5) does not change.

**Privacy default:** VPS access logs are off or IP-anonymized by default —
cheap to do, and a genuine differentiator for the audience.

## 4. Pairing protocol

**Trust anchor: DNS first, then real TLS.** Pairing requires the wildcard
(or at least `gw.<domain>`) record to be live, because the install command
allowlists `gw.<domain>` immediately — so the box's very first contact is
over a genuine Let's Encrypt certificate. No TOFU, no fingerprint-comparison
ceremony. The pairing code is the second, independent factor: it proves
console access to the VPS *and* cryptographically binds the key exchange.

Code properties: printed by `install.sh` (re-printable via `gatewayctl
code`), one-time, 10-minute TTL, ~48 bits formatted `K7PF-2Q9M-X3RD`,
invalidated after 5 failed attempts, verified in constant time, rate-limited.

```
VPS console                    gatewayd (VPS)                 Furtka box
-----------                    --------------                 ----------
1. user runs install.sh   -->  gen WG server keypair,
   --domain example.de         allowlist gw.example.de,
                               print pairing code C (TTL 10m)
2. user opens Furtka /settings, enters domain "example.de" + code C
                                                     3. resolve gw.example.de,
                                                        gen WG keypair,
                                                        POST https://gw.example.de/v1/pair
                                                        {box_pubkey, box_name,
                                                         mac = HMAC(C, box_pubkey)}
                          4. verify mac with C (one-time,
                             constant-time, rate-limited);
                             mint tenant_id + bearer token;
                             add WG peer; assign tunnel IPs
                          --> 200 {tenant_id, token, gw_pubkey,
                              wg_endpoint, box_ip, gw_ip, domain,
                              mac = HMAC(C, gw_pubkey || box_pubkey)}
                                                     5. verify response mac
                                                        (kills a TLS-MITM key swap);
                                                        write /var/lib/furtka/remote.json (0600)
                                                        + wg config (0600);
                                                        systemctl enable --now wg-quick@furtka-gw
                                                     6. WG handshake (box initiates,
                                                        keepalive 25s — NAT-safe)
                                                     7. PUT /v1/routes (Bearer): full map
                          8. render Caddyfile,
                             POST caddy admin /load
```

- **Re-pair**: new code; replaces the WG peer and revokes the old token.
- **Unpair (box side)**: `DELETE /v1/tenant`, wipe `remote.json`, disable the
  wg unit.
- **Revoke (gateway side, stolen-box case)**: `gatewayctl revoke <tenant>` —
  removes token, peer, and routes.
- **State**: box → `/var/lib/furtka/remote.json`, mode 0600, written with the
  tmp→chmod→replace idiom from `furtka/auth.py:save_users`. VPS → one JSON
  file per tenant (`state/tenants/<id>.json`, atomic replace). Not sqlite:
  n=1 in v1, trivially debuggable and backupable, and it matches the
  file-state idiom used everywhere else in Furtka. sqlite (stdlib anyway) is
  the documented escape hatch if the managed phase needs it.

## 5. Box ↔ gateway API

All endpoints HTTPS on `gw.<domain>`, JSON bodies,
`Authorization: Bearer <token>` except `/v1/pair`. **Only the box ever
initiates; there is no gateway→box API at all.**

| Endpoint | Auth | Purpose |
|---|---|---|
| `POST /v1/pair` | pairing code (HMAC) | key exchange, tenant + token mint |
| `PUT /v1/routes` | Bearer | **full desired-state** route map — idempotent, replay-harmless; gateway rejects `revision` ≤ last applied |
| `GET /v1/status` | Bearer | gateway version, api_version, WG last-handshake, per-route cert state — feeds the settings card |
| `DELETE /v1/tenant` | Bearer | unpair: remove peer, routes, state |

Route map shape:

```json
{
  "revision": 17,
  "routes": [
    {"subdomain": "jellyfin", "port": 8096, "auth": "builtin"},
    {"subdomain": "tools", "port": 8080, "auth": "basic",
     "basic_user": "daniel", "basic_hash": "$2b$..."}
  ]
}
```

Versioning: `/v1/` path prefix; every response echoes `api_version`; the
gateway supports current and current−1; the box refuses to sync against an
unknown major and surfaces "update your gateway" in the settings card.

## 6. Manifest `expose` + per-app UX

New **optional** manifest object; apps without it get no public toggle:

```json
"expose": {
  "subdomain": "jellyfin",
  "port": 8096,
  "auth": "builtin"
}
```

- `subdomain` — default public name, user-overridable in the UI.
- `port` — the *host* port the gateway proxies to over the tunnel. Explicit
  on purpose: `ports` stays informational (its ordering is ambiguous —
  it-tools maps 8080:80, zigbee2mqtt 8084:8080), and `open_url` stays a
  display template, not a routing contract.
- `auth` — `"builtin"` (the app has its own login: jellyfin, home-assistant,
  uptime-kuma) or `"none"` (it-tools).

**Backward compatible by construction**: `furtka/manifest.py` reads known
keys and ignores unknown ones, so old cores parse new catalog manifests
untouched; `expose` is additive and opt-in per app.

**Per-app toggle, default OFF for every app** (DSGVO + attack surface).
Toggling triggers a full `PUT /v1/routes`. Apps with `auth: "none"` get a
hard warning ("Diese App hat keinen eigenen Login — wirklich öffentlich
machen?") plus a one-click gateway **Basic Auth** option: username + bcrypt
hash generated on the box, only the hash ships in the route map.

**`open_url` interaction**: when the box is paired and an app is exposed, the
API rewrites that app's link server-side to `https://<subdomain>.<domain>/`
(around the manifest serialization in `furtka/api.py`, `_manifest_summary`).
This also finally unifies today's divergent client-side substitution
(`furtka/api.py:353` uses `location.hostname`;
`assets/www/index.html:107-118` uses the furtka.json hostname).

## 7. Auth in v1, and the Authentik path

v1 relies on **app-native logins + guardrails**:

1. `auth: "builtin"` apps expose cleanly — their own login is the gate (the
   same posture as every competitor, see [competitors.md](competitors.md)).
2. `auth: "none"` apps require the explicit warning and offer gateway Basic
   Auth (Caddy `basic_auth` directive).

Forward-auth against the box's session auth (`furtka/auth.py`) is **rejected
for v1**: cookie-domain gymnastics across subdomains, a per-request round
trip over the tunnel, and it couples gateway availability to the box API.

**Future-proofing that costs nothing now**: the route-map `auth` field is an
enum `none | basic | forward`. When Authentik (locked in
[wizard-flow.md](wizard-flow.md) as the IdP, still unbuilt) lands on the box,
the gateway receives `forward` routes pointing at a box-side outpost — zero
gateway redesign.

## 8. Threat model

| Asset / scenario | Attacker capability | Mitigation |
|---|---|---|
| MITM at pairing | on-path between box and VPS | DNS-first requirement → real LE TLS at first contact; HMAC-with-code binds *both* WG pubkeys in request and response; code is one-time, 10-min TTL, console-only |
| **Compromised VPS** (the big one — it's a cheap VPS) | TLS plaintext of exposed apps; a WG path toward the LAN | **non-negotiable v1 scope: box-side nftables on the WG interface** — inbound restricted to exactly the exposed ports, no forwarding, peer `AllowedIPs` = gateway /32. Without this, VPS compromise = LAN pivot. (The box has no firewall code today; this feature is where it must grow some.) |
| Stolen/compromised box | valid token + WG key | `gatewayctl revoke <tenant>` kills token, peer, routes from the VPS side |
| Replay | captured pair/sync requests | one-time TTL'd codes; idempotent full-state PUTs with monotonic `revision` |
| Cert-mint DoS | mass requests for random subdomains | On-Demand TLS `ask` allowlist + per-IP rate limit — ACME never fires for unknown names |
| Malicious co-tenant (managed phase) | claims another tenant's hostname | hostname→tenant resolution in `ask`; a tenant's domain is recorded at pairing and cross-tenant claims are refused |
| Exposed app with no login | anyone on the internet | default-OFF toggles; `auth:none` warning; Basic Auth option |

## 9. Multi-tenant-capable design constraints

Baked in from day one (cheap now, expensive to retrofit):

- `tenant_id` on all gateway state and log lines; bearer token per tenant
- WG tunnel IPs allocated from a pool (`10.88.0.0/16`, one /32 per box)
- `ask` endpoint resolves hostname→tenant and refuses cross-tenant claims
- versioned `/v1/` API; structured JSON logs
- rate-limit configuration *shaped* per-tenant (v1 values are global)

Explicitly **not** built in v1: tenant provisioning UI, billing, Furtka-run
DNS/NS delegation, per-tenant network namespaces, HA/failover, metrics
endpoint. The managed offering later is "Furtka operates this same stack +
the DNS story from wizard-flow.md S5" — not a second codebase.

## 10. Repos, artifacts, box-side changes

**New Forgejo repo `daniel/furtka-gateway`:**

```
docker-compose.yml     # official caddy image + gatewayd image
gatewayd/              # stdlib-only Python 3 (~500 lines), Dockerfile
install.sh             # --domain example.de; prints pairing code
docs/
```

- Releases: CalVer + sha256 sidecar + release.json, Forgejo Actions on the
  self-hosted runner — cloned from `scripts/build-release-tarball.sh` /
  `scripts/publish-release.sh` / the `furtka/_release_common.py` shape.
- Install UX: `curl -fsSL https://…/install.sh | bash -s -- --domain
  example.de`, with the paranoid path (download, read, verify sha256, run)
  documented right next to it.
- gatewayd tests follow the `tests/test_https.py` style: inject paths and a
  fake subprocess/reload via kwargs.

**Box side (core repo):**

- `furtka/remote.py` — pattern donors: `furtka/https.py` (atomic write +
  reload + rollback, error class contract), `furtka/catalog.py` +
  `furtka/_release_common.py` (HTTP, state JSON), `furtka/paths.py` accessor
  for `remote.json`
- `furtka remote pair|status|sync|unpair` in `furtka/cli.py`
- `_do_remote_*` handlers + dispatch lines in `furtka/api.py` (same shape as
  the HTTPS pair at `api.py:1032/1039`)
- settings card "Remote access" (replaces the dead `furtka.org/#planned`
  links — 10 occurrences across `assets/www/`)
- `wireguard-tools` added to the archinstall package list
  (`webinstaller/app.py` `packages`, ~line 453) and the wg-quick unit wired
  via `_FURTKA_UNITS` (`webinstaller/app.py:261`); upgraded boxes get it via
  `updater._link_new_units`
- nftables rules on the WG interface (see §8)

**Subdomain scheme**: `app.domain.tld` in v1; `gw.<domain>` reserved for the
gateway itself. Route-sync rejects reserved names: `gw`, `furtka`, `www`,
`mail`, `autoconfig`, `autodiscover`, `_acme-challenge`. Multi-box later:
`app.<boxname>.domain.tld` — reserved here, zero code now. The Furtka admin
UI is not exposed in v1; `furtka.<domain>` stays reserved for a later opt-in
once a stronger auth story exists.

## 11. Phased plan

- **P0 — this document.** Review in the 2026-08-24 meeting, merge.
- **P1 — tracer bullet (1–2 days, demo-able).** No product code: a scratch
  compose file on a **clean** test VPS + a test domain with wildcard A record
  + a Furtka VM from the current ISO. Manual WG configs both ends, static
  Caddyfile with On-Demand TLS and hardcoded routes to jellyfin/HA. Validates
  the three real risks before any pairing code exists: on-demand LE issuance
  under BYO domain, WebSockets through the whole chain, tunnel latency/MTU.
  Demo: `https://jellyfin.<testdomain>` on a phone on LTE.
- **P2 — gatewayd v1** (furtka-gateway repo): pairing, routes PUT, tenant
  state, WG peer mgmt, Caddyfile render + admin-API push, `ask`, gatewayctl,
  install.sh, tests, release pipeline. Validation: pair via `curl` by hand
  from the P1 VM; kill/restart containers, confirm state re-render.
- **P3 — box client** (core): `furtka/remote.py`, CLI verbs, API handlers,
  wg-quick unit, nftables rules, ISO packages. Validation: fresh ISO install
  → `furtka remote pair example.de K7PF-…` → tunnel up, `furtka remote
  status` green, port scan **from the VPS** confirms the firewall.
- **P4 — `expose` + route sync** (furtka-apps + core): `expose` for
  jellyfin, home-assistant, uptime-kuma, it-tools (`auth:none`); manifest
  parsing; sync hooks on install/uninstall/toggle; server-side `open_url`
  rewrite. Validation: toggle → live in <5 s; uninstall → route gone; old
  core parses new catalog (backward-compat test).
- **P5 — UI + docs** (core): settings card, pairing form, per-app toggles +
  warning modal, user guide, wizard-flow.md revision, website/README.
  Validation: the full dad test — clean ISO → pair → toggle → phone on LTE,
  without ever opening a terminal on the box.
- **P6 — later, unscoped**: Authentik + `forward` auth, managed multi-tenant
  operation, TCP passthrough (MQTT), multi-box, family WG profiles.

## 12. Open questions (decide with Robert)

1. **Reserved name**: `gw.<domain>` vs `furtka-gw.<domain>` — and whether
   the admin UI (`furtka.<domain>`) should *ever* be exposable.
2. **Gateway Basic Auth**: in v1 or cut to shrink scope? (Lean: **in** —
   ~20 lines, and it's the only guardrail for it-tools-class apps.)
3. **Install UX**: `curl | bash` one-liner vs documented 3-step install.
4. **German UI wording** ("Fernzugriff"? "Sicherer Zugang von unterwegs"?)
   and wizard scope: redesign S5/S6 now, or ship settings-page-first and
   revise the (still unimplemented) wizard afterwards? (Lean:
   settings-first.)