diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b09f3a57..8958d1b4 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -135,7 +135,17 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [ ] 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) + - [ ] R0 foundation (GO 2026-10-12, BDR-045; branch feature/rust-r0-foundation; Annex B; owner constraints: builds reproducible in Docker, no Rust on the VPS, live deployment untouched, frontend never loads the module, no R1): + - [x] R0.1 toolchain: `docker/rust-builder.Dockerfile` (rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy), `docker/rust-run.sh` (named volumes faunosteo_cargo_registry / faunosteo_rust_target), `docker/rust-check.sh`, `docker/wasm-build.sh` (CLI/crate version lock), root scripts rust:builder / rust:check / wasm:build / worker:test / worker:image + - [x] R0.2 workspace: Cargo.toml (3 members, pinned deps, lints unwrap/expect/disallowed_methods, dev deps optimised), rust-toolchain.toml 1.99.0, rustfmt/clippy/deny config, .cargo/config.toml (wasm stack 1 MiB, TS_RS_EXPORT_DIR), Cargo.lock, .gitignore/.dockerignore (target, pkg) + - [x] R0.3 crates/core: js_number + JsPrettyFormatter (JSON.stringify semantics), report contract types (SheetRef, ReportZone, Vertebra, LateralSide, Unresolved) with optional-absent / nullable-null, facade `call(op, json)` with closed kinds; 12 cargo tests + ts-rs export (4 types committed under packages/core-wasm/types) + - [x] R0.4 crates/wasm: facade (core_version, call, panic_for_test, recurse_for_test); build 224,713 B raw / 85 KB gzip (float_roundtrip on), instantiate ≈ 3 ms in Node + - [x] R0.5 crates/worker: plain main, `decode` child (env check → rlimits AS 512 MiB / CPU 10 s soft, 12 s hard → seccomp allowlist TSYNC kill) → image decode with Limits → orientation → resize_to_fill 512 → libwebp-sys lossy; parent `Spawner` (env_clear, 512 KiB output cap, deadline, signal classification) + `webp_check` (RIFF allowlist, dims, no metadata); `run --check`, `version`; test-hooks (fixtures, violate, flood, alloc, spin, print-allowlist); Dockerfile alpine musl → test stage (sandbox tests + strace derivation) → distroless/static:nonroot + - [x] R0.6 packages/core-wasm: loader (lazy, Node bytes), generated types, vitest proofs (facade, serialisation byte-equal with JSON.stringify on 4 real documents + number cases + Zod readers, panic/stack traps, size budget) skipped with a notice when pkg/ is absent + - [ ] R0.7 proofs recorded with numbers in RUST.md: panic=abort + fresh instance path; float_roundtrip finding; musl static + libwebp ≥ 1.6 build; seccomp allowlist derived by strace and proven on the corpus; CSP with/without 'wasm-unsafe-eval' under the production nginx config (headless Chromium); size/instantiate; runner cache (not measurable here: documented as pending on the forge) + - [ ] R0.8 CI: job `rust` (builder image, fmt/clippy/test/deny, wasm build, types drift), worker test stage + runtime image build in the docker job, nightly advisories, manual `release-images` workflow (digest output, no auto deploy) + - [ ] R0.9 docs: docs/development/RUST.md, DEPLOY.md (prepared: pull by digest, CSP line, gzip wasm, rollback = previous digest; live deployment unchanged), WORKSPACE.md, packages/README.md, CLAUDE.md (stack, map, commands), TEST_STRATEGY.md, CHANGELOG + - [ ] R0.10 gates: `pnpm check` (existing suites untouched), verifier contract, security-auditor; memory (BDR/LRN/EVAL/journal); stop for owner validation, R1 not started - [ ] 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6583db1f..ef5d35e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added (Rust foundation, plan R0) + +- **Rust by default** (rule adopted 2026-10-12, `docs/development/RUST_ARCHITECTURE_REVIEW.md`): Cargo workspace with three crates, `crates/core` (contracts and the JavaScript-compatible JSON formatter, no I/O by lint), `crates/wasm` (browser facade built into `packages/core-wasm/pkg`) and `crates/worker` (the future file-processing worker: sandboxed `decode` child with rlimits and a seccomp allowlist derived by `strace`, image decoding in pure Rust, lossy WebP through libwebp confined to the child, parent-side container check; `run --check` only, no job loop before R1). Reference toolchain in Docker (`docker/rust-builder.Dockerfile`, `pnpm rust:check`, `pnpm wasm:build`), worker image on `distroless/static`, CI job `rust`, nightly advisories, manual digest-tagged image workflow (no deploy). R0 proofs recorded in `docs/development/RUST.md`: `float_roundtrip` required for JSON parity, traps leave a wasm instance unusable (fresh instance per recovery), CSP needs `'wasm-unsafe-eval'`. No application behaviour, interface, archive or database change; the frontend does not load the module. + ### Added (SaaS migration, plan Step 7) - **Identity (Step 7)** — sign-in and sign-up by email/password (confirmation mandatory, policy 12 chars + lower/upper/digit), password recovery, OAuth buttons (Google, Apple) driven by `APP_AUTH_PROVIDERS`, landing route for confirmation / OAuth links; the guarded `/app` shell (desktop sidebar, light top bar, mobile drawer) with a dashboard (greeting, profile completeness, local tool, account) and **Mon compte** (personal, professional, preferences, security). Profile columns `practice_name`, `professional_title`, `siret` (migration `20261011100000`, pgTAP 009), language synced with `profiles.locale`, platform roles shown read-only. GoTrue TOTP enabled server-side; MFA enforcement for platform roles documented as a gap (`docs/development/IDENTITY.md`). The local tool (`/`, `/new`, `/editor`) stays unauthenticated; the Home header links to the space only when Supabase is configured. diff --git a/CLAUDE.md b/CLAUDE.md index bd05dd49..dbb5f0b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,6 +52,9 @@ MVP species: equine only. Open-source MIT. | DB client | @supabase/supabase-js (packages/supabase) | 2.x | | SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 | | Deploy | Docker multi-stage → nginx:alpine | — | +| Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; every cargo command runs in `docker/rust-builder.Dockerfile` (`pnpm rust:check`, `pnpm wasm:build`), never on the VPS | 1.99.0 | +| WASM glue | wasm-bindgen crate = CLI version (locked in `docker/wasm-build.sh`), `ts-rs` types committed under `packages/core-wasm/types` | 0.2.129 / 12 | +| Worker image | `crates/worker/Dockerfile`: `rust:1.99.0-alpine3.24` (musl, libwebp via `cc`) → `distroless/static:nonroot`; sandbox tests + seccomp derivation in the `test` stage | — | --- @@ -99,6 +102,13 @@ pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview de pnpm preview:draft # same, then serves it pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings) pnpm report:compare ... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md) + +# Rust (docs/development/RUST.md) — all through the builder image, no toolchain on the host +pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0) +pnpm rust:check # fmt --check, clippy -D warnings, cargo test (core, wasm), ts-rs export, cargo deny +pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run +pnpm worker:test # crates/worker/Dockerfile stage test: sandbox tests + seccomp derivation on the musl binary +pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static, `run --check`) ``` ## Docker commands @@ -244,7 +254,14 @@ faunosteo/ │ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql │ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy ├─ packages/README.md ← shared packages index -├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker +├─ packages/core-wasm/ ← @faunosteo/core-wasm: loader of the browser module (pkg/ built, git-ignored), ts-rs types (committed), R0 proofs (panic, serialisation, size) +├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root) +│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced) +│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs) +│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check, `run --check`; Dockerfile, scripts/derive-seccomp.sh +├─ docker/rust-builder.Dockerfile, rust-run.sh, rust-check.sh, wasm-build.sh, csp-proof/ ← reference Rust toolchain + the CSP proof +├─ .gitea/workflows/ci.yml ← CI: rust job (builder image, fmt/clippy/test/deny, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) +├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy) ├─ .claude/{tasks/TODO.md,memory/,audits/} ├─ Dockerfile, docker-compose.yml, docker/ ├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json @@ -492,6 +509,7 @@ the owner's validation before any implementation; release 0.2.0 unaffected). - Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040). - After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision. - Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install. +- Rust: never on the host or the VPS; `pnpm rust:check` and `pnpm wasm:build` run inside the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed, the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes. - SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test` on the real stack when Docker is available; regenerate types (`pnpm db:types`). diff --git a/DEPLOY.md b/DEPLOY.md index ba9928ed..8015d106 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -21,6 +21,13 @@ The host should publish only ports `22`, `80`, `443` to the internet. The container port (`8080` by default) should stay loopback-only — the host reverse proxy reads from it on `127.0.0.1:8080`. +Rust (plan R0, `docs/development/RUST.md`): the repository also builds a +worker image (`crates/worker/Dockerfile`, static musl binary on +`distroless/static`, container `faunosteo_worker`). It is not deployed yet +(its job loop arrives at R1); the live deployment above is unchanged. The +production VPS never needs a Rust toolchain: images are built in CI and +pulled by digest ("Image deploy by digest", prepared below). + ### Reference sheet in the image (SHEET_BUNDLE) The application needs an anatomical sheet to work. Until sheets are served by @@ -563,6 +570,64 @@ already exported are unaffected. --- +## Image deploy by digest (prepared at R0, not yet applied) + +Decision D-R13 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Annex A and +C): production images are built in CI and the VPS pulls them; it never +compiles the Rust project, and the DEV1-XS memory limit stops mattering for +builds. The procedure below is prepared and documented now; it replaces +"Routine deploys" and "Rollback" above **only when the first image built +this way is deployed, after a separate validation**. Until then the live +deployment keeps building on the VPS as documented above. + +1. Build and publish: run the manual workflow `release-images` + (`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on + push) on the forge. It pushes `faunosteo_app:` and + `faunosteo_worker:` to the container registry named by the + `REGISTRY` secret (the forge's own Gitea registry is the recommended + choice, Scaleway Container Registry the alternative) and prints their + digests in the job summary. No workflow deploys anything. +2. Pin: `docker-compose.yml` on the VPS references the images by digest + (`image: //faunosteo_app@sha256:…`); the digest is the + only thing that changes at a deploy, by hand, after validation. +3. Deploy: `docker compose pull && docker compose up -d` (no `--build`), then + the post-deploy checks of "Routine deploys". +4. Rollback: set the previous digest back in `docker-compose.yml` and run + step 3 again; nothing is rebuilt and nothing needs crates.io or npm. +5. Registry credentials on the VPS: a read-only token in `~/.docker/config.json` + of the deploy user, never in the repository. + +Prerequisites checked at R0 and to re-check before the first digest deploy: +disk headroom on the VPS for two image generations (app ≈ 100 MB, +worker ≈ 9 MB, measured at R0), the registry reachable from the VPS, `docker compose pull` +working with the read-only token. + +### WebAssembly and the CSP (from R2 on) + +The application does not load the Rust core module before plan R2. When it +does, the two `Content-Security-Policy` headers of this file (nginx and +Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`: + +```text +script-src 'self' 'wasm-unsafe-eval'; +``` + +Proven at R0 under the production nginx image and headers with headless +Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in +`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses +to compile the module ("Compiling or instantiating WebAssembly module +violates the following Content Security policy directive"); with the keyword +the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation +only, never `eval` or inline scripts (the proof's inline variant was still +blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16 +(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by +`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains +`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types +application/wasm`) and the served, compressed size is what the D-R13 budget +counts. + +--- + ## Health checks | URL | Expected | diff --git a/docs/development/RUST.md b/docs/development/RUST.md new file mode 100644 index 00000000..9b9b63cd --- /dev/null +++ b/docs/development/RUST.md @@ -0,0 +1,260 @@ +# Rust in the Faunosteo monorepo + +Status: plan R0 (foundation), 2026-10-12, on `feature/rust-r0-foundation`. Rule +and roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III +boundary rules, Part VI phases R0–R5, Annex B R0 scope, Annex C owner +amendments). R0 ships the toolchain, the workspace skeleton, the worker's +sandboxed child, the browser module loader and seven experimental proofs. No +application behaviour, interface, archive or database changes; the frontend +does not load the module before R2; the worker's job loop arrives at R1. + +## 1. Toolchain: reproducible in Docker, never on the VPS + +Every cargo command runs inside the reference builder image, so CI and a +developer machine use the same compiler and the production VPS never needs +Rust (images are built in CI and pulled by digest, DEPLOY.md "Image deploy by +digest"). + +| Piece | Where | Pinned by | +|---|---|---| +| Rust 1.99.0, edition 2024, rustfmt, clippy, `wasm32-unknown-unknown` | `docker/rust-builder.Dockerfile` (`FROM rust:1.99.0-bookworm`) | `rust-toolchain.toml` (same channel; a difference would make rustup download inside the container) | +| `wasm-bindgen-cli` 0.2.129 | same image | `wasm-bindgen = "=0.2.129"` in `Cargo.toml`; `docker/wasm-build.sh` refuses to run when `Cargo.lock` and the CLI differ | +| `cargo-deny` 0.20.2 | same image | `deny.toml` | +| worker builder | `crates/worker/Dockerfile` (`FROM rust:1.99.0-alpine3.24`, `build-base` for libwebp) | same channel | + +Commands (root `package.json`): + +```bash +pnpm rust:builder # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold) +pnpm rust:check # docker/rust-check.sh: fmt --check, clippy -D warnings (all targets), + # cargo test (core, wasm), ts-rs export, cargo deny licenses/bans/sources +pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored), prints raw and gzip sizes +pnpm worker:test # crates/worker/Dockerfile stage test: 13 sandbox tests + seccomp derivation +pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static:nonroot) +bash docker/rust-run.sh cargo # any cargo command in the builder +``` + +`docker/rust-run.sh` mounts the repository at `/w` and keeps Cargo's registry +and the target directory in the named volumes `faunosteo_cargo_registry` and +`faunosteo_rust_target` (incremental builds take seconds). A local `rustup` +is optional for the inner loop (same `rust-toolchain.toml`); the container is +the arbiter. + +## 2. Workspace + +```text +Cargo.toml workspace (resolver 3), pinned [workspace.dependencies], lints, profiles +rust-toolchain.toml channel 1.99.0, components rustfmt + clippy +rustfmt.toml edition 2024, max_width 100 +clippy.toml disallowed-methods: std::time::*::now, std::fs::*, std::env::var* (the core) +deny.toml licences allow-list, bans (duplicates warn, wildcards deny, path deps allowed), sources +.cargo/config.toml wasm shadow stack 1 MiB (explicit), TS_RS_EXPORT_DIR = packages/core-wasm/types +crates/core faunosteo-core: lib, no I/O (lint), serde + serde_json only +crates/wasm faunosteo-wasm: cdylib facade over core (wasm-bindgen) +crates/worker faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit) +packages/core-wasm loader, generated types (committed), vitest proofs +``` + +Lints: `unwrap_used`, `expect_used` and `disallowed_methods` are errors in the +libraries (tests allow them explicitly at the top of the file); `unsafe_code` +is forbidden everywhere except the worker (libwebp FFI, each block with a +`SAFETY` comment). Dependencies are optimised even in debug builds +(`profile.dev.package."*"`) because the sandbox tests decode 4096² images +under a 10 s CPU limit. + +### 2.1 Boundary rules in code (review III.3) + +- `faunosteo_core::facade::call(op, json) -> json`: one operation name, one + JSON text in, the outcome envelope out (`{"ok":true,"value":…}` or + `{"ok":false,"kind":…,"detail":…}`), never a panic on content. R0 ops: + `core_version`, `pretty_json`, `sheet_ref`, `report_zone`. +- `faunosteo_core::json`: `js_number(f64)` prints floats as ECMAScript + `Number::toString`; `JsPrettyFormatter` is `serde_json`'s pretty formatter + with that rule; `to_js_pretty` and `pretty_js_round_trip` produce + `JSON.stringify(v, null, 2)` byte for byte (proof §5.2). +- `faunosteo_core::domain::report`: `SheetRef`, `ReportZone`, `Vertebra`, + `LateralSide`, `Unresolved`, field order of the Zod schemas, optional + fields `skip_serializing_if = "Option::is_none"`, nullable fields plain + `Option`, unknown keys ignored where Zod strips them. `cargo test -p + faunosteo-core --features ts` writes the TypeScript types to + `packages/core-wasm/types` (committed; CI fails on drift). +- `packages/core-wasm/src/index.ts`: `loadCore()` instantiates a **fresh** + module each time (cache-busting import of the glue), `callCore()` parses + the envelope, `isCoreBuilt()` lets the proofs skip when `pkg/` is absent. + +## 3. The worker (R0 skeleton, R1 job loop) + +`faunosteo-worker` is one static musl binary with subcommands dispatched by +a plain `main` (no async runtime, no thread), so `decode` installs its +sandbox in a single-threaded process: + +- `decode`: refuses a non-empty environment; checks `Threads: 1` in + `/proc/self/status`; `RLIMIT_AS` 512 MiB, `RLIMIT_CPU` 10 s soft / 12 s + hard (soft = hard made the kernel SIGKILL first, finding §5.4); seccomp + allowlist installed with TSYNC, `KillProcess` on anything else; then reads + ≤ 5 MiB on stdin, sniffs the format (JPEG, PNG, WebP), decodes with + `image::Limits` (sides ≤ 4096, alloc 256 MiB), applies the EXIF + orientation, `resize_to_fill` 512 × 512, encodes lossy WebP (q 82) through + `libwebp-sys` (C, this process only), writes stdout. Exit codes in + `exit_codes.rs` (10–18, never 1, 101 or a signal number). +- the parent side (`spawn::Spawner`, used by the tests now and by R1): + `env_clear`, stdin/stdout/stderr piped, output read up to 512 KiB (the + child is killed past it), 20 s deadline, classification of every exit + (`Produced`, `Rejected{code}`, `Signalled{signal}`, `OutputOverflow`, + `Timeout`, `Failed`). The parent **never decodes**: `webp_check::inspect` + parses the RIFF container only (chunk allowlist `VP8X`, `VP8 `, `VP8L`, + `ALPH`; canvas size from the headers; any `EXIF`, `XMP `, `ICCP` or unknown + chunk refuses the output; owner amendment of D-R4). +- `run --check`: prints the resolved configuration without secrets (which + variables are set, the linked libwebp version, refused below 1.6.0). A + plain `run` does nothing before R1 and says so. +- `version`: binary, workspace and libwebp versions. +- test hooks (`--features test-hooks`, never in a release build): fixtures + generated in memory (no binary in git), `--no-seccomp` (rlimits only, + prints the `SECCOMP-MARKER` line for the strace derivation), `--violate` + (`getcwd` after the filter), `--flood`, `--alloc-gib n`, `--spin`, + `print-allowlist`. + +Image: `crates/worker/Dockerfile`, stages `build` (release, static), +`test` (sandbox tests + `scripts/derive-seccomp.sh`), `runtime` +(`gcr.io/distroless/static-debian12:nonroot`, `USER nonroot`, `ENTRYPOINT +/faunosteo-worker`, `CMD run --check`). Measured 2026-10-12: image 8.7 MB (one static +binary), `run --check` exits 0 with `--read-only --cap-drop ALL +--security-opt no-new-privileges:true`. + +## 4. CI + +- Job `rust` (before `check`): builds the builder image, runs + `docker/rust-check.sh`, checks the committed ts-rs types for drift, builds + the browser module (size printed). +- Job `check`: builds the module the same way, then the existing Node + pipeline; the `core-wasm` proofs run because `pkg/` exists. +- Job `docker`: application image, worker `test` stage (sandbox tests and + seccomp derivation on the musl binary that ships), worker runtime image + started once with `--read-only --cap-drop ALL`. +- `rust-advisories.yml`: nightly and manual `cargo deny check advisories`, + out of the blocking path on purpose. +- `release-images.yml`: manual only; builds and pushes `faunosteo_app:` + and `faunosteo_worker:` to the registry of the `REGISTRY` secret and + prints their digests. Deploys nothing (DEPLOY.md "Image deploy by digest"). + +Not measured here: the forge runner's cache behaviour and cold build times +(the runner was not available from this host). The builder image build took +about 6 minutes cold on the development host; both image builds reuse +BuildKit cache mounts (`faunosteo_cargo_registry_musl`, +`faunosteo_target_musl`). + +## 5. R0 proofs (2026-10-12, development host, Docker 29.8 rootless, kernel 7.0) + +Each proof is a permanent test; the numbers are what the run produced. + +### 5.1 Panic strategy on wasm32 (`packages/core-wasm/tests/panic.test.ts`) + +- A Rust panic reaches JavaScript as `WebAssembly.RuntimeError` (`unreachable`): + the module is panic = abort, `catch_unwind` cannot be used there. +- Exhausting the 1 MiB shadow stack (2 000 000 frames of 128 bytes) traps + (`RuntimeError`) instead of corrupting memory. +- After a stack-exhaustion trap, the next call on the same instance fails in + the allocator (`memory access out of bounds`, deterministic). After a + plain panic the same instance *still answers*, with a stack pointer that + was never unwound: the dangerous case. Rule for R2: no instance is reused + after any trap; a fresh instance is a new module record (the wasm-bindgen + glue caches its instance in a module variable, and the ESM cache returns + the same module for the same URL: `loadCore()` imports with a cache-busting + query; in the browser the glue must be a static asset imported the same + way, or the core runs in a Worker recreated on trap). + +### 5.2 Serialisation contract (`tests/serialisation.test.ts`, `crates/core/tests`) + +- Byte equality with `JSON.stringify(JSON.parse(text), null, 2)` on + `report-v3.demo.json`, `report-v2.full.json`, the 296 KB equine + `document.json` and the 84 KB `report-migration-map.json`, plus a number + corpus (`1523`, `1715.4285714285713`, `0.85`, `1e+21`, `1e-7`, + `0.000001`, `-0` → `0`, `123456789012345680000`, `5e-324`, + `1.7976931348623157e+308`). +- Finding: `serde_json`'s default float parser is a documented fast path + that can be one ULP off; the first run printed `1715.428571428571` and + `123456789012345670000`. The `float_roundtrip` feature (enabled in + `Cargo.toml`) fixes it; the module grew from 187 KB to 225 KB raw. +- Optional fields absent, nullable fields `null`, unknown keys ignored, + `unresolved: false` refused; the current `ReportZoneSchema` and + `SheetRefSchema` (Zod 3, `@faunosteo/domain`) parse what the core writes. + +### 5.3 musl static binary with libwebp (`crates/worker/Dockerfile`) + +Builds on `rust:1.99.0-alpine3.24` with `build-base`; `libwebp-sys` 0.14.4 +compiles its vendored libwebp with `cc`; `WebPGetEncoderVersion()` reports +**1.6.0** (logged by `run --check`, test +`the_linked_libwebp_is_recent_enough`). The runtime image carries the one +static binary. + +### 5.4 seccomp allowlist, derived and proven (`crates/worker/tests/sandbox.rs`) + +- Derivation (`scripts/derive-seccomp.sh`, strace over png, jpeg, webp, a + 4096 × 4096 JPEG and a 3000 × 3000 PNG, after the marker): exactly + `read write mmap munmap mremap exit_group getrandom`. musl's mallocng used + neither `brk` nor `mprotect`; no `futex` in a single-threaded decode. The + allowlist is that set plus the abort path (`rt_sigaction`, + `rt_sigprocmask`, `getpid`, `gettid`, `tkill`, `tgkill`, `exit`). +- Proven on the musl binary that ships, inside Docker's default seccomp + profile: 13 tests green (`png_jpeg_and_webp_decode_through_the_full_sandbox`, + `inputs_at_the_caps_decode_within_the_limits` (4096²), dimensions 32 px + and 20 000² header, GIF and SVG refused, truncated PNG, non-empty + environment refused, `--violate` → SIGSYS 31, `--flood` → output cut, + `--alloc-gib 2` → SIGABRT 6 under `RLIMIT_AS`, `--spin` → parent deadline, + `--spin` → SIGXCPU 24 at the CPU soft limit, libwebp ≥ 1.6.0). +- Findings: with `RLIMIT_CPU` soft = hard the kernel sends SIGKILL (hard + limit checked first), indistinguishable from the parent's deadline kill; + the soft limit is now two seconds below the hard one. The 4096² decode + exceeded 10 s of CPU in an unoptimised debug build: dependencies are + optimised in every profile. + +### 5.5 CSP with `'wasm-unsafe-eval'` (`docker/csp-proof/run.sh`) + +Served `packages/core-wasm/pkg` through `nginx:1.31-alpine` with +`docker/nginx.conf` plus the exact `Content-Security-Policy` of +`DEPLOY.md`, loaded by headless Chrome for Testing 156: + +| Header | Result | +|---|---| +| production (`script-src 'self'`) | `FAIL WebAssembly.instantiateStreaming(): Compiling or instantiating WebAssembly module violates the following Content Security policy directive because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"` | +| `script-src 'self' 'wasm-unsafe-eval'` | `OK 0.1.0` (module instantiated, `core_version()` answered) | + +The keyword allows WebAssembly compilation only: an inline `