diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index cd26d4a6..7878e824 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -19,7 +19,8 @@ supabase/ │ ├─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks │ ├─ 20261011100000_profiles_professional.sql practice_name, professional_title, siret │ ├─ 20261013100000_files_foundation.sql assets table, seven private buckets, avatar policies through assets, purge queue, browser + worker RPCs (STORAGE.md) -│ └─ 20261025100000_workspaces.sql V1-1.1 (M1): workspaces, workspace_members, personal workspace per account, access helpers, audit correlation cap (§3.3) +│ ├─ 20261025100000_workspaces.sql V1-1.1 (M1): workspaces, workspace_members, personal workspace per account, access helpers, audit correlation cap (§3.3) +│ └─ 20261025110000_clients.sql V1-1.2 (M2): clients, unaccent, client RPCs and search, write budget per workspace, N9 audit filter (§3.4) ├─ seed.sql LOCAL dev accounts + first owner (never run in prod) ├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine` │ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input) @@ -210,10 +211,14 @@ pnpm supabase status # API on the DEV origin, DB on por test ! -f supabase/.temp/project-ref && echo "no linked project" # nothing remote is linked docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}' -# 1. History: M1 must be the only pending migration. -pnpm supabase migration list --local # every row has local = remote, except 20261025100000 (remote empty) -pnpm db:types:check # the diff must be exactly the M1 objects (workspaces, workspace_members, - # workspace_kind, workspace_member_role): anything else = drift, STOP +# 1. History: only the V1-1 migrations may be pending. +pnpm supabase migration list --local # every row has local = remote, except the V1-1 ones (remote empty): + # 20261025100000 (M1) on a checkout of 6bf6978-08abe42, + # 20261025100000 and 20261025110000 (M1, M2) from 4adbfcb on +pnpm db:types:check # the diff must be exactly the objects of those migrations (M1: workspaces, + # workspace_members, workspace_kind, workspace_member_role; M2: clients, + # client_kind, create_client, update_client, set_client_archived, + # search_clients): anything else = drift, STOP # 2. Existing accounts (the backfill creates one workspace per profile). docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A \ @@ -227,14 +232,15 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/dev-before-m1.dump \ | grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected -# 4. Apply M1 without reset (its backfill runs inside the migration). -pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql" +# 4. Apply without reset (M1's backfill runs inside the migration). `migration up` applies every +# pending migration of the checkout, in order: to apply M1 alone, run it from a checkout of 08abe42. +pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql" (then ..._clients.sql) ``` After applying: ```bash -pnpm supabase migration list --local # 20261025100000 now has its remote column +pnpm supabase migration list --local # each applied migration now has its remote column docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A -c " select (select count(*) from public.profiles) || '"'"' profiles, '"'"' || (select count(*) from public.workspaces) || '"'"' workspaces, '"'"' @@ -242,7 +248,7 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h || (select count(*) from public.profiles p where (select count(*) from public.workspaces w where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace'"'"'"' # expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace -pnpm db:test # pgTAP 001-012 (grants, policies, reads); every file runs in +pnpm db:test # pgTAP 001-013 (grants, policies, reads); every file runs in # begin ... rollback: rows unchanged (checked on the sandbox) pnpm db:types:check # no diff pnpm e2e:avatar # avatar flow and worker on the DEV stack (fictitious seed accounts) @@ -251,13 +257,29 @@ pnpm e2e:avatar # avatar flow and worker on the DE Stop and report instead of continuing when: `migration list` shows another pending migration or a remote-only one; `db:types:check` before step 4 shows anything beyond the M1 objects; the dump check misses a line; `migration up` -applies anything else than `20261025100000`; any count after it differs from +applies anything else than the expected V1-1 migrations; any count after it differs from the expectation. The backup restores into a scratch database (rehearsed: every row back; `pg_restore --no-owner` prints privilege errors on Supabase-managed objects, which do not affect the data). Storage file bytes (avatars) live in the storage container's volume, not in the dump; M1 does not touch them. +### 3.4 Clients (V1-1.2, migration M2) + +Contract: `V1-1_OWNERS_ANIMALS.md` §5.1, §8.2, §9, §10. `public.clients` +holds the clients of a workspace; the browser reads them through RLS (members +of the workspace, active profile, confirmed email) and writes them only +through `create_client`, `update_client` and `set_client_archived` (security +definer); `search_clients` (invoker, POST) searches one workspace. Refusals +are closed codes: 42501 `not_found` (also for a foreign id), P0001 +`invalid_input`, `archived`, `conflict`, `request_conflict`, `limit_reached`, +`rate_limited`. Writes are counted per workspace in +`private.workspace_write_budgets` (UTC hour and day). M2 creates the +extension `unaccent` in `extensions` (available on the CLI image and in +PGlite 0.3.16, loaded by the harness). An account whose workspace holds a +client can no longer be deleted (D9a); in DEV, delete its clients first from +a privileged SQL session, or reset. + ## 4. Writing a migration 1. `pnpm supabase migration new ` creates `supabase/migrations/_.sql`. diff --git a/docs/development/TEST_STRATEGY.md b/docs/development/TEST_STRATEGY.md index 7bf1897f..09c0cbc1 100644 --- a/docs/development/TEST_STRATEGY.md +++ b/docs/development/TEST_STRATEGY.md @@ -16,6 +16,11 @@ V1-1.1 (2026-10-25): supabase vitest 44 (config test added), 12 pgTAP files (`012_workspaces.sql`, 85 checks; 531 checks in all), also run on an isolated real stack because the DEV stack stays untouched until the owner applies M1 (`V1-1_OWNERS_ANIMALS.md` §8.1). +V1-1.2 (2026-10-25): supabase vitest 53 (field-limits parity test added), 13 +pgTAP files (`013_clients.sql`, 130 checks; 661 in all); the isolated stack is +a project tool (`pnpm db:sandbox`, SUPABASE.md §5.1) with its own suite under +`packages/supabase/tests/sandbox` (28 real-stack checks: HTTP per role, +concurrency, budget races, 20 000-client search timing). ## 1. Layers diff --git a/docs/development/V1-1_OWNERS_ANIMALS.md b/docs/development/V1-1_OWNERS_ANIMALS.md index 60fcc75f..ae45907f 100644 --- a/docs/development/V1-1_OWNERS_ANIMALS.md +++ b/docs/development/V1-1_OWNERS_ANIMALS.md @@ -6,9 +6,12 @@ BDR-073). The architecture of Parts 4 to 9 and the technical choices N1 to N9 were validated by the owner the same day (brief « Validation du contrat V1-1 et autorisation de V1-1.1 Workspaces », BDR-074, §13.2), with the precisions written into §5.3, §9 and §10. The interface choices of §13.3 stay proposals -until their UI steps. Only step V1-1.1 is authorised: migration M1 is written -and tested on an isolated database (§8.1); it is not applied to Supabase DEV, -and nothing of V1-1.2 to V1-1.6 exists. +until their UI steps. V1-1.1 was validated by the owner on 2026-10-25 (brief +« Validation V1-1.1 et autorisation V1-1.2 Données clients », BDR-075), which +authorised V1-1.2. Migrations M1 (§8.1) and M2 (§8.2) are written and tested +on the isolated stack (`pnpm db:sandbox`, SUPABASE.md §5.1); neither is +applied to Supabase DEV (owner procedure: SUPABASE.md §3.3). Nothing of +V1-1.3 to V1-1.6 exists. Branch: `feature/v1-1-clients-animals`. Roadmap position: `IMPLEMENTATION_PLAN.md` §0; this step is a reduced plan Step 12 that also lays the permission frame of Step 10. The file name keeps "OWNERS" so the documents @@ -526,7 +529,7 @@ differences from the sketch below: §8.1. | Migration | Step | Content | |---|---|---| | M1 `20261025100000_workspaces.sql` (written, V1-1.1) | V1-1.1 | enums `workspace_kind`, `workspace_member_role`; `workspaces`, `workspace_members`; helpers; trigger; backfill function called once; `private.log_event` redefined (same signature) to keep `x-correlation-id` only when it matches `^[A-Za-z0-9-]{1,64}$`, plus a NOT VALID CHECK on `audit_logs.correlation_id`; grants; RLS | -| M2 `_clients.sql` | V1-1.2 | extension `unaccent`; `private.fold_text`; enum `client_kind`; `clients`; write budget helper; client RPCs and searches; grants; RLS | +| M2 `20261025110000_clients.sql` (written, V1-1.2) | V1-1.2 | extension `unaccent`; `private.fold_text`; enum `client_kind`; `clients`; write budget helper; client RPCs and searches; grants; RLS | | M3 `_animals_relations.sql` | V1-1.4 | species rows; enums `animal_sex`, `animal_relation_role`; `animals`, `animal_client_relations`; animal and relation RPCs; grants; RLS | Why the correlation header in M1: `private.log_event` copies that request @@ -755,6 +758,37 @@ workspace along, and the residual admin path of §6.3). The types were generated from that database: the diff with the committed file is exactly the M1 additions. +### 8.2 M2 as built (V1-1.2, 2026-10-25) + +`supabase/migrations/20261025110000_clients.sql`, tested by +`supabase/tests/013_clients.sql` (130 checks), the census of `001_schema.sql`, +the parity test `packages/supabase/tests/db/field-limits.test.ts` and the +sandbox suite `packages/supabase/tests/sandbox/clients.sandbox.ts`. +Differences from the sketch and the plan: + +| Point | Sketch or plan | As built | Why | +|---|---|---|---| +| Replay with other content | not covered | column `create_request_digest` (SHA-256 of the normalised creation content, not granted to any API role); a replay with the same id and another digest is refused `request_conflict` (§9.4), never applied | owner brief §11: a reused request id must not silently accept a divergent operation | +| Text rule in CHECKs | written inline | `private.is_clean_text(value, max)`, immutable, EXECUTE for nobody, used by every text CHECK (M3 reuses it) | one literal for the control ranges | +| Folding | `lower + unaccent` | `lower(unaccent('extensions.unaccent', value) collate "C")`: accents removed, then ASCII lower case only, identical on PGlite and the real image (checked); Cyrillic or Greek capitals keep their case | the database collations differ (C on PGlite, ICU on the image) | +| `search_key` | `concat_ws` | `display_name || ' ' || coalesce(city, '') || ' ' || coalesce(email, '')` | a generated column needs an immutable expression; `concat_ws` is stable | +| Write budget | `require_write_budget(p_actor)`, rolling windows | `private.consume_write_budget(p_workspace_id)` over `private.workspace_write_budgets` (one row per workspace), fixed UTC windows (§10) | owner decision N6 and brief §9: transactional counter per workspace, UTC windows | +| `search_clients` output | with `current_animal_count` | without it | the relations table comes with M3, which recreates the function with the column (return type change) | +| Access layer `clients.ts` | V1-1.2 | moved to V1-1.5, its first consumer, together with the personal workspace read | the brief's V1-1.2 scope lists no access layer; `field-limits.ts` (D-R7) is written now because the parity test needs it | +| Real-stack e2e | `clients-animals.e2e.ts` on the DEV stack | the sandbox suite, on the isolated stack | DEV stays untouched (owner) | + +Search measurement (owner requirement, §8): 20 000 clients in one workspace, +21 POST calls through PostgREST mixing name, city, email and phone terms: +median 9.8 ms, p95 21.4 ms, max 21.9 ms (isolated stack, this host). Under +the 100 ms threshold, so no trigram index is added. + +Residual disclosure found on the real image: a refused direct table access +(`permission denied for table clients`) carries a hint added by the Supabase +image, « Grant the required privileges to the current role with: GRANT +INSERT ON public.clients TO authenticated; ». It names the table, the role +and the privilege, never a value, and the app never sends such a request. +The RPC refusals carry no hint (checked on both engines). + --- ## 9. Policies, helpers and RPCs @@ -765,14 +799,15 @@ M1 additions. |---|---|---|---| | `private.caller_workspace_ids()` | `setof uuid` | the single source of the access rule: workspaces where `auth.uid()` is a member, with an active profile and a confirmed email | `authenticated` (policies evaluate it) | | `private.writable_workspace_ids()` | `setof uuid` | `caller_workspace_ids()` restricted to a write role (V1-1: `holder`) | none (called inside RPCs) | -| `private.require_write_budget(p_workspace_id uuid)` | `void` | raises P0001 `rate_limited` when the workspace has 1 000 audited writes within the past hour or 5 000 within the past day (N6: per workspace); the count and the write are serialised per workspace, never a bare count followed by an unprotected insert; the counter (rows counted by workspace, or a counter row per workspace and window) and its lock are fixed and documented with M2 | none | -| `private.fold_text(p_value text)` | `text` | lower case without accents (`unaccent` with an explicit dictionary), declared immutable for the generated columns | `authenticated` (the invoker search folds the term) | +| `private.consume_write_budget(p_workspace_id uuid)` | `void` | counts one write of the workspace in its UTC hour and day (upsert of its row in `private.workspace_write_budgets`, row lock), raises P0001 `rate_limited` past 1 000 / 5 000 (§10); called last by every write RPC (M2, §8.2) | none | +| `private.is_clean_text(p_value text, p_max integer)` | `boolean` | the text rule of §5 for CHECK constraints (M2) | none | +| `private.fold_text(p_value text)` | `text` | without accents (`unaccent` with an explicit dictionary), then ASCII lower case (collation "C"), declared immutable for the generated columns (§8.2) | `authenticated` (the invoker search folds the term) | | `private.ensure_personal_workspace(p_user_id uuid)` | `boolean` | the single write path: workspace and `holder` membership in one statement, `on conflict do nothing` on `personal_user_id`; true when it created (M1, §8.1) | none | | `private.create_personal_workspace()` | trigger | after insert on `profiles`: calls `ensure_personal_workspace(new.id)` | none | | `private.backfill_personal_workspaces()` | `integer` | same for every profile without a personal workspace; idempotent | none | | `private.check_personal_workspace()` | constraint trigger | deferred to commit: a personal workspace has exactly its account as `holder` (M1, §8.1) | none | -All are `security definer` (except `fold_text`, a pure SQL function), +All are `security definer` (except `fold_text` and `is_clean_text`, pure SQL functions), `set search_path = ''`, `revoke all ... from public, anon, authenticated, service_role` then the grants of the table, and listed in the census of `001_schema.sql`. The write RPCs do not call `private.require_actor()`: its @@ -811,25 +846,37 @@ Write RPCs: `language plpgsql`, `security definer`, volatile, private.writable_workspace_ids())` with its lock, so a caller outside the workspace never takes a lock and never waits on one; no row found raises 42501 `not_found`; -2. calls `private.require_write_budget`; -3. checks, in this order, archived (`archived`), then revision (`conflict`), - then the rules of the table below; +2. checks, in this order, archived (`archived`), then revision (`conflict`), + then the rules of the table below; a replayed create or a call that + changes nothing returns here, uncounted; +3. calls `private.consume_write_budget` (as built in M2: last, after the + checks, so its lock is the last one taken); 4. writes, inside a block that turns `check_violation`, `not_null_violation`, `string_data_right_truncation` and `invalid_text_representation` into `invalid_input`, `unique_violation` on the current-relation index into `duplicate_relation` and `foreign_key_violation` into `not_found`; 5. writes one audit row and returns ids and the new revision only. -Locks: create RPCs of clients and animals lock the workspace row (cap and -insert serialised per workspace); every relation RPC locks the animal row +Locks: create RPCs of clients and animals lock the workspace row `for no +key update` (cap, replay check and insert serialised per workspace, foreign +key checks of other writes not blocked); every relation RPC locks the animal row `for update` then the client row `for share`, in that order; the archive RPCs lock their row `for update`. So caps, « both active » and « animal active » cannot be passed by a concurrent call. The write budget and the 100 000 relations per workspace count rows that writes on different animals or clients can add at the same time: they are counted under a lock that serialises those writes per workspace (owner, N6: never a bare count followed -by an unprotected insert). M2 fixes that lock and the global lock order -(candidate: workspace row, then animal, then client) and documents it here. +by an unprotected insert). As built in M2: the budget row of the workspace +(`private.workspace_write_budgets`) is locked by the upsert of +`private.consume_write_budget`, which every write RPC calls last, after its +entity locks and checks; no lock is taken after it, so no cycle can form. The +lock order of every write RPC is therefore: workspace row (creates), animal +row, client row, budget row. M3 keeps it: a relation create locks the +workspace row first (its 100 000 cap), then the animal, then the client, then +the budget. The budget lock is per workspace: measured on the isolated stack, +a budget row held for 2 s delayed the create of its workspace by 1.75 s while +nine creates in nine other workspaces finished in 8 ms; 60 mixed writes in one +workspace raised no deadlock. Parameters: dates, years and enum values arrive as `text` and are parsed inside the body, so a malformed value (« 2015-02-30 ») is answered `invalid_input` @@ -873,7 +920,7 @@ with POST, so terms and cursors stay out of URLs and access logs. | RPC | Parameters | Returns (one row per record) | Rules | |---|---|---|---| -| `search_clients` | `workspace_id`, `query`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `kind`, `display_name`, `city`, `phone`, `email`, `archived_at`, `name_key`, `current_animal_count` | see below; also serves the client picker of the relation forms | +| `search_clients` | `workspace_id`, `query`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `kind`, `display_name`, `city`, `phone`, `email`, `archived_at`, `name_key`; `current_animal_count` added by M3 (§8.2) | see below; also serves the client picker of the relation forms | | `search_animals` | `workspace_id`, `query`, `species_id`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `name`, `species_id`, `species_detail`, `sex`, `breed`, `birth_year`, `archived_at`, `name_key`, `current_owners`, `current_owner_count` | see below; optional species filter | | `list_client_animals` | `client_id`, `page_size`, `after_sort`, `after_id` | relation and animal columns | a client's relations with their animals, current first then former, each group by animal `name_key`, then `id`; keyset on that order; 50 by default, 100 at most | | `client_archive_preview` | `client_id` | `{count, animals}` | active animals for which this client holds the only current `owner` relation: their count and the first 10 by name | @@ -918,6 +965,7 @@ in FR and EN, like the auth and asset failures: | P0001 `duplicate_relation` | `duplicate_relation` | same current (animal, client, role), including the loser of a race | | P0001 `already_ended` | `already_ended` | ending an ended relation | | P0001 `invalid_input` | `invalid_input` | an RPC rule or a constraint or parse error caught inside the RPC | +| P0001 `request_conflict` | `request_conflict` | a create replayed with a known `create_request_id` but other content (§8.2); the first record is kept unchanged | | anything else | `unavailable` | network, server | pgTAP compares the whole error (SQLSTATE, message, detail, hint) of a foreign id @@ -961,7 +1009,7 @@ migration. | Search term | 0 to 100 characters after trimming | a name or a phone fits; longer is noise | RPC | | Records per workspace | 20 000 clients, 20 000 animals, 100 000 relations | a full-time practitioner sees roughly 1 000 to 2 000 visits a year, so 20 000 animals is more than a decade of distinct animals for one person | RPC, under the workspace or animal row lock | | Relations per animal | 20 current, 200 in total | co-owners, keeper and contacts fit in 20; 200 covers decades of sales; the animal page reads them in one select | RPC | -| Write rate | 1 000 audited writes per workspace per rolling hour and 5 000 per rolling day (owner, N6), counted under a per-workspace lock (§9.3); the counter is fixed with M2 | typing a whole client base by hand stays under 200 an hour; bounds the growth of the append-only audit log and the damage of a stolen session | RPC (`private.require_write_budget`) | +| Write rate | 1 000 audited writes per workspace per UTC hour and 5 000 per UTC day (owner, N6), fixed windows: the hour from hh:00:00 to hh:59:59.999 UTC, the day from 00:00:00 UTC; the first write of a new window restarts its count at 1; the 1 000th write of the hour passes, the 1 001st is refused `rate_limited`. Across an hour boundary up to 2 000 writes can land in 2 minutes; the daily 5 000 still holds. Counted per workspace under the budget row lock (§9.3); a refused write, a replayed create and a call that changes nothing are not counted (the count is rolled back with the refusal) | typing a whole client base by hand stays under 200 an hour; bounds the growth of the append-only audit log and the damage of a stolen session | RPC (`private.consume_write_budget`) | | Audit row size | `correlation_id` kept only when it matches `^[A-Za-z0-9-]{1,64}$`; metadata limited to the workspace id (N9) | the caller no longer chooses the size of an append-only row | M1 (`private.log_event`, CHECK) | | Concurrent writes | optimistic `revision` on every update; locks of §9.3 (workspace row for creates, animal then client row for relations, the row itself for archive); idempotent creates through `create_request_id` | no silent overwrite between two tabs or devices, no cap overshoot, no duplicate on retry | SQL and RPC | | Enumeration | random uuid ids; one 42501 `not_found` for an unknown and a forbidden id in every RPC, with no lock taken outside the caller's workspaces; reads filtered by RLS return empty, never an error that says "exists"; searches limited to one workspace of the caller; closed codes, never values, in errors | | RLS, RPC | @@ -1257,7 +1305,7 @@ validates after V1-1.1 and after the first UI step; nothing merges into | Step | Content | |---|---| | V1-1.1 | Workspaces: M1 (with the correlation header cap), helpers, trigger, backfill, RLS, pgTAP `012`. Written and tested on an isolated stack (§8.1), awaiting the owner's checkpoint; not applied to DEV | -| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, access layer (with the personal workspace read deferred from V1-1.1), real-stack e2e | +| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, sandbox suite. Written and tested on the isolated stack (§8.2), awaiting the owner's checkpoint; not applied to DEV | | V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13) | | V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof | | V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry |