diff --git a/.cargo/config.toml b/.cargo/config.toml new file mode 100644 index 00000000..9bf3f9da --- /dev/null +++ b/.cargo/config.toml @@ -0,0 +1,10 @@ +# Workspace-level Cargo configuration (RUST_ARCHITECTURE_REVIEW III.3, III.5). + +[target.wasm32-unknown-unknown] +# The shadow stack of the browser module, set explicitly (the toolchain default is also +# 1 MiB). packages/core-wasm/tests/panic.test.ts proves that exhausting it traps. +rustflags = ["-C", "link-arg=-zstack-size=1048576"] + +[env] +# ts-rs writes the TypeScript types of the contracts here on `cargo test -p faunosteo-core --features ts`. +TS_RS_EXPORT_DIR = { value = "packages/core-wasm/types", relative = true } diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 2c75a0a5..ab4f9381 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -370,3 +370,15 @@ Status: active; awaiting D-R1..D-R14 validation. 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. + +## BDR-046 | 2026-10-13 | R0 implementation choices (Rust foundation) + +Choices made while building R0 (feature/rust-r0-foundation), within the validated review: (1) toolchain arbiter = Docker builder image (`docker/rust-builder.Dockerfile`, rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy baked in: official images ship rustup's minimal profile), `docker/rust-run.sh` with named volumes `faunosteo_cargo_registry` / `faunosteo_rust_target`; no rustup on the host, never on the VPS. (2) `serde_json` features `preserve_order` + `float_roundtrip` (default parser one ULP off, found by the proof). (3) Boundary = JSON strings + `ts-rs` types committed under `packages/core-wasm/types` with a CI drift check (no serde-wasm-bindgen/tsify). (4) Fresh wasm instance = cache-busting dynamic import of the glue (ESM cache returns the same instance otherwise); R2 must do the same in the browser or use a Worker per instance. (5) Worker: `RLIMIT_CPU` soft N / hard N+2 (soft = hard → SIGKILL first); seccomp allowlist = the 7 traced syscalls (read write mmap munmap mremap exit_group getrandom) + 7 abort-path ones, derived by strace in the Dockerfile `test` stage and compared on every build; dependencies optimised in the dev profile (4096² decode under the 10 s CPU cap); test hooks behind a cargo feature never in release; parent parses the RIFF container only (D-R4 amendment). (6) App `Dockerfile`, `docker/nginx.conf`, compose untouched at R0 (deviation from Annex B's "wasm stage built in CI": no consumer before R2, owner said live deployment untouched); CI `check` job builds the wasm itself (no artifact action dependency on the Gitea runner). (7) cargo-deny `allow-wildcard-paths = true` (a versionless path dep reads as a wildcard) and the core path dep declared per crate (workspace-inherited path dep hits a cargo-deny bug). (8) CSP proof committed as `docker/csp-proof/` (playwright-core outside the repo, documented). +Alt rejected: rustup on the dev host (owner: builds reproducible in Docker); wasm-pack; artifact upload/download between CI jobs (unverified on the forge); Landlock + NPROC/FSIZE/NOFILE (redundant under the allowlist, challenge finding). +Status: closed (R0 delivered, awaiting owner validation; R1 not started). + +## BDR-047 | 2026-10-13 | Native Rust toolchain primary on the Ubuntu dev server; Docker builder = reproducible alternative; no CI active + +Owner brief after R0 delivery: dev machine = self-hosted Ubuntu native (not WSL, not VPS), Docker rootless. Decision: daily Rust = native user-level rustup (channel from `rust-toolchain.toml`, wasm32 target, wasm-bindgen-cli 0.2.129, cargo-deny 0.20.2 via `cargo install --locked`, no sudo, no global package). Root scripts `rust:check` / `wasm:build` run `scripts/rust-check.sh` / `scripts/wasm-build.sh` natively (moved from docker/, PATH guard `scripts/rust-env.sh`); `rust:check:docker` / `wasm:build:docker` = same files through the builder image (kept, reference for a future runner, proof VPS never compiles). `pnpm check:all` (`scripts/check-all.sh`) = single pre-merge gate: rust check, types drift, wasm, `pnpm check`, app image, `worker:test`, `worker:image` read-only. Docker keeps Supabase, worker container (isolation untouched), sandbox + seccomp tests, images. Workflow files kept, headers "prepared, never executed"; no runner / secret / registry. Supersedes BDR-046 (1) "no rustup on host, container = arbiter". Names: existing script names stay = native (main path), `:docker` suffix = alternative; `check` stays the Node gate, `check:all` the full one. +Alt rejected: Docker as main path (owner: native loop; Docker for services only); scripts left under docker/ (misleading location); one script per environment (drift); `check:all` needing the Supabase stack (non-hermetic; `pnpm db:test` stays the complement after a supabase/ change). +Status: active; awaiting the owner's final validation before R1. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index a7dca81f..75dd55a2 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -129,3 +129,17 @@ Method: 4 read-only analyzers (domain, anatomy, pdf + app pdf side, app logic + 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. + +## EVAL-017 | 2026-10-13 | Rust R0 foundation — proofs in the real environment, 3 verifier passes, 3 security passes + +Method: contract `2026-10-13-rust-r0-verify.md` (16 criteria, CHECK/EXPECT) → fresh verifier; security-auditor on `5fec065..HEAD` (semgrep p/security-audit + p/secrets + p/owasp-top-ten + checklist + manual Rust review); all cargo commands through the Docker builder (no Rust on the host); worker sandbox tests + strace derivation inside the Alpine test stage on the release-profile musl binary; wasm proofs in vitest on the built module; CSP proof with the production nginx image + headers in headless Chrome 156. +Result: verifier pass 1 ECARTS(2), pass 2 CONFORME 16/16, pass 3 ECARTS(2) — every gap an oracle of MY contract (greps counting comment lines, the contract matching its own regex, the `[gated]` SAFETY form and a second refusal arm moved by the security fixes); code behaviour confirmed by reading each time. Security pass 1 BLOCK(1) HIGH real: shell injection via the `workflow_dispatch` input of release-images.yml, + 6 MEDIUM (shared BuildKit caches, tkill/tgkill without arg filters, core dumps, creds on the runner, no advisories gate, mutable action tag) → fixed; pass 2 PASS but 3 MEDIUM introduced by my fixes (ephemeral builder never used: GITHUB_ENV applied one step too late, silent fallback; `rm -rf "$VAR"`; content reaching the `Broken` outcome via `Reject::Internal`) → fixed; pass 3 PASS, 2 new MEDIUM (unpinned setup-node and `pnpm install` inside the token job) → gates moved to a secret-less job; remaining lows documented as R1/Step 27 follow-ups. Experimental findings (LRN-049): serde_json fast float path (float_roundtrip), traps leave the instance unusable + ESM cache, RLIMIT_CPU soft=hard → SIGKILL, minimal rustup profile, cargo-deny path wildcard, 7 traced syscalls, strace blind once dumpable=0 (marker became a syscall). Final: cargo 12+14 core tests, 9 unit + 16 sandbox worker tests on the release profile, 14 vitest proofs, root `pnpm check` 777 tests green, worker image 8.7 MB read-only/cap-drop, CSP refused/accepted as predicted, floor-guard clean ×3. +Anomalies: my contract oracles cost two verifier passes (lesson repeated from EVAL-013: run every CHECK once before dispatch, and re-run them after any fix commit); two of my own security fixes created new findings (an env variable applied too late, a recursive delete through a variable: the exact pattern the destructive-tools rule forbids) → fixes to CI files need the same adversarial pass as code; a scripted edit silently aborted on a rustfmt-reformatted string and the commit went out with the old test (caught by the next build); the `[gated 2026-10-13]` SAFETY markers were placed by me at the auditor's request, not by the owner → surfaced in the report for the owner's confirmation; one security-auditor Bash call (`cat` of two files) was refused twice by the auto-mode hook, the agent used Read instead (reported, no workaround). Not proven here: the Gitea runner (caches, timings, workflow syntax such as job-level env, actions/cache), HTTPS from the worker (no HTTP client before R1), browser-side fresh-instance mechanism (R2). +Action: owner validation of R0 (report with proved vs hypothetical); R1 not started. + +## EVAL-018 | 2026-10-13 | R0 correction: native Rust toolchain on the Ubuntu dev server — 2 verifier passes, 2 security passes + +Method: host audit first (rustup already user-level, 1.99.0 auto-installed by `rustup show`, system deps present, no sudo); installs `--locked`; scripts moved to `scripts/`, `pnpm check:all` gate; contract `2026-10-13-rust-r0-native-verify.md` (11 criteria) dry-run by me before dispatch (3 oracles fixed: comment prose matched a code grep, per-package vitest totals, README phrasing); fresh verifier ×2; security-auditor on `bd9c7d1..6e2bbec` then on the fix commits; full gate run twice (`check-all.log`, `check-all-2.log`). +Result: verifier pass 1 ECARTS(2) = floor STUB hits on doc prose "(not implemented)" → reworded; pass 2 CONFORME 11/11, floor clean. Security pass 1 PASS + 1 MEDIUM (no advisory check has ever run: nightly job never executed) + 6 LOW (PATH prepend, `rm -rf "$out"` via variable, prctl comment overstating the kernel contract + i32 into variadic unsigned long, dormant CI triggers, native build.rs exposure, drift gate blind to untracked files) → fixed except the trigger question (owner's CI/CD step); pass 2 PASS + 1 MEDIUM (my ci.yml drift step failed open on a git error: `test -z "$(…)"` drops the exit status) + `--untracked-files=all` + stale comment → fixed (496f549), verified by execution + shellcheck, no third dispatch (3-line change). Numbers: native rust-check 32 s warm / 1 s incremental, cold workspace build 31.5 s, wasm 224 777 B (+64 B vs builder, path strings), 14 proofs, `check:all` 1 min 59 s then 1 min 39 s, 777 Node tests, 16 sandbox tests, allowlist covers the trace, worker read-only `run --check` OK. +Anomalies: the R0 note "no cargo on the host" was stale, rustup had been installed 2026-10-12 23:27 (rtk) → always re-audit the host at session start; `rustup show` has a side effect (auto-install) → acceptable here (requested install) but say so; a fix I wrote for one security finding introduced the next MEDIUM (fail-open test) → the EVAL-017 lesson again: CI one-liners need the same scrutiny as code, prefer assign-then-test; the harness clock jumped 01:16 → 09:43 mid-session (timestamps in logs are not durations). +Action: owner's final validation of the R0 correction; R1 not started; CI/CD decision separate (trigger mode, runner label, action pinning, advisories cadence). diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 89400a6f..a1813056 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -228,3 +228,11 @@ User: Step 7 closed; Step 8 = files foundation + Storage, analysis before implem 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. + +## 2026-10-13 (Rust R0 delivered) + +Owner go (BDR-045): chore/step-08-files-analysis finished into develop (Annex C), feature/rust-r0-foundation. Built R0 through the Docker builder only: workspace (core, wasm, worker), proofs (float_roundtrip finding, trap/fresh-instance behaviour, musl + libwebp 1.6.0, seccomp 7 syscalls derived by strace on the release binary, CSP 'wasm-unsafe-eval' proven in Chrome 156, 225 KB / 85 KB gzip module), packages/core-wasm (14 proofs), CI (rust job, worker test stage, advisories nightly, manual release-images), docs (RUST.md, DEPLOY digest deploy prepared, CLAUDE/WORKSPACE/TEST_STRATEGY/CHANGELOG). Gates: verifier ×3 (oracle gaps only, CONFORME in substance), security ×3 (1 HIGH + mediums fixed; my first fixes introduced 3 mediums, fixed; follow-ups documented). Root `pnpm check` 777 tests, live deployment untouched, frontend loads nothing. BDR-046, LRN-049, EVAL-017. Stop: owner validation of R0; R1 not started; release 0.2.0 pending. + +## 2026-10-13 (R0 correction: native toolchain) + +Owner brief: dev = Ubuntu native server, Docker for services/isolation/images, VPS separate, no CI active. Host audit: rustup 1.29.1 already user-level, `rustup show` auto-installed 1.99.0; added wasm32 target, wasm-bindgen-cli 0.2.129, cargo-deny 0.20.2 (`--locked`, 100 s, no sudo, no package missing). Scripts moved docker/ → scripts/ (`rust-check.sh`, `wasm-build.sh`, PATH guard `rust-env.sh`), root `rust:check`/`wasm:build` native, `:docker` variants, `pnpm check:all` single pre-merge gate (+ warn-only advisories, porcelain drift gate). Worker unit tests now in the native check; sandbox/seccomp stay Docker. SAFETY comments rewritten as invariants (no `[gated]`), stride checked_mul, prctl args as c_ulong. Workflows kept, marked prepared/never executed. Docs: RUST.md §1/§4/§5.8/§6, CLAUDE, README, DEPLOY, WORKSPACE, TEST_STRATEGY, CHANGELOG, review C.1. Gates: verifier ECARTS(2 prose) → CONFORME; security PASS ×2 (fixes landed). `check:all` green ×2. BDR-047, LRN-050, EVAL-018. 7 commits on feature/rust-r0-foundation, pushed. Stop: owner's final validation; R1 not started; no deploy, no release. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index ee3c8c58..8521f0bf 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -362,3 +362,24 @@ Apply: every future Supabase auth surface (Step 14 gating, invitations), any pgT 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. + +## LRN-049 | 2026-10-13 | R0 experimental findings: serde_json fast float path, wasm traps and the ESM cache, RLIMIT_CPU soft=hard, minimal rustup profile, traced seccomp set + +Facts proven on the real environment (docs/development/RUST.md §5), each one changed a design assumption of the review: +- `serde_json` default float parsing is a fast path one ULP off on some inputs (`1715.4285714285713` → `1715.428571428571`): enable `float_roundtrip` whenever bytes must match `JSON.stringify`; the formatter alone (`js_number`) is not enough. +- wasm32 = panic=abort: a panic and a shadow-stack overflow both surface as `WebAssembly.RuntimeError`; after a stack-overflow trap the next call fails in the allocator (deterministic), after a plain panic the instance still answers with a never-unwound stack pointer (silent) → never reuse an instance after any trap; the wasm-bindgen glue caches its instance in a module variable and `import()` of the same URL returns it → a fresh instance needs a new module record (cache-busting query) or a new Worker. +- `setrlimit(RLIMIT_CPU, soft, hard)` with soft == hard kills with SIGKILL (hard checked first), indistinguishable from a parent deadline kill → soft two seconds below hard gives SIGXCPU. +- Official `rust:` images install rustup's minimal profile: `rustup component add rustfmt clippy` in the image, else every container downloads them (rust-toolchain.toml lists the components). +- A single-threaded musl static decode (image/zune-jpeg/png/image-webp + libwebp encode) makes exactly 7 syscalls after start: read write mmap munmap mremap exit_group getrandom; mallocng used neither brk nor mprotect, no futex. Derive with strace after a stderr marker, compare in the build, keep an explicit abort-path set (rt_sigaction rt_sigprocmask getpid gettid tkill tgkill exit) proven by the RLIMIT_AS → SIGABRT test. +- Unoptimised debug decoders blow a 10 s CPU budget on 4096² inputs: `[profile.dev.package."*"] opt-level = 3`. +- cargo-deny 0.20: a versionless path dependency is a "wildcard" (`allow-wildcard-paths = true`) and a workspace-inherited path dependency triggers an `unresolved-workspace-dependency` bug (declare `path = "../core"` per crate). +- CSP: `'wasm-unsafe-eval'` is required for `WebAssembly.instantiateStreaming` under `script-src 'self'` and allows nothing else (inline scripts still blocked); proven with the production nginx image + headers in headless Chrome 156. +Apply: R1 (worker loop keeps the same child), R2 (browser loader: fresh-instance mechanism, float_roundtrip stays on, CSP line at activation), any future "it should work" assumption about a runtime → run it in the real environment first. + +## LRN-050 | 2026-10-13 | Native vs Docker Rust: rustup auto-install, non-interactive PATH, path strings in the wasm, worker unit tests native + +- `rustup show` inside a repo with `rust-toolchain.toml` auto-installs the channel (rustup 1.29, default profile → rust-docs too, ~1.5 GB per toolchain); `rustup target add --toolchain ` + two `cargo install --locked` ≈ 100 s with a warm registry. +- Agent / hook / editor shells are non-interactive: `~/.bashrc` returns early, `~/.cargo/bin` absent from PATH while the user's shell has it → scripts source a 5-line guard (`scripts/rust-env.sh`), never assume PATH. The harness refuses tool commands containing `export PATH=`: use absolute paths or a sourced file. +- Same rustc + lock → wasm differs by 64 B and by hash between build roots (`/w` vs `/home/...`): panic `Location` paths embedded; bit-identity needs `--remap-path-prefix` (unset at R0). Builder image = reference when bytes must match. +- Worker sandbox tests are `#![cfg(feature = "test-hooks")]`: plain `cargo test --workspace` compiles them empty → the 9 worker unit tests run natively for free (R0's `--exclude faunosteo-worker` was unneeded); seccomp derivation stays Docker/musl only (glibc syscalls differ). +- Contract oracles need a dry run before dispatch (EVAL-013/017 lesson, applied): a grep for `width * 4` matched my own SAFETY prose; `pnpm -r test:run` prints per-package totals, never one root line. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b09f3a57..1bb4ec65 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -135,7 +135,29 @@ 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 + - [x] R0.7 proofs recorded with numbers in RUST.md §5: panic=abort traps + stack-trap instance unusable + fresh instance via cache-busting import; serde_json `float_roundtrip` finding (byte parity on 4 real documents + number corpus, Zod readers); musl static + libwebp 1.6.0 (image 8.7 MB, read-only, caps dropped); seccomp allowlist derived by strace on the release binary = 7 syscalls + 7 abort path, 13/13 sandbox tests; CSP: refused with `script-src 'self'`, OK with `'wasm-unsafe-eval'` (Chrome 156, nginx 1.31, `docker/csp-proof/`); wasm 224,713 B raw / 85 KB gzip / ≈ 3 ms; runner cache NOT measurable here (pending on the forge, §5.7) + - [x] R0.8 CI: job `rust` (builder image, fmt/clippy/test/deny, types drift, wasm build), `check` builds the wasm then runs the Node pipeline, `docker` builds the worker test stage + runtime started read-only/cap-drop, nightly advisories, manual `release-images` hardened after the security audit (typed input via env, advisories gate, ephemeral buildx builder, env secrets + per-job DOCKER_CONFIG + logout, main/develop only, pinned checkout; no deploy) + - [x] R0.9 docs: RUST.md, DEPLOY.md (prepared digest deploy + CSP note, live procedure untouched), WORKSPACE.md, packages/README.md, CLAUDE.md (stack, map, commands, workflow), TEST_STRATEGY.md, CHANGELOG + - [ ] R0 follow-ups from the security audits (R1 unless stated): base images and the buildkit engine image by digest (Step 27); verification decode of the child's output in a second sandboxed child; R1 treats Signalled/Timeout/OutputOverflow as rejections (content never alerts) and logs the child's stderr escaped only; negative tests for tkill(self, SIGTERM) and tgkill; iCCP fixture with image data so the allocation budget is seen firing; WebP structure residuals (duplicate ALPH, ALPH + VP8L, VP8X flags); dedicated release runner label that never runs PR jobs (Step 27); `actions/*@v4` in ci.yml pinned by commit (Step 27); drop `--features proofs` from docker/wasm-build.sh at R2 + - [x] R0.10 gates: root `pnpm check` 777 tests green (existing suites untouched); verifier ×3 (CONFORME in substance, oracle fixes only); security ×3 (HIGH shell injection + 6 MEDIUM fixed; 3 MEDIUM introduced by the first fixes fixed; 2 MEDIUM of pass 3 fixed by the secret-less gates job); memory BDR-046, LRN-049, EVAL-017, journal. STOPPED for owner validation (2026-10-13); R1 not started + - [ ] R0 owner points: review the worker's SAFETY comments (rewritten 2026-10-13 as technical invariants, the `[gated]` approval-looking markers removed); decide the registry (forge Gitea registry recommended) and set REGISTRY/REGISTRY_USER/REGISTRY_TOKEN secrets before the first `release-images` run; first run on the forge records the runner numbers (RUST.md §5.7) and validates the workflow syntax (job-level env, GITHUB_ENV path) + - [ ] R0.11 native toolchain correction (owner brief 2026-10-13, delivered 2026-10-13, awaiting the owner's final validation: Ubuntu dev server native Rust, Docker for services/isolation/images, VPS separate, no CI active): + - [x] R0.11.1 host audit: rustup 1.29.1 already user-level (~/.cargo, ~/.rustup), 1.99.0 auto-installed from rust-toolchain.toml, gcc/libc6-dev/pkg-config/libssl-dev/strace present, no sudo, no package needed + - [x] R0.11.2 install (user-level, `--locked`, 100 s, registry cache warm): wasm32-unknown-unknown on 1.99.0, wasm-bindgen-cli 0.2.129, cargo-deny 0.20.2 + - [x] R0.11.3 scripts: `scripts/rust-check.sh` + `scripts/wasm-build.sh` (moved from docker/, PATH guard `scripts/rust-env.sh`), `scripts/check-all.sh` pre-merge gate; root `rust:check` / `wasm:build` native, `rust:check:docker` / `wasm:build:docker` through the builder, `check:all`; worker unit tests in the native check (sandbox tests stay feature-gated in Docker) + - [x] R0.11.4 worker: SAFETY comments rewritten as verifiable technical invariants (no `[gated]` approval marker), stride with checked arithmetic + - [x] R0.11.5 CI files kept, header states prepared / never executed (no runner, no secrets), script paths updated + - [x] R0.11.6 verification (native rust-check 32 s warm, cold workspace build 31.5 s; wasm 224 777 B native vs 224 713 B builder, path strings; 14 proofs; `pnpm check:all` 1 min 59 s green: 777 Node tests, 16 sandbox tests, allowlist covers the trace, worker read-only run --check): native versions; cargo fmt/clippy/test/build/deny; wasm native + core-wasm proofs; Docker builder, docker check, docker wasm, worker:test, worker:image run --check, app image; `pnpm check`; numbers compared with R0 (RUST.md §5) + - [x] R0.11.7 docs: RUST.md §1/§4/§6, CLAUDE.md, README verifying, DEPLOY.md, WORKSPACE.md, TEST_STRATEGY.md, CHANGELOG, review Annex C addendum + - [x] R0.11.8 gates: verifier ECARTS(2 doc prose) → CONFORME 11/11; security PASS ×2 (1 MEDIUM + 6 LOW then 1 MEDIUM + 2 LOW, fixed: advisories warn-only stage, fail-closed porcelain drift gate with --untracked-files=all, PATH guard append/absolute, literal rm, prctl c_ulong args); BDR-047, LRN-050, EVAL-018, journal + - [ ] R0.11 follow-ups for the CI/CD step (owner): ci.yml push/PR triggers stay live, so registering a runner starts PR builds at once (keep, or switch to workflow_dispatch until then); `actions/*@v4` mutable tags (Step 27); advisories cadence while no nightly runs (`cargo deny check advisories` is warn-only in check:all); `--remap-path-prefix` if native and builder wasm must match byte for byte - [ ] 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/.claude/tasks/contracts/2026-10-13-rust-r0-native-verify.md b/.claude/tasks/contracts/2026-10-13-rust-r0-native-verify.md new file mode 100644 index 00000000..cb5f542a --- /dev/null +++ b/.claude/tasks/contracts/2026-10-13-rust-r0-native-verify.md @@ -0,0 +1,47 @@ +# CONTRACT — R0 correction: native Rust toolchain on the Ubuntu development server (for the fresh verifier) +- date: 2026-10-13 | flow: ad-hoc correction (owner brief 2026-10-13, after R0 delivery) | branch: feature/rust-r0-foundation (R0 closed at bd9c7d1; this delta on top) +- status: closed 2026-10-13 — pass 2 CONFORME 11/11, security pass 2 PASS; post-pass fix 496f549 (fail-closed drift step) verified by execution (oracles 6, 9, 10 amended before dispatch after a dry run by the orchestrator; pass 1: verifier ECARTS(2) = two floor STUB hits on doc prose "(not implemented)" → reworded; security PASS with 1 MEDIUM + 6 LOW → fixes: warn-only advisories stage and porcelain drift gate in check-all.sh and ci.yml, PATH guard appends an absolute dir only, literal rm path, prctl unused arguments as unsigned long with an honest comment; evidence of pass 2 = check-all-2.log) +- spec: owner brief (REQUEST below), docs/development/RUST.md §1 and §4 (what the correction builds), docs/development/RUST_ARCHITECTURE_REVIEW.md Annex C.1 +- evidence logs (runs made by the orchestrator on this host, readable): /tmp/claude-1000/-home-bchanot-Documents-faunosteo/71caaac9-9523-489e-bc17-e28e1d4fd532/scratchpad/{toolchain-install.log,warm-build.log,native-check.log,native-check-2.log,docker-alt.log,check-all.log,check-all-2.log} +- the verifier never installs, uninstalls or updates anything on the host; cargo commands below run the native toolchain already installed (rustup in ~/.cargo); `~/.cargo/bin` may be absent from a non-interactive PATH: prefix commands with `PATH="$HOME/.cargo/bin:$PATH"` when `cargo` is not found. Docker commands are not re-run (read check-all.log). + +## REQUEST (owner brief 2026-10-13, condensed — IMMUTABLE) +Development machine = self-hosted Ubuntu server (native, not WSL, not the VPS) with Docker rootless. Install a native user-level Rust toolchain (rustup, rustc, cargo, rustfmt, clippy, wasm32-unknown-unknown, wasm/bindings tools) at the pinned 1.99.0, no sudo, no global package, no sensitive system change. Daily Rust development = native cargo commands; wasm build native too; pinned toolchain + existing Cargo.lock. Adapt the monorepo scripts so the main path is native; keep the Docker commands as the reproducible alternative without imposing them; short compile times, reuse of Cargo artefacts. Docker stays for Supabase, the worker's execution, integration tests, untrusted-file isolation, seccomp/Linux protections, deployment images, production-like tests; the R0 builder is kept; the worker's isolation is not degraded. No CI/CD is operational: workflow files may stay, never claimed as run, no secrets/runner/auto-publication, no mandatory dependency on a pipeline; one simple command runs every technical check before a merge, reusable by a future Gitea runner. Verification: versions, native tests, lint, core build, wasm build, TS/WASM compatibility tests, Docker builds of R0 still work, monorepo tests, comparison with the R0 proofs; seccomp and container protections stay in Docker; no regression. Re-examine the worker's unsafe blocks: precise, verifiable technical justification, SAFETY comments never presented as the owner's approval; sandbox protections and tests kept. Update RUST.md and the associated docs (Ubuntu native dev, Docker services/isolated tests, separate VPS). No out-of-scope change; no R1, no deploy, no release 0.2.0. + +## ACCEPTANCE CRITERIA +1. Native toolchain pinned and complete, user-level only. + CHECK: cd /home/bchanot/Documents/faunosteo && "$HOME/.cargo/bin/rustup" show active-toolchain | cut -d' ' -f1; "$HOME/.cargo/bin/rustup" component list --installed --toolchain 1.99.0 | grep -c "rustfmt\|clippy"; "$HOME/.cargo/bin/rustup" target list --installed --toolchain 1.99.0 | grep -c "^wasm32-unknown-unknown$"; "$HOME/.cargo/bin/wasm-bindgen" --version; "$HOME/.cargo/bin/cargo-deny" --version; dpkg-query -W rustc cargo 2>&1 | grep -c "no packages found" + EXPECT: 1.99.0-x86_64-unknown-linux-gnu ; 2 ; 1 ; wasm-bindgen 0.2.129 ; cargo-deny 0.20.2 ; 2 +2. Scripts: the two Rust scripts live under scripts/ (not docker/), source the PATH guard, and the root scripts make native the primary path with `:docker` alternatives and a single pre-merge gate. + CHECK: ls scripts | tr '\n' ' '; ls docker | grep -c "rust-check.sh\|wasm-build.sh"; grep -c "^\. scripts/rust-env.sh" scripts/rust-check.sh scripts/wasm-build.sh; grep -c '"rust:check": "bash scripts/rust-check.sh"' package.json; grep -c '"rust:check:docker": "bash docker/rust-run.sh bash scripts/rust-check.sh"' package.json; grep -c '"wasm:build": "bash scripts/wasm-build.sh"' package.json; grep -c '"wasm:build:docker": "bash docker/rust-run.sh bash scripts/wasm-build.sh"' package.json; grep -c '"check:all": "bash scripts/check-all.sh"' package.json + EXPECT: check-all.sh rust-check.sh rust-env.sh wasm-build.sh ; 0 ; scripts/rust-check.sh:1 and scripts/wasm-build.sh:1 ; 1 ; 1 ; 1 ; 1 ; 1 +3. The native check covers the worker's unit tests; the sandbox tests stay feature-gated and Docker-only; the pre-merge gate runs them through the worker image. + CHECK: grep -c "cargo test --workspace --locked" scripts/rust-check.sh; grep -c "exclude faunosteo-worker" scripts/rust-check.sh; grep -c "git status --porcelain -- packages/core-wasm/types" scripts/check-all.sh .gitea/workflows/ci.yml | tr '\n' ' '; grep -c "cargo deny check advisories" scripts/check-all.sh; grep -c '#!\[cfg(all(feature = "test-hooks", target_os = "linux"))\]' crates/worker/tests/sandbox.rs; grep -c "pnpm worker:test" scripts/check-all.sh; grep -c "pnpm worker:image" scripts/check-all.sh; grep -c "read-only --cap-drop ALL" scripts/check-all.sh + EXPECT: 1 ; 0 ; both files at :1 (any order) ; 1 ; 1 ; 1 ; 1 ; 1 +4. The Docker path is intact: rust-run.sh and the builder Dockerfile changed in comments only; the worker Dockerfile, the application Dockerfile, compose and nginx are untouched. + CHECK: git diff HEAD -- docker/rust-run.sh | grep -E "^[-+]" | grep -vE "^(\+\+\+|---)" | grep -vc "^[-+]#"; git diff HEAD -- docker/rust-builder.Dockerfile | grep -E "^[-+]" | grep -vE "^(\+\+\+|---)" | grep -vc "^[-+]#"; git diff --stat HEAD -- crates/worker/Dockerfile Dockerfile docker-compose.yml docker/nginx.conf docker/entrypoint.sh | wc -l + EXPECT: 0 ; 0 ; 0 +5. Workflow files kept (three), each marked prepared / never executed, script paths updated, nothing added that configures a runner, a secret or an automatic publication. + CHECK: ls .gitea/workflows | wc -l; grep -c "PREPARED, NEVER EXECUTED" .gitea/workflows/ci.yml; grep -c "prepared, never executed" .gitea/workflows/rust-advisories.yml .gitea/workflows/release-images.yml; grep -rc "docker/rust-check.sh\|docker/wasm-build.sh" .gitea/workflows | grep -vc ":0$"; git diff HEAD -- .gitea | grep -E "^\+" | grep -vE "^\+\+\+" | grep -vc "^\+ *#\|^\+ *run: bash docker/rust-run.sh bash scripts/\|^\+ *run: docker build -f docker/rust-builder.Dockerfile" + EXPECT: 3 ; 1 ; rust-advisories.yml:1 and release-images.yml:1 ; 0 ; 0 +6. Worker unsafe blocks: every `unsafe {` in crates/worker/src is preceded by a `// SAFETY:` comment stating invariants the surrounding code establishes (read them: encode_webp checks `rgba.len() == w*h*4` and computes the stride with checked arithmetic; from_raw_parts after `size != 0 && !output.is_null()`; WebPFree once; prctl integer arguments with the return code checked; the two negative hooks compiled with `test-hooks` only); no `[gated …]` approval marker remains; no unsafe outside the worker. + CHECK: grep -c "gated" crates/worker/src/decode.rs crates/worker/src/sandbox.rs; grep -c "unsafe {" crates/worker/src/decode.rs; grep -c "// SAFETY:" crates/worker/src/decode.rs; grep -c "unsafe {" crates/worker/src/sandbox.rs; grep -c "// SAFETY:" crates/worker/src/sandbox.rs; grep -rc "unsafe {" crates/core/src crates/wasm/src | grep -vc ":0$"; grep -c "width.checked_mul(4)" crates/worker/src/decode.rs; grep -c "c_int::try_from(width \* 4)" crates/worker/src/decode.rs; grep -c 'unsafe_code = "forbid"' Cargo.toml; grep -c 'unsafe_code = "deny"' crates/worker/Cargo.toml + EXPECT: decode.rs:0 and sandbox.rs:0 ; 6 ; 6 ; 2 ; 2 ; 0 ; 1 ; 0 ; 1 ; 1 +7. The native Rust gate is green and the committed ts-rs types do not drift. + CHECK: cd /home/bchanot/Documents/faunosteo && PATH="$HOME/.cargo/bin:$PATH" bash scripts/rust-check.sh > /tmp/claude-1000/verify-rust-check.log 2>&1; echo rc=$?; grep -E "^test result" /tmp/claude-1000/verify-rust-check.log | grep -c "ok\."; grep -E "^test result" /tmp/claude-1000/verify-rust-check.log | grep -c " 10 passed\| 9 passed\| 14 passed"; grep -c "bans ok, licenses ok, sources ok" /tmp/claude-1000/verify-rust-check.log; git diff --exit-code -- packages/core-wasm/types > /dev/null && echo SAME + EXPECT: rc=0 ; 12 ; 3 ; 1 ; SAME +8. The native wasm build and the TypeScript/WASM proofs pass on the module it produces; the size stays within 1 KB of the R0 builder figure (224 713 B raw). + CHECK: cd /home/bchanot/Documents/faunosteo && PATH="$HOME/.cargo/bin:$PATH" bash scripts/wasm-build.sh 2>&1 | grep "faunosteo_wasm_bg.wasm:"; corepack pnpm --filter @faunosteo/core-wasm test:run 2>&1 | grep -E "Tests " + EXPECT: a line "faunosteo_wasm_bg.wasm: NNNNNN bytes raw, …" with 223713 <= NNNNNN <= 225713 ; "Tests 14 passed (14)" +9. The single pre-merge gate passed end to end on this host (native stages, Node pipeline, application image, worker sandbox tests + seccomp derivation, worker runtime read-only), read from the evidence log. + CHECK: L=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/71caaac9-9523-489e-bc17-e28e1d4fd532/scratchpad/check-all-2.log; grep -c "^== all checks passed" "$L"; grep -c "DONE rc=0" "$L"; grep -c "== allowlist covers the trace" "$L"; grep -E "Tests [0-9]+ passed" "$L"; grep -c "test result: ok. 16 passed" "$L" + EXPECT: 1 ; 1 ; 1 ; six per-package lines (domain 194, core-wasm 14, supabase 24, anatomy 130, pdf 137, app 278 = 777, every one "passed") ; 1 +10. Documentation reflects the three environments and the CI status; no doc still claims a Docker-only or CI-run toolchain. + CHECK: grep -c "native on the development machine" docs/development/RUST.md; grep -c "prepared, no CI active" docs/development/RUST.md; grep -c "### 5.8 Native toolchain run" docs/development/RUST.md; grep -c "C.1 Addendum 2026-10-13" docs/development/RUST_ARCHITECTURE_REVIEW.md; for f in CLAUDE.md README.md CHANGELOG.md docs/development/RUST.md docs/development/TEST_STRATEGY.md; do grep -c "check:all" $f; done | tr '\n' ' '; grep -c "no toolchain on the host\|never on the host\|all through the builder image" CLAUDE.md docs/development/RUST.md docs/development/WORKSPACE.md | grep -vc ":0$"; grep -c "(not implemented" docs/development/RUST.md docs/development/RUST_ARCHITECTURE_REVIEW.md | grep -vc ":0$"; grep -c "No CI/CD\|no CI active\|No CI runs" DEPLOY.md CLAUDE.md README.md | grep -vc ":0$" + EXPECT: 1 ; 1 ; 1 ; 1 ; five numbers all >= 1 ; 0 ; 0 ; 3 +11. Scope held: no change under apps/, packages/, supabase/, no new dependency, Cargo.lock and pnpm-lock.yaml untouched. + CHECK: git diff --stat HEAD -- apps packages supabase Cargo.lock pnpm-lock.yaml | wc -l; git status --short | grep -c "^??" ; git status --short | grep "^??" | grep -vc "^?? scripts/\|^?? .claude/tasks/contracts/" + EXPECT: 0 ; >= 0 ; 0 + +## OUT OF SCOPE (do not report as gaps) +R1 (job loop), any deployment, release 0.2.0, runner / registry / secrets on the forge, `--remap-path-prefix` for bit-identical native vs Docker modules (documented in RUST.md §5.8), prettier conformance of Markdown files already non-conformant at HEAD, the `rust-docs` component installed by rustup's default profile. diff --git a/.claude/tasks/contracts/2026-10-13-rust-r0-verify.md b/.claude/tasks/contracts/2026-10-13-rust-r0-verify.md new file mode 100644 index 00000000..4e4a3283 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-13-rust-r0-verify.md @@ -0,0 +1,58 @@ +# CONTRACT — Rust R0 foundation (whole phase, for the fresh verifier) +- date: 2026-10-13 | flow: ad-hoc phase (owner go 2026-10-12, BDR-045) | branch: feature/rust-r0-foundation (base develop = 5fec065) +- status: active (amended 2026-10-13 after verifier pass 1: criteria 10 and 14 oracles counted comment lines; pass 2 CONFORME 16/16, criterion 16 oracle excludes the contract file itself; pass 3 after the security fixes: criteria 10 and 11 oracles updated to the gated SAFETY form and the second refusal arm; no code change) +- spec: docs/development/RUST_ARCHITECTURE_REVIEW.md (Part III, Annex B, Annex C), docs/development/RUST.md (what was built and proven) +- evidence logs (runs made by the orchestrator on this host, readable): /tmp/claude-1000/-home-bchanot-Documents-faunosteo/2fbc125b-9811-4458-8ebc-489c2f9255be/scratchpad/{pnpm-check.log,worker-test-build-5.log,worker-image-build-2.log,builder-build-2.log} + +## REQUEST (owner brief 2026-10-12, condensed — IMMUTABLE) +Implement R0 per Annex B: Cargo workspace with crates core, wasm, worker; pinned Rust and dependencies; reproducible Docker builder (no Rust on the VPS); native and WebAssembly compilation; working TypeScript bindings; JSON contracts compatible with the current data; first wasm size and performance measurements; applicable security and isolation tests; CI integration; development and deployment documentation. The seven proofs run in the real environment where possible (serialisation, wasm panics, musl, seccomp verified experimentally; a proof that cannot be obtained is reported, not assumed). Compatibility: the React app, Report v3, PDF v2/v3, Supabase, the interfaces and the existing tests stay unchanged; the frontend does not load the module. No migration of anatomy, PDF or business validations (R2–R5); no avatar business processing (R1). Everything dockerised; production images built in CI and pulled by the VPS; live deployment unchanged; no tag or merge into main. + +## ACCEPTANCE CRITERIA +1. Workspace with exactly three crates, toolchain pinned identically in the three places. + CHECK: grep -c '"crates/core", "crates/wasm", "crates/worker"' Cargo.toml; grep -c 'channel = "1.99.0"' rust-toolchain.toml; grep -c "FROM rust:1.99.0-bookworm" docker/rust-builder.Dockerfile; grep -c "FROM rust:1.99.0-alpine3.24" crates/worker/Dockerfile; ls crates + EXPECT: 1 ; 1 ; 1 ; 1 ; core wasm worker +2. wasm-bindgen crate and CLI locked to one version, refused up front on mismatch. + CHECK: grep -c 'wasm-bindgen = "=0.2.129"' Cargo.toml; grep -c "WASM_BINDGEN_VERSION=0.2.129" docker/rust-builder.Dockerfile; grep -c 'lock_version" != "$cli_version"' docker/wasm-build.sh + EXPECT: 1 ; 1 ; 1 +3. The core takes ids, time and bytes as inputs: no I/O, clock or env in crates/core/src, lint-enforced. + CHECK: grep -rn "std::fs\|std::env\|std::time\|SystemTime\|Instant::now" crates/core/src | wc -l; grep -c "disallowed_methods = \"deny\"" Cargo.toml; grep -c "std::fs::read\|std::env::var\|SystemTime::now" clippy.toml; grep -c "^serde\|^serde_json\|^ts-rs" crates/core/Cargo.toml + EXPECT: 0 ; 1 ; >= 3 ; 3 +4. JSON contract: preserve_order and float_roundtrip enabled; the JavaScript number formatter and the pretty formatter exist with their unit tests. + CHECK: grep -c '"preserve_order", "float_roundtrip"' Cargo.toml; grep -c "pub fn js_number\|pub struct JsPrettyFormatter\|pub fn to_js_pretty\|pub fn pretty_js_round_trip" crates/core/src/json.rs; bash docker/rust-run.sh cargo test -p faunosteo-core --locked 2>&1 | grep -E "^test result" | head -2 + EXPECT: 1 ; 4 ; two lines "ok. 10 passed" and "ok. 2 passed" +5. Report contract types mirror the Zod rules: optional fields skipped when None, nullable field plain Option, Unresolved = literal true; committed ts-rs types equal a fresh export. + CHECK: grep -c 'skip_serializing_if = "Option::is_none"' crates/core/src/domain/report.rs; grep -c "pub version_id: Option" crates/core/src/domain/report.rs; grep -c 'ts(optional, type = "true")' crates/core/src/domain/report.rs; bash docker/rust-run.sh cargo test -p faunosteo-core --features ts --locked 2>&1 | grep -c "test result: ok"; git diff --exit-code -- packages/core-wasm/types && echo SAME + EXPECT: 5 ; 1 ; 1 ; >= 1 ; SAME +6. Browser facade exposes exactly core_version, call, panic_for_test, recurse_for_test; the loader never imports pkg statically; every proof file skips when pkg is absent. + CHECK: grep -c "^pub fn core_version\|^pub fn call\|^pub fn panic_for_test\|^pub fn recurse_for_test" crates/wasm/src/lib.rs; grep -c "^import .* from '../pkg" packages/core-wasm/src/index.ts; grep -l "describe.skipIf(!coreBuilt)" packages/core-wasm/tests/*.test.ts | wc -l + EXPECT: 4 ; 0 ; 4 +7. The wasm proofs pass on the built module (byte equality with JSON.stringify on the four documents, number corpus, Zod readers, panic and stack traps, fresh-instance recovery, size budget). + CHECK: ls packages/core-wasm/pkg/faunosteo_wasm_bg.wasm; corepack pnpm --filter @faunosteo/core-wasm test:run 2>&1 | grep -E "Tests |Test Files"; grep -c "float_roundtrip\|memory access out of bounds\|wasm-unsafe-eval" docs/development/RUST.md + EXPECT: file exists (built by the orchestrator; if absent run `pnpm wasm:build` first) ; "4 passed" and "14 passed" ; >= 3 +8. Worker process model: plain main without an async runtime; decode checks the environment, then the thread count, then rlimits, then seccomp, before reading input. + CHECK: grep -c "tokio" crates/worker/Cargo.toml; grep -n "vars_os().next().is_some()\|sandbox::apply(\|read_to_end(&mut input)" crates/worker/src/decode.rs | head -3; grep -n "ensure_single_thread()?;\|set_rlimits(limits)?;\|install_seccomp()?;" crates/worker/src/sandbox.rs | head -3 + EXPECT: 0 ; the three lines appear in that order (env check line < sandbox line < read line) ; the three calls appear in that order +9. seccomp allowlist is the traced set plus the abort path, denies every file and process syscall, and was derived and proven on the musl binary. + CHECK: sed -n '/^pub const ALLOWED_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs | grep -c '("'; sed -n '/^pub const ABORT_PATH_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs | grep -c '("'; grep -c "open\|execve\|clone\|socket" <(sed -n '/^pub const ALLOWED_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs); grep -E "test result: ok. 16 passed|allowlist covers the trace" /tmp/claude-1000/-home-bchanot-Documents-faunosteo/2fbc125b-9811-4458-8ebc-489c2f9255be/scratchpad/worker-test-build-11.log | sed -E 's/^#[0-9]+ [0-9.]+ //' | sort -u + EXPECT: 7 ; 7 ; 0 ; both lines present +10. The keyed parent never decodes: spawn.rs and webp_check.rs use no image decoder; output capped at 512 KiB; the RIFF check allowlists four chunk types and refuses the rest. + CHECK: grep -c "image::" crates/worker/src/spawn.rs crates/worker/src/webp_check.rs; grep -c "MAX_OUTPUT_BYTES: usize = 512 \* 1024" crates/worker/src/limits.rs; grep -c 'b"VP8X", b"VP8 ", b"VP8L", b"ALPH"' crates/worker/src/webp_check.rs; grep -c "return Err(WebpIssue::ForbiddenChunk(fourcc))" crates/worker/src/webp_check.rs + EXPECT: 0 for both files ; 1 ; 1 ; 2 (the allowlist gate and the defensive arm of the structure match, since a8b644a) +11. libwebp confined to the child and its version controlled: FFI only in decode.rs with SAFETY comments, minimum 1.6.0 checked by a test and by `run --check`. + CHECK: grep -l "libwebp_sys::" crates/worker/src/*.rs; grep -c "// SAFETY" crates/worker/src/decode.rs; grep -c "MIN_LIBWEBP_VERSION: (u8, u8, u8) = (1, 6, 0)" crates/worker/src/limits.rs; grep -c "the_linked_libwebp_is_recent_enough" crates/worker/tests/sandbox.rs + EXPECT: crates/worker/src/decode.rs only ; >= 4 ; 1 ; 1 +12. Test hooks never ship: release build without features; the runtime image is distroless static, non-root, with `run --check` as its command. + CHECK: grep -n "cargo build -p faunosteo-worker --release --locked" crates/worker/Dockerfile | grep -c "features"; grep -c "FROM gcr.io/distroless/static-debian12:nonroot" crates/worker/Dockerfile; grep -c "^USER nonroot" crates/worker/Dockerfile; grep -c 'CMD \["run", "--check"\]' crates/worker/Dockerfile; tail -1 /tmp/claude-1000/-home-bchanot-Documents-faunosteo/2fbc125b-9811-4458-8ebc-489c2f9255be/scratchpad/worker-image-build-6.log + EXPECT: 0 ; 1 ; 1 ; 1 ; exit=0 +13. Frontend, live deployment and database untouched; the existing suites still pass. + CHECK: git diff --stat 5fec065..HEAD -- apps/app Dockerfile docker-compose.yml docker/nginx.conf docker/entrypoint.sh supabase packages/domain packages/anatomy packages/pdf packages/supabase | wc -l; tail -1 /tmp/claude-1000/-home-bchanot-Documents-faunosteo/2fbc125b-9811-4458-8ebc-489c2f9255be/scratchpad/pnpm-check.log; grep -E "apps/app test:run:\s+Tests|packages/pdf test:run:\s+Tests|packages/anatomy test:run:\s+Tests" /tmp/claude-1000/-home-bchanot-Documents-faunosteo/2fbc125b-9811-4458-8ebc-489c2f9255be/scratchpad/pnpm-check.log + EXPECT: 0 ; exit=0 ; 278, 137, 130 passed +14. CI: rust job before check through the builder image with the types drift check; docker job builds the worker test stage and starts the runtime image read-only with every capability dropped; advisories nightly; release-images manual only and deploys nothing. + CHECK: grep -c "needs: rust" .gitea/workflows/ci.yml; grep -c "docker/rust-check.sh\|git diff --exit-code -- packages/core-wasm/types" .gitea/workflows/ci.yml; grep -c -- "--target test\|--read-only --cap-drop ALL" .gitea/workflows/ci.yml; grep -v "^#" .gitea/workflows/release-images.yml | grep -c "^ workflow_dispatch:"; grep -v "^#" .gitea/workflows/release-images.yml | grep -cE "^\s*(push|pull_request|schedule):|ssh |scp |compose (up|pull)"; grep -c "cron:" .gitea/workflows/rust-advisories.yml + EXPECT: 1 ; 2 ; 2 ; 1 ; 0 ; 1 +15. Docs: RUST.md carries the seven proofs with numbers and the hypothetical list; DEPLOY.md carries the prepared digest procedure and the CSP note while the live procedure stays; CLAUDE.md, WORKSPACE.md, TEST_STRATEGY.md, packages/README.md, CHANGELOG updated. + CHECK: grep -c "^### 5\.[1-7]" docs/development/RUST.md; grep -c "^## 7. What stays hypothetical" docs/development/RUST.md; grep -c "^## Image deploy by digest (prepared at R0, not yet applied)" DEPLOY.md; grep -c "docker compose up --build -d" DEPLOY.md; grep -c "wasm-unsafe-eval" DEPLOY.md; grep -c "pnpm rust:check" CLAUDE.md; grep -c "crates/worker" docs/development/WORKSPACE.md; grep -c "Worker sandbox" docs/development/TEST_STRATEGY.md; grep -c "core-wasm" packages/README.md; grep -c "Rust foundation, plan R0" CHANGELOG.md + EXPECT: 7 ; 1 ; 1 ; >= 2 (live procedure kept) ; >= 2 ; >= 1 ; >= 1 ; 1 ; >= 1 ; 1 +16. No secret and no credential in the new files; the worker's env check and the CI secrets usage are the only places naming keys. + CHECK: git diff 5fec065..HEAD -- . ':!.claude/tasks/contracts' | grep -E "^\+" | grep -Ei "eyJ[a-zA-Z0-9_-]{20,}|sk_live|service_role_key *= *\"[^\"]+\"|password *= *\"" | wc -l; grep -c "secrets.REGISTRY_TOKEN" .gitea/workflows/release-images.yml + EXPECT: 0 ; 1 diff --git a/.dockerignore b/.dockerignore index 9538a6c6..c13f94eb 100644 --- a/.dockerignore +++ b/.dockerignore @@ -18,3 +18,5 @@ graphify-out/ .gitea/ docs/ logos/ +target/ +packages/core-wasm/pkg/ diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 2da5724b..b349aeb5 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -1,6 +1,17 @@ -# Gitea Actions (same syntax as GitHub Actions). Runs on the self-hosted forge -# runner; no external provider. The check job covers the SQL layer through the -# PGlite harness (no Docker); the supabase job replays it on the real stack. +# Gitea Actions (same syntax as GitHub Actions), written for a self-hosted forge +# runner; no external provider. +# +# STATUS 2026-10-13: PREPARED, NEVER EXECUTED. No runner, secret or registry is +# configured on the forge; the CI/CD decision is a separate step. Until then the +# same checks run on the development machine with `pnpm check:all` +# (scripts/check-all.sh), which a future runner can call as is. +# +# The check job covers the SQL layer through the PGlite harness (no Docker); the +# supabase job replays it on the real stack. Rust (plan R0, docs/development/RUST.md): +# in this file every cargo command runs inside the reference builder image built from +# docker/rust-builder.Dockerfile (the native toolchain of the development machine runs +# the same scripts), so a runner and a developer machine use the same compiler and the +# production VPS never needs Rust. name: ci on: @@ -9,8 +20,24 @@ on: pull_request: jobs: + rust: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Reference Rust builder image (runner needs a Docker daemon) + run: docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker + - name: fmt, clippy, tests, ts-rs export, cargo-deny (licenses, bans, sources) + run: bash docker/rust-run.sh bash scripts/rust-check.sh + - name: Committed TypeScript types match the Rust contracts (no modified or new file) + run: | + drift="$(git status --porcelain --untracked-files=all -- packages/core-wasm/types)" + if [ -n "$drift" ]; then echo "$drift"; exit 1; fi + - name: Browser module builds (size printed; the budget is asserted by the vitest proofs) + run: bash docker/rust-run.sh bash scripts/wasm-build.sh + check: runs-on: ubuntu-latest + needs: rust steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 @@ -19,6 +46,8 @@ jobs: - name: Activate pnpm (version from package.json "packageManager") run: corepack enable && corepack prepare --activate - run: pnpm install --frozen-lockfile + - name: Browser module for the core-wasm proofs (same builder image as the rust job) + run: docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker && bash docker/rust-run.sh bash scripts/wasm-build.sh - run: pnpm typecheck - run: pnpm test:run - run: pnpm lint @@ -29,8 +58,14 @@ jobs: needs: check steps: - uses: actions/checkout@v4 - - name: Docker image builds (runner needs a Docker daemon) + - name: Application image builds (runner needs a Docker daemon) run: docker build -t faunosteo:ci . + - name: Worker sandbox tests and seccomp derivation on the musl binary that ships + run: docker build -f crates/worker/Dockerfile --target test -t faunosteo_worker:test . + - name: Worker runtime image builds and starts (configuration check, no job loop before R1) + run: | + docker build -f crates/worker/Dockerfile -t faunosteo_worker:ci . + docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges:true faunosteo_worker:ci run --check supabase: runs-on: ubuntu-latest diff --git a/.gitea/workflows/release-images.yml b/.gitea/workflows/release-images.yml new file mode 100644 index 00000000..2c022198 --- /dev/null +++ b/.gitea/workflows/release-images.yml @@ -0,0 +1,128 @@ +# Production images, built in CI and identified by digest (D-R13, owner amendment of +# 2026-10-12): the VPS pulls them and never compiles. Manual only (workflow_dispatch), never +# on push: no publication or promotion of a production image without an explicit run and +# a validation. Nothing here deploys; DEPLOY.md "Image deploy by digest (prepared at R0, not +# yet applied)" is the runbook. +# +# Hardening (security audits of R0): the dispatch input is a typed choice re-validated in +# the shell through an environment variable (never interpolated into a script); the +# advisory gates (RustSec, npm) run in a job that holds no secret, and the image job runs no +# third-party code before its login (no npm install, only the pinned checkout); the registry +# token reaches the login step only, through env, into a per-job DOCKER_CONFIG under +# RUNNER_TEMP created fresh before the login and removed by a literal path; the images are +# built by a named ephemeral buildx builder (`--builder`, so a missing builder fails instead +# of falling back to the daemon's shared BuildKit and its cache mounts). The +# `if: github.ref` line keeps honest runs on main or develop: it is not a security boundary +# (whoever can push a branch can dispatch a copy of this file), push access and the token's +# scope are. The real isolation from pull-request jobs is a dedicated release runner label +# that never runs them (Step 27 operations). Known mutable references, to pin at Step 27: +# the buildkit engine image of the builder, the base images of the Dockerfiles. +# +# STATUS 2026-10-13: prepared, never executed. No runner, no registry and none of the +# secrets below exist on the forge yet; configuring them is the CI/CD step, not R0. +# +# Secrets expected on the forge: REGISTRY (host, e.g. the Gitea container registry of this +# forge), REGISTRY_USER, REGISTRY_TOKEN (write:package scope). Images are pushed as +# //faunosteo_app: and faunosteo_worker:; the digests are +# printed in the job summary and are what the VPS pins. +name: release-images + +on: + workflow_dispatch: + inputs: + sheet_bundle: + description: 'SHEET_BUNDLE for the app image (none = production default, draft = preview)' + required: true + type: choice + options: + - none + - draft + default: none + +concurrency: + group: release-images-${{ github.sha }} + cancel-in-progress: false + +jobs: + # No secret here: this job runs third-party code (pnpm install for the audit, the + # builder image) and must never see the registry token. + gates: + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' + runs-on: ubuntu-latest + env: + SHEET_BUNDLE: ${{ inputs.sheet_bundle }} + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: Validate the dispatch input (the shell trusts the env value only after this) + run: | + case "$SHEET_BUNDLE" in + none|draft) ;; + *) echo "refused SHEET_BUNDLE value" >&2; exit 1 ;; + esac + - name: RustSec advisories gate (release only; CI runs it nightly) + run: | + docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker + bash docker/rust-run.sh cargo deny check advisories + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + - name: npm advisories gate for the application image (production dependencies) + run: | + corepack enable && corepack prepare --activate + pnpm install --frozen-lockfile + pnpm audit --prod --audit-level=high + + images: + needs: gates + runs-on: ubuntu-latest + env: + SHEET_BUNDLE: ${{ inputs.sheet_bundle }} + REGISTRY: ${{ secrets.REGISTRY }} + NAMESPACE: ${{ github.repository_owner }} + GIT_SHA: ${{ github.sha }} + BUILDER: faunosteo_release_${{ github.run_id }} + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: Re-validate the dispatch input in this job + run: | + case "$SHEET_BUNDLE" in + none|draft) ;; + *) echo "refused SHEET_BUNDLE value" >&2; exit 1 ;; + esac + - name: Fresh per-job Docker config (fails if the directory already exists) + run: | + mkdir -m 700 "$RUNNER_TEMP/faunosteo-release-docker" + echo "DOCKER_CONFIG=$RUNNER_TEMP/faunosteo-release-docker" >> "$GITHUB_ENV" + - name: Ephemeral builder with its own cache (named; every build names it explicitly) + run: docker buildx create --name "$BUILDER" --driver docker-container + - name: Registry login (token in this step's env only, never on the command line) + env: + REGISTRY_USER: ${{ secrets.REGISTRY_USER }} + REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }} + run: printf '%s' "$REGISTRY_TOKEN" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin + - name: Build and push the application image + run: | + image="$REGISTRY/$NAMESPACE/faunosteo_app:$GIT_SHA" + docker buildx build --builder "$BUILDER" --push --provenance=false \ + --metadata-file "$RUNNER_TEMP/app-metadata.json" \ + --build-arg "SHEET_BUNDLE=$SHEET_BUNDLE" -t "$image" . + digest="$(sed -n 's/.*"containerimage.digest": *"\([^"]*\)".*/\1/p' "$RUNNER_TEMP/app-metadata.json")" + [ -n "$digest" ] || { echo "no digest in the build metadata" >&2; exit 1; } + echo "app: faunosteo_app:$GIT_SHA@$digest" >> "$GITHUB_STEP_SUMMARY" + - name: Build and push the worker image + run: | + image="$REGISTRY/$NAMESPACE/faunosteo_worker:$GIT_SHA" + docker buildx build --builder "$BUILDER" --push --provenance=false \ + --metadata-file "$RUNNER_TEMP/worker-metadata.json" \ + -f crates/worker/Dockerfile -t "$image" . + digest="$(sed -n 's/.*"containerimage.digest": *"\([^"]*\)".*/\1/p' "$RUNNER_TEMP/worker-metadata.json")" + [ -n "$digest" ] || { echo "no digest in the build metadata" >&2; exit 1; } + echo "worker: faunosteo_worker:$GIT_SHA@$digest" >> "$GITHUB_STEP_SUMMARY" + - name: Logout, remove the builder and the per-job Docker config (literal path) + if: always() + run: | + rc=0 + docker logout "$REGISTRY" || true + docker buildx rm "$BUILDER" || rc=$? + rm -rf -- "${RUNNER_TEMP:?}/faunosteo-release-docker" + exit "$rc" diff --git a/.gitea/workflows/rust-advisories.yml b/.gitea/workflows/rust-advisories.yml new file mode 100644 index 00000000..72c85cb9 --- /dev/null +++ b/.gitea/workflows/rust-advisories.yml @@ -0,0 +1,19 @@ +# RustSec advisories, out of the blocking path on purpose (RUST_ARCHITECTURE_REVIEW VIII.3): +# an advisory published for an unrelated crate must not redden every branch. The run is +# nightly and manual; the release gate (Step 27) reads its last result. +# STATUS 2026-10-13: prepared, never executed (no runner on the forge yet). Locally: +# `bash docker/rust-run.sh cargo deny check advisories` or, natively, `cargo deny check advisories`. +name: rust-advisories + +on: + schedule: + - cron: '17 3 * * *' + workflow_dispatch: + +jobs: + advisories: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker + - run: bash docker/rust-run.sh cargo deny check advisories diff --git a/.gitignore b/.gitignore index f961359d..4bd836e4 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,7 @@ graphify-out/ # Supabase CLI local state (written by supabase start / db reset) supabase/.branches/ supabase/.temp/ + +# Rust workspace (R0): build output and the generated browser module +target/ +packages/core-wasm/pkg/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 6583db1f..55bb8921 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ 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. + +### Changed (Rust foundation, R0 correction 2026-10-13) + +- **Native Rust toolchain as the primary path** on the Ubuntu development machine (user-level rustup, channel of `rust-toolchain.toml`, `wasm32-unknown-unknown`, `wasm-bindgen-cli` 0.2.129, `cargo-deny` 0.20.2): `pnpm rust:check` and `pnpm wasm:build` run `scripts/rust-check.sh` and `scripts/wasm-build.sh` natively (moved from `docker/`, PATH guard `scripts/rust-env.sh`); the builder image stays the reproducible alternative (`pnpm rust:check:docker`, `pnpm wasm:build:docker`). The native check now covers the worker's unit tests; the sandbox tests and the seccomp derivation stay Docker-only (`pnpm worker:test`). New `pnpm check:all` (`scripts/check-all.sh`): every check a branch must pass before a merge, in one command. The Gitea workflow files are kept but marked prepared and never executed (no runner, secret or registry on the forge). Worker `unsafe` blocks: SAFETY comments rewritten as verifiable invariants (no approval marker), WebP stride computed with checked arithmetic. `docs/development/RUST.md` §1 and §4 describe the three environments (Ubuntu native development, Docker for services and isolation, separate production VPS). + ### 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..78cc362e 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; native user-level rustup on the Ubuntu development machine (`pnpm rust:check`, `pnpm wasm:build`, plain `cargo`), the builder image `docker/rust-builder.Dockerfile` as the reproducible alternative (`:docker` scripts), never on the VPS | 1.99.0 | +| WASM glue | wasm-bindgen crate = CLI version (locked in `scripts/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,16 @@ 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) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first +pnpm rust:check # scripts/rust-check.sh: fmt --check, clippy -D warnings, cargo test (core, wasm, worker unit), ts-rs export, cargo deny +pnpm wasm:build # scripts/wasm-build.sh: crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run +pnpm check:all # scripts/check-all.sh: the whole pre-merge gate (rust:check, types drift, wasm:build, check, app image, worker:test, worker:image) +pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0), the reproducible alternative +pnpm rust:check:docker # the same rust-check.sh inside the builder image +pnpm wasm:build:docker # the same wasm-build.sh inside the builder image +pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, sandbox tests + seccomp derivation on the musl binary +pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static, `run --check`) ``` ## Docker commands @@ -244,7 +257,15 @@ 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 +├─ scripts/{rust-env,rust-check,wasm-build,check-all}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`) +├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proof +├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) +├─ .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 +513,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: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. 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/Cargo.lock b/Cargo.lock new file mode 100644 index 00000000..71145926 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,588 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "bytemuck" +version = "1.25.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797" + +[[package]] +name = "byteorder-lite" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495" + +[[package]] +name = "cc" +version = "1.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6651c9ed80effdc7db0ff72512157f901af5e3549e341e24b1dd4887d836d838" +dependencies = [ + "find-msvc-tools", + "jobserver", + "libc", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "crc32fast" +version = "1.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "equivalent" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" + +[[package]] +name = "faunosteo-core" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "ts-rs", +] + +[[package]] +name = "faunosteo-wasm" +version = "0.1.0" +dependencies = [ + "faunosteo-core", + "wasm-bindgen", +] + +[[package]] +name = "faunosteo-worker" +version = "0.1.0" +dependencies = [ + "crc32fast", + "flate2", + "image", + "libc", + "libwebp-sys", + "rlimit", + "seccompiler", +] + +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484" + +[[package]] +name = "flate2" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb" +dependencies = [ + "crc32fast", + "miniz_oxide 0.9.1", + "zlib-rs", +] + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", +] + +[[package]] +name = "glob" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b" + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "image" +version = "0.25.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104" +dependencies = [ + "bytemuck", + "byteorder-lite", + "image-webp", + "moxcms", + "num-traits", + "png", + "zune-core", + "zune-jpeg", +] + +[[package]] +name = "image-webp" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3" +dependencies = [ + "byteorder-lite", + "quick-error", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "jobserver" +version = "0.1.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3" +dependencies = [ + "getrandom", + "libc", +] + +[[package]] +name = "libc" +version = "0.2.190" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78" + +[[package]] +name = "libwebp-sys" +version = "0.14.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b3a87b44e34d17161e4f17d92a463d596cb13825dcd1758ed18fd3a721e189c" +dependencies = [ + "cc", + "glob", + "pkg-config", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "miniz_oxide" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "moxcms" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b" +dependencies = [ + "num-traits", + "pxfm", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + +[[package]] +name = "png" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61" +dependencies = [ + "bitflags", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide 0.8.9", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "pxfm" +version = "0.1.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea" + +[[package]] +name = "quick-error" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3" + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rlimit" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f35ee2729c56bb610f6dba436bf78135f728b7373bdffae2ec815b2d3eb98cc3" +dependencies = [ + "libc", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "seccompiler" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4ae55de56877481d112a559bbc12667635fdaf5e005712fd4e2b2fa50ffc884" +dependencies = [ + "libc", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "foldhash", + "indexmap", + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "simd-adler32" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea" + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "termcolor" +version = "1.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "ts-rs" +version = "12.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "756050066659291d47a554a9f558125db17428b073c5ffce1daf5dcb0f7231d8" +dependencies = [ + "thiserror", + "ts-rs-macros", +] + +[[package]] +name = "ts-rs-macros" +version = "12.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38d90eea51bc7988ef9e674bf80a85ba6804739e535e9cab48e4bb34a8b652aa" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", + "termcolor", +] + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "wasm-bindgen" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.9", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.129" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" + +[[package]] +name = "zune-core" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b" + +[[package]] +name = "zune-jpeg" +version = "0.5.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296" +dependencies = [ + "zune-core", +] diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 00000000..b8d3faf9 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,57 @@ +# Faunosteo Rust workspace (plan R0, docs/development/RUST_ARCHITECTURE_REVIEW.md Part III). +# Three crates: core (feature-gated library), wasm (browser facade), worker (service binary). +# Commands run on the native toolchain of the development machine (rustup, the channel of +# rust-toolchain.toml) or inside the builder image: docs/development/RUST.md §1. +[workspace] +resolver = "3" +members = ["crates/core", "crates/wasm", "crates/worker"] + +[workspace.package] +version = "0.1.0" +edition = "2024" +license = "MIT" +rust-version = "1.99" +publish = false + +# The path dependency on crates/core is declared per crate (`path = "../core"`): cargo-deny +# 0.20 reads a workspace-inherited path dependency as a wildcard and fails the bans check. +[workspace.dependencies] +serde = { version = "1.0.229", features = ["derive"] } +# preserve_order keeps the input key order of parsed documents (JSON.stringify semantics). +# float_roundtrip: the default parser is a fast path that can be one ULP off (found by the R0 +# proof: 1715.4285714285713 came back as 1715.428571428571); JavaScript parses correctly. +serde_json = { version = "1.0.154", features = ["preserve_order", "float_roundtrip"] } +ts-rs = { version = "12.0", features = ["serde-compat"] } +# The CLI in docker/rust-builder.Dockerfile must be this exact version. +wasm-bindgen = "=0.2.129" +image = { version = "0.25.10", default-features = false, features = ["jpeg", "png", "webp"] } +libwebp-sys = "0.14.4" +seccompiler = "0.5.0" +rlimit = "0.11" +libc = "0.2" + +# The library crates deny unwrap/expect so that no panic path depends on content; +# the worker binary relaxes disallowed_methods (it owns I/O) in its own [lints]. +[workspace.lints.rust] +unsafe_code = "forbid" + +[workspace.lints.clippy] +unwrap_used = "deny" +expect_used = "deny" +disallowed_methods = "deny" + +# Dependencies optimised even in debug builds: the sandbox tests decode 4096² images under a +# 10 s CPU limit, which an unoptimised image decoder does not meet. +[profile.dev.package."*"] +opt-level = 3 + +[profile.release] +opt-level = 3 +lto = "fat" +codegen-units = 1 +# The worker child dies on a panic (the parent logs it); on wasm32 the std is abort anyway. +panic = "abort" +strip = "symbols" + +[profile.release.package.faunosteo-wasm] +opt-level = "z" diff --git a/DEPLOY.md b/DEPLOY.md index ba9928ed..42da1d8d 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -21,6 +21,16 @@ 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: Rust is compiled on the Ubuntu +development machine (native toolchain) or inside Docker builder images, and +production images will be pulled by digest ("Image deploy by digest", +prepared below) once a runner and a registry exist on the forge. No CI/CD is +operational today (2026-10-13). + ### Reference sheet in the image (SHEET_BUNDLE) The application needs an anatomical sheet to work. Until sheets are served by @@ -563,6 +573,66 @@ 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. Prerequisite not met yet: no runner, registry or + secret is configured on the forge (2026-10-13); the workflow has never + run, which is the CI/CD step to decide separately. 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/README.md b/README.md index 7b2caccc..d4403bd8 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,11 @@ cp .env.example .env # edit APP_* vars if desired pnpm dev # http://localhost:5173 ``` +Rust (core, browser module, worker): a user-level `rustup` installs the +pinned toolchain from `rust-toolchain.toml` on first use; see +`docs/development/RUST.md` §1 for the three `cargo install` / `rustup +target add` lines and the Docker alternative. + Docker Compose (matches production topology): ```bash @@ -81,8 +86,14 @@ pnpm lint # ESLint 9 flat config, 0 warnings pnpm test:run # vitest run (domain, anatomy, supabase/PGlite, app) pnpm build # tsc + vite build → apps/app/dist/ pnpm report:compare ... # archive PDF vs its v3 reading, unresolved items flagged +pnpm rust:check # native: fmt, clippy -D warnings, cargo test, ts-rs export, cargo deny +pnpm wasm:build # native: browser module → packages/core-wasm/pkg (the core-wasm proofs run on it) +pnpm check:all # everything a branch must pass before a merge, in one command (needs Docker for the image stages) ``` +No CI/CD runs on the forge yet: the workflow files under `.gitea/workflows/` +are prepared for a future runner and call these same scripts. + --- ## Build & deploy diff --git a/clippy.toml b/clippy.toml new file mode 100644 index 00000000..fd2c1e2e --- /dev/null +++ b/clippy.toml @@ -0,0 +1,14 @@ +# The core library never reads the clock, the file system or the environment: ids, time +# and bytes are inputs (RUST_ARCHITECTURE_REVIEW III.3). Tests and the worker binary +# allow these lints locally where they own I/O. +disallowed-methods = [ + { path = "std::time::SystemTime::now", reason = "the core takes time as an input" }, + { path = "std::time::Instant::now", reason = "the core takes time as an input" }, + { path = "std::fs::read", reason = "the core takes bytes as inputs" }, + { path = "std::fs::read_to_string", reason = "the core takes bytes as inputs" }, + { path = "std::fs::write", reason = "the core returns bytes, the caller writes" }, + { path = "std::fs::File::open", reason = "the core takes bytes as inputs" }, + { path = "std::fs::File::create", reason = "the core returns bytes, the caller writes" }, + { path = "std::env::var", reason = "configuration is injected into the core" }, + { path = "std::env::var_os", reason = "configuration is injected into the core" }, +] diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml new file mode 100644 index 00000000..c200db44 --- /dev/null +++ b/crates/core/Cargo.toml @@ -0,0 +1,24 @@ +[package] +name = "faunosteo-core" +description = "Faunosteo core: data contracts, rules and parsers shared by the browser (wasm), the worker and the tools" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +publish.workspace = true + +[lib] +path = "src/lib.rs" + +[features] +default = [] +# Exports the TypeScript types of the contracts (ts-rs) on `cargo test -p faunosteo-core --features ts`. +ts = ["dep:ts-rs"] + +[dependencies] +serde.workspace = true +serde_json.workspace = true +ts-rs = { workspace = true, optional = true } + +[lints] +workspace = true diff --git a/crates/core/src/domain/mod.rs b/crates/core/src/domain/mod.rs new file mode 100644 index 00000000..06ade144 --- /dev/null +++ b/crates/core/src/domain/mod.rs @@ -0,0 +1,9 @@ +//! Data contracts of the core. +//! +//! R0 carries the Report v3 reference types (sheet reference, zone, vertebra) to prove the +//! serialisation rules against the current Zod schemas; the full contracts and the rules +//! arrive at R2 (review Part VI.2). + +pub mod report; + +pub use report::{LateralSide, ReportZone, SheetRef, Unresolved, Vertebra}; diff --git a/crates/core/src/domain/report.rs b/crates/core/src/domain/report.rs new file mode 100644 index 00000000..d02d091b --- /dev/null +++ b/crates/core/src/domain/report.rs @@ -0,0 +1,137 @@ +//! Report v3 reference types (`packages/domain/src/report/v3.ts`), field order as the Zod +//! schemas declare it. Optional fields are absent when unset and nullable fields are `null` +//! (review I.2): the serde attributes below are the contract, not a convenience. + +use serde::de::Error as _; +use serde::{Deserialize, Deserializer, Serialize, Serializer}; +#[cfg(feature = "ts")] +use ts_rs::TS; + +/// Reference of the anatomical sheet a report was written against (`Report.sheet`). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "camelCase")] +pub struct SheetRef { + pub sheet_id: String, + /// Database version id once the sheet lives in the database; `null` for a bundled draft. + pub version_id: Option, + /// sha256 of the document file the report was written against. + pub document_sha256: String, +} + +/// Side of a bilateral zone. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "lowercase")] +pub enum LateralSide { + Left, + Right, +} + +/// One vertebra of a spine zone: the region code and the 1-based index in that region. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "camelCase")] +pub struct Vertebra { + pub region: String, + pub index: u32, +} + +/// A zone of an observation. Unknown keys are ignored on input, as the Zod schema strips +/// them; optional fields are written only when set. +#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)] +#[cfg_attr(feature = "ts", derive(TS), ts(export))] +#[serde(rename_all = "camelCase")] +pub struct ReportZone { + pub annotation_id: String, + pub view_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + #[cfg_attr(feature = "ts", ts(optional))] + pub side: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + #[cfg_attr(feature = "ts", ts(optional))] + pub vertebrae: Option>, + /// Annotation name at selection time (or legacy name at migration). + #[serde(default, skip_serializing_if = "Option::is_none")] + #[cfg_attr(feature = "ts", ts(optional))] + pub label_fr_snapshot: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + #[cfg_attr(feature = "ts", ts(optional))] + pub label_en_snapshot: Option, + /// Set by the migration when the legacy id has no canonical annotation. + #[serde(default, skip_serializing_if = "Option::is_none")] + #[cfg_attr(feature = "ts", ts(optional, type = "true"))] + pub unresolved: Option, +} + +/// The literal `true` flag of a zone or finding the sheet cannot place +/// (`z.literal(true).optional()` in Zod). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct Unresolved; + +impl Serialize for Unresolved { + fn serialize(&self, serializer: S) -> Result { + serializer.serialize_bool(true) + } +} + +impl<'de> Deserialize<'de> for Unresolved { + fn deserialize>(deserializer: D) -> Result { + if bool::deserialize(deserializer)? { + Ok(Unresolved) + } else { + Err(D::Error::custom( + "unresolved must be the literal true when present", + )) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::json::to_js_pretty; + + #[test] + fn optional_fields_are_absent_and_nullable_fields_are_null() { + let zone = ReportZone { + annotation_id: "hip".to_owned(), + view_id: "main".to_owned(), + ..ReportZone::default() + }; + let Ok(text) = to_js_pretty(&zone) else { + panic!("serialisation failed"); + }; + assert_eq!( + text, + "{\n \"annotationId\": \"hip\",\n \"viewId\": \"main\"\n}" + ); + + let sheet = SheetRef { + sheet_id: "faunosteo-cheval".to_owned(), + version_id: None, + document_sha256: "0".repeat(64), + }; + let Ok(text) = to_js_pretty(&sheet) else { + panic!("serialisation failed"); + }; + assert!(text.contains("\"versionId\": null")); + } + + #[test] + fn unresolved_accepts_true_only() { + let parsed: Result = + serde_json::from_str(r#"{"annotationId":"a","viewId":"v","unresolved":true}"#); + assert_eq!(parsed.ok().and_then(|z| z.unresolved), Some(Unresolved)); + let refused: Result = + serde_json::from_str(r#"{"annotationId":"a","viewId":"v","unresolved":false}"#); + assert!(refused.is_err()); + } + + #[test] + fn unknown_keys_are_ignored_like_the_zod_strip_schema() { + let parsed: Result = + serde_json::from_str(r#"{"annotationId":"a","viewId":"v","extra":1}"#); + assert!(parsed.is_ok()); + } +} diff --git a/crates/core/src/facade.rs b/crates/core/src/facade.rs new file mode 100644 index 00000000..a63b34cd --- /dev/null +++ b/crates/core/src/facade.rs @@ -0,0 +1,90 @@ +//! The call surface the wasm facade and the tools expose (review III.3): one operation +//! name, one JSON text in, one JSON text out, closed outcome kinds, never a panic on +//! content. The envelope is `{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`. + +use serde::Serialize; +use serde::de::DeserializeOwned; +use serde_json::{Value, json}; + +use crate::domain::{ReportZone, SheetRef}; +use crate::json::pretty_js_round_trip; + +/// Runs the operation `op` on the JSON text `input` and returns the outcome envelope. +/// +/// Operations of R0: `core_version`, `pretty_json` (JavaScript pretty form of any JSON +/// text), `sheet_ref` and `report_zone` (parse and re-emit a contract type). +pub fn call(op: &str, input: &str) -> String { + let outcome = match op { + "core_version" => Ok(Value::String(crate::CORE_VERSION.to_owned())), + "pretty_json" => pretty_js_round_trip(input) + .map(Value::String) + .map_err(|error| Failure::new("invalid_json", error)), + "sheet_ref" => echo::(input), + "report_zone" => echo::(input), + _ => Err(Failure::new( + "unknown_op", + format!("no operation named {op}"), + )), + }; + render(outcome) +} + +fn echo(input: &str) -> Result { + let parsed: T = + serde_json::from_str(input).map_err(|error| Failure::new("invalid_shape", error))?; + serde_json::to_value(parsed).map_err(|error| Failure::new("internal", error)) +} + +struct Failure { + kind: &'static str, + detail: String, +} + +impl Failure { + fn new(kind: &'static str, detail: impl std::fmt::Display) -> Self { + Self { + kind, + detail: detail.to_string(), + } + } +} + +fn render(outcome: Result) -> String { + let envelope = match outcome { + Ok(value) => json!({ "ok": true, "value": value }), + Err(failure) => json!({ "ok": false, "kind": failure.kind, "detail": failure.detail }), + }; + serde_json::to_string(&envelope).unwrap_or_else(|_| { + r#"{"ok":false,"kind":"internal","detail":"outcome serialisation failed"}"#.to_owned() + }) +} + +#[cfg(test)] +mod tests { + use super::call; + + #[test] + fn unknown_operation_is_a_closed_kind() { + let outcome = call("nope", "{}"); + assert!(outcome.contains(r#""ok":false"#)); + assert!(outcome.contains(r#""kind":"unknown_op""#)); + } + + #[test] + fn invalid_json_never_panics() { + let outcome = call("pretty_json", "{ not json"); + assert!(outcome.contains(r#""kind":"invalid_json""#)); + } + + #[test] + fn report_zone_round_trip_keeps_the_declared_order() { + let outcome = call( + "report_zone", + r#"{"viewId":"v","side":"left","annotationId":"a"}"#, + ); + assert_eq!( + outcome, + r#"{"ok":true,"value":{"annotationId":"a","viewId":"v","side":"left"}}"# + ); + } +} diff --git a/crates/core/src/json.rs b/crates/core/src/json.rs new file mode 100644 index 00000000..5e4d1459 --- /dev/null +++ b/crates/core/src/json.rs @@ -0,0 +1,227 @@ +//! JSON output with JavaScript number semantics. +//! +//! `JSON.stringify(value, null, 2)` and `serde_json`'s pretty printer agree on everything +//! (two-space indent, `": "`, `[]` and `{}` for empty containers, raw non-ASCII, `\u00XX` +//! control escapes) except finite floats: JavaScript prints `1523` for `1523.0` and `1e+21` +//! for `1e21`, `serde_json` prints `1523.0` and `1e21`. The documents of the repository carry +//! integer-valued coordinates as floats, so the archive attachment and the generated seed +//! files need the JavaScript form (review I.2, D-R11). + +use std::io; + +use serde::Serialize; +use serde_json::ser::{Formatter, PrettyFormatter}; + +/// Formats a finite `f64` exactly as ECMAScript `Number::toString(10)` does. +/// +/// Non-finite values have no JSON form (`JSON.stringify` writes `null`): same here. +pub fn js_number(value: f64) -> String { + if !value.is_finite() { + return "null".to_owned(); + } + if value == 0.0 { + return "0".to_owned(); + } + let (digits, point) = shortest_digits(value.abs()); + let mut out = String::with_capacity(digits.len() + 8); + if value.is_sign_negative() { + out.push('-'); + } + write_decimal(&mut out, &digits, point); + out +} + +/// Shortest round-trip digits of a positive finite value and the position `n` of the +/// decimal point relative to the first digit (ECMAScript's `n`): value = 0.d₁d₂… × 10ⁿ. +/// +/// Rust's `LowerExp` prints the shortest round-trip mantissa (`1.7154285714285713e3`), +/// chosen by the same rule as ECMAScript (shortest, then closest to the value). +fn shortest_digits(value: f64) -> (String, i32) { + let scientific = format!("{value:e}"); + let (mantissa, exponent) = scientific + .split_once('e') + .unwrap_or((scientific.as_str(), "0")); + let exponent: i32 = exponent.parse().unwrap_or(0); + let digits: String = mantissa.chars().filter(char::is_ascii_digit).collect(); + (digits, exponent + 1) +} + +/// ECMAScript Number::toString steps 6 to 10 for `k` digits and point position `n`. +fn write_decimal(out: &mut String, digits: &str, n: i32) { + let k = i32::try_from(digits.len()).unwrap_or(i32::MAX); + if k <= n && n <= 21 { + out.push_str(digits); + out.extend(std::iter::repeat_n('0', (n - k).unsigned_abs() as usize)); + } else if 0 < n && n <= 21 { + let (integer, fraction) = digits.split_at(n.unsigned_abs() as usize); + out.push_str(integer); + out.push('.'); + out.push_str(fraction); + } else if -6 < n && n <= 0 { + out.push_str("0."); + out.extend(std::iter::repeat_n('0', n.unsigned_abs() as usize)); + out.push_str(digits); + } else { + let (first, rest) = digits.split_at(1); + out.push_str(first); + if !rest.is_empty() { + out.push('.'); + out.push_str(rest); + } + let exponent = n - 1; + out.push('e'); + out.push(if exponent < 0 { '-' } else { '+' }); + out.push_str(&exponent.unsigned_abs().to_string()); + } +} + +/// `serde_json`'s pretty formatter with JavaScript float printing. +pub struct JsPrettyFormatter<'a> { + inner: PrettyFormatter<'a>, +} + +impl Default for JsPrettyFormatter<'_> { + fn default() -> Self { + Self { + inner: PrettyFormatter::new(), + } + } +} + +impl Formatter for JsPrettyFormatter<'_> { + fn write_f32(&mut self, writer: &mut W, value: f32) -> io::Result<()> + where + W: ?Sized + io::Write, + { + writer.write_all(js_number(f64::from(value)).as_bytes()) + } + + fn write_f64(&mut self, writer: &mut W, value: f64) -> io::Result<()> + where + W: ?Sized + io::Write, + { + writer.write_all(js_number(value).as_bytes()) + } + + fn begin_array(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.begin_array(writer) + } + + fn end_array(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.end_array(writer) + } + + fn begin_array_value(&mut self, writer: &mut W, first: bool) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.begin_array_value(writer, first) + } + + fn end_array_value(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.end_array_value(writer) + } + + fn begin_object(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.begin_object(writer) + } + + fn end_object(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.end_object(writer) + } + + fn begin_object_key(&mut self, writer: &mut W, first: bool) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.begin_object_key(writer, first) + } + + fn begin_object_value(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.begin_object_value(writer) + } + + fn end_object_value(&mut self, writer: &mut W) -> io::Result<()> + where + W: ?Sized + io::Write, + { + self.inner.end_object_value(writer) + } +} + +/// Serialises `value` as `JSON.stringify(value, null, 2)` would (no trailing newline). +pub fn to_js_pretty(value: &T) -> Result { + let mut buffer = Vec::new(); + let mut serializer = + serde_json::Serializer::with_formatter(&mut buffer, JsPrettyFormatter::default()); + value.serialize(&mut serializer)?; + String::from_utf8(buffer).map_err(::custom) +} + +/// Parses JSON text and re-emits it in the JavaScript pretty form, keeping the key order. +pub fn pretty_js_round_trip(text: &str) -> Result { + let value: serde_json::Value = serde_json::from_str(text)?; + to_js_pretty(&value) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn integer_valued_floats_print_without_a_fraction() { + assert_eq!(js_number(1523.0), "1523"); + assert_eq!(js_number(-7.0), "-7"); + assert_eq!( + js_number(123_456_789_012_345_680_000.0), + "123456789012345680000" + ); + } + + #[test] + fn fractions_and_small_values_follow_the_javascript_thresholds() { + assert_eq!(js_number(0.85), "0.85"); + assert_eq!(js_number(1_715.428_571_428_571_3), "1715.4285714285713"); + assert_eq!(js_number(0.000_001), "0.000001"); + assert_eq!(js_number(0.000_000_1), "1e-7"); + assert_eq!(js_number(1e21), "1e+21"); + assert_eq!(js_number(1.5e300), "1.5e+300"); + assert_eq!(js_number(5e-324), "5e-324"); + } + + #[test] + fn zero_and_non_finite_values() { + assert_eq!(js_number(0.0), "0"); + assert_eq!(js_number(-0.0), "0"); + assert_eq!(js_number(f64::NAN), "null"); + assert_eq!(js_number(f64::INFINITY), "null"); + } + + #[test] + fn pretty_output_matches_the_javascript_shape() { + let text = r#"{"b":[1,2.0,{"c":[]}],"a":{},"d":"é\u0001","e":-0.0}"#; + let expected = "{\n \"b\": [\n 1,\n 2,\n {\n \"c\": []\n }\n ],\n \"a\": {},\n \"d\": \"é\\u0001\",\n \"e\": 0\n}"; + let Ok(actual) = pretty_js_round_trip(text) else { + panic!("round trip failed"); + }; + assert_eq!(actual, expected); + } +} diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs new file mode 100644 index 00000000..f369ae49 --- /dev/null +++ b/crates/core/src/lib.rs @@ -0,0 +1,13 @@ +//! Faunosteo core library (plan R0, `docs/development/RUST_ARCHITECTURE_REVIEW.md`). +//! +//! Rules of the crate (review Part III.3): no I/O, no clock, no random ids; every input +//! is bytes or JSON text, every output is plain data. The same code serves the browser +//! (`crates/wasm`), the worker and the tools. R0 ships the serialisation rules and the +//! first contract types; the business rules arrive with R2. + +pub mod domain; +pub mod facade; +pub mod json; + +/// Version of the core, reported by the wasm facade and the worker. +pub const CORE_VERSION: &str = env!("CARGO_PKG_VERSION"); diff --git a/crates/core/tests/fixtures_round_trip.rs b/crates/core/tests/fixtures_round_trip.rs new file mode 100644 index 00000000..01ba77e7 --- /dev/null +++ b/crates/core/tests/fixtures_round_trip.rs @@ -0,0 +1,39 @@ +//! R0 proof (half of it): the JavaScript pretty form is idempotent on the real documents and +//! prints no integer-valued float with a fraction. The other half, byte equality against +//! `JSON.stringify(JSON.parse(text), null, 2)`, runs in `packages/core-wasm/tests` on the +//! same files through the wasm build. +#![allow(clippy::disallowed_methods, clippy::unwrap_used, clippy::expect_used)] + +use faunosteo_core::json::pretty_js_round_trip; + +fn fixture(relative: &str) -> String { + let path = format!("{}/../../{relative}", env!("CARGO_MANIFEST_DIR")); + std::fs::read_to_string(&path).unwrap_or_else(|error| panic!("{path}: {error}")) +} + +fn assert_round_trip(relative: &str) -> String { + let text = fixture(relative); + let once = pretty_js_round_trip(&text).expect("first pass"); + let twice = pretty_js_round_trip(&once).expect("second pass"); + assert_eq!( + once, twice, + "{relative}: the pretty form must be a fixed point" + ); + assert!( + !once.contains(".0,") && !once.contains(".0\n"), + "{relative}: a float printed as x.0" + ); + once +} + +#[test] +fn demo_report_v3_round_trips() { + let text = assert_round_trip("apps/app/tests/fixtures/report-v3.demo.json"); + assert!(text.starts_with("{\n \"version\": 3,\n")); +} + +#[test] +fn equine_draft_document_round_trips() { + let text = assert_round_trip("supabase/seed/anatomical-sheets/equine/draft/document.json"); + assert!(text.contains("\"schema_version\": 2")); +} diff --git a/crates/wasm/Cargo.toml b/crates/wasm/Cargo.toml new file mode 100644 index 00000000..56fa404a --- /dev/null +++ b/crates/wasm/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "faunosteo-wasm" +description = "Browser facade of the Faunosteo core (wasm-bindgen), built into packages/core-wasm/pkg" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +publish.workspace = true + +[lib] +crate-type = ["cdylib", "rlib"] +path = "src/lib.rs" + +[features] +default = [] +# The R0 trap proofs (panic_for_test, recurse_for_test): built for the proofs, never for the +# module the application ships (scripts/wasm-build.sh passes it until R2 wires the real loader). +proofs = [] + +[dependencies] +faunosteo-core = { path = "../core" } +wasm-bindgen.workspace = true + +[lints] +workspace = true diff --git a/crates/wasm/src/lib.rs b/crates/wasm/src/lib.rs new file mode 100644 index 00000000..af347b06 --- /dev/null +++ b/crates/wasm/src/lib.rs @@ -0,0 +1,46 @@ +//! wasm-bindgen facade over `faunosteo-core` (review III.3): JSON strings in and out, closed +//! outcome kinds. Built by `scripts/wasm-build.sh` into `packages/core-wasm/pkg`; loaded +//! lazily by the application from R2 on (never at R0). + +use wasm_bindgen::prelude::wasm_bindgen; + +/// Version of the core compiled into this module. +#[wasm_bindgen] +pub fn core_version() -> String { + faunosteo_core::CORE_VERSION.to_owned() +} + +/// Runs one core operation: `op` names it, `input` is its JSON text, the result is the +/// JSON text of the outcome envelope (`{"ok":true,"value":…}` or `{"ok":false,"kind":…}`). +#[wasm_bindgen] +pub fn call(op: &str, input: &str) -> String { + faunosteo_core::facade::call(op, input) +} + +/// R0 proof: on wasm32 a panic is a trap (panic = abort), reaching JavaScript as a +/// `WebAssembly.RuntimeError`; the caller re-instantiates the module. +#[cfg(feature = "proofs")] +#[wasm_bindgen] +pub fn panic_for_test() { + panic!("deliberate panic for the R0 proof"); +} + +/// R0 proof: exhausting the shadow stack traps instead of corrupting memory. +#[cfg(feature = "proofs")] +#[wasm_bindgen] +pub fn recurse_for_test(depth: u32) -> u32 { + recurse(depth) +} + +#[cfg(feature = "proofs")] +#[inline(never)] +fn recurse(depth: u32) -> u32 { + let mut frame = [depth; 32]; + if depth == 0 { + return std::hint::black_box(&frame)[0]; + } + let below = recurse(depth - 1); + frame[(below as usize) % 32] ^= below; + std::hint::black_box(&frame); + below.wrapping_add(1) +} diff --git a/crates/worker/Cargo.toml b/crates/worker/Cargo.toml new file mode 100644 index 00000000..d74f8a80 --- /dev/null +++ b/crates/worker/Cargo.toml @@ -0,0 +1,42 @@ +[package] +name = "faunosteo-worker" +description = "Faunosteo file-processing worker: job loop (R1) and the sandboxed decode child (R0 proof)" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +publish.workspace = true + +[lib] +path = "src/lib.rs" + +[[bin]] +name = "faunosteo-worker" +path = "src/main.rs" + +[features] +default = [] +# Extra subcommands and flags for the sandbox tests and the seccomp derivation +# (crates/worker/Dockerfile stage `test`); never part of a release build. +test-hooks = ["dep:crc32fast", "dep:flate2"] + +[dependencies] +image.workspace = true +libwebp-sys.workspace = true +seccompiler.workspace = true +rlimit.workspace = true +libc.workspace = true +crc32fast = { version = "1.4", optional = true } +# Already in the tree through png: used by the iCCP-bomb fixture only. +flate2 = { version = "1.1", optional = true } + +# The worker owns I/O (it is the process boundary), so the core's disallowed_methods lint is +# off here. unsafe stays denied crate-wide; the libwebp FFI and the prctl call carry a local +# #[allow(unsafe_code)] with a SAFETY comment each (forbid would not allow the local override). +[lints.rust] +unsafe_code = "deny" + +[lints.clippy] +unwrap_used = "deny" +expect_used = "deny" +disallowed_methods = "allow" diff --git a/crates/worker/Dockerfile b/crates/worker/Dockerfile new file mode 100644 index 00000000..dffcd4bf --- /dev/null +++ b/crates/worker/Dockerfile @@ -0,0 +1,39 @@ +# syntax=docker/dockerfile:1.7 +# Faunosteo worker image (review Part IV, VIII.1). Build context = repository root: +# docker build -f crates/worker/Dockerfile --target test . # sandbox tests + seccomp derivation +# docker build -f crates/worker/Dockerfile -t faunosteo_worker:dev . # runtime image +# The binary is a static musl executable; the runtime image carries nothing else. + +FROM rust:1.99.0-alpine3.24 AS base +# build-base: the C compiler for libwebp (libwebp-sys, D-R4), nothing else is compiled from C. +# rustfmt/clippy: listed in rust-toolchain.toml, absent from the image's minimal profile. +RUN apk add --no-cache build-base && rustup component add rustfmt clippy +WORKDIR /w +COPY Cargo.toml Cargo.lock rust-toolchain.toml rustfmt.toml clippy.toml ./ +COPY .cargo .cargo +COPY crates crates + +FROM base AS build +RUN --mount=type=cache,id=faunosteo_cargo_registry_musl,target=/usr/local/cargo/registry \ + --mount=type=cache,id=faunosteo_target_musl,target=/w/target \ + cargo build -p faunosteo-worker --release --locked \ + && cp target/release/faunosteo-worker /faunosteo-worker + +# The tests and the derivation run on the release profile (LTO, panic = abort) plus the +# test-hooks feature, inside the default Docker seccomp profile (the inner filter is allowed +# by it): the binary under test differs from the shipped one by the feature-gated hooks only. +FROM base AS test +RUN apk add --no-cache strace +# Own target cache: the hooks build and the shipped build must never share target/release. +RUN --mount=type=cache,id=faunosteo_cargo_registry_musl,target=/usr/local/cargo/registry \ + --mount=type=cache,id=faunosteo_target_musl_test,target=/w/target \ + cargo test -p faunosteo-worker --release --features test-hooks --locked -- --test-threads=4 +RUN --mount=type=cache,id=faunosteo_cargo_registry_musl,target=/usr/local/cargo/registry \ + --mount=type=cache,id=faunosteo_target_musl_test,target=/w/target \ + sh crates/worker/scripts/derive-seccomp.sh + +FROM gcr.io/distroless/static-debian12:nonroot AS runtime +COPY --from=build /faunosteo-worker /faunosteo-worker +USER nonroot +ENTRYPOINT ["/faunosteo-worker"] +CMD ["run", "--check"] diff --git a/crates/worker/scripts/derive-seccomp.sh b/crates/worker/scripts/derive-seccomp.sh new file mode 100755 index 00000000..60d946d6 --- /dev/null +++ b/crates/worker/scripts/derive-seccomp.sh @@ -0,0 +1,48 @@ +#!/bin/sh +# Derives the seccomp allowlist of the decode child from a real trace and checks it against +# `sandbox::ALLOWED_SYSCALLS` (review Part IV.1: "derived by strace over the fixture corpus +# at the caps on the production image, not hand-written"). Runs in the Alpine `test` stage +# of crates/worker/Dockerfile, where the musl binary that ships is built. +# +# Exit 1 when a traced syscall is missing from the allowlist (the sandbox would kill a +# legitimate decode). Syscalls the list allows but the trace never shows are printed for +# review (the abort path is expected there). +set -eu + +bin=target/release/faunosteo-worker +cargo build -p faunosteo-worker --release --features test-hooks --locked +work=$(mktemp -d) + +fixtures="png jpeg webp big-jpeg big-png" +: > "$work/traced.raw" +for kind in $fixtures; do + "$bin" fixture "$kind" > "$work/$kind.bin" + # `env -i`: the child refuses a non-empty environment; `--no-seccomp` keeps the rlimits + # and makes one sched_yield where the filter would be installed (strace cannot read the + # child's memory once PR_SET_DUMPABLE is 0, so the marker is a syscall, not a string). + env -i strace -f -qq -o "$work/trace.$kind" "$bin" decode --no-seccomp \ + < "$work/$kind.bin" > "$work/$kind.webp" + awk 'found { print } /sched_yield\(/ { found = 1 }' "$work/trace.$kind" \ + | sed -E 's/^[0-9]+ +//; /^(\+\+\+|---)/d; s/^<\.\.\. ([a-z0-9_]+) resumed>.*/\1/; s/\(.*//' \ + | grep -E '^[a-z0-9_]+$' >> "$work/traced.raw" || true +done +sort -u "$work/traced.raw" > "$work/traced.txt" +"$bin" print-allowlist | sort -u > "$work/allowed.txt" +if [ ! -s "$work/traced.txt" ]; then + echo "== NO SYSCALL TRACED AFTER THE MARKER: the derivation is broken, not the allowlist" >&2 + echo "== tail of the png trace:" >&2 + tail -n 40 "$work/trace.png" >&2 + exit 1 +fi + +echo "== syscalls traced after the sandbox marker" +cat "$work/traced.txt" +missing=$(comm -23 "$work/traced.txt" "$work/allowed.txt") +extra=$(comm -13 "$work/traced.txt" "$work/allowed.txt") +echo "== allowed but not traced (abort path expected): $(echo "$extra" | tr '\n' ' ')" +if [ -n "$missing" ]; then + echo "== TRACED BUT NOT ALLOWED (the filter would kill a legitimate decode):" + echo "$missing" + exit 1 +fi +echo "== allowlist covers the trace" diff --git a/crates/worker/src/decode.rs b/crates/worker/src/decode.rs new file mode 100644 index 00000000..aee12efd --- /dev/null +++ b/crates/worker/src/decode.rs @@ -0,0 +1,364 @@ +//! The decode child: bytes in, one 512 × 512 lossy WebP out (review Part IV.1). R0 ships +//! the pipeline as the sandbox, musl and libwebp proof; the job semantics arrive with R1. + +use std::ffi::c_int; +use std::io::{self, Cursor, Read, Write}; + +use image::error::LimitErrorKind; +use image::imageops::FilterType; +use image::metadata::Orientation; +use image::{DynamicImage, ImageDecoder, ImageError, ImageFormat, ImageReader, Limits}; + +use crate::exit_codes; +use crate::limits::{ + MAX_ALLOC_BYTES, MAX_INPUT_BYTES, MAX_SIDE, MIN_SIDE, OUTPUT_SIDE, WEBP_QUALITY, +}; +use crate::sandbox; + +/// Why the child refused an input (one exit code each). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Reject { + UnsupportedType, + DecodeFailed, + Dimensions, + /// A decoder budget (`image::Limits`, allocation, complexity) exceeded by the content. + ResourceLimit, + /// libwebp failed on the buffer the child produced itself: an environment fault. + EncodeFailed, + /// A programming or I/O fault of the child, never a judgement on the content. + Internal, +} + +impl Reject { + pub fn exit_code(self) -> i32 { + match self { + Self::UnsupportedType => exit_codes::UNSUPPORTED_TYPE, + Self::DecodeFailed => exit_codes::DECODE_FAILED, + Self::Dimensions => exit_codes::DIMENSIONS, + Self::ResourceLimit => exit_codes::RESOURCE_LIMIT, + Self::EncodeFailed => exit_codes::ENCODE_FAILED, + Self::Internal => exit_codes::INTERNAL, + } + } +} + +/// Entry of `faunosteo-worker decode`: returns the process exit code. +/// +/// Order matters: the environment check and the sandbox come before the first byte of +/// input is read, and no thread exists at that point (`main` is a plain function). +pub fn main( + args: &[String], + stdin: &mut dyn Read, + stdout: &mut dyn Write, + stderr: &mut dyn Write, +) -> i32 { + if std::env::vars_os().next().is_some() { + let _ = writeln!(stderr, "decode: the environment must be empty"); + return exit_codes::ENV_NOT_EMPTY; + } + let hooks = match TestHooks::parse(args) { + Ok(hooks) => hooks, + Err(message) => { + let _ = writeln!(stderr, "decode: {message}"); + return exit_codes::USAGE; + } + }; + if let Err(error) = sandbox::apply(&sandbox::Limits::default(), hooks.seccomp) { + let _ = writeln!(stderr, "decode: sandbox: {error}"); + return exit_codes::SANDBOX_FAILED; + } + if let Some(code) = hooks.run_after_sandbox(stdout, stderr) { + return code; + } + + let mut input = Vec::new(); + let read = stdin + .take(MAX_INPUT_BYTES as u64 + 1) + .read_to_end(&mut input); + if read.is_err() { + return exit_codes::INTERNAL; + } + if input.len() > MAX_INPUT_BYTES { + let _ = writeln!(stderr, "decode: input over {MAX_INPUT_BYTES} bytes"); + return exit_codes::INPUT_TOO_LARGE; + } + + match process(&input) { + Ok(webp) => match stdout.write_all(&webp).and_then(|()| stdout.flush()) { + Ok(()) => exit_codes::OK, + Err(_) => exit_codes::OUTPUT_FAILED, + }, + Err(reject) => { + let _ = writeln!(stderr, "decode: {}", exit_codes::name(reject.exit_code())); + reject.exit_code() + } + } +} + +/// Decodes, orients, crops to a square and encodes one image; pure function of the bytes. +pub fn process(bytes: &[u8]) -> Result, Reject> { + let format = image::guess_format(bytes).map_err(|_| Reject::UnsupportedType)?; + if !matches!( + format, + ImageFormat::Jpeg | ImageFormat::Png | ImageFormat::WebP + ) { + return Err(Reject::UnsupportedType); + } + let mut reader = ImageReader::with_format(Cursor::new(bytes), format); + let mut limits = Limits::default(); + limits.max_image_width = Some(MAX_SIDE); + limits.max_image_height = Some(MAX_SIDE); + limits.max_alloc = Some(MAX_ALLOC_BYTES); + reader.limits(limits); + + let mut decoder = reader.into_decoder().map_err(map_image_error)?; + let (width, height) = decoder.dimensions(); + if width < MIN_SIDE || height < MIN_SIDE { + return Err(Reject::Dimensions); + } + let orientation = decoder.orientation().unwrap_or(Orientation::NoTransforms); + let mut image = DynamicImage::from_decoder(decoder).map_err(map_image_error)?; + image.apply_orientation(orientation); + let square = image + .resize_to_fill(OUTPUT_SIDE, OUTPUT_SIDE, FilterType::Lanczos3) + .into_rgba8(); + encode_webp(square.as_raw(), OUTPUT_SIDE, OUTPUT_SIDE, WEBP_QUALITY) +} + +/// Every decode-time error is a judgement on the content (a content code): an uploader must +/// never be able to produce a "broken environment" outcome (security audit of R0). +fn map_image_error(error: ImageError) -> Reject { + match error { + ImageError::Limits(limit) => match limit.kind() { + LimitErrorKind::DimensionError => Reject::Dimensions, + _ => Reject::ResourceLimit, + }, + ImageError::Unsupported(_) => Reject::UnsupportedType, + _ => Reject::DecodeFailed, + } +} + +/// Encodes an RGBA buffer as lossy WebP through libwebp (D-R4: C confined to this process). +#[allow(unsafe_code)] +pub fn encode_webp(rgba: &[u8], width: u32, height: u32, quality: f32) -> Result, Reject> { + let expected = (width as usize) + .checked_mul(height as usize) + .and_then(|n| n.checked_mul(4)); + if expected != Some(rgba.len()) { + return Err(Reject::Internal); + } + let Some(stride_bytes) = width.checked_mul(4) else { + return Err(Reject::Internal); + }; + let (Ok(w), Ok(h), Ok(stride)) = ( + c_int::try_from(width), + c_int::try_from(height), + c_int::try_from(stride_bytes), + ) else { + return Err(Reject::Internal); + }; + let mut output: *mut u8 = std::ptr::null_mut(); + // SAFETY: WebPEncodeRGBA reads `height` rows of `stride` bytes starting at `rgba`; + // `rgba.len() == width * height * 4` and `stride == width * 4` are established above with + // overflow-checked arithmetic, so every read stays inside the slice, which outlives the + // call. `&mut output` is a valid `*mut *mut u8` for the duration of the call: libwebp + // stores the address of a buffer it allocated there, or leaves it null and returns 0. + // libwebp retains no pointer once the call returns. + let size = + unsafe { libwebp_sys::WebPEncodeRGBA(rgba.as_ptr(), w, h, stride, quality, &mut output) }; + if size == 0 || output.is_null() { + return Err(Reject::EncodeFailed); + } + // SAFETY: a non-zero return means libwebp initialised exactly `size` bytes at `output` + // (both non-zero and non-null, checked just above). The slice lives only for the copy + // below and is dropped before the buffer is released. + let encoded = unsafe { std::slice::from_raw_parts(output, size) }.to_vec(); + // SAFETY: `output` was allocated by libwebp for this call and must be released by its + // own WebPFree; this is the single release and the pointer is not used afterwards. + unsafe { libwebp_sys::WebPFree(output.cast()) }; + Ok(encoded) +} + +/// Version of the libwebp linked into this binary, as (major, minor, revision). +#[allow(unsafe_code)] +pub fn libwebp_version() -> (u8, u8, u8) { + // SAFETY: WebPGetEncoderVersion takes no argument, touches no memory owned by the caller + // and has no side effect: it returns the version packed into a C int. + let packed = unsafe { libwebp_sys::WebPGetEncoderVersion() }; + let packed = u32::try_from(packed).unwrap_or(0); + ( + u8::try_from((packed >> 16) & 0xff).unwrap_or(0), + u8::try_from((packed >> 8) & 0xff).unwrap_or(0), + u8::try_from(packed & 0xff).unwrap_or(0), + ) +} + +/// Flags of the test build (`--features test-hooks`); a release build accepts no argument. +#[derive(Debug, Default)] +pub struct TestHooks { + pub seccomp: bool, + #[cfg(feature = "test-hooks")] + action: Option, +} + +#[cfg(feature = "test-hooks")] +#[derive(Debug, Clone, Copy)] +enum HookAction { + /// Makes a denied syscall (`getcwd`) after the filter: the child must die with SIGSYS. + Violate, + /// Writes a megabyte on stdout: the parent must cut the child at its output cap. + Flood, + /// Allocates the given number of GiB: `RLIMIT_AS` must abort the child. + AllocGib(usize), + /// Burns CPU forever: `RLIMIT_CPU` (SIGXCPU) or the parent's deadline must stop it. + Spin, + /// Sends SIGTERM to the parent through `tkill`: the argument filter must kill the child. + SignalParent, + /// Maps executable memory: the `mmap` argument filter must kill the child. + MmapExec, +} + +impl TestHooks { + fn parse(args: &[String]) -> Result { + #[cfg(not(feature = "test-hooks"))] + let hooks = Self { seccomp: true }; + #[cfg(feature = "test-hooks")] + let mut hooks = Self { + seccomp: true, + action: None, + }; + #[cfg(feature = "test-hooks")] + { + let mut iter = args.iter(); + while let Some(arg) = iter.next() { + match arg.as_str() { + "--no-seccomp" => hooks.seccomp = false, + "--violate" => hooks.action = Some(HookAction::Violate), + "--flood" => hooks.action = Some(HookAction::Flood), + "--spin" => hooks.action = Some(HookAction::Spin), + "--signal-parent" => hooks.action = Some(HookAction::SignalParent), + "--mmap-exec" => hooks.action = Some(HookAction::MmapExec), + "--alloc-gib" => { + let value = iter + .next() + .and_then(|v| v.parse().ok()) + .ok_or("--alloc-gib ")?; + hooks.action = Some(HookAction::AllocGib(value)); + } + other => return Err(format!("unknown flag {other}")), + } + } + } + #[cfg(not(feature = "test-hooks"))] + if let Some(arg) = args.first() { + return Err(format!("unexpected argument {arg}")); + } + Ok(hooks) + } + + #[cfg(feature = "test-hooks")] + fn run_after_sandbox(&self, stdout: &mut dyn Write, stderr: &mut dyn Write) -> Option { + if !self.seccomp { + // Marker for crates/worker/scripts/derive-seccomp.sh: one `sched_yield`, a syscall + // the decode path never makes, right where the filter would be installed. The + // syscalls after it are the ones the filter must allow. (A string marker is not + // readable by strace once PR_SET_DUMPABLE is 0.) + std::thread::yield_now(); + let _ = stderr.write_all(b"SECCOMP-MARKER\n"); + } + match self.action? { + HookAction::Violate => { + let cwd = std::env::current_dir(); + let _ = writeln!(stderr, "decode: getcwd survived the filter: {cwd:?}"); + Some(exit_codes::INTERNAL) + } + HookAction::Flood => { + let chunk = vec![0u8; 64 * 1024]; + for _ in 0..16 { + if stdout.write_all(&chunk).is_err() { + return Some(exit_codes::OUTPUT_FAILED); + } + } + Some(exit_codes::OK) + } + HookAction::AllocGib(gib) => { + let bytes = gib.saturating_mul(1024 * 1024 * 1024); + let buffer = vec![1u8; bytes]; + let _ = writeln!( + stderr, + "decode: allocated {} bytes", + std::hint::black_box(&buffer).len() + ); + Some(exit_codes::INTERNAL) + } + HookAction::Spin => loop { + std::hint::black_box(0u8); + }, + HookAction::SignalParent => { + let survived = negative_hooks::signal_parent(); + let _ = writeln!( + stderr, + "decode: tkill(parent) survived the filter: {survived}" + ); + Some(exit_codes::INTERNAL) + } + HookAction::MmapExec => { + let survived = negative_hooks::mmap_exec(); + let _ = writeln!( + stderr, + "decode: mmap(PROT_EXEC) survived the filter: {survived}" + ); + Some(exit_codes::INTERNAL) + } + } + } + + #[cfg(not(feature = "test-hooks"))] + fn run_after_sandbox(&self, _stdout: &mut dyn Write, _stderr: &mut dyn Write) -> Option { + None + } +} + +/// Negative proofs of the seccomp argument filters (`test-hooks` only): each call must die +/// with SIGSYS before returning; a return value means the filter let it through. +#[cfg(feature = "test-hooks")] +#[allow(unsafe_code)] +mod negative_hooks { + /// `tkill(getppid(), SIGTERM)`: a signal to another process. + pub fn signal_parent() -> i32 { + // SAFETY: a raw syscall with three integer arguments and no pointer: the kernel + // validates them, so the call cannot touch this process's memory. What the proof + // checks is behaviour: under the filter the process dies with SIGSYS before any + // signal exists; without the filter the parent would receive SIGTERM, which is why + // this module is compiled with the test hooks only and reached by `--signal-parent`. + unsafe { libc::syscall(libc::SYS_tkill, libc::getppid(), libc::SIGTERM) as i32 } + } + + /// `mmap` of one executable page. + pub fn mmap_exec() -> i32 { + // SAFETY: an anonymous private mapping with a null address hint and no file + // descriptor: no existing mapping is touched, and the returned address is only + // compared with MAP_FAILED, never dereferenced. Under the filter the process dies + // with SIGSYS before the mapping exists; without it one page leaks in a test process. + let page = unsafe { + libc::mmap( + std::ptr::null_mut(), + 4096, + libc::PROT_READ | libc::PROT_EXEC, + libc::MAP_PRIVATE | libc::MAP_ANONYMOUS, + -1, + 0, + ) + }; + i32::from(page != libc::MAP_FAILED) + } +} + +/// Reads at most `cap` bytes from a reader, reporting whether more were available. +pub fn read_capped(reader: &mut dyn Read, cap: usize) -> io::Result<(Vec, bool)> { + let mut buffer = Vec::new(); + reader.take(cap as u64 + 1).read_to_end(&mut buffer)?; + let overflow = buffer.len() > cap; + buffer.truncate(cap); + Ok((buffer, overflow)) +} diff --git a/crates/worker/src/exit_codes.rs b/crates/worker/src/exit_codes.rs new file mode 100644 index 00000000..f787e494 --- /dev/null +++ b/crates/worker/src/exit_codes.rs @@ -0,0 +1,47 @@ +//! Exit codes of the `decode` child, reserved away from 1 (generic failure), 101 (Rust +//! panic) and signal deaths (reported separately by the parent). The parent maps them to +//! the closed rejection reasons of STEP8_FILES_ANALYSIS II.7. + +pub const OK: i32 = 0; +pub const USAGE: i32 = 2; +pub const ENV_NOT_EMPTY: i32 = 10; +pub const SANDBOX_FAILED: i32 = 11; +pub const INPUT_TOO_LARGE: i32 = 12; +pub const UNSUPPORTED_TYPE: i32 = 13; +pub const DECODE_FAILED: i32 = 14; +pub const DIMENSIONS: i32 = 15; +pub const ENCODE_FAILED: i32 = 16; +pub const OUTPUT_FAILED: i32 = 17; +pub const INTERNAL: i32 = 18; +/// The decoders' allocation or complexity budget was exceeded by the content. +pub const RESOURCE_LIMIT: i32 = 19; + +/// Codes that judge the content (the upload is refused). Every other non-zero code means +/// the child's environment is broken (`Broken` outcome: the parent alerts rather than +/// rejects). Explicit list on purpose: a new code never lands in the wrong class by +/// accident, and no content can produce a "broken" code. +pub fn is_content_rejection(code: i32) -> bool { + matches!( + code, + INPUT_TOO_LARGE | UNSUPPORTED_TYPE | DECODE_FAILED | DIMENSIONS | RESOURCE_LIMIT + ) +} + +/// Stable name of an exit code for logs and tests. +pub fn name(code: i32) -> &'static str { + match code { + OK => "ok", + USAGE => "usage", + ENV_NOT_EMPTY => "env_not_empty", + SANDBOX_FAILED => "sandbox_failed", + INPUT_TOO_LARGE => "input_too_large", + UNSUPPORTED_TYPE => "unsupported_type", + DECODE_FAILED => "decode_failed", + DIMENSIONS => "dimensions", + ENCODE_FAILED => "encode_failed", + OUTPUT_FAILED => "output_failed", + INTERNAL => "internal", + RESOURCE_LIMIT => "resource_limit", + _ => "unknown", + } +} diff --git a/crates/worker/src/fixtures.rs b/crates/worker/src/fixtures.rs new file mode 100644 index 00000000..387bc096 --- /dev/null +++ b/crates/worker/src/fixtures.rs @@ -0,0 +1,127 @@ +//! Synthetic images for the sandbox tests and the seccomp derivation (`test-hooks` only): +//! nothing binary lives in the repository. + +use std::io::Cursor; + +use image::{DynamicImage, ImageBuffer, ImageFormat, Rgba}; + +fn gradient(width: u32, height: u32) -> DynamicImage { + let buffer = ImageBuffer::from_fn(width, height, |x, y| { + let r = u8::try_from(x * 255 / width.max(1)).unwrap_or(255); + let g = u8::try_from(y * 255 / height.max(1)).unwrap_or(255); + let b = u8::try_from((x / 8 + y / 8) % 256).unwrap_or(0); + Rgba([r, g, b, 255]) + }); + DynamicImage::ImageRgba8(buffer) +} + +fn encode(image: &DynamicImage, format: ImageFormat) -> Vec { + let mut out = Cursor::new(Vec::new()); + if image.write_to(&mut out, format).is_err() { + return Vec::new(); + } + out.into_inner() +} + +/// A PNG gradient. +pub fn png(width: u32, height: u32) -> Vec { + encode(&gradient(width, height), ImageFormat::Png) +} + +/// A baseline JPEG gradient (no alpha channel). +pub fn jpeg(width: u32, height: u32) -> Vec { + let rgb = DynamicImage::ImageRgb8(gradient(width, height).into_rgb8()); + encode(&rgb, ImageFormat::Jpeg) +} + +/// A lossless WebP gradient (the only WebP encoder of the `image` crate). +pub fn webp(width: u32, height: u32) -> Vec { + encode(&gradient(width, height), ImageFormat::WebP) +} + +/// A PNG whose header declares `width` × `height` with no pixel data: the decoder must +/// refuse it on dimensions before allocating anything. +pub fn png_header_only(width: u32, height: u32) -> Vec { + let mut out = vec![0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]; + let mut ihdr = Vec::new(); + ihdr.extend_from_slice(&width.to_be_bytes()); + ihdr.extend_from_slice(&height.to_be_bytes()); + ihdr.extend_from_slice(&[8, 6, 0, 0, 0]); + push_chunk(&mut out, b"IHDR", &ihdr); + push_chunk(&mut out, b"IEND", &[]); + out +} + +fn push_chunk(out: &mut Vec, kind: &[u8; 4], payload: &[u8]) { + out.extend_from_slice(&(payload.len() as u32).to_be_bytes()); + let mut hasher = crc32fast::Hasher::new(); + hasher.update(kind); + hasher.update(payload); + out.extend_from_slice(kind); + out.extend_from_slice(payload); + out.extend_from_slice(&hasher.finalize().to_be_bytes()); +} + +/// A small PNG header whose `iCCP` profile inflates to `inflated_bytes` (hundreds of +/// kilobytes of compressed zeros) and that carries no image data: the decoder refuses it as +/// content (`decode_failed` or `resource_limit`, depending on which check fires first), +/// never as a broken environment. R1 adds a variant with image data so the budget itself +/// is seen firing. +pub fn png_iccp_bomb(inflated_bytes: usize) -> Vec { + use std::io::Write; + let mut out = vec![0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a]; + let mut ihdr = Vec::new(); + ihdr.extend_from_slice(&64u32.to_be_bytes()); + ihdr.extend_from_slice(&64u32.to_be_bytes()); + ihdr.extend_from_slice(&[8, 6, 0, 0, 0]); + push_chunk(&mut out, b"IHDR", &ihdr); + let mut iccp = b"p\0\0".to_vec(); + let mut encoder = flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::best()); + let zeros = vec![0u8; 1 << 20]; + let mut written = 0; + while written < inflated_bytes { + let chunk = (inflated_bytes - written).min(zeros.len()); + if encoder.write_all(&zeros[..chunk]).is_err() { + break; + } + written += chunk; + } + iccp.extend_from_slice(&encoder.finish().unwrap_or_default()); + push_chunk(&mut out, b"iCCP", &iccp); + push_chunk(&mut out, b"IEND", &[]); + out +} + +/// The first bytes of a GIF: a format the avatar pipeline never accepts. +pub fn gif() -> Vec { + let mut out = b"GIF89a".to_vec(); + out.extend_from_slice(&[64, 0, 64, 0, 0xf7, 0, 0]); + out.extend(std::iter::repeat_n(0u8, 800)); + out +} + +/// A valid PNG cut in half. +pub fn truncated_png() -> Vec { + let mut bytes = png(200, 200); + bytes.truncate(bytes.len() / 2); + bytes +} + +/// Writes one named fixture on stdout (`faunosteo-worker fixture `). +pub fn by_name(name: &str) -> Option> { + Some(match name { + "png" => png(800, 600), + "jpeg" => jpeg(640, 480), + "webp" => webp(300, 700), + "big-jpeg" => jpeg(4096, 4096), + // Same pixel budget as the JPEG but compressible (4096 × 2048 of this gradient + // weighed more than the 5 MiB input cap). + "big-png" => png(3000, 3000), + "tiny" => png(32, 32), + "huge-header" => png_header_only(20_000, 20_000), + "iccp-bomb" => png_iccp_bomb(300 << 20), + "gif" => gif(), + "truncated" => truncated_png(), + _ => return None, + }) +} diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs new file mode 100644 index 00000000..8981b33b --- /dev/null +++ b/crates/worker/src/lib.rs @@ -0,0 +1,15 @@ +//! `faunosteo-worker` library: the pieces the binary, the tests and the R1 job loop share. +//! +//! Process model (review Part IV.1): a keyed parent spawns the same binary as `decode`, a +//! child with an empty environment that confines itself (rlimits + seccomp) before reading +//! one image on stdin and writing one 512 × 512 WebP on stdout. The parent never decodes: +//! it checks the container header of what comes back (`webp_check`). + +pub mod decode; +pub mod exit_codes; +#[cfg(feature = "test-hooks")] +pub mod fixtures; +pub mod limits; +pub mod sandbox; +pub mod spawn; +pub mod webp_check; diff --git a/crates/worker/src/limits.rs b/crates/worker/src/limits.rs new file mode 100644 index 00000000..f418bd04 --- /dev/null +++ b/crates/worker/src/limits.rs @@ -0,0 +1,26 @@ +//! Caps of the decode child (review Part IV.1 and STEP8_FILES_ANALYSIS II.5 step 6). + +use std::time::Duration; + +/// Largest accepted upload (STEP8 D4: 5 MiB at upload). +pub const MAX_INPUT_BYTES: usize = 5 * 1024 * 1024; +/// Largest output the parent reads before killing the child (a 512 × 512 WebP is ~30 KB). +pub const MAX_OUTPUT_BYTES: usize = 512 * 1024; +/// Smallest accepted side of the source image. +pub const MIN_SIDE: u32 = 64; +/// Largest accepted side of the source image (header check before decoding). +pub const MAX_SIDE: u32 = 4096; +/// Allocation budget handed to the decoders (`image::Limits::max_alloc`, advisory). +pub const MAX_ALLOC_BYTES: u64 = 256 * 1024 * 1024; +/// Side of the produced avatar. +pub const OUTPUT_SIDE: u32 = 512; +/// Lossy WebP quality of the produced avatar. +pub const WEBP_QUALITY: f32 = 82.0; +/// Hard address-space cap of the child (`RLIMIT_AS`): the real memory bound. +pub const CHILD_ADDRESS_SPACE_BYTES: u64 = 512 * 1024 * 1024; +/// CPU-time cap of the child (`RLIMIT_CPU`, seconds). +pub const CHILD_CPU_SECONDS: u64 = 10; +/// Wall-clock deadline after which the parent kills the child. +pub const CHILD_DEADLINE: Duration = Duration::from_secs(20); +/// Oldest libwebp the worker accepts to link (D-R4: the linked version is controlled). +pub const MIN_LIBWEBP_VERSION: (u8, u8, u8) = (1, 6, 0); diff --git a/crates/worker/src/main.rs b/crates/worker/src/main.rs new file mode 100644 index 00000000..7eea8959 --- /dev/null +++ b/crates/worker/src/main.rs @@ -0,0 +1,113 @@ +//! `faunosteo-worker` entry: a plain `main`, no async runtime, no thread, so the `decode` +//! child installs its sandbox in a single-threaded process (review Part IV.1). +//! +//! R0 subcommands: `decode` (the sandboxed child), `run --check` (prints the resolved +//! configuration, no job loop before R1), `version`. + +use std::io::Write; + +use faunosteo_worker::decode; +use faunosteo_worker::exit_codes; +use faunosteo_worker::limits::MIN_LIBWEBP_VERSION; + +fn main() { + let args: Vec = std::env::args().collect(); + let code = match args.get(1).map(String::as_str) { + Some("decode") => { + let stdin = std::io::stdin(); + let stdout = std::io::stdout(); + let stderr = std::io::stderr(); + decode::main( + &args[2..], + &mut stdin.lock(), + &mut stdout.lock(), + &mut stderr.lock(), + ) + } + Some("run") => run(&args[2..]), + Some("version") => version(), + #[cfg(feature = "test-hooks")] + Some("fixture") => fixture(&args[2..]), + #[cfg(feature = "test-hooks")] + Some("print-allowlist") => { + for name in faunosteo_worker::sandbox::allowed_names() { + println!("{name}"); + } + exit_codes::OK + } + _ => { + eprintln!("usage: faunosteo-worker "); + exit_codes::USAGE + } + }; + std::process::exit(code); +} + +fn version() -> i32 { + let (major, minor, revision) = decode::libwebp_version(); + println!( + "faunosteo-worker {} (core {}, libwebp {major}.{minor}.{revision})", + env!("CARGO_PKG_VERSION"), + faunosteo_core_version() + ); + exit_codes::OK +} + +fn faunosteo_core_version() -> &'static str { + // The worker links no core module before R1 (nothing to share yet); the version printed + // is the workspace version the two crates share. + env!("CARGO_PKG_VERSION") +} + +/// `run --check`: prints what the worker would start with, without secrets. The job loop +/// arrives at R1; a plain `run` therefore refuses to pretend it works. +fn run(args: &[String]) -> i32 { + let (major, minor, revision) = decode::libwebp_version(); + let libwebp_ok = (major, minor, revision) >= MIN_LIBWEBP_VERSION; + println!("faunosteo-worker run: R0 skeleton, the job loop arrives at R1"); + println!( + "libwebp {major}.{minor}.{revision} ({})", + if libwebp_ok { + "accepted" + } else { + "below the minimum, refusing to start" + } + ); + for name in ["SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "WORKER_ID"] { + let state = if std::env::var_os(name).is_some() { + "set" + } else { + "unset" + }; + println!("{name}: {state}"); + } + let _ = std::io::stdout().flush(); + if !libwebp_ok { + return exit_codes::INTERNAL; + } + if args.iter().any(|arg| arg == "--check") { + exit_codes::OK + } else { + eprintln!("run: nothing to do before R1 (use --check to print the configuration)"); + exit_codes::USAGE + } +} + +#[cfg(feature = "test-hooks")] +fn fixture(args: &[String]) -> i32 { + let Some(bytes) = args + .first() + .and_then(|name| faunosteo_worker::fixtures::by_name(name)) + else { + eprintln!( + "usage: faunosteo-worker fixture " + ); + return exit_codes::USAGE; + }; + let stdout = std::io::stdout(); + let mut lock = stdout.lock(); + if lock.write_all(&bytes).and_then(|()| lock.flush()).is_err() { + return exit_codes::OUTPUT_FAILED; + } + exit_codes::OK +} diff --git a/crates/worker/src/sandbox.rs b/crates/worker/src/sandbox.rs new file mode 100644 index 00000000..015cf5c3 --- /dev/null +++ b/crates/worker/src/sandbox.rs @@ -0,0 +1,266 @@ +//! Confinement of the decode child (review Part IV.1), applied by the child itself from a +//! single-threaded process before it reads any input. Three layers: an empty environment +//! (cleared by the parent, checked in `decode`), rlimits on address space and CPU time, and +//! a seccomp allowlist installed with TSYNC that kills the process on any other syscall. + +use std::collections::BTreeMap; +use std::fmt; + +use seccompiler::{ + BpfProgram, SeccompAction, SeccompCmpArgLen, SeccompCmpOp, SeccompCondition, SeccompFilter, + SeccompRule, TargetArch, +}; + +use crate::limits; + +/// Syscalls the decode child makes once the filter is installed (static musl binary, x86_64). +/// +/// Derived with `strace -f` over the fixture corpus at the caps (`crates/worker/scripts/ +/// derive-seccomp.sh`, run by the Dockerfile stage `test`, 2026-10-12: exactly these seven +/// after the marker) and proven by running every fixture through the full sandbox. musl's +/// mallocng used neither `brk` nor `mprotect`, and no `futex` appears in a single-threaded +/// decode. +pub const ALLOWED_SYSCALLS: &[(&str, i64)] = &[ + ("read", libc::SYS_read), + ("write", libc::SYS_write), + ("mmap", libc::SYS_mmap), + ("munmap", libc::SYS_munmap), + ("mremap", libc::SYS_mremap), + ("exit_group", libc::SYS_exit_group), + ("getrandom", libc::SYS_getrandom), +]; + +/// Syscalls of the abort path (`RLIMIT_AS` hit, allocation failure, panic = abort): what +/// musl's `abort()` and Rust's alloc error handler need, proven by the sandbox test +/// `the_address_space_limit_aborts_a_huge_allocation` (SIGABRT observed, not SIGSYS). +pub const ABORT_PATH_SYSCALLS: &[(&str, i64)] = &[ + ("rt_sigaction", libc::SYS_rt_sigaction), + ("rt_sigprocmask", libc::SYS_rt_sigprocmask), + ("getpid", libc::SYS_getpid), + ("gettid", libc::SYS_gettid), + ("tkill", libc::SYS_tkill), + ("tgkill", libc::SYS_tgkill), + ("exit", libc::SYS_exit), +]; + +/// Resource limits of the child. +#[derive(Debug, Clone, Copy)] +pub struct Limits { + pub address_space_bytes: u64, + pub cpu_seconds: u64, +} + +impl Default for Limits { + fn default() -> Self { + Self { + address_space_bytes: limits::CHILD_ADDRESS_SPACE_BYTES, + cpu_seconds: limits::CHILD_CPU_SECONDS, + } + } +} + +/// Why the sandbox could not be applied (the child exits `sandbox_failed`). +#[derive(Debug)] +pub enum SandboxError { + NotSingleThreaded(usize), + ProcStatusUnreadable, + Rlimit(String), + Seccomp(String), + UnsupportedArchitecture, +} + +impl fmt::Display for SandboxError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::NotSingleThreaded(n) => write!(f, "process has {n} threads, expected 1"), + Self::ProcStatusUnreadable => write!(f, "/proc/self/status unreadable"), + Self::Rlimit(detail) => write!(f, "rlimit: {detail}"), + Self::Seccomp(detail) => write!(f, "seccomp: {detail}"), + Self::UnsupportedArchitecture => write!(f, "no seccomp filter for this architecture"), + } + } +} + +impl std::error::Error for SandboxError {} + +/// Applies the three layers. `seccomp = false` keeps only the rlimits (the strace +/// derivation run of the test stage); a release child always passes `true`. +pub fn apply(limits: &Limits, seccomp: bool) -> Result<(), SandboxError> { + ensure_single_thread()?; + disable_core_dumps()?; + set_rlimits(limits)?; + if seccomp { + install_seccomp()?; + } + Ok(()) +} + +/// No core dump of the child: a dump would hold the uploaded photo (personal data) and +/// could fill the VPS disk (SIGABRT under `RLIMIT_AS`, SIGSYS, SIGXCPU all dump by default). +/// `PR_SET_DUMPABLE 0` is the kernel-side stop, `RLIMIT_CORE 0` the belt. +#[allow(unsafe_code)] +fn disable_core_dumps() -> Result<(), SandboxError> { + /// prctl reads its variadic arguments as unsigned long: the flag value and the + /// arguments an option ignores are passed at that width. + const NOT_DUMPABLE: libc::c_ulong = 0; + const UNUSED: libc::c_ulong = 0; + // SAFETY: prctl is a variadic FFI reading its extra arguments as unsigned long; for + // PR_SET_DUMPABLE the kernel uses the first one (the new flag) and ignores the other + // three, passed at that width: no pointer, no memory of this process involved, and only + // this process's flag changes. The return code is checked below. + let rc = unsafe { libc::prctl(libc::PR_SET_DUMPABLE, NOT_DUMPABLE, UNUSED, UNUSED, UNUSED) }; + if rc != 0 { + return Err(SandboxError::Rlimit("PR_SET_DUMPABLE".to_owned())); + } + // SAFETY: PR_GET_DUMPABLE reads this process's flag and ignores the extra arguments, + // passed as unsigned-long zeros. The result is the flag (0 expected) or -1 on failure: + // any non-zero value is refused below. + let dumpable = unsafe { libc::prctl(libc::PR_GET_DUMPABLE, UNUSED, UNUSED, UNUSED, UNUSED) }; + if dumpable != 0 { + return Err(SandboxError::Rlimit(format!( + "PR_GET_DUMPABLE = {dumpable}" + ))); + } + rlimit::setrlimit(rlimit::Resource::CORE, 0, 0) + .map_err(|error| SandboxError::Rlimit(format!("RLIMIT_CORE: {error}"))) +} + +/// Every syscall name the filter allows, for the derivation script and the tests. +pub fn allowed_names() -> Vec<&'static str> { + ALLOWED_SYSCALLS + .iter() + .chain(ABORT_PATH_SYSCALLS) + .map(|(name, _)| *name) + .collect() +} + +/// Parses the `Threads:` line of a `/proc//status` text. +pub fn thread_count(status: &str) -> Option { + status + .lines() + .find_map(|line| line.strip_prefix("Threads:")) + .and_then(|value| value.trim().parse().ok()) +} + +fn ensure_single_thread() -> Result<(), SandboxError> { + let status = std::fs::read_to_string("/proc/self/status") + .map_err(|_| SandboxError::ProcStatusUnreadable)?; + match thread_count(&status) { + Some(1) => Ok(()), + Some(n) => Err(SandboxError::NotSingleThreaded(n)), + None => Err(SandboxError::ProcStatusUnreadable), + } +} + +fn set_rlimits(limits: &Limits) -> Result<(), SandboxError> { + rlimit::setrlimit( + rlimit::Resource::AS, + limits.address_space_bytes, + limits.address_space_bytes, + ) + .map_err(|error| SandboxError::Rlimit(format!("RLIMIT_AS: {error}")))?; + // Soft limit first (SIGXCPU, observable), hard limit two seconds later (SIGKILL): with + // soft == hard the kernel checks the hard limit first and the child dies by SIGKILL, + // indistinguishable from the parent's own deadline kill. + rlimit::setrlimit( + rlimit::Resource::CPU, + limits.cpu_seconds, + limits.cpu_seconds + 2, + ) + .map_err(|error| SandboxError::Rlimit(format!("RLIMIT_CPU: {error}"))) +} + +/// Builds the BPF program: allow the listed syscalls, kill the process on anything else. +/// +/// Argument filters on the abort path and on `mmap`: `tkill`/`tgkill` may only send SIGABRT +/// to this very process (the child is single-threaded, so tid == pid), never a signal to the +/// keyed parent or a sibling; `mmap` may not map executable memory. +pub fn build_filter() -> Result { + let pid = u64::from(std::process::id()); + let sigabrt = u64::try_from(libc::SIGABRT).unwrap_or(6); + let prot_exec = u64::try_from(libc::PROT_EXEC).unwrap_or(4); + let mut rules: BTreeMap> = ALLOWED_SYSCALLS + .iter() + .chain(ABORT_PATH_SYSCALLS) + .map(|(_, number)| (*number, Vec::new())) + .collect(); + let seccomp_err = |error: seccompiler::BackendError| SandboxError::Seccomp(error.to_string()); + let eq = |index: u8, value: u64| { + SeccompCondition::new(index, SeccompCmpArgLen::Qword, SeccompCmpOp::Eq, value) + .map_err(seccomp_err) + }; + rules.insert( + libc::SYS_tkill, + vec![SeccompRule::new(vec![eq(0, pid)?, eq(1, sigabrt)?]).map_err(seccomp_err)?], + ); + rules.insert( + libc::SYS_tgkill, + vec![ + SeccompRule::new(vec![eq(0, pid)?, eq(1, pid)?, eq(2, sigabrt)?]) + .map_err(seccomp_err)?, + ], + ); + let no_exec = SeccompCondition::new( + 2, + SeccompCmpArgLen::Qword, + SeccompCmpOp::MaskedEq(prot_exec), + 0, + ) + .map_err(seccomp_err)?; + rules.insert( + libc::SYS_mmap, + vec![SeccompRule::new(vec![no_exec]).map_err(seccomp_err)?], + ); + let filter = SeccompFilter::new( + rules, + SeccompAction::KillProcess, + SeccompAction::Allow, + target_arch()?, + ) + .map_err(|error| SandboxError::Seccomp(error.to_string()))?; + filter.try_into().map_err(seccomp_err) +} + +fn install_seccomp() -> Result<(), SandboxError> { + let program = build_filter()?; + seccompiler::apply_filter_all_threads(&program) + .map_err(|error| SandboxError::Seccomp(error.to_string())) +} + +fn target_arch() -> Result { + if cfg!(target_arch = "x86_64") { + Ok(TargetArch::x86_64) + } else if cfg!(target_arch = "aarch64") { + Ok(TargetArch::aarch64) + } else { + Err(SandboxError::UnsupportedArchitecture) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn thread_count_reads_the_status_line() { + assert_eq!(thread_count("Name:\tx\nThreads:\t1\nSigQ:\t0/1\n"), Some(1)); + assert_eq!(thread_count("Threads:\t12\n"), Some(12)); + assert_eq!(thread_count("Name:\tx\n"), None); + } + + #[test] + fn the_filter_compiles() { + let program = build_filter(); + assert!(program.is_ok()); + } + + #[test] + fn no_file_or_process_syscall_is_allowed() { + let names = allowed_names(); + for forbidden in [ + "open", "openat", "execve", "clone", "fork", "socket", "ptrace", + ] { + assert!(!names.contains(&forbidden), "{forbidden} must stay denied"); + } + } +} diff --git a/crates/worker/src/spawn.rs b/crates/worker/src/spawn.rs new file mode 100644 index 00000000..bf9d068f --- /dev/null +++ b/crates/worker/src/spawn.rs @@ -0,0 +1,183 @@ +//! Runs the decode child from the keyed parent (review Part IV.1): empty environment, +//! bounded output, wall-clock deadline, and the mapping of every way the child can end to +//! a closed outcome. The parent reads the container header of the output, never the pixels. + +use std::io::{Read, Write}; +use std::os::unix::process::ExitStatusExt; +use std::path::PathBuf; +use std::process::{Command, ExitStatus, Stdio}; +use std::sync::mpsc; +use std::time::{Duration, Instant}; + +use crate::limits::{CHILD_DEADLINE, MAX_OUTPUT_BYTES, OUTPUT_SIDE}; +use crate::{exit_codes, webp_check}; + +/// How a decode child ended. +#[derive(Debug)] +pub enum ChildOutcome { + /// A 512 × 512 WebP whose container passed the parent's check. + Produced(Vec), + /// The child refused the input with one of its content exit codes + /// (`exit_codes::is_content_rejection`). + Rejected { code: i32, name: &'static str }, + /// The child could not run properly (usage, non-empty environment, sandbox failure, + /// encode or output failure, internal error): the confinement environment is broken, + /// not the upload. No content can produce this outcome (every decode-time error maps + /// to a content code). R1 alerts and stops on it instead of rejecting the job. + Broken { code: i32, name: &'static str }, + /// The child died from a signal (SIGSYS 31 = seccomp, SIGABRT 6 = allocation failure, + /// SIGXCPU 24 = CPU limit, SIGKILL 9 = the parent). + Signalled { signal: i32 }, + /// The child wrote more than the output cap and was killed. + OutputOverflow, + /// The child outlived the deadline and was killed. + Timeout, + /// The child exited 0 but its output failed the container check, or it could not run. + Failed(String), +} + +/// A finished child run. `stderr` is text the child controls (up to 4 KiB): never logged +/// raw by R1, control characters escaped and the field allowlist applied (LRN-044). +#[derive(Debug)] +pub struct ChildRun { + pub outcome: ChildOutcome, + pub stderr: String, +} + +/// Spawns `decode` children of one worker binary. +#[derive(Debug, Clone)] +pub struct Spawner { + pub exe: PathBuf, + pub deadline: Duration, + pub max_output: usize, + pub extra_args: Vec, +} + +impl Spawner { + pub fn new(exe: impl Into) -> Self { + Self { + exe: exe.into(), + deadline: CHILD_DEADLINE, + max_output: MAX_OUTPUT_BYTES, + extra_args: Vec::new(), + } + } + + /// Feeds `input` to a fresh child and classifies what comes back. + pub fn decode(&self, input: &[u8]) -> ChildRun { + let spawned = Command::new(&self.exe) + .arg("decode") + .args(&self.extra_args) + .env_clear() + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn(); + let mut child = match spawned { + Ok(child) => child, + Err(error) => return failed(format!("spawn: {error}")), + }; + let (Some(mut stdin), Some(stdout), Some(stderr)) = + (child.stdin.take(), child.stdout.take(), child.stderr.take()) + else { + let _ = child.kill(); + let _ = child.wait(); + return failed("child pipes unavailable".to_owned()); + }; + + let input = input.to_vec(); + let writer = std::thread::spawn(move || { + let _ = stdin.write_all(&input); + }); + let cap = self.max_output; + let (tx, rx) = mpsc::channel(); + std::thread::spawn(move || { + let mut buffer = Vec::new(); + let mut limited = stdout.take(cap as u64 + 1); + let _ = limited.read_to_end(&mut buffer); + let _ = tx.send(buffer); + }); + let err_reader = std::thread::spawn(move || { + let mut buffer = Vec::new(); + let _ = stderr.take(4096).read_to_end(&mut buffer); + String::from_utf8_lossy(&buffer).into_owned() + }); + + let started = Instant::now(); + let mut output: Option> = None; + let status: Option = loop { + if output.is_none() + && let Ok(buffer) = rx.try_recv() + { + if buffer.len() > cap { + let _ = child.kill(); + let _ = child.wait(); + let _ = writer.join(); + let stderr = err_reader.join().unwrap_or_default(); + return ChildRun { + outcome: ChildOutcome::OutputOverflow, + stderr, + }; + } + output = Some(buffer); + } + match child.try_wait() { + Ok(Some(status)) => break Some(status), + Ok(None) => { + if started.elapsed() > self.deadline { + let _ = child.kill(); + let _ = child.wait(); + break None; + } + std::thread::sleep(Duration::from_millis(20)); + } + Err(error) => { + let _ = child.kill(); + let _ = child.wait(); + return failed(format!("wait: {error}")); + } + } + }; + let _ = writer.join(); + let output = output.unwrap_or_else(|| rx.recv().unwrap_or_default()); + let stderr = err_reader.join().unwrap_or_default(); + if output.len() > cap { + return ChildRun { + outcome: ChildOutcome::OutputOverflow, + stderr, + }; + } + let outcome = match status { + None => ChildOutcome::Timeout, + Some(status) => classify(status, output), + }; + ChildRun { outcome, stderr } + } +} + +fn classify(status: ExitStatus, output: Vec) -> ChildOutcome { + match status.code() { + Some(0) => match webp_check::expect_square(&output, OUTPUT_SIDE) { + Ok(_) => ChildOutcome::Produced(output), + Err(issue) => ChildOutcome::Failed(format!("output refused: {issue}")), + }, + Some(code) if exit_codes::is_content_rejection(code) => ChildOutcome::Rejected { + code, + name: exit_codes::name(code), + }, + Some(code) => ChildOutcome::Broken { + code, + name: exit_codes::name(code), + }, + None => ChildOutcome::Signalled { + signal: status.signal().unwrap_or(-1), + }, + } +} + +fn failed(detail: String) -> ChildRun { + ChildRun { + outcome: ChildOutcome::Failed(detail), + stderr: String::new(), + } +} diff --git a/crates/worker/src/webp_check.rs b/crates/worker/src/webp_check.rs new file mode 100644 index 00000000..7af7ec10 --- /dev/null +++ b/crates/worker/src/webp_check.rs @@ -0,0 +1,291 @@ +//! Parent-side check of the child's output (review Part IV.1): the keyed parent never +//! decodes pixels. It parses the RIFF container, allowlists the chunk types, reads the +//! canvas size from the bitstream headers and refuses any metadata chunk. + +use std::fmt; + +/// Why the parent refused the child's output. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum WebpIssue { + TooShort, + NotRiff, + RiffSizeMismatch, + NotWebp, + ChunkOverrun, + ForbiddenChunk([u8; 4]), + MissingBitstream, + BadBitstream, + Dimensions { width: u32, height: u32 }, +} + +impl fmt::Display for WebpIssue { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::ForbiddenChunk(fourcc) => { + write!(f, "forbidden chunk {}", String::from_utf8_lossy(fourcc)) + } + Self::Dimensions { width, height } => write!(f, "unexpected size {width}x{height}"), + other => write!(f, "{other:?}"), + } + } +} + +/// What the parent learnt from the container without decoding a pixel. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct WebpSummary { + pub width: u32, + pub height: u32, + pub chunks: Vec<[u8; 4]>, +} + +const ALLOWED_CHUNKS: [&[u8; 4]; 4] = [b"VP8X", b"VP8 ", b"VP8L", b"ALPH"]; + +/// Parses the container of a WebP file produced by the child. +pub fn inspect(bytes: &[u8]) -> Result { + let header = bytes.get(0..12).ok_or(WebpIssue::TooShort)?; + if &header[0..4] != b"RIFF" { + return Err(WebpIssue::NotRiff); + } + let riff_size = u32::from_le_bytes([header[4], header[5], header[6], header[7]]) as usize; + if riff_size.checked_add(8) != Some(bytes.len()) { + return Err(WebpIssue::RiffSizeMismatch); + } + if &header[8..12] != b"WEBP" { + return Err(WebpIssue::NotWebp); + } + + let mut offset = 12; + let mut chunks: Vec<[u8; 4]> = Vec::new(); + let mut canvas: Option<(u32, u32)> = None; + let mut frame: Option<(u32, u32)> = None; + while offset < bytes.len() { + let chunk_header = bytes + .get(offset..offset + 8) + .ok_or(WebpIssue::ChunkOverrun)?; + let fourcc = [ + chunk_header[0], + chunk_header[1], + chunk_header[2], + chunk_header[3], + ]; + let size = u32::from_le_bytes([ + chunk_header[4], + chunk_header[5], + chunk_header[6], + chunk_header[7], + ]) as usize; + let start = offset + 8; + let end = start.checked_add(size).ok_or(WebpIssue::ChunkOverrun)?; + let payload = bytes.get(start..end).ok_or(WebpIssue::ChunkOverrun)?; + if !ALLOWED_CHUNKS.contains(&&fourcc) { + return Err(WebpIssue::ForbiddenChunk(fourcc)); + } + // Structure the encoder produces, and nothing else: an optional VP8X first, then an + // optional ALPH (extended files only), then exactly one VP8 or VP8L frame. + match &fourcc { + b"VP8X" => { + if !chunks.is_empty() { + return Err(WebpIssue::BadBitstream); + } + canvas = Some(parse_vp8x(payload)?); + } + b"ALPH" => { + if canvas.is_none() || frame.is_some() { + return Err(WebpIssue::BadBitstream); + } + } + b"VP8 " | b"VP8L" => { + if frame.is_some() { + return Err(WebpIssue::BadBitstream); + } + frame = Some(if &fourcc == b"VP8 " { + parse_vp8(payload)? + } else { + parse_vp8l(payload)? + }); + } + _ => return Err(WebpIssue::ForbiddenChunk(fourcc)), + } + chunks.push(fourcc); + offset = end + (size & 1); + } + let frame = frame.ok_or(WebpIssue::MissingBitstream)?; + // The canvas (VP8X) and the frame must agree: the encoder never writes otherwise. + if let Some(canvas) = canvas + && canvas != frame + { + return Err(WebpIssue::BadBitstream); + } + let (width, height) = canvas.unwrap_or(frame); + Ok(WebpSummary { + width, + height, + chunks, + }) +} + +/// `inspect`, then the canvas must be exactly `side` × `side`. +pub fn expect_square(bytes: &[u8], side: u32) -> Result { + let summary = inspect(bytes)?; + if summary.width != side || summary.height != side { + return Err(WebpIssue::Dimensions { + width: summary.width, + height: summary.height, + }); + } + Ok(summary) +} + +fn parse_vp8x(payload: &[u8]) -> Result<(u32, u32), WebpIssue> { + let p = payload.get(0..10).ok_or(WebpIssue::BadBitstream)?; + let width = 1 + u32::from_le_bytes([p[4], p[5], p[6], 0]); + let height = 1 + u32::from_le_bytes([p[7], p[8], p[9], 0]); + Ok((width, height)) +} + +fn parse_vp8(payload: &[u8]) -> Result<(u32, u32), WebpIssue> { + let p = payload.get(0..10).ok_or(WebpIssue::BadBitstream)?; + if p[3..6] != [0x9d, 0x01, 0x2a] { + return Err(WebpIssue::BadBitstream); + } + let width = u32::from(u16::from_le_bytes([p[6], p[7]]) & 0x3fff); + let height = u32::from(u16::from_le_bytes([p[8], p[9]]) & 0x3fff); + Ok((width, height)) +} + +fn parse_vp8l(payload: &[u8]) -> Result<(u32, u32), WebpIssue> { + let p = payload.get(0..5).ok_or(WebpIssue::BadBitstream)?; + if p[0] != 0x2f { + return Err(WebpIssue::BadBitstream); + } + let bits = u32::from_le_bytes([p[1], p[2], p[3], p[4]]); + Ok(((bits & 0x3fff) + 1, ((bits >> 14) & 0x3fff) + 1)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn riff(chunks: &[(&[u8; 4], &[u8])]) -> Vec { + let mut body = b"WEBP".to_vec(); + for (fourcc, payload) in chunks { + body.extend_from_slice(*fourcc); + body.extend_from_slice(&(payload.len() as u32).to_le_bytes()); + body.extend_from_slice(payload); + if payload.len() % 2 == 1 { + body.push(0); + } + } + let mut out = b"RIFF".to_vec(); + out.extend_from_slice(&(body.len() as u32).to_le_bytes()); + out.extend_from_slice(&body); + out + } + + fn vp8x(width: u32, height: u32) -> Vec { + let w = (width - 1).to_le_bytes(); + let h = (height - 1).to_le_bytes(); + vec![0x10, 0, 0, 0, w[0], w[1], w[2], h[0], h[1], h[2]] + } + + #[test] + fn a_square_vp8x_file_passes() { + let mut vp8 = vec![0u8; 20]; + vp8[3..6].copy_from_slice(&[0x9d, 0x01, 0x2a]); + vp8[6..8].copy_from_slice(&512u16.to_le_bytes()); + vp8[8..10].copy_from_slice(&512u16.to_le_bytes()); + let bytes = riff(&[(b"VP8X", &vp8x(512, 512)), (b"VP8 ", &vp8)]); + let summary = expect_square(&bytes, 512); + assert_eq!(summary.map(|s| (s.width, s.height)), Ok((512, 512))); + } + + #[test] + fn a_frame_disagreeing_with_its_canvas_is_refused() { + let mut vp8 = vec![0u8; 10]; + vp8[3..6].copy_from_slice(&[0x9d, 0x01, 0x2a]); + vp8[6..8].copy_from_slice(&256u16.to_le_bytes()); + vp8[8..10].copy_from_slice(&512u16.to_le_bytes()); + let bytes = riff(&[(b"VP8X", &vp8x(512, 512)), (b"VP8 ", &vp8)]); + assert_eq!(inspect(&bytes), Err(WebpIssue::BadBitstream)); + } + + #[test] + fn chunk_structure_is_strict() { + let mut vp8 = vec![0u8; 20]; + vp8[3..6].copy_from_slice(&[0x9d, 0x01, 0x2a]); + vp8[6..8].copy_from_slice(&512u16.to_le_bytes()); + vp8[8..10].copy_from_slice(&512u16.to_le_bytes()); + // two frames + assert_eq!( + inspect(&riff(&[(b"VP8 ", &vp8), (b"VP8 ", &vp8)])), + Err(WebpIssue::BadBitstream) + ); + // ALPH without VP8X + assert_eq!( + inspect(&riff(&[(b"ALPH", &[0; 4]), (b"VP8 ", &vp8)])), + Err(WebpIssue::BadBitstream) + ); + // VP8X not first + assert_eq!( + inspect(&riff(&[(b"VP8 ", &vp8), (b"VP8X", &vp8x(512, 512))])), + Err(WebpIssue::BadBitstream) + ); + // the encoder's extended layout + assert!( + expect_square( + &riff(&[ + (b"VP8X", &vp8x(512, 512)), + (b"ALPH", &[0; 4]), + (b"VP8 ", &vp8) + ]), + 512 + ) + .is_ok() + ); + } + + #[test] + fn metadata_chunks_are_refused() { + let bytes = riff(&[(b"VP8X", &vp8x(512, 512)), (b"EXIF", b"x")]); + // refused on the chunk type before any structural rule + assert_eq!(inspect(&bytes), Err(WebpIssue::ForbiddenChunk(*b"EXIF"))); + } + + #[test] + fn wrong_sizes_are_refused() { + let mut vp8 = vec![0u8; 20]; + vp8[3..6].copy_from_slice(&[0x9d, 0x01, 0x2a]); + vp8[6..8].copy_from_slice(&511u16.to_le_bytes()); + vp8[8..10].copy_from_slice(&512u16.to_le_bytes()); + let bytes = riff(&[(b"VP8X", &vp8x(511, 512)), (b"VP8 ", &vp8)]); + assert_eq!( + expect_square(&bytes, 512), + Err(WebpIssue::Dimensions { + width: 511, + height: 512 + }) + ); + let mut truncated = riff(&[(b"VP8X", &vp8x(512, 512))]); + truncated.pop(); + assert_eq!(inspect(&truncated), Err(WebpIssue::RiffSizeMismatch)); + assert_eq!( + inspect(&riff(&[(b"VP8X", &vp8x(512, 512))])), + Err(WebpIssue::MissingBitstream) + ); + assert_eq!(inspect(b"not a webp"), Err(WebpIssue::TooShort)); + } + + #[test] + fn simple_lossy_and_lossless_headers_give_the_size() { + let mut vp8 = vec![0u8; 10]; + vp8[3..6].copy_from_slice(&[0x9d, 0x01, 0x2a]); + vp8[6..8].copy_from_slice(&512u16.to_le_bytes()); + vp8[8..10].copy_from_slice(&512u16.to_le_bytes()); + assert!(expect_square(&riff(&[(b"VP8 ", &vp8)]), 512).is_ok()); + + let bits: u32 = (512 - 1) | ((512 - 1) << 14); + let mut vp8l = vec![0x2f]; + vp8l.extend_from_slice(&bits.to_le_bytes()); + assert!(expect_square(&riff(&[(b"VP8L", &vp8l)]), 512).is_ok()); + } +} diff --git a/crates/worker/tests/sandbox.rs b/crates/worker/tests/sandbox.rs new file mode 100644 index 00000000..6fa19fc0 --- /dev/null +++ b/crates/worker/tests/sandbox.rs @@ -0,0 +1,212 @@ +//! R0 proofs of the decode child, run against the real binary (`--features test-hooks`, +//! Linux): the full sandbox accepts the fixture corpus, refuses what it must, and every +//! other way the child can die is observed and classified by the parent. +#![cfg(all(feature = "test-hooks", target_os = "linux"))] +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use std::process::{Command, Stdio}; +use std::time::Duration; + +use faunosteo_worker::spawn::{ChildOutcome, Spawner}; +use faunosteo_worker::{exit_codes, fixtures, limits, webp_check}; + +const SIGABRT: i32 = 6; +const SIGXCPU: i32 = 24; +const SIGSYS: i32 = 31; + +fn spawner() -> Spawner { + Spawner::new(env!("CARGO_BIN_EXE_faunosteo-worker")) +} + +fn with_hook(flags: &[&str]) -> Spawner { + let mut spawner = spawner(); + spawner.extra_args = flags.iter().map(|flag| (*flag).to_owned()).collect(); + spawner +} + +fn expect_rejected(bytes: &[u8], code: i32) { + let run = spawner().decode(bytes); + match run.outcome { + ChildOutcome::Rejected { code: got, .. } if got == code => {} + other => panic!( + "expected {}, got {other:?} (stderr: {})", + exit_codes::name(code), + run.stderr + ), + } +} + +#[test] +fn png_jpeg_and_webp_decode_through_the_full_sandbox() { + for (name, bytes) in [ + ("png", fixtures::png(800, 600)), + ("jpeg", fixtures::jpeg(640, 480)), + ("webp", fixtures::webp(300, 700)), + ] { + let run = spawner().decode(&bytes); + match run.outcome { + ChildOutcome::Produced(out) => { + let summary = webp_check::inspect(&out).unwrap(); + assert_eq!((summary.width, summary.height), (512, 512), "{name}"); + assert!( + out.len() < limits::MAX_OUTPUT_BYTES, + "{name}: {} bytes", + out.len() + ); + } + other => panic!("{name}: {other:?} (stderr: {})", run.stderr), + } + } +} + +#[test] +fn inputs_at_the_caps_decode_within_the_limits() { + let big = fixtures::jpeg(4096, 4096); + let run = spawner().decode(&big); + assert!( + matches!(run.outcome, ChildOutcome::Produced(_)), + "{:?} {}", + run.outcome, + run.stderr + ); +} + +#[test] +fn too_small_images_are_refused_on_dimensions() { + expect_rejected(&fixtures::png(32, 32), exit_codes::DIMENSIONS); +} + +#[test] +fn oversized_headers_are_refused_before_decoding() { + expect_rejected( + &fixtures::png_header_only(20_000, 20_000), + exit_codes::DIMENSIONS, + ); +} + +#[test] +fn an_iccp_bomb_is_a_content_rejection_not_a_broken_environment() { + // The png crate reports the inflated profile as a decoding error; the property proven + // here is that content can only ever be rejected, never classified as a broken + // environment (the outcome R1 alerts on). + let run = spawner().decode(&fixtures::png_iccp_bomb(300 << 20)); + match run.outcome { + ChildOutcome::Rejected { code, .. } + if code == exit_codes::DECODE_FAILED || code == exit_codes::RESOURCE_LIMIT => {} + other => panic!( + "expected a content rejection, got {other:?} ({})", + run.stderr + ), + } +} + +#[test] +fn a_signal_to_the_parent_is_killed_by_the_argument_filter() { + let run = with_hook(&["--signal-parent"]).decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Signalled { signal: SIGSYS }), + "{:?} {}", + run.outcome, + run.stderr + ); +} + +#[test] +fn an_executable_mapping_is_killed_by_the_argument_filter() { + let run = with_hook(&["--mmap-exec"]).decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Signalled { signal: SIGSYS }), + "{:?} {}", + run.outcome, + run.stderr + ); +} + +#[test] +fn unsupported_formats_are_refused() { + expect_rejected(&fixtures::gif(), exit_codes::UNSUPPORTED_TYPE); + expect_rejected( + b"", + exit_codes::UNSUPPORTED_TYPE, + ); +} + +#[test] +fn truncated_files_are_decode_failures() { + expect_rejected(&fixtures::truncated_png(), exit_codes::DECODE_FAILED); +} + +#[test] +fn the_child_refuses_a_non_empty_environment() { + let status = Command::new(env!("CARGO_BIN_EXE_faunosteo-worker")) + .arg("decode") + .env_clear() + .env("LEAKED", "1") + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status() + .unwrap(); + assert_eq!(status.code(), Some(exit_codes::ENV_NOT_EMPTY)); +} + +#[test] +fn a_denied_syscall_kills_the_child_with_sigsys() { + let run = with_hook(&["--violate"]).decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Signalled { signal: SIGSYS }), + "{:?} {}", + run.outcome, + run.stderr + ); +} + +#[test] +fn an_output_flood_is_cut_at_the_cap() { + let run = with_hook(&["--flood"]).decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::OutputOverflow), + "{:?}", + run.outcome + ); +} + +#[test] +fn the_address_space_limit_aborts_a_huge_allocation() { + let run = with_hook(&["--alloc-gib", "2"]).decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Signalled { signal: SIGABRT }), + "{:?} {}", + run.outcome, + run.stderr + ); +} + +#[test] +fn the_deadline_kills_a_spinning_child() { + let mut spawner = with_hook(&["--spin"]); + spawner.deadline = Duration::from_secs(2); + let run = spawner.decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Timeout), + "{:?}", + run.outcome + ); +} + +#[test] +fn the_cpu_limit_stops_a_spinning_child_before_the_deadline() { + let mut spawner = with_hook(&["--spin"]); + spawner.deadline = Duration::from_secs(limits::CHILD_CPU_SECONDS + 10); + let run = spawner.decode(b""); + assert!( + matches!(run.outcome, ChildOutcome::Signalled { signal: SIGXCPU }), + "{:?}", + run.outcome + ); +} + +#[test] +fn the_linked_libwebp_is_recent_enough() { + assert!(faunosteo_worker::decode::libwebp_version() >= limits::MIN_LIBWEBP_VERSION); +} diff --git a/deny.toml b/deny.toml new file mode 100644 index 00000000..f079a33b --- /dev/null +++ b/deny.toml @@ -0,0 +1,46 @@ +# cargo-deny policy (RUST_ARCHITECTURE_REVIEW Part V). `cargo deny check licenses bans sources` +# blocks in CI; `cargo deny check advisories` runs in the nightly job and at release time, so +# an unrelated advisory publication never reddens every branch. +[graph] +targets = [ + { triple = "x86_64-unknown-linux-gnu" }, + { triple = "x86_64-unknown-linux-musl" }, + { triple = "wasm32-unknown-unknown" }, +] +all-features = true + +[advisories] +yanked = "deny" +ignore = [] + +[licenses] +allow = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Unicode-3.0", + "Zlib", + "MPL-2.0", + "CC0-1.0", + "Unlicense", + "BSL-1.0", +] +confidence-threshold = 0.9 + +[licenses.private] +ignore = true + +[bans] +multiple-versions = "warn" +wildcards = "deny" +# The workspace path dependency on crates/core has no version requirement: not a wildcard. +allow-wildcard-paths = true +highlight = "all" + +[sources] +unknown-registry = "deny" +unknown-git = "deny" +allow-registry = ["https://github.com/rust-lang/crates.io-index"] diff --git a/docker/csp-proof/run.mjs b/docker/csp-proof/run.mjs new file mode 100644 index 00000000..5ff51936 --- /dev/null +++ b/docker/csp-proof/run.mjs @@ -0,0 +1,17 @@ +import { chromium } from 'playwright-core' +const exe = process.env.CHROME +const browser = await chromium.launch({ executablePath: exe, headless: true }) +for (const [name, port] of [['without wasm-unsafe-eval', 8091], ['with wasm-unsafe-eval', 8092]]) { + const page = await browser.newPage() + const logs = [] + page.on('console', (m) => logs.push(`${m.type()}: ${m.text()}`)) + page.on('pageerror', (e) => logs.push(`pageerror: ${e.message}`)) + const resp = await page.goto(`http://127.0.0.1:${port}/`) + const csp = resp.headers()['content-security-policy'] + await page.waitForFunction(() => document.title !== 'pending', null, { timeout: 10000 }).catch(() => {}) + const wasmResp = await page.request.get(`http://127.0.0.1:${port}/pkg/faunosteo_wasm_bg.wasm`) + console.log(`== ${name}: title="${await page.title()}" csp-has-wasm-unsafe-eval=${csp.includes('wasm-unsafe-eval')} wasm-content-type=${wasmResp.headers()['content-type']}`) + for (const l of logs) console.log(' ' + l.slice(0, 220)) + await page.close() +} +await browser.close() diff --git a/docker/csp-proof/run.sh b/docker/csp-proof/run.sh new file mode 100755 index 00000000..70e327b3 --- /dev/null +++ b/docker/csp-proof/run.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# R0 proof (D-R13): the browser module instantiates under the production CSP only with +# 'wasm-unsafe-eval'. Serves packages/core-wasm/pkg through the production nginx image with +# the DEPLOY.md header (as is, then with the keyword) and loads the page in headless Chromium. +# +# pnpm wasm:build +# CHROME=/path/to/chrome bash docker/csp-proof/run.sh # needs playwright-core on NODE_PATH +# +# Recorded result (2026-10-12, Chrome for Testing 156, nginx:1.31-alpine): docs/development/RUST.md §5. +set -euo pipefail +cd "$(dirname "$0")/../.." +work="$(mktemp -d)" +mkdir -p "$work/site" +cp -r packages/core-wasm/pkg "$work/site/" +cp docker/csp-proof/site/index.html docker/csp-proof/site/main.js "$work/site/" +prod_csp="$(grep -m1 '^add_header Content-Security-Policy' DEPLOY.md | sed -E 's/^add_header Content-Security-Policy "(.*)" always;$/\1/')" +wasm_csp="${prod_csp/script-src \'self\'/script-src \'self\' \'wasm-unsafe-eval\'}" +for variant in without with; do + if [ "$variant" = without ]; then csp="$prod_csp"; else csp="$wasm_csp"; fi + sed "s/\${PORT}/8080/; s|^ # SPA fallback| add_header Content-Security-Policy \"$csp\" always;\n # SPA fallback|" docker/nginx.conf > "$work/csp-$variant.conf" +done +cleanup() { docker rm -f faunosteo_csp_without faunosteo_csp_with >/dev/null 2>&1 || true; } +trap cleanup EXIT +cleanup +docker run -d --rm --name faunosteo_csp_without -p 127.0.0.1:8091:8080 -v "$work/site:/usr/share/nginx/html:ro" -v "$work/csp-without.conf:/etc/nginx/conf.d/default.conf:ro" nginx:1.31-alpine >/dev/null +docker run -d --rm --name faunosteo_csp_with -p 127.0.0.1:8092:8080 -v "$work/site:/usr/share/nginx/html:ro" -v "$work/csp-with.conf:/etc/nginx/conf.d/default.conf:ro" nginx:1.31-alpine >/dev/null +sleep 1.5 +node docker/csp-proof/run.mjs diff --git a/docker/csp-proof/site/index.html b/docker/csp-proof/site/index.html new file mode 100644 index 00000000..07b75384 --- /dev/null +++ b/docker/csp-proof/site/index.html @@ -0,0 +1,2 @@ +pending + diff --git a/docker/csp-proof/site/main.js b/docker/csp-proof/site/main.js new file mode 100644 index 00000000..acd9e22b --- /dev/null +++ b/docker/csp-proof/site/main.js @@ -0,0 +1,2 @@ +import init, { core_version } from './pkg/faunosteo_wasm.js' +try { await init(); document.title = 'OK ' + core_version() } catch (e) { document.title = 'FAIL ' + (e && e.message) } diff --git a/docker/rust-builder.Dockerfile b/docker/rust-builder.Dockerfile new file mode 100644 index 00000000..6b49a3cc --- /dev/null +++ b/docker/rust-builder.Dockerfile @@ -0,0 +1,30 @@ +# Faunosteo reference Rust build environment (plan R0, RUST_ARCHITECTURE_REVIEW Annex B, +# amended 2026-10-13). Daily development runs cargo natively on the Ubuntu development +# machine (rustup, docs/development/RUST.md §1); this image is the reproducible +# alternative (`pnpm rust:check:docker`, `pnpm wasm:build:docker`), the reference for a +# future runner, and the proof that the production VPS never needs Rust. +# +# docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker +# bash docker/rust-run.sh cargo test --workspace +# +# The pinned versions below must match rust-toolchain.toml (channel) and Cargo.lock +# (wasm-bindgen crate): scripts/wasm-build.sh refuses to run when they differ. The same +# three tools are installed natively with rustup / cargo install at these versions. +FROM rust:1.99.0-bookworm + +ARG WASM_BINDGEN_VERSION=0.2.129 +ARG CARGO_DENY_VERSION=0.20.2 + +# The wasm target is the browser build of crates/wasm. +RUN rustup target add wasm32-unknown-unknown + +# Build tools compiled from crates.io at pinned versions with their own lockfiles. +RUN cargo install wasm-bindgen-cli --version "${WASM_BINDGEN_VERSION}" --locked \ + && cargo install cargo-deny --version "${CARGO_DENY_VERSION}" --locked \ + && rm -rf /usr/local/cargo/registry + +# The official image installs rustup's minimal profile: without this line every container +# would download rustfmt and clippy again (rust-toolchain.toml lists them as components). +RUN rustup component add rustfmt clippy + +WORKDIR /w diff --git a/docker/rust-run.sh b/docker/rust-run.sh new file mode 100755 index 00000000..4f87d291 --- /dev/null +++ b/docker/rust-run.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Runs a command inside the reference Rust builder image with the repository mounted +# at /w: the reproducible alternative to the native toolchain of the development machine +# (docs/development/RUST.md §1). Cargo's registry and the target directory live in named +# Docker volumes (faunosteo_ prefix, DEPLOY.md "Docker resource naming"), separate from +# the native ./target, so incremental builds stay fast across runs. +# +# bash docker/rust-run.sh cargo test --workspace +# bash docker/rust-run.sh bash scripts/wasm-build.sh # = pnpm wasm:build:docker +set -euo pipefail + +IMAGE="${FAUNOSTEO_RUST_BUILDER:-faunosteo_rust_builder:1.99.0}" +ROOT="$(cd "$(dirname "$0")/.." && pwd)" + +TTY_FLAG=() +if [ -t 0 ] && [ -t 1 ]; then + TTY_FLAG=(-t) +fi + +exec docker run --rm -i "${TTY_FLAG[@]}" \ + -v "$ROOT":/w \ + -v faunosteo_cargo_registry:/usr/local/cargo/registry \ + -v faunosteo_rust_target:/w/target \ + -w /w \ + "$IMAGE" "$@" diff --git a/docs/development/RUST.md b/docs/development/RUST.md new file mode 100644 index 00000000..1cb9137f --- /dev/null +++ b/docs/development/RUST.md @@ -0,0 +1,416 @@ +# 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: native on the development machine, reproducible in Docker, never on the VPS + +Three environments, three roles (owner decision of 2026-10-13, review Annex C +addendum). The development machine is a self-hosted Ubuntu server (native, +not WSL, not the VPS) with Docker rootless. + +| Environment | Role | Rust | +|---|---|---| +| Ubuntu development machine, native | daily development (`cargo check / test / build / clippy / fmt`), the browser module build, every check before a merge (`pnpm check:all`) | user-level `rustup` in `~/.cargo` and `~/.rustup`, channel pinned by `rust-toolchain.toml` | +| Docker on that machine | the Supabase stack, the worker's sandbox tests and seccomp derivation, integration tests, the application and worker images, and the reproducible run of the same Rust scripts through the builder image | inside images only | +| Production VPS | runs images; never compiles | none | + +### 1.1 Native toolchain (the primary path) + +Everything lives in the user's home: no global package, no `sudo`. Checked on +2026-10-13 (Ubuntu 26.04.1, x86_64): `build-essential` (gcc 15, the C +compiler that builds the worker's vendored libwebp), `libc6-dev`, +`pkg-config`, `libssl-dev` and `strace` were already installed; no system +package is missing. + +```bash +# once: rustup, the user-level installer (https://rustup.rs); ~/.bashrc and ~/.profile source ~/.cargo/env +rustup show # from the repository: installs 1.99.0 + rustfmt + clippy +rustup target add wasm32-unknown-unknown # browser build of crates/wasm +cargo install wasm-bindgen-cli --version 0.2.129 --locked # = the wasm-bindgen crate in Cargo.lock +cargo install cargo-deny --version 0.20.2 --locked +``` + +`rustup show` run inside the repository installs the channel of +`rust-toolchain.toml` (rustup auto-install), so `cargo` here is always +1.99.0 whatever the default toolchain of the machine. Non-interactive +shells (editor tasks, git hooks, agent shells) skip `~/.bashrc` and start +without `~/.cargo/bin` on PATH: the scripts source `scripts/rust-env.sh`, +which prepends it when `cargo` is not found. + +| Piece | Native | Builder image | Pinned by | +|---|---|---|---| +| Rust 1.99.0, edition 2024, rustfmt, clippy | `rustup show` (auto-install) | `FROM rust:1.99.0-bookworm` + `rustup component add` | `rust-toolchain.toml` | +| `wasm32-unknown-unknown` | `rustup target add` | `RUN rustup target add` | same channel | +| `wasm-bindgen-cli` 0.2.129 | `cargo install --locked` | same | `wasm-bindgen = "=0.2.129"` in `Cargo.toml`; `scripts/wasm-build.sh` refuses to run when `Cargo.lock` and the CLI on PATH differ | +| `cargo-deny` 0.20.2 | `cargo install --locked` | same | `deny.toml` | +| worker builder (musl, libwebp) | not native: sandbox tests run in Docker only | `crates/worker/Dockerfile` (`FROM rust:1.99.0-alpine3.24`, `build-base`) | same channel | + +Commands (root `package.json`; every Rust script is one file run natively +or inside the builder image): + +```bash +pnpm rust:check # scripts/rust-check.sh, native: fmt --check, clippy -D warnings (all targets), + # cargo test (core, wasm, worker unit tests), ts-rs export, cargo deny licenses/bans/sources +pnpm wasm:build # scripts/wasm-build.sh, native: crates/wasm → packages/core-wasm/pkg (git-ignored), sizes printed +pnpm check:all # scripts/check-all.sh: the pre-merge gate (§4): rust:check, types drift, wasm:build, + # pnpm check, application image, worker:test, worker:image started read-only +pnpm rust:check:docker # the same rust-check.sh inside the builder image (reproducible run) +pnpm wasm:build:docker # the same wasm-build.sh inside the builder image +pnpm rust:builder # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold) +pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, 16 sandbox tests + seccomp derivation +pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static:nonroot) +bash docker/rust-run.sh cargo # any cargo command in the builder +cargo check | test | build | clippy | fmt # the inner loop, from the repository root +``` + +The native `target/` (git-ignored, `.dockerignore`d) and the builder's named +volumes `faunosteo_cargo_registry` / `faunosteo_rust_target` are two +separate caches; neither invalidates the other. + +### 1.2 What stays in Docker, and why + +- The worker's sandbox tests (`crates/worker/tests/sandbox.rs`) are gated by + the `test-hooks` feature: a native `cargo test` compiles that target empty + and runs the worker's unit tests only. The seccomp allowlist is derived by + `strace` on the **musl static binary that ships**, inside the Alpine + `test` stage, and glibc would need other syscalls (`brk`, `mprotect`, + `futex`): running the sandbox natively would either kill a legitimate + decode or prove nothing about the shipped binary. `pnpm worker:test` is + the only path, and the worker keeps running in its container. +- The Supabase stack, the application image, the worker image and the + integration tests on them: `pnpm db:start`, `docker build -t faunosteo .`, + `pnpm worker:image`. +- The builder image stays as the reproducible alternative (same compiler, + same tools, a clean environment) and as the reference a future runner + uses; it is not needed for a compile or a test on the development + machine. + +Exposure change, stated for the record: a native build runs the build +scripts and proc-macros of the dependencies under the user account (the +builder container ran them with the repository mounted read-write, so the +difference is the rest of the home directory). Mitigations in place: +`--locked` everywhere, `deny.toml` `[sources]` limited to crates.io with +unknown registries and git sources denied, `cargo deny check licenses bans +sources` in every check. + +## 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`; disables core dumps (`PR_SET_DUMPABLE 0`, + `RLIMIT_CORE 0`: a dump would hold the uploaded photo); `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, with argument filters: `tkill`/`tgkill` + may only send SIGABRT to the child's own pid (never a signal to the keyed + parent or a sibling), `mmap` may not map `PROT_EXEC`; 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–19, never 1, 101 or a signal number); every decode-time + error maps to a content code (`unsupported_type`, `decode_failed`, + `dimensions`, `resource_limit`), so no upload can produce a broken-environment + code. +- 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}` for the content codes + (`exit_codes::is_content_rejection`, an explicit list), `Broken{code}` when + the child could not run properly (usage, non-empty environment, sandbox + failure, encode or output failure, internal: R1 alerts instead of blaming + the upload; no content can produce it), `Signalled{signal}`, + `OutputOverflow`, `Timeout`, `Failed`). The + parent **never decodes**: `webp_check::inspect` parses the RIFF container + only (chunk allowlist `VP8X`, `VP8 `, `VP8L`, `ALPH`; the encoder's structure + enforced: optional `VP8X` first, optional `ALPH` only in an extended file, + exactly one frame; canvas size from the headers, the frame size must agree + with the canvas; any `EXIF`, `XMP `, `ICCP` or unknown chunk refuses the + output; owner amendment of D-R4). The + child's stderr (≤ 4 KiB) is child-controlled text: R1 never logs it raw + (LRN-044). +- `run --check`: prints the resolved configuration without secrets (which + variables are set, the linked libwebp version, refused below 1.6.0). A + plain `run` does nothing before R1 and says so. +- `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 and `scripts/derive-seccomp.sh` on the **release +profile** with the `test-hooks` feature, so the binary under test differs +from the shipped one by the feature-gated hooks only), `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. Checks before a merge, and the workflow files (prepared, no CI active) + +No CI/CD runs on the forge today (2026-10-13): no runner, no secret, no +registry. The YAML files under `.gitea/workflows/` are kept as prepared +material for that separate decision; a green workflow is never claimed +until one has actually run on the forge. Until then the gate is local: + +```bash +pnpm check:all # scripts/check-all.sh, stops at the first failure +``` + +Stages, in order: `scripts/rust-check.sh` (native), the ts-rs types drift +(`git status --porcelain --untracked-files=all -- packages/core-wasm/types` +must be empty: a modified or a new type file both fail, whatever the git +configuration), `cargo deny check advisories` +(warn-only: out of the blocking path by design, review VIII.3, but printed +here because no nightly job runs yet; needs the network), `scripts/wasm-build.sh` +(native), `pnpm check` (typecheck, tests including the `core-wasm` proofs on +the module just built and the pgTAP suite on PGlite, lint, build), the +application image, `pnpm worker:test` (sandbox tests and seccomp derivation +on the musl binary), `pnpm worker:image` started once with `--read-only +--cap-drop ALL`. The local Supabase stack is not required; `pnpm db:test` +is the real-stack complement after a change under `supabase/`. + +Workflow files, each mapping onto those stages so a future runner calls the +same scripts: + +- `ci.yml` (push on main/develop, pull requests): job `rust` (builder image, + `scripts/rust-check.sh`, types drift, `scripts/wasm-build.sh`), job `check` + (module built the same way, then the Node pipeline), job `docker` + (application image, worker `test` stage, worker runtime started read-only), + job `supabase` (real stack, pgTAP, generated types diff). +- `rust-advisories.yml`: nightly and manual `cargo deny check advisories`, + out of the blocking path on purpose. +- `release-images.yml`: manual only; the dispatch input is a typed choice + re-validated through an environment variable; the RustSec and npm + (`pnpm audit --prod`) advisories gates run first in a job without + secrets; a named ephemeral `buildx` builder (`--builder`, no silent + fallback) with its own cache builds the images; the registry token + reaches the login step only, into a per-job `DOCKER_CONFIG` under + `RUNNER_TEMP` created before any step and removed by a literal path; + digests read from the build metadata; `actions/checkout` pinned to a + commit. The `if: github.ref` line is not a boundary (push access and the + token's scope are; a dedicated release runner label is the Step 27 + operation). It would push `faunosteo_app:` and + `faunosteo_worker:` and print their digests. Deploys nothing + (DEPLOY.md "Image deploy by digest"). + +Target of the future CI/CD step (planned, not yet built; recorded so the +scripts stay compatible): tests on every push and pull request, Rust and +TypeScript checks, PostgreSQL/RLS tests, Docker builds, security checks, +branch verification before a merge, image publication only in an +explicitly authorised workflow. + +Not measured: the forge runner's cache behaviour, cold build times and the +workflow syntax (job-level `env`, `GITHUB_ENV` path) have never run. 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 release-profile musl binary with the test hooks, inside + Docker's default seccomp profile: 16 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; negative + proofs of the argument filters: `--signal-parent` (`tkill` to the parent) + and `--mmap-exec` → SIGSYS; an `iCCP` bomb of 300 MB inflated → a content + rejection, never a broken-environment outcome). +- 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 `