34 KiB
Step 8 — Files foundation and Supabase Storage: technical analysis
Status: proposal for the owner's decision, 2026-10-12. Nothing implemented. Applies the owner's brief of 2026-10-12 (Step 7 closed; hosting = self-hosted Supabase first, managed later; eight private buckets; quarantine + server validation; avatar as first consumer; service role never in the browser).
Part I states the facts the design rests on. Part II is the proposed design. Part III answers the ten security questions of the brief. Part IV lists the exact scope, the tests, the risks and the decisions the owner has to take.
Part I — Facts
I.1 What exists today
| Area | State |
|---|---|
| Storage | One bucket, anatomical-sheet-assets (migration 20261009100000): private, SVG only, 20 MiB cap, content-addressed keys <sha256>.svg, SELECT policy through the sheet (private.can_read_sheet_asset_object), no API write policy, operator upload script with the service key, confirm_sheet_asset_upload RPC (service role). pgTAP 006 (28 checks) runs on the PGlite shim and on the real stack. |
| Storage API | storage-api v1.79.36 in the local stack (same image family as a self-hosted deployment). Signed URLs, signed upload URLs and RLS on storage.objects are available; image transformation needs imgproxy, absent here and a paid add-on on managed. |
| Profiles | avatar_asset_id was deliberately deferred to this step (comment in 20261008100100_profiles.sql). |
| Shell UI | UserBadge (monogram) in the sidebar and the drawer; the top bar holds only the language switch; "Mon compte" = stacked sections, PersonalInfoForm first. The validated mockup shows the avatar with "Modifier la photo" inside the Profil section and an avatar + name in the top bar. |
| SVG sanitiser | packages/pdf/src/svg/sanitize.ts: allowlist of elements and attributes, href / url() kept in-document, backslash refused, caps 20 000 elements / depth 64 / 256 <use> / stdDeviation 100, DOM Level 2 on @xmldom/xmldom, SvgRejectedError. Browser-free. |
| Edge runtime | Disabled in config.toml. BACKEND_ARCHITECTURE.md §6: self-hosted Edge Functions are hand-deployed; first steps lean on SQL. C3: PostgreSQL-backed jobs before a queue. C12: the sanitiser runs between upload and publication, never "on upload". |
| Worker | The plan creates apps/worker at Step 19 (notifications). Files processing needs server-side code before that. |
| Deploy | No backend in production yet. The VPS .env is documented as non-sensitive. CSP: default-src 'self', img-src 'self' data: blob: (a Supabase origin would be blocked for both API calls and images). |
| Tests | pgTAP on PGlite + real stack; app vitest on happy-dom; Step 7 added a headless e2e script against the local stack (scratchpad, Mailpit). |
I.2 Corrections to the plan's Step 8 text
- "RPC
issue_signed_url(asset_id)" cannot exist in SQL: signing needs the Storage API's secret. The Storage API signs a URL only after evaluating the SELECT policy ofstorage.objectsas the caller, so the access check and the signature live in one place already. The design uses it directly. - "Edge Function or SQL-only sanitizer": SQL cannot parse XML or decode images safely; Edge Functions cannot load a native image library and are hand-deployed on self-hosted. A containerised worker is the fit (II.1).
Part II — Proposed design
II.1 Components
Browser (anon key + user JWT)
│ begin_avatar_upload (RPC) ─► assets row pending_upload + quarantine key
│ PUT object (Storage API, INSERT policy = that key, that row, that user)
│ confirm_asset_upload (RPC) ─► status uploaded
│ poll own assets row ─► clean | rejected
│ createSignedUrl(object_key, 3600) (Storage API, SELECT policy) ─► <img>
▼
Supabase (self-hosted compose, later managed)
PostgREST ─ public.assets, RPCs, private helpers Storage API ─ 8 private buckets
▲
│ claim_asset_jobs / complete_asset_job / reject_asset_job (RPC, service role)
│ GET quarantine object, PUT clean object, DELETE quarantine (service role)
apps/worker (container faunosteo_worker, outbound only, no port)
processors: image (sharp) · svg (@faunosteo/pdf allowlist)
sweeper: purge objects of deleted/rejected rows, abandoned uploads, stale jobs
operator commands: reconcile, migrate
Why a worker and not Edge Functions: Edge Functions on the self-hosted stack
run in a separate edge-runtime container, are deployed by hand, cannot
load sharp (native), and the config keeps them off. Why not SQL: no image
decoding, no XML parsing. The worker is one Node 24 container with the
service key in its own env file, no inbound port, the same code against the
local stack, the VPS stack and a managed project (URL + key change only).
It is the apps/worker the plan creates at Step 19; it arrives earlier with
one job family, Step 19 adds its own.
Dependency added: sharp (0.35.x, libvips, prebuilt linuxmusl-x64
package, no install script, Node ≥ 20.9). It decodes JPEG / PNG / WebP,
resizes, re-encodes, and drops metadata by default. The only widely
maintained option that does all four in Node; pure-JS stacks cover PNG only
or are unmaintained.
II.2 Buckets
All eight private (public = false). Created by one migration with
on conflict (id) do update so the migration converges on the local stack,
the VPS and managed alike. file_size_limit and allowed_mime_types on the
bucket are a first filter on what the Storage API accepts, never a proof of
content.
| Bucket | Kind(s) | Owning domain and step | Step 8 state |
|---|---|---|---|
avatars |
profile_avatar | Identity (self) | open: SELECT + INSERT policies through assets |
logos |
organization_logo | Organizations, Step 10 | closed, no policy |
professional-documents |
professional_document | Verification, Step 9 | closed |
client-files |
client_file | Clients, Step 12 | closed |
animal-files |
animal_file | Animals, Step 12 | closed |
report-files |
report_file | PDF artifacts, Step 15 | closed |
anatomical-sheet-assets |
anatomical_sheet_asset | Sheets (existing policy kept) | unchanged |
imports |
import_file | Imports, Step 24 | closed |
"Closed" = the bucket row exists, RLS on storage.objects has no policy
naming it, so anon and authenticated can neither list, read, upload,
update nor delete. Only the service role touches it. A pgTAP census pins
the exact policy count per bucket, so a later step cannot open a bucket by
accident without changing the test.
Open point (D2): the brief names the sheet bucket anatomical-sheets; the
repository already has anatomical-sheet-assets with its policy, its
operator script, its tests and its seed. Recommendation: keep the existing
name and record the deviation; a rename costs a migration, a re-upload and
touches Step 13 for no behaviour.
Proposed caps (closed buckets get the final value at their own step):
| Bucket | Size | Declared types |
|---|---|---|
| avatars | 5 MiB | image/jpeg, image/png, image/webp |
| logos | 2 MiB | image/jpeg, image/png, image/webp |
| professional-documents | 20 MiB | application/pdf, image/jpeg, image/png |
| client-files, animal-files | 20 MiB | pdf + the three image types |
| report-files | 50 MiB | application/pdf |
| anatomical-sheet-assets | 20 MiB (existing) | image/svg+xml |
| imports | 50 MiB | application/pdf, application/json, text/csv |
II.3 public.assets — the authority on every user file
One row per file, created before the bytes exist, kept after they are gone
(status deleted) until the sweeper has purged the object.
create type public.asset_kind as enum (
'profile_avatar', 'organization_logo', 'professional_document',
'client_file', 'animal_file', 'report_file', 'anatomical_sheet_asset', 'import_file');
create type public.asset_status as enum (
'pending_upload', 'uploaded', 'processing', 'clean', 'rejected', 'deleted');
create table public.assets (
id uuid primary key default gen_random_uuid(),
owner_id uuid not null references public.profiles (id) on delete cascade,
kind public.asset_kind not null,
bucket_id text not null, -- derived from kind, checked by trigger
resource_id uuid, -- profile id for avatars
object_key text not null unique, -- final key, server-built
quarantine_key text, -- upload key, null once purged
status public.asset_status not null default 'pending_upload',
declared_mime text not null,
declared_size integer not null check (declared_size between 1 and 52428800),
original_filename text check (char_length(original_filename) <= 120), -- display only
detected_mime text,
byte_size integer,
sha256 text check (sha256 ~ '^[0-9a-f]{64}$'),
width integer,
height integer,
rejection_reason text, -- closed codes, see II.6
attempts smallint not null default 0,
locked_at timestamptz,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
processed_at timestamptz,
deleted_at timestamptz,
purged_at timestamptz -- object removed by the sweeper
);
-- one avatar in flight per account
create unique index assets_one_avatar_in_flight
on public.assets (owner_id) where kind = 'profile_avatar' and status in ('pending_upload','uploaded','processing');
alter table public.profiles add column avatar_asset_id uuid references public.assets (id);
Privileges: revoke all from API roles, grant select to authenticated,
RLS assets_select_own (owner_id = auth.uid()). No INSERT / UPDATE /
DELETE policy: every write is an RPC. profiles.avatar_asset_id is not in
the column grant: only the server sets it, and a trigger checks that it
points to a clean profile_avatar of the same profile.
RPCs (security definer, set search_path = '', authorisation before any
lookup, EXECUTE revoked from PUBLIC, granted per role, audited through
private.log_event where the state is sensitive):
| RPC | Role | Effect |
|---|---|---|
begin_avatar_upload(declared_mime, declared_size, original_filename) |
authenticated | caps (type in list, size ≤ 5 MiB), rate (≤ 10 rows created in the last hour), replaces a stale pending_upload of the same account; inserts the row with object_key = profiles/<uid>/<id>/avatar.webp and quarantine_key = quarantine/<uid>/<id>/upload; returns {asset_id, bucket_id, quarantine_key} |
confirm_asset_upload(asset_id) |
authenticated | own row, pending_upload → checks the object exists at quarantine_key with metadata->>'size' ≤ cap → uploaded |
remove_avatar() |
authenticated | clears profiles.avatar_asset_id, marks the asset deleted; logs asset.avatar_removed |
claim_asset_jobs(limit) |
service_role | uploaded → processing with for update skip locked, locked_at, attempts + 1; returns the rows |
complete_asset_job(asset_id, result) |
service_role | processing → clean with detected fields; for an avatar: sets profiles.avatar_asset_id, marks the previous avatar asset deleted, in the same transaction; logs asset.avatar_set |
reject_asset_job(asset_id, reason) |
service_role | processing → rejected; logs asset.rejected |
reclaim_stale_jobs() |
service_role | processing older than 10 min → uploaded while attempts < 3, else rejected (processing_error) |
list_purgeable_assets() / mark_asset_purged(asset_id) |
service_role | rows whose object must go (deleted, rejected, abandoned pending_upload > 24 h, clean with a quarantine key still present) |
Why assets does not absorb anatomical_sheet_assets: that table is
content-addressed and sheet-scoped (BDR-032/034) with its own confirmed
upload path; merging would rewrite a validated model for no gain. The SVG
processor of the worker will serve it at Step 13 through a
sanitization_status added then.
II.4 Object keys
- Final:
<resource-plural>/<resource-id>/<asset-id>/<canonical-name>. Avatar:profiles/<user_id>/<asset_id>/avatar.webp. The name is fixed per kind; the user's filename never enters a key (it is stored, length-capped and control-character-free, for display only). - Quarantine:
quarantine/<user_id>/<asset_id>/uploadin the same bucket. No API role can read it: the SELECT predicate only matches theobject_keyofcleanrows, the INSERT predicate only thequarantine_keyof the caller'spending_uploadrow. - Keys are built by the RPC from uuids; the policies compare whole strings
(no prefix match, no
storage.foldername()so the PGlite shim and the real stack evaluate the same expression). - Sheet assets keep
<sha256>.svg(shared drawings, immutable versions). Avatars are per-account and mutable: a hash key would need reference counting for nothing.
II.5 Upload, processing, display (avatar)
- Browser pre-checks (feedback only): size ≤ 5 MiB, magic bytes of
JPEG / PNG / WebP, the file decodes (
createImageBitmap). Preview fromURL.createObjectURL, shown in the circle withobject-fit: cover, nothing uploaded yet. - "Enregistrer" →
begin_avatar_upload→ row + keys. storage.from('avatars').upload(quarantine_key, file, { upsert: false })with the user JWT. The INSERT policy onstorage.objectsaccepts only(bucket_id = 'avatars', name = quarantine_key)for apending_uploadrow owned byauth.uid().confirm_asset_upload(asset_id)→uploaded.- Worker loop (every 2 s, backoff to 15 s when idle):
claim_asset_jobs(1)→ download the quarantine object with the service client → processor. - Image processor: detect the type from bytes (JPEG
FF D8 FF, PNG 8-byte signature, WebPRIFF….WEBP); any other →not_an_image.sharp(bytes, { limitInputPixels: 24e6, failOn: 'error', animated: false })→ header check (metadata(): format matches the magic, 64 ≤ sides ≤ 8192) →.rotate()(applies EXIF orientation, then EXIF is dropped) →.resize(512, 512, { fit: 'cover', position: 'centre' })→.webp({ quality: 82 }), nowithMetadata()→ EXIF, XMP, IPTC and ICC are gone. Output: one 512 × 512 WebP, sha256, byte size. - Worker uploads the clean bytes at
object_key(service client), deletes the quarantine object, callscomplete_asset_job(clean + profile pointer + previous avatar markeddeleted, one transaction). On a processor refusal:reject_asset_job(reason)and the quarantine object is deleted. - Browser polls its own
assetsrow (1 s, up to 30 s):clean→ refresh the profile and the signed URL;rejected→ message from the closed reason code; stillprocessingafter 30 s → "toujours en cours" with a retry on next visit. - Display:
createSignedUrl(object_key, 3600)with the user JWT. The Storage API evaluates the SELECT policy, then signs. The URL is cached in the auth store with its expiry and renewed five minutes before. Used as<img src>inUserBadge(sidebar, drawer), the account section and, if the owner approves D3, the top bar.
Why no client-side resize before upload: the server re-encodes anyway and is the boundary; a second pipeline would duplicate the crop rule and could drift. The 5 MiB cap keeps the upload short.
II.6 Rejection codes (closed set, phrased by i18n)
not_an_image, unsupported_type, too_large, decode_failed,
dimensions (too small or too large), svg_rejected, processing_error.
The raw library message never reaches the row nor the screen; it is logged
by the worker with the asset id only.
II.7 SVG processor (anatomical sheets)
Same worker, kind anatomical_sheet_asset: parse with @xmldom/xmldom
(parse errors fatal), sanitizeSvgRoot from @faunosteo/pdf (allowlist +
caps), serialise, 20 MiB cap in and out, refusal → svg_rejected. The
removed element and attribute names are kept in the result (never values).
In Step 8 there is no user producer: uploads into the sheet bucket stay
operator-only until the editor step (17) and the database sheets step (13)
open a signed upload path with sanitization_status on
anatomical_sheet_assets. The processor is tested on hostile fixtures and
through the worker with the service key, so the boundary exists before the
producer does (D6).
II.8 Worker runtime and operations
apps/worker(@faunosteo/worker): TypeScript, Node 24, deps@supabase/supabase-js,sharp,@faunosteo/pdf(sanitiser),@xmldom/xmldom. No DB driver: every database access is an RPC through PostgREST with the service key, so one credential and one transport, and a managed project needs no open database port.- Container
faunosteo_worker(compose serviceworker): non-root,read_only: true+tmpfs /tmp,mem_limit: 512m,pids_limit, no published port,restart: unless-stopped, healthcheck = heartbeat file refreshed each loop. Env file.env.worker(SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,WORKER_ID),chmod 600, separate from the app.envwhich DEPLOY.md keeps non-sensitive. Egress limited to the Supabase host (documented firewall rule). - One job at a time,
sharp.concurrency(1); time is bounded by the input caps (≤ 5 MiB, ≤ 24 MP), not by a kill switch; a crashed run is reclaimed byreclaim_stale_jobs(max 3 attempts). - Sweeper every 10 min: purge objects of
deleted/rejectedrows and of abandoned uploads, remove quarantine leftovers ofcleanrows, markpurged_at. Objects with no row (orphans from a crash between PUT and RPC) are only reported;pnpm worker reconcile --applydeletes them after an operator reads the dry run. - Local dev:
pnpm worker:devagainst the local stack (service key fromsupabase status, typed into the shell as SUPABASE.md §8 already does). - Logging: structured lines, asset id and reason codes only; never bytes, names or user email.
II.9 Orphans on replacement and deletion
| Event | Row state | Object state | Who cleans |
|---|---|---|---|
| New avatar clean | new clean, previous deleted (same transaction) |
previous object still present | sweeper (purge, idempotent) |
remove_avatar() |
deleted, profiles.avatar_asset_id = null |
present until purge | sweeper |
| Upload never confirmed | pending_upload |
maybe present | sweeper after 24 h |
Worker dies after PUT clean, before complete |
processing → reclaimed |
clean object present | retry: upsert: true on the same deterministic key, then complete |
Worker dies after complete, before quarantine DELETE |
clean, quarantine_key set |
quarantine present | sweeper (quarantine leftovers of clean rows) |
| Account deleted (Step 26) | rows cascade | objects orphaned | reconcile; Step 26 will mark then purge before dropping rows |
Access is always cut by the row: a deleted or rejected row matches no
read predicate, whatever the object's fate. The object lifetime is an
eventual-consistency concern handled by the sweeper and verified by
reconcile (lists objects vs rows per bucket, dry run by default).
II.10 Backups and restore on the VPS (self-hosted)
- Storage backend
fileon a named volumefaunosteo_supabase_storage(kept across renames, BDR-035). One VPS, one disk, no extra service. The S3 backend (Scaleway Object Storage) remains available when the volume outgrows the disk or a second host appears: copy the files, change the backend env, rows unchanged. - Backup order: database first (
pg_dumpof the whole instance, thestorageschema included), files second (restic snapshot of the volume to Scaleway Object Storage, encrypted, 7 daily / 4 weekly / 6 monthly). Dumping the rows first guarantees every row in the dump has its file in the snapshot; files newer than the dump are extra and show up inreconcileas orphans. - Restore: stop the worker, restore the database, restore the volume, start
the stack, run
pnpm worker reconcile(dry run), decide on the report. - Runbook delivered by this step (
docs/development/STORAGE.md, pointer in DEPLOY.md); the owner runs it. Claude never runs a backup, restore or transfer tool. A restore drill on the local stack is part of the manual validation.
II.11 Migration to managed Supabase
- Schema: the same migrations (
supabase db push); buckets and policies are SQL and apply on managed. Thestorageschema itself is never dumped into managed:storage.objectsrows are re-created by the uploads. - Objects: operator command
pnpm worker migrate --from <url> --to <url>(two service keys from env), driven byassetsandanatomical_sheet_assets: for everyclean/ confirmed row, download, verify sha256, upload at the same key, verify; report. Thenreconcileon the destination. Everything is verifiable because every object has a row with its hash. - Worker and app: change
SUPABASE_URL/ keys. No code change. - Not used on purpose because managed meters or lacks them: image transformations (imgproxy), Edge Functions, Realtime.
II.12 UI (follows the validated mockup, no redesign)
- Mon compte → Informations personnelles: avatar circle (photo, else the
monogram) with "Modifier la photo" under it, as drawn. Picking a file
shows the local preview in the circle with "Enregistrer la photo" /
"Annuler"; after saving, the circle shows a "Traitement en cours…" state
until the row is
clean; "Supprimer la photo" appears when a photo exists. Errors useaccount.avatar.error.<code>. UserBadge(sidebar + drawer): photo when present, monogram otherwise.- Top bar (D3): the mockup shows avatar + name with a chevron on desktop and the avatar alone on mobile; Step 7 shipped the bar without a user element. Proposal: add the avatar (and the name on desktop) as a link to Mon compte, no dropdown yet (the menu's content is undefined). Decision for the owner.
- Dashboard unchanged (the mockup shows no avatar in the content area).
- Accepted inputs: JPEG, PNG, WebP; never SVG for avatars.
Part III — The ten security questions
- Access control: the
assetsrow is the authority.storage.objectspolicies callprivate.can_read_object(uid, bucket, name)/private.can_upload_object(uid, bucket, name)which look the key up inassets(status, owner, kind) and dispatch per kind to the owning domain's helper. Step 8 implements theprofile_avatarbranch (owner only); every other kind returns false. Buckets without policy are unreachable by API roles. - No cross-user access: the read predicate requires a
cleanrow whoseowner_id = auth.uid()(avatar branch) and whoseobject_keyequals the requested name; keys contain the owner's uuid but the policy never trusts the path, only the row. Listing is denied the same way (SELECT policy). pgTAP: Bob reads nothing of Alice, cannot upload at her key, cannot confirm her row, cannot sign her URL (real-stack e2e). - Keys: server-built from uuids by the RPC
(
profiles/<uid>/<asset>/avatar.webp,quarantine/<uid>/<asset>/upload), canonical file name per kind, user filename never in a key, policies compare whole strings. - Signed URLs: issued by the Storage API after the SELECT policy, with
the user's JWT; TTL per kind in one table (
profile_avatar: 3600 s), cached client-side until five minutes before expiry; nodownloadflag, no transform, no public URL. A signed URL is a bearer token until expiry: accepted for a 512 px avatar, documented; documents (Step 9) get 60 s anddownload. - Quarantine: upload lands under
quarantine/with the row inpending_upload→uploaded; no API role can read it; only the worker (service key) reads it, writes the clean bytes under the final key, deletes the quarantine object. Status machine and every transition are RPCs; the browser cannot setclean. - Dangerous SVG: the existing allowlist sanitiser (elements,
attributes, in-document
href/url(#)only, no backslash, no<script>/<foreignObject>/<image>/ event attributes by construction, caps on elements, depth,<use>, filters, 20 MiB) runs in the worker; refusal =svg_rejected; hostile fixtures (script, foreignObject,on*,javascript:, externaluse, CSSurl(), entity expansion, deep nesting, oversized) are unit tests. Avatars never accept SVG. - Images without metadata: the worker never stores the uploaded
bytes. It decodes (type from magic bytes, header limits, 24 MP pixel cap),
applies the EXIF orientation, resizes and re-encodes to WebP without
withMetadata(): EXIF, XMP, IPTC and ICC are not copied. A test asserts the output of an EXIF-laden JPEG carries noEXIF/XMPchunk and that a rotated portrait comes out upright. - Orphans: replacement and deletion flip the row first (one
transaction), the sweeper removes the object later and marks
purged_at; abandoned uploads expire;reconcilelists objects vs rows and only deletes with--applyafter a dry run (II.9). - Backups and restore: file backend on a named volume, database dump
first then restic snapshot of the volume to Scaleway Object Storage,
restore in the same order followed by
reconcile; runbook inSTORAGE.md, drill on the local stack (II.10). - Managed migration: same migrations, objects copied by an operator command driven by the rows with hash verification, URLs and keys switched by env (II.11).
Service role: only the worker's env file and the operator commands hold
it; env.js is generated from APP_* variables only (unchanged).
Part IV — Scope, tests, risks, decisions
IV.1 Exact scope of the implementation
In:
- Migration
20261012100000_files_foundation.sql: enums,assets, trigger (bucket_idfrom kind, avatar pointer check), seven bucket rows (the existing one untouched),private.can_read_object/private.can_upload_object(avatar branch, closed default),storage.objectsSELECT + INSERT policies foravatars, the eight RPCs of II.3,profiles.avatar_asset_id, explicit EXECUTE revokes. pgTAP010_files_foundation.sql(allowed and denied cases, policy census per bucket), shim extension if a column is missing,database.types.tsregenerated. apps/worker: loop, claim / complete / reject, image processor, SVG processor, sweeper,reconcileandmigratecommands, Dockerfile (node:24-alpine, non-root), compose service,.env.worker.example, vitest on fixtures, an integration test against the local stack run by the CIsupabasejob.packages/supabase/src/assets.ts:beginAvatarUpload,uploadToQuarantine,confirmAssetUpload,removeAvatar,fetchOwnAsset,signedUrlForwith the TTL table; closedAssetFailurekinds.apps/app: avatar block inPersonalInfoForm(picker, preview, save, processing, delete),UserBadgephoto, top bar avatar if D3 = yes, auth store avatar URL cache, i18n keys FR/EN, component and store tests.- Docs:
docs/development/STORAGE.md(model, keys, statuses, worker operations, backup / restore runbook, managed migration), DEPLOY.md (worker service, env file, CSP additions for the Supabase origin), SUPABASE.md (worker in dev), CLAUDE.md, CHANGELOG; plan note on the early worker. - CI: worker typecheck / lint / test / build,
docker buildof the worker image, worker integration test in thesupabasejob.
Out (named so nothing is implied): user SVG upload path and
sanitization_status on sheet assets (Steps 13 / 17), logos, documents,
client / animal / report / import flows (their steps), image
transformations, public profile photo, the production deployment of the
self-hosted stack itself (runbook only), account erasure (Step 26),
Realtime, a user menu dropdown in the top bar.
IV.2 Test scenarios
pgTAP (PGlite + real stack), every case with its denial twin:
- buckets: eight rows, all private, caps and types as the table; policy
census = 2 on
avatars, 1 onanatomical-sheet-assets, 0 elsewhere;authenticatedcannot insert nor select in a closed bucket. begin_avatar_upload: happy path returns keys of the right shape; wrong type, oversize, rate exceeded, anon → denied; a second begin replaces the stale pending row (unique index holds).- upload policy: Alice inserts at her quarantine key; Bob at her key →
42501; Alice at a final key, at a key of a
cleanrow, at an unknown key → denied; no UPDATE / DELETE policy exists. - confirm: own pending row with the object present →
uploaded; without the object → error; Bob confirming Alice's row → denied; confirming twice → error. - read policy: Alice reads her
cleanobject only; nothing whilepending_upload/uploaded/processing/rejected/deleted; the quarantine object is never readable; Bob reads nothing; anon nothing. - worker RPCs:
authenticatedcannot execute any of them; claim locks and increments attempts; complete sets the profile pointer and marks the previous avatardeletedatomically; reject stores a closed code; reclaim after 10 min, rejection after three attempts; purge list contents. - profile pointer trigger: pointing at a
rejectedrow, a foreign row, a non-avatar kind → refused;authenticatedcannot update the column. - audit:
asset.avatar_set,asset.avatar_removed,asset.rejectedrows.
Worker (vitest, fixtures under apps/worker/tests/fixtures):
- image: JPEG / PNG / WebP accepted; PNG bytes with
.jpgname accepted as PNG; GIF, BMP, SVG, PDF, HTML, polyglot (PNG + trailing script), zip bomb PNG (declares 20 000 × 20 000) → rejected with the right code; truncated file →decode_failed; 32 px image →dimensions; EXIF-laden JPEG → no EXIF / XMP / ICC in the output, orientation applied; output is 512 × 512 WebP, deterministic size bounds. - svg: each hostile fixture rejected or rewritten as the sanitiser rules
say; caps enforced; clean draft
horse.svgpasses unchanged. - loop: claim → process → complete call sequence; processor throw → reject; Storage error → row left for reclaim; sweeper purges only listed rows and reports orphans without deleting.
Integration (local stack, CI supabase job): Alice's full flow with the
service key for the worker side → row clean, object at the final key, no
quarantine object, profile pointer set; a second upload replaces and the
first object disappears after the sweep; remove_avatar then sweep →
bucket empty.
Real-stack e2e (scratchpad script, like Step 7): Alice signs her URL (200), Bob signing Alice's key (400 / 403), anon (400), Alice signing her quarantine key (denied), signed URL fetch works then expires.
App (vitest + happy-dom): picker rejects a 6 MiB file and a .jpg that is
a PNG by magic bytes with the phrased error; preview appears before any
request; save calls begin → upload → confirm in order; processing state
then photo on clean; rejection message per code; delete flow; UserBadge
shows the photo when the store has a URL, the monogram otherwise; i18n
parity.
Manual validation (owner): upload, replace, delete from Mon compte on desktop and mobile; photo visible in the sidebar, the drawer and the top bar; copy the signed URL, open it in a private window (works until expiry, then 400); try the object URL without token (400); upload a renamed PNG and an HTML file (refused with a clear message); restore drill on the local stack.
IV.3 Risks
- Decoder vulnerabilities (libvips / libwebp history): the worker is
the only process that decodes untrusted images, runs non-root, read-only,
memory-capped, with no inbound port and egress limited to the Supabase
host;
sharpupdates become a routine chore. Residual risk accepted and documented. - Worker down: uploads stay
uploaded; the UI says "toujours en cours"; nothing is lost; the healthcheck andrestart: unless-stoppedcover the common case; a monitoring hook is Step 27. - Signed URL as bearer: a leaked avatar URL exposes a 512 px picture for at most one hour. Documents will use short TTLs.
- CSP in production:
connect-srcandimg-srcmust include the Supabase origin, or neither the API nor the avatars load. Documented in DEPLOY.md; the owner applies it at deployment. - PGlite shim vs real
storageschema: policies use onlybucket_idandname, no storage helper function, so both engines evaluate the same expression; the real stack'sprotect_deletetrigger forbids direct deletes in tests (LRN-041), writes are asserted by census. - Storage API version drift between the CLI image, the self-hosted compose and managed: signing and RLS semantics are stable since 2023; the integration test on the CI stack catches a regression.
- Service key handling on the VPS: a second env file with
chmod 600; the app.envstays key-free;env.jsnever carries it (test). - Orientation and colour: EXIF orientation is applied before the rotation data is dropped; wide-gamut ICC profiles are dropped, a slight colour shift on rare photos is accepted for an avatar.
- Plan deviation: the worker arrives at Step 8 instead of Step 19; Step 19 extends it rather than creating it. Recorded in the plan.
IV.4 Decisions for the owner
| Id | Question | Recommendation |
|---|---|---|
| D1 | Server-side processing runtime | Containerised worker faunosteo_worker (II.1), no Edge Functions |
| D2 | Sheet bucket name | Keep anatomical-sheet-assets, record the deviation from the announced anatomical-sheets |
| D3 | Top bar avatar | Add avatar (+ name on desktop) as a link to Mon compte, no dropdown; or sidebar / drawer / account only |
| D4 | Avatar output | One 512 × 512 WebP, centre square crop, no metadata; inputs JPEG / PNG / WebP ≤ 5 MiB |
| D5 | Self-hosted Storage backend and backups | File backend on a named volume + restic to Scaleway Object Storage, database dumped first |
| D6 | SVG processor in Step 8 | Yes, in the worker with hostile fixtures, producer at Steps 13 / 17 |
| D7 | Signed URL TTL for avatars | 3600 s, cached client-side |
| D8 | Polling vs Realtime for the processing state | Polling the own row (1 s, 30 s cap); Realtime stays off |