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é).
199 lines
28 KiB
Markdown
199 lines
28 KiB
Markdown
# 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|due_date|period|amount|issuer|reference|doc_type, valueText?, valueNum?, valueDate? (ISO), confidence (0..1), origin: auto|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|duplicate_of|same_issuer|same_reference, confidence, createdBy: auto|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"|"group", username, access, inherit, expiresAt (ms|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"|"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"|"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. |