diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index da5969c1..2c75a0a5 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -354,3 +354,19 @@ Status: active, awaiting user validation of the step. User validated every Step 7 screen and flow (login, signup, recovery, dashboard, account, sidebar + drawer, logout, FR/EN, responsive), no UI correction. Decisions: (1) the mockup file the user produced (`docs/design/faunosteo-etape7-maquettes-validees.png`, 7 views) is the permanent graphic reference for the SaaS shell; `docs/design/README.md` lists what it shows beyond Step 7 with the owning step (Bilans/Clients/Animaux/Agenda/Fiches entries, stat tiles, bell, avatar photo → Step 8, Mon compte tabs, mobile tab bar) so no screen invents them early; a redesign needs a new validated file there. (2) Local-tool Home (`/`) shows no sidebar when signed in, only "Mon espace": accepted until the tool is integrated into `/app` (Step 14). (3) Password rule in the mockup (8 chars) does NOT override the server policy (12 + classes). (4) Follow-ups kept in TODO 7.10: MFA before sensitive admin features, professional verification ≠ SIRET format, real OAuth tests once ids exist, tool integration into /app. Status: closed; Step 7 finished into develop. + +## BDR-043 | 2026-10-12 | Rust by default: permanent language rule + target architecture (study awaiting validation) + +Owner rule: Rust preferred wherever equivalent or better; "already TS", "more work", "no perf gain" never reasons for C. Kept: React/TS UI + DOM + stores + vendor glue, Tailwind, SQL + RLS, Supabase Auth/Storage, Vite tooling. Study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 (61 challenger findings folded). Classification: A = domain contracts/rules, sheet handle + index data, reducers, data-building component rules, publish gate, layer renderer + compose, one SVG sanitiser, PDF reader + writer, CLI tools, curation pipeline + importer, upload script, Step 8 worker, every future backend/rule mirror; B = none; C = React render glue + display helpers, Zustand/storage adapters, supabase-js session + error shapes (no Rust GoTrue PKCE client), UI form schemas + dictionaries, clock/crypto/Intl screen dates, browser rasteriser (DOM), Vite tooling, SQL/RLS, public web (Astro, global rule). Target: 3 crates (`core` feature-gated lib + tool bins, `wasm` facade, `worker` bin), JSON strings across the boundary + `ts-rs` types (no serde-wasm-bindgen: writes absent optionals as null), `SheetHandle` built once, closed error kinds, ids/time injected, panic=abort handled TS-side (poison + reinstantiate), lazy init + `core_unavailable`, reader in terminated Web Worker. Worker: Rust binary, decode child = same binary dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist (Landlock dropped: redundant), pure-Rust decoders (`image`/zune-jpeg/png/image-webp) + `moxcms` ICC, lossy WebP via `libwebp-sys` ≥ 1.6 in the child only, parent parses RIFF header only (never decodes), 512 KiB output cap, per-stage deadlines; service key kept (dedicated role = Step 27 option). Roadmap: R0 workspace + worker image inside Step 8, R1 = Step 8 worker, R2 domain core before Step 9, R3 anatomy, R4 pdf reader + writer (Std14 AFM metrics, draw-log golden frozen first), R5 pipeline + importer + tools, all before Step 13; TTF fonts separate later change. Deploy prerequisites: CSP `'wasm-unsafe-eval'`, gzip wasm, images built in CI pulled by digest (VPS 1 GB never compiles), N-1 reader test, draft quarantine. +Alt rejected: single `core` crate without features (worker would carry pdf deps) → features chosen; 6 crates (rev 1) → too many; resvg in browser (949 KB gz, visual change); wasm-pack (one maintainer, CLI lock); Edge Functions (limits, hand deploy); Prettier-chained sheet identity (hash only compared at runtime → one-time rebase accepted); parent re-decode of child output (breaks keyless-decoder invariant). +Status: active, awaiting owner validation of the study + 13 decisions D-R1..D-R14 (D-R6 withdrawn); nothing implemented; release 0.2.0 untouched. + +## BDR-044 | 2026-10-12 | Rust orientation validated by the owner; detailed decisions D-R1..D-R14 pending + +Owner validated the study's orientation + 10 principles: Rust worker at Step 8; Cargo workspace; native + WASM libs; progressive anatomy migration; PDF migration under complete compatibility proofs; React + PostgreSQL/Supabase kept; testable increments with rollback; no premature deletion of TS still used; fully dockerised, production builds outside the small VPS; WASM vs production CSP proven before activation. Requests: expanded decision table (Annex A), R0 scope with build tools reproducible in Docker and no Rust on the VPS (Annex B), serde/WASM/panic/musl hypotheses verified experimentally when they condition a choice (R0 proofs as permanent tests). Release 0.2.0 still waiting. R0 and Step 8 implementation NOT started until the 13 decisions are validated. +Status: active; awaiting D-R1..D-R14 validation. + +## BDR-045 | 2026-10-12 | Rust review rev 2 validated with amendments; R0 go + +Owner validated D-R1/2/3/7/8/10/11/12/14 as recommended. Amended: D-R4 libwebp C only in the isolated child, parent validates result + limits before use, linked libwebp version known/controlled, no new unmanaged risk; D-R5 fingerprint → canonical JSON (RFC 8785 JCS or strictly defined alternative) independent of formatter, explicit compat with old fingerprints/archives, existing fingerprints untouched, decision prepared for R5; D-R9 Edge Functions → Rust services, shared code but distinct processes (worker vs HTTP endpoints), same image + subcommands, least privilege per service, Supabase Auth keeps OAuth; D-R13 CSP `'wasm-unsafe-eval'` proven experimentally without widening JS permissions, reproducible Docker builds in CI, digest images + rollback prepared, no auto-deploy, no image publication without workflow + validation, VPS never compiles Rust. R0 go per Annex B (7 proofs for real, unverified hypotheses tested, blockers reported not assumed); R1 NOT started without a go; release 0.2.0 pending; live deployment untouched. +Status: closed (owner, 2026-10-12); R0 in progress on feature/rust-r0-foundation. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index d1e7cf7d..a7dca81f 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -122,3 +122,10 @@ Method: contract with 16 criteria (`2026-10-11-step-07-verify.md`) → fresh ver Result: verifier pass 1 ECARTS(2): (a) real gap, `safeNextPath` prefix check let `/\host` and `//host` through (router `location.assign` fallback = open redirect after login) → fixed by resolving against a sentinel origin and rebuilding from parsed parts, 5 new cases; (b) contract regex over-matched other unions (`'google' | 'apple'`, `'fr' | 'en'`) → CHECK scoped. Pass 2 CONFORME 16/16. Security PASS, 1 MEDIUM (same redirect, already fixed) + 4 LOW: 3 closed same session (sign-out failure reported, `reauthentication_needed` phrased, exact prod redirect allowlist documented), 1 pre-existing (TOTP not enforced for staff = documented gap). E2E 20/20. Workspace 763 tests, lint 0, build, docker, real-stack pgTAP 280 green. Anomalies: both gates found the same redirect hole my own tests missed → a prefix check on a URL is never enough, parse it; the auditor misread the sign-out note ("this device") as "everywhere" but the LOW still pointed at a silent failure path worth phrasing. Mockups validated with ChatGPT are not in the repo: the screens follow the written direction and the existing tokens, pixel fidelity unverifiable here. Action: awaiting user validation of Step 7 (manual procedure IDENTITY.md §5); release/0.2.0 still open for the human go. + +## EVAL-016 | 2026-10-12 | Rust-by-default architecture review — 4 analyzers + 3 researchers + 3 plan-challengers + +Method: 4 read-only analyzers (domain, anatomy, pdf + app pdf side, app logic + supabase) wrote factual inventories to the scratchpad; 3 general-purpose researchers verified crate versions/maintenance/advisories and Supabase facts on crates.io, RustSec, GitHub, supabase docs (2026-10-12), UNVERIFIED items listed; study rev 1 written from them, committed (6a078da); 3 plan-challengers (correctness FATAL(11), robustness FATAL(11), simplicity CONCERNS(9); 61 findings) → rev 2 with 56 folded, 2 declined with reasons (§0.2). +Result: real blockers caught by the gates, not by me: (1) VI.4 deleted TS modules still imported by later-phase TS consumers (pipeline, engine); (2) production CSP `script-src 'self'` refuses wasm, VPS 1 GB compiles images; plus wrong premises: envelope byte-parity (integer-valued floats, insertion order), Prettier identity overstated (hash only compared), `catch_unwind` unusable on wasm32 (panic=abort), serde-wasm-bindgen null-for-absent, parent re-decode breaking the keyless invariant, Step 15 misread as server rendering. Simplicity: 6 crates → 3, dual-run harness → frozen goldens, Landlock + 3 rlimits redundant, constraints generator/schemars/cargo-chef/cargo-audit/infer/img-parts dropped. +Anomalies: one analyzer had a read-only `find -exec cat | wc -l` refused (no rule named) and re-ran as `find | xargs wc -l` (already allowed earlier) — reported to the user as a possible workaround; agents flagged writing report files to the scratchpad against their default (orchestrator asked for it). Three challenger claims came from memory not code (json_compatible null, panic=abort, musl mprotect) → folded as "verify at R0/R1". +Action: owner validates study + D-R1..D-R14; nothing implemented; CLAUDE.md rule section added; TODO roadmap lines. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index e7292b8f..89400a6f 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -219,3 +219,12 @@ User: mockups validated (external, not in repo), implement Step 7 on a branch. f ## 2026-10-12 (Step 7 closure) User validated Step 7 (all screens, flows, FR/EN, responsive; Home-without-sidebar accepted). Mockup file dropped at root → `docs/design/faunosteo-etape7-maquettes-validees.png` + README (deltas vs step, owning steps); CLAUDE.md design-reference rule; IDENTITY.md pointer. BDR-042; TODO 7.10 follow-ups (MFA gate, verification ≠ SIRET, OAuth real tests, tool integration). Final check green; gitflow finish into develop. Next: Step 8 files foundation, awaiting user go (Q2 hosting/edge-runtime decision shapes the SVG sanitizer). + +## 2026-10-12 (Step 8 analysis) + +User: Step 7 closed; Step 8 = files foundation + Storage, analysis before implementation; Q2 settled (self-hosted first, managed later); 8 private buckets closed by default; quarantine + server validation; allowlist SVG; avatar in Mon compte; release 0.2.0 kept = Steps 3–6, identity → 0.3.0, check deploy triggers before finishing. Done on chore/step-08-files-analysis: docs/development/STEP8_FILES_ANALYSIS.md (assets table authority, server-built keys, quarantine prefix, worker `faunosteo_worker` sharp + pdf sanitiser, policies through assets, Storage API signing under RLS, sweeper/reconcile, file volume + restic backups, managed migration by rows, 10 security answers, scope, tests, risks, D1–D8); 3 plan-challengers dispatched. Release check: CI on push main/develop only, no tag trigger, no deploy job; hooks push only; VPS deploy manual; default 0.2.0 build has no sheet → never redeploy the live tool from main without SHEET_BUNDLE=draft. Awaiting user: D1–D8 + Step 8 go; release finish go. + +## 2026-10-12 (Rust-by-default review) + +User: new permanent rule, Rust preferred for everything equivalent or better, existing code included; study + roadmap before Step 8 or any migration; nothing implemented. On chore/step-08-files-analysis: 4 analyzers + 3 researchers (scratchpad reports) → `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 1 (6a078da) → 3 plan-challengers (61 findings, 2 blockers: deletion schedule vs surviving TS consumers; CSP/VPS deployment facts) → rev 2 folded. Outcome: A/B/C classification (B empty), 3-crate workspace, Rust worker design (keyless parent, traced seccomp, libwebp in child), roadmap R0–R5 with end criteria + rollback rows, 13 decisions D-R1..D-R14. Memory: BDR-043, LRN-048, EVAL-016; CLAUDE.md "Rust by default" section; TODO Rust block. No cargo on the dev host (owner installs rustup at R0). Awaiting owner validation; release 0.2.0 untouched. +- Same day: owner validated the Rust orientation (10 principles, BDR-044), asked the expanded decision table + R0 scope before validating D-R1..D-R14 → Annex A (13 decisions: recommendation, alternatives, pros/cons, risks, consequence, impact tags) and Annex B (R0: Docker builder image as the reference toolchain, rustup optional locally, workspace skeleton, worker image, CI job, 7 experimental proofs kept as tests, exit criteria) appended to the review. Nothing started; awaiting the 13 validations. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index b44d7872..ee3c8c58 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -357,3 +357,8 @@ Apply: any pipeline extraction (Step 13 Supabase provider, Step 14 worker); any Step 7 facts worth keeping. (1) `client.auth.initialize()` is public and idempotent: await it at store start to catch the URL exchange error (expired/foreign link) that `onAuthStateChange` never reports; `INITIAL_SESSION` ordering vs that promise is not guaranteed → a callback route landing signed-out = failure, don't wait for a flag. (2) PKCE confirmation/recovery links only open a session in the browser that made the request (verifier in its localStorage); the email is still confirmed server-side → phrase it ("opened in another browser… just sign in"), don't claim expiry. (3) supabase-js 2.117 `AuthError.code` (`invalid_credentials`, `user_already_exists`, `weak_password`, `otp_expired`, `bad_code_verifier`…) → map to a closed union in the access layer, UI translates `auth.failure.`; raw messages never rendered. (4) Account load must run outside the auth callback (`setTimeout 0`): the client serialises callbacks, awaiting a request inside deadlocks. (5) pgTAP: `select is((with upd as (update … returning 1) select count(*) from upd), …)` fails ("data-modifying CTE must be top level") and silently breaks the plan count; use `lives_ok` + a read after `reset role`. (6) Mailpit API (`/api/v1/search?query=to:`, `/api/v1/message/`) makes the confirmation + recovery flows scriptable headlessly; playwright-core installed in the scratchpad + cached `ms-playwright` chromium via `executablePath` = no project dependency. Apply: every future Supabase auth surface (Step 14 gating, invitations), any pgTAP write assertion, any e2e of email flows. + +## LRN-048 | 2026-10-12 | Before porting a module, list the hidden serialisation contracts; goldens on drawn primitives make an engine swap provable + +Context: Rust review inventories. Facts found: `documentSha256` = sha256 of Prettier-formatted text (only compared at runtime → mismatch = rebase, not loss); coordinates = raw JS number strings (serde_json prints `1523.0`); attachment = insertion-order JSON, snapshot = Zod schema order; `.optional()` absent vs nullable `null` (serde-wasm-bindgen json preset writes null → breaks readers); text x positions = AFM widths + kerning pairs; dates = ICU; `toUpperCase`, `/\s+/`, non-fatal TextDecoder, last-dup-key JSON.parse, Zod `.int()` accepting 2.0. The 39 PDF goldens record draw calls (spies), never bytes → a Rust engine with a draw-log layer can match them exactly; byte goldens (xmldom XMLSerializer, Prettier files) cannot be matched by another stack → compare parsed trees or regenerate by decision. +Apply: any port (R2–R5): freeze unpinned outputs with the old code (LRN-046), write the contract list with a fixture each, decide lenient-vs-strict per item, keep an N-1 reader test permanently. Challengers found 2 blockers rev 1: deletion schedule vs surviving consumers (name the last consumer per module), and deployment facts (CSP without 'wasm-unsafe-eval', VPS compiling images) → check the serving path before the language. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 87768c48..b09f3a57 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -126,6 +126,23 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 7.8 tests: config, authStore (fake client), locale sync, forms, guards, shell, dashboard, account; i18n parity; pgTAP 009 (PGlite + real stack 280/280); root check + docker build green; headless e2e vs local stack 20/20 (signup via Mailpit, recovery, logout, mobile) - [x] 7.9 docs (IDENTITY.md, SUPABASE.md, CLAUDE.md, CHANGELOG, plan note); memory BDR-041, LRN-047, EVAL-015, journal; gates: verifier ECARTS(2) → open-redirect fix + contract CHECK → CONFORME 16/16; security PASS (MEDIUM fixed, 3 LOW closed, TOTP enforcement = documented gap). User validated 2026-10-12; user action still open: `.env.example` += `APP_AUTH_PROVIDERS=` (file edit denied here) - [ ] 7.10 follow-ups kept by the user (2026-10-12), each owned by a later step: MFA mandatory before any sensitive admin feature (has_mfa helper + enrolment UI, IDENTITY.md §4; first admin screen); professional verification distinct from the SIRET format check (Step 11); real tests of Google and Apple once the provider ids exist (config.toml env(), APP_AUTH_PROVIDERS); integration of the report tool into the signed-in /app space (Step 14 gating); mockup elements not built yet listed in docs/design/README.md (bell, avatar photo → Step 8, stat tiles, tabs, mobile tab bar) +- [ ] Step 8 — files foundation + Supabase Storage (analysis 2026-10-12 on chore/step-08-files-analysis: docs/development/STEP8_FILES_ANALYSIS.md; 3 plan-challengers (47 findings folded, rev 2); AWAITING USER DECISIONS D1–D9 + go; nothing implemented). User brief: 8 private buckets closed by default, quarantine + server validation, allowlist SVG, avatar in Mon compte (upload/preview/replace/delete/header), JPEG/PNG/WebP ≤ 5 MB resized + metadata stripped, no SVG avatar, service role never in the browser, portable self-hosted → managed, allowed + denied access tests + - [x] 8.0 analysis: facts (existing bucket + policy pattern, sanitiser, edge runtime off, CSP, deploy), design (assets table authority, server-built keys, quarantine prefix, worker `faunosteo_worker` with sharp + pdf sanitiser, storage.objects policies through assets, Storage API signing under RLS, sweeper/reconcile, backups file volume + restic, managed migration by rows), 10 security answers, scope, tests, risks, D1–D8 + - [ ] 8.1 migration 20261012100000_files_foundation (asset_status, assets, 7 buckets, avatar predicates, avatars policies, purge queue + triggers, storage ceiling, 9 RPCs, revokes) + pgTAP 010 allowed/denied + policy census (one bucket literal per policy) + 001 census + types regen + - [ ] 8.2 worker → SUPERSEDED by Rust R1 (RUST_ARCHITECTURE_REVIEW Part IV, D1 = native Rust worker): `crates/worker` keyed `run` loop + keyless `decode` child, lease claim, PUT→complete→DELETE order, sweeper (purge queue + quarantine by key), per-stage deadlines, Dockerfile (distroless/static) + compose service (read-only, cpus 1, internal network) + .env.worker.example, fixtures + sandbox tests on the production image, local-stack integration test + - [ ] 8.3 packages/supabase assets service (begin/upload/confirm/remove/fetchOwnAvatar/downloadAvatar, closed failure kinds; no signed URL) + - [ ] 8.4 app: avatar block in Mon compte (picker, canvas ≤1024 JPEG transport, preview, save, processing, supersede, delete), UserBadge photo, top bar avatar (D3), authStore blob URL, i18n, tests; design toolchain + impeccable detect + - [ ] 8.5 docs: STORAGE.md (model, keys, statuses, purge/grace rules, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker, env file, network, CSP connect-src), SUPABASE.md, CLAUDE.md, CHANGELOG, plan note (worker early, SVG processor → Step 13); CI jobs + - [ ] 8.6 verify: root check, PGlite + real stack pgTAP, types, docker builds (app + worker), real-stack e2e (sign allowed/denied), gates verifier + security; memory; stop for user validation +- [ ] 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 (inside Step 8, Annex B): Docker builder image = reference toolchain (rustup optional locally, never on the VPS), Cargo workspace (`crates/core`, `wasm`, `worker` skeletons), toolchain pin, deny.toml, lints, CI job `rust`, worker image started once against the local stack, app wasm stage built but not loaded, `docs/development/RUST.md`, DEPLOY.md (images pulled by digest, CSP `'wasm-unsafe-eval'`, gzip wasm, VPS headroom, rollback = previous digest); 7 experimental proofs kept as tests (wasm panic/re-instantiate, js_number + optional/nullable vs Zod, musl + libwebp build, traced seccomp child, CSP headless, size/instantiate, runner caches) + - [ ] R1 = Step 8 worker in Rust (replaces 8.2 below): decode child dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist, `image` + `moxcms` + `libwebp-sys` in the child, parent RIFF-header check only, 512 KiB output cap, per-stage deadlines, service key + - [ ] R2 domain core (before Step 9): sheet/report/archive contracts, `SheetHandle` + `SheetIndexData`, reducers, Finding builder, vertebra selection, publish gate; wasm facade (JSON strings, ts-rs types, poison + reinstantiate, lazy init); app switched; 3 envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP; `packages/domain` frozen for engine/pipeline + - [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first + - [ ] R4 pdf core: reader (Web Worker, BLK-009 browser measurements) + writer (`pdf-writer`, Std14 AFM, draw log; lines/rects/colours golden frozen with the TS engine first, D-R2) + `report-compare` tool; `packages/pdf` deleted; N-1 scanner reads R4 PDFs + - [ ] R5 curation pipeline + importer + upload tool: seed golden regenerated once (new `documentSha256`, D-R5), `packages/anatomy` + `packages/domain` deleted, docs map; all before Step 13 + - [ ] separate chore (D-R7): form constraints module + PGlite `pg_constraint`/config.toml parity test +- [ ] Release 0.2.0 (branch release/0.2.0 = Steps 3–6, version.txt + package versions 0.2.0, CHANGELOG [0.2.0] 2026-10-11): deploy-trigger check done 2026-10-12 (CI = branches main/develop only, no tag trigger, no deploy job, docker job builds `faunosteo:ci` locally; hooks push only; DEPLOY.md deploy = manual on the VPS). Default 0.2.0 build carries NO sheet (SHEET_BUNDLE=none) → the live local tool must not be redeployed from main without `--build-arg SHEET_BUNDLE=draft`. Finish via /release-candidate (finish + tag span, tag push on explicit go); CHANGELOG back-merge conflict expected (Unreleased Step 7 above [0.2.0]). Awaiting the user's go. --- ## Phase A — DONE (kept for reference) diff --git a/CLAUDE.md b/CLAUDE.md index 07516633..bd05dd49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -424,6 +424,36 @@ Database (Supabase) --- +## Rust by default (rule adopted 2026-10-12, BDR-043) + +Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (awaiting +the owner's validation before any implementation; release 0.2.0 unaffected). + +- Any logic that can run in Rust with no significant loss (features, UX, + graphics, data compatibility, security, reliability, useful performance, + resources, portability, maintainability, operations) is written in Rust: + native for services, jobs and tools, WebAssembly for the browser. + Equivalence suffices; "already in TypeScript", "more work" and "no + performance gain" are never reasons to keep TypeScript. +- Kept as is: React + TypeScript for UI, DOM, routing, Zustand stores, + display formatting and vendor-SDK glue (supabase-js); UI form schemas + (Zod, i18n keys) and dictionaries; Tailwind; PostgreSQL/SQL + RLS; + Supabase Auth and Storage; Vite/ESLint tooling. A component kept in + TypeScript needs the concrete constraint recorded in the review's + exception table (Part II). +- New business logic (rules, data transformations, parsers, validators, + jobs, services, rule mirrors of SQL) is designed in `crates/` first and + reached from TypeScript through the wasm facade; Edge Functions are not + used. Boundary rules: "Rust computes, TypeScript reads" (review Part + III.3: coarse calls, JSON strings, sheet handle, closed error kinds, ids + and time injected, no call in a render path). +- Existing code migrates along the review's phases (R0–R5), each with + oracles frozen with the old code before the switch and a consumer-driven + deletion of the TypeScript it replaces; two implementations never outlive + the phase that switches the last consumer. + +--- + ## Key dependencies | Package | Purpose | diff --git a/docs/development/RUST_ARCHITECTURE_REVIEW.md b/docs/development/RUST_ARCHITECTURE_REVIEW.md new file mode 100644 index 00000000..4b665065 --- /dev/null +++ b/docs/development/RUST_ARCHITECTURE_REVIEW.md @@ -0,0 +1,987 @@ +# Rust by default: architecture review and migration roadmap + +Status: study for the owner's decision, 2026-10-12, revision 2 after three +independent plan challenges (correctness, robustness, simplicity: 61 +findings, 2 blockers; what changed is listed in §0.2). Nothing implemented. +Applies the owner's brief of 2026-10-12: Rust becomes the preferred language +for everything that can reasonably be written in Rust, for new work and for +existing code; equivalence suffices; "already in TypeScript" and "more work" +are not reasons to keep TypeScript; a component kept in another language +needs a concrete constraint. + +Part I states the facts (inventory, the hidden contracts a port must honour, +the state of the Rust ecosystem on 2026-10-12, verified by three research +agents against crates.io, RustSec, GitHub and the Supabase docs). Part II +classifies every module (A now, B later with a trigger, C exception). Part +III is the target architecture (workspace, boundary, bindings). Part IV is +the Step 8 worker in Rust. Part V lists the libraries retained and their +limits. Part VI is the progressive migration with end criteria and rollback. +Part VII adapts the development plan. Part VIII covers Docker, Supabase and +CI. Part IX gives validation criteria and risks. Part X lists the decisions +the owner has to take. §0 states what this study pushes back on and what the +challenges changed. + +Companion material: `STEP8_FILES_ANALYSIS.md` (the design this review keeps, +with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, +`ANATOMICAL_SHEET_MODEL.md` (contracts that stay as they are). + +--- + +## 0. Pushbacks and revision notes + +### 0.1 What this study pushes back on + +1. **Where Rust buys something here.** The browser already runs memory-safe + code, so "Rust is safer" is no argument for the SPA. The gains the study + claims: one core that runs identically in the worker, the CLI tools and + the browser (server-side archive validation at Step 15 needs the reader + the browser has); untrusted bytes (images, SVG, PDF attachments) parsed on + the server with hard allocation caps and without libvips, libpng, xmldom + or UPNG in the trusted base; the removal of three dependencies the + project already distrusts (`pdf-lib` unmaintained since 2021, BLK-009; + UPNG trusting its input; `DecompressionStream` as the only inflater on + every read path); and the unification of what the inventory found + duplicated (two SVG sanitisers, two view compositions, three copies of + the bilingual label fallback in rule code). Screen-only helpers + (`formatDate` for the UI, `pickLabel` in JSX) stay TypeScript and are not + counted as unified. +2. **The rule has a standing cost the project must own.** Two toolchains in + CI and Docker, a WASM boundary to design, debug and keep safe, Rust + skills on a one-person team, oracles to freeze before every switch. Each + cost is made visible (Parts VIII, IX) instead of hidden in "equivalent". +3. **Rust does not remove the SQL mirror.** `private.sheet_document_issues` + stays SQL because managed Supabase runs no custom `pgrx` extension; Rust + replaces the TypeScript side of the pair; the pair itself remains. +4. **The sheet identity hash changes once.** `documentSha256` is today the + sha256 of the Prettier-formatted document text. It is computed once by + the pipeline and only compared at runtime; a different hash sends an old + archive through the rebase path (visible import message, nothing lost), + exactly as any content changeset does. The study therefore does not + chain the pipeline to Prettier (D-R5); it states the one-time effect. +5. **One global rule conflicts with the new one.** The global CLAUDE.md + mandates Astro for public sites; the Rust rule would prefer a Rust static + generator. The study recommends keeping Astro and records the conflict as + a decision (D-R8). +6. **Form validation stays TypeScript by the owner's own retained list** + (code directly tied to React). The constraints themselves are written in + two places today (Zod and SQL CHECKs) and already drift; a small chore + outside this roadmap gives them one home (D-R7). +7. **The production surface decides more than the language.** Two of the + blockers found by the challenges were deployment facts: the documented + CSP refuses WebAssembly, and the VPS (1 vCPU, 1 GB) compiles the images + it runs. Both are fixed in the roadmap before any wasm reaches + production (D-R13, VIII.1). + +### 0.2 Changes after the challenges (revision 2) + +Folded: three crates instead of six (one feature-gated core, one wasm +facade, one worker binary with tool binaries); no throwaway dual-run parity +harness (unpinned outputs frozen as goldens with the old code, oracle suites +ported to cargo on the fixtures in place); consumer-driven deletion schedule +(a TypeScript module is deleted in the phase that switches its last +consumer, frozen and parity-tested in between; revision 1 deleted modules +that later phases still imported); the PDF writer and the curation pipeline +reclassified A with technical dependencies only (revision 1 deferred them +for reasons the brief excludes); a two-call export (compose views, the +caller rasterises, pure writer) that removes the async rasteriser from the +boundary and the need for resvg in the browser; a Rust-owned sheet handle +instead of re-shipping the sheet per click; JSON strings across the boundary +with generated types (no `serde-wasm-bindgen`, whose `json_compatible` +preset would write absent optionals as `null`); panic = abort on wasm32 +handled on the TypeScript side (poison and re-instantiate); lazy wasm +initialisation with a degraded state so the auth shell never depends on the +module; the PDF reader in a Web Worker with the BLK-009 browser measurements +as exit criteria; CSP `'wasm-unsafe-eval'` and gzip for the module; images +built in CI and pulled by digest, never compiled on the VPS; per-phase +rollback rows and draft quarantine instead of silent discard; the keyed +worker parent never decodes (fixed-size read, RIFF header allowlist, no +pixel decode); seccomp allowlist derived by tracing, applied before any +thread exists, Landlock and three rlimits dropped as redundant; worker +credential kept as validated (service key), the dedicated role moved to a +hardening option with its exact prerequisites; display helpers and +`isIdentityComplete` kept in TypeScript; `constraints.json`, `schemars`, +`cargo-chef`, `cargo-audit`, `infer`, `img-parts`, fuzzing-now and the DEV +footer removed; five JavaScript semantics on reader paths added to the +contract list; Step 15 no longer cited as a rendering trigger; decisions +merged from 14 to 13. + +Not folded (with the reason): "split R2 into three gates" is kept as an +option for the implementation contract, since each sub-phase would create a +short-lived TS-to-wasm seam inside the store; "keep the Landlock layer +best-effort" is replaced by dropping it (the seccomp allowlist already +denies every file and process syscall, so the layer would test nothing). + +--- + +## Part I. Facts + +### I.1 Inventory of the existing code + +Sizes are TypeScript lines (`wc -l`, `.d.ts` excluded), HEAD `aae0b39`. +Test counts are static (`it` plus `.each` rows) except where a suite was run. + +| Unit | Source | Tests | Runs where | Purity today | +|---|---|---|---|---| +| `packages/domain` | 18 files, 2,298 lines; zod 3.25 only | 9 files, 162 cases (194 at runtime, one file re-imports another) | browser (app), engine, pipeline, scripts | pure: no `JSON.stringify`, no `Date`, no ids, no I/O; host APIs `structuredClone`, `TextEncoder`, `Object.hasOwn`, `new URL()` via Zod | +| `packages/anatomy` | 43 files, 4,897 lines: legacy importer 1,842, curation 2,329, render 553, cli 119 | 15 files, 130 cases (run: 130/130) | **render only** at application runtime (app canvas, PDF composition); the other 4,344 lines run for `pnpm import:equine`, the pipeline and tests | render is pure (plain `LayerElement` tree); importer and pipeline use xmldom, `node:fs`, `node:crypto`, Prettier | +| `packages/pdf` | 27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom | 9 files, 137 cases | browser (export, import), CLI, tests | explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: `DecompressionStream` on every read path and in the PNG gate, `Intl.DateTimeFormat`, `TextEncoder/Decoder` | +| `packages/supabase` | 949 lines (596 generated `database.types.ts`) + `scripts/upload-sheet-assets.ts` (99 lines, operator, service key) | 6 files; PGlite harness runs 9 pgTAP files, 280 assertions | browser, CI, operator | two rules only: GoTrue code → closed `AuthFailure` kind (23 → 13), publish gate (Zod + `assertPublishable` before the RPC); the rest wraps supabase-js | +| `apps/app/src` logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) | 37 files, 2,476 lines (1,708 without the two 281-key dictionaries) | 42 files, 214 cases + 7 `.each` blocks | browser | `services/zoneInteraction.ts` (213 lines) pure; stores are Zustand glue around domain calls; `drawing.ts` is DOM (DOMParser, importNode) with an app-local denylist sanitiser | +| `apps/app/src` UI (components, routes, styles) | 65 files, 4,838 lines | component and route suites | browser | React; carries some data-building rules (I.2) | +| `apps/app/src/pdf` + `scripts/` | 4 files, 235 lines + 2 files, 549 lines | 65 PDF-related app cases + 11 CLI cases | browser / Node | branding from bundled logos, `Image` + canvas rasterizer; CLI `report:compare` on the engine scanner | +| `apps/app/vite/sheet-bundle.ts` | 102 lines | 7 | Vite build | virtual module embedding ~510 KB of seed JSON | +| `supabase/` | 7 migrations, 9 pgTAP files, seed | 280 assertions (PGlite and real stack) | PostgreSQL | SQL; stays | + +Workspace total at the Step 7 closure: 763 vitest cases, lint 0, build and +Docker green. + +### I.2 Hidden contracts a port must honour + +These facts decide feasibility, not the line counts. Each one gets a fixture +or a golden before the phase that touches it (Part VI). + +| Contract | Where | Consequence for Rust | +|---|---|---| +| `documentSha256` = sha256 of the Prettier-formatted lean document text, computed once by the pipeline (`pipeline.ts:163`, `format.ts`), only **compared** at runtime (`rebase.ts:119`, `envelope.ts:100`, pdf `export.ts:88`); a mismatch sends the report through `rebaseReportOnSheet`, which keeps every datum and flags only ids the sheet lacks | `packages/anatomy`, every Report v3 `sheet.documentSha256` | identity = sha256 of whatever bytes the pipeline emits; when the Rust pipeline emits different bytes, the hash changes once and every older archive rebases on import, as after any content changeset (D-R5) | +| Generated coordinates and layer attributes are raw JS number strings (`1715.4285714285713`, `"1118"`, `"0.85"`); `CoordinateSchema` is `z.number().finite()` and most values are integer-valued floats (`"cx": 1523`) | pipeline outputs, review SVGs, layer attributes, snapshot in the archive | `serde_json` prints `1523.0`; a `js_number` formatter (shortest round-trip, JS rules for `.0`, `-0`, exponents at 1e21 / 1e-7) is installed as a custom `serde_json::Formatter` for **every** JSON output and used by the SVG serialiser; tested on the committed overlays | +| Attachment JSON: `report`, `branding` and `labels` are serialised in **insertion order** as passed (pdf `export.ts:112-115`); only the snapshot is re-parsed (Zod schema order); zones are built `{annotationId, viewId, labelFrSnapshot, labelEnSnapshot, side}` with `vertebrae` appended last | engine, store reducers | the attachment bytes change at R2 when Rust emits struct-ordered objects: declared as a new contract (D-R11); what must hold is that every previous reader (the shipped Zod schemas, frozen as a test fixture) parses what Rust writes | +| Optional vs nullable: `.optional()` fields are **absent** when unset (`side`, `unresolved`, `severity`, `nextAppointment`), `versionId` is required and `null` for bundled-draft reports | `packages/domain/src/report/v3.ts` | per-field serde attributes (`skip_serializing_if = "Option::is_none"` for optional, plain `Option` for nullable); a boundary that writes absent as `null` breaks every existing reader | +| Text layout x positions depend on `widthOfTextAtSize`, which sums AFM widths **plus kerning pairs**, while `drawText` writes unkerned glyphs | engine render, 39 goldens (12 text, 12 images, 12 links, 3 views) | the Rust engine embeds the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so exact reproduction is provable | +| Dates through `Intl.DateTimeFormat` (ICU): `11 octobre 2026`, `November 20, 2026`, UTC; `Date.UTC` maps years 26–99 to 19xx | `packages/pdf/src/render/dates.ts` | explicit fr/en month tables; the two-digit-year quirk is decided (tighten) with a fixture | +| `toUpperCase()` on labels before `safeText`; `wrapLines` splits on `/\s+/` (keeps a trailing empty word; JS `\s` ≠ `char::is_whitespace` on U+FEFF, U+0085) | engine | same Unicode upper-casing in Rust; whitespace class written explicitly; fixtures for both | +| Reader leniency: `TextDecoder` non-fatal (invalid UTF-8 → U+FFFD, BOM stripped, `scan.ts:498`); `JSON.parse` keeps the last duplicate key; Zod `.int()` accepts `2.0` | engine reader, domain | `serde_json` rejects all three; each is decided (keep lenient with a custom step, or tighten) and pinned by a hostile fixture before R4 | +| One inflater: `DecompressionStream('deflate')` on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size | engine read path, branding | `miniz_oxide` bounded inflate replaces it everywhere (no Web API on the read path) | +| Two sanitisers: app canvas denylist (`drawing.ts`: 5 tags, `on*`, `javascript:`) and engine allowlist with caps; the engine's "zero-removal" oracle is xmldom's own re-serialisation | app vs engine | one Rust sanitiser; the oracle becomes a DOM-equivalence check (parsed trees compared), not bytes | +| Two view compositions: `composeViewSvg` mutates an xmldom element passed by the engine; the app composes with the browser DOM; the `review/app-*.svg` byte goldens are xmldom `XMLSerializer` output (declaration, whitespace nodes, `xlink:` prefixes) | engine vs app vs pipeline | one Rust `compose_view_svg` for app and engine; the xmldom-byte goldens stay owned by the TS pipeline until R5, where their regeneration is a decided change | +| `buildSheetIndex` returns ten closures over four private `Map`s and the whole `LoadedSheet` (296 KB document, 130 KB drawing, 84 KB map), called per render by ~14 modules and taken by the reducers | domain sheet-index, app | the sheet lives once in Rust memory as a handle; React reads a precomputed plain-data index (names, node-by-path) built once | +| Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (codes only) and adds 3 of its own | domain `validate.ts`, migrations | the Rust validator takes the TS role; SQL stays; conformance fixtures carry two expectation sets (Rust: codes + paths; SQL: codes) | +| `instanceof` on three domain error classes in pdf and app scripts | domain errors | closed kind discriminants at the boundary (BDR-015 pattern) | +| Report ids `crypto.randomUUID()`, `createdAt` / `exportedAt` from `new Date()` | `apps/app` | ids and timestamps are inputs of the core | +| Store takes `hydrateReport(report)` as is, no parse; `initReport` only trims | `reportStore.ts` | the Rust parser becomes the single entry for any report entering the store | +| Rules living in UI files that **build data**: `FindingsTreePicker.toggleLeaf` (Finding with snapshots and the vet flag), `VertebraPicker` selection rules | components | move to the core with the reducers (R2); display helpers (`zoneLabel`, `zoneTrees`, `describeZone`, import message lines, `isIdentityComplete`) stay TypeScript glue over precomputed data | +| Draft persistence drops an unparseable draft silently (`persistence.ts:55-58`, DEV warning only) | app | a draft the running build cannot parse is kept under a quarantine key with a visible notice (needed by every phase's rollback, VI.3) | +| The wasm module is a new single point of failure: `useSheet.ts` caches a rejected promise for the session and has no error state | app | lazy initialisation behind the sheet and import paths only, a `core_unavailable` state with retry, auth shell independent of the module | + +### I.3 Toolchain, host and deployment facts + +- No `cargo`, `rustc` or `rustup` on the development host (checked + 2026-10-12). Rust stable 1.99.0 (2026-10-01); edition 2024 since 1.85. On + `wasm32-unknown-unknown` the shipped standard library is panic = abort: a + panic traps the instance and `catch_unwind` never returns (verify at R0; + consequence handled in III.3). +- Docker 29.8.2 rootless on the host (seccomp builtin, `rootless`, + `cgroupns`), kernel 7.0. Docker's default seccomp profile (rootless + included) allows `seccomp`, `prctl`, `setrlimit`, `prlimit64` + unconditionally; `unshare` and `clone3` with namespace flags need + `CAP_SYS_ADMIN`. A seccomp + rlimit child works inside a container; + user-namespace isolation does not. +- Production: `DEPLOY.md` sizes the VPS at 1 vCPU / 1 GB / 10 GB (the Node + build already ran out of memory on DEV1-XS), deploys with `docker compose + up --build` **on the VPS**, documents a rebuild as the rollback, and sets + `script-src 'self'` without `'wasm-unsafe-eval'` in both the nginx and + the Caddy examples; `docker/nginx.conf` has no `gzip` directive. +- CI runs on a Gitea `act_runner`; JavaScript actions need `node` in the job + image; `dtolnay/rust-toolchain` and `taiki-e/install-action` are shell + composites; `Swatinem/rust-cache` relies on `actions/cache` (Gitea runner + v5 has a per-runner cache server; not verified on this forge). + +### I.4 Ecosystem facts (as of 2026-10-12) + +Verified on crates.io, docs.rs, GitHub and RustSec; "UNVERIFIED" items are in +IX.4. + +Core and bindings: + +| Need | Crate | Version (date) | Status | Limits | +|---|---|---|---|---| +| JSON | `serde` / `serde_json` | 1.0.229 / 1.0.154 (2026-10-11) | serde-rs org | pretty printer matches `JSON.stringify(v,null,2)` except integer-valued floats (`3.0`) and `-0.0`: custom `Formatter` (I.2) | +| Hashing, base64 | `sha2` 0.11.1, `base64` 0.23.1, `hex` 0.4.3 | | RustCrypto / marshallpierce | none open | +| Inflate | `miniz_oxide` 0.9.1 (2026-03), `flate2` 1.1.10 | pure Rust | | `decompress_to_vec_zlib_with_limit`, streaming `Decompress` for incremental cancel | +| WASM glue | `wasm-bindgen` 0.2.129 (2026-09-25), `js-sys` / `web-sys` 0.3.106 | org `wasm-bindgen` (Cloudflare maintainers), monthly releases, MSRV 1.81 | since 0.2.128 the crate and the CLI must be the same version: the CI and Docker install lines read it from `Cargo.lock` | +| WASM build | `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen-cli`; `wasm-pack` 0.15.0 (one maintainer, 335 open issues) | | cargo + CLI, pinned; `wasm-opt` (npm `binaryen` 132) only when the size budget needs it | +| Types for TypeScript | `ts-rs` 12.0.1 (2026-01): `.ts` files written by `cargo test`; `Option` → `T \| null`, `#[ts(optional)]` → `t?: T` | active | types only; the payloads cross as JSON strings (III.3); `tsify` 0.5.8 and `serde-wasm-bindgen` 0.6.5 (no release in 2.5 years, writes absent optionals as `null` in its JSON preset) are not used | +| Vite 7 | `--target web` output: `await init()` + `?url`, no plugin | | `.wasm` served raw unless nginx gzips it (VIII.1) | + +PDF, SVG, XML, fonts: + +| Need | Crate | Version (date) | Status | Limits | +|---|---|---|---|---| +| PDF writing | `pdf-writer` | 0.15.0 (2026-05-27) | typst org, 4 pure-Rust deps, no advisory | `EmbeddedFile` + `EmbeddingParams`, `FileSpec::association_kind(Data)`, `Names::embedded_files`, `Catalog::associated_files`, Type1 fonts with `WinAnsiEncoding` + explicit widths, image XObjects with `SMask`, `Action::uri`, Info dates, classic xref table; **cannot write object streams at all** (BLK-009 option B by construction); coordinates are `f32` (the links golden keeps a read-back oracle, VI.2) | +| PDF writing, higher level | `krilla` 0.8.2 (2026-06) | one maintainer | page text is OpenType only (no Standard 14), merges CreationDate/ModDate: candidate for the TTF step, not for the parity step | +| PDF read-back in tests | `lopdf` 0.45 (HIGH advisory patched ≥ 0.42) | test-only | reads `/Annots` of the written file for the links golden | +| Standard 14 metrics | **no credible crate** | | vendor the Adobe Core 14 AFM files (SPDX `APAFML`: redistribution allowed with `MustRead.html`, edits noted); `@pdf-lib/standard-fonts` bundles the same files (WX, N, KernPairs) | +| TTF later | `subsetter` 0.2.6, `skrifa` 0.48, `harfrust` 0.14; **`ttf-parser` and `rustybuzz` are RustSec-unmaintained** | | Inter and Fraunces are OFL | +| SVG raster (native only) | `resvg` / `usvg` 0.48.1 (2026-08), `tiny-skia` 0.12 | linebender org since 0.45 | only cap is 1,000,000 elements, `allow_dtd: true`: our sanitiser runs first; the head-view crop needs the render-full-box-then-crop workaround (LRN-046); not shipped to the browser (949 KB gzip measured on resvg-wasm 2.6.2) | +| XML parse | `roxmltree` 0.21.1 (2025-10) | RazrFalcon, 27M/90d | read-only, refuses DTD by default, `nodes_limit`; **unreleased fix (2026-09-22) for a stack overflow on deep nesting**: depth capped by a byte pre-scan until the fixed release is pinned | +| XML write | hand-written serialiser for the allowlisted tree | | ~100 lines; `quick-xml` not needed | +| PNG | `png` 0.18.1 (2026-02) | image-rs, no `unsafe`, OSS-fuzz | encoder writes only IHDR/IDAT/IEND unless asked | + +Worker (image pipeline, sandbox, transport): + +| Need | Crate | Version (date) | Status | Limits | +|---|---|---|---|---| +| Decode + resize + orientation | `image` 0.25.10 (2026-03-10), MSRV 1.88 | image-rs org | `orientation()`, `icc_profile()`, `set_limits` (max_alloc advisory 512 MiB), `apply_orientation`, `resize_to_fill`, `guess_format`; JPEG = `zune-jpeg`, PNG = `png`, WebP = `image-webp`; no ICC application API; resolves `moxcms` ^0.8 (use that version, not 0.9) | +| JPEG | `zune-jpeg` 0.5.15 | one very active maintainer | `unsafe` only in SIMD (togglable), default cap 16536×16535, CMYK ok, "panics are okay" policy → child process justified | +| WebP decode | `image-webp` 0.2.4 (2025-08) | image-rs, `forbid(unsafe)` | lossy, lossless, alpha, animation, ICC/EXIF/XMP; memory limit has a documented TODO; **encoder is lossless only** | +| WebP lossy encode | `libwebp-sys` 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, `cc` build) | C | no established pure-Rust lossy encoder (`oxideav-webp` 0.3.1 created 2026-04, `zenwebp` AGPL); `webp` 0.3.1 pins libwebp 1.3.1 + one fix (not used) | +| ICC → sRGB | `moxcms` (version resolved by `image`) pure Rust, one maintainer, SIMD `unsafe` on by default; `lcms2` 6.2 (C) alternative | | no documented ICC input limits: profile size capped by us (1 MiB) | +| Sandbox | `seccompiler` 0.5.0 (rust-vmm, sets `no_new_privs`, TSYNC available), `rlimit` 0.11 | | `landlock` not used (redundant under the allowlist); `extrasafe` dormant; `wasmtime` carries ~2 advisories/month in 2026 | +| Runtime, HTTP | `tokio` 1.53, `reqwest` 0.13.5 (rustls, `webpki-roots` compiled in), `tracing` 0.1.44 | | | +| Supabase clients | `postgrest` 1.6.0 (2023-07), `supabase-rs` 0.8.0 (PostgREST only) | weak | hand-written `reqwest` calls to PostgREST `/rpc/` and Storage `/storage/v1` (~10 endpoints) | +| Toolchain | `rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}`, `cargo-deny` 0.20.2, `distroless/static:nonroot` (Debian 13, CA bundle included) | | | + +Baseline for comparison, `sharp` 0.35.5 (2026-09-27): libvips 8.18.7, +libwebp 1.6.0, libpng 1.6.58, mozjpeg; strips metadata and converts to sRGB +by default, `limitInputPixels` 268 MP, WebP q80; EXIF orientation only with +`autoOrient`/`rotate()`. libvips had three High CVEs in July and August 2026, +libpng twelve CVEs since late 2025. The Rust pipeline's advantage is the +loader surface (three formats, pure-Rust decoders, hard caps), not the +encoder (still libwebp, confined to the child process). + +Supabase platform facts: + +- Edge Functions (managed: 2 s CPU, 256 MB, 150 s wall clock; self-hosted: + `edge-runtime` container, hand-deployed) run Deno, which can execute a + wasm build of the core; the rule retires them from the plan for those + limits, the hand deployment and the preference for one Rust runtime + (D-R9). The language alone would allow them. +- A dedicated Postgres role is honoured by PostgREST and storage-api + (official custom-roles guide), with a JWT minted from the legacy HS256 + `JWT_SECRET` or an imported ES256 standby key; on managed the imported + key must become a signing key of the project. Recorded as a hardening + option (IV.4), not adopted. +- `pg_jsonschema` 0.3.3 exists on managed and in the `supabase/postgres` + image but not in PGlite; custom `pgrx` extensions have no documented path + on managed. + +--- + +## Part II. Classification of every module + +### II.1 Criteria + +Business logic = anything that interprets or transforms the sheet, report or +archive data, encodes a product rule (what a click does, how a finding is +built, how a report migrates), parses untrusted bytes, or runs as a job or a +service. Glue = React rendering and display formatting, routing, DOM +access, store subscription, vendor SDK calls, build tooling. The owner's +brief keeps glue in TypeScript; everything else is Rust unless a concrete +loss is named on the brief's list (features, UX, graphics, data +compatibility, security, reliability, useful performance, resources, +portability, maintainability, deployment). Absence of a performance gain is +never a reason for C. + +Classes: **A** = Rust, scheduled on technical dependencies only; **B** = +Rust, waiting for a named external trigger; **C** = exception with its +concrete constraint. + +### II.2 Module table + +| Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Oracle for the switch | Class | Phase | +|---|---|---|---|---|---|---|---|---|---| +| domain: sheet document schema, `validateSheetDocument` (21 rules), `createEmptySheetDocument` | shape and integrity of the sheet | Zod | serde structs (strict = `deny_unknown_fields`, defaults), hand-written rules returning `SheetIssue {code, severity, path, message}` | yes + native | app load and publish gate call the core; types from `ts-rs` | low: codes and paths pinned by the validate suite; strict/strip policy per schema reproduced | validate suite (exact code + path lists), `horse-slice` fixture (converted to JSON), the draft document (0 issues) | **A** | R2 | +| domain: report v3, v2 input, `migrateReportV2ToV3`, `readReportDocument` | report contract and migration | Zod | full; "never throws on content" made true (today a malformed map entry can throw a raw `ZodError`) | yes + native | store hydrates only through the core | medium: strip semantics, `requiresVetReferral: false` dropped in v3 (kept, pinned), optional vs nullable fields | 612-leaf migration suites, golden v2 fixtures, migration map | **A** | R2 | +| domain: `rebaseReportOnSheet` | rebase on another sheet | TS over the index | full; takes the sheet handle | yes | store restore and import | CLAUDE.md gate: behaviour preserved exactly | rebase suite (exact objects) | **A** (owner go, D-R12) | R2 | +| domain archive: `buildSheetSnapshot`, `assertSnapshot`, envelope v1 layered read, branding + labels schemas | archive contract | Zod | full; UTF-16 string caps and UTF-8 asset caps reproduced; closed `snapshotRejected` reasons | yes + native | app import and export | medium: attachment bytes change once (D-R11); `origin` quirk for unknown envelope versions preserved | envelope decision table, branding/labels suite, size test, three envelopes frozen as goldens | **A** | R2 | +| domain: `buildSheetIndex` | lookups by id | closures over Maps | different shape: a Rust-owned `SheetHandle` (built once per session) for the core calls, plus `SheetIndexData` exported once for React (views, annotations, finding zones, regions by id; annotations per view; spine per region and view; precomputed `name` per annotation in both languages; `node_by_path`) | yes | ~14 modules read properties instead of calling closures; no wasm call in a render | low; one duplicate-id policy (document order, first wins) | service and component suites | **A** | R2 | +| `apps/app/src/services/zoneInteraction.ts` | click decision, observation reducers | pure TS | full; `apply_click(handle, observation, annotation_id, view_id)`, `sync_vertebrae(handle, …)` | yes | `EditorRoute.onZoneClick` and `ObservationPickers` call the core per click with the observation only (the sheet stays in the handle) | low | 13-case service suite, route click-chain characterisation | **A** | R2 | +| data-building rules in components: `toggleLeaf` (Finding builder), `VertebraPicker` selection | product rules inside components | TSX | `build_finding`, `vertebra_selection` in the core | yes | components call the core on the user action | low | component suites keep their assertions | **A** | R2 | +| display helpers in components and routes: `zoneLabel`, `zoneTrees`, `unresolvedFindings`, `describeZone`, import message lines, `isIdentityComplete`, `pickLabel` in JSX | formatting of core data for the screen | TSX | portable, but run inside renders and `useMemo` with `t()`; moving them means wasm calls in the render path or a view-model layer | no | none; they read `SheetIndexData` | none | existing suites | **C**: React render glue over precomputed data (the sheet names and `node_by_path` they need come from the core) | n/a | +| `reportStore.ts` actions | report construction and edits | Zustand | rules in the core (`new_report(draft, sheet, id, created_at)`, `swap`, `set_*` validation); the store stays Zustand | yes | one-line delegations | low | store suite | **A** (rules) / C (Zustand, adapters) | R2 | +| `persistence.ts`, `practitionerCache.ts`, `localeStore.ts`, `authStore.ts`, `localeSync.ts` | storage adapters, GoTrue event glue | TS | glue; the only rules (`isLocale`, "account locale wins once per sign-in") are tied to supabase-js events | no | none | none | existing suites | **C**: browser storage and supabase-js session glue (no Rust GoTrue client with PKCE and refresh) | n/a | +| anatomy render: layer renderer, `composeViewSvg`, highlight, `viewBoxOf` | markers from the document; composition with highlight | pure tree + DOM mutation | `render_annotation_layer(document, view, states) → LayerElement` (same plain contract) and `compose_view_svg(asset, document, view, highlight) → String` | yes + native | app canvas and engine use one composition; `drawing.ts` parses a sanitised string with `DOMParser` and keeps `importNode` + click delegation | low on the layer (step6 view facts); the composed string is compared as parsed trees, not bytes | step6 `views.*.json`, DOM-equivalence of the composed views for the three reports (frozen with the TS code), security SVG cases | **A** | R3 | +| pdf `svg/{parse,sanitize,view}` + app `drawing.ts` denylist | untrusted SVG → safe tree | xmldom / DOMParser | `roxmltree` with DTD refused and a byte pre-scan for depth and size, own allowlisted tree, own serialiser; one sanitiser for canvas, PDF, Step 13 uploads and branding SVG | yes + native | denylist deleted | medium: the "zero-removal" oracle becomes a DOM-equivalence test on `horse.svg` | 7 hostile cases, caps, zero-removal (tree compare) | **A** | R3 | +| pdf reader: byte scan, bounded inflate, JSON depth pre-scan, stamp, layered read; PNG gate inflater | untrusted PDF → archive outcome | TS + `DecompressionStream` | `miniz_oxide` streaming inflate with cancel; same candidate ordering and budgets; the leniency decisions of I.2 pinned | yes (in a Web Worker) + native (Step 15 server validation, CLI) | app import runs the core in a dedicated Web Worker terminated after each import | low: scan (39), inflate (9), read (13) suites are byte-level oracles | the same suites in cargo on the fixtures in place; BLK-009 browser measurements | **A** | R4 | +| pdf writer: layout, pages, footer, links, attachment, metadata, `exportFromEnvelope`, branding PNG gate, `safeText`, `wrapLines`, labels (25 keys) | A4 archive writer | pdf-lib | `pdf-writer`; layout split from serialisation (draw log = the golden format); AFM vendored; `png` decodes the archived logos under the existing gate; fr/en month tables | yes + native | two synchronous calls: `compose_export_views(report, snapshot, branding) → [{key, svg, size}]`, the caller rasterises (canvas in the browser, resvg natively), then `write_archive(input, pngs) → {pdf, warnings}`; no rasteriser callback crosses the boundary | medium: widths with kerning, `Math.round` half-up, dates, upper-casing; lines, rectangles and colours are not golden-covered today (D-R2 adds that golden with the TS engine first) | 39 goldens through the Rust draw log, links read back from the written file with `lopdf`, re-export test, size test, poppler/pdfium render diff | **A** (after R3 and the reader; same phase as the reader) | R4 | +| `apps/app/src/pdf/browserRasterizer.ts` | SVG → PNG via `Image` + canvas | DOM | DOM adapter between the two core calls; a native rasteriser (`resvg`) serves the worker and tools if a server-side rendering need appears | no | unchanged | none | raster facts test | **C**: browser rasterisation is DOM; no resvg in the browser bundle (D-R3) | n/a | +| `apps/app/src/pdf/export.ts`, `import.ts`, `branding.ts` | wiring, Vite asset imports, download | TS | glue | no | thin | none | existing suites | **C**: Vite asset imports, Web Worker and DOM download | n/a | +| `apps/app/scripts/compare-reports.ts` + `compare/report.ts` | archive check CLI | tsx + Node | `faunosteo-tools report-compare` on the core (LRN-044 escaping ported) | native | none | low | 11 CLI cases | **A** | R4 | +| anatomy curation pipeline (changeset, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) + legacy importer | changeset → draft artifacts; baseline import re-run at every regeneration | TS + xmldom + Prettier + `node:fs` | full (sha-derived "v5-like" uuid, strict label equality, region inference, ops); outputs emitted by Rust with `js_number`; markdown tables written by Rust; Prettier no longer touches generated files (`.prettierignore`) | native (tools) | none | the 18 generated files and `documentSha256` change once (D-R5); counts, determinism and the 612-leaf semantics are the oracles | `seed.golden.test` (regenerated once, decided), determinism and count suites, 612-leaf test, review drawings compared as parsed trees against the xmldom-era files | **A** (after R2, R3) | R5 | +| `packages/supabase/scripts/upload-sheet-assets.ts` | operator upload of sheet SVGs (service key) | tsx + Node | `faunosteo-tools upload-sheet-assets` (reqwest) | native | none | none | manual operator check (SUPABASE.md §3.1) | **A** | R5 | +| `packages/supabase` `classifyAuthError`, publish gate | closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue | partial | gate delegates | none | existing suites | gate **A** (R2); code map **C** (supabase-js error shapes) | R2 | +| `packages/supabase` client factory, auth/profile wrappers, `database.types.ts`, PGlite harness | vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser; PGlite is a JS/WASM library | no | none | none | | **C** | n/a | +| `auth/validation.ts`, `account/validation.ts` (Zod, i18n keys) | form field rules | Zod | portable but React-bound (retained list); the constraints are duplicated in SQL CHECKs and `config.toml` and drift (trim, UTF-16 vs `char_length`, `''` on names) | no | | | one constants module + a PGlite test reading `pg_constraint` and `config.toml` with the counting rule recorded (separate chore, D-R7) | **C** | chore | +| `lib/{dates,id}.ts` | `nowIso`, `todayIso`, `formatDate` (screen), `generateId` | Web APIs | clock and ids injected into the core; screen dates stay `Intl` | no | | | | **C** | n/a | +| `i18n/*` (281 keys ×2, `useT`, `pickLocaleLabel`) | UI strings | TS | UI data and hook; the engine's 25 archived labels move with the engine | no | | | parity test | **C** | n/a | +| `config/env.ts`, `lib/supabase.ts`, providers, guards, routes, components, styles | runtime config, React | TS | glue | no | | | | **C** | n/a | +| `vite/sheet-bundle.ts`, ESLint, Vite, vitest configs | build tooling | Node | Vite plugin API is JavaScript | no | | | | **C** | n/a | +| `supabase/migrations`, pgTAP, `private.sheet_document_issues` | database | SQL | retained; the TS/SQL rule pair becomes Rust/SQL with conformance fixtures (two expectation sets) | no | | | fixtures inlined into a generated pgTAP file with a drift test (the PGlite harness has no file access) | **C** (retained) | n/a | +| Step 8 worker (planned Node + sharp) | file processing | not built | native Rust (Part IV) | native | none | none (new) | Part IV tests | **A** | R1 (Step 8) | +| Step 13 SVG upload processor; Step 15 server-side archive validation; Step 19 notifications and job queue; Step 21 travel engine and calendar sync; Step 23 Stripe webhook; Step 24 import adapters; Step 26 export/archive jobs | future backend | not built | the worker binary (jobs) and its `serve` subcommand (inbound HTTP) sharing the core crate | native | none | none | per step | **A** at design time | their steps | +| Step 17 editor document operations (undo, geometry: bbox + margin → `view_box`, polygon edits, mapping validation); Step 20 agenda rule mirrors (48/24/1 h) | future app logic | not built | core functions through the wasm; UI in React | yes | editor store holds plain documents, calls the core on actions | none | per step | **A** at design time | their steps | +| Step 22 public web | marketing site, public profiles, SEO | not built | Rust static generators exist (Zola); the global rule mandates Astro for indexed sites (islands, SEO/GEO tooling) | n/a | | | | **C** proposed, D-R8 | Step 22 | + +### II.3 Summary by class + +- **A**: domain contracts and rules, the sheet handle and index data, + reducers and data-building rules, publish gate, layer renderer and view + composition, the one sanitiser, the PDF reader and writer, the CLI tools, + the curation pipeline and importer, the asset upload script, the Step 8 + worker, every future backend job, service or rule mirror. +- **B**: none left after the challenges; every migratable component is + scheduled on technical dependencies (VI.2). +- **C** (each with its constraint): React render glue and display helpers, + Zustand subscriptions and browser storage adapters, supabase-js session + and error shapes, UI form schemas and dictionaries, platform clock/crypto + and screen date formatting, the browser rasteriser (DOM), Vite asset + wiring and tooling, SQL and RLS, the public web framework (D-R8). + +--- + +## Part III. Target Rust architecture + +### III.1 Cargo workspace (three crates) + +```text +faunosteo/ +├─ Cargo.toml workspace: members crates/*, [workspace.dependencies], lints +│ (unwrap_used / expect_used = deny in the library, +│ disallowed_methods for std::time, std::fs, rand in core) +├─ rust-toolchain.toml channel pinned (1.99.0 at adoption), target wasm32-unknown-unknown +├─ deny.toml cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0, +│ APAFML for the AFM data), bans (duplicate versions), sources +├─ crates/ +│ ├─ core/ faunosteo-core (lib). Modules: domain (sheet, report, archive, +│ │ index, reducers, rules), anatomy (xml tree, sanitiser, +│ │ serialiser, layer, compose), pdf (reader, writer, afm, png gate, +│ │ labels), curation (pipeline, importer). Features: `xml`, +│ │ `pdf-read`, `pdf-write`, `curation`, `cli`. No I/O, no clock, +│ │ no ids in any module (lint-enforced). [[bin]] targets behind +│ │ `cli`: report-compare, import-equine, upload-sheet-assets. +│ ├─ wasm/ faunosteo-wasm (cdylib): the wasm-bindgen facade over core +│ │ (features xml + pdf-read + pdf-write), JSON strings in and out, +│ │ closed error kinds, `ts-rs` types emitted into +│ │ packages/core-wasm/types. +│ └─ worker/ faunosteo-worker (bin): `run` (job loop, transport, sweeper, +│ watchdog), `decode` (the sandboxed child), later `serve` +│ (inbound HTTP). Depends on core without the pdf features +│ until Step 15. +└─ packages/core-wasm/ committed package.json (exports → pkg/) and generated types; + pkg/ (js, wasm, d.ts) is git-ignored and built by + `pnpm wasm:build` +``` + +Why three: one library keeps every rule in one dependency graph and one test +run; features keep `pdf-writer` and `roxmltree` out of the worker build +until it needs them (`cargo build -p faunosteo-worker` compiles only the +features it enables); the facade and the binary are the two deployment +boundaries. A `crates/editor` for Step 17 is not planned; editor operations +are a module of core (D-R1). + +### III.2 Native and WASM: who runs what + +| Code | Native | WASM | +|---|---|---| +| core domain | worker (Step 15 validation), tools, cargo tests | app: parse, validate, index, reducers, rules, snapshot, envelope | +| core anatomy | worker (Step 13 uploads), tools (pipeline) | app: sanitise, compose views for the canvas and the export | +| core pdf | worker (Step 15), tools (report-compare) | app: reader (in a Web Worker), writer | +| core curation | tools only | never | +| worker | container `faunosteo_worker` | never | + +Platform access (clock, ids, storage, network, DOM, rasterisation) is +injected; the core never calls `std::time`, `rand`, `fs` or `fetch`. + +### III.3 Boundary rules ("Rust computes, TypeScript reads") + +1. **Coarse calls, JSON strings.** One call per user action or per load, + never per render. Payloads cross as JSON strings (`serde_json` with the + `js_number` formatter, `JSON.parse` on the TypeScript side); types come + from `ts-rs` (`packages/core-wasm/types`). No `serde-wasm-bindgen`, no + `tsify`: zero extra crates on the boundary, no `null`-for-absent trap, + payloads readable in the debugger. The kilobyte-sized observations and + outcomes make the string cost irrelevant; the sheet never crosses more + than once. +2. **The sheet is a handle.** `SheetHandle` is a `#[wasm_bindgen]` struct + built once per session from the loaded sheet (document, assets, + migration map); every core call that needs the sheet takes the handle by + reference. `handle.index_data()` returns `SheetIndexData` once (plain + data: views, annotations, finding zones, regions by id, annotations per + view, spine per region and view, `main_view_id`, `name_fr`/`name_en` per + annotation, `node_by_path`); React reads properties. +3. **Errors are closed kinds.** Every fallible call returns + `{ ok: true, value } | { ok: false, kind, detail }` with the kinds already + named in the code (`invalid_pdf`, `no_attachment`, `incompatible_version`, + `snapshotRejected` reasons, `ArchiveExportError` kinds, `internal`). The + `instanceof` checks on domain errors go away with the TS classes. +4. **Ids and time are inputs.** `new_report(draft, sheet, id, created_at)`, + `write_archive(…, exported_at)`; TypeScript keeps `crypto.randomUUID()` + and `new Date()`. +5. **Panics are traps, handled outside.** On wasm32 the core is panic = + abort, so `catch_unwind` is native-only. Libraries deny `unwrap`/`expect`; + every TypeScript facade call catches `WebAssembly.RuntimeError`, marks + the instance poisoned, re-instantiates it (and rebuilds the sheet handle) + before the next call, and surfaces `kind: 'internal'`. The hostile corpus + (security and scan suites) runs through the wasm build at the shipped + shadow-stack size (set explicitly with `-C link-arg=-zstack-size`), not + only natively. +6. **Lazy, degradable initialisation.** The module loads behind the sheet + and import paths only; `/login`, `/app/*` and Mon compte never touch it. + A failed load yields a `core_unavailable` state with a retry that evicts + the cached promise. The import path runs the reader in a dedicated Web + Worker with its own instance, terminated after each import (linear memory + never shrinks; BLK-009 wants a bounded blast radius). +7. **Deterministic serialisation.** Struct fields in a declared order (the + Zod schema order for the snapshot, the store's insertion order for the + report), integer fields as integers, `js_number` for floats; optional + fields `skip_serializing_if = "Option::is_none"`, nullable fields plain + `Option`. A permanent compatibility test parses every Rust-written + envelope and draft fixture with a frozen copy of the last shipped Zod + schemas (the "N-1 reader" test, VI.3). + +### III.4 Contracts: one source of truth + +- **Rust is the source** for the sheet document, the report, the migration + map, the envelope, the snapshot, the branding and the labels. `ts-rs` + emits the TypeScript types; the Zod schemas of these contracts are + deleted in the phase that switches their last consumer (VI.4), and + `packages/domain` is deleted at R5 (its app importers are codemodded to + `@faunosteo/core-wasm` at R2). +- **SQL keeps its mirror.** Conformance fixtures (`crates/core/tests/ + conformance/*.json`: document, expected Rust issues with paths, expected + SQL codes) are run by cargo and by a pgTAP file generated with the + fixtures inlined (PGlite runs SQL text only); a drift test regenerates and + compares the pgTAP file. +- **JSON Schema** is not produced until a consumer exists (`pg_jsonschema` + CHECK is an option for Step 14, which stores reports). +- **Generated database types** stay `supabase gen types`. + +### III.5 Build and serving of the wasm + +- `cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown`, + then `wasm-bindgen --target web --out-dir packages/core-wasm/pkg`; the + CLI version is read from `Cargo.lock` by the install line in CI and + Docker. Root script `pnpm wasm:build`; `cargo test -p faunosteo-wasm` + writes the `ts-rs` types. +- Vite 7: `await init()` lazily (III.3 rule 6), `?url` resolution of the + `.wasm`, no plugin. Vitest: `init(readFileSync(wasmPath))`. +- Production serving (D-R13): CSP `script-src 'self' 'wasm-unsafe-eval'` in + both `DEPLOY.md` examples with a sanity-check row; nginx serves a + precompressed `.wasm.gz` (`gzip_static`) or adds `application/wasm` to + `gzip_types`; the hashed file name invalidates caches at each deploy. The + size budget counts bytes actually served (`curl --compressed`), proposal: + core module ≤ 600 KB compressed, measured at R2 and enforced by a CI + check. +- Debugging: `--keep-debug` builds in development, Chrome DWARF extension; a + vendored 30-line panic hook (the upstream crate is archived). + +--- + +## Part IV. Step 8 worker in Rust + +Everything in `STEP8_FILES_ANALYSIS.md` Part II stays (buckets, `assets` +table, RPCs, keys, quarantine, purge queue, backups, migration runbook, UI, +D1 to D9). What changes is the runtime of II.1 and II.8: one Rust binary +replaces the Node process and `sharp`. The keyless-decoder invariant of +STEP8 IV.3 ("the keyed process never decodes") is kept. + +### IV.1 Process model + +```text +container faunosteo_worker (distroless/static:nonroot, read-only, no port, default seccomp) + faunosteo-worker run ← keyed parent (tokio, reqwest, service key) + poll every 2 s: POST /rest/v1/rpc/claim_avatar_jobs {max_jobs: 1} + GET /storage/v1/object/avatars/ (≤ 5 MiB, 30 s timeout) + spawn faunosteo-worker decode ← same binary; `decode` is dispatched from a plain fn main + BEFORE any runtime or thread exists; empty env; stdin/stdout + child: assert Threads: 1 (/proc/self/status) → RLIMIT_AS 512 MiB, RLIMIT_CPU 10 s → + seccomp allowlist installed with TSYNC, kill on violation (list derived by strace + over the fixture corpus at the caps on the production image, not hand-written) + decode: image::guess_format ∈ {jpeg, png, webp} else unsupported_type + ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB} + header dimensions before decode (64 ≤ sides ≤ 4096 else dimensions) + decode (first frame of an animated WebP), apply_orientation (EXIF), + ICC → sRGB through moxcms when a profile ≤ 1 MiB is present, else assume sRGB + resize_to_fill 512×512 (Lanczos3), alpha kept + encode lossy WebP q=82 via libwebp-sys (C, confined to this process) + stdout: WebP bytes; exit code from a reserved table (never 101, never a signal number) + parent: read stdout up to 512 KiB (kill past it); parse the RIFF container only: size field = + byte length, chunk FourCC allowlist {VP8X, VP8, VP8L, ALPH}, canvas 512×512 from the + VP8X/VP8 header, no EXIF/XMP/ICCP chunk; sha256; size. NO pixel decode in the parent. + PUT /storage/v1/object/avatars/ (upsert) → POST rpc/complete_avatar_job + → DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job + SIGSYS, SIGKILL (deadline) and RLIMIT deaths are logged with their own internal code + (syscall number for SIGSYS) and mapped to processing_error; after 20 s the parent SIGKILLs + sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep + watchdog: per-stage deadlines (claim 35 s, download 35 s, decode 25 s, upload 35 s, commit 35 s); + a stage past its deadline exits the process; Docker restarts it + start-up log: libwebp version (WebPGetEncoderVersion, CI fails below 1.6.0), seccomp status, + token expiry (service key: none) +``` + +The crash matrix, the write order, the lease and attempt rules, the purge +grace periods and the fairness rule of the Step 8 analysis apply unchanged. +The 60 s single watchdog of the Node proposal is replaced by per-stage +deadlines, because one iteration's worst case (three 30 s network calls plus +the 20 s child) exceeded it and would have burnt leases during a slow Storage. + +### IV.2 Comparison with the Node proposal + +| Aspect | Node 24 + sharp (STEP8 II.8) | Rust worker | Verdict | +|---|---|---|---| +| Decoders on untrusted bytes | libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 | `zune-jpeg` (SIMD `unsafe`, togglable), `png` (no `unsafe`, fuzzed), `image-webp` (`forbid(unsafe)`), hard `Limits` | Rust better: smaller trusted base, caps by construction | +| Encoder | libwebp via sharp | libwebp via `libwebp-sys` 0.14 (C), in the same sandboxed child, on a buffer that child decoded; the parent checks the container header only | equivalent; the C surface is the encoder, process-confined (D-R4 lists the alternatives) | +| Orientation, ICC, metadata | `rotate()`, ICC → sRGB and stripping by default | `apply_orientation`, `moxcms` ICC → sRGB, stripping by construction (the encoder writes no metadata chunk) plus the parent's chunk allowlist | equivalent, verified rather than assumed | +| Isolation | two Node processes, child without env | one static binary, child without env **plus** rlimits and a traced seccomp allowlist installed before any thread | Rust better | +| Resource bounds | `limitInputPixels`, `mem_limit` 512m, 20 s kill | `Limits`, `RLIMIT_AS`, `RLIMIT_CPU`, 20 s kill, output cap 512 KiB, `mem_limit` | better | +| Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB | Rust better on resources | +| Transport to Supabase | supabase-js with the service key over PostgREST and Storage | `reqwest` calls to the same two APIs with the same key (`webpki-roots` compiled in for HTTPS on managed) | equivalent | +| Maintenance | `sharp` Renovate rule | `cargo deny` in CI (licences, bans, sources blocking; advisories nightly) | equivalent | +| Managed Supabase | URL + key only | same | equivalent | +| Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule; built in CI, pulled by digest (VIII.1) | + +### IV.3 Worker crates + +`tokio` (rt, process, time, io), `reqwest` (rustls, json, stream, +`webpki-roots`), `serde` / `serde_json`, `image` (default-features off; +`jpeg`, `png`, `webp`), `moxcms` (version resolved by `image`), +`libwebp-sys`, `sha2`, `rlimit`, `seccompiler`, `tracing` + +`tracing-subscriber` (JSON logs, field allowlist, control characters escaped: +LRN-044), `thiserror`. No database driver (one transport, no open DB port on +managed, as in STEP8 II.8). + +### IV.4 Credential: as validated, with one hardening option recorded + +The worker holds the service key in `.env.worker` as the owner validated +(STEP8 D1, II.8). A dedicated `faunosteo_worker` Postgres role with a minted +JWT would narrow a leak, but it is independent of the language and is not +"at the same cost": it needs the role granted to `authenticator` (the PGlite +shim defines only `anon`, `authenticated`, `service_role`), EXECUTE on the +nine worker RPCs plus a new RPC for the key-driven sweep lookup, `SELECT`, +`INSERT`, `UPDATE` and `DELETE` policies on `storage.objects` for the role +(which breaks the pinned census "2 / 1 / 0 per bucket" and the assertion +"no UPDATE / DELETE policy exists"), token expiry handling (log `exp` at +start, warn 30 days before, re-mint), a revocation path (`REVOKE +faunosteo_worker FROM authenticator` plus re-mint), and on managed an +operator-held signing key. Recorded as a Step 27 hardening option with +those prerequisites; not a decision of this study. + +### IV.5 Tests specific to the Rust worker + +- Decode child fixtures (STEP8 IV.2 list, unchanged): JPEG/PNG/WebP + accepted, renamed PNG, GIF/BMP/SVG/PDF/HTML refused, truncated, 32 px, + 20 000² header, 5000², EXIF-rotated → upright and chunk-free, PNG trailer + after IEND, progressive JPEG with many scans and a large ICC under the + deadline with RSS asserted, sleeping child killed at 20 s. +- Sandbox tests (Linux, on the production image in CI): every accepted + fixture passes through the **fully** sandboxed child (the allowlist is + derived, then proven on the corpus at the caps: 4096² RGBA, 16-bit PNG, + CMYK JPEG, ICC through `moxcms`); a disallowed syscall kills the child and + the parent logs SIGSYS with the syscall number; `/proc/self/environ` is + empty; `Threads: 1` holds when the filter is installed. +- Parent checks: a child returning 511×511, an `EXIF` chunk, a wrong RIFF + size, 513 KiB of output, or garbage → rejected before any PUT; the child + is killed on output overflow. +- Integration against the local stack (CI `supabase` job): Alice's full + flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2; one + HTTPS call in CI proves the CA bundle. + +--- + +## Part V. Libraries retained and their limits + +| Area | Retained | Rejected | Limits to manage | +|---|---|---|---| +| Serialisation | `serde`, `serde_json` (custom formatter), `thiserror`, `ts-rs` | `serde-wasm-bindgen`, `tsify`, `schemars` (until a consumer exists), `serde_jcs` | float printing owned by `js_number`; field order declared per struct | +| XML | `roxmltree` + own tree and serialiser | `quick-xml`, `usvg` as sanitiser (allows DTD, drops silently, rewrites the drawing) | depth and size pre-scan until the deep-nesting fix is released | +| PDF write | `pdf-writer` | `krilla` (no Standard 14 page text, merged dates; candidate for TTF), `printpdf` (no attachments), `lopdf` as writer | classic xref only (wanted); `f32` coordinates (links read back) | +| PDF read | own byte scan + `miniz_oxide`; `lopdf` test-only | `pdf`, `pdfium` in the app | same caps as today | +| Fonts | vendored Core 14 AFM (APAFML notice committed); later `skrifa` + `subsetter` + `harfrust` | `ttf-parser`, `rustybuzz` (RustSec unmaintained) | kerning-inclusive width rule reproduced from pdf-lib | +| PNG | `png` | UPNG semantics | gate stays ours; decoder under `Limits` | +| Raster | browser canvas (DOM adapter); `resvg` native in tools/worker when a need appears | `resvg` in the browser bundle | `allow_dtd`, 1M-element cap and the crop workaround handled by our sanitiser and adapter | +| Images (worker) | `image`, `moxcms`, `libwebp-sys` | `webp` crate, `image-webp` in the parent, `img-parts`, `infer`, `wasmtime`, `extrasafe` | `Limits.max_alloc` advisory → `RLIMIT_AS` is the hard cap; profile size capped | +| Sandbox | `seccompiler`, `rlimit` | `landlock` (redundant under the allowlist), user namespaces | allowlist derived by tracing, proven on the corpus | +| Runtime | `tokio`, `reqwest` (`webpki-roots`), `tracing` | `postgrest`, `supabase-rs` | ~10 hand-written endpoints tested against the local stack | +| WASM | `wasm-bindgen` + CLI (version from `Cargo.lock`), `binaryen` when needed | `wasm-pack` | crate/CLI lock | +| Hygiene | `cargo-deny` (licences, bans, sources blocking; advisories nightly and at release) | `cargo-audit` (same database), `cargo-chef` (BuildKit cache mounts suffice), `cargo-fuzz` before Step 27 (nightly toolchain; our own parsers only) | | + +--- + +## Part VI. Progressive migration strategy + +### VI.1 Principles + +- **Freeze with the old code, then switch.** Before a phase ports a module, + every output that no test pins yet is committed as a golden produced by + the TypeScript code (LRN-046): the three archive envelopes, the composed + views as parsed trees, the draw log of lines, rectangles and colours. The + oracle suites are then ported to cargo on the fixtures in place (JSON + fixtures under `apps/app/tests/fixtures` and `packages/*/tests/fixtures`, + read by path; the two TypeScript fixtures `horse-slice.ts` and + `mini-sheet.ts` converted to JSON once). No dual-run harness. +- **Consumer-driven deletion.** A TypeScript module is deleted in the phase + that switches its last consumer; until then it is frozen (no new logic) + and its existing goldens keep proving it. The table in VI.4 names the + last consumer of every module so nothing is deleted while imported + (revision 1 broke this twice). +- **Goldens are never regenerated silently.** A phase that changes an + oracle (the attachment bytes at R2, the generated seed files at R5) says + so in its end criteria and the owner decides. +- **Every phase** ends with `pnpm check`, `cargo test --workspace --locked`, + `cargo clippy -D warnings`, `cargo deny check` (licences, bans, sources), + Docker builds green, the real-stack pgTAP when SQL changed, the verifier + and security gates, the rollback row of VI.3 proven, and a manual + validation script for the owner. +- Phases are gitflow branches (`feature/rust-r-`; + `chore/rust-r0-workspace` for the foundation). + +### VI.2 Phases and end criteria + +| Phase | Content | Depends on | End criteria (verifiable) | +|---|---|---|---| +| **R0 Foundation** (inside Step 8) | `Cargo.toml` workspace, `rust-toolchain.toml`, `deny.toml`, lints, `crates/core` skeleton (no app consumer yet), `crates/worker` skeleton, CI job `rust`, worker image build, `docs/development/RUST.md` (setup, commands, boundary rules), `DEPLOY.md`: images built in CI and pulled by digest, CSP line with `'wasm-unsafe-eval'`, gzip for `.wasm`, VPS disk and RAM headroom recorded; `rustup` on the dev host (owner) | none | `cargo test`, `clippy`, `deny` green in CI; worker image builds (< 30 MB) and starts against the local stack with no job; panic strategy on wasm32 verified and written in `RUST.md`; CI duration and runner cache behaviour measured and recorded; no production artifact changed yet | +| **R1 Step 8 worker** | Part IV: decode child, sandbox, transport, sweeper, per-stage deadlines, compose service, `.env.worker.example`, the Step 8 migration and app work as analysed | R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests on the production image, local-stack integration, real-stack e2e); image non-root, `cap_drop ALL`, read-only; libwebp ≥ 1.6.0 logged; owner manual validation of the avatar flow | +| **R2 Domain core** | `crates/core` domain: sheet document + rules, report v3/v2 + migration, rebase (owner go, D-R12), snapshot/envelope/branding/labels, `SheetHandle` + `SheetIndexData`, reducers, `build_finding`, `vertebra_selection`, `new_report`; `crates/wasm` facade (JSON strings, `ts-rs` types, poison-and-reinstantiate, lazy init, `core_unavailable`); `packages/core-wasm` package; app Dockerfile wasm stage; app switched (`SheetProvider`, store, click chain, pickers, publish gate); app importers codemodded from `@faunosteo/domain` to `@faunosteo/core-wasm`; `packages/domain` frozen for the TS engine and pipeline; three envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP | R0 | the domain, service, store, component and route suites pass with their assertions on the core; the three frozen envelopes parse with the frozen Zod schemas and compare semantically equal (bytes differ by decision D-R11); the 39 step6 goldens and the seed golden are untouched (the TS engine and pipeline still run on frozen TS); `pnpm build` with the wasm; the app boots under the exact production headers (CSP) in a headless check; a wasm load failure leaves `/login` and `/app` usable and shows the degraded state in the editor; a deliberate trap re-instantiates the module; served module size ≤ 600 KB compressed; owner manual FR/EN flow | +| **R3 Anatomy core** | `crates/core` anatomy: tree, sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas on the core (denylist deleted); the TS engine still composes with its frozen TS copy; composed-view trees for the three reports frozen with the TS code first | R2 | step6 `views.*.json` unchanged through the app path; composed views DOM-equivalent to the frozen trees; 7 hostile cases + caps + zero-removal (tree compare) in cargo; canvas suite green; one sanitiser reachable from the app (grep) | +| **R4 PDF core** (reader + writer + CLI) | `crates/core` pdf: scan, bounded inflate, layered read; layout → draw log → `pdf-writer`; AFM vendored; `png` + gate; dates tables; the leniency decisions of I.2 pinned by fixtures; draw-log golden for lines, rectangles and colours frozen with the TS engine first (D-R2); app import in a Web Worker, app export on the two-call design; `report-compare` tool; `packages/pdf` deleted (last consumer); frozen TS `render/` deleted with it only if the pipeline no longer imports it (it does: kept until R5) | R3 | 39 goldens reproduced exactly through the Rust draw log (text, images), links read back from the written files with `lopdf`, views via the app path; the new draw-log golden reproduced; scan (39), inflate (9), read (13), security (55), text (5), size (2) suites in cargo; the hostile corpus through the wasm build; BLK-009 browser measurements (Chromium, Firefox, Safari, one low-end phone) recorded in `PDF_IMPORT_HARDENING.md` §5 as done items (the gate itself stays open until every §5 item is done); poppler or pdfium render diff of the three reports within a stated threshold; the last TS scanner, kept as a test fixture, and the previous release's reader read every R4 fixture PDF; stored attachment < 250 KB; no `pdf-lib`, `@pdf-lib/*`, `@xmldom/xmldom` in the lockfile of `apps/app` or `packages/pdf` | +| **R5 Curation pipeline, importer, operator tools** | `crates/core` curation + `cli` bins: import-equine, upload-sheet-assets; outputs emitted by Rust (`js_number`, markdown tables); `.prettierignore` on generated dirs; seed golden regenerated once (decided); review drawings compared as parsed trees against the xmldom-era files; `packages/anatomy` and `packages/domain` deleted (last consumers); CLAUDE.md folder map, `packages/README.md`, `WORKSPACE.md`, CHANGELOG | R2, R3, R4 | `seed.golden.test` green on the regenerated set; determinism (two runs byte-equal), counts (27/792/612/41, 811 nodes), 612-leaf semantics unchanged; `documentSha256` changed once and the import of an older archive shows the rebase message with 0 unresolved items on identical content; no TypeScript business logic outside UI glue (grep census in `RUST.md`); workspace test count reconciled with the deleted-tests list (TEST_STRATEGY §6) | + +Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 right after Step 8 and +before Step 9, so that every later step writes its rules in Rust. R3, R4 and +R5 before Step 13 (which needs the sanitiser in the worker), interleaved with +Steps 9 to 12, which touch no module these phases move. The TTF font change +is a separate later change with its own golden regeneration (D-R2). + +### VI.3 Rollback per phase + +Production rollback is "deploy the previous image by digest" (VIII.1), so +each phase states what the previous build must still read. + +| Phase | Artifacts written by the new build | What N-1 must read | Proof | +|---|---|---|---| +| R1 | avatars (WebP) | the app only displays them; the Node proposal never shipped | none needed | +| R2 | drafts in `osteo:draft` and archives in `osteo:archive` written by the core (struct order, `js_number`); PDFs still written by the frozen TS engine from core-produced reports | N-1 (Step 7 build) parses the draft and the envelope with its Zod schemas | N-1 reader test on the frozen fixtures; a draft N-1 cannot parse goes to the quarantine key with a notice (never discarded) | +| R3 | none persisted (canvas only) | n/a | | +| R4 | PDFs from `pdf-writer` (classic xref, same attachment, same stamp) | N-1 scanner finds the attachment and the stamp; Step 6 build reads bare v3 and envelope | the kept TS scanner fixture and the previous release's reader read every R4 fixture PDF; `DEPLOY.md` rollback note updated as for Step 6 | +| R5 | regenerated seed (new `documentSha256`) | N-1 app bundles the old seed and rebases archives written on the new one (visible message, nothing lost); reports written on the old seed rebase on the new build | rebase tests both ways on the two seeds | + +### VI.4 What is deleted when (last consumer named) + +| Module | Consumers today | Last consumer switched at | Deleted at | +|---|---|---|---| +| `services/zoneInteraction.ts`, component data-building rules, store rules | app | R2 | R2 | +| `packages/domain` Zod contracts and functions | app (R2), TS engine (R4), TS pipeline (R5), scripts (R4) | R5 | R5 (`packages/domain` removed; app imports codemodded at R2) | +| `anatomy/drawing.ts` denylist | app canvas | R3 | R3 | +| `packages/pdf/src/svg/**` (sanitiser, view) | TS engine | R4 | R4 | +| `packages/anatomy/src/render/**` | app (R3), TS engine (R4), TS pipeline `app-review.ts` (R5) | R5 | R5 | +| `packages/pdf/src/**` (reader, writer, attachment, branding gate), `apps/app/scripts/**`, `browserRasterizer.ts` stays | app, CLI | R4 | R4 (`browserRasterizer.ts` kept as the DOM adapter) | +| `packages/anatomy/src/{legacy,curation,cli}/**`, `packages/supabase/scripts/upload-sheet-assets.ts` | operator | R5 | R5 | +| `packages/anatomy`, `packages/domain`, `packages/pdf` packages | | | R4 (pdf), R5 (anatomy, domain) | + +--- + +## Part VII. Adaptations to the development plan + +| Step | Plan text today | Adaptation under the rule | +|---|---|---| +| 8 Files | Node worker + sharp (STEP8 D1) | D1 reads "native Rust worker"; R0 + R1 inside the step; `apps/worker` is not created; `crates/worker` is; service key kept (IV.4) | +| 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors in `crates/core` domain, called through the wasm; UI unchanged | +| 13 Sheets in DB | SVG processor "from packages/pdf" | the R3 sanitiser runs in the worker's decode child (same isolation as images); the Supabase `SheetProvider` stays TS glue, parsing through the core | +| 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; diff/throttle rules in the core; optional `pg_jsonschema` CHECK from a `schemars` export (decision at the step, first consumer of JSON Schema) | +| 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row"; artifacts = PDFs generated by the browser | the worker validates the attachment with the core reader (R4); no Edge Function; server-side rendering is not in the plan; if a need appears, `resvg` native between the two core calls | +| 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in the core | +| 17 Sheet editor | editor store with undo, geometry | document operations and geometry as a core module, UI React | +| 19 Notifications/worker | `apps/worker` Node, EmailProvider, `private.jobs`, `packages/i18n` for templates | `crates/worker` `run` gains the `private.jobs` loop (RPC with `SKIP LOCKED`) and templates rendered in Rust from Rust-side dictionaries; `packages/i18n` stays UI-only | +| 20–21 Agenda, travel | expiry rule TS mirror, routing adapter, "Edge Function or worker endpoint" for the Google OAuth callback | mirror in the core; routing and calendar sync in the worker; the callback is the first inbound route of the worker's `serve` subcommand (axum, one route, behind the reverse proxy) | +| 22 Public web | Q8 framework | Astro (global rule), D-R8 | +| 23 Billing | "Edge Function stripe-webhook" | `serve` hosts the webhook (signature check, idempotency table unchanged) | +| 24 Imports | adapters in the Node worker | Rust adapters (`csv`, `calamine`, `zip`), same `ImportAdapter` contract | +| 26 Lifecycle | export/archive/restore jobs in the Node worker | Rust jobs in the same binary | +| 27 Hardening | | adds `cargo deny` advisories, the sandbox tests and the `cargo-fuzz` run (nightly toolchain, our own parsers) to the release gate; the worker-role option of IV.4 evaluated here | +| BACKEND_ARCHITECTURE §6 | Edge Function row | "Rust service (worker `serve`)"; PostgreSQL rows unchanged | +| WORKSPACE.md, packages/README.md | `apps/worker` Node, `@faunosteo/i18n` for the worker | `crates/*`; i18n package UI-only | +| TEST_STRATEGY.md | layers | adds the cargo layer, the freeze-then-switch rule, the N-1 reader test and the conformance fixtures shared with pgTAP | + +--- + +## Part VIII. Docker, Supabase and CI impacts + +### VIII.1 Docker and deployment + +- **Images are built in CI (or on the dev host) and pulled by digest.** The + VPS (1 vCPU, 1 GB) never compiles Rust: `docker compose up --build` on the + VPS is replaced by `docker compose pull && up -d` on tagged images + (registry: the Gitea container registry of the forge, or Scaleway's); + rollback = the previous digest. This is a prerequisite recorded in R0 and + written into `DEPLOY.md` (routine deploys, rollback, disk headroom). +- **App image**: a first stage `FROM rust:1.99.0-bookworm AS wasm` (BuildKit + cache mounts on `~/.cargo` and `target`, pinned `wasm-bindgen-cli`) + producing `packages/core-wasm/pkg`; the committed + `packages/core-wasm/package.json` is in the manifest COPY list so + `pnpm install --frozen-lockfile` keeps working; the Node builder copies + `pkg/` before `pnpm build`; nginx serves `.wasm` (and `.wasm.gz` with + `gzip_static`) with the hashed name. +- **Worker image**: `rust:1.99.0-alpine3.24` builder (musl, `musl-dev`, + `build-base` for libwebp's `cc` build) → `distroless/static:nonroot` (CA + bundle present; `scratch` rejected), one static binary. Compose service + `worker` (container `faunosteo_worker`): `read_only: true`, `tmpfs: /tmp`, + `cap_drop: [ALL]`, `security_opt: [no-new-privileges:true]`, + `mem_limit: 512m`, `cpus: 1`, `pids_limit: 64`, no `ports`, Supabase + internal network only, `restart: unless-stopped`, `env_file: .env.worker`. + The default Docker seccomp profile stays (it permits the inner filter). +- **Naming**: `faunosteo_worker`, image `faunosteo/worker` (BDR-035). + +### VIII.2 Supabase + +- No schema change comes from the rule itself. +- Conformance fixtures for `sheet_document_issues` land as a generated + pgTAP file with inlined fixtures (PGlite and real stack), owned by R2. +- Managed migration: the worker container is hosting-agnostic (URL + key); + HTTPS works out of the box (`webpki-roots`, distroless CA bundle, one + HTTPS call tested in CI). + +### VIII.3 CI (`.gitea/workflows/ci.yml`) + +- New job `rust` (runs before `check`): toolchain from `rust-toolchain.toml` + (`dtolnay/rust-toolchain`), `cargo fmt --check`, `cargo clippy --workspace + --all-targets -D warnings`, `cargo test --workspace --locked`, `cargo deny + check licenses bans sources`, `pnpm wasm:build`, artifact + `packages/core-wasm/pkg` uploaded. Cache: `Swatinem/rust-cache` if the + Gitea cache server works (verified at R0), else a directory cache on the + runner host. +- `check` downloads the artifact before `pnpm install`. `docker` builds both + images and pushes them by tag and digest on `main` and `develop`. + `supabase` runs the worker integration test against the local stack. +- Nightly: `cargo deny check advisories`; from Step 27, the fuzz run. + +### VIII.4 Local development + +- Owner action: install `rustup` (lives in `~/.cargo`, no global package); + the pinned toolchain installs itself from `rust-toolchain.toml`; + `wasm32-unknown-unknown` target; `cargo install wasm-bindgen-cli + --version ` and `cargo-deny`. +- `pnpm dev` keeps working: `pnpm wasm:build` once and after Rust changes + (a `cargo watch` recipe in `RUST.md`); Vite serves the `.wasm` from the + package. +- The worker runs against the local stack with `cargo run -p + faunosteo-worker -- run` and `.env.worker` (SUPABASE.md §8 recipe). + +--- + +## Part IX. Validation criteria and risks + +### IX.1 Validation criteria of the orientation (beyond the per-phase ones) + +1. No regression on the owner's list: Report v3, v2 PDF import, autonomous + archives, immutable sheet versions, RLS, unresolved findings, FR/EN, file + security, graphics. Proof = the existing suites kept with their + assertions (one-to-one migrations named in commits, TEST_STRATEGY §6), + goldens unchanged except where a decision regenerates them, pgTAP + unchanged, the N-1 reader test green at every phase. +2. No duplicate business logic at the end of a phase, by the consumer-driven + deletion table (grep census in `RUST.md`); hand-written TS mirrors of + core helpers are not allowed (the core precomputes what React needs). +3. Security gates: the security-auditor runs on every phase; the worker + sandbox tests run on the production image; `cargo deny` licences, bans + and sources block, advisories gate releases. +4. Operability: worker image size, start time, memory ceiling, libwebp and + seccomp status logged at start; a runbook line per failure mode in + STORAGE.md; deploy and rollback never compile. +5. Cost visibility: CI duration and the served module size recorded in each + phase's TODO note. + +### IX.2 Risks + +| Risk | Likelihood | Effect | Mitigation | +|---|---|---|---| +| Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; frozen oracles catch what review misses | +| Dual toolchain in CI and Docker | certain | CI minutes | caches; wasm artifact reused by `check`; images built once, pulled by digest | +| WASM module as a point of failure (CSP, 404 after deploy, trap, memory growth) | medium | editor unusable or tab memory | CSP line and headless check at R2; lazy init with `core_unavailable`; poison-and-reinstantiate; reader in a terminated Web Worker; hashed file name | +| Hidden JS semantics in outputs and readers (float printing, upper-casing, ICU dates, kerning widths, rounding, lenient decoding, duplicate keys, `.int()`, `\s`) | high | golden mismatches or stricter readers refusing old files | the I.2 list with a fixture each before the owning phase; leniency decisions recorded; N-1 reader test | +| Sheet identity hash changes at R5 | certain | every older archive rebases once on import (message, nothing lost) | stated in R5's criteria and in the CHANGELOG; rebase tested both ways | +| Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; relaxed fields never widened without a decision | +| Crates maintained by one person (`zune-jpeg`, `moxcms`, `libwebp-sys`, `ts-rs`, `krilla`) | medium | abandonment | `cargo deny` `unmaintained` advisories; alternatives in Part V; decoders confined to the child; the boundary has no third-party crate | +| `roxmltree` deep-nesting overflow (fix unreleased) | known | parser DoS | depth cap by byte pre-scan; pin the fixed release | +| seccomp allowlist killing a valid decode | medium if hand-written | valid photos rejected after three leases | derived by tracing, proven on the corpus at the caps in CI, SIGSYS logged with the syscall number | +| VPS resources | certain | OOM or full disk during a build | never build on the VPS (VIII.1); disk headroom recorded | +| Gitea runner caches for Rust | unverified | slow CI | measured at R0; host-level cache fallback | +| `wasm-bindgen` crate/CLI version lock | certain | broken builds on drift | one version read from `Cargo.lock` by the install lines | +| Two implementations lingering | medium | drift, double maintenance | VI.4 last-consumer table is part of each Definition of Done | +| Public web framework conflict | certain | decision needed | D-R8 | + +### IX.3 Explicit non-goals of the rule + +- Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos, + Dioxus): excluded by the owner's retained list and the validated mockups. +- Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer: + excluded (retained list; RLS stays the boundary). +- Running Rust inside PostgreSQL (`pgrx`): excluded by managed compatibility. +- Moving SQL transactional rules to Rust: excluded. +- Shipping `resvg` to the browser: excluded (size, no visual change wanted). + +### IX.4 Unverified items (settled at R0 or at the phase that needs them) + +- Panic strategy and `catch_unwind` on stable `wasm32-unknown-unknown` for + the pinned toolchain (handled as abort regardless). +- `resvg` byte-identical output native vs the Node test adapter (README + claim; matters only if a server-side rendering need appears). +- Exact libwebp version string in `libwebp-sys` 0.14.4 (≥ 1.6.0 by API + presence; logged at start, checked in CI). +- `serde_json`/`zmij` exponent thresholds vs JavaScript (the `js_number` + formatter is tested on the committed overlays regardless). +- Gitea runner support for `Swatinem/rust-cache`; cold build times on the + runner; registry choice for images. +- Core wasm size and instantiate time (measured at R2). +- The syscalls a static-musl decoder needs (`mprotect`, `madvise`, + `rt_sigreturn`, `tkill`…): derived by tracing at R1, never assumed. + +--- + +## Part X. Decisions for the owner + +| Id | Question | Recommendation | +|---|---|---| +| D-R1 | Workspace layout | Three crates: `core` (feature-gated library with tool binaries), `wasm` (facade), `worker` (binary); no crate per module, no `crates/editor` | +| D-R2 | PDF engine | Reader and writer ported together at R4 with the Standard 14 AFM metrics (goldens exact); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port (additive); TTF fonts as a separate later change with its own regeneration | +| D-R3 | Rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | +| D-R4 | Lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (`ravif`, pure Rust, changes D4's format) | +| D-R5 | Sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives rebase on import with a visible message and 0 unresolved items (as any content changeset); no Prettier dependency kept | +| D-R7 | Form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home: a hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, with the counting rule recorded | +| D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the site needs no islands | +| D-R9 | Edge Functions | Retired from the plan (limits, hand deployment, one Rust runtime); webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | +| D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9–12 | +| D-R11 | Archive attachment bytes | New contract adopted at R2 (declared field order, `js_number`, optional absent / nullable null); every previous reader keeps parsing it (N-1 reader test, permanent); the bytes of existing PDFs are untouched | +| D-R12 | Gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | +| D-R13 | Serving the wasm in production | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples, gzip for `.wasm`, images built in CI and pulled by digest (no compile on the VPS), served module ≤ 600 KB compressed enforced in CI | +| D-R14 | BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the §5 browser measurements; the external-user import gate (BDR-040) stays open until every §5 item is done, never closed by R4 alone | + +The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native +Rust worker" from this review on; the worker credential stays the service +key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1 +(that role) is therefore no longer a decision of this study, which is why +the numbering skips it. + +--- + +## Annex A. Decision table (expanded for the owner's validation, 2026-10-12) + +Orientation validated by the owner on 2026-10-12 with ten principles (Rust +worker at Step 8, Cargo workspace, native and WASM libraries, progressive +anatomy migration, PDF migration under complete compatibility proofs, React +and PostgreSQL/Supabase kept, testable increments with rollback, no premature +deletion of TypeScript still in use, fully dockerised infrastructure with +production builds outside the small VPS, WASM compatibility with the +production CSP proven before activation). The detailed decisions below await +validation. Impact tags: SEC security, HIST historical data, PERF browser +performance, UI interfaces, DEPLOY deployment. + +| Id, subject | Recommendation | Relevant alternatives | Advantages / drawbacks | Risks | If validated | Impacts | +|---|---|---|---|---|---|---| +| D-R1 workspace layout | Three crates: `core` (feature-gated library, tool binaries behind `cli`), `wasm` (cdylib facade), `worker` (binary) | Six crates per boundary (rev 1); one crate holding the facade too (wasm-bindgen would pollute native builds); one crate per module | One dependency graph and one test run; features keep the worker lean / feature combinations must be tested in CI (`--no-default-features`, `--all-features`); core compile time grows with modules | Accidental I/O or clock in core (lint `disallowed_methods`); feature creep | R0 creates the three crates and the lint set | none | +| D-R2 PDF engine | Reader and writer ported together at R4 on `pdf-writer` with the Standard 14 AFM metrics (kerning-inclusive widths); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port; TTF fonts as a separate later change | Reader first, writer later (two phases, longer hybrid); writer on `krilla` + TTF at once (no Standard 14 page text, goldens regenerated blind); keep pdf-lib for writing (unmaintained, contradicts the rule) | The 39 goldens stay the exact oracle; `packages/pdf` deleted in one phase; no object streams by construction / largest single phase; AFM files vendored under the APAFML notice | Kerning, rounding, ICU dates or `f32` coordinates moving a run (caught by goldens and the `lopdf` read-back); viewer compatibility of classic xref (standard) | Golden regeneration decision for the additive draw-log golden; the gated functions port (D-R12); rollback note in DEPLOY.md as for Step 6 | HIST, DEPLOY | +| D-R3 rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | `resvg` lazy-loaded in the browser (949 KB gzip, anti-aliasing change, new raster goldens); `resvg` everywhere for identical bytes server and browser | No bundle growth, no visual change, no golden change / browser and future server renderings would differ (only matters if server rendering appears) | Browser rasteriser limits unmeasured (true today already) | Export becomes `compose_export_views` → rasterise → `write_archive`; `browserRasterizer.ts` kept as DOM adapter | PERF, UI | +| D-R4 lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; output checked by the parent at container level only | Lossless WebP via `image-webp` (pure Rust; avatars 5 to 10× larger); AVIF via `ravif` (pure Rust, slower encode, changes D4's format); wait for a pure-Rust lossy encoder (`oxideav-webp`, months old) | Standard output, small files, mature encoder / C compiled in the worker build (Alpine `build-base`), vendored version invisible to RustSec (logged at start, checked in CI) | libwebp CVEs (historically decoder side); mitigation = process confinement, rlimits, seccomp, version check | R0 spike proves the musl static build with `cc`; R1 implements | SEC, DEPLOY | +| D-R5 sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives and drafts rebase once with a visible message and 0 unresolved items | Keep a Node Prettier step to preserve the bytes (rev 1; chains the identity to a JS formatter); hash of canonical JSON (RFC 8785, `serde_jcs`): identity independent of formatting forever, one more concept | Simplest rule, matches today's semantics (the file is the identity) / one import notice per old archive after R5 | None on data (rebase keeps everything); user confusion if the message is not worded for "identical content" | R5 regenerates the seed golden knowingly; CHANGELOG entry; the import and restore messages re-read for the 0-unresolved case | HIST, UI | +| D-R7 form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home (hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, counting rule recorded) | Rust validation through the wasm per field (render-path calls on every keystroke); constants generated from the SQL migrations (rev 1: a DDL interpreter for eleven numbers) | Forms stay responsive and simple; the drift found by the inventory is closed / constants hand-written (kept honest by the test) | low | A small chore branch, any time; no UI change | UI | +| D-R8 public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception | Zola (Rust static generator, no islands, no React); Leptos/Dioxus SSR (immature SEO tooling, contradicts "React stays"); Next.js (global rule names Astro) | SEO/GEO tooling and islands / a TypeScript app in a Rust-by-default repository | none now | Exception recorded; Step 22 brainstorm re-checks per the global rule | DEPLOY | +| D-R9 Edge Functions | Retired from the plan; webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | Edge Functions (Deno can run the wasm core; limits, hand deployment on self-hosted); a separate HTTP container; `pg_net`/`pg_cron` for some jobs | One runtime, one image, Rust / the worker gains an inbound route at Steps 21 and 23 and uptime expectations | Inbound surface (signature checks, proxy rate limits, monitoring at Step 27) | `BACKEND_ARCHITECTURE.md` §6 updated; Steps 21 and 23 designs change | SEC, DEPLOY | +| D-R10 order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9 to 12 | R2 after Steps 9 to 12 (more TypeScript rules to migrate twice); R3 to R5 after Step 13 (impossible: the Rust worker needs the Rust sanitiser at Step 13) | Every later step writes its rules in Rust once / Steps 9 to 12 slowed by the migrations | Velocity of the functional steps | TODO order; Step 9 starts after R2 | DEPLOY | +| D-R11 archive attachment bytes | New contract adopted at R2: declared field order (struct order), `js_number` floats, optional absent, nullable `null`; every previous reader keeps parsing it (permanent N-1 reader test); existing PDFs untouched. At R2 the frozen TS engine still writes the attachment from the core's objects (order changes, floats printed by JS); at R4 the Rust writer serialises fully | Reproduce the insertion order of the TS store exactly (fragile mirror); keep TS serialisation of the attachment until R4 (same end state, same key-order change) | Declared and testable order / byte diff against pre-R2 exports (no reader depends on order; Zod ignores it) | A reader depending on key order (none known) | Struct field orders documented; N-1 reader test added at R2 and kept | HIST | +| D-R12 gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | Keep the TypeScript readers and rebase permanently (two implementations, contradicts the rule) | One reader for browser, worker and tools / the highest-stakes port (user data) | Behaviour drift on archives; mitigation = exact-object oracles, all fixtures, hostile corpus through the wasm build, N-1 test | The port follows the oracle suites; any behaviour change needs its own decision | SEC, HIST | +| D-R13 serving the wasm | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples; gzip for `.wasm`; images built in CI and pulled by digest (no compile on the VPS); served module ≤ 600 KB compressed enforced in CI; registry = the forge's Gitea container registry (recommended; Scaleway Container Registry as alternative) | `'unsafe-eval'` (broader, rejected); inline the module as base64 (CSP still applies, bigger); Brotli (nginx module needed); build on the VPS (rejected) | Minimal CSP relaxation specific to WebAssembly; deploy and rollback never compile / `'wasm-unsafe-eval'` needs Chrome 97+, Firefox 102+, Safari 16+ (Vite 7 baseline); an older browser lands in `core_unavailable` | Registry credentials on the VPS; CSP forgotten on one proxy (sanity-check row) | DEPLOY.md rewritten at R0 (procedure prepared, applied at the first image deployed: worker at R1); the deploy procedure change is validated separately | SEC, PERF, DEPLOY | +| D-R14 BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the `PDF_IMPORT_HARDENING.md` §5 browser measurements (Chromium, Firefox, Safari, one low-end phone); the external-user import gate (BDR-040) stays open until every §5 item is done | Main-thread synchronous reader (memory never shrinks, UI blocked); server-side import only (Step 15) | Bounded blast radius, measurable, import off the main thread / a second instantiation per import; a browser runner (Playwright) introduced for the measurements | Safari worker + wasm specifics; measurement effort | R4 includes the browser measurement campaign; the gate stays open | SEC, PERF | + +## Annex B. R0 scope (owner's clarification request, 2026-10-12) + +R0 is the foundation phase inside Step 8. It changes no production +artifact, implements no feature and starts only on the owner's go. + +### B.1 Toolchain, reproducible in Docker + +- Reference build environment = a Docker builder image + (`docker/rust-builder.Dockerfile`, `FROM rust:1.99.0-bookworm`, plus + `wasm32-unknown-unknown`, `wasm-bindgen-cli` at the version in + `Cargo.lock`, `cargo-deny`, `binaryen` for `wasm-opt`), used by CI and by + the application and worker image builds. The worker's own builder stays + `rust:1.99.0-alpine3.24` (musl, `build-base` for libwebp). +- The development host may install `rustup` for the inner loop (same + `rust-toolchain.toml`, so the same compiler); the containerised build is + the arbiter. Root scripts: `pnpm rust:check` (fmt, clippy, test, deny) + and `pnpm wasm:build`, each runnable locally or through the builder image + (`docker run --rm -v "$PWD":/w`). +- The production VPS never gets Rust: it pulls images by digest. + +### B.2 Workspace + +- `Cargo.toml` (workspace, `[workspace.dependencies]`, `[workspace.lints]`: + `unwrap_used`, `expect_used`, `disallowed_methods` for `std::time`, + `std::fs`, `std::env` in core), `rust-toolchain.toml`, `rustfmt.toml`, + `clippy.toml`, `deny.toml`, `.cargo/config.toml` (wasm stack size, + `-C link-arg=-zstack-size`). +- `crates/core` (modules declared, `SheetRef` + `Locale` types, the + `js_number` formatter, the conformance fixture loader), `crates/wasm` + (facade exporting `core_version()` and one JSON round-trip call), + `crates/worker` (binary with `run` printing its configuration and + `decode` wired to the sandbox spike, no job logic). +- `packages/core-wasm/package.json` committed, `pkg/` ignored. + +### B.3 Docker and CI + +- Worker image built from the skeleton (Alpine musl builder → + `distroless/static:nonroot`), started once in CI against the local stack + with no job (proves transport configuration, CA bundle, non-root, + read-only). +- Application image: the wasm stage added and exercised in CI, its output + not loaded by the application until R2. +- CI job `rust` before `check`: fmt, clippy, test, `cargo deny check + licenses bans sources`, wasm build artifact; `docker` job builds both + images; registry push by tag and digest prepared (registry decision in + D-R13); nightly advisories job; CI duration and runner cache behaviour + recorded in `RUST.md`. + +### B.4 Feasibility proofs (experimental, each one a permanent test) + +| Proof | Why it conditions a choice | How | Lives on as | +|---|---|---|---| +| Panic strategy on wasm32 | III.3 rule 5 (poison and re-instantiate) | a facade call that panics; observe `WebAssembly.RuntimeError`; re-instantiate; call again; try a deep recursion at the configured stack size | vitest in `packages/core-wasm` | +| Serialisation contract | D-R11, I.2 (`js_number`, optional vs nullable) | parse `report-v3.demo.json` and `document.json` with serde, re-emit through the custom formatter, compare byte for byte with `JSON.stringify(JSON.parse(x), null, 2)`; a struct with optional and nullable fields parsed by the current Zod schemas | cargo test + vitest N-1 reader seed | +| musl static binary with libwebp (`cc`) | D-R4 | build the worker skeleton with `libwebp-sys` on the Alpine builder; log `WebPGetEncoderVersion` | the worker image build in CI | +| seccomp allowlist derivation and application | Part IV (traced allowlist, `Threads: 1`, TSYNC) | `decode` spike: minimal `image` decode of one JPEG, one PNG, one WebP at the caps, traced with `strace -f` in the production image under Docker rootless; filter installed before any thread; disallowed syscall kills the child; environment empty | the sandbox test of R1 | +| CSP with `'wasm-unsafe-eval'` | D-R13, owner principle "proven before activation" | serve the wasm artifact under the production nginx config with the DEPLOY.md headers in headless Chromium: instantiation succeeds with the keyword, fails without it; result written in DEPLOY.md | CI headless check | +| Served size and instantiate time | D-R13 budget | measure raw and gzip bytes of the skeleton module and its instantiate time; set the budget check | CI size check | +| Runner caches and build times | VIII.3 | time the cold and warm `rust` job with and without `Swatinem/rust-cache` on the Gitea runner | `RUST.md` numbers | + +### B.5 R0 exit criteria + +`cargo test`, `clippy`, `deny` green in CI through the builder image; worker +image < 30 MB, non-root, starts against the local stack; the seven proofs +recorded in `RUST.md` with their numbers; `DEPLOY.md` rewritten (pull by +digest, CSP line, gzip, VPS headroom, rollback = previous digest) without +touching the live deployment; `pnpm check` unchanged; no production +artifact changed. Owner validation closes R0; R1 (the Step 8 worker) starts +on a separate go. + +--- + +## Annex C. Owner validation and amendments (2026-10-12) + +Revision 2 validated with the amendments below. The rule stays definitive: +Rust by default whenever it gives an equivalent or better result with no +functional, practical, graphical, security or reliability loss. R0 may start; +R1 waits for a separate go; release 0.2.0 waits for its own validation. + +Validated as recommended: D-R1 (three crates), D-R2 (reader and writer at +R4 after the oracles exist), D-R3 (browser canvas, no resvg in wasm), D-R7 +(form validation in TypeScript), D-R8 (Astro exception, re-evaluated at Step +22), D-R10 (order R0–R5), D-R11 (deterministic serialisation with old-reader +compatibility), D-R12 (gated PDF functions ported with identical behaviour), +D-R14 (import in a Web Worker, security controls kept before public opening). + +Amended: + +| Id | Amendment | +|---|---| +| D-R4 WebP | libwebp in C is allowed only inside the isolated processing child. The parent checks the validity and the limits of the produced result before any use (container structure, dimensions, size, absence of metadata). The native libwebp version actually linked into the build is known and controlled (logged at start, checked in CI). The migration must not introduce new unmanaged risks. | +| D-R5 sheet fingerprint | Preference for a deterministic fingerprint over a canonical JSON representation independent of the formatter (Prettier or Rust): study RFC 8785 (JCS) or a strictly defined alternative, so that a purely technical serialisation change never causes needless rebases. Explicit compatibility with the fingerprints and archives already produced. Existing fingerprints are not changed now: the decision is prepared for R5 and its implications verified before the switch. | +| D-R9 Rust HTTP services | Business Edge Functions replaced by Rust services where appropriate. Shared code but distinct processes for the job worker and the future exposed HTTP endpoints; they may come from the same Docker image run with different subcommands. Each service holds only the secrets, permissions, resources and protections it strictly needs. Supabase Auth keeps the OAuth mechanisms it already handles. | +| D-R13 WASM, CI, deployment | CSP compatibility with `'wasm-unsafe-eval'` validated experimentally, without widening JavaScript permissions. Rust/WASM builds reproducible in Docker and run in CI. Images identified by digest and a rollback strategy prepared. No automatic deployment to the VPS; no publication or promotion of a production image without an appropriate workflow and a validation; the VPS never needs to compile the Rust project. | + +R0 scope confirmed as Annex B, with these instructions: the seven proofs +run in the real environment as far as possible, the unconfirmed hypotheses +(serialisation, wasm panics, musl, seccomp) verified experimentally, a proof +that cannot be obtained reported as a blocker rather than assumed; during R0 +the React application, Report v3, PDF v2/v3, Supabase, the interfaces and +the existing tests stay unchanged; the WASM integration does not force the +frontend to load the module; no anatomy, PDF or business validation +migration (R2–R5); no avatar processing (R1); everything dockerised, the +production image produced in CI and pulled by the VPS; the live deployment +untouched; no tag or merge into main. diff --git a/docs/development/STEP8_FILES_ANALYSIS.md b/docs/development/STEP8_FILES_ANALYSIS.md new file mode 100644 index 00000000..681748ea --- /dev/null +++ b/docs/development/STEP8_FILES_ANALYSIS.md @@ -0,0 +1,627 @@ +# Step 8 — Files foundation and Supabase Storage: technical analysis + +Status: proposal for the owner's decision, 2026-10-12, revision 2 after three +independent plan challenges (correctness, robustness, simplicity: 47 +findings, folded in; the changes are listed in I.3). Nothing implemented. +Applies the owner's brief of 2026-10-12 (Step 7 closed; hosting = +self-hosted Supabase first, managed later; eight private buckets closed by +default; quarantine + server validation; avatar as first consumer; service +role never in the browser). + +Part I states the facts the design rests on. Part II is the proposed design. +Part III answers the ten security questions of the brief. Part IV lists the +exact scope, the tests, the risks and the decisions the owner has to take. + +--- + +## Part I — Facts + +### I.1 What exists today + +| Area | State | +|---|---| +| Storage | One bucket, `anatomical-sheet-assets` (migration `20261009100000`): private, SVG only, 20 MiB cap, content-addressed keys `.svg`, SELECT policy through the sheet (`private.can_read_sheet_asset_object`), no API write policy, operator upload script with the service key, `confirm_sheet_asset_upload` RPC (service role). pgTAP 006 (28 checks) runs on the PGlite shim and on the real stack; pgTAP 001 pins the exact list of `private` functions `authenticated` may execute. | +| Storage API | `storage-api v1.79.36` locally (same image family as self-hosted). Verified on the client library (storage-js 2.117): an upload with the user JWT and `upsert: false` needs only an INSERT policy on `storage.objects`, evaluated on `bucket_id` and `name`; the bucket MIME check runs before RLS on the multipart part type (the browser's `File.type`, not sniffed); `createSignedUrl` evaluates the SELECT policy as the caller and answers 400 when denied; a signed upload URL is checked at signing time only and stays valid two hours. Image transformation needs `imgproxy`, absent here and a paid add-on on managed. | +| Profiles | `avatar_asset_id` was deferred to this step (comment in `20261008100100_profiles.sql`). | +| Shell UI | `UserBadge` (monogram) in the sidebar and the drawer; the top bar holds only the language switch; "Mon compte" = stacked sections, `PersonalInfoForm` first. The validated mockup shows the avatar with "Modifier la photo" inside the Profil section and an avatar + name in the top bar. Production CSP: `default-src 'self'`, `img-src 'self' data: blob:`. | +| SVG sanitiser | `packages/pdf/src/svg/{parse,sanitize,view}.ts`: `parseSvg` refuses DOCTYPE / ENTITY, `sanitizeSvgRoot` = allowlist of elements and attributes, in-document `href` / `url(#)` only, backslash refused, caps 20 000 elements / depth 64 / 256 `` / `stdDeviation` 100; `cleanSvgRoot` chains both. Hostile fixtures already covered by `packages/pdf/tests/security.test.ts` (script, `on*`, `javascript:`, external image, CSS escapes, ENTITY, 257 ``, `horse.svg` unchanged). Not exported from the package index; serialisation drops the XML declaration (byte change). | +| Edge runtime | Disabled in `config.toml`. `BACKEND_ARCHITECTURE.md` §6; C3: PostgreSQL-backed jobs before a queue; C12: the sanitiser runs between upload and publication. | +| Worker | The plan creates `apps/worker` at Step 19 (notifications). Files processing needs server-side code before that. | +| Deploy | No backend in production yet. The VPS `.env` is documented as non-sensitive. The VPS is shared by several SaaS (BDR-035). | +| sharp 0.35.5 | No install script, Node ≥ 20.9, prebuilt `linuxmusl-x64`. `rotate()` with no angle auto-orients from EXIF; output strips all metadata by default and converts through the embedded ICC profile to sRGB; `failOn` defaults to `warning` (stricter than `error`); `limitInputPixels` is enforced before `metadata()` returns. | +| Tests | pgTAP on PGlite + real stack; app vitest on happy-dom; Step 7 added a headless e2e script against the local stack. PostgREST `max_rows = 1000` caps set-returning RPCs. | + +### I.2 Corrections to the plan's Step 8 text + +- "RPC `issue_signed_url(asset_id)`" cannot exist in SQL: signing needs the + Storage API's secret. The Storage API signs only after the SELECT policy + passes, so the check and the signature already live in one place. For an + owner-only avatar, Step 8 does not sign at all (II.6). +- "Edge Function or SQL-only sanitizer": SQL cannot parse XML or decode + images; a containerised worker is the fit (II.1). +- "Upload a hostile SVG as a sheet asset and verify it is rewritten": no user + can upload a sheet asset before Step 13, so this manual check moves there + with the processor (D6). + +### I.3 Changes after the challenges (revision 2) + +Decoder isolated from the service key and bounded by a hard deadline; +write order PUT clean → commit → delete quarantine; `uploaded` rows +superseded by a new upload instead of a blocking unique index; purge queue +with a grace period longer than a backup run (the backup invariant was +false otherwise); every quarantine leftover auto-purged (signed upload URLs +can land bytes after the row moved on); client-side downscale as transport +(current phones exceed a 24 MP cap); owner-only avatar read by `download` +under RLS, no signed URL, no bearer token; schema narrowed to the one kind +that has rules (no multi-kind dispatcher, no derived-bucket trigger, no +unread columns); avatar pointer derived by a unique index instead of a +profile column + trigger; SVG processor, `migrate` and `reconcile` +commands, backup tooling and restore drill moved out of Step 8 (runbook +text stays); policy census pins one bucket literal per policy. + +--- + +## Part II — Proposed design + +### II.1 Components + +```text +Browser (anon key + user JWT) + │ pick file → decode → canvas downscale (transport) → JPEG blob + │ begin_avatar_upload (RPC) ─► assets row pending_upload + quarantine key + │ PUT object (Storage API, INSERT policy = that key, that row, that user) + │ confirm_asset_upload (RPC) ─► status uploaded + │ poll own assets row ─► clean | rejected + │ download(object_key) (Storage API, SELECT policy) ─► blob URL ─► + ▼ +Supabase (self-hosted compose, later managed) + PostgREST ─ public.assets, RPCs, private helpers Storage API ─ 8 private buckets + ▲ + │ claim_avatar_jobs / complete_avatar_job / reject_avatar_job (service role) + │ claim_purges / ack_purge (service role) + │ GET quarantine, PUT clean, DELETE objects (service role) +apps/worker — container faunosteo_worker, outbound only, no port + keyed I/O loop ──stdin/stdout──► unkeyed decode child (sharp), 20 s deadline, SIGKILL + sweeper: purge queue (row-driven), quarantine leftovers (key-driven) +``` + +Why a worker: image validation needs a native decoder on the server side, +behind the service key, with a hard resource bound. Postgres cannot read +object bytes; a client-side re-encode is not validation (a polyglot +passes); pg_net or a webhook would give the worker an inbound port. Edge +Functions would be one more container on self-hosted too, hand-deployed, +and on managed they decode in WASM under a CPU and memory budget not sized +for photos (`sharp` is native and cannot run there). The worker is one Node +24 container, the same code against the local stack, the VPS and a managed +project (URL + key only). It is the `apps/worker` of plan Step 19, arriving +early with one job family; Step 19 extends it. + +Dependency added: `sharp` 0.35.x (libvips). The only maintained Node +library that decodes JPEG / PNG / WebP, resizes, re-encodes and strips +metadata; pure-JS alternatives cover PNG only or are unmaintained. The +worker imports no workspace package, so Node 24 runs its TypeScript +directly (type stripping), no bundler, no `tsx`. + +### II.2 Buckets + +All eight private. One migration, `on conflict (id) do update`, so it +converges on the local stack, the VPS and managed alike. + +| Bucket | Owning domain and step | Step 8 state | +|---|---|---| +| `avatars` | Identity (self) | **open**: SELECT + INSERT policies through `assets`, 5 MiB, image/jpeg · png · webp | +| `logos` | Organizations, Step 10 | closed, no policy, no cap yet | +| `professional-documents` | Verification, Step 9 | closed | +| `client-files` | Clients, Step 12 | closed | +| `animal-files` | Animals, Step 12 | closed | +| `report-files` | PDF artifacts, Step 15 | closed | +| `anatomical-sheet-assets` | Sheets (existing policy, kept) | unchanged | +| `imports` | Imports, Step 24 | closed | + +"Closed" = the bucket row exists with `public = false`, no policy on +`storage.objects` names it, so `anon` and `authenticated` can neither list, +read, upload, update nor delete; only the service role can. Caps and MIME +lists of closed buckets are set by their own step. A pgTAP census asserts +that every `storage.objects` policy pins exactly one bucket literal +(`bucket_id = '…'`), counts them per bucket (2 on `avatars`, 1 on +`anatomical-sheet-assets`, 0 elsewhere) and pins the total, so a generic +policy naming no bucket cannot open the others. + +Open point (D2): the brief names the sheet bucket `anatomical-sheets`; the +repository already has `anatomical-sheet-assets` with policy, operator +script, tests and seed. Recommendation: keep the name, record the deviation. + +### II.3 `public.assets` and the RPCs + +One row per file, created before the bytes exist, kept after they are gone +(status `deleted`) until the purge queue has been served. + +```sql +create type public.asset_status as enum + ('pending_upload', 'uploaded', 'clean', 'rejected', 'deleted'); + +create table public.assets ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null references public.profiles (id) on delete cascade, + kind text not null check (kind in ('profile_avatar')), -- extended per step + bucket_id text not null check (bucket_id = 'avatars'), -- extended with kind + object_key text not null unique, -- final key, server-built + quarantine_key text, -- upload key, null once purged + status public.asset_status not null default 'pending_upload', + declared_mime text not null, + declared_size integer not null check (declared_size between 1 and 5242880), + byte_size integer, -- clean output + sha256 text check (sha256 ~ '^[0-9a-f]{64}$'), + rejection_reason text, -- closed codes, II.7 + attempts smallint not null default 0, + locked_at timestamptz, -- lease, II.8 + created_at timestamptz not null default now(), + updated_at timestamptz not null default now() +); +-- "the" avatar of an account = its single clean row (no profile column, no trigger) +create unique index assets_one_clean_avatar + on public.assets (owner_id) where kind = 'profile_avatar' and status = 'clean'; +create index assets_claimable on public.assets (created_at) where status = 'uploaded'; +``` + +Privileges: `revoke all` from API roles, `grant select` to `authenticated`, +RLS `assets_select_own` (`owner_id = auth.uid()`). No INSERT / UPDATE / +DELETE policy: every write is an RPC (security definer, `search_path = ''`, +authorisation before lookup, EXECUTE revoked from PUBLIC, granted per role, +`private.log_event` on sensitive transitions). pgTAP 001's census of +`private` functions executable by `authenticated` is updated for the two +new predicates. + +| RPC | Role | Effect | +|---|---|---| +| `begin_avatar_upload(declared_mime, declared_size)` | authenticated | locks the caller's `profiles` row (`for update`, serialises a double click); rate: ≤ 10 rows of the caller created in the last hour, all statuses counted → `rate_limited`; global ceiling: sum of `declared_size` of non-deleted rows < `private.storage_ceiling()` → `storage_full`; caps (type in the list, size ≤ 5 MiB); supersedes any `pending_upload` / `uploaded` row of the caller (→ `deleted`, enqueued for purge); inserts the row with `object_key = profiles///avatar.webp`, `quarantine_key = quarantine///upload`; returns `{asset_id, bucket_id, quarantine_key}` | +| `confirm_asset_upload(asset_id)` | authenticated | own row, `pending_upload`, a `storage.objects` row exists at `(bucket_id, quarantine_key)` with `metadata->>'size'` ≤ cap → `uploaded`. Kept as an explicit client signal: the worker never has to guess from Storage API internals whether a PUT finished | +| `remove_avatar()` | authenticated | every `profile_avatar` row of the caller not already `deleted` / `rejected` (clean and in flight) → `deleted`; logs `asset.avatar_removed` | +| `claim_avatar_jobs(max_jobs)` | service_role | `uploaded` rows with `locked_at is null or locked_at < now() - 10 min` and `attempts < 3`, `for update skip locked`, oldest first → sets `locked_at`, `attempts + 1`, returns the rows; a row at its 3rd expired lease becomes `rejected (processing_error)` instead. VOLATILE (a STABLE function runs read-only through PostgREST) | +| `complete_avatar_job(asset_id, byte_size, sha256)` | service_role | guard `status = 'uploaded'` (a superseded row is not completed: the worker then deletes what it wrote) → marks the caller's previous `clean` avatar `deleted` (enqueued), sets the row `clean`; one transaction; logs `asset.avatar_set` | +| `reject_avatar_job(asset_id, reason)` | service_role | guard `uploaded` → `rejected` with a closed code; logs `asset.rejected` | +| `mark_quarantine_purged(asset_id)` | service_role | nulls `quarantine_key` after the worker deleted the quarantine object of a `clean` row | +| `claim_purges(max_items)` / `ack_purge(purge_id)` | service_role | the purge queue, II.9 | + +Why `assets` does not absorb `anatomical_sheet_assets`: that table is +content-addressed and sheet-scoped (BDR-032/034) with its own confirmed +upload path; the kinds that join `assets` later (logos, documents, client +and animal files, report files, imports) extend the `kind` CHECK and add a +predicate branch at their step. The profile pointer is derived by the +unique index rather than the pre-announced `profiles.avatar_asset_id` +column: no cross-table write, no trigger, three fewer tests; a column can be +added additively when a public profile needs a join (D5). + +### II.4 Object keys + +- Final: `profiles///avatar.webp`. The name is fixed per + kind; the user's filename never reaches the server. +- Quarantine: `quarantine///upload` in the same bucket. + No API role can read it: the SELECT predicate only matches the + `object_key` of a `clean` row, the INSERT predicate only the + `quarantine_key` of the caller's `pending_upload` row. +- Keys are built by the RPC from uuids; the policies compare whole strings, + no prefix match, no `storage.foldername()`, so the PGlite shim and the real + stack evaluate the same expression. The asset id in the key lets the + sweeper classify a leftover without a row. +- Sheet assets keep `.svg` (shared drawings, immutable versions). + +### II.5 Upload and processing (avatar) + +1. Browser: `File.size` ≤ 20 MiB (sanity), `createImageBitmap` decodes it + (else `unsupported_type`), draw on a canvas with the longest side capped + at 1024 px, `toBlob('image/jpeg', 0.9)`. This is transport only (phones + produce 24 MP / 8 MiB photos; a 1024 px JPEG weighs ~150 KB); the server + re-decodes and re-encodes regardless. The preview shows that blob in the + circle with `object-fit: cover`. Nothing uploaded yet. +2. "Enregistrer la photo" → `begin_avatar_upload('image/jpeg', blob.size)`. +3. `storage.from('avatars').upload(quarantine_key, blob, { upsert: false, contentType: 'image/jpeg' })` + with the user JWT. The INSERT policy accepts only + `(bucket_id = 'avatars', name = quarantine_key)` of a `pending_upload` + row owned by `auth.uid()`; `upsert` would need UPDATE and SELECT rights + the plan withholds on purpose. +4. `confirm_asset_upload(asset_id)` → `uploaded`. +5. Worker loop, fixed 2 s interval: `claim_avatar_jobs(1)` → GET the + quarantine object (service client, 30 s timeout on every network call). +6. Decode child: the I/O process spawns `decode.ts` with an empty + environment (no key, `PATH` only), feeds the bytes on stdin, reads the + result on stdout, kills it with SIGKILL after 20 s. The child: type from + magic bytes (JPEG `FF D8 FF`, PNG 8-byte signature, WebP `RIFF….WEBP`), + `sharp(bytes, { limitInputPixels: 16_777_216 })` with default `failOn`, + `sharp.cache(false)`, `sharp.concurrency(1)`, `metadata()` (format matches + the magic; 64 ≤ sides ≤ 4096; the pixel-limit error maps to + `dimensions`), `.rotate()`, `.resize(512, 512, { fit: 'cover', + position: 'centre' })`, `.webp({ quality: 82 })`, no `withMetadata()`: + EXIF, XMP, IPTC and the ICC profile are not copied (colours converted to + sRGB through the profile first). Output: one 512 × 512 WebP, sha256, + byte size. Data after a PNG `IEND` is ignored by the decoder and absent + from the output. +7. I/O process: PUT the clean bytes at `object_key` (`upsert: true`, + `contentType: 'image/webp'`; idempotent on retry) → `complete_avatar_job` + (commit) → DELETE the quarantine object → `mark_quarantine_purged`. A + refusal → `reject_avatar_job(reason)`; the quarantine object is + enqueued for purge by the status trigger. A `complete` refused by the + guard (row superseded) → the worker deletes the clean object it wrote. +8. Browser polls its own row (1 s, up to 30 s): `clean` → download the + photo; `rejected` → message from the closed code; still `uploaded` after + 30 s → "Traitement en cours, revenez dans un instant"; on the next visit + the account page loads any in-flight row and shows the same state. The + save button is disabled while a row of the caller is in flight; a new + pick supersedes it. + +Crash matrix (the retry is idempotent at every point): + +| Worker dies | Row | Objects | Recovery | +|---|---|---|---| +| before PUT clean | `uploaded`, lease set | quarantine | lease expires (10 min) → re-claim | +| after PUT clean, before complete | same | quarantine + clean | re-claim, PUT again (`upsert`), complete | +| after complete, before DELETE quarantine | `clean`, `quarantine_key` set | both | sweeper: quarantine leftovers of `clean` rows, then `mark_quarantine_purged` | +| 3rd lease expired | `rejected (processing_error)` | enqueued | purge queue | + +### II.6 Read path (owner-only, no signed URL) + +`storage.from('avatars').download(object_key)` with the user JWT: the +Storage API evaluates the SELECT policy, the bytes come back, the app keeps +a `URL.createObjectURL(blob)` in the auth store (revoked on change or sign +out) and uses it as `` in `UserBadge`, the account section and, if +D3 is accepted, the top bar. One download of ~30 KB per session; the +production CSP already allows `blob:` images, `connect-src` must name the +Supabase origin (already required by Step 7's API calls). + +Why not a signed URL: in Step 8 nobody but the owner reads the avatar, and a +signed URL is a bearer token that keeps serving after `remove_avatar` until +it expires. Signed URLs arrive with the first kind shared with other users +(documents, Step 9): issued by the Storage API after the SELECT policy, TTL +per kind, `download` flag for documents, query strings dropped from the +proxy access logs. + +### II.7 Rejection codes (closed set, phrased by i18n) + +Row codes: `unsupported_type`, `decode_failed`, `dimensions`, +`processing_error`. Client-side failure kinds (never rows): `too_large`, +`unsupported_type`, `rate_limited`, `storage_full`, `network`, `unknown`. +The raw library or supabase-js error never reaches a row or the screen; the +worker logs an allowlist of fields (asset id, code, duration) with control +characters escaped (LRN-044). + +### II.8 Worker runtime and operations + +- `apps/worker` (`@faunosteo/worker`): TypeScript run by Node 24, deps + `@supabase/supabase-js` and `sharp` only. No DB driver: every database + access is an RPC through PostgREST with the service key (one credential, + one transport; a managed project needs no open database port). +- Two processes in one container: the keyed I/O loop and the unkeyed decode + child per job (II.5 step 6). A decoder exploit lands in a process with no + key, no file access beyond stdin/stdout and a 20 s life; it can reach + Kong with anonymous rights only, which is what any browser has. +- Container `faunosteo_worker` (compose service `worker`): non-root, + `read_only: true` + `tmpfs /tmp`, `mem_limit: 512m`, `cpus: 1`, + `pids_limit: 64`, no published port, attached to the Supabase compose + network only (`internal`, Kong reachable, nothing else; a host firewall + rule would not filter container egress), `restart: unless-stopped`. A + watchdog exits the process when one loop iteration exceeds 60 s so the + restart policy fires (Docker never restarts an `unhealthy` container on + its own). Env file `.env.worker` (`SUPABASE_URL`, + `SUPABASE_SERVICE_ROLE_KEY`, `WORKER_ID`), `chmod 600`, separate from the + app `.env`, excluded from any backup copy of env files, readable through + `docker inspect` by the `docker` group (documented). +- Fairness: one in-flight avatar per account (begin supersedes), oldest + first → no account can queue more than one job. +- Sweeper every 10 min, two sources: (a) the purge queue (row-driven, II.9); + (b) key-driven: list `quarantine/` of the bucket, parse the asset id, + delete any object older than 3 h whose row is not `pending_upload` / + `uploaded` (covers bytes landed through a signed upload URL or a slow PUT + after the row moved on; the 3 h grace exceeds the 2 h validity of such a + URL). No operator step, no `--apply`. +- `sharp` updates: a Renovate / dependabot rule on the worker package, + not a manual chore. +- Local dev: `pnpm worker:dev` against the local stack (service key typed + into the shell as SUPABASE.md §8 already does). + +### II.9 Purge queue, orphans, replacement, deletion + +`private.object_purge_queue(id, bucket_id, object_name, not_before, +enqueued_at)` fed by triggers on `assets`: a transition to `deleted` or +`rejected` enqueues `object_key` and `quarantine_key`; a row DELETE (account +cascade) enqueues them too. `not_before` = now + 48 h for the final key of a +`deleted` row (longer than any backup run, II.10), now + 1 h for quarantine +keys and rejected uploads. The sweeper calls `claim_purges(max_items)`, +deletes each object (a missing object is a success), `ack_purge(id)`. The +only automated deletions are those two sources; a `clean` row's `object_key` +is never deleted (test). + +| Event | Row | Object | Cleanup | +|---|---|---|---| +| New avatar clean | new `clean`, previous `deleted` (same transaction) | previous object kept 48 h | queue | +| `remove_avatar()` | clean and in-flight rows `deleted` | kept 48 h | queue | +| New pick while in flight | superseded row `deleted` | its bytes, if any | queue; a `complete` for it is refused | +| Upload never confirmed | `pending_upload` superseded or expired by the next begin / after 24 h | maybe present | queue | +| Bytes landed after the row moved on | none or not pending | present | key-driven sweep after 3 h | +| Account deleted (Step 26) | rows cascade | enqueued by the DELETE trigger | queue | + +Access is cut by the row: a `deleted` or `rejected` row matches no read +predicate, and no URL outlives the policy check in Step 8 (download, not +signing). Object lifetime is eventual, bounded by the grace periods. + +Reconciliation (operator, documented in STORAGE.md, not a tool): one SQL +anti-join between `storage.objects` and `assets` (same database) lists +objects without a row and rows without an object per bucket; sheet assets +are checked against `anatomical_sheet_assets`. Reading only; deletions stay +row-driven. + +### II.10 Backups and restore on the VPS (self-hosted) + +- Storage backend `file` on a named volume `faunosteo_supabase_storage` + (kept across renames, BDR-035), on a filesystem separate from the + PostgreSQL volume with a quota, and a disk-usage alert: the VPS hosts + other products, a full disk would take PostgreSQL down with it. The S3 + backend (Scaleway Object Storage) remains the alternative when the volume + outgrows the disk: copy the files, change the backend env, rows unchanged. +- Global ceiling: `private.storage_ceiling()` (constant, 10 GiB to start) + checked by `begin_avatar_upload` on top of the per-account rate. +- Backup order: database dump first (whole instance, `storage` schema + included), files second. With the 48 h purge grace, every `clean` row of + the dump still has its object in the snapshot, provided the snapshot runs + within 48 h of the dump (the invariant the restore checks: every `clean` + row has an object). +- Restore: stop the worker, start the database, restore the dump, restore + the volume, start the rest, run the reconciliation query, start the + worker. Files newer than the dump have no row and are invisible to the + Storage API (it lists from `storage.objects`); the directory listing of + the volume against `storage.objects` finds them. +- Tooling (restic to Scaleway Object Storage, encrypted, dump in the same + run, write-only key with retention pruned from another host, the + Supabase secrets `JWT_SECRET` / `POSTGRES_PASSWORD` in the encrypted set, + `.env.worker` never in a plaintext copy) and the restore drill belong to + the self-hosted deployment runbook (plan Step 27 "backup/restore + rehearsal"). Step 8 writes the ordering, the invariant and the backend + choice in `STORAGE.md`; the owner runs every backup or restore command. + +### II.11 Migration to managed Supabase (runbook, no tool in Step 8) + +Order: freeze writes (stop the worker, maintenance notice); migrate the +schema (`supabase db push`, buckets and policies are SQL; the `storage` +schema itself is never dumped into managed); migrate the data rows +(`auth.users` through the Supabase auth migration path, then `public`: +profiles, roles, sheets, `assets`); copy the objects driven by the rows +(`assets` and `anatomical_sheet_assets`: for every `clean` / confirmed row, +download, verify sha256, upload at the same key, verify; paginate by keyset, +PostgREST caps a set at 1000 rows); run the reconciliation query on the +destination; switch `SUPABASE_URL` and the keys of the app and the worker; +resume. The service key of a self-hosted stack is a long-lived JWT: revoking +it means rotating `JWT_SECRET` (every key and session); documented, and a +reason to prefer managed secret keys once there. + +### II.12 UI (follows the validated mockup, no redesign) + +- Mon compte → Informations personnelles: avatar circle (photo, else the + monogram from `UserBadge`) with "Modifier la photo" under it, as drawn. + Picking a file shows the local preview in the circle with "Enregistrer la + photo" / "Annuler"; after saving, the circle shows "Traitement en cours…" + until the row is `clean`; "Supprimer la photo" appears when a photo + exists (one confirmation). Errors use `account.avatar.error.`. +- `UserBadge` (sidebar + drawer): photo when present, monogram otherwise. +- Top bar (D3): the mockup shows avatar + name with a chevron on desktop and + the avatar alone on mobile; Step 7 shipped the bar without a user element. + Proposal: add the avatar (and the name on desktop) as a link to Mon + compte, no dropdown (its content is undefined). Decision for the owner. +- Dashboard unchanged (the mockup shows no avatar in the content area). +- Accepted inputs at the picker: JPEG, PNG, WebP; never SVG for avatars. + What the browser cannot decode is refused there with `unsupported_type`; + what it decodes is sent as JPEG and judged again by the worker. + +--- + +## Part III — The ten security questions + +1. **Access control**: the `assets` row is the authority. The two policies + on `storage.objects` are bucket-scoped + (`bucket_id = 'avatars' and private.can_read_avatar_object(uid, name)`, + same for upload) and look the key up in `assets` (status, owner, kind). + A bucket without policy is unreachable by API roles; the census pins one + bucket literal per policy and the counts. +2. **No cross-user access**: the read predicate requires a `clean` row with + `owner_id = auth.uid()` whose `object_key` equals the requested name; the + path is never trusted, only the row. Listing is denied the same way. + pgTAP: Bob reads nothing of Alice, cannot upload at her key, cannot + confirm her row; real-stack e2e: Bob's `download` of Alice's key → 400. +3. **Keys**: server-built from uuids by the RPC, canonical file name per + kind, no user filename anywhere, whole-string comparison in the policies. +4. **Signed URLs**: not used in Step 8. An owner-only avatar is read by + `download` under RLS and shown through a blob URL, so no bearer token + exists and a removed avatar stops being readable at the row flip. When a + shared kind arrives (documents, Step 9): Storage API signing after the + SELECT policy, TTL per kind (60 s and `download` for documents), query + strings dropped from access logs, the row cuts signing and the purge cuts + serving. +5. **Quarantine**: upload lands under `quarantine/` with the row + `pending_upload` → `uploaded`; no API role can read it; only the worker + reads it, writes the clean bytes under the final key, commits the row, + deletes the quarantine object. Every transition is an RPC; the browser + cannot set `clean`. Bytes landed late (signed upload URL, slow PUT) are + swept by key after 3 h without an operator. +6. **Dangerous SVG**: avatars never accept SVG (the browser decodes raster + only, the worker checks magic bytes, the bucket lists three raster types). + For sheet drawings the allowlist sanitiser exists and is tested on + hostile fixtures (`packages/pdf`); it becomes the worker's SVG processor + at Step 13 with its producer, after a pre-parse byte and tag-count cap + (the DOM is built before the element cap counts) and a bounded removed + list (D6). +7. **Images without metadata**: the worker never stores the uploaded bytes. + The browser already re-encoded through a canvas (no EXIF survives), and + the worker decodes again (type from magic bytes, 16.7 MP pixel cap, sides + ≤ 4096), applies the EXIF orientation if any, resizes and re-encodes to + WebP without `withMetadata()`: no EXIF, XMP, IPTC or ICC chunk in the + output. Tests: an EXIF-laden JPEG fed directly to the worker yields an + output without `EXIF` / `XMP ` / `ICCP` chunks, upright. +8. **Orphans**: replacement, removal, supersede and rejection flip the row + in one transaction and enqueue the keys; the sweeper serves the queue + after the grace period and sweeps quarantine leftovers by key; a `clean` + row's object is never deleted; the reconciliation query reports the rest. +9. **Backups and restore**: file backend on a named, quota-limited volume; + dump first, files second, 48 h purge grace so every `clean` row of a dump + has its object; restore in the documented order followed by the + reconciliation query; tooling and drill in the deployment runbook. +10. **Managed migration**: same migrations; rows then objects driven by the + rows with hash verification; keys and URLs switched by env; write freeze + during the copy. + +Service role: only `.env.worker` and operator commands hold it; the decode +child never sees it; `env.js` is generated from `APP_*` variables only. + +--- + +## Part IV — Scope, tests, risks, decisions + +### IV.1 Exact scope of the implementation + +In: + +- Migration `20261012100000_files_foundation.sql`: `asset_status`, `assets` + (CHECKs, indexes), seven bucket rows (the existing one untouched), + `private.can_read_avatar_object` / `can_upload_avatar_object`, + `storage.objects` SELECT + INSERT policies for `avatars`, + `private.object_purge_queue` + triggers, `private.storage_ceiling()`, the + nine RPCs of II.3, explicit EXECUTE revokes. pgTAP `010_files_foundation.sql` + (allowed and denied cases, policy census), pgTAP 001 census update, shim + extension if a column is missing, `database.types.ts` regenerated. +- `apps/worker`: I/O loop, decode child, sweeper (queue + key-driven), + watchdog, Dockerfile (`node:24-alpine`, non-root), compose service, + `.env.worker.example`, vitest on fixtures (with wall-time and RSS + assertions on the pathological ones), an integration test against the + local stack run by the CI `supabase` job. +- `packages/supabase/src/assets.ts`: `beginAvatarUpload`, + `uploadToQuarantine`, `confirmAssetUpload`, `removeAvatar`, + `fetchOwnAvatar` (clean or in flight), `downloadAvatar`; closed + `AssetFailure` kinds. +- `apps/app`: avatar block in `PersonalInfoForm` (picker, canvas transport, + preview, save, processing, delete), `UserBadge` photo, top bar avatar if + D3 = yes, auth store blob URL, i18n keys FR/EN, component and store tests. +- Docs: `docs/development/STORAGE.md` (model, keys, statuses, worker + operations, purge and grace rules, reconciliation query, backup ordering + and invariant, managed migration runbook), DEPLOY.md (worker service, env + file, network, CSP `connect-src`), SUPABASE.md (worker in dev), CLAUDE.md, + CHANGELOG; plan note (worker early, SVG processor at Step 13). +- CI: worker typecheck / lint / test / build, `docker build` of the worker + image, worker integration test in the `supabase` job. + +Out (named so nothing is implied): SVG processor and user SVG upload path +(Steps 13 / 17), logos, documents, client / animal / report / import flows +(their steps), signed URLs, image transformations, public profile photo, +`profiles.avatar_asset_id`, the production deployment of the self-hosted +stack, backup tooling and restore drill, migration and reconcile tools, +account erasure (Step 26), Realtime, a user menu dropdown. + +### IV.2 Test scenarios + +pgTAP (PGlite + real stack), every case with its denial twin: + +- buckets: eight rows, all private; `avatars` cap and types; census: one + bucket literal per policy, 2 / 1 / 0 per bucket, total pinned; + `authenticated` cannot insert nor select in a closed bucket. +- `begin_avatar_upload`: keys of the right shape; wrong type, oversize → + denied; 11th begin within the hour fails even after supersedes; ceiling + reached → `storage_full`; a begin while a row is `pending_upload` or + `uploaded` supersedes it (`deleted`, queue row written); anon denied. +- upload policy: Alice inserts at her quarantine key; Bob at her key → + 42501; Alice at a final key, at the key of a `clean` row, at a superseded + key, at an unknown key → denied; no UPDATE / DELETE policy exists. +- confirm: own pending row with the object present → `uploaded`; without + the object → error; Bob confirming Alice's row → denied; twice → error. +- read policy: Alice reads her `clean` object only; nothing while + `pending_upload` / `uploaded` / `rejected` / `deleted`; the quarantine + object never; Bob nothing; anon nothing. +- worker RPCs: `authenticated` cannot execute any; claim leases oldest + first and skips a live lease; an expired lease is re-claimed; the third + expiry rejects with `processing_error`; complete marks the previous clean + avatar `deleted` and enqueues it atomically; complete on a superseded row + is refused; reject stores a closed code; the queue holds the right keys + with the right `not_before`; a `clean` row's `object_key` never enters + the queue. +- `remove_avatar`: clean and in-flight rows → `deleted`; a later complete + of the in-flight row is refused (the photo does not reappear). +- cascade: deleting a profile enqueues its keys (trigger). +- audit: `asset.avatar_set`, `asset.avatar_removed`, `asset.rejected` rows. + +Worker (vitest, fixtures under `apps/worker/tests/fixtures`): + +- decode child: JPEG / PNG / WebP accepted; PNG bytes under a `.jpg` name + accepted as PNG (the name is never seen); GIF, BMP, SVG, PDF, HTML → + `unsupported_type`; truncated → `decode_failed`; 32 px → `dimensions`; + header-declared 20 000 × 20 000 and a 5000 × 5000 → `dimensions` through + the pixel limit; EXIF-laden rotated JPEG → upright output without EXIF / + XMP / ICCP chunks; PNG with a trailer after IEND → accepted, trailer + absent from the output; output always 512 × 512 WebP under a size bound; + pathological-but-within-cap fixtures (progressive JPEG with many scans, + large ICC) finish under the deadline with RSS asserted; a child that + sleeps is killed at 20 s → `processing_error`. +- I/O loop: claim → decode → PUT → complete → DELETE sequence; complete + refused → the clean object is deleted; Storage error → row left for the + lease; the child never receives the environment; sweeper serves the queue + and the key-driven list only, never a `clean` `object_key`. + +Integration (local stack, CI `supabase` job): Alice's full flow with the +service key for the worker side → row `clean`, object at the final key, no +quarantine object; a second upload replaces, the first object disappears +once its `not_before` is reached (clock-shifted in the test); `remove_avatar` +then sweep → bucket empty; a signed upload URL obtained during +`pending_upload` and used after supersede → object swept by key. + +Real-stack e2e (scratchpad script, like Step 7): Alice `download` 200, Bob +`download` of Alice's key 400, anon 400, Alice's quarantine key 400, a +direct GET of the object path without JWT 400. + +App (vitest + happy-dom): picker refuses a file the browser cannot decode +with the phrased error; preview appears before any request; save calls +begin → upload → confirm in order with a JPEG blob; processing state then +photo on `clean`; rejection message per code; delete flow; in-flight row +shown on mount; save disabled while in flight; `UserBadge` shows the photo +when the store has a blob URL, the monogram otherwise; i18n parity. + +Manual validation (owner): upload, replace, delete from Mon compte on +desktop and mobile with a phone photo; photo visible in the sidebar, the +drawer and the top bar; open the object path in a private window (400); +upload a renamed PNG (accepted) and an HTML file (refused with a clear +message); sign in as another seeded user and check nothing of the first +user shows. + +### IV.3 Risks + +- **Decoder vulnerabilities** (libvips / libwebp history): confined to a + keyless child with a 20 s life; the keyed process never decodes; `sharp` + updates automated. Residual: a child exploit reaches Kong with anonymous + rights, which any browser has. +- **Worker down or stuck**: uploads stay `uploaded`; the UI says so; the + watchdog exits on a hung loop and the restart policy restarts the + container; a stuck decode is killed by the deadline; an account can + always supersede. Monitoring and alerting are Step 27. +- **Disk**: separate quota-limited filesystem, global ceiling, per-account + rate, 48 h grace. Residual: a burst of accounts within the ceiling fills + the quota, not the host. +- **CSP in production**: `connect-src` must include the Supabase origin + (already needed by Step 7); documented in DEPLOY.md. +- **PGlite shim vs real `storage` schema**: policies use only `bucket_id` + and `name`; pgTAP never deletes storage objects (LRN-041). +- **Storage API behaviour relied on**: INSERT policy on direct upload, + SELECT policy on `download`, signed upload URL semantics; the integration + test on the CI stack pins them on the pinned image. +- **Service key handling**: a second env file, `chmod 600`, excluded from + env backups; rotation = `JWT_SECRET` rotation on self-hosted (documented). +- **Colour**: ICC profiles are converted to sRGB then dropped; only + out-of-gamut colours clip. Accepted for an avatar. +- **Plan deviations**: worker at Step 8 instead of 19; SVG processor at + Step 13; avatar pointer derived instead of a profile column. Recorded. + +### IV.4 Decisions for the owner + +| Id | Question | Recommendation | +|---|---|---| +| D1 | Server-side processing runtime | Containerised worker `faunosteo_worker`, keyless decode child; no Edge Functions (no native decoder, WASM budget on managed, one more container on self-hosted anyway) | +| D2 | Sheet bucket name | Keep `anatomical-sheet-assets`, record the deviation from the announced `anatomical-sheets` | +| D3 | Top bar avatar | Add avatar (+ name on desktop) as a link to Mon compte, no dropdown; or sidebar / drawer / account only | +| D4 | Avatar pipeline | Browser: decode, canvas ≤ 1024 px, JPEG transport. Server: magic check, ≤ 16.7 MP, one 512 × 512 WebP, centre crop, no metadata. Inputs JPEG / PNG / WebP ≤ 5 MiB at upload | +| D5 | Avatar pointer | Derived from the single `clean` row (unique index), no `profiles.avatar_asset_id` yet | +| D6 | SVG processor | Deferred to Step 13 with its producer; the sanitiser and its hostile fixtures already exist in `packages/pdf` | +| D7 | Read path | `download` under RLS + blob URL (no signed URL, no bearer) for the owner-only avatar | +| D8 | Processing feedback | Browser polling of the own row (1 s, 30 s cap), worker at a fixed 2 s; Realtime stays off | +| D9 | Self-hosted Storage backend | File backend on a named, quota-limited volume; dump-first backups with 48 h purge grace; tooling at the deployment step |