@design-edito/publisher-core 0.0.1

package/README.md

@@ -0,0 +1,265 @@
+# LM-Publisher
+
+`lm-publisher`, est serveur qui ne répond que du JSON ou des fichiers, pas de frontend.
+
+## API
+
+Il y a pour l'instant 5 types de réponses : `void`, `file`, `json`, `list`, `error`. Si le serveur ne répond pas une réponse de type `error`, c'est que l'opération a abouti. Ci-dessous, d'abord le détail des réponses HTTP avec les headers avant de détailler la forme de la donnée JSON reçue pour les réponses de type `json`, `list` et `error`.
+
+### Les réponses HTTP
+
+#### Type VOID
+
+Une réponse de type `void`, est une réponse vide avec un statut HTTP 204, ce sont des opérations qui ne nécessitent pas de récupérer de la donnée en réponse. Ça ne va pas concerner beaucoup de routes normalement, typiquement :
+
+  - `POST /auth/logout`
+  - `POST /auth/logout-everywhere`
+  - `POST /auth/refresh-token (celle là elle est un peu spéciale, more on that later)`
+  - `POST /auth/request-email-verification-token`
+  - `POST /auth/submit-new-password`
+  - Quelques autres dans la section `/storage` du serveur, mais cette partie là est encore expérimentale, on va pas en avoir besoin tout de suite
+
+Le détail de comment la réponse est formée :
+
+```ts
+// Headers par défaut pour chaque route (possiblement overridées plus bas en fonction du type de réponse)
+res.setHeader('Cache-Control', 'no-store')
+    .setHeader('Content-Security-Policy', `default-src 'none';`)
+    .setHeader('Referrer-Policy', 'no-referrer')
+    .setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+    .setHeader('X-Content-Type-Options', 'nosniff')
+    .setHeader('X-Request-ID', initMeta.requestId)
+    .setHeader('X-Response-Time', `${Date.now() - initMeta.timestamp}ms`)
+    .setHeader('X-Server-Meta', JSON.stringify({
+      userId: initMeta.userId,
+      requestId: initMeta.requestId,
+      timestamp: initMeta.timestamp
+    }))
+// Fin des headers par défaut
+    .status(204)
+    .end()
+```
+
+#### Type FILE
+
+Lorsque le serveur répond par un fichier.
+
+> Note pour plus tard : pour l'instant elle n'est implémentée nulle part, mais on va en faire usage pour nos générateurs d'image, et après réflexion, on va pas passer par un truc intermédiaire de genre la route renvoie une liste d'urls temporaires sur lesquelles trouver les fichiers, on va effectivement répondre un zip, j'ai vu qu'on pouvait unzip côté client et récupérer le contenu des images, donc on va faire comme ça je pense. Anyway, la réponse est créée comme ça :
+
+```ts
+// Headers par défaut, puis
+res.status(fileResponse.httpStatus)
+    .type(fileResponse.contentType)
+    .setHeader('Content-Disposition', `attachment; filename="${fileResponse.filename}"; filename*=UTF-8''${encodeURIComponent(fileResponse.filename)}`)
+    .setHeader('Cache-Control', fileResponse.cacheControl)
+    .setHeader('Content-Length', fileResponse.contentLengthBytes)
+```
+Ensuite, soit le fichier est envoyé d'un bloc via `res.send(fileBuffer)` parce que c'est un buffer côté serveur, soit il est "streamé" via `fileStream.pipe(res)`.
+
+> Qu'est-ce que ça veut dire ? Aucune idée.
+
+#### Type JSON et LIST
+
+Pour la plupart des routes, le serveur va répondre du JSON :
+- soit un seul objet (type `json`) :
+    ```ts
+        // Réponse JSON, headers par défaut, puis
+        res.status(fullJsonResponse.httpStatus)
+            .type('application/json; charset=utf-8')
+            .setHeader('Content-Disposition', 'inline')
+            .json(fullJsonResponse)
+    ```
+- soit une liste d'objets partielle et paginée (type `list`) :
+    ```ts    
+    // Réponse LIST, headers par défaut, puis
+    res.status(fullListResponse.httpStatus)
+        .type('application/json; charset=utf-8')
+        .setHeader('Content-Disposition', 'inline')
+        .setHeader('X-Total-Count', fullListResponse.total)
+        .setHeader('X-Page', fullResponse.page)
+        .setHeader('X-Next-Page', fullListResponse.next ?? '')
+        .setHeader('X-Prev-Page', fullListResponse.prev ?? '')
+        .json(fullListResponse)
+    ```
+
+#### Type ERROR
+
+À chaque fois que quelque chose s'est mal passé, soit côté client (auth manquante, requête malformée, ...), soit côté serveur (mauvaise implémentation, db non accessible, etc...) :
+
+```ts
+// Headers par défaut
+res.status(fullResponse.httpStatus)
+    .type('application/problem+json')
+    .setHeader('Content-Disposition', 'inline')
+    .json(fullResponse)
+```
+
+### Le contenu des réponses JSON, LIST et ERROR
+
+Quand le serveur renvoie autre chose qu'une réponse `void` ou `file`, il renvoie du JSON dans `response.body`. La structure sera toujours :
+
+```ts
+type ServerErrorResponse<C extends Codes> = {
+  success: false
+  httpStatus: number
+  type: 'error'
+  error: ErrorData<C> // Voir plus bas
+  meta: {
+    userId: string | null
+    requestId: string
+    timestampMs: number
+    elapsedMs: number
+  }
+}
+
+type ServerJsonResponse<P extends object> = {
+  success: true
+  httpStatus: number
+  type: 'json'
+  payload: P
+  meta: {
+    userId: string | null
+    requestId: string
+    timestampMs: number
+    elapsedMs: number
+  }
+}
+
+type ServerListResponse<P extends object> = {
+  success: true
+  httpStatus: number
+  type: 'list'
+  payload: P[]
+  page: number
+  total: number
+  prev: string | null
+  next: string | null
+  meta: {
+    userId: string | null
+    requestId: string
+    timestampMs: number
+    elapsedMs: number
+  }
+}
+```
+
+Ce qui compte, c'est le contenu de `response.body.error` ou `response.body.payload`, et éventuellement les détails de pagination pour les réponses `list`: `page`, `total`, `prev` (`null` si première), `next` (`null` si dernière).
+
+### Routes, Méthodes, Requêtes et Réponses
+
+Toute la partie API du serveur est définie à partir d'ici :
+https://github.com/lm-design-edito/lm-publisher/tree/master/src/api
+
+Dans [/api/index.ts](https://github.com/lm-design-edito/lm-publisher/blob/master/src/api/index.ts), il y a :
+
+```ts
+enum ENDPOINT = {
+    // Liste des endpoints sous la forme METHOD:PATH, ex: GET:/system/status-check, POST:/auth/login, etc...
+}
+
+const ROUTES = {
+    [ENDPOINT]: handlerFunction
+}
+```
+
+Ensuite, chaque handler est défini dans son sous-dossier dans [/api](https://github.com/lm-design-edito/lm-publisher/blob/master/src/api), exemple : [/api/auth/login](https://github.com/lm-design-edito/lm-publisher/blob/master/src/api/auth/login)
+
+Pour chaque sous-dossier de handler, il y a :
+- `index.ts` — Rien d'intéressant ici
+- `operation.ts` — La fonction qui est éxécutée pour effectuer l'opération. On y trouve normalement toujours :
+    - `const silentOperation`, le cœur de la fonction éxécutée
+    - `const operation`, la fonction embarquant les logs qu'elle implique
+    - `type OperationErrorCodes`, la liste des codes d'erreurs que peut renvoyer l'opération
+    - `type DTO`, le "[data transfer object](https://en.wikipedia.org/wiki/Data_transfer_object)", c'est à dire la forme de l'objet qu'on va trouver dans `response.body.payload`, si la réponse est de type `json` ou `list`
+- `validation.ts` — Optionnel, la fonction qui s'occupe de valider l'input utilisateur avant de la passer à `operation.ts`. On y trouve :
+    - `type ExpectedBody`, qui décrit la forme de l'objet à envoyer via `request.body` pour passer la validation
+    - Plus tard, potentiellement `type ExpectedQuery`, je ne vois pas trop de cas d'usage à transmettre de la donnée via les query params de l'URL, à part pour une route qui répondrait une liste, `?page=2` pourrait avoir du sens.
+- `authentication.ts` — Optionnel, la fonction qui s'occupe de savoir si l'utilisateur qui fait la reqûete a les droits suffisants. Normalement assez straigntforward, ça ressemblera très souvent à ça : [/api/storage/credentials/create/authentication.ts](https://github.com/lm-design-edito/lm-publisher/blob/master/src/api/storage/credentials/create/authentication.ts)
+
+### Les codes d'erreur
+
+La liste des codes d'erreurs que peut renvoyer le serveur en cas de réponse de type `error`, ainsi que le message et l'objet de détails qui y sont associés (`ErrorData<Code>`) est trouvable sur : [/errors/index.ts](https://github.com/lm-design-edito/lm-publisher/blob/master/src/errors/index.ts)
+
+## Authentification
+
+L'authentification d'un client lorsqu'il envoie une requête au serveur repose sur deux concepts :
+- Des [JSON Web Tokens](https://fr.wikipedia.org/wiki/JSON_Web_Token), avec une logique de access & refresh tokens
+- Une protection contre les [attaques CSRF](https://fr.wikipedia.org/wiki/Cross-site_request_forgery), via le package NPM [csurf](https://www.npmjs.com/package/csurf), qui... a été archivé la veille de la rédaction de ce README 😭😭😭😭. Il n'y a pas trop de raison de bouger pour l'instant et surtout pas d'autre solution viable donc on va continuer et régler ça plus tard.
+
+### CSRF
+
+Que l'on fasse une requête sur un endpoint qui demande l'authentification ou non, si la requête n'est pas en `GET`, la protection CSRF va s'interposer en premier, et par défaut, elle va répondre une réponse de type `error`, avec le code `invalid-csrf-token`.
+
+Avant toute requête hors `GET`, il faut donc aller récupérer le token généré par le serveur, sur `/csrf/get-token`. Dans l'idée :
+
+```ts
+const res = await fetch('https://<hostname>/csrf/get-token', { credentials: 'include' })
+const data = await res.json()
+const csrfToken = data.payload.token
+```
+
+Ensuite, le token vit uniquement dans la mémoire, dans une variable, et disparait donc quand l'onglet ou le navigateur est fermé. Une fois le token récupéré, les requêtes doivent embarquer le header `'X-CSRF-Token': csrfToken`, et spécifier `credentials: 'include'`. Ex: 
+
+```ts
+await fetch('https://<hostname>/some/path', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRF-Token': csrfToken
+  },
+  credentials: 'include',
+  body: JSON.stringify({ ... })
+})
+```
+
+Le token a une durée de vie de 2h, il faut aller le générer à nouveau sur `/csrf/get-token` à chaque fois que le serveur répond `invalid-csrf-token` (en limitant les retries successifs, si la procédure ne fonctionne pas du premier coup, c'est probablement qu'il y a un problême côté serveur).
+
+### JWT
+
+Dans l'idée, lorsqu'un client va s'authentifier sur `/auth/login`, si l'authentification réussit, le serveur va répondre avec :
+- Un access token via le Header `X-Access-Token` :
+    ```ts
+    res.setHeader('X-Access-Token', `Bearer ${token}`)
+    ```
+- Un refresh token via le cookie `refreshToken` :
+    ```ts
+    res.cookie('refreshToken', token, {
+        httpOnly: true,
+        secure: MODE === 'production',
+        sameSite: 'none',
+        expires: new Date(Date.now() + REFRESH_TOKEN_EXPIRATION_SECONDS * 1000)
+    })
+    ```
+
+Une fois ces tokens récupérés, le client doit idéalement persister la valeur de l'access token dans `localStorage` ou `sessionStorage`. Il peut le garder uniquement en mémoire dans une variable comme le token CSRF, mais en revanche il ne doit **SURTOUT PAS** être persisté via un cookie. La valeur de cet `accessToken` est ensuite utilisée pour chaque requête (du moins celles qui nécessitent authentification, mais c'est bien de le mettre tout le temps) :
+
+```ts
+await fetch('https://<hostname>/some/path', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${accessToken}`,
+    'X-CSRF-Token': csrfToken
+  },
+  body: JSON.stringify({ ... }),
+  credentials: 'include'
+})
+```
+
+Si l'`accessToken` a expiré, le serveur ne va pas forcément répondre par une erreur explicite. Le middleware chargé de récupérer le contenu du token dans le header va juste considérer que la requête vient d'un utilisateur qui n'est pas authentifié, laisse passer la requête qui continue sa route vers le handler correspondant à l'URL demandée, qui lui se charge de répondre que l'utilisateur n'est pas authentifié si la route est protégée, via le code d'erreur `user-not-authenticated`.
+
+Il faut donc à ce moment demander un renouvellement de l'`accessToken`, sur `/auth/refresh-token`. Pour ce faire, pas besoin de se préoccuper de la valeur du `refreshToken` : le serveur nous l'a fourni initialement via un cookie dont le contenu n'est pas accessible à JavaScript, et sera automatiquement inclus dans la requête :
+
+```ts
+await fetch('https://<hostname>/auth/refresh-token', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRF-Token': csrfToken
+  },
+  credentials: 'include'
+})
+```
+
+[WIP] à continuer, détails sur les erreurs retournées par `/auth/refresh-token`, etc...
+

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function start(): Promise<void>;