From dd4c35c0614f57b845c5975b6a7a8df826bc3289 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 22:06:25 +0200 Subject: [PATCH 1/7] =?UTF-8?q?chore(workspace):=20DEV=20origin=20on=20the?= =?UTF-8?q?=20private=20network=20=E2=80=94=20scripts/dev-env.sh=20(FAUNOS?= =?UTF-8?q?TEO=5FDEV=5FHOST=20detected=20or=20set),=20Supabase=20CLI=20wra?= =?UTF-8?q?pper,=20pnpm=20dev=20on=20the=20LAN=20address,=20config.toml=20?= =?UTF-8?q?URLs=20via=20env();=20ENVIRONMENTS.md=20(identity=20Faunosteo?= =?UTF-8?q?=20/=20faunosteo.com,=20DEV=20/=20STAGING=20/=20PROD,=20exposur?= =?UTF-8?q?e=20table,=20owner=20procedure)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner tests from other devices of the private network: every test surface is addressed by the machine's LAN address, never 127.0.0.1 or localhost, never hard-coded. scripts/dev-env.sh decides the host once (hostname -I, FAUNOSTEO_DEV_HOST override, production hosts refused); scripts/supabase.sh exports it for every CLI call (pnpm db:*, pnpm supabase) because config.toml now reads api.external_url (mail links), auth.site_url and studio.api_url with env(); scripts/dev.sh = pnpm dev on that origin, pnpm dev:offline keeps the local tool alone; dev-lan.sh removed. Verified: GoTrue API_EXTERNAL_URL and Studio SUPABASE_PUBLIC_URL on the LAN address, a signup mail linking to http://:54321/auth/v1/verify, the four published ports answering from a separate Docker network, and the 10-step procedure in headless Chromium at the LAN origin with every request URL audited (no 127.0.0.1 / localhost). --- CHANGELOG.md | 4 ++ CLAUDE.md | 23 +++++-- README.md | 5 ++ docs/development/ENVIRONMENTS.md | 107 +++++++++++++++++++++++++++++++ docs/development/IDENTITY.md | 5 +- docs/development/SUPABASE.md | 21 ++++-- docs/development/WORKSPACE.md | 4 +- package.json | 17 ++--- scripts/avatar-e2e.sh | 1 + scripts/dev-env.sh | 26 ++++++++ scripts/dev-lan.sh | 13 ---- scripts/dev.sh | 14 ++++ scripts/supabase.sh | 10 +++ supabase/config.toml | 19 +++--- 14 files changed, 228 insertions(+), 41 deletions(-) create mode 100644 docs/development/ENVIRONMENTS.md create mode 100644 scripts/dev-env.sh delete mode 100755 scripts/dev-lan.sh create mode 100755 scripts/dev.sh create mode 100755 scripts/supabase.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 05dd439f..44caca9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Changed (development environment, 2026-10-13) + +- **DEV on the private network** — the owner tests from other devices: the DEV origin (the machine's LAN address, `FAUNOSTEO_DEV_HOST`, detected or set) lives in `scripts/dev-env.sh`; `pnpm dev` serves the app on that origin wired to the local stack, `pnpm dev:offline` keeps the local tool alone; every Supabase CLI call goes through `scripts/supabase.sh` so `config.toml` (API external URL for the mail links, site URL, Studio API URL via `env()`) follows the origin; private-network redirect URLs for the PKCE links. Identity recorded: Faunosteo, https://faunosteo.com; environments DEV / STAGING / PROD and the exposure table in `docs/development/ENVIRONMENTS.md`. + ### Added (SaaS migration, plan Step 8 = Rust R1) - **Files foundation and profile photo (Step 8)** — `public.assets` as the authority over user files (status, owner, server-built keys, worker lease token), seven private Storage buckets (only `avatars` open, through SELECT / INSERT policies evaluated on `assets`; the six others closed until their step), a quarantine upload path (`begin_avatar_upload` → direct upload at the quarantine key → `confirm_asset_upload`), a deferred purge queue (48 h for a replaced or removed avatar, 1 h for quarantine and rejected uploads: the backup invariant) and the audited RPCs of the browser and of the worker (migration `20261013100000`, pgTAP 010 with 125 allowed and denied checks, policy census). **Rust worker job loop** (`crates/worker`, R1): the keyed parent claims leased jobs through PostgREST, downloads the quarantine bytes, hands them to the sandboxed `decode` child of R0 (empty environment, rlimits, seccomp allowlist unchanged), uploads the 512 × 512 lossy WebP, commits the row, deletes the quarantine object, rejects with closed codes (`unsupported_type`, `decode_failed`, `dimensions`, `processing_error`), sweeps expired uploads, the purge queue and quarantine leftovers; JSON line logs with a field allowlist; per-stage watchdog; Compose service `worker` (profile `worker`, read-only, no capability, external Supabase network, `.env.worker`). **Profile photo** in Mon compte (preview before any request, save, processing with polling, rejection messages, replacement, removal with confirmation) and in the sidebar, the mobile drawer and the top bar (name beside it on desktop, link to Mon compte); JPEG / PNG / WebP only, never SVG, downscaled to 1024 px in the browser as transport, judged again by the worker; the owner downloads the clean object under RLS (no signed URL). Real-stack end-to-end run `pnpm e2e:avatar`. Spec: `docs/development/STORAGE.md`. diff --git a/CLAUDE.md b/CLAUDE.md index 19d3adf6..5ca48313 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,8 @@ ## Project overview +**Faunosteo** is the official, final product name (the SaaS, the application, the public site and its services); official domain **https://faunosteo.com** (production, separate VPS, the site present there is preserved until an explicit migration decision). Never propose another brand name; keep the logo, palette and validated mockups. Environments DEV / STAGING (`staging.faunosteo.com`, planned, not created) / PROD are isolated (`docs/development/ENVIRONMENTS.md`). + Single-praticien French web app for veterinary osteopathy bilans on animal anatomy SVGs. Practitioner clicks anatomical zones, builds observations with pathologies/severity, writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native @@ -71,8 +73,9 @@ access layer (see `docs/development/WORKSPACE.md`). Every command below runs from the repository root and delegates to the packages. ```bash -# Development -pnpm dev +# 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 # Production build (typecheck + vite build) pnpm build @@ -95,8 +98,9 @@ pnpm lint # Format pnpm format -# Supabase local stack (Docker) — docs/development/SUPABASE.md -pnpm db:start # start stack, apply migrations + seed +# Supabase local stack (Docker) — docs/development/SUPABASE.md; every CLI call goes through +# scripts/supabase.sh (exports the DEV origin that config.toml reads with env()); `pnpm supabase ` +pnpm db:start # start stack, apply migrations + seed; FAUNOSTEO_DEV_HOST= to pick another address pnpm db:reset # replay from zero pnpm db:test # pgTAP on the real stack pnpm db:types # regenerate packages/supabase/src/database.types.ts @@ -271,6 +275,7 @@ faunosteo/ │ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs) │ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh ├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e +├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin ├─ docker-compose.yml ← `app` service; `worker` service under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`) ├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proof ├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) @@ -433,6 +438,16 @@ Database (Supabase) operator scripts under `packages/*/scripts/` read it from the environment and are never bundled. - pgTAP files run on PGlite and on the real image: scope counts to fixture ids, pin `collate "C"` on text ordering. +### Environments and LAN access (docs/development/ENVIRONMENTS.md) +- The owner tests from other devices of the private network, never on the Ubuntu machine: every test surface + (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 + 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) - `public.assets` is the authority over every user file: status, owner, keys, lease. Every write is an RPC; the browser reads its own rows through an explicit column list (`select=*` is refused: lease columns are not granted). diff --git a/README.md b/README.md index 70d57f92..ec2aa917 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,11 @@ cp .env.example .env # edit APP_* vars if desired pnpm dev # http://localhost:5173 ``` +Development server on the private network (the DEV origin is the machine's +LAN address, `scripts/dev-env.sh`): `pnpm db:start`, then `pnpm dev` and open +`http://:5173` from any device of the network; Mailpit for the +sign-up mails on `:54324` (`docs/development/ENVIRONMENTS.md`). + Rust (core, browser module, worker): a user-level `rustup` installs the pinned toolchain from `rust-toolchain.toml` on first use; see `docs/development/RUST.md` §1 for the three `cargo install` / `rustup diff --git a/docs/development/ENVIRONMENTS.md b/docs/development/ENVIRONMENTS.md new file mode 100644 index 00000000..d256be81 --- /dev/null +++ b/docs/development/ENVIRONMENTS.md @@ -0,0 +1,107 @@ +# Environments: DEV, STAGING, PROD + +Owner decisions of 2026-10-13 (BDR-049). Product identity: **Faunosteo**, +official domain **https://faunosteo.com** (the SaaS, the application, the +public site and its services; the current logo, palette and validated +mockups under `docs/design/` stay). No other brand name is proposed again. + +| Environment | Where | Data | Reachable from | +|---|---|---|---| +| **DEV** | the self-hosted Ubuntu development machine (native Rust via rustup/Cargo, Node/Vite, Docker rootless for the Supabase stack, the worker and the images) | test data, fictitious accounts, local Supabase, local worker | the owner's other devices on the private network (computer, phone): the DEV origin below | +| **STAGING** | `staging.faunosteo.com`, planned, not created | its own database, storage, secrets, accounts | later | +| **PROD** | `https://faunosteo.com`, separate VPS | real data | the Internet; the site present today is preserved until an explicit migration decision | + +Isolation: each environment keeps its own PostgreSQL, Storage, secrets, +accounts, OAuth client ids, payments, e-mails, professional files and +bilans. Production data is never copied into DEV. A merge into `develop` +never deploys anything; no CI/CD runs on the forge today (workflow files are +prepared material), no runner, registry or secret exists. + +## 1. Rule: every test surface of DEV is reachable on the private network + +The owner does not test on the Ubuntu machine itself. Whatever a browser or +a phone needs for a test is addressed by the machine's LAN address (or a +private DNS name), never by `127.0.0.1` or `localhost` of the server, and +never hard-coded in the sources. + +## 2. The DEV origin, in one place + +`scripts/dev-env.sh` decides the DEV host once: + +| Variable | Default | Meaning | +|---|---|---| +| `FAUNOSTEO_DEV_HOST` | the first non-loopback IPv4 of the host (`hostname -I`) | address or name of this machine on the private network; `127.0.0.1` for a host-only session; a production host is refused | +| derived | `FAUNOSTEO_DEV_API_URL` `http://:54321`, `FAUNOSTEO_DEV_SITE_URL` `http://:5173`, `FAUNOSTEO_DEV_API_ORIGIN`, `FAUNOSTEO_DEV_STUDIO_URL` `:54323`, `FAUNOSTEO_DEV_MAILPIT_URL` `:54324` | read by `supabase/config.toml` (`env()`) and by the Vite dev server | + +Consumers: `scripts/supabase.sh` (every CLI call: `pnpm supabase …`, +`pnpm db:start|stop|reset|test|types`), `scripts/dev.sh` (`pnpm dev`), +`scripts/avatar-e2e.sh`. The address changes with `FAUNOSTEO_DEV_HOST=…` +in front of the command, without touching a source file. Calling the CLI +binary directly (`node_modules/.bin/supabase start`) leaves the literal +`env(...)` text in the services: always go through `pnpm`. + +```bash +pnpm db:start # stack on the DEV origin; mails link to http://:54321/auth/v1/... +pnpm worker:image && docker compose --profile worker up -d worker # .env.worker: DEPLOY.md +pnpm dev # http://:5173, Supabase by the DEV origin, HMR over the LAN +pnpm dev:offline # the local tool without backend (host:5173 too) +FAUNOSTEO_DEV_HOST=10.0.0.5 pnpm db:start # another address: restart the stack, then pnpm dev again +``` + +`supabase/config.toml` reads: `api.external_url` (the address GoTrue writes +into confirmation and recovery mails), `auth.site_url`, `studio.api_url`; +`auth.additional_redirect_urls` allows every private-network host on `:5173` +(`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) + +The Supabase CLI publishes its ports on every interface (`0.0.0.0`, no bind +option); Vite listens on every interface (`server.host: true`). + +| 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 | — | + +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. + +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. + +## 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: + +1. `http://:5173/` opens the Faunosteo home. +2. `/login` shows the sign-in card. +3. `alice@faunosteo.local` / `LocalDev-only-password-1` signs in. +4. `/app` shows the dashboard. +5. Mon compte opens. +6. Modifier la photo with a photo of the device → preview → Enregistrer. +7. "Traitement en cours…" then the photo (the worker's log shows + `job_completed`). +8. Reload: the photo is still there, in the circle, the sidebar / drawer and + the top bar. +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. diff --git a/docs/development/IDENTITY.md b/docs/development/IDENTITY.md index e03839c7..eee177fe 100644 --- a/docs/development/IDENTITY.md +++ b/docs/development/IDENTITY.md @@ -99,9 +99,8 @@ holding a platform role. ## 5. Manual validation (local stack) ```bash -pnpm db:start # prints API URL + anon key; Mailpit at http://127.0.0.1:54324 -VITE_SUPABASE_URL=http://127.0.0.1:54321 VITE_SUPABASE_ANON_KEY= \ -VITE_AUTH_PROVIDERS=google pnpm dev +pnpm db:start # stack on the DEV origin (LAN address); Mailpit at http://:54324 +VITE_AUTH_PROVIDERS=google pnpm dev # http://:5173 from any device of the private network (ENVIRONMENTS.md) ``` 1. `/app` while signed out → `/login?next=%2Fapp`. The login card shows a diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 192e4467..38b9d0d9 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -55,6 +55,14 @@ like every other tool. Never install it globally. ## 3. Start, stop, reset +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). + ```bash pnpm db:start # supabase start: pulls images, applies migrations + seed, prints URLs and keys pnpm db:stop # supabase stop (keeps the volume) @@ -246,14 +254,19 @@ audit rows (bootstrap with null actor, grant by the owner). ## 9. Wiring the app -`.env` (Docker) or `apps/app/.env.local` (Vite dev): +Development: `pnpm dev` (`scripts/dev.sh`) sets `VITE_SUPABASE_URL` to the DEV +origin (`http://:54321`, the LAN address of the machine: +`ENVIRONMENTS.md` §2) and the anon key from `supabase status`; the app is +served on `http://:5173` for every device of the private network. +`pnpm dev:offline` runs the local tool without backend. Docker deployments use +`.env`: ```bash -APP_SUPABASE_URL=http://127.0.0.1:54321 # VITE_SUPABASE_URL in dev -APP_SUPABASE_ANON_KEY= # VITE_SUPABASE_ANON_KEY in dev +APP_SUPABASE_URL= +APP_SUPABASE_ANON_KEY= # public by design ``` -Both empty (the default) keeps the app in its local-only mode: +Both empty keeps the app in its local-only mode: `getSupabaseClient()` returns null, the auth screens show an "unavailable" notice and `/app` redirects to `/login`. `APP_AUTH_PROVIDERS` / `VITE_AUTH_PROVIDERS` (`google,apple`) lists the OAuth buttons to show. diff --git a/docs/development/WORKSPACE.md b/docs/development/WORKSPACE.md index 2e09f100..2c93df8a 100644 --- a/docs/development/WORKSPACE.md +++ b/docs/development/WORKSPACE.md @@ -85,7 +85,9 @@ works as `corepack pnpm `. | Command | Does | |---|---| | `pnpm install` | installs the whole workspace from the lockfile | -| `pnpm dev` | Vite dev server of `apps/app` on :5173 | +| `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 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 | | `pnpm test:run` | vitest once in every package | diff --git a/package.json b/package.json index b954d381..118b5a81 100644 --- a/package.json +++ b/package.json @@ -10,8 +10,8 @@ "pnpm": ">=10.13 <11" }, "scripts": { - "dev": "pnpm --filter @faunosteo/app dev", - "dev:lan": "bash scripts/dev-lan.sh", + "dev": "bash scripts/dev.sh", + "dev:offline": "pnpm --filter @faunosteo/app dev", "preview": "pnpm --filter @faunosteo/app preview", "build": "pnpm -r build", "typecheck": "pnpm -r typecheck", @@ -23,12 +23,13 @@ "check:all": "bash scripts/check-all.sh", "report:compare": "pnpm --filter @faunosteo/app report:compare", "import:equine": "pnpm --filter @faunosteo/anatomy import:equine", - "db:start": "supabase start", - "db:stop": "supabase stop", - "db:reset": "supabase db reset", - "db:test": "supabase test db", - "db:types": "supabase gen types typescript --local --schema public | prettier --parser typescript > packages/supabase/src/database.types.ts", - "db:types:check": "supabase gen types typescript --local --schema public | prettier --parser typescript | diff - packages/supabase/src/database.types.ts", + "supabase": "bash scripts/supabase.sh", + "db:start": "bash scripts/supabase.sh start", + "db:stop": "bash scripts/supabase.sh stop", + "db:reset": "bash scripts/supabase.sh db reset", + "db:test": "bash scripts/supabase.sh test db", + "db:types": "bash scripts/supabase.sh gen types typescript --local --schema public | prettier --parser typescript > packages/supabase/src/database.types.ts", + "db:types:check": "bash scripts/supabase.sh gen types typescript --local --schema public | prettier --parser typescript | diff - packages/supabase/src/database.types.ts", "assets:upload": "pnpm --filter @faunosteo/supabase assets:upload", "build:preview": "SHEET_BUNDLE=draft pnpm --filter @faunosteo/app build", "preview:draft": "SHEET_BUNDLE=draft pnpm --filter @faunosteo/app build && pnpm --filter @faunosteo/app preview", diff --git a/scripts/avatar-e2e.sh b/scripts/avatar-e2e.sh index f981546d..0a1a3b9d 100755 --- a/scripts/avatar-e2e.sh +++ b/scripts/avatar-e2e.sh @@ -14,6 +14,7 @@ kong="${SUPABASE_INTERNAL_URL:-http://supabase_kong_faunosteo:8000}" image="${WORKER_IMAGE:-faunosteo_worker:dev}" name="faunosteo_worker_e2e" +. scripts/dev-env.sh status="$(node_modules/.bin/supabase status -o env 2>/dev/null)" \ || { echo "avatar-e2e: the local stack is not running (pnpm db:start)" >&2; exit 1; } value() { printf '%s\n' "$status" | sed -n "s/^$1=\"\(.*\)\"$/\1/p"; } diff --git a/scripts/dev-env.sh b/scripts/dev-env.sh new file mode 100644 index 00000000..5bc0a3e9 --- /dev/null +++ b/scripts/dev-env.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# shellcheck shell=bash +# The one place the DEV origin is decided (docs/development/ENVIRONMENTS.md §2). +# Sourced by the wrappers (scripts/supabase.sh, scripts/dev.sh, scripts/avatar-e2e.sh): +# every service the browser of another device must reach is addressed by the +# host's LAN address, never by 127.0.0.1 or localhost. +# +# FAUNOSTEO_DEV_HOST the address or name of this machine on the private network; +# unset = the first non-loopback IPv4 of the host; 127.0.0.1 for +# a host-only session. Never a production host. +# +# Exports FAUNOSTEO_DEV_HOST and the derived URLs read by supabase/config.toml +# (env() substitution) and by the Vite dev server. +if [ -z "${FAUNOSTEO_DEV_HOST:-}" ]; then + FAUNOSTEO_DEV_HOST="$(hostname -I 2>/dev/null | awk '{print $1}')" + [ -n "$FAUNOSTEO_DEV_HOST" ] || FAUNOSTEO_DEV_HOST=127.0.0.1 +fi +case "$FAUNOSTEO_DEV_HOST" in + *faunosteo.com*) echo "dev-env: FAUNOSTEO_DEV_HOST must never be a production host ($FAUNOSTEO_DEV_HOST)" >&2; return 1 ;; +esac +export FAUNOSTEO_DEV_HOST +export FAUNOSTEO_DEV_API_ORIGIN="http://$FAUNOSTEO_DEV_HOST" +export FAUNOSTEO_DEV_API_URL="http://$FAUNOSTEO_DEV_HOST:54321" +export FAUNOSTEO_DEV_SITE_URL="http://$FAUNOSTEO_DEV_HOST:5173" +export FAUNOSTEO_DEV_STUDIO_URL="http://$FAUNOSTEO_DEV_HOST:54323" +export FAUNOSTEO_DEV_MAILPIT_URL="http://$FAUNOSTEO_DEV_HOST:54324" diff --git a/scripts/dev-lan.sh b/scripts/dev-lan.sh deleted file mode 100755 index b1cb99cc..00000000 --- a/scripts/dev-lan.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/usr/bin/env bash -# Vite dev server reachable from the LAN, wired to the local Supabase stack by the -# host's LAN address (the stack publishes 54321 / 54323 / 54324 on every interface). -# Usage: pnpm dev:lan [host-ip] (default: the first non-loopback IPv4 of this host) -set -euo pipefail -cd "$(dirname "$0")/.." -ip="${1:-$(hostname -I 2>/dev/null | awk '{print $1}')}" -[ -n "$ip" ] || { echo "dev-lan: pass the host IP as the first argument" >&2; exit 1; } -anon="$(node_modules/.bin/supabase status -o env 2>/dev/null | sed -n 's/^ANON_KEY="\(.*\)"$/\1/p')" -[ -n "$anon" ] || { echo "dev-lan: local stack not running (pnpm db:start)" >&2; exit 1; } -echo "== app http://$ip:5173 supabase http://$ip:54321 studio http://$ip:54323 mailpit http://$ip:54324" -VITE_SUPABASE_URL="http://$ip:54321" VITE_SUPABASE_ANON_KEY="$anon" \ - exec node_modules/.bin/pnpm --filter @faunosteo/app exec vite --host 0.0.0.0 --port 5173 diff --git a/scripts/dev.sh b/scripts/dev.sh new file mode 100755 index 00000000..d15b9e7e --- /dev/null +++ b/scripts/dev.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# Vite dev server reachable from the private network, wired to the local +# Supabase stack by the DEV origin (scripts/dev-env.sh). Vite listens on every +# interface (apps/app/vite.config.ts server.host); HMR follows the page host. +# pnpm dev # http://:5173 +# pnpm dev:offline # no backend: the local tool alone +set -euo pipefail +cd "$(dirname "$0")/.." +. scripts/dev-env.sh +anon="$(node_modules/.bin/supabase status -o env 2>/dev/null | sed -n 's/^ANON_KEY="\(.*\)"$/\1/p')" +[ -n "$anon" ] || { echo "dev: the local stack is not running (pnpm db:start), or use pnpm dev:offline" >&2; exit 1; } +echo "== app $FAUNOSTEO_DEV_SITE_URL api $FAUNOSTEO_DEV_API_URL studio $FAUNOSTEO_DEV_STUDIO_URL mailpit $FAUNOSTEO_DEV_MAILPIT_URL" +VITE_SUPABASE_URL="$FAUNOSTEO_DEV_API_URL" VITE_SUPABASE_ANON_KEY="$anon" \ + exec node_modules/.bin/pnpm --filter @faunosteo/app exec vite --port 5173 --strictPort diff --git a/scripts/supabase.sh b/scripts/supabase.sh new file mode 100755 index 00000000..6d73e73c --- /dev/null +++ b/scripts/supabase.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +# Supabase CLI with the DEV origin exported: supabase/config.toml reads the +# API external URL, the site URL and Studio's API URL through env(), so every +# CLI call (start, stop, status, db reset, test db, gen types) must see them, +# or the literal "env(...)" text lands in the running services. +# pnpm supabase · pnpm db:start · FAUNOSTEO_DEV_HOST=10.0.0.5 pnpm db:start +set -euo pipefail +cd "$(dirname "$0")/.." +. scripts/dev-env.sh +exec node_modules/.bin/supabase "$@" diff --git a/supabase/config.toml b/supabase/config.toml index 52c33fab..018680c2 100644 --- a/supabase/config.toml +++ b/supabase/config.toml @@ -6,9 +6,11 @@ project_id = "faunosteo" [api] enabled = true port = 54321 -# LAN development: the address written into confirmation and recovery mails -# (GoTrue API_EXTERNAL_URL). Keep 127.0.0.1 when working on the host alone. -external_url = "http://192.168.1.100:54321" +# DEV origin (scripts/dev-env.sh, exported by every CLI call through scripts/supabase.sh): +# the address written into confirmation and recovery mails (GoTrue API_EXTERNAL_URL). +# Tests run from other devices of the private network, so it is the host's LAN +# address, never 127.0.0.1 (docs/development/ENVIRONMENTS.md). +external_url = "env(FAUNOSTEO_DEV_API_URL)" # Only public is exposed through PostgREST. private and audit stay internal # (docs/development/BACKEND_ARCHITECTURE.md §3). schemas = ["public"] @@ -48,7 +50,8 @@ enabled = false [studio] enabled = true port = 54323 -api_url = "http://127.0.0.1" +# Origin the remote browser running Studio calls the API on (same DEV origin, no port). +api_url = "env(FAUNOSTEO_DEV_API_ORIGIN)" # Local mail catcher: confirmation and OTP mails land at http://127.0.0.1:54324 [local_smtp] @@ -70,10 +73,10 @@ enabled = false [auth] enabled = true -# Vite dev server of apps/app -site_url = "http://192.168.1.100:5173" -# LAN access (pnpm dev:lan): confirmation and recovery links must land on the -# address the browser used, so every private-network host on :5173 is allowed. +# Vite dev server of apps/app on the DEV origin (scripts/dev-env.sh) +site_url = "env(FAUNOSTEO_DEV_SITE_URL)" +# Confirmation and recovery links land on the address the browser used: every +# private-network host on :5173 is allowed, plus the host-only forms. additional_redirect_urls = [ "http://127.0.0.1:5173", "http://localhost:5173", From 5a125961957e2125b26aac26d89c37bcc439d742 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 22:07:00 +0200 Subject: [PATCH 2/7] =?UTF-8?q?chore(memory):=20R1=20validated=20and=20mer?= =?UTF-8?q?ged,=20identity=20and=20environments,=20LAN=20rule=20=E2=80=94?= =?UTF-8?q?=20BDR-049,=20journal,=20TODO?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/decisions.md | 6 ++++++ .claude/memory/journal.md | 4 ++++ .claude/tasks/TODO.md | 2 ++ 3 files changed, 12 insertions(+) diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index eefad8a6..91a9fd07 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -388,3 +388,9 @@ Status: active; awaiting the owner's final validation before R1. Built on STEP8 D1–D9 (D1 = Rust worker, D3 = top-bar avatar + name → Mon compte). Choices beyond the analysis: (1) `assets.lock_token` uuid set by `claim_avatar_jobs`, required by complete/reject → stale worker after lease expiry refused (`invalid_state`), not only superseded rows; (2) complete refused → worker deletes nothing, purge queue owns every object of a terminal row (the analysis' "delete the clean object it wrote" would race a legit re-claim); (3) key-driven quarantine sweep = SQL anti-join RPC `claim_quarantine_leftovers` on `storage.objects` (same DB) instead of paginated Storage API listing; `expire_pending_uploads` RPC for the 24 h expiry; (4) closed refusals = SQLSTATE P0001 with the code as message, authz = 42501; TS/Rust map message → closed kind only when it has the code shape; (5) worker HTTP = `ureq` 3 (rustls + ring, webpki-roots), hand JSON log lines, 25-line base64url decoder: deviation from review Part V (tokio/reqwest/tracing/base64) justified by sequential loop + smaller keyed-process tree (34 → 84 crates, no aws-lc-rs/cmake); (6) Storage API v1.79 answers a missing object HTTP 400 + statusCode "404" → normalised to 404 = purge done (found by the e2e, queue entries looped otherwise); (7) e2e = vitest file outside the default include, runner script starts the worker container (5 s sweep, 0 grace), fresh admin-created user per run (10/h rate limit), purge clock shifted via `docker exec psql`; (8) `run --check` exit 0 when startable OR wholly unconfigured (check:all envless stage), 2 on partial config; (9) `.env.worker*` not writable here (file rule) → documented in DEPLOY.md, user creates it; (10) R1 branch cut from the R0 tip because `gitflow finish` of R0 was refused by the harness classifier. Alt rejected: profile column avatar pointer (D5 kept derived); signed read URL (bearer outlives row flip); Storage listing sweep (3-level prefix pagination); reqwest blocking (pulls tokio). Status: active; awaiting owner validation (TEST FONCTIONNEL + TEST GRAPHIQUE), no merge. + +## BDR-049 | 2026-10-13 | Identity Faunosteo / faunosteo.com; DEV-STAGING-PROD; DEV reachable on the private network; R0+R1 validated and merged + +Owner decisions: (1) R1 validated 10/10 manual + graphic → R0 and R1 finished into develop (5cfb6f1, f5865f0; the earlier classifier refusal did not recur); (2) identity final: product/app/site = **Faunosteo**, domain **https://faunosteo.com**, no new brand name, logo/palette/mockups kept; (3) environments: DEV = self-hosted Ubuntu native (Claude Code, git, rustup, Vite, Docker rootless, local Supabase, worker), STAGING = `staging.faunosteo.com` planned not created, PROD = separate VPS, current site preserved, no DNS/cert/proxy/data change; isolation of DB/Storage/secrets/accounts/OAuth/payments/mails/files per env, prod data never copied to DEV, merge ≠ deploy, no CI/CD operational (workflows preparatory); (4) permanent rule: the owner tests from other devices (computer, phone) → every test surface addressed by the DEV origin (LAN address or private name), never 127.0.0.1/localhost, never hard-coded; implemented as `scripts/dev-env.sh` (`FAUNOSTEO_DEV_HOST`, detected via `hostname -I`, prod host refused) + `scripts/supabase.sh` wrapper (config.toml `env()` for api.external_url, auth.site_url, studio.api_url) + `scripts/dev.sh` (`pnpm dev` on the origin, `pnpm dev:offline` without backend) + private-network redirect URLs; (5) exposure: 5173/54321 needed by browsers, Studio 54323 + Mailpit 54324 unauthenticated → private subnet only, PostgreSQL 54322 published by the CLI on 0.0.0.0 (no bind option) → firewall restriction proposed to the owner, not applied; worker no port; (6) Rust native via Cargo, Docker for services/worker/sandbox/images/prod, VPS never compiles. +Alt rejected: hard-coded IP in config.toml (first iteration, replaced the same day); Vite `dev:lan` variant (folded into `dev`); binding the CLI ports to loopback (impossible in config.toml). +Status: active; `chore/dev-lan-access` awaiting the owner's LAN validation; R2 not started. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index aceee697..fc4f80b8 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -240,3 +240,7 @@ Owner brief: dev = Ubuntu native server, Docker for services/isolation/images, V ## 2026-10-13 (Step 8 = Rust R1 delivered) Owner validated R0, go for R1 with D1–D9 (D1 Rust worker, D3 top-bar avatar). `gitflow finish` of R0 refused by the classifier → R1 branch feature/step-08-files-foundation cut from the R0 tip (owner finishes both). Delivered: migration 20261013100000 (assets, 7 private buckets, avatar policies through assets, purge queue, 11 RPCs, lease token, per-account byte budget + bytes-present ceiling), pgTAP 010 (140), worker R1 loop (ureq, config/log/keys/backend/http/job/sweep/watchdog, 11 loop tests, child untouched, allowlist unchanged), TS assets layer + avatar UI (Mon compte, sidebar, drawer, top bar), real-stack e2e + runner, compose worker profile, STORAGE.md + docs. Gates: verifier CONFORME (pass 2), security PASS after 5 passes (1 BLOCK from my own fix), check:all ×4 green, e2e ×7, Chromium smoke 18/18. BDR-048, LRN-051, EVAL-019. Stop: owner manual validation; no merge, no deploy, no release. + +## 2026-10-13 (R1 validated, merges, DEV on the LAN) + +Owner: R1 10/10 validated, identity final (Faunosteo, faunosteo.com), env DEV/STAGING/PROD, permanent LAN-access rule. gitflow finish R0 then R1 → develop (linear graph, two merge commits, branches deleted). chore/dev-lan-access: DEV origin centralised (`scripts/dev-env.sh`, CLI wrapper, `pnpm dev` on the LAN, config.toml via env()), ENVIRONMENTS.md, docs, CHANGELOG. Verified: GoTrue/Studio on the LAN address, signup mail link on the LAN, probes from a separate Docker network (app/api/mailpit 200, studio 307), 10-step procedure in headless Chromium at http://192.168.1.100:5175 computer + phone 26/26 with URL audit. Firewall state unreadable (no sudo) → proposal to the owner (54322 loopback, 54323/54324 subnet). BDR-049. Stop: owner LAN validation + R2 go. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 058deef2..250c2f6d 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -136,6 +136,8 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 8.6 integration: docker-compose `worker` service under profile `worker` (read-only, cap_drop ALL, no-new-privileges, mem 512m, cpus 1, pids 64, external Supabase network), `.env.worker` variables documented (file not editable here), real-stack e2e `pnpm --filter @faunosteo/supabase test:e2e` (worker container against the local stack: Alice flow clean + download 200, replace, remove, Bob 400, anon 400, quarantine 400, late signed-upload bytes swept, purge after grace via clock shift) - [x] 8.7 docs: STORAGE.md final (model, keys, statuses, worker operations, purge/grace, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker service, env file, network, CSP connect-src), SUPABASE.md (worker in dev, buckets), RUST.md §3 (R1 loop), WORKSPACE.md, TEST_STRATEGY.md, IDENTITY.md §5 avatar steps, docs/design/README.md (avatar built), CLAUDE.md, CHANGELOG; CI yml untouched beyond a comment (no runner) - [x] 8.8 verify: `pnpm check:all` ×4, PGlite + real stack pgTAP (140 / 420), types unchanged, worker image + sandbox tests, e2e ×7, Chromium smoke 18/18, verifier CONFORME (pass 2), security PASS after 5 passes (BLOCK on my ceiling join fixed: bytes-present ceiling + 64 MiB per-account budget); BDR-048, LRN-051, EVAL-019, journal. OPEN: owner manual validation; owner runs `gitflow finish` for feature/rust-r0-foundation then, after validation, for this branch; `.env.worker` to create by hand (DEPLOY.md); residual LOWs documented in STORAGE.md §2.1 (colluding-account ceiling fill, search-domain on native glibc runs, ceiling race) + - [x] 8.9 owner validation 2026-10-13: 10/10 manual + graphic → R0 (5cfb6f1) and R1 (f5865f0) finished into develop; identity + environments + LAN rule → BDR-049 +- [ ] chore/dev-lan-access (2026-10-13): DEV origin centralised (`scripts/dev-env.sh`, `pnpm supabase` wrapper, `pnpm dev` on the LAN, config.toml env()), ENVIRONMENTS.md; automated 26/26 at http://192.168.1.100 (computer + phone viewports, URL audit); AWAITING owner's validation from their own devices + firewall decision (54322 loopback, 54323/54324 subnet) before finish - [ ] Rust by default (rule adopted 2026-10-12, BDR-043; orientation + 10 principles VALIDATED by the owner 2026-10-12, BDR-044; study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 + Annex A decision table + Annex B R0 scope on chore/step-08-files-analysis; AWAITING the owner's validation of decisions D-R1..D-R14 (D-R6 withdrawn); R0 and Step 8 NOT started until then). Roadmap (each phase: oracles frozen with the old code, consumer-driven deletion, rollback row, gates): - [ ] R0 foundation (GO 2026-10-12, BDR-045; branch feature/rust-r0-foundation; Annex B; owner constraints: builds reproducible in Docker, no Rust on the VPS, live deployment untouched, frontend never loads the module, no R1): - [x] R0.1 toolchain: `docker/rust-builder.Dockerfile` (rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy), `docker/rust-run.sh` (named volumes faunosteo_cargo_registry / faunosteo_rust_target), `docker/rust-check.sh`, `docker/wasm-build.sh` (CLI/crate version lock), root scripts rust:builder / rust:check / wasm:build / worker:test / worker:image From 3e48b0d848b4633f0ca507b367cfb65dc1b70261 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 22:38:40 +0200 Subject: [PATCH 3/7] =?UTF-8?q?chore(workspace):=20DEV=20least-privilege?= =?UTF-8?q?=20exposure=20=E2=80=94=20nginx=20DEV=20gateway=20(API=20on=20t?= =?UTF-8?q?he=20LAN,=20Mailpit=20behind=20basic=20auth),=20network=20check?= =?UTF-8?q?=20from=20a=20distinct=20origin,=20loopback=20default=20for=20t?= =?UTF-8?q?he=20rootless=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