SPB Git

Repository Public

api-contract.md 6.4 KB

# SP Mail — contrat d'API (v1)

Base : https://mail.spboucher.ai (dev : http://localhost:8731, lancé par scripts/dev.sh node dist/server.mjs). Erreurs : statut HTTP + {"error":"code","message":"…"}. Toutes les routes /api/* répondent cache-control: no-store.

# Authentification des requêtes

Client Session Requêtes non-GET
Web cookie __Host-spmail_session (HttpOnly, SameSite=Strict), posé par le serveur en-têtes Origin = origine du site et X-SPMail: 1
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

client (optionnel, dans les corps de login/verify et enroll/verify) : {"kind":"web"|"native","deviceName":"MacBook de …","platform":"macOS 27"}.

# Identité (passkeys WebAuthn ; RP ID = mail.spboucher.ai)

Route Corps → Réponse
POST /api/login/options {} → {challenge_id, options} (options = PublicKeyCredentialRequestOptions JSON, identifiant découvrable, aucun nom d'utilisateur)
POST /api/login/verify {challenge_id, response, client?} → {ok, token?} (response = AuthenticationResponseJSON, champs en base64url)
POST /api/enroll/check {token} → `{purpose: "bootstrap"
POST /api/enroll/options {token, handle?, display_name?} (requis sauf recover) → {challenge_id, options} (création)
POST /api/enroll/verify {challenge_id, response, label?, client?} → {ok, token?} (RegistrationResponseJSON)
POST /api/logout → {ok}
GET /api/me → {user:{id,handle,display_name,role,prefs}, session:{id,kind}, mailboxes:[{id,address,display_name,position}], version}
PUT /api/profile {display_name}
GET /api/usage [{id,address,used_bytes}] pour les boîtes de l'utilisateur
PUT /api/prefs objet JSON libre (≤ 20 ko) remplaçant user.prefs
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)
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
POST /api/push/register natif : `{apns_token (hex), environment: "production"

Apps Apple : Associated Domains webcredentials:mail.spboucher.ai ; /.well-known/apple-app-site-association liste les App ID autorisés.

# Courrier : JMAP standard (RFC 8620/8621) par la passerelle

Une « boîte » SP Mail (mailboxes[].id, UUID, noté {mb}) = un compte du serveur Stalwart. Le client ne voit jamais d'identifiant Stalwart.

Route Rôle
GET /api/jmap/{mb}/session objet Session JMAP ; ses URL pointent déjà vers la passerelle
POST /api/jmap/{mb}/api requête JMAP {using, methodCalls} (≤ 10 Mo, ≤ 16 appels)
POST /api/jmap/{mb}/upload/{accountId}/ corps binaire brut, Content-Type du fichier (≤ 50 Mo) → {accountId, blobId, type, size}
GET /api/jmap/{mb}/download/{accountId}/{blobId}/{name}?accept={type}[&inline=1] toujours attachment + CSP: sandbox, sauf inline=1 pour `image/png
GET /api/jmap/{mb}/eventsource?types=*&closeafter=no&ping=30 SSE event: state (changements d'état, jamais de contenu)

Capacité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. accountId = session.primaryAccounts["urn:ietf:params:jmap:mail"].

Recettes vérifiées par tests/integration/api.test.ts :

  • Dossiers : Mailbox/get (rôles inbox, drafts, sent, trash, junk, archive), Mailbox/set.
  • 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.
  • Synchro delta : Email/changes, Mailbox/changes, Thread/changes à partir du state conservé ; si cannotCalculateChanges → resynchronisation complète.
  • Drapeaux : Email/set update {"keywords/$seen": true}, $flagged, $draft, $answered, $forwarded ; déplacement = patch de mailboxIds.
  • 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}.
  • Identités / signatures : Identity/get|set (name, email, textSignature, htmlSignature).
  • Règles : SieveScript/get|set ; réponse automatique : VacationResponse/get|set.
  • Recherche plein texte : Email/query filter {text|from|to|subject|body|hasAttachment|before|after}.

# Images distantes

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.

# Administration (role = admin)

Route Rôle
GET /api/admin/overview {server:{reachable,latency_ms}, domains, accounts:[{id,address,description,used_bytes,aliases}], queue:[…enveloppes], certificates, backup, counts}
GET /api/admin/dns par domaine : {mx,spf,dkim,dmarc,mxHost,ptr} chacun avec ok et les enregistrements lus en direct
GET /api/admin/users utilisateurs + boîtes
POST /api/admin/mailboxes {address, display_name?, user_id?} crée le compte de courrier et le rattache (409 si l'adresse existe)
POST /api/admin/mailboxes/adopt rattache un compte de courrier existant
PUT /api/admin/mailboxes/:id/aliases {aliases:[…]} alias
DELETE /api/admin/mailboxes/:id[?purge=delete-all-mail] détache ; supprime le courrier seulement avec purge
POST /api/admin/queue/:id/retry · GET /api/admin/audit file d'attente, journal d'audit

GET /api/health/live, GET /api/health/ready : sans authentification.

Files main
Menu

Theme