SPB Git

Repository Public

api-contract.md 6.4 KB 78 lines markdown

1# SP Mail — contrat d'API (v1)23Base : `https://mail.spboucher.ai` (dev : `http://localhost:8731`, lancé par `scripts/dev.sh node dist/server.mjs`).4Erreurs : statut HTTP + `{"error":"code","message":"…"}`. Toutes les routes `/api/*` répondent `cache-control: no-store`.56## Authentification des requêtes78| Client | Session | Requêtes non-GET |9|---|---|---|10| Web | cookie `__Host-spmail_session` (HttpOnly, SameSite=Strict), posé par le serveur | en-têtes `Origin` = origine du site **et** `X-SPMail: 1` |11| Natif (macOS/iOS) | `Authorization: Bearer <jeton>` — rendu **une fois** par `login/verify` ou `enroll/verify` quand `client.kind = "native"` ; à ranger au trousseau | **aucune** en-tête `Origin` ; avant connexion ajouter `X-SPMail-Client: native` |1213`client` (optionnel, dans les corps de `login/verify` et `enroll/verify`) : `{"kind":"web"|"native","deviceName":"MacBook de …","platform":"macOS 27"}`.1415## Identité (passkeys WebAuthn ; RP ID = `mail.spboucher.ai`)1617| Route | Corps → Réponse |18|---|---|19| `POST /api/login/options` | `{}` → `{challenge_id, options}` (`options` = PublicKeyCredentialRequestOptions JSON, identifiant découvrable, aucun nom d'utilisateur) |20| `POST /api/login/verify` | `{challenge_id, response, client?}` → `{ok, token?}` (`response` = AuthenticationResponseJSON, champs en base64url) |21| `POST /api/enroll/check` | `{token}` → `{purpose: "bootstrap"|"recover"|"invite", user}` — le jeton vient du lien `/enroll#<token>` |22| `POST /api/enroll/options` | `{token, handle?, display_name?}` (requis sauf `recover`) → `{challenge_id, options}` (création) |23| `POST /api/enroll/verify` | `{challenge_id, response, label?, client?}` → `{ok, token?}` (RegistrationResponseJSON) |24| `POST /api/logout` | → `{ok}` |25| `GET /api/me` | → `{user:{id,handle,display_name,role,prefs}, session:{id,kind}, mailboxes:[{id,address,display_name,position}], version}` |26| `PUT /api/profile` | `{display_name}` |27| `GET /api/usage` | `[{id,address,used_bytes}]` pour les boîtes de l'utilisateur |28| `PUT /api/prefs` | objet JSON libre (≤ 20 ko) remplaçant `user.prefs` |29| `GET /api/passkeys` · `POST /api/passkeys/options` · `POST /api/passkeys/verify {challenge_id,response,label}` · `DELETE /api/passkeys/:id` | gestion des clés (la dernière ne peut pas être retirée) |30| `GET /api/sessions` · `DELETE /api/sessions/:id` | appareils connectés `[{id,kind,device_name,platform,ip,user_agent,created_at,last_seen_at,current}]`, révocation |31| `POST /api/push/register` | natif : `{apns_token (hex), environment: "production"|"sandbox", bundle_id}` |3233Apps Apple : Associated Domains `webcredentials:mail.spboucher.ai` ; `/.well-known/apple-app-site-association` liste les App ID autorisés.3435## Courrier : JMAP standard (RFC 8620/8621) par la passerelle3637Une « boîte » SP Mail (`mailboxes[].id`, UUID, noté `{mb}`) = un compte du serveur Stalwart. Le client ne voit jamais d'identifiant Stalwart.3839| Route | Rôle |40|---|---|41| `GET /api/jmap/{mb}/session` | objet Session JMAP ; ses URL pointent déjà vers la passerelle |42| `POST /api/jmap/{mb}/api` | requête JMAP `{using, methodCalls}` (≤ 10 Mo, ≤ 16 appels) |43| `POST /api/jmap/{mb}/upload/{accountId}/` | corps binaire brut, `Content-Type` du fichier (≤ 50 Mo) → `{accountId, blobId, type, size}` |44| `GET /api/jmap/{mb}/download/{accountId}/{blobId}/{name}?accept={type}[&inline=1]` | toujours `attachment` + `CSP: sandbox`, sauf `inline=1` pour `image/png|jpeg|gif|webp` |45| `GET /api/jmap/{mb}/eventsource?types=*&closeafter=no&ping=30` | SSE `event: state` (changements d'état, jamais de contenu) |4647Capacités utilisables : `urn:ietf:params:jmap:core`, `:mail`, `:submission`, `:vacationresponse`, `:sieve`, `:blob`, `:quota`, `:contacts`, `:calendars`. Refusés (403) : `urn:stalwart:jmap` et toute méthode `x:*`. Pas de WebSocket.48`accountId` = `session.primaryAccounts["urn:ietf:params:jmap:mail"]`.4950Recettes vérifiées par `tests/integration/api.test.ts` :51- Dossiers : `Mailbox/get` (rôles `inbox`, `drafts`, `sent`, `trash`, `junk`, `archive`), `Mailbox/set`.52- Liste : `Email/query` (`filter.inMailbox`, `filter.text`, `sort: [{property:"receivedAt",isAscending:false}]`, `collapseThreads`) + `Email/get` par référence de résultat ; fil : `Thread/get`.53- Synchro delta : `Email/changes`, `Mailbox/changes`, `Thread/changes` à partir du `state` conservé ; si `cannotCalculateChanges` → resynchronisation complète.54- Drapeaux : `Email/set update {"keywords/$seen": true}`, `$flagged`, `$draft`, `$answered`, `$forwarded` ; déplacement = patch de `mailboxIds`.55- Envoi : `Email/set create` (brouillon, `bodyValues` + `textBody`/`htmlBody`, `attachments:[{blobId,type,name,disposition}]`) puis `EmailSubmission/set create {identityId, emailId}` avec `onSuccessUpdateEmail` (brouillons → envoyés). **Création acceptée = « accepté pour livraison », pas « remis »** : l'état réel se lit dans `EmailSubmission/get → deliveryStatus[destinataire].{delivered: "queued"|"yes"|"no"|"unknown", smtpReply}`.56- Identités / signatures : `Identity/get|set` (`name`, `email`, `textSignature`, `htmlSignature`).57- Règles : `SieveScript/get|set` ; réponse automatique : `VacationResponse/get|set`.58- Recherche plein texte : `Email/query filter {text|from|to|subject|body|hasAttachment|before|after}`.5960## Images distantes6162`GET /api/img?u=<url encodée>` — seulement sur action explicite (« afficher les images »). Refuse toute destination privée/locale, tout ce qui n'est pas une image matricielle (pas de SVG), > 10 Mo.6364## Administration (`role = admin`)6566| Route | Rôle |67|---|---|68| `GET /api/admin/overview` | `{server:{reachable,latency_ms}, domains, accounts:[{id,address,description,used_bytes,aliases}], queue:[…enveloppes], certificates, backup, counts}` |69| `GET /api/admin/dns` | par domaine : `{mx,spf,dkim,dmarc,mxHost,ptr}` chacun avec `ok` et les enregistrements lus en direct |70| `GET /api/admin/users` | utilisateurs + boîtes |71| `POST /api/admin/mailboxes {address, display_name?, user_id?}` | crée le compte de courrier et le rattache (409 si l'adresse existe) |72| `POST /api/admin/mailboxes/adopt` | rattache un compte de courrier existant |73| `PUT /api/admin/mailboxes/:id/aliases {aliases:[…]}` | alias |74| `DELETE /api/admin/mailboxes/:id[?purge=delete-all-mail]` | détache ; supprime le courrier seulement avec `purge` |75| `POST /api/admin/queue/:id/retry` · `GET /api/admin/audit` | file d'attente, journal d'audit |7677`GET /api/health/live`, `GET /api/health/ready` : sans authentification.78
Files main
Menu

Theme