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

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

No files matched your search

+39 -6
View File
@@ -27,7 +27,12 @@ confirmation, password recovery, OAuth buttons driven by config, the guarded
`/app` shell (dashboard, Mon compte with personal / professional / preferences /
security sections) on Supabase Auth + `profiles` + `profile_roles`, language
synced with `profiles.locale` (`docs/development/IDENTITY.md`). The local tool
routes stay unauthenticated.
routes stay unauthenticated. Step 8 (= Rust R1) added the files foundation: the
`assets` table as the authority over user files, seven private buckets (only
`avatars` open, through policies evaluated on `assets`), a quarantine upload path,
the Rust worker `crates/worker` (keyed job loop + keyless sandboxed decode child)
producing 512 × 512 WebP avatars, a deferred purge queue, and the profile photo in
Mon compte, the sidebar, the drawer and the top bar (`docs/development/STORAGE.md`).
MVP species: equine only. Open-source MIT.
---
@@ -112,6 +117,7 @@ pnpm rust:check:docker # the same rust-check.sh inside the builder image
pnpm wasm:build:docker # the same wasm-build.sh inside the builder image
pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, sandbox tests + seccomp derivation on the musl binary
pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static, `run --check`)
pnpm e2e:avatar # scripts/avatar-e2e.sh: worker container against the local stack + packages/supabase/tests/e2e (real-stack avatar flow)
```
## Docker commands
@@ -213,7 +219,8 @@ faunosteo/
│ │ ├─ brand/{Brand,AppHeader,Footer,LanguageSwitcher,HomeSpaceLink}.tsx
│ │ ├─ auth/{AuthLayout,OAuthButtons,PasswordField,UnavailableNotice,AuthLink}.tsx
│ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx
│ │ └─ account/{SectionCard,SaveRow,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx
│ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx
│ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob
│ ├─ pdf/ ← app side of @faunosteo/pdf (engine in packages/pdf)
│ │ ├─ export.ts + import.ts ← exportReportToPdf (sheet snapshot + branding + browser rasterizer → engine), importReportFromPdf (ArchiveReadOutcome, ImportError kinds)
│ │ └─ branding.ts + browserRasterizer.ts ← bundled src/assets/brand logos (?inline / ?raw) → Branding; Image/canvas Rasterizer adapter
@@ -245,11 +252,12 @@ faunosteo/
│ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft
│ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts
├─ packages/supabase/ ← @faunosteo/supabase
│ ├─ src/{index,client,database.types,anatomical-sheets}.ts ← typed client, generated types, publish gate
│ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds)
│ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar`), skipped without the stack env
│ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test
├─ supabase/
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2, profiles_professional, files_foundation (assets, buckets, avatar policies, purge queue, RPCs)
│ ├─ seed/anatomical-sheets/equine/
│ │ ├─ legacy-sources/ ← the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input, never edited)
│ │ ├─ legacy-import/ ← GENERATED baseline: document, id map, IMPORT-REPORT, SVG copies (no SQL)
@@ -261,8 +269,9 @@ faunosteo/
├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root)
│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced)
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs)
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check, `run --check`; Dockerfile, scripts/derive-seccomp.sh
├─ scripts/{rust-env,rust-check,wasm-build,check-all}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`)
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh
├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e
├─ docker-compose.yml ← `app` service; `worker` service under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`)
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proof
├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime)
├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy)
@@ -319,6 +328,15 @@ Identity (Step 7, docs/development/IDENTITY.md)
→ RequireAuth guards /app/* (→ /login?next=), AppLayout (sidebar / top bar / drawer), Dashboard, Account (updateOwnProfile)
→ no Supabase configured: status unavailable, auth screens show a notice, local tool unchanged
Files and avatar (Step 8 / R1, docs/development/STORAGE.md)
→ AvatarSection: pick → avatarTransport (sniff jpeg/png/webp, bitmap → canvas ≤ 1024 → JPEG) → preview (no request)
→ save: rpc begin_avatar_upload (row pending_upload, server-built keys) → storage upload at the quarantine key (INSERT policy)
→ rpc confirm_asset_upload (uploaded) → poll own assets row 1 s ≤ 30 s → clean: download under the SELECT policy → blob URL in authStore
→ worker (container faunosteo_worker, service key): claim_avatar_jobs (lease token) → GET quarantine → decode child (sandbox, 512² WebP)
→ POST clean object (upsert) → complete_avatar_job (previous clean → deleted, enqueued 48 h) → DELETE quarantine → mark_quarantine_purged
→ refusals: reject_avatar_job(closed code); sweeper: expire_pending_uploads, claim_purges/ack_purge, claim_quarantine_leftovers
→ remove_avatar: rows → deleted, objects purged after the grace; a deleted / superseded row never completes (status + token guards)
Runtime config
→ Docker entrypoint writes env.js (window.__APP_CONFIG__)
→ index.html loads env.js before bundle
@@ -415,6 +433,20 @@ Database (Supabase)
operator scripts under `packages/*/scripts/` read it from the environment and are never bundled.
- pgTAP files run on PGlite and on the real image: scope counts to fixture ids, pin `collate "C"` on text ordering.
### Files and Storage (migration 20261013100000, docs/development/STORAGE.md)
- `public.assets` is the authority over every user file: status, owner, keys, lease. Every write is an RPC; the browser
reads its own rows through an explicit column list (`select=*` is refused: lease columns are not granted).
- Object keys are server-built from uuids (`profiles/<owner>/<id>/avatar.webp`, `quarantine/<owner>/<id>/upload`);
policies on `storage.objects` compare whole strings through `assets` and pin one bucket literal each (census test).
A quarantine object is never readable by an API role; a final key is never writable by the browser.
- New buckets stay closed (row only, no policy) until their step writes the rules; `anatomical-sheet-assets` keeps its own policy.
- The worker holds the service key; the decode child has an empty environment, no file, no network, and is the only
process that decodes untrusted bytes. The parent checks the container header only. Rejections are closed codes.
- Deletions are row-driven: terminal rows enqueue their keys (48 h / 1 h grace), the sweeper serves the queue and the
quarantine leftovers; a clean row's object is never deleted. Backups: dump first, files within 48 h.
- Avatar UI follows the validated mockup: photo in Mon compte (Informations personnelles), sidebar, drawer and top bar
link to Mon compte; JPEG / PNG / WebP only, never SVG; no signed URL for the owner-only avatar (download under RLS).
### Anatomical sheet model (packages/domain + migration 20261008110000)
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth: document shape, issue codes, tables, RPCs.
- Ids are stable slugs never derived from labels; labels are `{ fr, en }` objects. Annotation → findings is the
@@ -514,6 +546,7 @@ the owner's validation before any implementation; release 0.2.0 unaffected).
- After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision.
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
- Rust: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes.
- Storage or worker change: `pnpm e2e:avatar` (worker container against the local stack, `packages/supabase/tests/e2e`) in addition to `pnpm worker:test`; `docker compose --profile worker` serves the worker from `.env.worker` (never the app `.env`).
- 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`).