> ## Documentation Index > Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt > Use this file to discover all available pages before exploring further. # JMAP Core > La couche Core de la RFC 8620 telle que OxiMail l'implémente : la ressource session, l'authentification, les requêtes groupées, les références arrière, les capacités et le push. JMAP (JSON Meta Application Protocol) est l'API que parle OxiMail pour le courrier, les agendas, les contacts, les tâches, les fichiers et le chat. Cette page couvre la couche **Core** de la [RFC 8620](https://www.rfc-editor.org/rfc/rfc8620) : comment un client découvre le serveur, s'authentifie, groupe plusieurs appels de méthode dans une seule requête HTTP, enchaîne ces appels avec des références arrière, déclare les capacités qu'il utilise, et reçoit les notifications push. Tout ce qui suit décrit ce que OxiMail expose réellement en v0.30.0. Les jeux de méthodes par domaine s'appuient sur cette couche : voir [JMAP Mail](./jmap-mail), [Agendas](./jmap-calendar), [Contacts](./jmap-contacts), [Tâches](./jmap-tasks), [Fichiers](./jmap-files), [Partage](./jmap-sharing) et [Chat](./jmap-chat). ## La ressource session Un client JMAP commence par récupérer la **ressource session**. C'est le document de découverte unique qui indique au client tout ce dont il a besoin : les capacités prises en charge par le serveur, les comptes accessibles à l'utilisateur, et les URL de toutes les autres opérations. ```http theme={null} GET /.well-known/jmap Authorization: Bearer ``` Le point d'accès de la session est **authentifié** : il faut présenter un token valide pour le récupérer. La réponse est un objet JSON (RFC 8620 §2) qui contient les champs suivants. | Champ | Contenu | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capabilities` | La table des capacités au niveau serveur : chaque URN de capacité associée à son objet de configuration (limites, options). | | `accounts` | Chaque compte accessible à cet utilisateur, indexé par identifiant de compte. Chaque entrée contient `name`, `isPersonal`, `isReadOnly` et ses propres `accountCapabilities`. | | `primaryAccounts` | Pour chaque URN de capacité, l'identifiant du compte considéré comme principal. | | `username` | Le nom de l'utilisateur authentifié (son adresse e-mail). | | `apiUrl` | Le point d'accès où envoyer les appels de méthode : `/jmap`. | | `uploadUrl` | Le modèle d'URL pour l'envoi de blobs : `/jmap/upload/{accountId}`. | | `downloadUrl` | Le modèle d'URL pour le téléchargement de blobs : `/jmap/download/{accountId}/{blobId}/{name}?type={type}`. | | `eventSourceUrl` | Le modèle d'URL pour le push (EventSource) : `/jmap/eventsource/?types={types}&closeafter={closeafter}&ping={ping}`. | | `state` | Une chaîne opaque qui change dès que l'objet session lui-même change (par exemple lorsqu'un compte est ajouté). | ### Ne jamais coder les chemins en dur Les trois champs `*Url` sont des **modèles d'URL** ([RFC 6570](https://www.rfc-editor.org/rfc/rfc6570)) : un client, en particulier une intégration sans état comme un worker serverless ou un script cron, doit les lire depuis la session et substituer les variables (`{accountId}`, `{blobId}`, ...), jamais reconstruire les chemins de mémoire d'après la disposition d'un autre serveur. Ce n'est pas théorique. Le point d'envoi d'OxiMail est `/jmap/upload/{accountId}` **sans barre oblique finale** (routage strict) ; d'autres serveurs JMAP utilisent `/jmap/upload/{accountId}/`. Un client qui code la forme avec barre oblique reçoit un `404` à chaque envoi, et le bug ressemble à une panne serveur. Lire `uploadUrl` depuis la session rend le même code client compatible avec n'importe quel serveur RFC 8620. Un client sans état n'a pas besoin de récupérer la session à chaque invocation : 1. `GET /.well-known/jmap` une fois, mettre en cache l'objet de session avec sa chaîne `state`. 2. À chaque exécution, utiliser directement les modèles en cache. 3. Chaque réponse de méthode JMAP porte un `sessionState` : quand il ne correspond plus au `state` en cache (ou qu'une URL substituée se met à répondre `404`), récupérer la session à nouveau et remplacer le cache. L'objet de la capacité `Core` annonce aussi les limites strictes du serveur, qu'un client doit respecter avant d'envoyer une requête. | Limite | Valeur en v0.30.0 | | ----------------------- | ----------------- | | `maxSizeUpload` | 50 Mo | | `maxConcurrentUpload` | 4 | | `maxSizeRequest` | 10 Mo | | `maxConcurrentRequests` | 8 | | `maxCallsInRequest` | 64 | | `maxObjectsInGet` | 500 | | `maxObjectsInSet` | 500 | Un utilisateur peut voir plus d'un compte dans la session. Outre son compte personnel, tout dossier, agenda ou carnet d'adresses partagé avec lui via le [partage JMAP](./jmap-sharing) apparaît comme une entrée de compte supplémentaire (indexée `shared:{ownerId}`), qui ne porte que les capacités partagées et parfois `isReadOnly: true`. ## Authentification OxiMail utilise des tokens **Bearer** ([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)). On obtient un token en envoyant les identifiants au point d'accès de connexion. ```http theme={null} POST /auth/login Content-Type: application/json { "email": "alice@example.com", "password": "..." } ``` La réponse renvoie le token et l'identifiant du compte. ```json theme={null} { "accessToken": "...", "accountId": "..." } ``` Envoyez ce token sur chaque requête suivante. ```http theme={null} Authorization: Bearer ``` ### Durée de vie et renouvellement du token Les tokens expirent **24 heures** après leur émission. Pour rester connecté sans ressaisir de mot de passe, renouvelez le token. ```http theme={null} POST /auth/refresh Authorization: Bearer ``` Si le token est encore valide, ou expiré depuis **moins de 7 jours**, le serveur supprime l'ancien token et en renvoie un nouveau avec une nouvelle expiration à 24 heures. Le format de la réponse est le même que pour la connexion : `{ "accessToken": "...", "accountId": "..." }`. Passé le délai de grâce de 7 jours, le renouvellement échoue avec un `401` et l'utilisateur doit se reconnecter. ### Tokens liés à l'appareil DPoP (RFC 9449) Un client peut activer la **preuve de possession** à la connexion en envoyant une preuve DPoP (un JWT signé par une clé ES256 éphémère) avec ses identifiants. La session est alors liée à cette clé : `POST /auth/refresh` exige une preuve fraîche signée par la même clé. Un bearer token volé seul ne peut donc plus être renouvelé. Deux couches de durcissement côté serveur prolongent ce mécanisme. Les deux sont configurables et désactivées par défaut : * **Nonce serveur (§8).** Chaque réponse d'authentification porte un en-tête `DPoP-Nonce`. Une preuve qui contient une revendication `nonce` est toujours vérifiée contre lui. Un nonce périmé répond `401` avec l'erreur `use_dpop_nonce` et un nonce frais, et le client réessaie (la séquence standard de la RFC 9449). Avec `[auth] dpop_nonce_required = true`, le serveur rejette en plus les preuves sans nonce : la fraîcheur contrôlée par le serveur remplace la fenêtre d'horloge. * **Preuve de possession par requête (§7).** Avec `[auth] dpop_resource = "require"`, une session liée par DPoP doit envoyer une preuve sur **chaque** requête qui présente son token dans l'en-tête `Authorization`, liée à ce token par la revendication `ath`. Un bearer volé ne peut alors plus appeler JMAP du tout, et pas seulement plus se renouveler. `"monitor"` journalise ce que `require` rejetterait, pour un déploiement sans risque. Les sessions qui n'ont jamais lié de clé et les mots de passe d'application ne sont pas concernés. La comparaison `htu` normalise les ports par défaut selon la RFC 3986 §6.2 (un `:443` explicite d'un côté ou de l'autre correspond quand même). Comme les éléments médias (`