feat(supabase): owner trial sandbox commands and the V1-2.6 trial guide

This commit is contained in:
bchanot committed 2026-11-04 14:11:23 +01:00
1 parent aa5c10d73c
commit ac5fbfbc44
5 files changed
+297 -2

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
import { defineConfig, mergeConfig } from 'vite'
import base from '../vite.config'
/**
* Dev server of `pnpm db:sandbox trial` (docs/development/V1-2-6_OWNER_TRIAL.md).
* The browser talks to this origin only: the three Supabase routes are
* forwarded to the trial gateway on loopback, so no CORS rule is involved.
*/
const target = process.env.FAUNOSTEO_TRIAL_GATEWAY
if (!target || new URL(target).hostname !== '127.0.0.1')
throw new Error('FAUNOSTEO_TRIAL_GATEWAY must be an http://127.0.0.1:<port> URL')
const SUPABASE_ROUTES = ['/auth/v1', '/rest/v1', '/storage/v1']
export default defineConfig((env) =>
mergeConfig(base(env), {
server: {
proxy: Object.fromEntries(
SUPABASE_ROUTES.map((route) => [route, { target }]),
),
},
}),
)
+4
View File
@@ -170,3 +170,7 @@ comes with them), read every visible string from `@/i18n/{fr,en}`, use
fictitious values only, and pass the values a test creates to
`requests.forbid(...)`. A new backend origin goes into the suite's
`allowedOrigins`, never into a wildcard.
## Owner trial (V1-2.6)
`pnpm db:sandbox trial` serves the app on `127.0.0.1:5193` (Vite config `apps/app/vite/trial.config.ts`, proxy to a trial gateway on `127.0.0.1:57801`) for manual testing in the owner's browser, not a test suite. Ports 5193 and 57801 must be free. Guide: `docs/development/V1-2-6_OWNER_TRIAL.md`.
+1
View File
@@ -805,6 +805,7 @@ Docker.
| `pnpm db:sandbox e2e-shell` (= `pnpm e2e:shell`) | the authenticated `/app` shell in Chromium (`apps/app/e2e/shell`, `docs/development/BROWSER_TESTS.md`): a loopback dev server whose Supabase calls are replayed on the sandbox, fictitious accounts per test |
| `pnpm db:sandbox verify-e2e` | V1-2.3: a gateway (`nginx:1.31-alpine`, sandbox network only, no host port) and the real verification worker `faunosteo_worker:dev run --jobs sheet-verify` against the sandbox, then `packages/supabase/tests/sandbox/sheet-verification.sandbox.ts`; both containers removed at the end, the service key passed through a 600 file deleted at start |
| `pnpm db:sandbox avatar-e2e` | V1-2.3: the same gateway, published on `127.0.0.1:57800` only and routing `/auth/v1/` too, the real worker `faunosteo_worker:dev run` (default mode: avatars and sweep, 5 s sweep, no quarantine grace, 512 MiB as the compose `worker`) against the sandbox, then `packages/supabase/tests/e2e/avatar-flow.e2e.ts` through that port; the suite's psql calls go to the sandbox database container, which it requires by name; its two accounts are made per run with random passwords and deleted after; both containers removed at the end |
| `pnpm db:sandbox trial` / `trial-account <email>` / `trial-grant <email> <kind>` | V1-2.6 owner trial (`docs/development/V1-2-6_OWNER_TRIAL.md`): the app on `127.0.0.1:5193` behind a trial gateway on `127.0.0.1:57801` (refuses to start when `faunosteo_dbsandbox_trial_gateway` exists), a confirmed account (hidden password prompt), a catalogue right (email and kind checked, passed as psql variables; editor and publisher also get the admin role) |
| `pnpm db:sandbox sql` / `down` | psql as postgres on stdin / remove the stack |
Every CLI call passes `--db-url` with `sslmode=disable` (the sandbox has no
+168
View File
@@ -0,0 +1,168 @@
# V1-2.6 : essai par le propriétaire de l'éditeur de fiche
Ce guide permet de tester l'éditeur de brouillon (niveau 1) dans votre navigateur, avant la validation
fonctionnelle, sur une pile Supabase jetable. Rien ne touche DEV : les conteneurs `supabase_*_faunosteo`
ne sont ni lus ni arrêtés, la base de l'essai est `faunosteo_dbsandbox_*` et disparaît avec `down`.
Toutes les commandes se lancent à la racine du dépôt (`/home/bchanot/Documents/faunosteo-v1-2`), une
commande `pnpm db:sandbox` à la fois. Prérequis : Docker, `pnpm install` fait, une application
d'authentification TOTP (téléphone ou gestionnaire de mots de passe) pour l'étape 3, et un écran d'au moins
1 024 px de large (en dessous l'éditeur est en lecture seule).
## 1. Démarrer la pile jetable
```bash
pnpm db:sandbox up fresh
```
Attendu : une dizaine de secondes, puis `== sandbox up (fresh): …`.
## 2. Créer votre compte et ses droits
```bash
pnpm db:sandbox trial-account vous@example.com
```
Un mot de passe est demandé deux fois, sans écho (12 caractères au moins). Il n'est ni affiché ni enregistré.
Attendu : `== account created and confirmed: vous@example.com`. Le compte est déjà confirmé : aucun e-mail à lire.
```bash
pnpm db:sandbox trial-grant vous@example.com sheet_editor
pnpm db:sandbox trial-grant vous@example.com sheet_publisher
```
Attendu : `== sheet_editor granted to vous@example.com`, puis la même ligne pour `sheet_publisher`. Le droit
`sheet_editor` donne aussi le rôle d'administrateur (requis par l'éditeur). Relancer une commande est sans effet.
Un e-mail inconnu s'arrête sur `no rows returned for \gset`. Les droits possibles : `catalog_reader`,
`sheet_editor`, `sheet_reviewer`, `sheet_publisher`.
## 3. Lancer l'application d'essai
Dans un terminal que vous laissez ouvert :
```bash
pnpm db:sandbox trial
```
Attendu : `== trial: http://127.0.0.1:5193`, puis les lignes de Vite. L'application est servie sur
`http://127.0.0.1:5193` et la même adresse relaie `/auth/v1`, `/rest/v1` et `/storage/v1` vers une passerelle
de l'essai, publiée sur `127.0.0.1:57801` uniquement : le navigateur ne parle qu'à une seule origine. La
commande refuse de démarrer si la passerelle de l'essai existe déjà ou si l'un des ports est pris.
Ouvrez `http://127.0.0.1:5193/login` et connectez-vous avec le compte de l'étape 2. Le site n'est joignable que
depuis cette machine (pas depuis un téléphone du réseau local).
### Double authentification (TOTP)
L'administration exige une session renforcée (`aal2`).
1. Menu « Mon compte », section « Sécurité », bouton « Ajouter un facteur ».
2. Nom du facteur (par exemple « Essai »), « Continuer ».
3. Scannez le QR code avec l'application d'authentification (sinon recopiez la « Clé de configuration manuelle »,
affichée une seule fois), saisissez le code à 6 chiffres, « Vérifier ». Attendu : « Facteur ajouté et vérifié. »
4. Menu « Administration » : la page « Double authentification requise » demande un code. Saisissez le code
courant (attendez le suivant si le vôtre est sur le point d'expirer), « Vérifier ». Attendu : la liste des
fiches officielles.
## 4. Parcours à dérouler
Chaque étape donne l'action et le résultat attendu. Notez tout écart avec la date et l'étape.
### 4.1 Créer une fiche non équine
1. Administration, « Nouvelle fiche ». Choisissez une espèce autre que le cheval (une espèce inactive est
acceptée), renseignez « Nom (français) », « Nom (anglais) » et l'identifiant (slug, par exemple `essai-chien`),
« Créer la fiche ».
2. Attendu : la fiche apparaît, avec un brouillon vide, ouvrable dans l'éditeur (onglets Général, Vues et
illustrations, Annotations, Constats, Références, Vertèbres, Vérification).
### 4.2 Importer une illustration SVG
Préparez deux fichiers dans un dossier hors du dépôt :
```bash
mkdir -p ~/essai-svg
cat > ~/essai-svg/valide.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><rect x="20" y="20" width="360" height="260" fill="#eee" stroke="#333"/><circle cx="200" cy="150" r="60" fill="#c96"/></svg>
SVG
cat > ~/essai-svg/nettoyable.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><style>.a{fill:#c96}</style><rect class="a" x="20" y="20" width="360" height="260"/></svg>
SVG
cat > ~/essai-svg/hostile.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><script>alert(1)</script><rect x="20" y="20" width="360" height="260"/></svg>
SVG
```
1. Onglet « Vues et illustrations », vue principale, « Choisir une illustration », fichier `valide.svg`.
Attendu : « L'illustration est ajoutée à la vue. » et le dessin s'affiche.
2. Même geste avec `nettoyable.svg`. Attendu : la boîte « Nettoyer cette illustration ? » avec l'aperçu du dessin
nettoyé et la mention que l'élément `<style>` est retiré. « Nettoyer et utiliser cette version » applique,
« Annuler » n'ajoute rien.
3. Même geste avec `hostile.svg`. Attendu : refus avec « Ce fichier contient du contenu actif ou externe… » ;
aucune boîte de nettoyage, aucune illustration ajoutée.
### 4.3 Créer des annotations
1. Onglet « Général » : créez une catégorie d'annotation (sans catégorie, l'onglet Annotations le signale).
2. Onglet « Annotations », outil « Point » : cliquez dans le dessin, renseignez les noms FR et EN, la catégorie, la
latéralité, « Créer ». Attendu : le point apparaît dans la liste et sur le dessin.
3. Outil « Zone » : posez au moins trois sommets, Entrée ou « Fermer le tracé ». Attendu : la zone est créée.
4. Ajoutez une vue de détail (onglet « Vues et illustrations », « Nouvelle vue de détail »), puis l'outil « Accès à
une vue détaillée » : tracez un contour et choisissez la « Vue ouverte ». Attendu : l'accès est créé.
5. « Annuler » et « Rétablir » défont et refont chaque création.
### 4.4 Correction de géométrie
1. Avec l'outil « Point », cliquez très près d'un bord du dessin. Attendu : « Le point ne tient pas à l'endroit
choisi. Position corrigée proposée : x = …, y = … » avec « Utiliser cette position » et « Annuler ». Le
brouillon ne change qu'après « Utiliser cette position ».
2. Sélectionnez un point, ouvrez ses propriétés (« Position et rayon ») et saisissez dans « Centre x » une valeur
hors du dessin (par exemple 9999). Attendu : « Valeurs non appliquées : le brouillon est inchangé. » ;
« Revenir aux valeurs enregistrées » rétablit le champ. Une valeur valide s'applique.
### 4.5 Enregistrer et restaurer
1. Faites une modification, puis « Enregistrer ». Attendu : « Révision N » avance, plus de mention de
modifications non enregistrées.
2. Faites une autre modification sans enregistrer et rechargez la page (F5). Attendu : le navigateur demande de
confirmer le départ (beforeunload). Confirmez le rechargement.
3. Attendu au retour : une offre de copie locale (« Une copie locale temporaire de ce brouillon existe dans cet
onglet… ») avec « Restaurer la copie » et « Ignorer la copie ». Restaurez : la modification revient, toujours
non enregistrée.
4. Limites sur mobile : `beforeunload` est peu fiable sur Safari iOS et sur un onglet tué en arrière-plan ; la
copie locale appartient à l'onglet et disparaît avec lui. Seul « Enregistrer » met le travail sur le serveur.
### 4.6 Concurrence entre deux onglets
1. Ouvrez le même brouillon dans deux onglets (A et B). Dans A, modifiez et enregistrez.
2. Dans B, modifiez autre chose et enregistrez. Attendu : la boîte « Conflit d'enregistrement » indiquant qu'une
autre session de votre compte a enregistré la révision.
3. « Recharger » (après confirmation) abandonne la modification de B et reprend la révision du serveur.
Recommencez le conflit puis « Garder ma version » (après confirmation) : la version de B remplace la révision
du serveur et la révision avance.
### 4.7 Vérification et soumission
1. Onglet « Vérification » : les erreurs bloquantes sont listées ; « Aller à » ouvre l'onglet concerné.
2. Corrigez-les, enregistrez, saisissez la « Note de soumission (obligatoire) », « Soumettre à la revue ».
Attendu : le brouillon passe en lecture seule, avec la mention de la revue et de la vérification en cours.
3. Gel : aucun worker de vérification ne tourne dans cet essai et le retrait d'une soumission n'existe pas. Le
brouillon reste donc gelé jusqu'à `down`. C'est attendu, pas un défaut. Refaites un essai avec une nouvelle
fiche (4.1) si vous voulez continuer à modifier.
## 5. Limites à connaître
- Risque résiduel RR-12 : les opérations du catalogue lisent la mention `aal2` du jeton, pas la session vivante.
Un jeton émis à `aal2` reste accepté après la suppression du facteur, jusqu'à son expiration (une heure).
- Les e-mails ne partent nulle part (l'interface de courrier de la pile jetable est sur `127.0.0.1:57025`).
- Les mots de passe créés ici n'ont de valeur que pour cette pile.
## 6. Arrêt et nettoyage
1. Dans le terminal de `trial` : Ctrl+C. Vite et la passerelle de l'essai s'arrêtent ensemble.
2. Puis :
```bash
pnpm db:sandbox down
```
Attendu : `== sandbox removed`. Vérification :
```bash
docker ps -a --format '{{.Names}}' | grep dbsandbox
```
Attendu : aucune ligne. Les secrets de la pile jetable sont supprimés avec elle. Rien n'a été écrit dans DEV.
Si le terminal de `trial` a été fermé sans Ctrl+C, `pnpm db:sandbox down` retire aussi la passerelle de l'essai ;
vérifiez ensuite que rien n'écoute plus sur le port 5193 (`ss -ltn | grep 5193`).
+101 -2
View File
@@ -22,6 +22,11 @@
# container, then tests/e2e/avatar-flow.e2e.ts (args go to vitest)
# pnpm db:sandbox sheet-assets-e2e (= pnpm e2e:sheet-assets) the sheet-asset upload tool against the sandbox:
# a gateway on 127.0.0.1:$PORT_GATEWAY, then scripts/sheet-assets-e2e.sh
# pnpm db:sandbox trial the owner's trial (docs/development/V1-2-6_OWNER_TRIAL.md): a gateway on
# 127.0.0.1:$PORT_TRIAL_GATEWAY and the app on http://127.0.0.1:$PORT_TRIAL_APP,
# foreground, Ctrl+C stops both
# pnpm db:sandbox trial-account <email> a confirmed account, password at a hidden prompt (12 characters min.)
# pnpm db:sandbox trial-grant <email> <catalog_reader|sheet_editor|sheet_reviewer|sheet_publisher>
# pnpm db:sandbox sql psql as postgres on stdin
# pnpm db:sandbox down
#
@@ -45,11 +50,13 @@ REST=faunosteo_dbsandbox_rest
STORAGE=faunosteo_dbsandbox_storage
MAIL=faunosteo_dbsandbox_mail
GATEWAY=faunosteo_dbsandbox_gateway
TRIAL_GATEWAY=faunosteo_dbsandbox_trial_gateway
WORKER=faunosteo_dbsandbox_worker_verify
AVATAR_WORKER=faunosteo_dbsandbox_worker_avatar
GATEWAY_IMAGE=nginx:1.31-alpine
WORKER_IMAGE=faunosteo_worker:dev
PORT_DB=57432 PORT_AUTH=57999 PORT_REST=57300 PORT_STORAGE=57500 PORT_MAIL=57025 PORT_GATEWAY=57800
PORT_TRIAL_GATEWAY=57801 PORT_TRIAL_APP=5193
STATE="${FAUNOSTEO_SANDBOX_DIR:-$HOME/.cache/faunosteo-db-sandbox}"
SECRETS="$STATE/secrets.sh"
CLI=node_modules/.bin/supabase
@@ -252,7 +259,7 @@ cmd_up() {
}
cmd_down() {
docker rm -f "$AVATAR_WORKER" "$WORKER" "$GATEWAY" "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB" >/dev/null 2>&1 || true
docker rm -f "$AVATAR_WORKER" "$WORKER" "$TRIAL_GATEWAY" "$GATEWAY" "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB" >/dev/null 2>&1 || true
docker network rm "$NET" >/dev/null 2>&1 || true
rm -f "$SECRETS" "$STATE/db.env" "$STATE/auth.env" "$STATE/storage.env" "$STATE/rest.env" "$STATE/service-header"
echo "== sandbox removed"
@@ -375,6 +382,95 @@ cmd_sheet_assets_e2e() {
SUPABASE_SERVICE_ROLE_KEY="$SB_SERVICE_KEY" bash scripts/sheet-assets-e2e.sh
}
# ---- Owner trial (docs/development/V1-2-6_OWNER_TRIAL.md) -------------------
port_taken() { (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
trial_email() { # email: one fixed shape, nothing else reaches curl or psql
[[ "${1:-}" =~ ^[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,120}\.[A-Za-z]{2,24}$ ]] \
|| die "an e-mail address is expected"
}
# Its own gateway container and loopback port, so the other commands' gateway is untouched.
start_trial_gateway() {
docker run -d --name "$TRIAL_GATEWAY" --network "$NET" --security-opt no-new-privileges:true \
-p 127.0.0.1:$PORT_TRIAL_GATEWAY:8000 \
--entrypoint sh "$GATEWAY_IMAGE" -c 'printf "%s\n" "$0" > /etc/nginx/conf.d/default.conf && exec nginx -g "daemon off;"' \
"$GATEWAY_CONF" >/dev/null
wait_for "trial gateway" docker exec "$TRIAL_GATEWAY" wget -q -O /dev/null http://127.0.0.1:8000/rest/v1/
[ "$(docker port "$TRIAL_GATEWAY" 8000/tcp)" = "127.0.0.1:$PORT_TRIAL_GATEWAY" ] \
|| die "the trial gateway is not published on 127.0.0.1:$PORT_TRIAL_GATEWAY only"
}
trial_stop() {
[ -z "${trial_pid:-}" ] || kill "$trial_pid" 2>/dev/null || true
docker rm -f "$TRIAL_GATEWAY" >/dev/null 2>&1 || true
}
# The app origin is the Vite server itself (/auth/v1, /rest/v1, /storage/v1 are proxied to the
# trial gateway, apps/app/vite/trial.config.ts): same origin, no CORS. The anon key reaches Vite
# through its environment, never argv.
cmd_trial() {
load_secrets
[ -z "$(docker ps -a -q -f "name=^${TRIAL_GATEWAY}\$")" ] \
|| die "$TRIAL_GATEWAY exists (stop the running trial, or pnpm db:sandbox down)"
for port in $PORT_TRIAL_GATEWAY $PORT_TRIAL_APP; do
! port_taken "$port" || die "port 127.0.0.1:$port is already in use: nothing was started"
done
trap trial_stop EXIT
trap 'exit 130' INT TERM
start_trial_gateway
echo "== trial: http://127.0.0.1:$PORT_TRIAL_APP (Ctrl+C stops the app and its gateway)"
( cd apps/app && FAUNOSTEO_TRIAL_GATEWAY="http://127.0.0.1:$PORT_TRIAL_GATEWAY" \
VITE_SUPABASE_URL="http://127.0.0.1:$PORT_TRIAL_APP" VITE_SUPABASE_ANON_KEY="$SB_ANON_KEY" \
exec node_modules/.bin/vite --config vite/trial.config.ts --host 127.0.0.1 \
--port $PORT_TRIAL_APP --strictPort ) &
trial_pid=$!
wait "$trial_pid"
}
# The password is typed twice at a hidden prompt, kept in this process only and sent to GoTrue
# on stdin through node (JSON escaping); nothing secret is printed.
cmd_trial_account() {
trial_email "${1:-}"
load_secrets
local pw confirm
read -rsp "Password (12 characters min.): " pw; echo
read -rsp "Again: " confirm; echo
[ "$pw" = "$confirm" ] || die "the two passwords differ"
[ "${#pw}" -ge 12 ] || die "12 characters min."
TRIAL_EMAIL="$1" TRIAL_PW="$pw" node -e '
process.stdout.write(JSON.stringify({ email: process.env.TRIAL_EMAIL,
password: process.env.TRIAL_PW, email_confirm: true }));' \
| curl -fsS -o /dev/null -X POST http://127.0.0.1:$PORT_AUTH/admin/users \
-H @"$STATE/service-header" -H 'Content-Type: application/json' --data-binary @- \
|| die "account not created (already existing, or password refused)"
echo "== account created and confirmed: $1"
}
# The sheet_editor / sheet_publisher rights need an active admin role (O1); same SQL as
# apps/app/e2e/support/admin.ts. Email and kind are psql variables, never SQL text.
cmd_trial_grant() {
local email="${1:-}" kind="${2:-}"
trial_email "$email"
[[ "$kind" =~ ^(catalog_reader|sheet_editor|sheet_reviewer|sheet_publisher)$ ]] \
|| die "kind: catalog_reader | sheet_editor | sheet_reviewer | sheet_publisher"
load_secrets
sb_psql -v email="$email" -v kind="$kind" --single-transaction >/dev/null <<'SQL'
-- no row: \gset fails and the run stops (no account with this e-mail)
select id::text as uid from auth.users where email = :'email' \gset
insert into public.anatomical_catalog_grants (user_id, grant_kind, reason, verification_note, granted_by)
select :'uid'::uuid, :'kind'::public.catalog_grant_kind, 'owner trial',
case when :'kind' = 'catalog_reader' then null else 'owner trial' end, :'uid'::uuid
where not exists (select 1 from public.anatomical_catalog_grants
where user_id = :'uid'::uuid and grant_kind = :'kind'::public.catalog_grant_kind and revoked_at is null);
select private.assign_platform_role(null, :'uid'::uuid, 'admin')
where :'kind' in ('sheet_editor', 'sheet_publisher')
and not exists (select 1 from public.profile_roles
where user_id = :'uid'::uuid and role = 'admin' and revoked_at is null);
SQL
echo "== $kind granted to $email"
}
case "${1:-}" in
up) shift; cmd_up "$@" ;;
down) cmd_down ;;
@@ -392,6 +488,9 @@ case "${1:-}" in
verify-e2e) shift; cmd_verify_e2e "$@" ;;
avatar-e2e) shift; cmd_avatar_e2e "$@" ;;
sheet-assets-e2e) cmd_sheet_assets_e2e ;;
trial) cmd_trial ;;
trial-account) shift; cmd_trial_account "$@" ;;
trial-grant) shift; cmd_trial_grant "$@" ;;
sql) load_secrets; sb_psql ;;
*) sed -n '2,31p' "$0"; exit 1 ;;
*) sed -n '2,36p' "$0"; exit 1 ;;
esac