docs(docs): Step 8 / R1 — files foundation, worker loop, avatar: CLAUDE, DEPLOY (.env.worker, CSP), SUPABASE, RUST, TEST_STRATEGY, WORKSPACE, IDENTITY §5, design README, plan as-built note, CHANGELOG; R1 plan and verifier contract

This commit is contained in:
bchanot committed 2026-10-13 19:39:52 +02:00
1 parent 0c6053c174
commit 62eb4e5d82
13 files changed
+235 -35

No files matched your search

+11 -1
View File
@@ -18,7 +18,7 @@ by side until the plan's Step 14 decides what goes behind authentication.
| `/reset-password` | none; needs the recovery session | new password ×2; "invalid or expired link" otherwise |
| `/auth/callback` | none | landing of OAuth redirects and confirmation links; waits for the session then goes to `/app` (or `?next=`) |
| `/app` | `RequireAuth` | dashboard: greeting, profile completeness card, local tool card, account card |
| `/app/account` | `RequireAuth` | Mon compte: personal, professional, preferences (language, timezone), security (password, MFA note, sign out) |
| `/app/account` | `RequireAuth` | Mon compte: profile photo (Step 8, `STORAGE.md` §4), personal, professional, preferences (language, timezone), security (password, MFA note, sign out) |
`RequireAuth` waits for the client to read the persisted session, then sends
a visitor to `/login?next=<path>`; `next` is honoured only when it is a
@@ -126,6 +126,16 @@ VITE_AUTH_PROVIDERS=google pnpm dev
password → `/app`; sign out and sign in with the new password.
9. REST: anon cannot read profiles (`42501`), alice reads one row only
(SUPABASE.md §8).
10. Profile photo (Step 8, worker container running: `pnpm worker:image`
then `docker compose --profile worker up worker` or the container of
`scripts/avatar-e2e.sh`): Mon compte → Modifier la photo with a phone
JPEG → preview → Enregistrer → "Traitement en cours…" → the photo in the
circle, the sidebar, the drawer (mobile) and the top bar (name beside it
on desktop, alone on mobile) linking to Mon compte; a renamed PNG is
accepted, an HTML or SVG file is refused at the picker; replace, then
Supprimer la photo → confirmation → monogram; sign in as bob: nothing of
alice shows; open the object path of alice's photo in a private window
→ 400.
Automated: `pnpm test:run` (auth store, locale sync, forms, guards, shell,
dashboard, account, pgTAP 009), plus the headless end-to-end run described in
+11
View File
@@ -238,6 +238,17 @@ Definition of Done: all eight buckets exist and are private; architecture §15.1
Risks: direct-to-bucket uploads bypassing the assets row (mitigate: insert policy on storage.objects requires a matching assets row).
```
Step 8 as built (2026-10-13, `STEP8_FILES_ANALYSIS.md` D1–D9 + Rust R1,
`STORAGE.md`): the server-side processing is the Rust worker `crates/worker`
(the plan's `apps/worker` of Step 19 arrives early, in Rust, with one job
family); there is no `issue_signed_url` RPC (the Storage API signs after the
SELECT policy; the owner-only avatar is downloaded under RLS, no signed URL);
the SVG sanitiser and the user SVG upload path move to Step 13 with their
producer (the allowlist sanitiser already exists in `packages/pdf`); the
avatar pointer is derived from the single clean `assets` row (no
`profiles.avatar_asset_id`); the sheet bucket keeps its name
`anatomical-sheet-assets`.
```text
Step 9 (∥ Step 10)
Name: Professional verification
+43 -13
View File
@@ -1,12 +1,13 @@
# Rust in the Faunosteo monorepo
Status: plan R0 (foundation), 2026-10-12, on `feature/rust-r0-foundation`. Rule
and roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III
boundary rules, Part VI phases R0–R5, Annex B R0 scope, Annex C owner
amendments). R0 ships the toolchain, the workspace skeleton, the worker's
sandboxed child, the browser module loader and seven experimental proofs. No
application behaviour, interface, archive or database changes; the frontend
does not load the module before R2; the worker's job loop arrives at R1.
Status: plan R0 (foundation, validated 2026-10-13) and R1 (the Step 8 worker,
2026-10-13, `feature/step-08-files-foundation`). Rule and roadmap:
`RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III boundary
rules, Part IV the worker, Part VI phases R0–R5, Annex B R0 scope, Annex C
owner amendments). R0 shipped the toolchain, the workspace skeleton, the
worker's sandboxed child, the browser module loader and seven experimental
proofs; R1 ships the worker's job loop and sweeper for the avatar pipeline
(`STORAGE.md` §3). The frontend does not load the browser module before R2.
## 1. Toolchain: native on the development machine, reproducible in Docker, never on the VPS
@@ -141,11 +142,36 @@ under a 10 s CPU limit.
module each time (cache-busting import of the glue), `callCore()` parses
the envelope, `isCoreBuilt()` lets the proofs skip when `pkg/` is absent.
## 3. The worker (R0 skeleton, R1 job loop)
## 3. The worker (R0 sandboxed child, R1 job loop)
`faunosteo-worker` is one static musl binary with subcommands dispatched by
a plain `main` (no async runtime, no thread), so `decode` installs its
sandbox in a single-threaded process:
sandbox in a single-threaded process. R1 (Step 8) adds the keyed parent:
`run` polls `claim_avatar_jobs` through PostgREST every 2 s, downloads the
quarantine object, feeds it to a `decode` child, uploads the 512 × 512 WebP
at the final key, commits the row (`complete_avatar_job` with the lease
token), deletes the quarantine object, and sweeps (expired uploads, the
purge queue, quarantine leftovers) every 10 minutes. Modules: `config` (env,
secret newtype that no Debug output prints, JWT expiry), `log` (JSON lines,
field allowlist, child stderr escaped and cut at 200 bytes), `keys` (strict
four-segment key shapes validated before any URL), `backend` (trait, closed
`BackendError`), `http` (ureq 3 on rustls + ring with the bundled roots, 30 s
global / 5 s connect timeouts, no redirect, `P0001` bodies → closed
refusals, the Storage API's HTTP 400 + `statusCode` 404 → 404), `decoder`,
`job` (the STORAGE.md §3.4 mapping), `sweep` (§3.5), `watchdog` (per-stage
deadlines, exit 21 on overrun; `Broken` child → exit 20), `run`
(`WORKER_ONCE`, `--check`). Library choice recorded against the review's
Part V list: `ureq` instead of `tokio` + `reqwest`, hand-written JSON lines
instead of `tracing`, a 25-line base64url decoder instead of `base64`: the
loop is sequential, nothing needs an async runtime, and the keyed process
keeps a smaller dependency tree (34 → 84 crates, `aws-lc-rs` absent, no
cmake on Alpine). The decode child's traced syscall set did not change with
the parent's TLS code (§5.4 re-run at R1: the same seven). Image 11.6 MB
(8.7 MB at R0: ring + rustls). Tests: `crates/worker/tests/job_loop.rs` (11,
fake backend + fake decoder) and the module unit tests run natively; the
real-stack end-to-end runs through `pnpm e2e:avatar` (`STORAGE.md` §6).
The sandboxed child, unchanged from R0:
- `decode`: refuses a non-empty environment; checks `Threads: 1` in
`/proc/self/status`; disables core dumps (`PR_SET_DUMPABLE 0`,
@@ -181,8 +207,10 @@ sandbox in a single-threaded process:
child's stderr (≤ 4 KiB) is child-controlled text: R1 never logs it raw
(LRN-044).
- `run --check`: prints the resolved configuration without secrets (which
variables are set, the linked libwebp version, refused below 1.6.0). A
plain `run` does nothing before R1 and says so.
variables are set, the linked libwebp version, refused below 1.6.0, the
JWT expiry of the service key); exit 0 when startable or when no worker
variable is set at all, 2 on a partial configuration. `run` starts the loop
(STORAGE.md §3.2 for the variables).
- `version`: binary, workspace and libwebp versions.
- test hooks (`--features test-hooks`, never in a release build): fixtures
generated in memory (no binary in git), `--no-seccomp` (rlimits only,
@@ -406,8 +434,10 @@ pnpm check:all # everything above bu
- The browser-side fresh-instance mechanism (static glue URL with a
cache-busting query under Vite, or a Worker per instance) is designed, not
built: R2 builds and tests it.
- HTTPS from the worker (CA bundle of distroless, `webpki-roots`): no HTTP
client in the R0 binary; R1 adds `reqwest` and the CI HTTPS call.
- HTTPS from the worker: R1 links `ureq` with rustls and the bundled
`webpki-roots` (distroless has no CA bundle; none is needed), but every
run so far targets the local stack over plain HTTP on the Docker network;
the first managed (HTTPS) target proves the roots.
- The forge runner's cache and timings (§5.7), and the workflow files
themselves: no runner exists, none of the three workflows has ever run
(§4).
+22 -2
View File
@@ -16,7 +16,9 @@ supabase/
│ ├─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs
│ ├─ 20261008110100_private_execute_hardening.sql EXECUTE revoked from PUBLIC on the Step 3 helpers
│ ├─ 20261009100000_sheet_asset_storage.sql bucket anatomical-sheet-assets + read policy through the sheet
│ └─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks
│ ├─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks
│ ├─ 20261011100000_profiles_professional.sql practice_name, professional_title, siret
│ └─ 20261013100000_files_foundation.sql assets table, seven private buckets, avatar policies through assets, purge queue, browser + worker RPCs (STORAGE.md)
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine`
│ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input)
@@ -28,7 +30,9 @@ packages/supabase/
├─ src/client.ts createBrowserClient() (anon key, PKCE)
├─ src/database.types.ts `supabase gen types` output
├─ src/anatomical-sheets.ts publishSheetVersion(): Zod + integrity gate before the RPC
└─ tests/db/ PGlite harness: runs the pgTAP files without Docker
├─ src/assets.ts avatar flow: begin / quarantine upload / confirm / remove / own state / download, closed AssetFailure kinds
├─ tests/db/ PGlite harness: runs the pgTAP files without Docker
└─ tests/e2e/ real-stack end-to-end (avatar flow with the worker container), `pnpm e2e:avatar`
packages/domain/
└─ src/anatomical-sheet/ canonical sheet document (Zod), validateSheetDocument, createEmptySheetDocument
```
@@ -109,6 +113,22 @@ uploading, keeps objects already present, and calls
read policy ignores a row whose upload was never confirmed, so a user who
registers a known hash on their own sheet opens nothing.
### 3.2 Files worker (Storage, Step 8)
User files land in private buckets and are processed by the Rust worker
(`crates/worker`, `docs/development/STORAGE.md`). Against the local stack:
```bash
pnpm worker:image # faunosteo_worker:dev
pnpm e2e:avatar # starts the container on supabase_network_faunosteo, runs tests/e2e, stops it
docker compose --profile worker up worker # the same container from docker-compose.yml, reading .env.worker
```
`.env.worker` (not editable by the assistant): `SUPABASE_URL=http://supabase_kong_faunosteo:8000`,
`SUPABASE_SERVICE_ROLE_KEY=<the service key of pnpm supabase status>`, `WORKER_ID=dev`.
The service key stays in that file and in the shell; it never reaches the
app `.env`, env.js or a commit.
Seed accounts (local only, password `LocalDev-only-password-1`):
| Email | Role |
+3 -1
View File
@@ -19,7 +19,9 @@ Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
| SQL/TS contract | generated types diff check | CI | every PR touching `supabase/` |
| Rust core and facade | `cargo test` (unit + fixture tests reading the repository JSON in place), `clippy -D warnings`, `cargo deny`; ts-rs types drift check | `crates/*`, `pnpm rust:check` (native, `scripts/rust-check.sh`; same file in the builder image), `pnpm check:all` | before every Rust commit and every merge; CI job `rust` prepared, no runner yet |
| Rust/TS contract | vitest proofs on the built module: byte equality with `JSON.stringify(…, null, 2)` on the real documents, optional/nullable shape read by the current Zod schemas, panic and stack traps, served size budget | `packages/core-wasm/tests` (skipped with a notice when `pkg/` is absent) | `pnpm check:all` (after the native `wasm:build`); CI `check` prepared |
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests`, Dockerfile stage `test` (`pnpm worker:test`, Docker only, never native) | every `crates/worker` commit, `pnpm check:all`; CI `docker` job prepared |
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests/sandbox.rs`, Dockerfile stage `test` (`pnpm worker:test`, Docker only, never native) | every `crates/worker` commit, `pnpm check:all`; CI `docker` job prepared |
| Worker job loop | native unit tests on a fake backend and a fake decoder: call order claim → download → decode → upload → commit → purge, every child outcome mapped to a closed code, no deletion on a refused commit, lease left on transport failures, sweeper targets and acks, key validation, config and secret redaction | `crates/worker/tests/job_loop.rs`, `crates/worker/src/*` unit tests (`pnpm rust:check`) | every Rust commit |
| Files e2e (real stack) | the worker container against the local Supabase stack: clean upload and owner-only download (Bob, anon, quarantine, direct final-key write refused), replacement and purge after the grace (queue clock shifted through psql), late signed-upload bytes swept, hostile uploads rejected with closed codes, removal and drained queue | `packages/supabase/tests/e2e/avatar-flow.e2e.ts` (`pnpm e2e:avatar`, `scripts/avatar-e2e.sh`) | every Storage, worker or avatar change; not in `check:all` (needs the stack) |
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
happy-dom where sufficient and under Playwright when real rendering matters
+1
View File
@@ -94,6 +94,7 @@ works as `corepack pnpm <cmd>`.
| `pnpm build` | typecheck + Vite build in every package |
| `pnpm check` | typecheck, test:run, lint, build in sequence (the Node gate) |
| `pnpm check:all` | the whole pre-merge gate: native Rust check, types drift, wasm build, `pnpm check`, application and worker images (`docs/development/RUST.md` §4; no CI runs it yet) |
| `pnpm e2e:avatar` | real-stack end-to-end of the avatar flow: worker container against the local Supabase stack + `packages/supabase/tests/e2e` (`docs/development/STORAGE.md` §6; needs `pnpm db:start`) |
| `pnpm format` | Prettier on the whole repository |
Package-scoped: `pnpm --filter @faunosteo/app <script>`.