From 2a38fa37b5a9700a3045727ba1098a4b977c5ab5 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 00:01:25 +0200 Subject: [PATCH 01/17] =?UTF-8?q?chore(workspace):=20Rust=20workspace=20R0?= =?UTF-8?q?=20=E2=80=94=20builder=20image,=20core=20crate=20(JS-compatible?= =?UTF-8?q?=20JSON,=20report=20contracts,=20facade),=20wasm=20facade,=20co?= =?UTF-8?q?re-wasm=20package=20with=20proofs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cargo/config.toml | 10 + .dockerignore | 2 + .gitignore | 4 + Cargo.lock | 587 ++++++++++++++++++ Cargo.toml | 56 ++ clippy.toml | 14 + crates/core/Cargo.toml | 24 + crates/core/src/domain/mod.rs | 9 + crates/core/src/domain/report.rs | 137 ++++ crates/core/src/facade.rs | 90 +++ crates/core/src/json.rs | 227 +++++++ crates/core/src/lib.rs | 13 + crates/core/tests/fixtures_round_trip.rs | 39 ++ crates/wasm/Cargo.toml | 19 + crates/wasm/src/lib.rs | 43 ++ deny.toml | 46 ++ docker/rust-builder.Dockerfile | 27 + docker/rust-check.sh | 16 + docker/rust-run.sh | 24 + docker/wasm-build.sh | 26 + package.json | 7 +- packages/core-wasm/eslint.config.js | 21 + packages/core-wasm/package.json | 28 + packages/core-wasm/src/index.ts | 72 +++ packages/core-wasm/tests/facade.test.ts | 56 ++ packages/core-wasm/tests/helpers/core.ts | 13 + packages/core-wasm/tests/panic.test.ts | 52 ++ .../core-wasm/tests/serialisation.test.ts | 115 ++++ packages/core-wasm/tests/size.test.ts | 26 + packages/core-wasm/tsconfig.json | 21 + packages/core-wasm/types/LateralSide.ts | 6 + packages/core-wasm/types/ReportZone.ts | 17 + packages/core-wasm/types/SheetRef.ts | 14 + packages/core-wasm/types/Vertebra.ts | 6 + packages/core-wasm/types/index.ts | 6 + packages/core-wasm/vitest.config.ts | 9 + pnpm-lock.yaml | 24 + rust-toolchain.toml | 6 + rustfmt.toml | 2 + 39 files changed, 1913 insertions(+), 1 deletion(-) create mode 100644 .cargo/config.toml create mode 100644 Cargo.lock create mode 100644 Cargo.toml create mode 100644 clippy.toml create mode 100644 crates/core/Cargo.toml create mode 100644 crates/core/src/domain/mod.rs create mode 100644 crates/core/src/domain/report.rs create mode 100644 crates/core/src/facade.rs create mode 100644 crates/core/src/json.rs create mode 100644 crates/core/src/lib.rs create mode 100644 crates/core/tests/fixtures_round_trip.rs create mode 100644 crates/wasm/Cargo.toml create mode 100644 crates/wasm/src/lib.rs create mode 100644 deny.toml create mode 100644 docker/rust-builder.Dockerfile create mode 100755 docker/rust-check.sh create mode 100755 docker/rust-run.sh create mode 100755 docker/wasm-build.sh create mode 100644 packages/core-wasm/eslint.config.js create mode 100644 packages/core-wasm/package.json create mode 100644 packages/core-wasm/src/index.ts create mode 100644 packages/core-wasm/tests/facade.test.ts create mode 100644 packages/core-wasm/tests/helpers/core.ts create mode 100644 packages/core-wasm/tests/panic.test.ts create mode 100644 packages/core-wasm/tests/serialisation.test.ts create mode 100644 packages/core-wasm/tests/size.test.ts create mode 100644 packages/core-wasm/tsconfig.json create mode 100644 packages/core-wasm/types/LateralSide.ts create mode 100644 packages/core-wasm/types/ReportZone.ts create mode 100644 packages/core-wasm/types/SheetRef.ts create mode 100644 packages/core-wasm/types/Vertebra.ts create mode 100644 packages/core-wasm/types/index.ts create mode 100644 packages/core-wasm/vitest.config.ts create mode 100644 rust-toolchain.toml create mode 100644 rustfmt.toml 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/.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/.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/Cargo.lock b/Cargo.lock new file mode 100644 index 00000000..c6f058b1 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,587 @@ +# 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", + "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..de12b3ce --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,56 @@ +# 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). +# Every command runs through the builder image: docs/development/RUST.md. +[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/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..b1d7ff8c --- /dev/null +++ b/crates/wasm/Cargo.toml @@ -0,0 +1,19 @@ +[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" + +[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..6ffd632f --- /dev/null +++ b/crates/wasm/src/lib.rs @@ -0,0 +1,43 @@ +//! wasm-bindgen facade over `faunosteo-core` (review III.3): JSON strings in and out, closed +//! outcome kinds. Built by `docker/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. +#[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. +#[wasm_bindgen] +pub fn recurse_for_test(depth: u32) -> u32 { + recurse(depth) +} + +#[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/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/rust-builder.Dockerfile b/docker/rust-builder.Dockerfile new file mode 100644 index 00000000..6deeee76 --- /dev/null +++ b/docker/rust-builder.Dockerfile @@ -0,0 +1,27 @@ +# Faunosteo reference Rust build environment (plan R0, RUST_ARCHITECTURE_REVIEW Annex B). +# Every Rust command of the repository runs through this image (CI and local), so the +# toolchain is identical everywhere and 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 --exclude faunosteo-worker +# +# The pinned versions below must match rust-toolchain.toml (channel) and Cargo.lock +# (wasm-bindgen crate): docker/wasm-build.sh refuses to run when they differ. +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-check.sh b/docker/rust-check.sh new file mode 100755 index 00000000..17947834 --- /dev/null +++ b/docker/rust-check.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# The Rust quality gate, identical in CI and locally: `pnpm rust:check`. +# Runs inside the builder image (glibc). The worker's sandbox tests run in its own +# Alpine/musl image (crates/worker/Dockerfile, stage `test`) because the seccomp +# allowlist is derived for the musl static binary that ships. +set -euo pipefail + +cd "$(dirname "$0")/.." + +cargo fmt --all --check +cargo clippy --workspace --all-targets --locked -- -D warnings +cargo test --workspace --exclude faunosteo-worker --locked +# Exports the TypeScript types of the contracts (ts-rs) into packages/core-wasm/types; +# CI fails on a diff so the committed types never drift from the Rust structs. +cargo test -p faunosteo-core --features ts --locked +cargo deny check licenses bans sources diff --git a/docker/rust-run.sh b/docker/rust-run.sh new file mode 100755 index 00000000..f4afe9a8 --- /dev/null +++ b/docker/rust-run.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# Runs a command inside the reference Rust builder image with the repository mounted +# at /w. Cargo's registry and the target directory live in named Docker volumes +# (faunosteo_ prefix, DEPLOY.md "Docker resource naming") so incremental builds stay +# fast across runs while the host needs no Rust toolchain. +# +# bash docker/rust-run.sh cargo test --workspace --exclude faunosteo-worker +# bash docker/rust-run.sh bash docker/wasm-build.sh +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/docker/wasm-build.sh b/docker/wasm-build.sh new file mode 100755 index 00000000..c2f6c840 --- /dev/null +++ b/docker/wasm-build.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Builds the browser module of crates/wasm into packages/core-wasm/pkg (git-ignored). +# Runs inside the builder image: `pnpm wasm:build` or `bash docker/rust-run.sh bash docker/wasm-build.sh`. +# The wasm-bindgen CLI must be the exact version of the wasm-bindgen crate in Cargo.lock +# (wasm-bindgen >= 0.2.128 refuses a mismatch at runtime; we refuse it up front). +set -euo pipefail + +cd "$(dirname "$0")/.." + +lock_version="$(awk '/^name = "wasm-bindgen"$/ { getline; sub(/^version = "/, ""); sub(/"$/, ""); print; exit }' Cargo.lock)" +cli_version="$(wasm-bindgen --version | awk '{ print $2 }')" +if [ "$lock_version" != "$cli_version" ]; then + echo "wasm-bindgen crate ${lock_version} (Cargo.lock) != wasm-bindgen-cli ${cli_version} (builder image)" >&2 + exit 1 +fi + +cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown --locked + +out=packages/core-wasm/pkg +rm -rf "$out" +wasm-bindgen --target web --out-dir "$out" --out-name faunosteo_wasm \ + target/wasm32-unknown-unknown/release/faunosteo_wasm.wasm + +raw=$(wc -c < "$out/faunosteo_wasm_bg.wasm") +gz=$(gzip -9 -c "$out/faunosteo_wasm_bg.wasm" | wc -c) +echo "faunosteo_wasm_bg.wasm: ${raw} bytes raw, ${gz} bytes gzip -9" diff --git a/package.json b/package.json index e8f3f99d..7e6f958a 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,12 @@ "db:types:check": "supabase gen types typescript --local --schema public | prettier --parser typescript | diff - packages/supabase/src/database.types.ts", "assets:upload": "pnpm --filter @faunosteo/supabase assets:upload", "build:preview": "SHEET_BUNDLE=draft pnpm --filter @faunosteo/app build", - "preview:draft": "SHEET_BUNDLE=draft pnpm --filter @faunosteo/app build && pnpm --filter @faunosteo/app preview" + "preview:draft": "SHEET_BUNDLE=draft pnpm --filter @faunosteo/app build && pnpm --filter @faunosteo/app preview", + "rust:builder": "docker build -f docker/rust-builder.Dockerfile -t faunosteo_rust_builder:1.99.0 docker", + "rust:check": "bash docker/rust-run.sh bash docker/rust-check.sh", + "wasm:build": "bash docker/rust-run.sh bash docker/wasm-build.sh", + "worker:test": "docker build -f crates/worker/Dockerfile --target test -t faunosteo_worker:test .", + "worker:image": "docker build -f crates/worker/Dockerfile -t faunosteo_worker:dev ." }, "devDependencies": { "pnpm": "10.13.1", diff --git a/packages/core-wasm/eslint.config.js b/packages/core-wasm/eslint.config.js new file mode 100644 index 00000000..08c2e32f --- /dev/null +++ b/packages/core-wasm/eslint.config.js @@ -0,0 +1,21 @@ +import globals from 'globals' +import tseslint from 'typescript-eslint' + +export default tseslint.config( + // pkg/ is the wasm-bindgen output, types/ the ts-rs output: generated, never linted. + { ignores: ['node_modules/**', 'pkg/**', 'types/**'] }, + { + files: ['**/*.ts'], + extends: [...tseslint.configs.recommended], + languageOptions: { + globals: { ...globals.node, ...globals.es2022 }, + }, + rules: { + '@typescript-eslint/no-explicit-any': 'warn', + '@typescript-eslint/no-unused-vars': [ + 'error', + { argsIgnorePattern: '^_' }, + ], + }, + }, +) diff --git a/packages/core-wasm/package.json b/packages/core-wasm/package.json new file mode 100644 index 00000000..91d05a5a --- /dev/null +++ b/packages/core-wasm/package.json @@ -0,0 +1,28 @@ +{ + "name": "@faunosteo/core-wasm", + "version": "0.1.0", + "private": true, + "description": "Faunosteo core compiled to WebAssembly: loader, generated TypeScript types of the contracts, and the R0 proofs (panic, serialisation, size)", + "license": "MIT", + "type": "module", + "exports": { + ".": "./src/index.ts", + "./types": "./types/index.ts" + }, + "scripts": { + "typecheck": "tsc -p tsconfig.json --noEmit", + "test": "vitest", + "test:run": "vitest run", + "lint": "eslint . --max-warnings 0", + "build": "tsc -p tsconfig.json --noEmit" + }, + "devDependencies": { + "@faunosteo/domain": "workspace:*", + "@types/node": "^20.19.41", + "eslint": "^9.17.0", + "globals": "^15.14.0", + "typescript": "^5.7.2", + "typescript-eslint": "^8.19.0", + "vitest": "^3.2.7" + } +} diff --git a/packages/core-wasm/src/index.ts b/packages/core-wasm/src/index.ts new file mode 100644 index 00000000..bd134e96 --- /dev/null +++ b/packages/core-wasm/src/index.ts @@ -0,0 +1,72 @@ +/** + * Loader of the Faunosteo core module (wasm-bindgen `--target web` output under `pkg/`, + * built by `pnpm wasm:build`, git-ignored). + * + * The module is never imported statically: `pkg/` may be absent on a host without Docker, + * and the application loads the core lazily behind the paths that need it (review III.3). + * No file of this package is reachable from the application before R2. + */ +import { existsSync } from 'node:fs' +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' + +/** The functions the module exports (mirror of `pkg/faunosteo_wasm.d.ts`). */ +export interface CoreModule { + core_version(): string + call(op: string, input: string): string + panic_for_test(): void + recurse_for_test(depth: number): number +} + +/** Outcome envelope of every `call` (closed kinds, never an exception for content). */ +export type CoreOutcome = + | { ok: true; value: T } + | { ok: false; kind: string; detail?: string } + +const PKG_JS = new URL('../pkg/faunosteo_wasm.js', import.meta.url) +const PKG_WASM = new URL('../pkg/faunosteo_wasm_bg.wasm', import.meta.url) + +interface PkgModule extends CoreModule { + default(input: { module_or_path: BufferSource }): Promise +} + +/** True when `pnpm wasm:build` has produced the module. */ +export function isCoreBuilt(): boolean { + return existsSync(fileURLToPath(PKG_WASM)) +} + +let instances = 0 + +/** + * Instantiates a fresh module (Node: bytes from disk). Each call is a new instance. + * + * The wasm-bindgen glue keeps its instance in a module-level variable and the ESM cache + * returns the same module for the same URL, so a second plain `import()` would hand back + * the previous (possibly trapped) instance: R0 proved that an instance is unusable after a + * trap (`memory access out of bounds` in the allocator on the next call). A cache-busting + * query gives a new module record, hence a new instance. The browser loader of R2 must do + * the same (static glue URL imported with a query, or a Worker recreated on trap). + */ +export async function loadCore(): Promise { + instances += 1 + const pkg = (await import( + `${PKG_JS.href}?instance=${instances}` + )) as PkgModule + const bytes = await readFile(PKG_WASM) + await pkg.default({ module_or_path: bytes }) + return pkg +} + +/** Runs one operation and parses its envelope. */ +export function callCore( + core: CoreModule, + op: string, + input: string, +): CoreOutcome { + return JSON.parse(core.call(op, input)) as CoreOutcome +} + +/** Path of the built module on disk (size measurements). */ +export function coreWasmPath(): string { + return fileURLToPath(PKG_WASM) +} diff --git a/packages/core-wasm/tests/facade.test.ts b/packages/core-wasm/tests/facade.test.ts new file mode 100644 index 00000000..271b43a2 --- /dev/null +++ b/packages/core-wasm/tests/facade.test.ts @@ -0,0 +1,56 @@ +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' + +import { callCore, loadCore } from '../src/index' +import { coreBuilt } from './helpers/core' + +const CORE_MANIFEST = new URL( + '../../../crates/core/Cargo.toml', + import.meta.url, +) +const WORKSPACE_MANIFEST = new URL('../../../Cargo.toml', import.meta.url) + +describe.skipIf(!coreBuilt)('core facade (wasm)', () => { + it('reports the workspace version of the core', async () => { + const core = await loadCore() + const workspace = readFileSync(fileURLToPath(WORKSPACE_MANIFEST), 'utf8') + const version = /\[workspace\.package\][^[]*?version = "([^"]+)"/s.exec( + workspace, + )?.[1] + expect(version).toBeDefined() + expect(readFileSync(fileURLToPath(CORE_MANIFEST), 'utf8')).toContain( + 'version.workspace = true', + ) + expect(core.core_version()).toBe(version) + }) + + it('answers with a closed outcome envelope', async () => { + const core = await loadCore() + expect(callCore(core, 'core_version', '')).toEqual({ + ok: true, + value: core.core_version(), + }) + expect(callCore(core, 'nope', '{}')).toMatchObject({ + ok: false, + kind: 'unknown_op', + }) + expect(callCore(core, 'pretty_json', '{ not json')).toMatchObject({ + ok: false, + kind: 'invalid_json', + }) + }) + + it('exposes exactly the documented functions', async () => { + const core = await loadCore() + for (const name of [ + 'core_version', + 'call', + 'panic_for_test', + 'recurse_for_test', + ]) { + expect(typeof (core as unknown as Record)[name]).toBe( + 'function', + ) + } + }) +}) diff --git a/packages/core-wasm/tests/helpers/core.ts b/packages/core-wasm/tests/helpers/core.ts new file mode 100644 index 00000000..4a8d57c2 --- /dev/null +++ b/packages/core-wasm/tests/helpers/core.ts @@ -0,0 +1,13 @@ +import { isCoreBuilt } from '../../src/index' + +/** + * The proofs need the built module. On a host without Docker they are skipped with a + * visible notice instead of failing `pnpm check`; CI always builds the module first. + */ +export const coreBuilt = isCoreBuilt() + +if (!coreBuilt) { + console.warn( + '[core-wasm] pkg/ missing: run `pnpm wasm:build` (Docker builder); proofs skipped', + ) +} diff --git a/packages/core-wasm/tests/panic.test.ts b/packages/core-wasm/tests/panic.test.ts new file mode 100644 index 00000000..113fe2cc --- /dev/null +++ b/packages/core-wasm/tests/panic.test.ts @@ -0,0 +1,52 @@ +/** + * R0 proof: on wasm32 a Rust panic is a trap (`WebAssembly.RuntimeError`), the shadow + * stack overflow is a trap too (no silent corruption), and a trapped instance must never be + * reused: review III.3 rule 5 (poison and re-instantiate) rests on these three facts. + * + * Observed at R0 (Node 24, wasm-bindgen 0.2.129): + * - after a plain panic the same instance still answers calls, which is the dangerous case: + * the shadow stack pointer was never unwound, so later frames run in a shifted stack; + * - after a stack-exhaustion trap the next call on the same instance fails in the allocator + * (`memory access out of bounds`), deterministically; + * - a genuinely new instance (new module record, new memory) recovers in full. + */ +import { loadCore } from '../src/index' +import { coreBuilt } from './helpers/core' + +describe.skipIf(!coreBuilt)('panics and stack exhaustion (wasm)', () => { + it('turns a panic into a WebAssembly.RuntimeError', async () => { + const core = await loadCore() + expect(() => core.panic_for_test()).toThrow(WebAssembly.RuntimeError) + }) + + it('traps on shadow stack exhaustion instead of returning garbage', async () => { + const core = await loadCore() + expect(core.recurse_for_test(100)).toBe(100) + // 2 000 000 frames of at least 128 bytes exceed the 1 MiB shadow stack by far. + expect(() => core.recurse_for_test(2_000_000)).toThrow( + WebAssembly.RuntimeError, + ) + }) + + it('leaves a stack-trapped instance unusable and recovers with a fresh instance', async () => { + const poisoned = await loadCore() + expect(() => poisoned.recurse_for_test(2_000_000)).toThrow( + WebAssembly.RuntimeError, + ) + expect(() => poisoned.core_version()).toThrow(WebAssembly.RuntimeError) + const fresh = await loadCore() + expect(fresh.core_version()).toMatch(/^\d+\.\d+\.\d+$/) + expect(JSON.parse(fresh.call('pretty_json', '[1.0]'))).toEqual({ + ok: true, + value: '[\n 1\n]', + }) + }) + + it('may keep answering after a plain panic, which is why no instance is reused after any trap', async () => { + const poisoned = await loadCore() + expect(() => poisoned.panic_for_test()).toThrow(WebAssembly.RuntimeError) + // Not asserted either way: the instance's stack pointer is undefined from here on. + const fresh = await loadCore() + expect(fresh.core_version()).toMatch(/^\d+\.\d+\.\d+$/) + }) +}) diff --git a/packages/core-wasm/tests/serialisation.test.ts b/packages/core-wasm/tests/serialisation.test.ts new file mode 100644 index 00000000..d04d069d --- /dev/null +++ b/packages/core-wasm/tests/serialisation.test.ts @@ -0,0 +1,115 @@ +/** + * R0 proof: the core's JSON output is byte-identical to `JSON.stringify(v, null, 2)` on the + * real documents, optional fields stay absent and nullable fields stay `null`, and the + * current Zod readers accept what the core writes (review I.2, D-R11). + */ +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' + +import { ReportZoneSchema, SheetRefSchema } from '@faunosteo/domain' + +import type { ReportZone, SheetRef } from '../types/index' +import { callCore, loadCore, type CoreModule } from '../src/index' +import { coreBuilt } from './helpers/core' + +const FIXTURES = [ + 'apps/app/tests/fixtures/report-v3.demo.json', + 'apps/app/tests/fixtures/report-v2.full.json', + 'supabase/seed/anatomical-sheets/equine/draft/document.json', + 'supabase/seed/anatomical-sheets/equine/draft/report-migration-map.json', +] + +const NUMBER_CASES = [ + 1523, 1715.4285714285713, 0.85, 1e21, 1e-7, 0.000001, -0, + 123456789012345680000, 5e-324, 1.7976931348623157e308, 100, -2.5, 0.1, + 1.5e300, 12345678901234567890, +] + +function repoFile(relative: string): string { + return readFileSync( + fileURLToPath(new URL(`../../../${relative}`, import.meta.url)), + 'utf8', + ) +} + +function prettyByCore(core: CoreModule, text: string): string { + const outcome = callCore(core, 'pretty_json', text) + if (!outcome.ok) throw new Error(`${outcome.kind}: ${outcome.detail ?? ''}`) + return outcome.value +} + +describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => { + it.each(FIXTURES)( + '%s: core pretty output equals JSON.stringify(…, null, 2)', + async (relative) => { + const core = await loadCore() + const text = repoFile(relative) + const expected = JSON.stringify(JSON.parse(text), null, 2) + expect(prettyByCore(core, text)).toBe(expected) + }, + ) + + it('prints every number as JavaScript does', async () => { + const core = await loadCore() + const text = JSON.stringify(NUMBER_CASES) + expect(prettyByCore(core, text)).toBe( + JSON.stringify(JSON.parse(text), null, 2), + ) + }) + + it('writes optional fields absent and nullable fields null, readable by the Zod schemas', async () => { + const core = await loadCore() + const bare = callCore( + core, + 'report_zone', + JSON.stringify({ annotationId: 'hip', viewId: 'main' }), + ) + expect(bare).toEqual({ + ok: true, + value: { annotationId: 'hip', viewId: 'main' }, + }) + if (!bare.ok) return + expect(Object.keys(bare.value)).toEqual(['annotationId', 'viewId']) + expect(ReportZoneSchema.parse(bare.value)).toEqual(bare.value) + + const full = callCore( + core, + 'report_zone', + JSON.stringify({ + viewId: 'main', + annotationId: 'hip', + side: 'left', + unresolved: true, + extra: 1, + }), + ) + expect(full).toEqual({ + ok: true, + value: { + annotationId: 'hip', + viewId: 'main', + side: 'left', + unresolved: true, + }, + }) + + const sheet = callCore( + core, + 'sheet_ref', + JSON.stringify({ + sheetId: 'faunosteo-cheval', + versionId: null, + documentSha256: 'a'.repeat(64), + }), + ) + expect(sheet.ok && sheet.value.versionId).toBeNull() + if (sheet.ok) expect(SheetRefSchema.parse(sheet.value)).toEqual(sheet.value) + + const refused = callCore( + core, + 'report_zone', + JSON.stringify({ annotationId: 'a', viewId: 'v', unresolved: false }), + ) + expect(refused).toMatchObject({ ok: false, kind: 'invalid_shape' }) + }) +}) diff --git a/packages/core-wasm/tests/size.test.ts b/packages/core-wasm/tests/size.test.ts new file mode 100644 index 00000000..1dc8671a --- /dev/null +++ b/packages/core-wasm/tests/size.test.ts @@ -0,0 +1,26 @@ +/** + * R0 measurement: served size of the module and instantiate time (D-R13 budget, enforced + * from R2 on the real core; R0 records the skeleton's numbers). + */ +import { readFileSync } from 'node:fs' +import { gzipSync } from 'node:zlib' + +import { coreWasmPath, loadCore } from '../src/index' +import { coreBuilt } from './helpers/core' + +/** D-R13: the served module (compressed) stays under this many bytes. */ +const COMPRESSED_BUDGET_BYTES = 600_000 + +describe.skipIf(!coreBuilt)('module size and instantiate time (wasm)', () => { + it('stays under the compressed budget and reports its numbers', async () => { + const bytes = readFileSync(coreWasmPath()) + const gzip = gzipSync(bytes, { level: 9 }).length + const started = performance.now() + await loadCore() + const instantiateMs = performance.now() - started + console.info( + `[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, instantiate ${instantiateMs.toFixed(1)} ms`, + ) + expect(gzip).toBeLessThanOrEqual(COMPRESSED_BUDGET_BYTES) + }) +}) diff --git a/packages/core-wasm/tsconfig.json b/packages/core-wasm/tsconfig.json new file mode 100644 index 00000000..0faa8e61 --- /dev/null +++ b/packages/core-wasm/tsconfig.json @@ -0,0 +1,21 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022", "DOM"], + "module": "ESNext", + "moduleResolution": "bundler", + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true, + "noImplicitReturns": true, + "skipLibCheck": true, + "esModuleInterop": true, + "resolveJsonModule": true, + "isolatedModules": true, + "types": ["node", "vitest/globals"], + "noEmit": true + }, + "include": ["src", "tests", "types"], + "exclude": ["node_modules", "pkg"] +} diff --git a/packages/core-wasm/types/LateralSide.ts b/packages/core-wasm/types/LateralSide.ts new file mode 100644 index 00000000..fefb9237 --- /dev/null +++ b/packages/core-wasm/types/LateralSide.ts @@ -0,0 +1,6 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * Side of a bilateral zone. + */ +export type LateralSide = "left" | "right"; diff --git a/packages/core-wasm/types/ReportZone.ts b/packages/core-wasm/types/ReportZone.ts new file mode 100644 index 00000000..f0b42b7d --- /dev/null +++ b/packages/core-wasm/types/ReportZone.ts @@ -0,0 +1,17 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. +import type { LateralSide } from "./LateralSide"; +import type { Vertebra } from "./Vertebra"; + +/** + * A zone of an observation. Unknown keys are ignored on input, as the Zod schema strips + * them; optional fields are written only when set. + */ +export type ReportZone = { annotationId: string, viewId: string, side?: LateralSide, vertebrae?: Array, +/** + * Annotation name at selection time (or legacy name at migration). + */ +labelFrSnapshot?: string, labelEnSnapshot?: string, +/** + * Set by the migration when the legacy id has no canonical annotation. + */ +unresolved?: true, }; diff --git a/packages/core-wasm/types/SheetRef.ts b/packages/core-wasm/types/SheetRef.ts new file mode 100644 index 00000000..a1a95cd0 --- /dev/null +++ b/packages/core-wasm/types/SheetRef.ts @@ -0,0 +1,14 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * Reference of the anatomical sheet a report was written against (`Report.sheet`). + */ +export type SheetRef = { sheetId: string, +/** + * Database version id once the sheet lives in the database; `null` for a bundled draft. + */ +versionId: string | null, +/** + * sha256 of the document file the report was written against. + */ +documentSha256: string, }; diff --git a/packages/core-wasm/types/Vertebra.ts b/packages/core-wasm/types/Vertebra.ts new file mode 100644 index 00000000..ee8f0693 --- /dev/null +++ b/packages/core-wasm/types/Vertebra.ts @@ -0,0 +1,6 @@ +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +/** + * One vertebra of a spine zone: the region code and the 1-based index in that region. + */ +export type Vertebra = { region: string, index: number, }; diff --git a/packages/core-wasm/types/index.ts b/packages/core-wasm/types/index.ts new file mode 100644 index 00000000..bcd07fa8 --- /dev/null +++ b/packages/core-wasm/types/index.ts @@ -0,0 +1,6 @@ +// Types of the core contracts, generated by ts-rs from crates/core (`pnpm rust:check` +// regenerates them; CI fails when the committed files drift from the Rust structs). +export type { LateralSide } from './LateralSide' +export type { ReportZone } from './ReportZone' +export type { SheetRef } from './SheetRef' +export type { Vertebra } from './Vertebra' diff --git a/packages/core-wasm/vitest.config.ts b/packages/core-wasm/vitest.config.ts new file mode 100644 index 00000000..f6374039 --- /dev/null +++ b/packages/core-wasm/vitest.config.ts @@ -0,0 +1,9 @@ +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + test: { + environment: 'node', + globals: true, + include: ['tests/**/*.test.ts'], + }, +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8a6927e4..be32feeb 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -146,6 +146,30 @@ importers: specifier: ^3.2.7 version: 3.2.7(@types/node@20.19.41)(happy-dom@20.10.6)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.23.15) + packages/core-wasm: + devDependencies: + '@faunosteo/domain': + specifier: workspace:* + version: link:../domain + '@types/node': + specifier: ^20.19.41 + version: 20.19.41 + eslint: + specifier: ^9.17.0 + version: 9.39.4(jiti@2.7.0) + globals: + specifier: ^15.14.0 + version: 15.15.0 + typescript: + specifier: ^5.7.2 + version: 5.9.3 + typescript-eslint: + specifier: ^8.19.0 + version: 8.59.3(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3) + vitest: + specifier: ^3.2.7 + version: 3.2.7(@types/node@20.19.41)(happy-dom@20.10.6)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.23.15) + packages/domain: dependencies: zod: diff --git a/rust-toolchain.toml b/rust-toolchain.toml new file mode 100644 index 00000000..8f7978b7 --- /dev/null +++ b/rust-toolchain.toml @@ -0,0 +1,6 @@ +# Pinned toolchain, identical to docker/rust-builder.Dockerfile (FROM rust:1.99.0-bookworm) +# and crates/worker/Dockerfile (FROM rust:1.99.0-alpine3.24). Bump the three together. +# The wasm32 target is added by the builder image only (the worker image never needs it). +[toolchain] +channel = "1.99.0" +components = ["rustfmt", "clippy"] diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 00000000..ed49ca7b --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1,2 @@ +edition = "2024" +max_width = 100 From 3970cdca52afe978c581d1250fb08643718bb7c4 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 00:01:26 +0200 Subject: [PATCH 02/17] =?UTF-8?q?feat(worker):=20sandboxed=20decode=20chil?= =?UTF-8?q?d=20skeleton=20=E2=80=94=20rlimits,=20traced=20seccomp=20allowl?= =?UTF-8?q?ist,=20pure-Rust=20decoders,=20libwebp=20in=20the=20child,=20pa?= =?UTF-8?q?rent=20RIFF=20check,=20musl=20image=20with=20test=20stage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- crates/worker/Cargo.toml | 39 ++++ crates/worker/Dockerfile | 37 +++ crates/worker/scripts/derive-seccomp.sh | 41 ++++ crates/worker/src/decode.rs | 286 ++++++++++++++++++++++++ crates/worker/src/exit_codes.rs | 33 +++ crates/worker/src/fixtures.rs | 96 ++++++++ crates/worker/src/lib.rs | 15 ++ crates/worker/src/limits.rs | 26 +++ crates/worker/src/main.rs | 113 ++++++++++ crates/worker/src/sandbox.rs | 200 +++++++++++++++++ crates/worker/src/spawn.rs | 168 ++++++++++++++ crates/worker/src/webp_check.rs | 207 +++++++++++++++++ crates/worker/tests/sandbox.rs | 174 ++++++++++++++ 13 files changed, 1435 insertions(+) create mode 100644 crates/worker/Cargo.toml create mode 100644 crates/worker/Dockerfile create mode 100755 crates/worker/scripts/derive-seccomp.sh create mode 100644 crates/worker/src/decode.rs create mode 100644 crates/worker/src/exit_codes.rs create mode 100644 crates/worker/src/fixtures.rs create mode 100644 crates/worker/src/lib.rs create mode 100644 crates/worker/src/limits.rs create mode 100644 crates/worker/src/main.rs create mode 100644 crates/worker/src/sandbox.rs create mode 100644 crates/worker/src/spawn.rs create mode 100644 crates/worker/src/webp_check.rs create mode 100644 crates/worker/tests/sandbox.rs diff --git a/crates/worker/Cargo.toml b/crates/worker/Cargo.toml new file mode 100644 index 00000000..44c32d35 --- /dev/null +++ b/crates/worker/Cargo.toml @@ -0,0 +1,39 @@ +[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"] + +[dependencies] +image.workspace = true +libwebp-sys.workspace = true +seccompiler.workspace = true +rlimit.workspace = true +libc.workspace = true +crc32fast = { version = "1.4", optional = true } + +# The worker owns I/O (it is the process boundary), so the core's disallowed_methods lint is +# off here; unsafe is allowed for the libwebp FFI only, each block carries a SAFETY comment. +[lints.rust] +unsafe_code = "allow" + +[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..6890654c --- /dev/null +++ b/crates/worker/Dockerfile @@ -0,0 +1,37 @@ +# 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 run against the musl binary that ships, inside the default Docker seccomp +# profile (the inner filter is allowed by it). strace serves the allowlist derivation. +FROM base AS test +RUN apk add --no-cache strace +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 test -p faunosteo-worker --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,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..a1684092 --- /dev/null +++ b/crates/worker/scripts/derive-seccomp.sh @@ -0,0 +1,41 @@ +#!/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/debug/faunosteo-worker +cargo build -p faunosteo-worker --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 prints the marker where the filter would be installed. + env -i strace -f -qq -o "$work/trace.$kind" "$bin" decode --no-seccomp \ + < "$work/$kind.bin" > "$work/$kind.webp" + awk 'found { print } /SECCOMP-MARKER/ { 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" + +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..fab9dedf --- /dev/null +++ b/crates/worker/src/decode.rs @@ -0,0 +1,286 @@ +//! 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, + EncodeFailed, + 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::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) +} + +fn map_image_error(error: ImageError) -> Reject { + match error { + ImageError::Limits(limit) => match limit.kind() { + LimitErrorKind::DimensionError => Reject::Dimensions, + _ => Reject::Internal, + }, + ImageError::Unsupported(_) => Reject::UnsupportedType, + ImageError::Decoding(_) | ImageError::IoError(_) => Reject::DecodeFailed, + _ => Reject::Internal, + } +} + +/// Encodes an RGBA buffer as lossy WebP through libwebp (D-R4: C confined to this process). +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 (Ok(w), Ok(h), Ok(stride)) = ( + c_int::try_from(width), + c_int::try_from(height), + c_int::try_from(width * 4), + ) else { + return Err(Reject::Internal); + }; + let mut output: *mut u8 = std::ptr::null_mut(); + // SAFETY: `rgba` holds exactly width × height × 4 bytes (checked above) with the matching + // stride; libwebp allocates the encoded buffer, writes its address into `output` and + // returns its size. The buffer is copied once and released with the matching WebPFree. + 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: libwebp returned `size` initialised bytes at `output`. + let encoded = unsafe { std::slice::from_raw_parts(output, size) }.to_vec(); + // SAFETY: `output` came from libwebp's allocator and is not read afterwards. + unsafe { libwebp_sys::WebPFree(output.cast()) }; + Ok(encoded) +} + +/// Version of the libwebp linked into this binary, as (major, minor, revision). +pub fn libwebp_version() -> (u8, u8, u8) { + // SAFETY: a pure getter of the FFI without arguments or side effects. + 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, +} + +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), + "--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: syscalls after this line + // are the ones the filter must allow. + 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); + }, + } + } + + #[cfg(not(feature = "test-hooks"))] + fn run_after_sandbox(&self, _stdout: &mut dyn Write, _stderr: &mut dyn Write) -> Option { + None + } +} + +/// 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..fb82a550 --- /dev/null +++ b/crates/worker/src/exit_codes.rs @@ -0,0 +1,33 @@ +//! 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; + +/// 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", + _ => "unknown", + } +} diff --git a/crates/worker/src/fixtures.rs b/crates/worker/src/fixtures.rs new file mode 100644 index 00000000..de6149ca --- /dev/null +++ b/crates/worker/src/fixtures.rs @@ -0,0 +1,96 @@ +//! 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()); +} + +/// 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), + "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..0f52603e --- /dev/null +++ b/crates/worker/src/sandbox.rs @@ -0,0 +1,200 @@ +//! 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, 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()?; + set_rlimits(limits)?; + if seccomp { + install_seccomp()?; + } + Ok(()) +} + +/// 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. +pub fn build_filter() -> Result { + let rules: BTreeMap> = ALLOWED_SYSCALLS + .iter() + .chain(ABORT_PATH_SYSCALLS) + .map(|(_, number)| (*number, Vec::new())) + .collect(); + let filter = SeccompFilter::new( + rules, + SeccompAction::KillProcess, + SeccompAction::Allow, + target_arch()?, + ) + .map_err(|error| SandboxError::Seccomp(error.to_string()))?; + filter + .try_into() + .map_err(|error: seccompiler::BackendError| SandboxError::Seccomp(error.to_string())) +} + +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..0aaf52a3 --- /dev/null +++ b/crates/worker/src/spawn.rs @@ -0,0 +1,168 @@ +//! 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 exit codes. + Rejected { 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. +#[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) => 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) => ChildOutcome::Rejected { + 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..cd0f96c4 --- /dev/null +++ b/crates/worker/src/webp_check.rs @@ -0,0 +1,207 @@ +//! 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::new(); + let mut dimensions = 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)); + } + if dimensions.is_none() { + dimensions = match &fourcc { + b"VP8X" => Some(parse_vp8x(payload)?), + b"VP8 " => Some(parse_vp8(payload)?), + b"VP8L" => Some(parse_vp8l(payload)?), + _ => None, + }; + } + chunks.push(fourcc); + offset = end + (size & 1); + } + let (width, height) = dimensions.ok_or(WebpIssue::MissingBitstream)?; + 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 bytes = riff(&[(b"VP8X", &vp8x(512, 512)), (b"VP8 ", &[0; 20])]); + let summary = expect_square(&bytes, 512); + assert_eq!(summary.map(|s| (s.width, s.height)), Ok((512, 512))); + } + + #[test] + fn metadata_chunks_are_refused() { + let bytes = riff(&[(b"VP8X", &vp8x(512, 512)), (b"EXIF", b"x")]); + assert_eq!(inspect(&bytes), Err(WebpIssue::ForbiddenChunk(*b"EXIF"))); + } + + #[test] + fn wrong_sizes_are_refused() { + let bytes = riff(&[(b"VP8X", &vp8x(511, 512)), (b"VP8 ", &[0; 20])]); + 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(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..3b0ed8ff --- /dev/null +++ b/crates/worker/tests/sandbox.rs @@ -0,0 +1,174 @@ +//! 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 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); +} From 4833fd29ef37954d1b8071a9aa204a6f64f4a7b2 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 00:01:26 +0200 Subject: [PATCH 03/17] ci: rust job through the builder image, worker test stage and runtime start, nightly advisories, manual digest-tagged release-images workflow; CSP proof script --- .gitea/workflows/ci.yml | 28 +++++++++++++++++++- .gitea/workflows/release-images.yml | 38 ++++++++++++++++++++++++++++ .gitea/workflows/rust-advisories.yml | 17 +++++++++++++ docker/csp-proof/run.mjs | 17 +++++++++++++ docker/csp-proof/run.sh | 28 ++++++++++++++++++++ docker/csp-proof/site/index.html | 2 ++ docker/csp-proof/site/main.js | 2 ++ 7 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 .gitea/workflows/release-images.yml create mode 100644 .gitea/workflows/rust-advisories.yml create mode 100644 docker/csp-proof/run.mjs create mode 100755 docker/csp-proof/run.sh create mode 100644 docker/csp-proof/site/index.html create mode 100644 docker/csp-proof/site/main.js diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 2da5724b..ed4b6eaa 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -1,6 +1,10 @@ # 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. +# +# Rust (plan R0, docs/development/RUST.md): every cargo command runs inside the +# reference builder image built from docker/rust-builder.Dockerfile, so CI and a +# developer machine use the same toolchain and the production VPS never needs Rust. name: ci on: @@ -9,8 +13,22 @@ 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 docker/rust-check.sh + - name: Committed TypeScript types match the Rust contracts + run: git diff --exit-code -- packages/core-wasm/types + - name: Browser module builds (size printed; the budget is asserted by the vitest proofs) + run: bash docker/rust-run.sh bash docker/wasm-build.sh + check: runs-on: ubuntu-latest + needs: rust steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 @@ -19,6 +37,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 docker/wasm-build.sh - run: pnpm typecheck - run: pnpm test:run - run: pnpm lint @@ -29,8 +49,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..64b9b8a2 --- /dev/null +++ b/.gitea/workflows/release-images.yml @@ -0,0 +1,38 @@ +# 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 (prepared)" is the runbook. +# +# 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: false + default: 'none' + +jobs: + images: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Registry login + run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login "${{ secrets.REGISTRY }}" -u "${{ secrets.REGISTRY_USER }}" --password-stdin + - name: Build and push the application image + run: | + image="${{ secrets.REGISTRY }}/${{ github.repository_owner }}/faunosteo_app:${{ github.sha }}" + docker build --build-arg SHEET_BUNDLE="${{ github.event.inputs.sheet_bundle }}" -t "$image" . + docker push "$image" + echo "app: $(docker inspect --format='{{index .RepoDigests 0}}' "$image")" >> "$GITHUB_STEP_SUMMARY" + - name: Build and push the worker image + run: | + image="${{ secrets.REGISTRY }}/${{ github.repository_owner }}/faunosteo_worker:${{ github.sha }}" + docker build -f crates/worker/Dockerfile -t "$image" . + docker push "$image" + echo "worker: $(docker inspect --format='{{index .RepoDigests 0}}' "$image")" >> "$GITHUB_STEP_SUMMARY" diff --git a/.gitea/workflows/rust-advisories.yml b/.gitea/workflows/rust-advisories.yml new file mode 100644 index 00000000..52f24c2f --- /dev/null +++ b/.gitea/workflows/rust-advisories.yml @@ -0,0 +1,17 @@ +# 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. +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/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) } From 9d3e0294e28c48569ad7e1427b91073ae1dc7cd5 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 13 Oct 2026 00:01:27 +0200 Subject: [PATCH 04/17] docs(docs): RUST.md with the R0 proofs, DEPLOY image deploy by digest + CSP note, workspace/test strategy/packages/CLAUDE.md, CHANGELOG; chore(memory): TODO R0 --- .claude/tasks/TODO.md | 12 +- CHANGELOG.md | 4 + CLAUDE.md | 20 ++- DEPLOY.md | 65 ++++++++ docs/development/RUST.md | 260 ++++++++++++++++++++++++++++++ docs/development/TEST_STRATEGY.md | 3 + docs/development/WORKSPACE.md | 9 +- packages/README.md | 6 + 8 files changed, 376 insertions(+), 3 deletions(-) create mode 100644 docs/development/RUST.md diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b09f3a57..8958d1b4 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -135,7 +135,17 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [ ] 8.5 docs: STORAGE.md (model, keys, statuses, purge/grace rules, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker, env file, network, CSP connect-src), SUPABASE.md, CLAUDE.md, CHANGELOG, plan note (worker early, SVG processor → Step 13); CI jobs - [ ] 8.6 verify: root check, PGlite + real stack pgTAP, types, docker builds (app + worker), real-stack e2e (sign allowed/denied), gates verifier + security; memory; stop for user validation - [ ] Rust by default (rule adopted 2026-10-12, BDR-043; orientation + 10 principles VALIDATED by the owner 2026-10-12, BDR-044; study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 + Annex A decision table + Annex B R0 scope on chore/step-08-files-analysis; AWAITING the owner's validation of decisions D-R1..D-R14 (D-R6 withdrawn); R0 and Step 8 NOT started until then). Roadmap (each phase: oracles frozen with the old code, consumer-driven deletion, rollback row, gates): - - [ ] R0 foundation (inside Step 8, Annex B): Docker builder image = reference toolchain (rustup optional locally, never on the VPS), Cargo workspace (`crates/core`, `wasm`, `worker` skeletons), toolchain pin, deny.toml, lints, CI job `rust`, worker image started once against the local stack, app wasm stage built but not loaded, `docs/development/RUST.md`, DEPLOY.md (images pulled by digest, CSP `'wasm-unsafe-eval'`, gzip wasm, VPS headroom, rollback = previous digest); 7 experimental proofs kept as tests (wasm panic/re-instantiate, js_number + optional/nullable vs Zod, musl + libwebp build, traced seccomp child, CSP headless, size/instantiate, runner caches) + - [ ] R0 foundation (GO 2026-10-12, BDR-045; branch feature/rust-r0-foundation; Annex B; owner constraints: builds reproducible in Docker, no Rust on the VPS, live deployment untouched, frontend never loads the module, no R1): + - [x] R0.1 toolchain: `docker/rust-builder.Dockerfile` (rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy), `docker/rust-run.sh` (named volumes faunosteo_cargo_registry / faunosteo_rust_target), `docker/rust-check.sh`, `docker/wasm-build.sh` (CLI/crate version lock), root scripts rust:builder / rust:check / wasm:build / worker:test / worker:image + - [x] R0.2 workspace: Cargo.toml (3 members, pinned deps, lints unwrap/expect/disallowed_methods, dev deps optimised), rust-toolchain.toml 1.99.0, rustfmt/clippy/deny config, .cargo/config.toml (wasm stack 1 MiB, TS_RS_EXPORT_DIR), Cargo.lock, .gitignore/.dockerignore (target, pkg) + - [x] R0.3 crates/core: js_number + JsPrettyFormatter (JSON.stringify semantics), report contract types (SheetRef, ReportZone, Vertebra, LateralSide, Unresolved) with optional-absent / nullable-null, facade `call(op, json)` with closed kinds; 12 cargo tests + ts-rs export (4 types committed under packages/core-wasm/types) + - [x] R0.4 crates/wasm: facade (core_version, call, panic_for_test, recurse_for_test); build 224,713 B raw / 85 KB gzip (float_roundtrip on), instantiate ≈ 3 ms in Node + - [x] R0.5 crates/worker: plain main, `decode` child (env check → rlimits AS 512 MiB / CPU 10 s soft, 12 s hard → seccomp allowlist TSYNC kill) → image decode with Limits → orientation → resize_to_fill 512 → libwebp-sys lossy; parent `Spawner` (env_clear, 512 KiB output cap, deadline, signal classification) + `webp_check` (RIFF allowlist, dims, no metadata); `run --check`, `version`; test-hooks (fixtures, violate, flood, alloc, spin, print-allowlist); Dockerfile alpine musl → test stage (sandbox tests + strace derivation) → distroless/static:nonroot + - [x] R0.6 packages/core-wasm: loader (lazy, Node bytes), generated types, vitest proofs (facade, serialisation byte-equal with JSON.stringify on 4 real documents + number cases + Zod readers, panic/stack traps, size budget) skipped with a notice when pkg/ is absent + - [ ] R0.7 proofs recorded with numbers in RUST.md: panic=abort + fresh instance path; float_roundtrip finding; musl static + libwebp ≥ 1.6 build; seccomp allowlist derived by strace and proven on the corpus; CSP with/without 'wasm-unsafe-eval' under the production nginx config (headless Chromium); size/instantiate; runner cache (not measurable here: documented as pending on the forge) + - [ ] R0.8 CI: job `rust` (builder image, fmt/clippy/test/deny, wasm build, types drift), worker test stage + runtime image build in the docker job, nightly advisories, manual `release-images` workflow (digest output, no auto deploy) + - [ ] R0.9 docs: docs/development/RUST.md, DEPLOY.md (prepared: pull by digest, CSP line, gzip wasm, rollback = previous digest; live deployment unchanged), WORKSPACE.md, packages/README.md, CLAUDE.md (stack, map, commands), TEST_STRATEGY.md, CHANGELOG + - [ ] R0.10 gates: `pnpm check` (existing suites untouched), verifier contract, security-auditor; memory (BDR/LRN/EVAL/journal); stop for owner validation, R1 not started - [ ] R1 = Step 8 worker in Rust (replaces 8.2 below): decode child dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist, `image` + `moxcms` + `libwebp-sys` in the child, parent RIFF-header check only, 512 KiB output cap, per-stage deadlines, service key - [ ] R2 domain core (before Step 9): sheet/report/archive contracts, `SheetHandle` + `SheetIndexData`, reducers, Finding builder, vertebra selection, publish gate; wasm facade (JSON strings, ts-rs types, poison + reinstantiate, lazy init); app switched; 3 envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP; `packages/domain` frozen for engine/pipeline - [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first diff --git a/CHANGELOG.md b/CHANGELOG.md index 6583db1f..ef5d35e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added (Rust foundation, plan R0) + +- **Rust by default** (rule adopted 2026-10-12, `docs/development/RUST_ARCHITECTURE_REVIEW.md`): Cargo workspace with three crates, `crates/core` (contracts and the JavaScript-compatible JSON formatter, no I/O by lint), `crates/wasm` (browser facade built into `packages/core-wasm/pkg`) and `crates/worker` (the future file-processing worker: sandboxed `decode` child with rlimits and a seccomp allowlist derived by `strace`, image decoding in pure Rust, lossy WebP through libwebp confined to the child, parent-side container check; `run --check` only, no job loop before R1). Reference toolchain in Docker (`docker/rust-builder.Dockerfile`, `pnpm rust:check`, `pnpm wasm:build`), worker image on `distroless/static`, CI job `rust`, nightly advisories, manual digest-tagged image workflow (no deploy). R0 proofs recorded in `docs/development/RUST.md`: `float_roundtrip` required for JSON parity, traps leave a wasm instance unusable (fresh instance per recovery), CSP needs `'wasm-unsafe-eval'`. No application behaviour, interface, archive or database change; the frontend does not load the module. + ### Added (SaaS migration, plan Step 7) - **Identity (Step 7)** — sign-in and sign-up by email/password (confirmation mandatory, policy 12 chars + lower/upper/digit), password recovery, OAuth buttons (Google, Apple) driven by `APP_AUTH_PROVIDERS`, landing route for confirmation / OAuth links; the guarded `/app` shell (desktop sidebar, light top bar, mobile drawer) with a dashboard (greeting, profile completeness, local tool, account) and **Mon compte** (personal, professional, preferences, security). Profile columns `practice_name`, `professional_title`, `siret` (migration `20261011100000`, pgTAP 009), language synced with `profiles.locale`, platform roles shown read-only. GoTrue TOTP enabled server-side; MFA enforcement for platform roles documented as a gap (`docs/development/IDENTITY.md`). The local tool (`/`, `/new`, `/editor`) stays unauthenticated; the Home header links to the space only when Supabase is configured. diff --git a/CLAUDE.md b/CLAUDE.md index bd05dd49..dbb5f0b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,6 +52,9 @@ MVP species: equine only. Open-source MIT. | DB client | @supabase/supabase-js (packages/supabase) | 2.x | | SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 | | Deploy | Docker multi-stage → nginx:alpine | — | +| Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; every cargo command runs in `docker/rust-builder.Dockerfile` (`pnpm rust:check`, `pnpm wasm:build`), never on the VPS | 1.99.0 | +| WASM glue | wasm-bindgen crate = CLI version (locked in `docker/wasm-build.sh`), `ts-rs` types committed under `packages/core-wasm/types` | 0.2.129 / 12 | +| Worker image | `crates/worker/Dockerfile`: `rust:1.99.0-alpine3.24` (musl, libwebp via `cc`) → `distroless/static:nonroot`; sandbox tests + seccomp derivation in the `test` stage | — | --- @@ -99,6 +102,13 @@ pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview de pnpm preview:draft # same, then serves it pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings) pnpm report:compare ... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md) + +# Rust (docs/development/RUST.md) — all through the builder image, no toolchain on the host +pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0) +pnpm rust:check # fmt --check, clippy -D warnings, cargo test (core, wasm), ts-rs export, cargo deny +pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run +pnpm worker:test # crates/worker/Dockerfile stage test: sandbox tests + seccomp derivation on the musl binary +pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static, `run --check`) ``` ## Docker commands @@ -244,7 +254,14 @@ faunosteo/ │ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql │ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy ├─ packages/README.md ← shared packages index -├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker +├─ packages/core-wasm/ ← @faunosteo/core-wasm: loader of the browser module (pkg/ built, git-ignored), ts-rs types (committed), R0 proofs (panic, serialisation, size) +├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root) +│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced) +│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs) +│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check, `run --check`; Dockerfile, scripts/derive-seccomp.sh +├─ docker/rust-builder.Dockerfile, rust-run.sh, rust-check.sh, wasm-build.sh, csp-proof/ ← reference Rust toolchain + the CSP proof +├─ .gitea/workflows/ci.yml ← CI: rust job (builder image, fmt/clippy/test/deny, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime) +├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy) ├─ .claude/{tasks/TODO.md,memory/,audits/} ├─ Dockerfile, docker-compose.yml, docker/ ├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json @@ -492,6 +509,7 @@ the owner's validation before any implementation; release 0.2.0 unaffected). - Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040). - After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision. - Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install. +- Rust: never on the host or the VPS; `pnpm rust:check` and `pnpm wasm:build` run inside the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed, the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes. - SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test` on the real stack when Docker is available; regenerate types (`pnpm db:types`). diff --git a/DEPLOY.md b/DEPLOY.md index ba9928ed..8015d106 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -21,6 +21,13 @@ The host should publish only ports `22`, `80`, `443` to the internet. The container port (`8080` by default) should stay loopback-only — the host reverse proxy reads from it on `127.0.0.1:8080`. +Rust (plan R0, `docs/development/RUST.md`): the repository also builds a +worker image (`crates/worker/Dockerfile`, static musl binary on +`distroless/static`, container `faunosteo_worker`). It is not deployed yet +(its job loop arrives at R1); the live deployment above is unchanged. The +production VPS never needs a Rust toolchain: images are built in CI and +pulled by digest ("Image deploy by digest", prepared below). + ### Reference sheet in the image (SHEET_BUNDLE) The application needs an anatomical sheet to work. Until sheets are served by @@ -563,6 +570,64 @@ already exported are unaffected. --- +## Image deploy by digest (prepared at R0, not yet applied) + +Decision D-R13 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Annex A and +C): production images are built in CI and the VPS pulls them; it never +compiles the Rust project, and the DEV1-XS memory limit stops mattering for +builds. The procedure below is prepared and documented now; it replaces +"Routine deploys" and "Rollback" above **only when the first image built +this way is deployed, after a separate validation**. Until then the live +deployment keeps building on the VPS as documented above. + +1. Build and publish: run the manual workflow `release-images` + (`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on + push) on the forge. It pushes `faunosteo_app:` and + `faunosteo_worker:` to the container registry named by the + `REGISTRY` secret (the forge's own Gitea registry is the recommended + choice, Scaleway Container Registry the alternative) and prints their + digests in the job summary. No workflow deploys anything. +2. Pin: `docker-compose.yml` on the VPS references the images by digest + (`image: //faunosteo_app@sha256:…`); the digest is the + only thing that changes at a deploy, by hand, after validation. +3. Deploy: `docker compose pull && docker compose up -d` (no `--build`), then + the post-deploy checks of "Routine deploys". +4. Rollback: set the previous digest back in `docker-compose.yml` and run + step 3 again; nothing is rebuilt and nothing needs crates.io or npm. +5. Registry credentials on the VPS: a read-only token in `~/.docker/config.json` + of the deploy user, never in the repository. + +Prerequisites checked at R0 and to re-check before the first digest deploy: +disk headroom on the VPS for two image generations (app ≈ 100 MB, +worker ≈ 9 MB, measured at R0), the registry reachable from the VPS, `docker compose pull` +working with the read-only token. + +### WebAssembly and the CSP (from R2 on) + +The application does not load the Rust core module before plan R2. When it +does, the two `Content-Security-Policy` headers of this file (nginx and +Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`: + +```text +script-src 'self' 'wasm-unsafe-eval'; +``` + +Proven at R0 under the production nginx image and headers with headless +Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in +`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses +to compile the module ("Compiling or instantiating WebAssembly module +violates the following Content Security policy directive"); with the keyword +the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation +only, never `eval` or inline scripts (the proof's inline variant was still +blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16 +(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by +`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains +`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types +application/wasm`) and the served, compressed size is what the D-R13 budget +counts. + +--- + ## Health checks | URL | Expected | diff --git a/docs/development/RUST.md b/docs/development/RUST.md new file mode 100644 index 00000000..9b9b63cd --- /dev/null +++ b/docs/development/RUST.md @@ -0,0 +1,260 @@ +# Rust in the Faunosteo monorepo + +Status: plan R0 (foundation), 2026-10-12, on `feature/rust-r0-foundation`. Rule +and roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III +boundary rules, Part VI phases R0–R5, Annex B R0 scope, Annex C owner +amendments). R0 ships the toolchain, the workspace skeleton, the worker's +sandboxed child, the browser module loader and seven experimental proofs. No +application behaviour, interface, archive or database changes; the frontend +does not load the module before R2; the worker's job loop arrives at R1. + +## 1. Toolchain: reproducible in Docker, never on the VPS + +Every cargo command runs inside the reference builder image, so CI and a +developer machine use the same compiler and the production VPS never needs +Rust (images are built in CI and pulled by digest, DEPLOY.md "Image deploy by +digest"). + +| Piece | Where | Pinned by | +|---|---|---| +| Rust 1.99.0, edition 2024, rustfmt, clippy, `wasm32-unknown-unknown` | `docker/rust-builder.Dockerfile` (`FROM rust:1.99.0-bookworm`) | `rust-toolchain.toml` (same channel; a difference would make rustup download inside the container) | +| `wasm-bindgen-cli` 0.2.129 | same image | `wasm-bindgen = "=0.2.129"` in `Cargo.toml`; `docker/wasm-build.sh` refuses to run when `Cargo.lock` and the CLI differ | +| `cargo-deny` 0.20.2 | same image | `deny.toml` | +| worker builder | `crates/worker/Dockerfile` (`FROM rust:1.99.0-alpine3.24`, `build-base` for libwebp) | same channel | + +Commands (root `package.json`): + +```bash +pnpm rust:builder # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold) +pnpm rust:check # docker/rust-check.sh: fmt --check, clippy -D warnings (all targets), + # cargo test (core, wasm), ts-rs export, cargo deny licenses/bans/sources +pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored), prints raw and gzip sizes +pnpm worker:test # crates/worker/Dockerfile stage test: 13 sandbox tests + seccomp derivation +pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static:nonroot) +bash docker/rust-run.sh cargo # any cargo command in the builder +``` + +`docker/rust-run.sh` mounts the repository at `/w` and keeps Cargo's registry +and the target directory in the named volumes `faunosteo_cargo_registry` and +`faunosteo_rust_target` (incremental builds take seconds). A local `rustup` +is optional for the inner loop (same `rust-toolchain.toml`); the container is +the arbiter. + +## 2. Workspace + +```text +Cargo.toml workspace (resolver 3), pinned [workspace.dependencies], lints, profiles +rust-toolchain.toml channel 1.99.0, components rustfmt + clippy +rustfmt.toml edition 2024, max_width 100 +clippy.toml disallowed-methods: std::time::*::now, std::fs::*, std::env::var* (the core) +deny.toml licences allow-list, bans (duplicates warn, wildcards deny, path deps allowed), sources +.cargo/config.toml wasm shadow stack 1 MiB (explicit), TS_RS_EXPORT_DIR = packages/core-wasm/types +crates/core faunosteo-core: lib, no I/O (lint), serde + serde_json only +crates/wasm faunosteo-wasm: cdylib facade over core (wasm-bindgen) +crates/worker faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit) +packages/core-wasm loader, generated types (committed), vitest proofs +``` + +Lints: `unwrap_used`, `expect_used` and `disallowed_methods` are errors in the +libraries (tests allow them explicitly at the top of the file); `unsafe_code` +is forbidden everywhere except the worker (libwebp FFI, each block with a +`SAFETY` comment). Dependencies are optimised even in debug builds +(`profile.dev.package."*"`) because the sandbox tests decode 4096² images +under a 10 s CPU limit. + +### 2.1 Boundary rules in code (review III.3) + +- `faunosteo_core::facade::call(op, json) -> json`: one operation name, one + JSON text in, the outcome envelope out (`{"ok":true,"value":…}` or + `{"ok":false,"kind":…,"detail":…}`), never a panic on content. R0 ops: + `core_version`, `pretty_json`, `sheet_ref`, `report_zone`. +- `faunosteo_core::json`: `js_number(f64)` prints floats as ECMAScript + `Number::toString`; `JsPrettyFormatter` is `serde_json`'s pretty formatter + with that rule; `to_js_pretty` and `pretty_js_round_trip` produce + `JSON.stringify(v, null, 2)` byte for byte (proof §5.2). +- `faunosteo_core::domain::report`: `SheetRef`, `ReportZone`, `Vertebra`, + `LateralSide`, `Unresolved`, field order of the Zod schemas, optional + fields `skip_serializing_if = "Option::is_none"`, nullable fields plain + `Option`, unknown keys ignored where Zod strips them. `cargo test -p + faunosteo-core --features ts` writes the TypeScript types to + `packages/core-wasm/types` (committed; CI fails on drift). +- `packages/core-wasm/src/index.ts`: `loadCore()` instantiates a **fresh** + module each time (cache-busting import of the glue), `callCore()` parses + the envelope, `isCoreBuilt()` lets the proofs skip when `pkg/` is absent. + +## 3. The worker (R0 skeleton, R1 job loop) + +`faunosteo-worker` is one static musl binary with subcommands dispatched by +a plain `main` (no async runtime, no thread), so `decode` installs its +sandbox in a single-threaded process: + +- `decode`: refuses a non-empty environment; checks `Threads: 1` in + `/proc/self/status`; `RLIMIT_AS` 512 MiB, `RLIMIT_CPU` 10 s soft / 12 s + hard (soft = hard made the kernel SIGKILL first, finding §5.4); seccomp + allowlist installed with TSYNC, `KillProcess` on anything else; then reads + ≤ 5 MiB on stdin, sniffs the format (JPEG, PNG, WebP), decodes with + `image::Limits` (sides ≤ 4096, alloc 256 MiB), applies the EXIF + orientation, `resize_to_fill` 512 × 512, encodes lossy WebP (q 82) through + `libwebp-sys` (C, this process only), writes stdout. Exit codes in + `exit_codes.rs` (10–18, never 1, 101 or a signal number). +- the parent side (`spawn::Spawner`, used by the tests now and by R1): + `env_clear`, stdin/stdout/stderr piped, output read up to 512 KiB (the + child is killed past it), 20 s deadline, classification of every exit + (`Produced`, `Rejected{code}`, `Signalled{signal}`, `OutputOverflow`, + `Timeout`, `Failed`). The parent **never decodes**: `webp_check::inspect` + parses the RIFF container only (chunk allowlist `VP8X`, `VP8 `, `VP8L`, + `ALPH`; canvas size from the headers; any `EXIF`, `XMP `, `ICCP` or unknown + chunk refuses the output; owner amendment of D-R4). +- `run --check`: prints the resolved configuration without secrets (which + variables are set, the linked libwebp version, refused below 1.6.0). A + plain `run` does nothing before R1 and says so. +- `version`: binary, workspace and libwebp versions. +- test hooks (`--features test-hooks`, never in a release build): fixtures + generated in memory (no binary in git), `--no-seccomp` (rlimits only, + prints the `SECCOMP-MARKER` line for the strace derivation), `--violate` + (`getcwd` after the filter), `--flood`, `--alloc-gib n`, `--spin`, + `print-allowlist`. + +Image: `crates/worker/Dockerfile`, stages `build` (release, static), +`test` (sandbox tests + `scripts/derive-seccomp.sh`), `runtime` +(`gcr.io/distroless/static-debian12:nonroot`, `USER nonroot`, `ENTRYPOINT +/faunosteo-worker`, `CMD run --check`). Measured 2026-10-12: image 8.7 MB (one static +binary), `run --check` exits 0 with `--read-only --cap-drop ALL +--security-opt no-new-privileges:true`. + +## 4. CI + +- Job `rust` (before `check`): builds the builder image, runs + `docker/rust-check.sh`, checks the committed ts-rs types for drift, builds + the browser module (size printed). +- Job `check`: builds the module the same way, then the existing Node + pipeline; the `core-wasm` proofs run because `pkg/` exists. +- Job `docker`: application image, worker `test` stage (sandbox tests and + seccomp derivation on the musl binary that ships), worker runtime image + started once with `--read-only --cap-drop ALL`. +- `rust-advisories.yml`: nightly and manual `cargo deny check advisories`, + out of the blocking path on purpose. +- `release-images.yml`: manual only; builds and pushes `faunosteo_app:` + and `faunosteo_worker:` to the registry of the `REGISTRY` secret and + prints their digests. Deploys nothing (DEPLOY.md "Image deploy by digest"). + +Not measured here: the forge runner's cache behaviour and cold build times +(the runner was not available from this host). The builder image build took +about 6 minutes cold on the development host; both image builds reuse +BuildKit cache mounts (`faunosteo_cargo_registry_musl`, +`faunosteo_target_musl`). + +## 5. R0 proofs (2026-10-12, development host, Docker 29.8 rootless, kernel 7.0) + +Each proof is a permanent test; the numbers are what the run produced. + +### 5.1 Panic strategy on wasm32 (`packages/core-wasm/tests/panic.test.ts`) + +- A Rust panic reaches JavaScript as `WebAssembly.RuntimeError` (`unreachable`): + the module is panic = abort, `catch_unwind` cannot be used there. +- Exhausting the 1 MiB shadow stack (2 000 000 frames of 128 bytes) traps + (`RuntimeError`) instead of corrupting memory. +- After a stack-exhaustion trap, the next call on the same instance fails in + the allocator (`memory access out of bounds`, deterministic). After a + plain panic the same instance *still answers*, with a stack pointer that + was never unwound: the dangerous case. Rule for R2: no instance is reused + after any trap; a fresh instance is a new module record (the wasm-bindgen + glue caches its instance in a module variable, and the ESM cache returns + the same module for the same URL: `loadCore()` imports with a cache-busting + query; in the browser the glue must be a static asset imported the same + way, or the core runs in a Worker recreated on trap). + +### 5.2 Serialisation contract (`tests/serialisation.test.ts`, `crates/core/tests`) + +- Byte equality with `JSON.stringify(JSON.parse(text), null, 2)` on + `report-v3.demo.json`, `report-v2.full.json`, the 296 KB equine + `document.json` and the 84 KB `report-migration-map.json`, plus a number + corpus (`1523`, `1715.4285714285713`, `0.85`, `1e+21`, `1e-7`, + `0.000001`, `-0` → `0`, `123456789012345680000`, `5e-324`, + `1.7976931348623157e+308`). +- Finding: `serde_json`'s default float parser is a documented fast path + that can be one ULP off; the first run printed `1715.428571428571` and + `123456789012345670000`. The `float_roundtrip` feature (enabled in + `Cargo.toml`) fixes it; the module grew from 187 KB to 225 KB raw. +- Optional fields absent, nullable fields `null`, unknown keys ignored, + `unresolved: false` refused; the current `ReportZoneSchema` and + `SheetRefSchema` (Zod 3, `@faunosteo/domain`) parse what the core writes. + +### 5.3 musl static binary with libwebp (`crates/worker/Dockerfile`) + +Builds on `rust:1.99.0-alpine3.24` with `build-base`; `libwebp-sys` 0.14.4 +compiles its vendored libwebp with `cc`; `WebPGetEncoderVersion()` reports +**1.6.0** (logged by `run --check`, test +`the_linked_libwebp_is_recent_enough`). The runtime image carries the one +static binary. + +### 5.4 seccomp allowlist, derived and proven (`crates/worker/tests/sandbox.rs`) + +- Derivation (`scripts/derive-seccomp.sh`, strace over png, jpeg, webp, a + 4096 × 4096 JPEG and a 3000 × 3000 PNG, after the marker): exactly + `read write mmap munmap mremap exit_group getrandom`. musl's mallocng used + neither `brk` nor `mprotect`; no `futex` in a single-threaded decode. The + allowlist is that set plus the abort path (`rt_sigaction`, + `rt_sigprocmask`, `getpid`, `gettid`, `tkill`, `tgkill`, `exit`). +- Proven on the musl binary that ships, inside Docker's default seccomp + profile: 13 tests green (`png_jpeg_and_webp_decode_through_the_full_sandbox`, + `inputs_at_the_caps_decode_within_the_limits` (4096²), dimensions 32 px + and 20 000² header, GIF and SVG refused, truncated PNG, non-empty + environment refused, `--violate` → SIGSYS 31, `--flood` → output cut, + `--alloc-gib 2` → SIGABRT 6 under `RLIMIT_AS`, `--spin` → parent deadline, + `--spin` → SIGXCPU 24 at the CPU soft limit, libwebp ≥ 1.6.0). +- Findings: with `RLIMIT_CPU` soft = hard the kernel sends SIGKILL (hard + limit checked first), indistinguishable from the parent's deadline kill; + the soft limit is now two seconds below the hard one. The 4096² decode + exceeded 10 s of CPU in an unoptimised debug build: dependencies are + optimised in every profile. + +### 5.5 CSP with `'wasm-unsafe-eval'` (`docker/csp-proof/run.sh`) + +Served `packages/core-wasm/pkg` through `nginx:1.31-alpine` with +`docker/nginx.conf` plus the exact `Content-Security-Policy` of +`DEPLOY.md`, loaded by headless Chrome for Testing 156: + +| Header | Result | +|---|---| +| production (`script-src 'self'`) | `FAIL WebAssembly.instantiateStreaming(): Compiling or instantiating WebAssembly module violates the following Content Security policy directive because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"` | +| `script-src 'self' 'wasm-unsafe-eval'` | `OK 0.1.0` (module instantiated, `core_version()` answered) | + +The keyword allows WebAssembly compilation only: an inline `