Files
Kazier/docs/api-v1.md
T
venture 1e38e6e4ee V3 S6 : confiance (révocation, quota, appareils, conflits) + import + onboarding
Backend : token_version (000022, claim tv, 401 si révoqué, bump au
password — fin limite V1), quota (000023 idempotente, colonne héritée
de 000001, 413 QUOTA_EXCEEDED, GET /users/me/usage), devices
(GET + DELETE révocation, EnforceDeviceExists en prod), renames
concurrents transparents (baseUpdatedAt + conflicts[] non-fataux,
tolérance 2 s). Tests service + handlers + migrations + auth.

Mobile : pipeline conflits (DTO + SyncConflictStore + worker + dialogue),
baseUpdatedAt prêt, liens 7j par défaut, écran Appareils (+ quota),
import classeur unifié (scan/note/dossier), onboarding cercle Famille.

Contrat docs/api-v1.md, V3.md (S6 livré).
2026-09-26 11:56:39 +02:00

199 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Kazier — Contrat API V1 (autoritatif)
Status : **autoritatif**. Le client mobile Kotlin est la source de vérité : `data/remote/ApiService.kt` + `data/remote/dto/Dtos.kt` (contrat Retrofit/Moshi) sont implémentés ; le serveur Go doit les matcher exactement (méthode + path + enveloppe), il ne re-négocie pas. Document consolidé depuis le client — toute divergence de ce doc doit être portée dans le client d'abord.
Références : `V2.md` (modèle cible), `mobile/services/db/` (conventions sync), `AGENTS.md` (structure + commandes).
---
## 1. Base et transport
- Base URL serveur : configurable à l'exécution dans les Réglages de l'appli (défaut `http://10.0.2.2:8080/api/v1`).
- JSON partout, sauf `POST /files/upload` (multipart).
- Enveloppe succès : `{ "data": T, "meta"?: { "page": int, "pageSize": int, "total": int } }` (`meta` présent sur les listes paginées).
- Erreur : `{ "error": { "code": string, "message": string } }` + statut HTTP adéquat.
- Côté client, toute réponse non-`2xx` est normalisée en `ApiError` : `code` du body si présent, sinon `HTTP_<status>` ; échec réseau → `NETWORK_ERROR`. Une réponse `2xx` mais dont le body n'est pas du JSON d'enveloppe valide (HTML, corps vide, JSON mal formé, absence de la clé `data`) → `INVALID_RESPONSE` (client-only).
## 2. Identité et identifiants (invariants)
- **User-first (V1 finale)** : le device s'enregistre d'abord (`POST /devices`) avec son identité **générée localement** (`device_user_id` 32-hex mobile) — **réponse `{ "deviceId" }` uniquement, sans token**. Puis le client appelle `POST /auth/login` (`username` + `password` + `device_id`) pour obtenir son token **paseto** v4-local. Requêtes suivantes : `Authorization: Bearer <token>` (toutes les routes **sauf `/health`, `/devices`, `/auth/login`**).
- **Claims du token** : le **subject = `user_id`** (AUTORISE, clé de scoping de toutes les ressources) ; `device_id` est un **claim secondaire, porté mais NON autorisant seul** (idempotence outbox + jobs OCR). Résolu par middleware `RequireAuth` qui vérifie aussi que le compte existe toujours (`deleted_at IS NULL`).
- **TTL : 7 jours, sans refresh.** À expiration, le client re-logine (`POST /auth/login`). **Révocation V3 (S6)** : `PATCH /users/me/password` bumpe `users.token_version` — tous les tokens antérieurs deviennent 401 (`token revoked`), y compris non expirés ; le client doit se reconnecter (le claim `tv` porte la version, les tokens pré-V3 sans `tv` valent 0 et survivent jusqu'au premier changement de mot de passe).
- Au login, `devices.user_id` mémorise le **dernier user connecté** (INFORMATIF uniquement, jamais autorisant — recommande `POST /devices` → `POST /auth/login` pour un nouveau device, sans réutiliser le device d'un autre compte). **Révocation V3 (S6 A1)** : `DELETE /devices/:id` supprime l'enregistrement (téléphone perdu) — avec `EnforceDeviceExists` (prod), les tokens du device deviennent 401 et son login est refusé ; seule une ré-inscription explicite (`POST /devices`) restaure l'accès. `GET /devices` liste les devices du compte (dernier login = ce compte).
- **Identifiants** : `resource_id`, `device_user_id`, `user_id`, `is_admin`… = **TEXT opaque 32-hex minuscule**, `^[0-9a-f]{32}$`. Le mobile génère toujours `lower(hex(randomblob(16)))` ; le serveur stocke **tel quel**, sans conversion UUID (cf. note V2.md). Contrainte serveur : `CHECK (col ~ '^[0-9a-f]{32}$')` sur toutes les colonnes id + FK.
- **Usernames** : `username` = forme affichée ; l'unicité et la résolution portent sur `username_normalized` (lowercase + trim). Résolution d'un destinataire : `GET /users/resolve?username=` (exact uniquement, jamais de listing ni de préfixe — pas d'énumération de comptes).
- **Bootstrap** : au premier démarrage, si `users` est vide, `ADMIN_USERNAME`/`ADMIN_PASSWORD` (env) créent le **premier admin** ; absents → le serveur **refuse de démarrer**. L'env n'écrase jamais un compte existant.
- Horodatages échangés en **millisecondes epoch** (le mobile utilise `Date.now()`).
## 3. Endpoints
| Méthode | Path | Requête | Réponse `data` | Statut absence |
|---|---|---|---|---|
| GET | `/health` | — | `{ "status": "healthy" }` | — |
| POST | `/devices` | `{ "deviceId": "…32-hex" }` (client-generated) | `{ "deviceId": "…32-hex" }` — **aucun token** (V1 finale) | `INVALID_DEVICE_ID` |
| POST | `/auth/login` | `{ "username", "password", "device_id" }` | `{ "token", "expires_at" (ms), "user": { "id", "username", "is_admin" } }` | `UNAUTHORIZED` / `INVALID_DEVICE_ID` |
| GET | `/shares/links/:token` | — (public, sans auth) | `{ "token", "resource_id", "resourceType", "name", "access", "expiresAt" }` | `NOT_FOUND` (inconnu/révoqué/expiré) |
| GET | `/users/resolve` | query `username` (obligatoire) | `{ "id", "username" }` | `NOT_FOUND` |
| PATCH | `/users/me/password` | `{ "current_password", "new_password" }` | `{ "id" }` (+ révocation globale des tokens) | `INVALID_PASSWORD` (403) |
| GET | `/users/me/usage` | — | `{ usedBytes, quotaBytes, fileCount, trashCount, trashedBytes }` (calculé, corbeille détaillée) | — |
| GET | `/devices` | — | `[{ deviceId, lastSeenAt }]` (dernier login = ce compte) | — |
| DELETE | `/devices/:id` | — (téléphone perdu, A1) | `{ "id" }` | `NOT_FOUND` (absent/autre compte — pas d'énumération) |
| GET | `/files` | query `folderId?`, `page?`, `pageSize?`, `sort?` | `FileDto[]` (+ `meta`) | — |
| GET | `/files/:id` | — | `FileDto` | `NOT_FOUND` |
| GET | `/files/:id/content` | — (binaire brut, hors enveloppe `{data}` ; `Range` supporté) | octets physiques (`Content-Type` du fichier, `Content-Disposition: inline`) — streaming lecture seule, jamais persisté côté client | `NOT_FOUND` (invisible OU metadata-only jamais uploadé — indistinguables) |
| DELETE | `/files/:id` | query `mode?` (`trash` défaut, `purge` = définitif) | `{ "id": "…" }` | `NOT_FOUND` |
| POST | `/files/:id/restore` | — | `{ "id": "…" }` | `NOT_FOUND` (absente/étrangère/purgée ; vivante = succès idempotent) |
| GET | `/trash` | query `page?`, `pageSize?` | `TrashDto[]` (`{ id, type, name, size, trashedAt, updatedAt }` + `meta`) | — |
| GET | `/files/:id/versions` | — (parent live uniquement) | `VersionDto[]` (`{ versionNo, size, mimeType, createdAt }`, plus récent d'abord) | `NOT_FOUND` |
| POST | `/files/:id/versions/:n/restore` | — (l'actuel est à son tour versionné) | `FileDto` | `NOT_FOUND` |
| GET | `/files/search` | query `q` (obligatoire), `page?`, `pageSize?`, facettes V3 : `issuer?`, `from?`/`to?` (ISO `YYYY-MM-DD`, sur faits date/échéance + recouvrement périodes `YYYY-MM`), `min_amount?`/`max_amount?` (numériques), `doc_type?` (vocabulaire suggéré) | `FileDto[]` (+ `meta`, rang : nom exact > TS > fait sûr > fait douteux) | `INVALID_REQUEST` (facette malformée) |
| GET | `/files/folders` | — | `FolderDto[]` (racines) | — |
| POST | `/files/upload` | multipart : `file` (uri/name/type), `folderId?` | `FileDto` | `FILE_TOO_LARGE` |
| POST | `/ocr/jobs` | `{ "fileId": "…" }` | `OcrJob` | — |
| GET | `/ocr/jobs/:id` | — | `OcrJob` | `NOT_FOUND` |
| GET | `/files/:id/ocr` | — | `FileOcr` (`{ text, updatedAt }`) | `NOT_FOUND` |
| GET | `/files/:id/facts` | — (viewer+, même portée que l'OCR) | `Fact[]` (`{ factType: date&#124;due_date&#124;period&#124;amount&#124;issuer&#124;reference&#124;doc_type, valueText?, valueNum?, valueDate? (ISO), confidence (0..1), origin: auto&#124;user }`, `[]` si rien d'extractible) | `NOT_FOUND` (trashé/absent/étranger) |
| PATCH | `/files/:id/facts` | `{ facts: [{ factType, valueText?, valueNum?, valueDate?, confidence? }] }` (jeu `user` complet, full-replace, editor+) | `Fact[]` (jeu complet auto + user) | `NOT_FOUND` (viewer-/absent/trashé), `INVALID_REQUEST` (type inconnu, date non ISO, fait sans valeur, corps malformé) |
| GET | `/files/:id/relations` | — (owner uniquement) | `Relation[]` (`{ id, otherId, type: same_scan&#124;duplicate_of&#124;same_issuer&#124;same_reference, confidence, createdBy: auto&#124;user, otherName, otherType, otherSize }`, réconcilié à la lecture, autre bout vivant) | `NOT_FOUND` (étranger/trashé/absent — pas d'énumération) |
| POST | `/files/:id/relations/verdict` | `{ otherId, linkType, confirmed }` | `Relation[]` (jeu réconcilié) | `NOT_FOUND` (bouts non possédés), `INVALID_REQUEST` (type/paire invalide, corps malformé) |
| GET | `/duplicates` | — (compte connecté) | `DuplicateGroup[]` (`{ contentHash, count, totalBytes, reclaimableBytes, files: [{ id, name, size, updatedAt }] }`, plus gros d'abord, `[]` si propre) | — |
| GET | `/files/:id/shares` | — (owner uniquement) | `ShareGrant[]` (`{ granteeUserId, granteeKind: "user"&#124;"group", username, access, inherit, expiresAt (ms&#124;null), updatedAt (ms) }`) | `NOT_FOUND` (non-owner ou inconnue — pas d'énumération) |
| GET | `/files/:id/links` | — (owner uniquement) | `ShareLink[]` (même forme que `GET /shares/links/:token`) | `NOT_FOUND` (non-owner ou inconnue) |
| GET | `/files/:id/placements` | — (owner uniquement) | `Placement[]` (`{ locationType: "server"&#124;"mobile", deviceId?, hasBytes, updatedAt }`, entrée serveur en premier) | `NOT_FOUND` (non-owner ou inconnue) |
| POST | `/groups` | `{ "name" }` | `{ "id", "name", "role": "owner" }` | `INVALID_REQUEST` (nom vide/trop long) |
| GET | `/groups` | — | `Group[]` (`{ "id", "name", "role": "owner"&#124;"member" }`, possédés + rejoints) | — |
| POST | `/groups/:id/members` | `{ "userId": "…32-hex" }` | `{ "id": "…" }` | `NOT_FOUND` (groupe d'autrui/inconnu), `GRANTEE_NOT_FOUND` (membre inconnu) |
| GET | `/groups/:id/members` | — (owner uniquement) | `Member[]` (`{ "id", "username" }`) | `NOT_FOUND` |
| DELETE | `/groups/:id/members/:userId` | — | `{ "id": "…" }` | `NOT_FOUND` |
| DELETE | `/groups/:id` | — | `{ "id": "…" }` | `NOT_FOUND` (d'autrui/inconnu) |
| POST | `/sync/ops` | voir §6 | voir §6 | — |
| GET | `/sync/permissions` | query `after?` (cached_at ms) | `ResourcePermission[]` | — |
> **Lecture partagée** : `GET /files`, `GET /files/:id`, `GET /files/search`, `GET /files/:id/ocr` et `GET /files/folders` couvrent les ressources **possédées ET partagées** (accès `viewer+`, §6.2). Le rename d'une ressource partagée passe par l'outbox `update_metadata` (nécessite `editor+`, §6.1). `DELETE /files/:id` reste owner-only.
### DTOs (copie conforme de `mobile/api/types.ts`)
```ts
type FileDto = {
id: string; // resource_id 32-hex
name: string;
size: number;
mimeType?: string | null;
folderId?: string | null; // resource_id 32-hex
tags?: string[];
hasContent: boolean; // V2 : octets vus présents (lazy healing, FALSE = jamais constatés)
createdAt?: string;
updatedAt?: string;
};
type FolderDto = { id: string; name: string; parentId?: string | null };
type OcrJobStatus = 'queued' | 'processing' | 'done' | 'failed';
type OcrJob = { id: string; status: OcrJobStatus; text?: string | null; error?: string | null };
type FileOcr = { text: string; updatedAt?: string | null };
```
## 4. Upload
- Multipart : champ `file` + `folderId?` optionnel + `resourceId?` optionnel. **Le client ne fixe jamais `Content-Type`** (le boundary doit être généré par la plateforme).
- `resourceId` optionnel : cible un **fichier déjà connu du user** (créé metadata-only via l'outbox `create_resource`, ou précédemment uploadé) pour lui **attacher ses octets physiques** — cas d'usage : le client local-first doit fournir le bytes d'un fichier SAF pour l'OCR serveur (`POST /ocr/jobs`). Le `resourceId` fourni doit exister et appartenir au user (sinon `NOT_FOUND`, même réponses/format que `GET /files/:id`) ; la ligne n'est **jamais re-créée ni renommée ni déplacée**, seule la métadonnée physique (`size`/`mimeType`/extension) est rafraîchie et `FileDto` renvoyé. `resourceId` absent → comportement historique (nouvelle ressource).
- Limite : `MAX_FILE_SIZE_MB` (défaut 50). Dépassement → 413 `{ "error": { "code": "FILE_TOO_LARGE", … } }`.
- Le fichier physique est stocké sous `UPLOAD_DIR/<user_id>/<resource_id>.<ext>` ; la métadonnée est persistée en base et renvoyée en `FileDto`. Si la persistance de la métadonnée échoue (ex. `NAME_CONFLICT`), le fichier physique est supprimé.
## 5. OCR
- `POST /ocr/jobs { fileId }` → `OcrJob` immédiat (`status: queued`), traitement **asynchrone** par une **file serveur bornée** (`ocr_jobs` + worker `Ocr.Run`, `OCR_WORKERS` défaut 2) — le handler n'enfile **jamais** de traitement, Tesseract tourne hors request handler (FIFO, récupération des `processing` orphelins au boot).
- `GET /ocr/jobs/:id` → statut. Le mobile **poll toutes les 3s** jusqu'à `done`/`failed` (`hooks/useUpload.ts`). Cycle : `queued → processing → done | failed` ; `done` renvoie `text`, `failed` renvoie `error`.
- Moteur : **Tesseract en appel système** (`ocr/tesseract.go`), langue `OCR_LANG` (défaut `fra+eng`). Les images sont passées directement à `tesseract` ; les **PDF** subissent une extraction du calque texte (`ledongthuc/pdf`, déjà en go.mod) — un PDF scanné produit un texte vide plutôt qu'un rendu/OCR (hors scope V1).
- `fileId` inconnu/pas du user → `NOT_FOUND`. Fichier physique introuvable (ex. suppression manuelle sous `UPLOAD_DIR`) → job `failed` `"file not readable"`. Le job est créé par le device courant (`ocr_jobs.device_id`) mais la validation de la ressource est scopée par le **user**.
- **Le texte atterrit sur la ressource** : à la complétion (`done` avec texte non vide), le worker écrit l'extrait trimé dans `resources.ocr_text` (et **bump `updated_at`**, d'où une injection dans le delta outbox/snapshot). `ocr_jobs.text` reste l'historique du job.
- **`GET /files/:id/ocr`** → `FileOcr { text, updatedAt }` : l'extrait server-side du fichier, lisible par le **possédant ET les grantees** (`viewer+`, même portée que `GET /files/:id` ; `text` `""` si pas encore extrait). Un **second device** rapatrie ainsi le texte d'un OCR fait par un autre device (ou par la ressource partagée) **sans re-téléverser les octets ni re-soumettre de job** — le client Kotlin le fait en tête de `OcrRepository.syncFromServer`/`processAuto` et du viewer (`OcrViewModel`).
- **Faits génériques V3 (`GET /files/:id/facts`)** : après chaque OCR `done`, le worker en dérive des faits vérifiables (règles FR, sans ML : dates ISO, échéances (`due_date` si mot-clé `échéance|à payer avant|date limite`), périodes (`2026-03`), montants € (confiance 0.9 si mot-clé `total|montant|à payer`), émetteurs (lignes capitales), références (`facture:FA-…`, `siret:…`, IBAN masqué `rib:••••1234`), `doc_type` suggéré (seuil de score, jamais gate). Chaque fait porte `confidence` (0..1) et `origin` (`auto` remplacé à chaque passe, `user` intouchable — corrections S3). Même portée que l'OCR (`viewer+`) ; `[]` si rien d'extractible. Backfill borné au boot (OCR d'avant la V3).
## 6. Contrat de sync (outbox + snapshot)
### 6.1 Outbox — `POST /sync/ops`
```json
{
"operations": [
{
"operation_id": "…32-hex", // généré par le client (GenerateId), jamais réutilisé
"ref_type": "resource", // "resource" | "share" | "share_link"
"ref_id": null, // id local de la ligne share/share_link (sinon null)
"resource_id": "…32-hex", // ressource cible
"resource_type": "folder", // "folder" | "file"
"operation": "create_resource",
"payload": {}
}
]
}
```
- `operation` ∈ `create_resource | update_metadata | delete_resource | move_resource | share | revoke_share | update_share | create_link | revoke_link | report_bytes | trash_resource | restore_resource | purge_resource | correct_facts` (cf. `PendingOperationType` mobile).
- **Identifiants** : `operation_id` est un **TEXT 32-hex** généré par le client (`^[0-9a-f]{32}$`, CHECK-enforced depuis la migration `000008`), distinct de `resource_id`. L'idempotence outbox reste **par device** : `UNIQUE(device_id, operation_id)` (la réinscription d'un device avec un login différent ne réutilise pas l'historique outbox d'un autre compte). Pour chaque op : si déjà traitée → **no-op** (comptée comme appliquée, les doublons arrivent à cause du backoff/retry). Sinon appliquée si valide.
- **Ordre** : les opérations sont appliquées **séquentiellement**, dans l'ordre du batch. Le serveur **s'arrête à la première erreur non-idempotente** et renvoie l'index atteint — le client reprend à cet index.
- Réponse : `2xx` avec `{ "applied": int, "failed": { "operation_id": "…32-hex", "code": string, "message": string } | null, "conflicts"?: [{ "operation_id", "resource_id", "serverName", "serverUpdatedAt" }] }` (`applied` = index de la prochaine op à envoyer ; `conflicts` = renames LWW appliqués malgré une `baseUpdatedAt` périmée — non-fataux, le batch continue).
- Côté client, le `pushStatus` (pending/synced/failed) des shares/share_links est **dérivé** de l'état des opérations de l'outbox ; **dead-letter immédiat** sur erreur 4xx non-idempotente (`failed`, non resélectionné ; `attempts` reste un compteur diagnostic, pas un seuil) — seul le transitoire (`NETWORK_ERROR`/5xx) est rejoué avec backoff. **Côté serveur, les ops partage créent un état réel** (tables `shares`/`share_links`, migration `000009`) — l'outbox est le seul chemin d'écriture des droits.
- Sémantique d'application (côté serveur) :
- `create_resource` : crée la ressource ; **déjà présente → no-op** (rejeu idempotent). `payload.name` obligatoire ; `payload.parentResourceId` (32-hex, optionnel) = dossier parent — absent → racine. **Parent inexistant → `NOT_FOUND`** (cohérent avec `move_resource`). Ordre garanti par construction client : le walk SAF émet les `create` des dossiers (ordre préfixe) avant ceux des fichiers, dans la même transaction Room → `id ASC` = parent avant enfant. `payload.scanSessionId` (32-hex, optionnel, V3 S5) = session de scan opaque — le serveur en déduit les arêtes `same_scan` (même session, même compte) ; format invalide → `INVALID_REQUEST`.
- `update_metadata` : ressource absente → **no-op** (état terminal atteint) ; **ressource partagée : nécessite `editor+`** (§6.2) — sinon `NOT_FOUND` (une ressource visible mais sans droit de mutation n'est pas renommée) ; une ressource sans relation applicable (ni owner, ni grant) reste un no-op (pas d'énumération). `payload = { "name", "baseUpdatedAt"? }` (V3 S6 A4 : `updated_at` ms vu par le client — périmé au-delà de 2 s de tolérance → rename appliqué quand même + signalé en `conflicts`, transparence sans CRDT). `move_resource` / `delete_resource` restent **owner-only** (scoping par `user_id`, les ops d'un non-owner sont des no-op).
- `delete_resource` : **legacy → mappé vers `trash_resource`** (corbeille, restaurable, même idempotence : absent/déjà trashé = succès, vivant d'autrui = `NOT_FOUND` halt).
- **Corbeille V3** (`trash_resource` / `restore_resource` / `purge_resource`, owner-only) : `trash` pose `deleted_at` sur la ressource **et son subtree** (dossier → contenu) ; `restore` lève le flag sur la ressource, son subtree **et sa chaîne d'ancêtres** (un fichier restauré dont le dossier est encore trashé resterait injoignable) ; `purge` détruit lignes + versions + octets. Sémantique : absent → no-op (`trash`/`restore`/`purge`), vivant d'autrui → `NOT_FOUND` halt, `restore` d'un live → no-op succès. Une ressource trashée reste `NOT_FOUND` en lecture normale, visible seulement via `GET /trash`. Passe serveur : destruction définitive après 30j (`TrashRetention`).
- **Corrections V3** (`correct_facts`, editor+) : `payload = { "facts": [{ "factType", "valueText"?, "valueNum"?, "valueDate"? (ISO `YYYY-MM-DD`), "confidence"? }] }` — remplace le jeu `user` complet (full-replace, jamais de diff ; jeu vide = efface les corrections, l'auto survit). Mêmes gardes qu'`update_metadata` (viewer- → `NOT_FOUND` halt) ; fait invalide (type inconnu, date non ISO, sans valeur) → `INVALID_REQUEST` avec arrêt du batch. Le client corrige en un tap depuis la fiche document et pousse dans la même transaction Room que l'écriture optimiste.
- **Graphe V3 (lecture)** : `GET /files/:id/relations` (owner-only) réconcilie puis renvoie les arêtes vivantes — `same_scan` (même `scan_session_id`, 1.0), `duplicate_of` (même SHA-256, 1.0 — hash posé à l'upload + backfill boot), `same_issuer`/`same_reference` (faits égaux, confiance = min, auto ignoré si correction `user` du même type — miroir de l'affichage). Stockage canonique (`from < to`), verdicts `user` préservés et bloquant toute re-création auto, élagage des auto périmées. `POST /files/:id/relations/verdict` (confirmé → 1.0, infirmé → 0.0 conservé). `version_of` non matérialisé : les versions vivent DANS la ressource (`resource_versions`). `GET /duplicates` (compte connecté) : groupes par hash avec gain récupérable (total − plus gros).
- **Versions V3** : chaque overwrite d'octets (upload ciblé) fige l'ancienne génération (`resource_versions`, N=3, élagage auto) ; `POST /files/:id/versions/:n/restore` recopie vers le live (l'actuel est à son tour versionné). Upload ciblé vers une ressource trashée → `NOT_FOUND` (jamais de résurrection d'octets).
- **Partage** (`share` / `update_share`, même sémantique d'upsert) : `payload = { "granteeUserId"?: "…32-hex", "granteeGroupId"?: "…32-hex", "access": "viewer"|"commenter"|"editor", "inherit"?: bool, "expiresAt"?: ms }` — **exactement un** principal (user XOR groupe, V2-6). La ressource doit **appartenir** au user appelant (sinon `NOT_FOUND`) ; le grantee user doit exister (sinon `GRANTEE_NOT_FOUND`), le groupe doit exister (sinon `GROUP_NOT_FOUND`) ; accès déjà partagé → mis à jour (idempotent). Privilégier `viewer` < `commenter` < `editor` (< `owner` réservé à l'ownership, non partageable → `INVALID_REQUEST`). Les membres d'un groupe partagé héritent du grant (un niveau, sans imbrication) dans le snapshot comme dans l'enforcement.
- `revoke_share` : `payload = { "granteeUserId": "…32-hex" }`. **Idempotent** (déjà révoqué/absent → no-op).
- `create_link` : `payload = { "token": "…32-hex", "access": "viewer"|"commenter"|"editor", "expiresAt"?: ms }`. Le token est **généré côté client** (`GenerateId`), c'est l'identifiant du lien (colonne `id` de `share_links`).
- `revoke_link` : `payload = { "token": "…32-hex" }`. **Idempotent**.
- **Présence multi-device** (`report_bytes`) : `payload = { "hasBytes": bool }` (**requis**). Le device signale ses octets locaux pour un fichier visible (`viewer+`, own ou partagé — sinon `NOT_FOUND`). Upsert idempotent par `(device, resource)` ; le rejeu à l'identique est no-op, mais chaque **changement d'état exige un nouvel `operation_id`** (garde anti-rejeu A9). Portée `file` uniquement.
- Validation (deuxième champ `operation_id`, hex32 pour `resource_id` **et** `operation_id`, enum `operation`) → échec `INVALID_REQUEST` avec arrêt du batch.
- Nom déjà pris (même parent, ou à la racine) → échec `NAME_CONFLICT`.**
- **Lien public** : `GET /shares/links/:token` est **sans authentification** (résolution publique d'un lien) et renvoie `{ "token", "resource_id", "resourceType", "name", "access", "expiresAt" }`. `NOT_FOUND` si le lien est inconnu, révoqué ou expiré. Le client partage les liens sous forme de deep-link `kazier://share/<token>` (custom scheme, pas d'App Links https) : indépendant du domaine du serveur, donc compatible self-hosting (chaque instance a son propre host).
### 6.2 Snapshot — `GET /sync/permissions?after=<cached_at_ms>`
- Renvoie le delta (ou l'ensemble) des permissions effectives pour le **user** appelant, chacune sous la forme exacte consommée par `canAccess` :
```ts
type ResourcePermission = {
resource_id: string; // 32-hex
resourceType: 'folder' | 'file';
effectiveAccess: 'viewer' | 'commenter' | 'editor' | 'owner';
name: string; // nom de la ressource (hydratation mobile)
parentId: string | null; // parent 32-hex, null = racine (hydratation mobile)
inherit: boolean;
ownerId: string | null; // ownership USER si applicable
sharedById: string | null;
expiresAt: number | null; // ms epoch ; null = jamais
cachedAt: number; // ms epoch — horodatage du snapshot (TTL 24h)
updatedAt: number;
};
```
- **Calcul de `effective_access`** (le serveur est la source de vérité) :
1. Rang : `viewer = 1 < commenter = 2 < editor = 3 < owner = 4`.
2. La permission **exacte sur le nœud** est autoritaire — elle n'est pas annulée par son propre `inherit=false` et n'est pas écrasée par un ancêtre de rang supérieur.
3. Les ancêtres propagent **uniquement si leur relation a `inherit = true`** ; une relation expirée (`expires_at` passé) est ignorée **et ne propage pas**.
4. `owner_id` == le user appelant → `owner` (fallback, quel que soit le niveau remonté).
5. Le **rang le plus élevé** l'emporte pour les nœuds **sans permission propre** ; sans relation applicable et sans ownership → la ressource n'est pas dans le snapshot. `inherit = false` sur un nœud intermédiaire stoppe uniquement la propagation de **sa propre relation** ; une relation `inherit = true` plus haut continue de traverser.
- **Delta** : `after` filtre sur `resource.updated_at` **et** l'`updated_at` de la relation gagnante — une ressource nouvellement partagée apparaît dans le delta du grantee dès sa création. **Révoquée/expirée, la ressource disparaît du snapshot** : la convergence côté client passe par les pulls complets (`after=0`, à chaque login et quand le cache dépasse le TTL 24h).
- **TTL / stale** : après `PERMISSION_TTL_MS` (= 24h) sans reseed, `canAccess` **downgrade en lecture seule** (`viewer`) vers le cache.
### 6.3 Placements
- Le statut de placement (`sync_status` mobile : `local` | `cloud` | `local-cloud`) est le reflet du `resource_placements` serveur (statuts V2 : `local_only`, `synced`, `cloud_only`, `pending_upload`, `pending_download`). La matérialisation se fait via l'outbox (`create_resource` → `synced`/`pending_upload` ; suppression physique locale ≠ suppression serveur).
- **Présence multi-device (V2)** : les devices reportent leurs octets via l'op `report_bytes` (tables `storage_locations` + `resource_placements`, migration `000015`) ; le propriétaire lit `GET /files/:id/placements` (entrée `server` implicite depuis `has_content` + reports devices, owner-only). Hint de présence, jamais preuve — le serveur ne vérifie pas les octets distants.
## 7. Codes d'erreur courants
- Authentification : `UNAUTHORIZED` (**401** — token manquant/invalide/expiré/**révoqué** (mot de passe changé, device révoqué), compte supprimé, OU identifiants de login erronés : **indistinguables par design**, même code+message), `INVALID_DEVICE_ID` (**400** — device non enregistré au login).
- Ressources : `NOT_FOUND` (404), `NAME_CONFLICT` (409 — même nom dans le même parent, cf. `UNIQUE(parent_id, name)`, **ou à la racine**, index partiel `(user_id, name) WHERE parent_id IS NULL`), `FILE_TOO_LARGE` (413), `QUOTA_EXCEEDED` (413 — créations au-delà de `storage_quota_bytes`, 10 Go par défaut ; overwrites ciblées exemptées, gain net ~nul), `INVALID_PASSWORD` (403 sur `PATCH /users/me/password`).
- Partage : `GRANTEE_NOT_FOUND` (404 — grantee inexistant sur une op share), `GROUP_NOT_FOUND` (404 — groupe inexistant sur une op share ou un endpoint membres), `NOT_FOUND` (404 — ressource non possédée sur une op share : scoping, pas d'énumération).
- Client-only : `NETWORK_ERROR`, `INVALID_RESPONSE` (2xx mais corps d'enveloppe invalide), `HTTP_<status>` (fallback). Statut `SERVICE_UNAVAILABLE` (503) si le backend n'est pas initialisé.
- **V1 finale : toutes les routes sont réelles** (pas de 501 restant).
## 8. Moteur de login (règles de sécurité)
- `POST /auth/login` : le **device doit exister** (`POST /devices` d'abord, sinon 400 `INVALID_DEVICE_ID`). La vérification du mot de passe est **constant-time** (`argon2id`, comparaison `subtle`) et le délai est **égalisé** entre « username inconnu » et « mauvais mot de passe » (vérification contre un dummy-hash) — les deux produisent exactement la même réponse 401.
- `GET /users/resolve` : résolution **exacte** du `username_normalized` uniquement ; ne renvoie **jamais** `email` ni `is_admin` (ni listing, ni préfixe → pas d'énumération de comptes).
- `PATCH /users/me/password` : exige `current_password` (mauvais curl → 403). Minimum 8 caractères. **V3 S6** : bumpe `token_version` (tous les tokens antérieurs révoqués — le client se reconnecte) ; `is_admin`/`ADMIN_*` non modifiables par API.