chore(workspace): DEV least-privilege exposure — nginx DEV gateway (API on the LAN, Mailpit behind basic auth), network check from a distinct origin, loopback default for the rootless daemon documented

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).
This commit is contained in:
bchanot committed 2026-10-13 22:38:40 +02:00
1 parent 5a12596195
commit 3e48b0d848
11 files changed
+246 -36

No files matched your search

+2
View File
@@ -20,3 +20,5 @@ docs/
logos/
target/
packages/core-wasm/pkg/
docker/dev-gateway/htpasswd
docker/dev-gateway/mailpit-password
+4
View File
@@ -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
+7 -3
View File
@@ -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://<FAUNOSTEO_DEV_HOST>: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)
+21
View File
@@ -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 <DEV host>:54321 and Mailpit behind
# basic auth on <DEV host>: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
+46
View File
@@ -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;
}
}
+67 -30
View File
@@ -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 `<DEV host>: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 `<FAUNOSTEO_DEV_HOST>:54321` (proxy
to Kong) and `<FAUNOSTEO_DEV_HOST>: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 <user>@<DEV host> # then http://localhost:54323 on that device
```
Studio's own API calls go to `http://<DEV host>: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://<host>: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://<host>:54324`, the link opened
in the same browser as the form.
A sign-up from the device: Mailpit at `http://<host>: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://<host>:54323` (Studio) and anything on `:54322` (PostgreSQL).
+4 -3
View File
@@ -59,9 +59,10 @@ Every CLI call goes through `scripts/supabase.sh` (`pnpm db:*`, `pnpm supabase
<args>`): 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
+2
View File
@@ -87,6 +87,8 @@ works as `corepack pnpm <cmd>`.
| `pnpm install` | installs the whole workspace from the lockfile |
| `pnpm dev` | Vite dev server of `apps/app` on `http://<FAUNOSTEO_DEV_HOST>: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 <args>` / `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 |
+3
View File
@@ -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",
+36
View File
@@ -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
+54
View File
@@ -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 <label> <expected> <curl args...>; expected = an HTTP code, "closed" or "open"
local label="$1" expected="$2"; shift 2
local code status=0
code="$(docker run --rm --network "$net" "$image" -s -o /dev/null -w '%{http_code}' --connect-timeout 4 "$@" 2>/dev/null)" || status=$?
# curl exit 7 = connection refused, 28 = timeout (filtered): nothing listens for the LAN.
# A TCP service that is not HTTP (PostgreSQL) answers with exit 52/56: the port is open.
case "$status" in
0) ;;
7|28) code=closed ;;
*) code=open ;;
esac
if [ "$code" = "$expected" ]; then
printf 'OK %-52s %s\n' "$label" "$code"
else
printf 'FAIL %-52s %s (expected %s)\n' "$label" "$code" "$expected"
failed=1
fi
}
failed=0
password=""
[ -s docker/dev-gateway/mailpit-password ] && password="$(cat docker/dev-gateway/mailpit-password)"
echo "== from a separate Docker network towards $host"
probe "app :5173 (Vite) allowed" 200 "http://$host:5173/login"
probe "API :54321 auth health (gateway) allowed" 200 "http://$host:54321/auth/v1/health"
probe "API :54321 rest without key 401" 401 "http://$host:54321/rest/v1/profiles"
probe "Mailpit :54324 without credentials 401" 401 "http://$host:54324/"
if [ -n "$password" ]; then
probe "Mailpit :54324 with credentials allowed" 200 -u "dev:$password" "http://$host:54324/"
fi
probe "PostgreSQL :54322 closed" closed "http://$host:54322/"
probe "Studio :54323 closed" closed "http://$host:54323/"
echo "== published ports of the stack (loopback expected except the gateway)"
for c in supabase_kong_faunosteo supabase_db_faunosteo supabase_studio_faunosteo supabase_inbucket_faunosteo faunosteo_dev_gateway; do
printf '%-30s %s\n' "$c" "$(docker port "$c" 2>/dev/null | grep -v '::' | tr '\n' ' ')"
done
exit "$failed"