From 3e48b0d848b4633f0ca507b367cfb65dc1b70261 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 22:38:40 +0200 Subject: [PATCH] =?UTF-8?q?chore(workspace):=20DEV=20least-privilege=20exp?= =?UTF-8?q?osure=20=E2=80=94=20nginx=20DEV=20gateway=20(API=20on=20the=20L?= =?UTF-8?q?AN,=20Mailpit=20behind=20basic=20auth),=20network=20check=20fro?= =?UTF-8?q?m=20a=20distinct=20origin,=20loopback=20default=20for=20the=20r?= =?UTF-8?q?ootless=20daemon=20documented?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Supabase CLI publishes 54321-54324 on every interface with no bind option. Design: the rootless daemon binds published ports on loopback by default (~/.config/docker/daemon.json {"ip":"127.0.0.1"}, owner action, not applied), and the DEV gateway (Compose service dev-gateway, profile dev, container faunosteo_dev_gateway) re-publishes only the API (Kong) and Mailpit behind HTTP basic auth on FAUNOSTEO_DEV_HOST; Studio and PostgreSQL stay loopback (SSH tunnel for Studio). pnpm dev:gateway generates the Mailpit credentials (gitignored; htpasswd 644 because the rootless container user cannot read a 600 file, hash only). pnpm dev:net-check probes from a throwaway container on its own Docker network: app, API health, REST 401, Mailpit 401/200, PostgreSQL and Studio closed. Gateway proven on alternate ports (health 200, password login 200, Mailpit 401 / 200). --- .dockerignore | 2 + .gitignore | 4 ++ CLAUDE.md | 10 +++- docker-compose.yml | 21 +++++++ docker/dev-gateway/nginx.conf | 46 +++++++++++++++ docs/development/ENVIRONMENTS.md | 97 ++++++++++++++++++++++---------- docs/development/SUPABASE.md | 7 ++- docs/development/WORKSPACE.md | 2 + package.json | 3 + scripts/dev-gateway.sh | 36 ++++++++++++ scripts/dev-net-check.sh | 54 ++++++++++++++++++ 11 files changed, 246 insertions(+), 36 deletions(-) create mode 100644 docker/dev-gateway/nginx.conf create mode 100755 scripts/dev-gateway.sh create mode 100755 scripts/dev-net-check.sh diff --git a/.dockerignore b/.dockerignore index c13f94eb..e32191b5 100644 --- a/.dockerignore +++ b/.dockerignore @@ -20,3 +20,5 @@ docs/ logos/ target/ packages/core-wasm/pkg/ +docker/dev-gateway/htpasswd +docker/dev-gateway/mailpit-password diff --git a/.gitignore b/.gitignore index 4bd836e4..837d4870 100644 --- a/.gitignore +++ b/.gitignore @@ -63,3 +63,7 @@ supabase/.temp/ # Rust workspace (R0): build output and the generated browser module target/ packages/core-wasm/pkg/ + +# DEV gateway credentials (generated by scripts/dev-gateway.sh) +docker/dev-gateway/htpasswd +docker/dev-gateway/mailpit-password diff --git a/CLAUDE.md b/CLAUDE.md index 5ca48313..806029c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,6 +76,8 @@ below runs from the repository root and delegates to the packages. # Development (DEV origin = this machine's LAN address, scripts/dev-env.sh; tests run from other devices) pnpm dev # Vite on http://:5173 wired to the local stack (needs pnpm db:start) pnpm dev:offline # the local tool without backend +pnpm dev:gateway # LAN entry: API :54321 + Mailpit :54324 (basic auth) on FAUNOSTEO_DEV_HOST; dev:gateway:stop +pnpm dev:net-check # allowed / refused probes from a distinct Docker network # Production build (typecheck + vite build) pnpm build @@ -443,9 +445,11 @@ Database (Supabase) (app, Supabase API, Mailpit, Studio) is addressed by the DEV origin (`scripts/dev-env.sh`, `FAUNOSTEO_DEV_HOST`), never by `127.0.0.1` / `localhost`, never hard-coded in a source. The Supabase CLI runs only through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase`): config.toml reads the origin with `env()`. -- Exposure: 5173 and 54321 are what a remote browser needs; Studio 54323 and Mailpit 54324 are unauthenticated - admin tools for the private subnet only; PostgreSQL 54322 should not be reachable from the LAN (firewall = - owner decision); the worker publishes no port. Nothing is exposed to the Internet; no production infrastructure +- Exposure (least privilege, `pnpm dev:net-check`): the rootless daemon binds published ports on loopback + (`~/.config/docker/daemon.json` `{"ip":"127.0.0.1"}`); the DEV gateway (`pnpm dev:gateway`, nginx, + `faunosteo_dev_gateway`) re-publishes only the API (54321) and Mailpit behind basic auth (54324) on the LAN + address; Vite 5173 on all interfaces; Studio 54323 and PostgreSQL 54322 loopback only (SSH tunnel for + Studio); the worker publishes no port. Nothing is exposed to the Internet; no production infrastructure is touched from this repository. Rust is built natively; Docker runs services, the worker, sandbox tests and images. ### Files and Storage (migration 20261013100000, docs/development/STORAGE.md) diff --git a/docker-compose.yml b/docker-compose.yml index f834e181..7caeca9d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -40,6 +40,27 @@ services: - supabase restart: unless-stopped + # DEV gateway (docs/development/ENVIRONMENTS.md §3): with the rootless daemon binding + # published ports on loopback by default, this is the only entry of the private + # network into the stack: the Supabase API on :54321 and Mailpit behind + # basic auth on :54324. Started by `pnpm dev:gateway` (profile `dev`), + # which exports FAUNOSTEO_DEV_HOST and generates docker/dev-gateway/htpasswd. + dev-gateway: + container_name: faunosteo_dev_gateway + profiles: ["dev"] + image: nginx:1.31-alpine + volumes: + - ./docker/dev-gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro + - ./docker/dev-gateway/htpasswd:/etc/nginx/htpasswd:ro + ports: + - "${FAUNOSTEO_DEV_HOST:-127.0.0.1}:54321:54321" + - "${FAUNOSTEO_DEV_HOST:-127.0.0.1}:54324:54324" + security_opt: + - no-new-privileges:true + networks: + - supabase + restart: unless-stopped + networks: supabase: external: true diff --git a/docker/dev-gateway/nginx.conf b/docker/dev-gateway/nginx.conf new file mode 100644 index 00000000..1edd75d8 --- /dev/null +++ b/docker/dev-gateway/nginx.conf @@ -0,0 +1,46 @@ +# DEV gateway (docs/development/ENVIRONMENTS.md §3): the only two Supabase surfaces +# re-published on the private network once the rootless Docker daemon binds published +# ports on loopback by default. Upstreams are resolved through Docker's DNS on every +# request (variables + resolver) so a restarted stack is followed without a restart here. +resolver 127.0.0.11 valid=10s ipv6=off; + +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +# Supabase API (Kong: Auth, PostgREST, Storage) for the browsers of the LAN. +server { + listen 54321; + server_name _; + client_max_body_size 16m; # avatar uploads are capped at 5 MiB by the bucket + location / { + set $kong http://supabase_kong_faunosteo:8000; + proxy_pass $kong; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_request_buffering off; + proxy_read_timeout 120s; + } +} + +# Mailpit (DEV mails: confirmation and recovery links) behind HTTP basic auth. +server { + listen 54324; + server_name _; + auth_basic "Faunosteo DEV mail"; + auth_basic_user_file /etc/nginx/htpasswd; + location / { + set $mailpit http://supabase_inbucket_faunosteo:8025; + proxy_pass $mailpit; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_read_timeout 3600s; + } +} diff --git a/docs/development/ENVIRONMENTS.md b/docs/development/ENVIRONMENTS.md index d256be81..a726e353 100644 --- a/docs/development/ENVIRONMENTS.md +++ b/docs/development/ENVIRONMENTS.md @@ -54,41 +54,76 @@ into confirmation and recovery mails), `auth.site_url`, `studio.api_url`; (`192.168.*.*`, `10.*.*.*`, `172.16.*.*`) plus the host-only forms, so PKCE links return to the origin the browser used. -## 3. What listens where (DEV, measured 2026-10-13) +## 3. Exposure on the private network: least privilege -The Supabase CLI publishes its ports on every interface (`0.0.0.0`, no bind -option); Vite listens on every interface (`server.host: true`). +Target (owner decision 2026-10-13): the browser surfaces are reachable from +the LAN, the administration tools and the database are not. -| Service | Port | Interface | Needed by the remote browser | Protection | -|---|---|---|---|---| -| Application (Vite) | 5173 | all | yes | none (dev build, anon key only) | -| Supabase API (Kong: Auth, PostgREST, Storage) | 54321 | all | yes | RLS, policies, the anon key; the service key never reaches a browser | -| Studio | 54323 | all | useful for inspection, not for the flows | **none**: full database access to anyone on the LAN | -| Mailpit | 54324 | all | yes for sign-up and recovery mails | **none**: every DEV mail readable on the LAN | -| PostgreSQL | 54322 | all | no | password `postgres`: **should not be reachable from the LAN** | -| Worker | none | — | no | internal only (Supabase compose network, read-only, no capability) | -| PostgREST, GoTrue, Storage, pg-meta | none | — | behind Kong | — | +| Service | Port | LAN | How it is enforced | +|---|---|---|---| +| Application (Vite) | 5173 | open | Vite listens on every interface (`server.host: true`); dev build, anon key only | +| Supabase API (Kong: Auth, PostgREST, Storage) | 54321 | open | the DEV gateway re-publishes it on `:54321`; RLS, policies and the anon key protect the data; the service key never reaches a browser | +| Mailpit (DEV mails) | 54324 | open **with credentials** | the DEV gateway re-publishes it behind HTTP basic auth (user `dev`, generated password in `docker/dev-gateway/mailpit-password`, never committed) | +| Studio | 54323 | **closed** | loopback only; from another device: SSH tunnel (below) | +| PostgreSQL | 54322 | **closed** | loopback only; tests and the CLI use `127.0.0.1:54322` on the host | +| Worker | none | — | internal, Supabase compose network, read-only, no capability | +| PostgREST, GoTrue, Storage, pg-meta | none | — | behind Kong | -The firewall state of the host could not be read without privileges. The -proposal for the owner (not applied): a host firewall keeping 54322 on -loopback only, and 54323 / 54324 restricted to the private subnet -(`192.168.1.0/24`); 5173 and 54321 open to that subnet. Nothing is exposed to -the Internet by this repository; the box, the router and any public -forwarding stay untouched. +### 3.1 Mechanism (no privileges, no firewall) -HTTP on a private address: the auth flows (PKCE, cookies-free session in -localStorage) work; what does not is any browser feature that needs a -secure context on a non-loopback origin (camera, geolocation, some -clipboard and service-worker features) and any OAuth provider that refuses -`http://` redirect URIs. When one of those lands, the answer is a private -HTTPS origin (local CA or a private name with a certificate), never the -production domain. +The Supabase CLI publishes its ports with no host address and offers no bind +option, so Docker uses the daemon's default address. Two pieces: + +1. **The rootless daemon binds published ports on loopback by default**: + `~/.config/docker/daemon.json` = `{"ip": "127.0.0.1"}` (user-level file of + Docker rootless, no sudo). Every port published without an explicit + address, the CLI's included, then listens on `127.0.0.1` only. +2. **The DEV gateway** (`docker/dev-gateway/nginx.conf`, Compose service + `dev-gateway`, profile `dev`, container `faunosteo_dev_gateway`): an nginx + on the Supabase network, published on `:54321` (proxy + to Kong) and `:54324` (proxy to Mailpit behind basic + auth). `pnpm dev:gateway` starts it (and generates the Mailpit password on + first use), `pnpm dev:gateway:stop` stops it. + +Why not UFW: with Docker rootless, published ports are ordinary listening +sockets of the rootlesskit process in the host network namespace, so host +INPUT rules would apply (unlike rootful Docker, whose DNAT bypasses UFW); +but a firewall rule needs sudo, and binding to loopback removes the +listener instead of filtering it. A host firewall stays a possible second +layer, the owner's decision. + +### 3.2 Check + +`pnpm dev:net-check` probes from a throwaway container on its own Docker +network (a distinct origin that reaches the host by its LAN address only): +app 200, API health 200, REST without key 401, Mailpit 401 without and 200 +with the credentials, PostgreSQL and Studio closed; it prints the published +ports of the stack. Exit 1 on any deviation. + +### 3.3 Studio from another device + +```bash +ssh -L 54323:127.0.0.1:54323 @ # then http://localhost:54323 on that device +``` + +Studio's own API calls go to `http://:54321` (the gateway), which +the device reaches directly. + +### 3.4 HTTP on a private address + +The auth flows (PKCE, session in localStorage, no cookie) work over HTTP. +What would not: browser features that need a secure context on a +non-loopback origin (camera capture, geolocation, some clipboard and +service-worker features) and OAuth providers that refuse `http://` redirect +URIs. When one of those lands, the answer is a private HTTPS origin (local CA +or a private name with a certificate), never the production domain. ## 4. Procedure from another device (owner validation) -Stack and worker started on the Ubuntu machine (`pnpm db:start`, the worker -container, `pnpm dev`), then from the computer, and again from the phone on -the same network: +On the Ubuntu machine: `pnpm db:start`, `pnpm dev:gateway`, the worker +(`docker compose --profile worker up -d worker`), `pnpm dev`, then +`pnpm dev:net-check` (all OK). From the computer, then from the phone on the +same network: 1. `http://:5173/` opens the Faunosteo home. 2. `/login` shows the sign-in card. @@ -103,5 +138,7 @@ the same network: 9. Se déconnecter returns to the home; `/app` redirects to `/login`. 10. Same steps on the phone; no horizontal scroll. -A sign-up from the device: Mailpit at `http://:54324`, the link opened -in the same browser as the form. +A sign-up from the device: Mailpit at `http://:54324` (user `dev`, +password: `cat docker/dev-gateway/mailpit-password` on the Ubuntu machine), +the link opened in the same browser as the form. Refused from the device: +`http://:54323` (Studio) and anything on `:54322` (PostgreSQL). diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 38b9d0d9..178c5655 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -59,9 +59,10 @@ Every CLI call goes through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase `): it exports the DEV origin that `config.toml` reads with `env()` (`api.external_url`, `auth.site_url`, `studio.api_url`). A direct `node_modules/.bin/supabase start` would leave the literal `env(...)` text in -GoTrue's mail links. Published ports (all interfaces): API 54321, PostgreSQL -54322, Studio 54323, Mailpit 54324 (`ENVIRONMENTS.md` §3 for what each one -exposes). +GoTrue's mail links. Published ports: API 54321, PostgreSQL 54322, Studio +54323, Mailpit 54324, on loopback once the rootless daemon defaults to +`127.0.0.1`; the DEV gateway re-publishes the API and Mailpit (basic auth) on +the LAN address (`ENVIRONMENTS.md` §3). ```bash pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys diff --git a/docs/development/WORKSPACE.md b/docs/development/WORKSPACE.md index 2c93df8a..24c43371 100644 --- a/docs/development/WORKSPACE.md +++ b/docs/development/WORKSPACE.md @@ -87,6 +87,8 @@ works as `corepack pnpm `. | `pnpm install` | installs the whole workspace from the lockfile | | `pnpm dev` | Vite dev server of `apps/app` on `http://:5173`, wired to the local Supabase stack by the DEV origin (`scripts/dev.sh`, `ENVIRONMENTS.md`) | | `pnpm dev:offline` | the same server without backend (local tool only) | +| `pnpm dev:gateway` / `dev:gateway:stop` | the DEV gateway: Supabase API and Mailpit (basic auth) on the LAN address (`ENVIRONMENTS.md` §3) | +| `pnpm dev:net-check` | allowed / refused access probes from a distinct Docker network | | `pnpm supabase ` / `pnpm db:*` | the Supabase CLI with the DEV origin exported (`scripts/supabase.sh`) | | `pnpm preview` | serves `apps/app/dist` on :4173 | | `pnpm typecheck` | `tsc --noEmit` in every package | diff --git a/package.json b/package.json index 118b5a81..be37348a 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,9 @@ "scripts": { "dev": "bash scripts/dev.sh", "dev:offline": "pnpm --filter @faunosteo/app dev", + "dev:gateway": "bash scripts/dev-gateway.sh up", + "dev:gateway:stop": "bash scripts/dev-gateway.sh down", + "dev:net-check": "bash scripts/dev-net-check.sh", "preview": "pnpm --filter @faunosteo/app preview", "build": "pnpm -r build", "typecheck": "pnpm -r typecheck", diff --git a/scripts/dev-gateway.sh b/scripts/dev-gateway.sh new file mode 100755 index 00000000..9c052473 --- /dev/null +++ b/scripts/dev-gateway.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# DEV gateway on the private network (docs/development/ENVIRONMENTS.md §3). +# pnpm dev:gateway # up: generates the Mailpit credentials once, starts faunosteo_dev_gateway +# pnpm dev:gateway:stop # down +# Prerequisite: the rootless Docker daemon binds published ports on loopback by default +# (~/.config/docker/daemon.json {"ip": "127.0.0.1"}, ENVIRONMENTS.md §3.1), so the +# gateway is the only listener of the stack on the LAN address. +set -euo pipefail +cd "$(dirname "$0")/.." +. scripts/dev-env.sh +dir=docker/dev-gateway +htpasswd="$dir/htpasswd" +secret="$dir/mailpit-password" + +case "${1:-up}" in + up) + if [ ! -s "$htpasswd" ]; then + password="$(openssl rand -base64 18 | tr -d '/+=' | cut -c1-20)" + printf 'dev:%s\n' "$(openssl passwd -apr1 "$password")" > "$htpasswd" + printf '%s\n' "$password" > "$secret" + # Rootless Docker: the container's nginx user maps to a subordinate uid and cannot + # read a 600 file of this account; the htpasswd holds only a hash. The clear + # password stays 600. + chmod 644 "$htpasswd" + chmod 600 "$secret" + echo "== Mailpit credentials generated: user dev, password in $secret (not committed)" + fi + docker compose --profile dev up -d dev-gateway + echo "== gateway: api $FAUNOSTEO_DEV_API_URL mailpit $FAUNOSTEO_DEV_MAILPIT_URL (user dev, password: cat $secret)" + ;; + down) + docker compose --profile dev rm -sf dev-gateway + ;; + *) + echo "usage: dev-gateway.sh [up|down]" >&2; exit 2 ;; +esac diff --git a/scripts/dev-net-check.sh b/scripts/dev-net-check.sh new file mode 100755 index 00000000..bb2dc5be --- /dev/null +++ b/scripts/dev-net-check.sh @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +# Allowed / refused access check of the DEV surfaces from a distinct network origin: +# a throwaway container on its own Docker bridge reaches the host only through its LAN +# address, like another device would (never through loopback). +# pnpm dev:net-check # expects the stack, pnpm dev and the gateway running +# Exit 1 when an expectation fails. docs/development/ENVIRONMENTS.md §3. +set -euo pipefail +cd "$(dirname "$0")/.." +. scripts/dev-env.sh +host="$FAUNOSTEO_DEV_HOST" +net=faunosteo_net_check +image=curlimages/curl:8.11.1 +docker network create "$net" >/dev/null 2>&1 || true +# shellcheck disable=SC2329 # invoked by the trap +cleanup() { docker network rm "$net" >/dev/null 2>&1 || true; } +trap cleanup EXIT + +probe() { # probe