NextMyDay/docs/deploy-zoraxy.md

# Deploying MyDay behind Zoraxy

> **Status:** the reference deployment for **D-043**. The app is never the TLS
> endpoint; **[Zoraxy](https://github.com/tobychui/zoraxy) terminates TLS** and
> relays plain HTTP to the app. This document is operator-facing — it changes no
> code. The decision of record is `PROJECT_PLAN.md` **D-043** / **D-025 (revised)**;
> the gate's behaviour is `docs/specs/spec-003-core-door.md` **§7**.

---

## 1. Topology

```
browser ──https──▶ Zoraxy  10.1.0.10  ──http──▶ app  0.0.0.0:8080
        (TLS public)   terminates TLS              (plain HTTP, trusted proxy)
                       sets X-Forwarded-For
                       + X-Forwarded-Proto
```

- **Zoraxy** — `10.1.0.10`, holds the certificate for `myday.sechpoint.app`,
  terminates TLS, and forwards to the app over plain HTTP.
- **App** — listens on `0.0.0.0:8080` over **HTTP** (`server.listen`). Because the
  app is not the TLS endpoint it must **honour the proxy's `X-Forwarded-Proto`** to
  know a request arrived over `https` (that is what turns on the `Secure` +
  `__Host-` session cookie and HSTS).
- **Firewall** — `:8080` is reachable **only from `10.1.0.10`** (see §4). The port
  is the app's whole attack surface: anything that can reach it bypasses both
  Zoraxy **and its TLS**.

---

## 2. The app config (`config.yaml`)

Copy `config.example.yaml` → `config.yaml` (gitignored — **never commit it**, D-010)
and set the three server keys:

```yaml
server:
  listen: "0.0.0.0:8080"
  base_url: "https://myday.sechpoint.app"   # the PUBLIC origin (invite / recovery links)
  trusted_proxies:
    - "10.1.0.10"                            # Zoraxy
```

- **`listen`** — any bind is allowed (there is **no** setup-mode bind refusal,
  D-025 revised). Bind `0.0.0.0:8080`; the firewall narrows who can reach it.
- **`base_url`** — the public origin. It is the host the browser actually visits,
  so it must be `https://` (WebAuthn derives its Relying Party ID from it).
- **`trusted_proxies`** — the peers whose `X-Forwarded-For` / `X-Forwarded-Proto`
  are honoured (A6/D-043).

> **It must be the address Zoraxy connects *from*, not the public hostname.**
> `trusted_proxies` matches the **TCP peer** of the app's connection. With Zoraxy
> on `10.1.0.10`, that peer is `10.1.0.10`. (If Zoraxy ran on the *same* host you
> would use `127.0.0.1` instead — that is the only case where loopback is right.)

---

## 3. The Zoraxy ProxyHost

Create a **Proxy Host** (reverse proxy rule) in Zoraxy:

| Field | Value |
|---|---|
| Domain / hostname | `myday.sechpoint.app` |
| TLS | on (Zoraxy's certificate for that host) |
| Upstream / target | `http://<app-host>:8080` (plain HTTP) |
| `X-Forwarded-For` | **set / forwarded** |
| `X-Forwarded-Proto` | **set / forwarded** (`https`) |

Zoraxy sets `X-Forwarded-For` on a normal HTTP proxy rule; confirm it **and**
`X-Forwarded-Proto` in the rule's header settings, then verify end-to-end (§7).
The app deliberately **requires** both:

- `X-Forwarded-Proto: https` is what makes the session cookie `Secure`
  (`__Host-myday_session`) and adds HSTS (AC-13).
- The **absence of `X-Forwarded-For`** is the proof the setup gate uses that a
  request is the direct SSH tunnel, not a proxy relay (§6, D-025 revised).

---

## 4. Firewall — lock `:8080` to Zoraxy

Allow `:8080/tcp` **only** from `10.1.0.10`.

**ufw:**

```bash
ufw allow from 10.1.0.10 to any port 8080 proto tcp
# the default incoming policy (deny) drops every other source
```

**nftables:**

```nft
table inet myday_guard {
  chain input {
    type filter hook input priority filter; policy accept;
    tcp dport 8080 ip saddr != 10.1.0.10 drop
  }
}
```

> If you run a host firewall, this rule is the load-bearing one: without it the
> app's plain-HTTP port is directly reachable and its TLS hardening (cookie
> `Secure`, HSTS, the tunnel gate) is bypassed.

---

## 5. Tunnel-only bootstrap (before the first admin exists)

The **first user becomes the top admin**, so the initial `/setup` wizard is served
**only over a direct SSH tunnel** — never through the proxy. This is enforced
**per request** (D-025 revised / SPEC-003 §7): in setup mode the app serves a
request **only** if its **TCP peer is loopback *and* it carries no
`X-Forwarded-For`** — i.e. the tunnel. Everything else is **404**.

```bash
# from your workstation — tunnel to the app's loopback port on the server
ssh -L 8080:127.0.0.1:8080 <user>@<app-host>
# then, in a browser on your workstation:
#   http://127.0.0.1:8080/setup
```

- Open the app over **`localhost` / `127.0.0.1`** — a loopback origin is the only
  one the browser treats as a secure context for **WebAuthn** dialogs.
- The wizard creates the top admin (**Passkey + TOTP**; the TOTP secret is sealed
  with the generated `totp_encryption_key`) and writes `config.yaml`
  (`setup: false`, the base URL, mail/locale, and the secrets).
- A proxy **cannot** reach a fresh instance: even a same-host proxy presents a
  loopback peer but always adds `X-Forwarded-For`, which gives it away → 404.

### The restart — adopting the persisted secrets

The **secrets are generated at startup** while any value is still `CHANGE_ME…`
(so the wizard's ceremony is never signed with a shipped, public key). The wizard
then **persists those same values** into `config.yaml`. So once setup is complete:

```bash
sudo systemctl restart myday
```

The restart **adopts the written `config.yaml`** — the generated keys are now on
disk, so the admin's TOTP secret (sealed with that key) keeps working. **Boot the
productive instance from the written `config.yaml`, never from
`config.example.yaml`** (its placeholders fail closed in productive mode by
design). After the restart, `/setup` is **404** and the app serves normally.

---

## 6. systemd

Build, install the unit, and start it. The unit is
[`deploy/myday.service`](../deploy/myday.service) — replace every `<PLACEHOLDER>`:

```bash
# 1. build the static, CGO-free binary
go build -trimpath -o /usr/local/bin/myday ./cmd/myday

# 2. the app dir holds config.yaml and data/ (SQLite)
install -d -o <myday-user> -g <myday-group> /opt/myday
install -m 0640 -o <myday-user> -g <myday-group> config.yaml /opt/myday/config.yaml

# 3. the unit
install -m 0644 deploy/myday.service /etc/systemd/system/myday.service
systemctl daemon-reload
systemctl enable --now myday
journalctl -u myday -f
```

The unit sets `WorkingDirectory=` to the app dir (where `config.yaml` and `data/`
live), `User=`, `ExecStart=<binary>`, and `After=network-online.target`; see the
file's header comment for the placeholders.

---

## 7. Verify, and the misconfig warnings

```bash
# from anywhere — the public origin
curl -sI https://myday.sechpoint.app/ | grep -i '^strict-transport-security'
# expect: Strict-Transport-Security: max-age=…   (HSTS — proves X-Forwarded-Proto was honoured)
```

| Symptom | Cause | Fix |
|---|---|---|
| Session cookie has **no `Secure`**, **no `__Host-`** prefix, and **no HSTS** | `trusted_proxies` is **empty or wrong**, so `X-Forwarded-Proto` is ignored (fails *silently*) | Set `server.trusted_proxies: ["10.1.0.10"]` and restart |
| Client IP in the audit log is the **proxy**, not the user | same — `X-Forwarded-For` is not trusted | as above |
| `/` and `/home` return **404** while bootstrapping | **by design** — in setup mode only `/setup` (and static assets) is served | complete the wizard; the app serves normally once productive |
| `/setup` returns **404** even via the proxy | **by design** — the gate is tunnel-only | bootstrap over the SSH tunnel (§5), *then* expose it |

> **The load-bearing deployment requirement:** Zoraxy **must set
> `X-Forwarded-For`**. The setup gate's "no XFF ⇒ it's the tunnel" test depends on
> it, and a missing header would re-open first-visitor-wins. `X-Forwarded-Proto`
> is what keeps the cookie `Secure` over the proxy.

---

## See also

| | |
|---|---|
| [`PROJECT_PLAN.md`](../PROJECT_PLAN.md) | D-043 · D-025 (revised) |
| [`docs/specs/spec-003-core-door.md`](specs/spec-003-core-door.md) | §7 the loopback/setup gate · §9 AC-7 / AC-10 / AC-13 |
| [`config.example.yaml`](../config.example.yaml) | the commented config template |
| [`deploy/myday.service`](../deploy/myday.service) | the systemd unit |