@kourouma/express-authkit 0.0.0-stage → 0.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Historique des versions
+
+Toutes les évolutions notables d'Express AuthKit sont consignées ici.
+
+Le format s'inspire de [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/)
+et le projet suit le [Versionnage sémantique](https://semver.org/lang/fr/).
+
+## Politique de versions
+
+- **MAJEURE** (`1.0.0` → `2.0.0`) : changement incompatible de l'API publique
+  (exports, signatures, codes d'erreur, format de `req.auth`).
+- **MINEURE** (`0.1.0` → `0.2.0`) : nouvelle fonctionnalité rétrocompatible.
+- **CORRECTIF** (`0.1.0` → `0.1.1`) : correction de bug ou de sécurité rétrocompatible.
+
+Tant que le projet est en `0.x`, une version mineure peut contenir des
+changements incompatibles ; ils seront toujours signalés dans ce fichier
+sous la rubrique **Incompatible**. L'API publique se limite aux exports de
+`@kourouma/express-authkit` et `@kourouma/express-authkit/express`.
+
+## [Non publié]
+
+## [0.1.0] — candidate
+
+Le paquet est publié sous le nom **`@kourouma/express-authkit`** : npm refuse le nom
+`express-authkit`, jugé trop proche du paquet existant `express-auth-kit`. La commande
+`npx express-authkit` garde son nom.
+
+### Ajouté
+
+- `createAuthKit()` : moteur d'authentification configurable par injection de dépendances.
+- Hachage et vérification des mots de passe avec Argon2id (`auth.password.hash()`, `auth.password.verify()`).
+- Émission de JWT d'accès signés HMAC (HS256 par défaut) avec `jose`, en-tête `typ: at+jwt`.
+- Vérification stricte des JWT : signature, algorithme autorisé, `exp`, `iat`, `iss`, `aud`, `sub`, `jti`.
+- `auth.login()` : authentification identifiant / mot de passe avec message d'erreur générique
+  et atténuation des écarts de temps de réponse pour les comptes inexistants.
+- `auth.verifyAccessToken()` : contrôle de l'existence et du statut actif de l'utilisateur à chaque requête.
+- Adaptateur Express `createExpressAuth()` : `authenticate()`, `login()` et `errorHandler()`.
+- Contrats `UserRepository`, `PasswordProvider`, `TokenProvider` documentés en JSDoc et vérifiés au démarrage.
+- Erreurs structurées avec codes stables (`AUTH_ERROR_CODES`).
+- Validation de la configuration : secret absent, court ou manifestement faible refusé,
+  paramètres Argon2id sous le plancher OWASP refusés, options inconnues refusées.
+- `expressAuth.login(options?)` : handler de connexion prêt à l'emploi
+  (`app.post("/login", express.json(), expressAuth.login())`), avec l'option `identifierField`.
+  Il ne crée aucune route : l'application choisit l'URL.
+- Commande `npx express-authkit secret` pour générer un secret JWT.
+- Les `id` renvoyés par le repository peuvent être des entiers, des `BigInt` ou des `ObjectId`
+  MongoDB : ils sont convertis automatiquement en chaîne.
+- Tous les messages d'erreur sont en français, centralisés dans un seul module, et indiquent
+  comment corriger le problème. Les codes d'erreur restent stables (en anglais).
+- `DependencyFailureError` (`DEPENDENCY_FAILURE`) : toute panne d'un repository ou d'un provider
+  est enveloppée, avec `dependency` (l'appel qui a échoué) et `cause` (l'erreur d'origine).
+- `AuthKitError#toJSON()` : sérialisation sûre `{ name, code, message }`, sans pile ni cause.
+- `expressAuth.errorHandler()` convertit aussi les erreurs du parseur `express.json()`
+  (JSON mal formé → 400, corps trop volumineux → 413) en réponses JSON.
+- Oublier les parenthèses (`expressAuth.authenticate` au lieu de `expressAuth.authenticate()`)
+  lève une `ConfigurationError` explicite au lieu de bloquer la requête.
+- `expressAuth.login({ identifierField })` cite le vrai nom du champ dans ses messages.
+- **Refresh tokens** (option `refreshTokens: { store, expiresInSeconds }`, désactivée par défaut) :
+  `auth.refresh()`, `auth.logout()`, `auth.revokeAllSessions()`, handlers Express
+  `expressAuth.refresh()` et `expressAuth.logout()`. Jetons opaques de 256 bits, stockés sous forme
+  d'empreinte SHA-256, rotation à chaque usage, révocation de toute la session en cas de
+  réutilisation. Contrat `RefreshTokenStore` (`save`, `consume`, `revokeFamily`, `revokeUser`),
+  `createInMemoryRefreshTokenStore()` pour le développement, exemple PostgreSQL documenté.
+- **Rôles et permissions** : `expressAuth.authorize(rule)` (rôle, `anyRole`, `allPermissions`,
+  règle `check` personnalisée), `isAuthorized()` hors d'Express, nouvelle erreur
+  `AccessDeniedError` (`ACCESS_DENIED`, 403). Le repository peut renvoyer `roles` et
+  `permissions` : ils sont relus à chaque requête (changement immédiat), exposés dans
+  `req.auth`, et jamais écrits dans le JWT.
+- Nouvelle erreur `InvalidRefreshTokenError` (`REFRESH_TOKEN_INVALID`, 401).
+- **Types TypeScript** générés depuis le JSDoc (`types/*.d.ts`, champ `types` et conditions
+  `types` dans `exports`), avec `req.auth` typé pour Express. Script `npm run typecheck` :
+  le code source passe la vérification TypeScript en mode strict.
+- Le type de `jwt.secret` accepte `undefined` : `secret: process.env.AUTH_SECRET` compile en
+  TypeScript sans `!` (une valeur absente reste refusée au démarrage, avec un message clair).
+- Démarrage rapide TypeScript dans `docs/typescript.md`, compilé et exécuté par
+  `npm run test:package`, avec les trois différences à connaître par rapport aux exemples JavaScript.
+- `TokenProvider.issue()` est vérifié : un provider personnalisé qui renvoie un jeton mal formé
+  lève une `ContractViolationError`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Express AuthKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/assets/banner.jpeg" alt="Express AuthKit — authentification pour Express.js : Argon2id, JWT, middleware de protection des routes" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Express AuthKit
+
+**Ajoutez une connexion par e-mail et mot de passe à votre API Express, en quelques lignes, sans sacrifier la sécurité.**
+
+> Version 0.1.0 (candidate), pas encore publiée sur npm. Voir les [limites connues](docs/securite.md#limites-connues).
+
+---
+
+## En bref
+
+Express AuthKit s'occupe pour vous de quatre choses :
+
+1. **Stocker les mots de passe de façon sûre.** Vous ne gardez jamais le mot de passe, seulement une empreinte impossible à inverser.
+2. **Connecter un utilisateur.** S'il donne le bon mot de passe, il reçoit un *token* (un jeton signé, comme un badge d'accès temporaire).
+3. **Protéger vos routes.** Une route protégée refuse toute requête qui n'a pas de token valide.
+4. **Contrôler les droits.** Une route peut être réservée à un rôle (« admin ») ou à des permissions précises.
+
+Vous gardez votre base de données et votre modèle d'utilisateur. Vous écrivez seulement deux petites fonctions pour dire à la bibliothèque comment retrouver un utilisateur.
+
+## Les mots à connaître
+
+| Mot | En clair |
+| --- | --- |
+| **Hash** (empreinte) | Version brouillée du mot de passe, impossible à inverser. On stocke le hash, jamais le mot de passe. |
+| **Token** (JWT) | Jeton signé remis après la connexion. Le client le renvoie à chaque requête pour prouver qui il est. Il expire après 15 minutes par défaut. |
+| **Secret** | Longue chaîne aléatoire qui sert à signer les tokens. Elle doit rester secrète. |
+| **Middleware** | Fonction Express qui s'exécute avant votre route, par exemple pour vérifier le token. |
+| **Repository** | Petit objet qui sait retrouver un utilisateur dans **votre** base de données. |
+
+## Prérequis
+
+- **Node.js 22.12 ou plus récent** (la version 24 est recommandée).
+- **Express 4.21+ ou 5.x**.
+- Un projet en modules ES : `"type": "module"` dans `package.json`.
+
+## Installation
+
+```bash
+npm install @kourouma/express-authkit express
+```
+
+> Tant que le package n'est pas publié sur npm, créez l'archive avec `npm pack` dans ce dépôt,
+> puis installez-la dans votre projet : `npm install /chemin/vers/kourouma-express-authkit-0.1.0.tgz express`.
+
+## Démarrage en cinq minutes
+
+> **JavaScript ou TypeScript ?** Tous les exemples de cette documentation sont en **JavaScript**.
+> Vous utilisez **TypeScript** ? Suivez plutôt le [démarrage TypeScript](docs/typescript.md) :
+> même code, avec la configuration et les trois petites différences à connaître.
+
+**Étape 1 — Créez un projet**
+
+```bash
+mkdir mon-api && cd mon-api
+npm init -y
+npm pkg set type=module
+npm install @kourouma/express-authkit express
+```
+
+**Étape 2 — Créez un secret**
+
+Cette commande génère un secret aléatoire et l'enregistre dans un fichier `.env` :
+
+```bash
+echo "AUTH_SECRET=$(npx express-authkit secret)" > .env
+```
+
+Ne partagez jamais ce fichier et ne le mettez pas dans Git.
+
+**Étape 3 — Créez `server.js`**
+
+```javascript
+import express from "express";
+import { createAuthKit } from "@kourouma/express-authkit";
+import { createExpressAuth } from "@kourouma/express-authkit/express";
+
+// 1. Où trouver vos utilisateurs : ici une simple liste, pour la démonstration.
+//    En production, interrogez votre base (voir docs/repository-utilisateur.md).
+const users = [];
+const userRepository = {
+  findByIdentifier: async (email) => users.find((user) => user.email === email.toLowerCase()) ?? null,
+  findById: async (id) => users.find((user) => user.id === id) ?? null
+};
+
+// 2. Le moteur d'authentification (la configuration est vérifiée immédiatement).
+const auth = createAuthKit({
+  users: userRepository,
+  jwt: {
+    secret: process.env.AUTH_SECRET,
+    issuer: "my-api",
+    audience: "my-client",
+    expiresInSeconds: 900
+  }
+});
+const expressAuth = createExpressAuth(auth);
+
+// 3. Un utilisateur de démonstration (ne codez jamais de vrai mot de passe en dur).
+users.push({
+  id: "1",
+  email: "alice@example.com",
+  passwordHash: await auth.password.hash("example-password"),
+  isActive: true
+});
+
+// 4. L'application : une route de connexion et une route protégée.
+const app = express();
+
+app.post("/login", express.json(), expressAuth.login({ identifierField: "email" }));
+
+app.get("/profile", expressAuth.authenticate(), (req, res) => {
+  res.json({ userId: req.auth.userId });
+});
+
+// 5. Des réponses JSON claires, en français, si le client envoie un JSON invalide.
+app.use(expressAuth.errorHandler());
+
+app.listen(3000, () => console.log("API sur http://localhost:3000"));
+```
+
+Ce que fait ce fichier, en cinq points :
+
+1. **`userRepository`** explique à la bibliothèque comment trouver un utilisateur : par son e-mail (à la connexion) et par son identifiant (à chaque requête).
+2. **`createAuthKit()`** crée le moteur. Si le secret manque ou est trop faible, l'application refuse de démarrer et vous explique pourquoi.
+3. **`auth.password.hash()`** transforme le mot de passe en empreinte avant de l'enregistrer.
+4. **`expressAuth.login()`** crée la route de connexion, et **`expressAuth.authenticate()`** protège `/profile`. Dans la route protégée, `req.auth.userId` contient l'identifiant de l'utilisateur connecté.
+5. **`expressAuth.errorHandler()`** transforme les erreurs (JSON mal formé, par exemple) en réponses JSON claires, avec des messages en français.
+
+**Étape 4 — Lancez et testez**
+
+```bash
+node --env-file=.env server.js
+```
+
+Dans un autre terminal :
+
+```bash
+# 1. Se connecter : la réponse contient "accessToken"
+curl -s -X POST http://localhost:3000/login \
+  -H "content-type: application/json" \
+  -d '{"email":"alice@example.com","password":"example-password"}'
+
+# 2. Sans token : refusé (401)
+curl -i http://localhost:3000/profile
+
+# 3. Avec le token (remplacez <accessToken>) : {"userId":"1"}
+curl -s http://localhost:3000/profile -H "authorization: Bearer <accessToken>"
+```
+
+Ça marche ? Votre API a maintenant une connexion sécurisée. 🎉
+
+Une application plus complète, avec ses tests, se trouve dans [examples/basic-express](examples/basic-express).
+
+## L'essentiel en un coup d'œil
+
+| Je veux… | Code |
+| --- | --- |
+| Créer le moteur | `const auth = createAuthKit({ users, jwt: { secret, issuer, audience } })` |
+| Le brancher sur Express | `const expressAuth = createExpressAuth(auth)` |
+| Ajouter la route de connexion | `app.post("/login", express.json(), expressAuth.login())` |
+| Protéger une route | `app.get("/me", expressAuth.authenticate(), handler)` puis `req.auth.userId` |
+| Réserver une route à un rôle | `app.get("/admin", expressAuth.authorize("admin"), handler)` |
+| Hacher un mot de passe (inscription) | `await auth.password.hash(password)` |
+| Vérifier un mot de passe | `await auth.password.verify(password, hash)` |
+| Rester connecté plus de 15 minutes | `refreshTokens: { store }` puis `app.post("/auth/refresh", express.json(), expressAuth.refresh())` |
+| Déconnecter | `app.post("/auth/logout", express.json(), expressAuth.logout())` |
+| Générer un secret | `npx express-authkit secret` |
+
+**Votre repository** : deux fonctions, `findByIdentifier()` et `findById()`. Elles renvoient
+`{ id, passwordHash, isActive }`, ou `null` si l'utilisateur n'existe pas.
+`id` peut être un texte, un nombre ou un `ObjectId` MongoDB.
+
+## Avant de passer en production
+
+- [ ] Limitez le nombre de tentatives de connexion ([exemple prêt à copier](docs/securite.md#limitation-des-tentatives-de-connexion)).
+- [ ] Servez l'API uniquement en **HTTPS**.
+- [ ] Gardez le secret hors du code, dans une variable d'environnement.
+
+La liste complète se trouve dans le [guide de sécurité](docs/securite.md).
+
+## Documentation
+
+**Pour démarrer**
+
+- [Brancher ma base de données](docs/repository-utilisateur.md) (PostgreSQL, Prisma, MongoDB…)
+- [Connecter les utilisateurs et protéger les routes](docs/connexion-et-routes.md)
+- [Gérer les mots de passe](docs/mots-de-passe.md) (inscription, changement de mot de passe)
+- [Rôles et permissions](docs/roles-et-permissions.md) (réserver une route aux administrateurs…)
+- [Rester connecté : les refresh tokens](docs/refresh-tokens.md) (et la déconnexion)
+- [Utiliser TypeScript](docs/typescript.md) (démarrage TypeScript, différences avec les exemples JavaScript)
+- [Régler la configuration](docs/configuration.md)
+
+**Quand quelque chose ne va pas**
+
+- [Dépannage](docs/depannage.md)
+- [Comprendre les erreurs](docs/erreurs.md)
+
+**Pour aller plus loin**
+
+- [Sécurité : bonnes pratiques et limites](docs/securite.md)
+- [Référence complète de l'API](docs/reference-api.md)
+- [Remplacer le hachage ou les tokens](docs/providers-personnalises.md)
+- [Architecture du projet](docs/architecture.md)
+
+**Le projet** : [contribuer](CONTRIBUTING.md) · [historique des versions](CHANGELOG.md) · [signaler une faille](SECURITY.md)
+
+## Ce que la version 0.1.0 ne fait pas (encore)
+
+Pas de connexion via Google/GitHub (OAuth), pas de double authentification (MFA), pas de
+hiérarchie de rôles ni de droits par objet (ACL), pas de cookies `HttpOnly`, pas de réinitialisation de mot de passe
+par e-mail.
+Ces sujets sont [prévus pour plus tard](docs/architecture.md#points-dextension-futurs).
+
+## Licence
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Politique de sécurité
+
+## Versions prises en charge
+
+| Version | Correctifs de sécurité |
+| ------- | ---------------------- |
+| 0.1.x   | Oui                    |
+
+## Signaler une vulnérabilité
+
+**N'ouvrez pas d'issue publique pour une vulnérabilité.**
+
+Utilisez la fonction « Report a vulnerability » (GitHub Security Advisories)
+du dépôt, en indiquant :
+
+- la version concernée ;
+- une description du problème et de son impact ;
+- les étapes ou le code permettant de le reproduire.
+
+Nous visons un accusé de réception sous 5 jours ouvrés et une première
+évaluation sous 14 jours. La divulgation est coordonnée avec la personne
+qui a fait le signalement.
+
+## Périmètre et limites connues
+
+Express AuthKit s'appuie sur `jose` (JWT) et `argon2` (Argon2id) et
+n'implémente aucun algorithme cryptographique. Les limites de sécurité
+connues (révocation des JWT, rate limiting à la charge de l'application,
+heuristique de détection des secrets faibles…) sont décrites dans
+[docs/securite.md](docs/securite.md).

package/bin/express-authkit.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Petit utilitaire en ligne de commande d'Express AuthKit.
+ *
+ *   npx express-authkit secret   → affiche un secret JWT aléatoire (48 octets, base64url)
+ */
+import { randomBytes } from "node:crypto";
+
+const SECRET_BYTES = 48;
+
+const USAGE = `Utilisation : express-authkit <commande>
+
+Commandes :
+  secret    Affiche un secret JWT aléatoire (${SECRET_BYTES} octets, base64url) pour AUTH_SECRET.
+  help      Affiche cette aide.
+
+Exemple :
+  echo "AUTH_SECRET=$(npx express-authkit secret)" >> .env
+`;
+
+const [command] = process.argv.slice(2);
+
+if (command === "secret") {
+  process.stdout.write(`${randomBytes(SECRET_BYTES).toString("base64url")}\n`);
+} else if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+  process.stdout.write(USAGE);
+} else {
+  process.stderr.write(`Commande inconnue : ${command}\n\n${USAGE}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@kourouma/express-authkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.1",
+  "description": "Moteur d'authentification sécurisé et extensible pour Express.js : Argon2id, JWT (jose), repository utilisateur injectable.",
+  "keywords": [
+    "express",
+    "authentication",
+    "auth",
+    "jwt",
+    "jose",
+    "argon2",
+    "argon2id",
+    "middleware",
+    "security",
+    "hexagonal"
+  ],
+  "license": "MIT",
+  "author": "Express AuthKit contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kourouma1/Express-AuthKit.git"
+  },
+  "homepage": "https://github.com/kourouma1/Express-AuthKit#readme",
+  "bugs": {
+    "url": "https://github.com/kourouma1/Express-AuthKit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./express": {
+      "types": "./types/adapters/express/index.d.ts",
+      "default": "./src/adapters/express/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "express-authkit": "bin/express-authkit.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "types/",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.js\"",
+    "test:coverage": "node --test --experimental-test-coverage \"tests/**/*.test.js\"",
+    "test:package": "node scripts/verify-package.js",
+    "lint": "eslint .",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "prepublishOnly": "npm run check",
+    "build:types": "node scripts/build-types.js",
+    "typecheck": "tsc -p tsconfig.types.json --noEmit --checkJs",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "argon2": "^0.45.1",
+    "jose": "^6.2.12"
+  },
+  "peerDependencies": {
+    "express": "^4.21.0 || ^5.0.0",
+    "@types/express": "^4.17.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "@types/express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.19.2",
+    "eslint": "^10.12.0",
+    "express": "^5.3.0",
+    "globals": "^17.13.0",
+    "typescript": "^7.0.2"
+  },
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/express/bearer-token.js

@@ -0,0 +1,35 @@
+import { InvalidTokenError, TokenMissingError } from "../../core/errors.js";
+import { MAX_TOKEN_LENGTH } from "../../core/input-limits.js";
+
+/** RFC 6750 §2.1 : `Bearer` suivi d’un jeton base64 ; le schéma ne distingue pas la casse. */
+const BEARER_PATTERN = /^Bearer +([A-Za-z0-9\-._~+/]+=*)$/i;
+const BEARER_SCHEME_PATTERN = /^Bearer(?: |$)/i;
+
+/**
+ * Extrait le jeton d’accès d’un en-tête `Authorization`.
+ *
+ * Un en-tête utilisant un autre schéma (par exemple `Basic`) est traité comme
+ * une absence de jeton ; une valeur `Bearer` mal formée est invalide.
+ *
+ * @param {string | undefined} headerValue
+ * @returns {string}
+ * @throws {TokenMissingError | InvalidTokenError}
+ */
+export function extractBearerToken(headerValue) {
+  if (typeof headerValue !== "string" || headerValue.trim() === "") {
+    throw new TokenMissingError();
+  }
+  // La longueur de l’en-tête est limitée avant toute expression régulière.
+  if (headerValue.length > MAX_TOKEN_LENGTH + "Bearer ".length) {
+    throw new InvalidTokenError();
+  }
+  if (!BEARER_SCHEME_PATTERN.test(headerValue)) {
+    throw new TokenMissingError();
+  }
+
+  const match = BEARER_PATTERN.exec(headerValue);
+  if (match === null) {
+    throw new InvalidTokenError();
+  }
+  return match[1];
+}

package/src/adapters/express/http-errors.js

@@ -0,0 +1,89 @@
+import { AUTH_ERROR_CODES, InvalidInputError, isAuthKitError } from "../../core/errors.js";
+import { PUBLIC_MESSAGES } from "../../core/messages.js";
+
+/**
+ * Statuts HTTP pour les erreurs causées par le client. Toute autre erreur
+ * (configuration, contrat, hash illisible, base de données…) est un problème
+ * serveur et est transmise à la chaîne d’erreurs Express.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+const CLIENT_ERROR_STATUSES = Object.freeze({
+  [AUTH_ERROR_CODES.INVALID_INPUT]: 400,
+  [AUTH_ERROR_CODES.INVALID_CREDENTIALS]: 401,
+  [AUTH_ERROR_CODES.TOKEN_MISSING]: 401,
+  [AUTH_ERROR_CODES.TOKEN_INVALID]: 401,
+  [AUTH_ERROR_CODES.TOKEN_EXPIRED]: 401,
+  [AUTH_ERROR_CODES.REFRESH_TOKEN_INVALID]: 401,
+  [AUTH_ERROR_CODES.ACCESS_DENIED]: 403
+});
+
+/** Code d’erreur RFC 6750 §3.1 pour les jetons Bearer rejetés. */
+/** @type {ReadonlySet<string>} */
+const INVALID_TOKEN_CODES = new Set([AUTH_ERROR_CODES.TOKEN_INVALID, AUTH_ERROR_CODES.TOKEN_EXPIRED]);
+
+/**
+ * @param {unknown} error
+ * @returns {number | undefined} Statut à envoyer, ou `undefined` si ce n’est pas une erreur client.
+ */
+export function getClientErrorStatus(error) {
+  return isAuthKitError(error) ? CLIENT_ERROR_STATUSES[error.code] : undefined;
+}
+
+/**
+ * Comme {@link getClientErrorStatus}, mais reconnaît aussi les erreurs du
+ * parseur JSON d’Express (`express.json()`) : un JSON mal formé ou trop
+ * volumineux reçoit une réponse JSON propre au lieu de la page d’erreur HTML
+ * d’Express, qui peut afficher la pile d’appels en développement.
+ *
+ * @param {unknown} error
+ * @returns {{ error: import("../../core/errors.js").AuthKitError, status: number } | undefined}
+ */
+export function resolveClientError(error) {
+  const status = getClientErrorStatus(error);
+  if (status !== undefined) {
+    return { error: /** @type {import("../../core/errors.js").AuthKitError} */ (error), status };
+  }
+  const bodyParserErrorType =
+    error !== null && typeof error === "object" ? /** @type {{ type?: unknown }} */ (error).type : undefined;
+  if (bodyParserErrorType === "entity.parse.failed") {
+    return { error: new InvalidInputError(PUBLIC_MESSAGES.malformedJsonBody), status: 400 };
+  }
+  if (bodyParserErrorType === "entity.too.large") {
+    return { error: new InvalidInputError(PUBLIC_MESSAGES.payloadTooLarge), status: 413 };
+  }
+  return undefined;
+}
+
+/**
+ * Envoie une erreur d’authentification client au format JSON.
+ *
+ * Seuls le `code` stable et le `message` public sont envoyés : jamais la pile,
+ * la cause ou la raison interne de l’échec.
+ *
+ * @param {import("express").Response} res
+ * @param {import("../../core/errors.js").AuthKitError} error
+ * @param {number} status
+ * @param {string} realm
+ */
+export function sendClientError(res, error, status, realm) {
+  if (status === 401) {
+    res.set("WWW-Authenticate", buildChallenge(error.code, realm));
+  }
+  if (status === 403) {
+    // RFC 6750 §3.1 : droits insuffisants pour la ressource demandée.
+    res.set("WWW-Authenticate", `Bearer realm="${realm}", error="insufficient_scope"`);
+  }
+  res.set("Cache-Control", "no-store");
+  res.status(status).json({ error: { code: error.code, message: error.message } });
+}
+
+/**
+ * @param {string} code
+ * @param {string} realm
+ * @returns {string}
+ */
+function buildChallenge(code, realm) {
+  const challenge = `Bearer realm="${realm}"`;
+  return INVALID_TOKEN_CODES.has(code) ? `${challenge}, error="invalid_token"` : challenge;
+}