chore: bump version to 1.4.210

- add `MediaDetailsModal.client.js` with support for `media={…}` or `slug="…"` props
- add `GET /zen/api/media/by-slug/:slug` route for slug-based lookup
- refactor `MediaPage.client.js` to use the new modal instead of inline details panel
- export `MediaDetailsModal` as `./features/media/details-modal` in package.json
- update `BlockEditor` image block to open `MediaDetailsModal` for media editing
- update media feature README to document new component and route

.env.example

@@ -10,13 +10,23 @@ ZEN_CURRENCY=CAD
 ZEN_CURRENCY_SYMBOL=$
 ZEN_SUPPORT_EMAIL=support@exemple.com
 
+# PROXY (activer si derrière un reverse proxy)
+ZEN_TRUST_PROXY=false
+
 # DATABASE
 ZEN_DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/postgres
 ZEN_DATABASE_URL_DEV=postgres://USER:PASSWORD@HOST:PORT/postgres_dev
+ZEN_DB_SSL_DISABLED=false
 
-# STORAGE (Cloudflare R2 for now)
-ZEN_STORAGE_BUCKET=my-bucket-name
-ZEN_STORAGE_REGION=your-account-id
+# STORAGE
+# Fournisseur : 'r2' (défaut) ou 'backblaze'
+ZEN_STORAGE_PROVIDER=r2
+# R2 endpoint : <accountId>.r2.cloudflarestorage.com
+# Backblaze endpoint : s3.<region>.backblazeb2.com
+# REGION optionnelle pour R2 (défaut : auto), obligatoire pour Backblaze
+ZEN_STORAGE_ENDPOINT=
+ZEN_STORAGE_REGION=
+ZEN_STORAGE_BUCKET=
 ZEN_STORAGE_ACCESS_KEY=
 ZEN_STORAGE_SECRET_KEY=
 
@@ -41,5 +51,11 @@ ZEN_PUBLIC_LOGO_WHITE=
 ZEN_PUBLIC_LOGO_BLACK=
 ZEN_PUBLIC_LOGO_URL=
 
+# MEDIA
+ZEN_MEDIA=false
+
 # OTHERS
 NEXT_TELEMETRY_DISABLED=1
+
+# DEVKIT (developer tools)
+ZEN_DEVKIT=false

CLAUDE.md

@@ -1,3 +1,13 @@
 # Claude Code Rules
 
-Always read [docs/DEV.md](docs/DEV.md) at the start of every conversation before doing any work in this project.
+Always read and respect [docs/DEV.md](docs/DEV.md) at the start of every conversation before doing any work in this project.
+
+After every code change, update the relevant documentation. This includes:
+- `docs/` for cross-cutting conventions, architecture decisions, and design rules
+- co-located `README.md` files in `src/core/<module>/` and `src/features/<feature>/` for module-level behaviour
+
+No task is complete until all impacted documentation is up to date.
+
+## No whack-a-mole
+
+Always fix the **root cause**, never the symptoms. If the same type of error appears in a second file after fixing the first, that's the signal the real fix is elsewhere — trace the import or call chain to understand why this code is reached in this context, then fix at that point.

README.md

@@ -1,6 +1,8 @@
-# zen
+# ZEN
 
-Un CMS Next.js construit sur l'essentiel, rien de plus, rien de moins.
+Une plateforme multi-usage construite sur l'essentiel, rien de plus, rien de moins.
+
+![banner](/assets/git-banner.png)
 
 > [!WARNING]
 > Ce projet est en développement actif et n'est pas encore prêt pour une utilisation en production. L'API, la structure et les fonctionnalités peuvent changer à tout moment.

docs/DESIGN.md

@@ -0,0 +1,285 @@
+# ZEN — Design Language
+
+Document de référence visuelle. Décrit l'apparence, le ressenti et les règles visuelles du produit. Valable pour toute reproduction, quelle que soit la technologie.
+
+---
+
+## Philosophie
+
+ZEN est un outil de travail. Pas un produit marketing. L'interface disparaît pour laisser place au contenu.
+
+**Un seul principe directeur : ne jamais ajouter un élément sans raison.**
+
+Chaque couleur, bordure, espace ou texte supplémentaire doit justifier sa présence. Le doute se résout toujours en faveur de la suppression.
+
+---
+
+## Palette
+
+### Base
+
+Le produit est **noir et blanc**. Pas de couleurs de marque, pas de teintes bleues ou violettes dans les fonds. Le fond est blanc pur. Le texte est presque noir.
+
+### Accents sémantiques
+
+Quatre couleurs uniquement. Utilisées **avec grande parcimonie** — pour les statuts, les alertes, les deltas. Jamais comme couleur décorative. Jamais sur un fond.
+
+| Couleur | Usage |
+|---|---|
+| **Bleu** | Information, liens, action principale |
+| **Vert** | Succès, actif, delta positif |
+| **Ambre** | Avertissement, en attente, brouillon |
+| **Rouge** | Erreur, danger, suppression, delta négatif |
+
+Chaque couleur existe en trois déclinaisons : la couleur elle-même (pour le texte), un fond très pâle, et une bordure légère. Ces trois valeurs forment toujours un ensemble — on ne mélange pas les déclinaisons de couleurs différentes.
+
+### Ce qu'on n'utilise pas
+
+- Dégradés
+- Couleurs de fond dans la sidebar ou les sections (sauf hover/actif)
+- Couleurs de marque personnalisées
+- Transparence et flou (sauf l'overlay des modales)
+
+---
+
+## Typographie
+
+**Police unique : IBM Plex Sans.** Pour les codes, IDs, montants et dates : IBM Plex Mono.
+
+### Hiérarchie
+
+| Rôle | Taille | Graisse | Notes |
+|---|---|---|---|
+| Titre de page | 20px | 600 | |
+| Titre de section | 14–20px | 600 | |
+| Corps de texte | 13px | 400 | |
+| Texte secondaire | 12px | 400 | Dans les tableaux, les listes |
+| Labels / captions | 12px | 400–500 | |
+| Labels colonnes | 11px | 500 | Uppercase, lettre-espacement +0.04em |
+| Codes / IDs / montants | 11–13px | 400 | IBM Plex Mono |
+
+**Taille minimale : 11px.** En dessous, on ne descend pas.
+
+### Règles d'écriture
+
+- **Sentence case partout.** "Tableau de bord", pas "TABLEAU DE BORD".
+- Seule exception : les en-têtes de colonnes de tableau, en majuscules petits.
+- Texte court et direct. Pas de phrase là où un mot suffit.
+- Les montants financiers, les dates ISO et les identifiants sont toujours en monospace.
+
+---
+
+## Espace
+
+Base : **4px**. Tout espacement est un multiple de 4.
+
+| Valeur | Usage typique |
+|---|---|
+| 4px | Espacement interne minimal (gap entre icône et texte) |
+| 8px | Padding compact, gap entre éléments proches |
+| 12px | Padding interne des petits composants |
+| 16px | Padding standard des cartes et panneaux |
+| 24px | Espacement entre sections |
+| 32px | Padding latéral du contenu principal |
+| 48–64px | Espacement entre blocs majeurs |
+
+La densité est **moyenne**. Pas étouffant, pas aéré. Un admin est un outil qu'on utilise plusieurs heures par jour — la densité confortable prime sur l'esthétique aérée.
+
+---
+
+## Formes et bordures
+
+### Rayon de bordure
+
+| Contexte | Rayon |
+|---|---|
+| Badges, étiquettes, petits éléments | Complet |
+| Boutons, champs de saisie | 8px |
+| Modales, panneaux flottants importants, tableau, cartes | 12px |
+| Avatars, indicateurs ronds | Cercle complet |
+
+**12px est le rayon standard.** On ne mélange pas les rayons dans un même composant.
+
+### Bordures
+
+Toutes les séparations sont des **bordures 1px solid**. Pas d'ombres sur les cartes et surfaces statiques. Pas de lignes de 2px ou plus.
+
+Les ombres existent uniquement pour les éléments qui **flottent au-dessus** de l'interface : menus déroulants, modales, toasts. Elles sont discrètes — juste assez pour indiquer la profondeur.
+
+---
+
+## Structure de l'admin
+
+```
+┌─────────────────────────────────────────────┐
+│ Sidebar 230px    │ Barre supérieure 48px      │
+│                  ├─────────────────────────── │
+│  Logo            │                            │
+│                  │   Zone de contenu          │
+│  Nav principale  │   padding 28px / 32px      │
+│                  │                            │
+│  ──────────────  │                            │
+│  Paramètres      │                            │
+└─────────────────────────────────────────────┘
+```
+
+- **Sidebar** : fixe, 230px. Fond blanc (`#ffffff`). Séparée par une bordure droite.
+- **Barre supérieure** : fixe, 48px. Fond blanc. Fil d'Ariane à gauche, utilisateur à droite.
+- **Contenu** : gris très pâle (`#fafafa` / `neutral-50`). Les cartes et tableaux ont un fond blanc, ce qui crée naturellement la séparation visuelle sans avoir besoin de bordures de section. Sur thème sombre le fond deviens noir est le boite sont grise.
+
+---
+
+## Navigation sidebar admin
+
+### Structure
+
+La sidebar fait **230px** de large, fixe. Fond blanc / noir complet en sombre. Séparée du contenu par une bordure droite `1px`.
+
+Elle se compose de trois zones verticales :
+
+1. **Logo** — hauteur 48px, aligné sur la barre supérieure. Séparé par une bordure basse.
+2. **Navigation principale** — défile si nécessaire. Padding `8px` autour des items.
+3. **Items épinglés en bas** — optionnels. Séparés par une bordure haute. Jamais dans la zone défilable.
+
+### Items de navigation
+
+Deux types d'items coexistent :
+
+- **Lien direct** : section avec un seul item dont le nom est identique au titre de la section. S'affiche comme un lien simple, sans chevron.
+- **Section accordéon** : section avec plusieurs items. Un bouton parent déploie ou replie les sous-items.
+
+### États visuels
+
+| État | Apparence |
+|---|---|
+| Inactif | Texte `neutral-500` (sombre : `neutral-400`), fond transparent |
+| Hover | Fond `neutral-100` (sombre : `neutral-900`), texte `neutral-900` (sombre : blanc) |
+| Actif replié | Fond `neutral-100` (sombre : `neutral-900`), texte noir (sombre : blanc), graisse `500` |
+| Actif ouvert (parent) | Pas de fond, texte noir (sombre : blanc), graisse `500` — le fond actif est sur le sous-item |
+| Sous-item actif | Fond `neutral-100` (sombre : `neutral-900`), texte noir (sombre : blanc), graisse `500` |
+
+### Gabarit d'un item
+
+- Padding : `7px` vertical, `10px` horizontal.
+- Rayon : `8px`.
+- Icône à gauche, `15×15px`, `flex-shrink-0`. Gap icône–texte : `8px`.
+- Texte : `13px`.
+- Transition : `120ms ease-out`.
+- Badge numérique (optionnel) : à droite, fond rouge, texte blanc, `10px`, rayon `8px`.
+
+### Sous-items
+
+Pas d'icône. Indentation via `padding-left: 25px`. Même gabarit que les items parents.
+
+### Accordéon
+
+Le chevron (`12×12px`) est à l'extrême droite du bouton parent. Il pivote de `-90deg` quand la section est repliée, revient à `0deg` quand elle est ouverte. L'animation du conteneur : `max-height` + `opacity`, `120ms ease-out`.
+
+Une section s'ouvre automatiquement au chargement si elle contient l'item actif courant. Toutes les autres sont repliées par défaut.
+
+### Mobile
+
+En dessous de `1024px`, la sidebar sort du flux et se positionne en fixe sur toute la hauteur. Elle est masquée par défaut (`translate-x: -100%`) et s'ouvre via un bouton externe. Un overlay semi-transparent (`black/50`) couvre le contenu derrière. Cliquer l'overlay ou naviguer vers un lien ferme la sidebar. Au redimensionnement au-delà de `1024px`, la sidebar mobile se ferme automatiquement.
+
+---
+
+## Boutons
+
+Sept variantes :
+
+| Variante | Apparence | Usage |
+|---|---|---|
+| **Primaire** | Fond `neutral-900`, texte blanc | Action principale de la page |
+| **Secondaire** | Fond transparent, bordure `neutral-300`, texte `neutral-700` | Actions secondaires, annulation |
+| **Fantôme** | Fond transparent, pas de bordure, texte `neutral-600` | Actions tertiaires |
+| **Fantôme plein** | Identique au fantôme, sans focus ring | Boutons très discrets dans des zones déjà interactives |
+| **Danger** | Fond rouge très pâle, bordure rouge pâle, texte rouge | Suppression, actions destructives |
+| **Succès** | Fond vert très pâle, bordure verte pâle, texte vert | Confirmation, validation |
+| **Avertissement** | Fond ambre très pâle, bordure ambre pâle, texte ambre | Alertes, actions risquées |
+
+**Il ne doit jamais y avoir plus d'un bouton primaire par section ou en-tête de page.**
+
+### Tailles
+
+| Taille | Padding horizontal | Padding vertical | Texte |
+|---|---|---|---|
+| **sm** | 10px | 5px | 12px |
+| **md** | 12px | 7px | 13px |
+| **lg** | 14px | 9px | 14px |
+
+La taille par défaut est `md`.
+
+### Icônes et chargement
+
+- Une icône peut se placer à gauche ou à droite du texte.
+- Un bouton icône seule (sans texte) a un padding uniforme.
+- L'état de chargement remplace le contenu par un spinner et désactive l'interaction.
+- L'état désactivé : opacité 50 %, curseur interdit.
+
+### Règles communes
+
+- Rayon : 8px (`rounded-lg`).
+- Transition : 120ms, `ease-out`.
+- Focus : anneau fin de la couleur de la variante.
+
+---
+
+## Cartes et panneaux
+
+- Fond blanc.
+- Bordure 1px.
+- Rayon 12px (rounded-xl).
+- Padding interne 16–20px.
+- **Pas d'ombre.**
+- En-tête interne séparé du contenu par une bordure horizontale.
+- Pied de panneau (actions de formulaire) séparé par une bordure horizontale.
+
+---
+
+## Tableaux
+
+- En-têtes de colonnes : texte 11px uppercase, couleur secondaire.
+- Lignes : fond blanc. Hover : fond légèrement grisé.
+- Bordure horizontale entre chaque ligne. Pas de bordure sur la dernière ligne.
+- Données numériques, IDs, dates : IBM Plex Mono.
+- Actions (modifier, supprimer) : à l'extrême droite, boutons icône discrets.
+- Pas de fond alterné sur les lignes.
+
+---
+
+## Badges de statut
+
+Petits éléments inline qui indiquent un état. Toujours composés de trois éléments : fond pâle de la couleur sémantique, bordure légère, texte de la couleur sémantique.
+
+Rayon : full. Taille du texte : 11px.
+
+---
+
+## États interactifs
+
+| État | Apparence |
+|---|---|
+| Hover | Fond légèrement plus sombre (4–5% de gris) |
+| Actif / focus | Bordure de 1px devient la couleur du texte principal |
+| Désactivé | Opacité 50%, curseur interdit |
+| Chargement | Pas défini — à traiter au cas par cas |
+
+Toutes les transitions durent **120ms**, courbe `ease-out`. Aucune animation décorative.
+
+---
+
+## Ce qu'on n'utilise jamais
+
+- Dégradés de couleur sur les fonds ou les boutons
+- Cartes avec une bordure colorée uniquement sur le côté gauche
+- Ombres internes
+- Texte en gras uniquement pour l'emphase décorative
+- Icônes sans fonction claire
+- Statistiques ou chiffres inventés pour remplir l'espace
+- Couleurs de fond dans les sections de contenu
+
+---
+
+## Thème sombre
+
+Le thème sombre est une inversion calibrée : les fonds passent au noir complet puis les zone par dessus sont noir-gris, les textes s'éclaircissent, les accents gagnent légèrement en luminosité pour rester lisibles. La structure, les espaces et les proportions restent identiques.

docs/DEV.md

@@ -1,62 +1,121 @@
-# DEV
+# Guide de développement
 
-## Standards
+Ce document couvre les conventions de code, les règles de sécurité et la procédure de publication du package `@zen/core`.
 
-On suit ces deux guides :
+Pour les conventions de rédaction : [LANGUE.md](./dev/LANGUE.md) et [REDACTION.md](./dev/REDACTION.md).
 
-- [GUIDE.md](./dev/GUIDE.md) : conventions générales de rédaction et de structure
-- [REDACTION.md](./dev/REDACTION.md) : règles de style, ton et formatage
+Pour les décisions de design et l'identité visuelle : [DESIGN.md](./DESIGN.md).
+
+Pour l'architecture partagée (composants, icônes) : [ARCHITECTURE.md](./dev/ARCHITECTURE.md).
+
+Pour la procédure de publication du package : [PUBLICATION.md](./dev/PUBLICATION.md).
+
+Pour les conventions de commit : [COMMITS.md](./dev/COMMITS.md).
+
+Pour la création de modules externes `@zen/module-*` : [MODULES.md](./MODULES.md).
+
+> **Contexte projet** : les utilisateurs finaux créent leur projet via `npx @zen/start`, qui génère automatiquement une structure Next.js avec la plateforme déjà intégré. Lors d'une assistance ou d'une revue, partez du principe que le projet cible est déjà structuré de cette façon.
 
 ---
 
-## Philosophie de développement
+## Standards de code
 
-### Power of Ten
+**On corrige la cause racine, jamais les symptômes.** Si le même type d'erreur réapparaît dans un deuxième fichier après avoir corrigé le premier, c'est le signe que le vrai fix est ailleurs. Remonter la chaîne d'imports ou d'appels jusqu'à comprendre *pourquoi* ce code est atteint dans ce contexte, puis corriger à cet endroit. Patcher les fichiers un par un (whack-a-mole) masque le problème et garantit qu'un troisième cas surgira.
 
-Tout le code produit suit les principes du [NASA Power of Ten](https://en.wikipedia.org/wiki/The_Power_of_10:_Rules_for_Developing_Safety-Critical_Code) :
+**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
 
-1. **Flux de contrôle simples** — pas de `goto`, pas de récursion non bornée, pas de pointeurs de fonctions imbriqués.
-2. **Boucles bornées** — toute boucle doit avoir une limite maximale d'itérations statiquement vérifiable.
-3. **Pas d'allocation dynamique après l'initialisation** — allouer les ressources en amont, libérer proprement.
-4. **Fonctions courtes et ciblées** — une fonction = une responsabilité, tient sur un écran.
-5. **Densité d'assertions élevée** — valider les préconditions, postconditions et invariants explicitement.
-6. **Portée des données minimale** — déclarer les variables au plus près de leur utilisation, limiter l'exposition.
-7. **Vérification systématique des retours** — chaque valeur de retour ou promesse rejetée doit être gérée.
-8. **Préprocesseur minimal** — éviter la magie implicite ; préférer la clarté à la concision.
-9. **Limiter les pointeurs** — une seule indirection par niveau ; pas d'aliasing caché.
-10. **Warnings = erreurs** — le linter et le compilateur doivent passer sans avertissement.
+**Les variables d'environnement et la documentation se mettent à jour avec le code.** Toute variable ajoutée, renommée ou supprimée doit être reflétée dans `.env.example`. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier `docs/` concerné.
 
-### Sécurité
+**Une fonction, une responsabilité.** Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.
 
-Chaque contribution doit intégrer la sécurité dès la conception (*security by design*) :
+**Le flux de contrôle se lit de haut en bas.** Pas de récursion non bornée, pas de callbacks imbriqués à plus de deux niveaux. Quelqu'un qui lit le code pour la première fois doit pouvoir suivre l'exécution sans se perdre.
 
-- **Validation des entrées** — toute donnée externe (utilisateur, API tierce, fichier) est considérée malveillante jusqu'à preuve du contraire. Valider côté serveur, jamais uniquement côté client.
-- **Moindre privilège** — un module n'accède qu'aux ressources strictement nécessaires à sa fonction.
-- **Pas de secrets dans le code** — tokens, clés API, mots de passe passent exclusivement par des variables d'environnement ou un gestionnaire de secrets.
-- **Dépendances auditées** — lancer `npm audit` avant chaque publication ; ne pas introduire de dépendance avec des vulnérabilités connues non corrigées.
-- **Gestion des erreurs opaque** — les messages d'erreur exposés à l'utilisateur ne révèlent pas de détails internes (stack trace, chemin de fichier, requête SQL…).
-- **Protection contre les injections** — utiliser exclusivement des requêtes paramétrées ou des ORM éprouvés ; jamais de concaténation de chaînes SQL/shell.
-- **Authentification et sessions** — tokens signés, durée de vie limitée, révocation possible, rotation des secrets régulière.
-- **En-têtes HTTP de sécurité** — `Content-Security-Policy`, `X-Content-Type-Options`, `Strict-Transport-Security` configurés sur toutes les routes.
+**Les données entrantes sont suspectes.** On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.
+
+**La portée des variables est minimale.** On déclare au plus près de l'usage. Pas de variables réutilisées pour deux rôles différents.
+
+**ESLint passe sans avertissement.** Un warning ignoré aujourd'hui est un bug non détecté demain.
+
+**Les commentaires reflètent toujours le comportement réel du code.** Un commentaire obsolète est pire qu'un commentaire absent — il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire. Un commentaire qui contredit le code est un bug de documentation.
 
 ---
 
-## Publier le package
+## Conventions d'arborescence
 
-Le package `@zen/core` est publié sur le registre npm à `https://git.hyko.cx`.
+Une feature (`src/features/<nom>/` ou `src/core/<nom>/`) suit la règle **flat + un barrel** :
+un `index.js` qui ré-exporte, des fichiers plats côte à côte pour l'implémentation. Pas de sous-dossier `lib/`, `middleware/`, `actions/` quand il ne contient qu'un ou deux fichiers — remonter directement au niveau du dossier feature.
 
-### 1. Configurer l'authentification
+Les sous-dossiers sont autorisés uniquement quand ils contiennent plusieurs fichiers du même rôle : `components/`, `pages/`, `templates/`, `widgets/`.
 
-Créer un token d'accès dans Gitea (Settings → Applications → Generate Token), puis l'enregistrer localement :
+### Suffixes de runtime
 
-```bash
-npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
+Tout fichier épinglé à une frontière Next.js porte le suffixe dans son nom :
+
+- `.server.js` → code serveur strict (peut importer `pg`, `fs`, etc.)
+- `.client.js` → débute par `'use client'`
+- pas de suffixe → module neutre, utilisable des deux côtés
+- `actions.js` → débute par `'use server'` (server actions Next.js)
+
+Ces suffixes ne sont pas cosmétiques : **le build les utilise comme source de vérité**. Le build compile l'intégralité de `src/` avec `bundle: false` — chaque fichier reste un module séparé, ce qui permet à Next.js de respecter les frontières RSC et `'use client'` sans que le bundler ne fusionne les modules.
+
+**Tout fichier qui `import 'pg'`, `'fs'`, `'net'`, `'node:*'` doit porter `.server.js`.** Sans ce suffixe, le fichier est réputé neutre — un barrel client peut le ré-exporter par mégarde, et Turbopack/Webpack tracent la chaîne d'imports statiques jusqu'à `pg` dans le bundle browser. L'erreur `Module not found: Can't resolve 'dns'` côté client est typiquement causée par un fichier serveur sans suffixe atteint via un barrel mixte.
+
+---
+
+## Build et configuration tsup
+
+`tsup.config.js` compile **tous les fichiers `.js` et `.jsx` de `src/`** avec `bundle: false`. Chaque fichier devient un module standalone dans `dist/` ; les imports relatifs sont préservés tels quels. La structure `dist/` reflète exactement `src/` grâce à `outbase: 'src'`.
+
+- **Ajouter un module public = éditer seulement `package.json#exports`.** L'entry list se régénère au prochain build via un walk de `src/`.
+- **Pas de bundling des fichiers internes** : les modules de registre (`registry.js`, etc.) sont des singletons — les bundler créerait une copie inline distincte et casserait le partage d'état entre les pages et les widgets.
+- Les self-imports `@zen/core/*` sont générés automatiquement à partir des clés de `exports` et restent toujours dans la liste `external`.
+- Les fichiers `.js` et `.jsx` sont tous traités comme du JSX via esbuild (`loader: { '.js': 'jsx' }`, `jsx: 'automatic'`) — pas besoin d'extension `.jsx` pour écrire du JSX.
+
+---
+
+## Étendre l'admin
+
+L'admin utilise un **registre runtime** pour permettre aux projets consommateurs d'ajouter des widgets, des entrées de navigation, et des pages sans modifier le core.
+
+> Pour distribuer ces extensions sous forme de package npm réutilisable plutôt que de les écrire en local, voir [MODULES.md](./MODULES.md) — chaque module `@zen/module-*` installé est auto-découvert et activé.
+
+```js
+// app/zen.extensions.js — projet consommateur
+import {
+  registerWidget,
+  registerWidgetFetcher,
+  registerNavItem,
+  registerNavSection,
+  registerPage,
+} from '@zen/core/features/admin';
+import OrdersWidget from './admin/OrdersWidget';
+import OrdersPage from './admin/OrdersPage';
+import { countOrders } from './admin/orders.server';
+
+registerWidgetFetcher('orders', async () => ({ total: await countOrders() }));
+registerWidget({ id: 'orders', Component: OrdersWidget, order: 20 });
+
+registerNavSection({ id: 'commerce', title: 'Commerce', icon: 'ShoppingBag03Icon', order: 30 });
+registerNavItem({ id: 'orders', label: 'Commandes', icon: 'ShoppingBag03Icon', href: '/admin/orders', sectionId: 'commerce', permission: 'orders.view' });
+
+registerPage({ slug: 'orders', Component: OrdersPage, title: 'Commandes' });
 ```
 
-Remplacer `TOKEN` par le token généré.
+L'item actif dans la sidebar et le fil d'Ariane sont calculés automatiquement à partir d'un `basePath` déduit de `href` (si `href` finit par `/list`, on retire le suffixe). Une convention `slug:edit` / `slug:new` permet de personnaliser les labels du breadcrumb sur les sous-routes — voir [src/features/admin/README.md](../src/features/admin/README.md#item-actif-et-fil-dariane) pour le détail.
 
-### 2. Build et publish
-
-```bash
-npm publish
+```js
+// app/layout.js — un seul import suffit ; les side effects enregistrent tout.
+import './zen.extensions';
 ```
+
+---
+
+## Sécurité
+
+**Données entrantes** : toute donnée externe est considérée malveillante par défaut. On valide côté serveur uniquement.
+
+**Base de données** : uniquement des requêtes paramétrées — jamais de SQL construit par concaténation de chaînes.
+
+**Secrets** : aucun token, clé API ou mot de passe dans le code. Tout passe par des variables d'environnement, jamais commitées.
+
+**Erreurs exposées** : pas de stack trace, nom de table ou requête SQL retournés au client. On log côté serveur, on renvoie un message générique côté client.

docs/MODULES.md

@@ -0,0 +1,501 @@
+# Modules externes `@zen/module-*`
+
+Un **module** est un package npm distinct qui ajoute des fonctionnalités à un projet construit avec `@zen/core` — sans aucune modification de code dans le projet consommateur.
+
+```bash
+npm install @zen/module-billing
+# ajouter les variables d'env documentées dans le README du module
+npx zen-db init   # crée les tables du module et seed ses permissions
+npm run dev       # tout est câblé : pages admin, sidebar, widgets, API, /zen/<module>/...
+```
+
+Aucun fichier de configuration manuelle. La plateforme découvre les modules par scan des dépendances `package.json`.
+
+---
+
+## Découverte
+
+Les modules sont activés via deux **manifestes statiques** générés par la CLI `zen-modules sync` dans le projet consommateur :
+
+- `app/.zen/modules.generated.js` — manifeste serveur (importé par `instrumentation.js`).
+- `app/.zen/modules.client.js` — manifeste client (`'use client'`, exporte un Component à rendre dans `app/layout.js`).
+
+Le manifeste serveur peuple le registre côté Node via le top-level await à l'import. Le manifeste client exporte `ZenModulesClient` — un Component React — que `app/layout.js` doit **rendre** dans son tree (pas seulement importer). Sous Next.js 15+/Turbopack, un `import` purement side-effect d'un fichier `'use client'` orphelin (sans Component utilisé) inclut bien le fichier dans le bundle browser mais n'en exécute pas le code top-level — `registerPage()` / `registerWidget()` ne tourneraient jamais côté client. Rendre le Component force l'exécution.
+
+```js
+// app/.zen/modules.generated.js — AUTO-GÉNÉRÉ (serveur)
+import * as m0_zen_module_posts from '@zen/module-posts';
+export const modules = [
+  { name: '@zen/module-posts', exports: m0_zen_module_posts },
+];
+await Promise.all(modules.map(m => m.exports.register?.()));
+```
+
+```js
+// app/.zen/modules.client.js — AUTO-GÉNÉRÉ (client)
+'use client';
+import '@zen/module-posts/client';
+export default function ZenModulesClient() {
+  return null;
+}
+```
+
+```js
+// app/layout.js — projet consommateur
+import ZenModulesClient from './.zen/modules.client.js';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <ZenModulesClient />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+Le manifeste client importe la **sous-entrée `./client`** de chaque module (et non son main entry). C'est essentiel : le main entry tire `createTables` / `registerApiRoutes` / la chaîne `register-server.js` qui dépend de `pg`, `fs`, `next/headers`, etc. — code serveur incompatible avec le bundle browser. Seuls les modules qui exposent `./client` dans leur `package.json#exports` sont inclus dans le manifeste client ; les modules purement back-end (API/DB) sont absents du bundle browser.
+
+L'importation statique (le `import * as ...`) permet à Turbopack/Webpack d'analyser le graphe complet du module — JSX, `next/headers`, `next/navigation`, frontières `'use client'` — exactement comme pour le code de l'application elle-même.
+
+### Critères de détection
+
+`zen-modules sync` scanne `dependencies` + `devDependencies` du `package.json` du projet et inclut tout package matchant :
+
+- **Préfixe officiel** : `@zen/module-*`
+- **Préfixe non-scopé** : `zen-module-*`
+- **Tiers** : tout package dont le `package.json` contient `"keywords": ["zen-module"]`
+
+### Quand resync ?
+
+Le template `@zen/start` câble la CLI dans :
+
+```json
+{
+  "scripts": {
+    "postinstall": "zen-modules sync",
+    "dev": "zen-modules sync && next dev",
+    "build": "zen-modules sync && next build"
+  }
+}
+```
+
+`postinstall` couvre `npm install @zen/module-X`. Les hooks `dev`/`build` couvrent les retraits / changements de version qui ne déclenchent pas de re-install. La commande est idempotente — pas d'écriture si le contenu est identique.
+
+`app/.zen/modules.generated.js` est gitignoré : régénéré localement, jamais commit.
+
+---
+
+## Forme d'un module
+
+Le point d'entrée du package (`main` ou `exports["."]`) doit exporter :
+
+```js
+// @zen/module-blog/src/index.js  (compilé vers dist/index.js par tsup)
+
+export const manifest = {
+  name: '@zen/module-blog',
+  version: '1.0.0',
+  permissions: [
+    { key: 'blog.view',   name: 'Voir les billets',   description: 'Consultation', group_name: 'Blog' },
+    { key: 'blog.manage', name: 'Gérer les billets',  description: 'CRUD',         group_name: 'Blog' },
+  ],
+  envVars: [
+    { key: 'BLOG_UPLOAD_DIR', required: false, description: 'Répertoire des médias' },
+  ],
+};
+
+export async function register() {
+  // Tous les enregistrements runtime se font ici (voir API ci-dessous).
+  await import('./register-server.js');
+}
+
+export { createTables, dropTables } from './db.js';
+```
+
+| Export | Type | Obligatoire |
+|--------|------|-------------|
+| `manifest` | objet (voir ci-dessous) | oui |
+| `register` | `() => void \| Promise<void>` | oui |
+| `createTables` | `async () => { created?: string[], skipped?: string[] }` | si le module a des tables |
+| `dropTables` | `async () => void` | si le module a des tables |
+
+### Manifest
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Nom du package (utilisé comme identifiant unique). |
+| `version` | `string` | Version du module (logguée au boot). |
+| `permissions` | `Array` | Permissions ajoutées au catalogue. Auto-attribuées au rôle `admin` au prochain `zen-db init`. |
+| `envVars` | `Array` | Variables d'env du module ; les `required: true` absentes émettent un warning au boot. |
+
+---
+
+## API d'enregistrement
+
+Toutes ces fonctions s'utilisent depuis le hook `register()` du module.
+
+### Permissions
+
+Déclarées dans `manifest.permissions`. Le core les enregistre automatiquement avant le seed BD et les attribue au rôle `admin`. À la connexion, l'admin peut les distribuer à d'autres rôles via `/admin/roles`.
+
+### Sidebar admin
+
+```js
+import { registerNavSection, registerNavItem } from '@zen/core/features/admin';
+
+registerNavSection({ id: 'blog', title: 'Blog', icon: 'Notebook01Icon', order: 40 });
+registerNavItem({
+  id: 'blog-posts',
+  label: 'Billets',
+  icon: 'Notebook01Icon',
+  href: '/admin/blog',
+  sectionId: 'blog',
+  permission: 'blog.view',
+});
+```
+
+### Pages admin
+
+```js
+import { registerPage } from '@zen/core/features/admin';
+import BlogAdminPage from './admin/BlogAdminPage.client.js';
+
+registerPage({ slug: 'blog', Component: BlogAdminPage, title: 'Blog' });
+```
+
+Rendue sous `/admin/blog`.
+
+Pour l'en-tête des pages admin (titre, description, bouton retour, action), utiliser `AdminHeader` importé depuis `@zen/core/features/admin/components` :
+
+```js
+'use client';
+import { AdminHeader } from '@zen/core/features/admin/components';
+
+// Page liste avec bouton d'action
+export default function BlogListPage() {
+  return (
+    <div className="flex flex-col gap-6">
+      <AdminHeader
+        title="Billets"
+        description="Billets disponibles."
+        action={<Button onClick={...}>Créer un billet</Button>}
+      />
+      {/* ... */}
+    </div>
+  );
+}
+
+// Page formulaire avec bouton retour
+export default function BlogCreatePage() {
+  return (
+    <div className="flex flex-col gap-6">
+      <AdminHeader
+        title="Créer un billet"
+        description="Remplir les champs et enregistrer."
+        backHref="/admin/blog"
+      />
+      {/* ... */}
+    </div>
+  );
+}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Titre de la page. |
+| `description` | `string` | Sous-titre optionnel. |
+| `backHref` | `string` | Si fourni, affiche un bouton « ← Retour » qui navigue vers cette URL. |
+| `backLabel` | `string` | Label du bouton retour (défaut : `← Retour`). |
+| `action` | `ReactNode` | Élément affiché à droite (bouton créer, etc.). |
+
+### Médias attachés au contenu
+
+Pour qu'un module puisse attacher des médias (image à la une, galerie, PDF) à ses propres ressources, utiliser `@zen/core/features/media` côté serveur et `@zen/core/features/media/picker` côté client.
+
+```js
+// côté serveur — au moment de sauvegarder un billet :
+import { attachMedia, detachAllForSource } from '@zen/core/features/media';
+
+await attachMedia({
+  mediaId: payload.featuredImageId,
+  sourceType: '@zen/module-blog:post',
+  sourceId: post.id,
+  field: 'featured_image',
+});
+
+// au moment de supprimer le billet : libérer toutes les références.
+await detachAllForSource({ sourceType: '@zen/module-blog:post', sourceId: post.id });
+```
+
+```jsx
+// côté client — sélecteur dans un formulaire :
+'use client';
+import MediaPicker from '@zen/core/features/media/picker';
+
+<MediaPicker
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  accept="image/*"
+  visibility="public"
+  onSelect={(media) => setFeaturedImage(media)}
+/>
+```
+
+Le module Médias doit être activé (`ZEN_MEDIA=true`) dans le projet consommateur — sinon les permissions ne sont pas seedées et les API renvoient 403. Vérifier avec `isMediaEnabled()` côté serveur si on veut adapter l'UI.
+
+### Widgets dashboard
+
+```js
+// côté serveur
+import { registerWidgetFetcher } from '@zen/core/features/admin';
+registerWidgetFetcher('blog-posts', async () => ({ count: await countPosts() }));
+
+// côté client
+'use client';
+import { registerWidget } from '@zen/core/features/admin';
+registerWidget({ id: 'blog-posts', Component: BlogWidget, order: 40, permission: 'blog.view' });
+```
+
+### Routes API
+
+```js
+import { registerApiRoutes } from '@zen/core/api';
+import { defineApiRoutes, apiSuccess } from '@zen/core/api';
+
+const routes = defineApiRoutes([
+  { path: '/blog/posts',     method: 'GET',  handler: handleListPosts,  auth: 'admin', permission: 'blog.view' },
+  { path: '/blog/posts',     method: 'POST', handler: handleCreatePost, auth: 'admin', permission: 'blog.manage' },
+  { path: '/blog/posts/:id', method: 'GET',  handler: handleGetPost,    auth: 'public' },
+]);
+
+registerApiRoutes(routes);
+```
+
+Le router applique automatiquement la session, le rate-limit et la vérification de permission. Les routes sont accessibles sous `/zen/api/*`.
+
+| Champ `auth` | Comportement |
+|--------------|--------------|
+| `'public'` | Aucune session requise. |
+| `'user'` | Session valide. |
+| `'admin'` | Session avec permission `admin.access`. La permission granulaire `permission` est aussi vérifiée si fournie. |
+
+### Pages publiques `/zen/<module>/...`
+
+```js
+import { registerPublicModulePage } from '@zen/core/public-pages';
+import BlogPublicPage from './public/BlogPublicPage.js';
+
+registerPublicModulePage({ moduleName: 'blog', Component: BlogPublicPage });
+```
+
+URL : `/zen/blog/<...>`. Le composant reçoit `{ params, segments }` :
+
+```js
+function BlogPublicPage({ params, segments }) {
+  // /zen/blog/post/abc-123 → segments = ['post', 'abc-123']
+  if (segments[0] === 'post') return <PostView id={segments[1]} />;
+  return <BlogIndex />;
+}
+```
+
+Le namespace `api` est réservé aux routes API et ne peut être utilisé comme `moduleName`.
+
+### Migrations BD
+
+```js
+// db.js
+import { query, tableExists } from '@zen/core/database';
+
+const TABLES = [
+  { name: 'zen_blog_posts', sql: `CREATE TABLE zen_blog_posts (...)` },
+];
+
+export async function createTables() {
+  const created = [];
+  const skipped = [];
+  for (const t of TABLES) {
+    if (await tableExists(t.name)) { skipped.push(t.name); continue; }
+    await query(t.sql);
+    created.push(t.name);
+  }
+  return { created, skipped };
+}
+
+export async function dropTables() {
+  for (const t of [...TABLES].reverse()) {
+    await query(`DROP TABLE IF EXISTS "${t.name}" CASCADE`);
+  }
+}
+```
+
+Convention : préfixer toutes les tables par `zen_<module>_` pour éviter les collisions.
+
+---
+
+## Frontières serveur/client
+
+Un module avec partie admin expose **deux entrées** dans son `package.json#exports` :
+
+```json
+{
+  "exports": {
+    ".":        { "import": "./dist/index.js" },
+    "./client": { "import": "./dist/client.js" }
+  }
+}
+```
+
+| Entrée | Bundle | Contenu |
+|--------|--------|---------|
+| `.` (main) | serveur | `manifest`, `register()`, `createTables`, `dropTables`. Le `register()` tire la chaîne `register-server.js` (API routes, navigation, fetchers, storage prefixes, hooks DB). |
+| `./client` | client | `'use client'` ; uniquement `registerPage({ Component })` et `registerWidget({ Component })`. Aucun import vers `pg`, `fs`, `.server.js` ou `register-server.js`. |
+
+Le manifeste serveur importe `@zen/module-X` (main) ; le manifeste client importe `@zen/module-X/client`. La séparation est obligatoire : tout ce qui est statiquement importé depuis l'entrée client finit dans le bundle browser, et `pg` / `fs` / `next/headers` y crashent.
+
+```js
+// src/index.js (entrée serveur)
+export const manifest = { /* ... */ };
+export async function register() { await import('./register-server.js'); }
+export { createTables, dropTables } from './db.server.js';
+```
+
+```js
+// src/register-server.js (server-only — appelée par register())
+import { registerNavItem, registerNavSection } from '@zen/core/features/admin';
+import { registerApiRoutes } from '@zen/core/api';
+import { routes } from './api.server.js';
+// PAS d'import de Component .client.js ici — ils vivent dans client.js.
+registerNavSection({ /* ... */ });
+registerApiRoutes(routes);
+```
+
+```js
+// src/client.js (entrée client — chargée par le manifeste client uniquement)
+'use client';
+import { registerPage } from '@zen/core/features/admin';
+import BlogAdminPage from './admin/BlogAdminPage.client.js';
+registerPage({ slug: 'blog', Component: BlogAdminPage, title: 'Blog' });
+```
+
+### Sous-entrées `@zen/core/*` safe-pour-client
+
+Le `client.js` d'un module ne doit jamais importer un barrel mixte (un barrel qui ré-exporte du code serveur à côté de constantes client-safe). Si on le fait, Turbopack/Webpack tracent toute la chaîne d'imports statiques et ramènent `pg`/`fs`/`next/headers` dans le bundle browser — qui crashe avec `Module not found: Can't resolve 'dns'` ou équivalent.
+
+Sous-entrées explicitement safe pour un import depuis un fichier `'use client'` :
+
+| Sous-entrée | Contenu |
+|-------------|---------|
+| `@zen/core/users/constants` | `PERMISSIONS`, `PERMISSION_DEFINITIONS`, `getPermissionGroups` — aucun import serveur. |
+| `@zen/core/features/admin` | `registerPage`, `registerWidget`, `registerNavItem`, `registerNavSection`, `buildNavigationSections`. Neutre côté boundary. |
+| `@zen/core/features/admin/components` | Composants client : `AdminHeader`, `AdminShell`, `AdminSidebar`, `ThemeToggle`, modals. |
+| `@zen/core/features/media/picker` | Composant client `MediaPicker` (modale de sélection de média). Importer **uniquement ce sous-chemin** depuis un client — `@zen/core/features/media` (barrel) tire le code serveur. |
+| `@zen/core/themes` | Tokens/utilitaires de thème. |
+| `@zen/core/toast` | API toast côté client. |
+| `@zen/core/shared/icons` | Composants d'icônes. |
+| `@zen/core/shared/components` | Composants partagés. |
+
+Tout ce qui n'est pas dans cette liste — en particulier `@zen/core/users` (barrel complet), `@zen/core/database`, `@zen/core/api`, `@zen/core/storage` — est du code serveur. Ne JAMAIS l'importer depuis un fichier `'use client'` ou un fichier transitivement importé par un `'use client'`.
+
+---
+
+## Variables d'environnement
+
+Toute variable requise par le module doit être déclarée dans `manifest.envVars` et documentée dans le `README.md` du module. Les variables `required: true` absentes génèrent un warning au boot — elles ne crashent pas le serveur, le module gère son propre fallback.
+
+---
+
+## Classes Tailwind
+
+Le projet consommateur importe `@zen/core/styles/zen.css`, qui déclare deux directives `@source` :
+
+1. `@source "../../**/*.js"` — scanne `node_modules/@zen/core/dist/**/*.js`
+2. `@source "../../../../module-*/dist/**/*.js"` — scanne `node_modules/@zen/module-*/dist/**/*.js`
+
+Conséquence pour un module : les classes Tailwind utilisées dans les composants du module sont générées **automatiquement** par le Tailwind du consommateur, à condition que :
+
+- Le package soit publié sous le nom `@zen/module-<nom>` (la convention est déjà imposée par la découverte runtime des modules).
+- Les fichiers compilés se trouvent dans `dist/` (pattern de scan).
+
+Aucune action n'est requise côté module ni côté consommateur — un module peut donc utiliser librement n'importe quelle classe Tailwind, y compris des variantes responsives (`md:`, `lg:`...) ou des valeurs arbitraires (`w-[300px]`).
+
+---
+
+## Squelette minimal d'un module
+
+```
+@zen/module-blog/
+├── package.json          # name: "@zen/module-blog", main: "./dist/index.js"
+├── tsup.config.js        # build avec bundle: false, loader JSX, outbase: 'src'
+├── README.md             # documente les env vars et la configuration
+├── src/
+│   ├── index.js              # exporte manifest, register, createTables, dropTables
+│   ├── db.server.js          # createTables/dropTables
+│   ├── register-server.js    # imports déclencheurs (chargé par register())
+│   ├── api.server.js         # routes API (registerApiRoutes)
+│   ├── admin/
+│   │   ├── BlogAdminPage.client.js    # registerPage + composant
+│   │   └── widgets/...                # registerWidgetFetcher + registerWidget
+│   └── public/
+│       └── BlogPublicPage.js          # registerPublicModulePage
+└── dist/                 # généré par `npm run build` — c'est ce qui est publié
+```
+
+Le champ `files` dans `package.json` publie **uniquement** `dist/`, `README.md` et `LICENSE` :
+
+```json
+{
+  "main": "./dist/index.js",
+  "exports": { ".": { "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  }
+}
+```
+
+---
+
+## Build avant publish
+
+**Tout module `@zen/module-*` est pré-compilé avant publication**, comme `@zen/core` lui-même. Le build `tsup` avec `bundle: false` transforme le JSX, préserve les directives `'use client'` en haut des fichiers compilés, et garde un fichier d'entrée par fichier de sortie pour respecter les frontières RSC quand le projet consommateur bundle le module.
+
+C'est ce qui permet au manifeste statique généré par `zen-modules sync` de simplement faire `import * as ... from '@zen/module-X'` et de laisser Turbopack/Webpack composer le reste : aucune transformation runtime n'est requise côté consommateur.
+
+### Exemple de `tsup.config.js` minimal
+
+```js
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/**/*.js', 'src/**/*.jsx'],
+  format: ['esm'],
+  outDir: 'dist',
+  outbase: 'src',
+  bundle: false,
+  splitting: false,
+  clean: true,
+  loader: { '.js': 'jsx' },
+  jsx: 'automatic',
+});
+```
+
+### Vérifier qu'un module est correctement compilé
+
+Avant `npm publish`, ouvrir `dist/` et confirmer qu'aucun fichier ne contient de syntaxe JSX brute (chercher `<` suivi d'une majuscule). Tous les composants doivent apparaître sous forme d'appels `jsx(...)` ou `React.createElement(...)`.
+
+---
+
+## Cycle de vie complet
+
+| Étape | Côté core | Côté module |
+|-------|-----------|-------------|
+| Install | — | `npm install @zen/module-X` |
+| Configuration | — | Ajout des `envVars` au `.env` |
+| Migration BD | `zen-db init` scanne, charge le module, registerPermissions(), seed, createTables() | `createTables()` exécuté |
+| Boot serveur | `instrumentation.js` → `initializeZen()` scanne, charge, registerPermissions(), `register()` | `register()` exécuté côté serveur |
+| Premier render client | bundle client traverse les imports → composants client enregistrés | `registerWidget()` exécuté côté client |
+| Runtime | router dispatch les requêtes, admin résout les pages/widgets via le registre | aucun travail supplémentaire |

docs/PROJECT.md

@@ -0,0 +1,71 @@
+# ZEN — Plan du projet
+
+> Une plateforme multi-usage construite sur l'essentiel, rien de plus, rien de moins.
+
+ZEN est une plateforme admin Next.js qui sert de base à tout type d'application : site vitrine, système de facturation, espace cloud, boutique en ligne, ou n'importe quoi d'autre. L'admin est extensible, on y greffe ce qu'on veut, sans modifier le core.
+
+Elle s'installe automatiquement dans n'importe quel projet Next.js via :
+
+```bash
+npx @zen/start
+```
+
+Le package principal est `@zen/core`. Il fournit toute l'infrastructure fondamentale : authentification, base de données, stockage, courriels, paiements, PDF, tâches planifiées, notifications. Chaque fonctionnalité est indépendante — les cores ne se connaissent pas entre eux. Le reste de la plateforme s'appuie sur chacun d'eux sans les coupler.
+
+---
+
+## Principes directeurs
+
+**Core purity** — Chaque core contient uniquement du code propre à son domaine. Aucune logique métier, aucune dépendance vers un autre core.
+
+**Minimal by default** — Pas de fonctionnalité superflue. Si ce n'est pas nécessaire, ça n'existe pas.
+
+**Sécuritaire par défaut** — Requêtes paramétrées, protection CSRF, limitation de débit, validation en entrée, erreurs opaques vers le client.
+
+**Performant** — Connexions en pool, cache HTTP, génération différée des services.
+
+---
+
+## Structure du projet
+
+```
+src/
+  core/         # Infrastructure fondamentale — la base de tout
+  features/     # Fonctionnalités de la palteforme utilisant les cores
+  shared/       # Utilitaires, composants et styles partagés
+```
+---
+
+## Résumé des règles absolues
+
+| Domaine | Règle |
+|---|---|
+| API | Toutes les routes HTTP passent par `core/api`. Aucune autre route API. |
+| Base de données | Tout accès DB passe par `core/database`. Jamais de requêtes directes. |
+| Courriels | Tout envoi de courriel passe par `core/email`. |
+| Cron | Toutes les tâches planifiées s'enregistrent dans `core/cron`. |
+| Stockage | Tout accès fichier passe par `core/storage`. |
+| Notifications | Un seul système de toast dans toute l'app : `core/toast`. |
+| Authentification | Toute auth de site passe par `features/auth`. |
+
+---
+
+### Pas de `next/headers` ni `next/navigation` au top-level dans la chaîne `register()` des modules
+
+Tout fichier qui peut être atteint depuis le `register()` d'un module externe (directement ou transitivement, via un barrel `@zen/core/*` qu'il importe) **ne doit pas** importer `next/headers` ou `next/navigation` au top-level. L'import doit être lazy à l'intérieur du handler :
+
+```js
+export async function handleSomething(request) {
+  const { cookies } = await import('next/headers');
+  // ...
+}
+```
+
+**Pourquoi.** [`discover.server.js`](../src/core/modules/discover.server.js) charge chaque module via `import(/* turbopackIgnore */ name)` pour empêcher Turbopack/Webpack de bundler un nom dynamique. Conséquence : Node résout tout l'arbre d'imports transitifs en ESM natif, **sans** la condition `react-server`. Or `next/headers` (Next.js 15+) n'est exposé que via cette condition — un import top-level échoue alors avec `Cannot find module 'next/headers'`.
+
+**Conséquences pratiques.**
+
+- Les fichiers qui ont besoin de Next.js au top-level (par ex. [`features/admin/protect.js`](../src/features/admin/protect.js), [`features/auth/actions.js`](../src/features/auth/actions.js)) ne sont jamais réexportés par les barrels accessibles aux modules ; ils sont exposés via des sous-chemins dédiés dans `package.json#exports` (ex. `@zen/core/features/admin/protect`).
+- Pour les handlers qui restent dans un barrel exposé (ex. [`core/api/router.js`](../src/core/api/router.js), [`core/storage/api.js`](../src/core/storage/api.js)), `cookies` et compagnie sont importés en lazy à l'intérieur du handler.
+
+Avant d'ajouter un `import { cookies } from 'next/headers'` à un fichier core, vérifier qu'aucun barrel exposé aux modules ne le tire transitivement. Sinon, garder l'import lazy.

docs/dev/ARCHITECTURE.md

@@ -0,0 +1,38 @@
+# Architecture partagée
+
+Ces modules existent pour éviter la duplication. Avant d'écrire du code utilitaire, vérifier s'il est déjà couvert ici.
+
+### Utilitaires serveur
+
+| Besoin | Module |
+|--------|--------|
+| Logs serveur | `src/shared/lib/logger.js` |
+| Manipulation de dates | `src/shared/lib/dates.js` |
+| Configuration de l'app | `src/shared/lib/appConfig.js` |
+| Formatage de devises | `src/shared/utils/currency.js` |
+
+### Composants et icônes
+
+**Icônes** — Toutes les icônes sont centralisées dans `src/shared/Icons.js`. Ne pas créer d'icône directement dans un composant. Si une icône manque, l'ajouter dans `Icons.js`.
+
+**Composants** — Utiliser `src/shared/components` en priorité. Si un besoin est réutilisable à plusieurs endroits et que le composant n'existe pas encore, le créer dans `src/shared/components` plutôt que dans le module.
+
+### Modules core
+
+**Notifications client** — Utiliser `src/core/toast` pour toutes les notifications côté client.
+
+**Stockage** — Utiliser `src/core/storage`. Toujours supprimer l'ancien fichier avant d'en écrire un nouveau à la même place. Éviter les fichiers fantômes (présents dans le stockage mais plus référencés dans l'app).
+
+**Paiements** — Utiliser `src/core/payments` pour tout ce qui touche au système de paiement.
+
+**Courriel** — Utiliser `src/core/email` pour l'envoi d'emails. Les gabarits réutilisables à l'échelle de l'app vont dans `src/core/email/templates`. Les gabarits spécifiques à un module peuvent rester dans les fichiers du module.
+
+**Base de données** — Utiliser `src/core/database` pour toutes les communications avec la BD. Toujours utiliser des requêtes paramétrées (voir la section Sécurité ci-dessus).
+
+**Tâches planifiées** — Utiliser `src/core/cron` pour créer des tâches cron.
+
+**API** — Utiliser `src/core/api` pour l'API admin et publique. Définir les routes avec `defineApiRoutes()` (valide la config au démarrage). L'authentification est déclarée dans la définition de route (`auth: 'public' | 'user' | 'admin'`) — ne jamais la vérifier manuellement dans un handler. Retourner `apiSuccess()` / `apiError()` dans tous les handlers. Voir `src/core/api/README.md` pour le détail.
+
+**Médias** — Pour gérer les fichiers attachés au contenu publié (images, PDFs, vidéos), utiliser `src/features/media`. Activable via `ZEN_MEDIA=true`. Expose `uploadMedia`/`deleteMedia`/`attachMedia`/`detachMedia` côté serveur et un composant `MediaPicker` réutilisable côté client. Voir `src/features/media/README.md`. Distinct d'un futur module `files` (style Drive/Dropbox) — ne pas confondre les deux usages.
+
+Pour **afficher** une image média, utiliser le wrapper `MediaImage` du module (pas `<img>` direct, pas `next/image` direct). Il route les médias publics via `next/image` (srcset AVIF/WebP, lazy) et garde un `<img>` natif pour les médias privés — `/_next/image` cache la réponse optimisée par URL et fuiterait l'image privée à tous les visiteurs après le premier hit.

docs/dev/COMMITS.md

@@ -0,0 +1,56 @@
+# Conventions de commit
+
+Tous les messages de commit sont rédigés en **anglais**, en suivant le format [Conventional Commits](https://www.conventionalcommits.org/) :
+
+```
+<type>(<scope>): <description courte>
+```
+
+---
+
+## Types
+
+| Type | Usage |
+|------|-------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring without behavior change |
+| `style` | Formatting only (spaces, commas, no logic change) |
+| `docs` | Documentation only |
+| `test` | Add or update tests |
+| `chore` | Maintenance, dependencies, build config |
+| `perf` | Performance improvement |
+| `revert` | Revert a previous commit |
+
+---
+
+## Exemples
+
+```
+feat(auth): add OAuth2 login support
+fix(api): handle null response from payment gateway
+refactor(storage): extract upload logic into helper
+docs(guide): add git commit message conventions
+chore(deps): update dependencies
+perf(db): cache user metadata on repeated reads
+revert: revert "feat(auth): add OAuth2 login support"
+```
+
+---
+
+## Règles
+
+- **Scope** : facultatif, précise la zone touchée `auth`, `api`, `storage`, `ui`, `config`
+- **Description** : minuscules, sans point final, en anglais
+- Un commit = une intention. Ne pas mélanger fix et refactor
+- Pas de `wip`, `fix fix`, `oups` ou messages vides
+
+## Breaking changes
+
+Ajouter `!` après le type et un pied de page `BREAKING CHANGE:` :
+
+```
+feat(api)!: remove legacy query parameter
+
+BREAKING CHANGE: the `legacy` param is no longer accepted, use `version` instead.
+```

docs/dev/LANGUE.md

@@ -1,4 +1,4 @@
-# GUIDE
+# LANGUE
 
 ## Langue du code
 
@@ -16,22 +16,6 @@ Tout ce qui est **visible par l'utilisateur** est en **français** :
 - Slugs et noms de dossiers qui correspondent à des routes URL
 - Documentations, README.md
 
-## Messages de commit Git
-
-Tous les messages de commit doivent être rédigés en **anglais**, en suivant le format conventional commits :
-
-```
-<type>(<scope>): <description courte>
-```
-
-Types courants : `feat`, `fix`, `refactor`, `style`, `docs`, `test`, `chore`
-
-Exemples :
-- `feat(auth): add OAuth2 login support`
-- `fix(api): handle null response from payment gateway`
-- `docs(guide): add git commit message conventions`
-- `chore(deps): update dependencies`
-
 ## Guide de rédaction
 
 Se référer à `REDACTION.md` avant de rédiger tout contenu textuel.

docs/dev/PUBLICATION.md

@@ -0,0 +1,37 @@
+# Publier le package
+
+Le package `@zen/core` est publié sur le registre npm privé à `https://git.hyko.cx`.
+
+### Configurer l'authentification (une seule fois)
+
+Créer un token dans Gitea : **Settings → Applications → Generate Token**, puis :
+
+```bash
+npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
+```
+
+### Checklist avant publication
+
+- [ ] `npm audit` — aucune vulnérabilité `high` ou `critical`
+- [ ] `npm run build` — build sans erreur ni warning TypeScript
+- [ ] Version mise à jour dans `package.json`
+
+### Versionner
+
+On suit [semver](https://semver.org) :
+
+- **patch** (`1.3.x`) — correction de bug, sans changement d'interface
+- **minor** (`1.x.0`) — nouvelle fonctionnalité, rétrocompatible
+- **major** (`x.0.0`) — changement cassant
+
+```bash
+npm version patch   # ou minor, ou major
+```
+
+### Publier
+
+```bash
+npm publish
+```
+
+Le script `prepublishOnly` lance le build automatiquement. Si le build échoue, la publication est annulée.

docs/dev/REDACTION.md

@@ -1,163 +1,139 @@
-# GUIDE DE RÉDACTION
-Dernière modification : 2026-04-12
+# Rédaction
 
-## La voix de l'entreprise
-
-On parle comme une personne, pas comme une organisation. Direct, sans fioritures.
-
-On dit **"on"** — jamais "nous sommes heureux de", jamais "notre équipe d'experts". Une seule exception : quand on cite quelqu'un nommément, on peut utiliser "je".
-
-La technique est là parce qu'elle est utile, pas pour impressionner. Si une explication technique ne sert pas le lecteur, elle ne sert pas le texte.
+Ce guide s'applique à tout contenu textuel visible par l'utilisateur dans ce projet : l'interface admin, les messages d'état, les documentations dans `docs/` et les README.
 
 ---
 
-## Ce qu'on évite absolument
+## Deux contextes, deux voix
 
-**Les superlatifs vides**
-*de premier plan, leader, de pointe, best-in-class, incontournable*
+**Interface (labels, messages, descriptions)** : la plateforme rapporte ce qui s'est passé. On utilise l'impersonnel et le passif descriptif. L'utilisateur est le sujet implicite.
 
-**Les promesses floues**
-*solutions sur mesure, accompagnement personnalisé, approche holistique*
+**Documentation** : on s'adresse directement au développeur qui lit. Phrases courtes, verbes actifs, ton direct.
+
+---
+
+## Ce qu'on évite partout
+
+**Superlatifs et formules vides**
+*de premier plan, robuste, puissant, tout-en-un, intuitif, seamless*
 
 **Le corporate**
-*nous nous engageons à, notre mission est de, dans une optique de, à cet effet*
+*notre plateforme vous permet de, dans une optique de, à cet effet*
 
-**La sur-promesse**
-Si on ne peut pas le garantir, on ne l'écrit pas. Jamais.
-
-**Les métaphores usées**
-*pont entre, clé en main, écosystème, synergies, à 360°*
+**Chevilles inutiles**
+*Ainsi, En effet, Il convient de noter que, N'hésitez pas à, Veuillez noter que*
 
 **Le tiret long (—)**
-Reformuler la phrase plutôt que d'insérer une incise.
+Reformuler la phrase à la place.
 
-**Les chevilles inutiles**
-*Ainsi, En effet, Il convient de noter que, N'hésitez pas à*
-
-**Le passif sans raison**
-Préférer la forme active. "On a livré le projet" plutôt que "le projet a été livré".
+**La sur-promesse**
+Si on ne peut pas le garantir, on ne l'écrit pas.
 
 ---
 
-## Formules qui marchent
+## Interface
 
-**Plutôt ça :**
-> "On dit non quand c'est la bonne réponse."
-> "On pense à comment les choses vont tenir dans six mois."
-> "Ce n'est pas le bon projet pour nous. Voilà pourquoi."
+### Voix de l'interface
 
-**Pas ça :**
-> "Notre approche centrée client garantit des résultats optimaux."
-> "Nous mettons notre expertise au service de vos ambitions."
-> "Une équipe passionnée à votre écoute."
+La plateforme rapporte. Elle ne dit pas "on a fait" — elle dit ce qui s'est passé.
 
-**La règle d'or :** si ça pourrait figurer dans la communication d'un concurrent sans changer un mot, c'est à réécrire.
+> ✓ "Les modifications ont été enregistrées."
+> ✓ "La page a été supprimée."
+> ✗ "On a enregistré vos modifications."
+> ✗ "Nous avons bien reçu votre demande."
+
+Pas de "vous" ni de "nous". L'état parle pour lui-même.
+
+### Labels et boutons
+
+Courts, un verbe d'action à l'infinitif, sans point.
+
+> ✓ "Enregistrer", "Supprimer", "Ajouter une page"
+> ✗ "Cliquez ici pour enregistrer vos modifications"
+
+Pas de majuscule à chaque mot.
+
+> ✓ "Ajouter un élément"
+> ✗ "Ajouter Un Élément"
+
+### Messages d'erreur
+
+Nommer ce qui ne va pas. Dire quoi faire si c'est utile.
+
+> ✓ "Ce champ est requis."
+> ✓ "Ce slug est déjà utilisé. Choisir un autre."
+> ✗ "Une erreur s'est produite. Veuillez réessayer."
+
+Pas de code d'erreur technique si l'utilisateur n'est pas développeur.
+
+### Messages de confirmation
+
+Une phrase. Ce qui s'est passé, au passé passif. Sans "avec succès".
+
+> ✓ "Page enregistrée."
+> ✓ "Modifications enregistrées."
+> ✓ "Élément supprimé."
+> ✗ "Vos modifications ont été enregistrées avec succès !"
+
+### États vides
+
+Expliquer la situation, pas juste la constater. Ajouter l'action à faire si applicable.
+
+> ✓ "Aucune page pour l'instant. Créer la première."
+> ✗ "Aucun résultat trouvé."
+
+### Textes d'aide et descriptions
+
+Une phrase. Répondre à "pourquoi" ou "comment", pas aux deux.
+
+> ✓ "Utilisé dans l'URL. Ne peut pas être modifié après publication."
+> ✗ "Le slug est un identifiant unique utilisé pour générer l'URL de la page. Il doit être en minuscules et ne peut pas contenir d'espaces ou de caractères spéciaux."
 
 ---
 
-## Structure des textes
+## Documentation
+
+### Voix de la documentation
+
+On s'adresse directement au développeur. Verbes actifs, phrases courtes, sans intermédiaire.
+
+> ✓ "Le registre permet d'ajouter des widgets sans toucher au core. Importer `registerWidget` et passer un composant."
+> ✗ "Le registre est un système centralisé qui permet la gestion modulaire des composants d'interface."
+
+### Structure
+
+- **Titre :** ce que le document permet de faire.
+- **Première phrase :** pourquoi ce document existe, à qui il s'adresse.
+- **Prérequis si nécessaire :** ce qu'il faut savoir ou avoir avant.
+- **Corps :** une idée par section, titres descriptifs.
+- **Notes :** à la fin, pas dans le milieu.
 
 ### Titres
-Courts, affirmatifs, sans point. Une idée, pas une liste. Pas de question rhétorique.
 
-> ✓ "Zéro raccourci. Zéro compromis."
-> ✓ "On livre. On reste."
-> ✗ "Une approche rigoureuse pour des résultats durables"
-> ✗ "Pourquoi nous choisir ?"
+Descriptifs, pas génériques.
+
+> ✓ "Ajouter un widget à l'admin"
+> ✗ "Configuration"
 
 ### Corps de texte
-Phrases courtes. Une idée par phrase. Maximum deux virgules par phrase — si on en compte plus, couper.
 
-Paragraphes de trois à quatre phrases maximum. Une ligne blanche entre chaque paragraphe.
+Phrases courtes. Une idée par phrase. Paragraphes de trois à quatre phrases maximum.
 
-Pas de bullet points pour des concepts. Seulement pour des listes réelles (étapes, éléments techniques, options).
+Commencer par un constat ou une situation concrète, pas par une définition.
 
-### Appels à l'action
-Concrets et à l'infinitif. Pas d'exclamation.
-
-> ✓ "Discuter de votre projet"
-> ✓ "Voir comment on travaille"
-> ✗ "Contactez-nous pour en savoir plus !"
-> ✗ "Passez à l'action"
+Pas de listes à puces pour des explications. Les listes servent pour les étapes, les options, les éléments techniques.
 
 ---
 
-## Selon le format
+## Révision avant de livrer
 
-### Site web
-Chaque page a une seule idée principale. Le visiteur doit comprendre l'essentiel en dix secondes. Les détails viennent après, pour ceux qui cherchent.
-
-Pas de jargon en page d'accueil. Le jargon technique appartient aux pages de service, là où le lecteur s'y attend.
-
-### Courriels
-Objet : concret, pas accrocheur. Dire ce dont il s'agit, pas promettre quelque chose.
-
-> ✓ "Proposition — Refonte infrastructure"
-> ✗ "Une opportunité à ne pas manquer"
-
-Corps du courriel : aller droit au but dès la première phrase. Pas de "j'espère que ce message vous trouve bien." Si on doit écrire plus de quatre paragraphes, se demander si c'est le bon format.
-
-### Applications et interfaces
-Chaque message, étiquette ou instruction doit avoir un seul sens possible. Pas de formulation qui force l'utilisateur à interpréter.
-
-Le ton reste humain, même dans un contexte technique. "Une erreur s'est produite" est mieux que "Erreur 403 — accès non autorisé" si le lecteur n'est pas développeur.
-
-Les messages de confirmation, d'erreur et d'aide suivent les mêmes règles que le reste : courts, directs, actifs.
-
-### Articles et billets
-Un angle précis, pas un survol. Mieux vaut un article sur un problème concis que dix paragraphes vagues.
-
-Commencer par un fait, un constat ou une situation — pas par une définition.
-
-> ✓ "La plupart des migrations ratent pour la même raison : on sous-estime ce qui dépend de ce qu'on déplace."
-> ✗ "La migration de données est un processus complexe qui nécessite une planification rigoureuse."
-
-Terminer sur ce qu'on retient, pas sur une invitation à nous contacter.
-
-### Propositions et soumissions
-Pas de section "qui sommes-nous" en ouverture. Le client le sait déjà ou s'en fout pour l'instant.
-
-Commencer par le problème du client, tel qu'on l'a compris. S'il se reconnaît dans les deux premiers paragraphes, le reste a de la valeur.
-
-La solution vient après le diagnostic. Jamais avant.
-
-### Documents internes
-Mêmes règles de clarté que pour les textes externes. Un document interne mal écrit crée autant de confusion qu'une mauvaise communication client.
-
-Titres de section descriptifs, pas génériques. "Décision retenue et raison" est mieux que "Résultats".
-
-Si un document dépasse deux pages, se demander si l'information ne serait pas mieux transmise autrement.
-
-### Réseaux sociaux
-Un seul message par publication. Si on a besoin d'un fil de publications pour expliquer, c'est probablement un article.
-
-Le ton reste celui de l'entreprise — pas plus décontracté sous prétexte que c'est un réseau social.
-
-Pas de hashtags décoratifs. Seulement ceux qui servent la découverte du contenu.
+- [ ] La première phrase dit déjà l'essentiel.
+- [ ] Chaque phrase dit quelque chose. Les phrases qui meublent sont supprimées.
+- [ ] L'interface utilise l'impersonnel. La doc s'adresse directement au lecteur.
+- [ ] Il n'y a pas de tiret long (—).
+- [ ] Les fautes sont corrigées.
+- [ ] L'utilisateur sait quoi faire ou quoi retenir après avoir lu.
 
 ---
 
-## Parler de ce qu'on fait
-
-Ne jamais affirmer qu'on est "les meilleurs" ou "différents des autres". Le montrer, pas le dire.
-
-Quand on parle de ce qu'on fait, on parle de situations concrètes. Pas de généralités.
-
-> ✓ "On a refusé un mandat parce que le calendrier ne tenait pas."
-> ✗ "On valorise l'honnêteté dans nos relations clients."
-
----
-
-## Révision d'un texte
-
-Avant de publier ou d'envoyer, se poser ces questions :
-
-1. **Est-ce qu'un concurrent pourrait signer ce texte ?** Si oui, réécrire.
-2. **Est-ce qu'on promet quelque chose qu'on ne contrôle pas ?** Retirer ou nuancer.
-3. **Est-ce que chaque phrase dit quelque chose ?** Supprimer celles qui ne font que meubler.
-4. **Est-ce que le lecteur sait quoi faire ou quoi penser après ?** Si non, préciser.
-5. **A-t-on utilisé le mot "solution" ?** Le remplacer. Presque toujours.
-
----
-
-*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, on l'ajuste.*
+*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, l'ajuster.*

docs/modules/EXTERNAL_MODULE.md

@@ -1,255 +0,0 @@
-# Créer un module externe
-
-Un module externe est un package npm indépendant qui s'intègre dans une app qui utilise `@zen/core`. Il n'a pas besoin de modifier le code source du CMS.
-
----
-
-## Convention de nommage
-
-```
-@scope/zen-nom-du-module
-```
-
-Exemples : `@zen/core-invoice`, `@zen/core-nuage`.
-
----
-
-## Structure du package
-
-```
-zen-invoice/
-├── index.js             # Point d'entrée — exporte defineModule()
-├── admin/               # Composants React pour l'admin
-│   ├── InvoiceListPage.js
-│   ├── InvoiceCreatePage.js
-│   └── InvoiceEditPage.js
-├── db.js                # createTables() et dropTables()
-├── actions.js           # Server actions pour pages publiques
-├── metadata.js          # Générateurs de métadonnées SEO
-├── package.json
-└── .env.example
-```
-
----
-
-## index.js
-
-On utilise `defineModule()` importé depuis `@zen/core/modules/define`.
-
-```js
-import { lazy } from 'react';
-import { defineModule } from '@zen/core/modules/define';
-
-import { createTables, dropTables } from './db.js';
-import { getInvoiceByToken } from './actions.js';
-import { generatePaymentMetadata } from './metadata.js';
-
-const InvoiceListPage   = lazy(() => import('./admin/InvoiceListPage.js'));
-const InvoiceCreatePage = lazy(() => import('./admin/InvoiceCreatePage.js'));
-const InvoiceEditPage   = lazy(() => import('./admin/InvoiceEditPage.js'));
-
-export default defineModule({
-  name: 'invoice',
-  displayName: 'Facturation',
-  version: '1.0.0',
-  description: 'Gestion des factures et paiements.',
-
-  dependencies: [],
-  envVars: ['STRIPE_SECRET_KEY', 'ZEN_INVOICE_TAX_RATE'],
-
-  // Navigation dans le panneau admin
-  navigation: [
-    {
-      id: 'invoice',
-      title: 'Facturation',
-      icon: 'Invoice03Icon',
-      items: [
-        { name: 'Factures', href: '/admin/invoice/list', icon: 'Invoice03Icon' },
-        { name: 'Nouvelle', href: '/admin/invoice/new',  icon: 'Add01Icon' },
-      ],
-    },
-  ],
-
-  // Pages admin avec leurs composants lazy
-  adminPages: {
-    '/admin/invoice/list': InvoiceListPage,
-    '/admin/invoice/new':  InvoiceCreatePage,
-    '/admin/invoice/edit': InvoiceEditPage,
-  },
-
-  // Résolveur pour les routes dynamiques (ex: /admin/invoice/edit/123)
-  pageResolver(path) {
-    const parts = path.split('/').filter(Boolean);
-    if (parts[0] !== 'admin' || parts[1] !== 'invoice') return null;
-    if (parts[2] === 'list') return InvoiceListPage;
-    if (parts[2] === 'new')  return InvoiceCreatePage;
-    if (parts[2] === 'edit') return InvoiceEditPage;
-    return null;
-  },
-
-  publicPages: {},
-  publicRoutes: [
-    { pattern: ':token',     description: 'Page de paiement' },
-    { pattern: ':token/pdf', description: 'Télécharger la facture PDF' },
-  ],
-
-  dashboardWidgets: [],
-
-  // Base de données
-  db: { createTables, dropTables },
-
-  // Server actions pour les pages publiques (/zen/invoice/...)
-  actions: { getInvoiceByToken },
-
-  // Générateurs de métadonnées SEO
-  metadata: {
-    payment: generatePaymentMetadata,
-  },
-
-  // Appelé une fois au démarrage du serveur
-  // ctx donne accès aux services du CMS
-  async setup(ctx) {
-    const stripe = await ctx.payments.then(p => p.stripe);
-    // Initialiser des webhooks, vérifier la config, etc.
-    console.log('[invoice] Stripe prêt :', !!stripe);
-  },
-});
-```
-
----
-
-## L'objet ctx dans setup()
-
-`setup(ctx)` reçoit un objet qui donne accès aux services du CMS. Chaque propriété retourne une promesse vers le module correspondant.
-
-```js
-async setup(ctx) {
-  // Base de données PostgreSQL
-  const { query, queryOne, queryAll } = await ctx.db;
-  const rows = await query('SELECT * FROM zen_auth_users LIMIT 1');
-
-  // Envoi de courriels (Resend)
-  const { sendEmail } = await ctx.email;
-  await sendEmail({ to: 'test@example.com', subject: 'Test', html: '<p>ok</p>' });
-
-  // Stockage de fichiers (Cloudflare R2)
-  const { uploadFile, deleteFile } = await ctx.storage;
-
-  // Stripe
-  const { stripe } = await ctx.payments;
-
-  // Variables d'environnement
-  const apiKey = ctx.config.get('STRIPE_SECRET_KEY');
-}
-```
-
----
-
-## package.json du module externe
-
-```json
-{
-  "name": "@zen/core-invoice",
-  "version": "1.0.0",
-  "type": "module",
-  "main": "./index.js",
-  "exports": {
-    ".": "./index.js"
-  },
-  "peerDependencies": {
-    "@zen/core": ">=1.0.0",
-    "react": ">=19.0.0"
-  }
-}
-```
-
----
-
-## Intégration dans l'app consommatrice
-
-### 1. Installer le package
-
-```bash
-npm install @zen/core-invoice
-```
-
-### 2. Créer zen.config.js à la racine de l'app
-
-```js
-// zen.config.js
-import invoiceModule from '@zen/core-invoice';
-
-export default {
-  modules: [invoiceModule],
-};
-```
-
-### 3. Passer la config à initializeZen()
-
-```js
-// instrumentation.js
-import zenConfig from './zen.config.js';
-
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { initializeZen } = await import('@zen/core');
-    await initializeZen(zenConfig);
-  }
-}
-```
-
-### 4. Passer les modules à ZenProvider
-
-```jsx
-// app/layout.js
-import zenConfig from './zen.config.js';
-import { ZenProvider } from '@zen/core/provider';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <ZenProvider modules={zenConfig.modules}>
-          {children}
-        </ZenProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-### 5. Activer le module via variable d'environnement
-
-```bash
-# .env.local
-ZEN_MODULE_INVOICE=true
-```
-
-La convention est la même que pour les modules internes : tirets en underscores, tout en majuscules.
-
----
-
-## Initialiser la base de données
-
-Le module déclare ses tables dans `db.createTables`. Deux façons de les créer.
-
-**Au démarrage du serveur** (si `skipDb: false`) :
-
-```js
-await initializeZen({ modules: zenConfig.modules, skipDb: false });
-```
-
-**Via la CLI** :
-
-```bash
-npx zen-db init
-```
-
----
-
-## Vérification rapide
-
-1. Démarrer avec `ZEN_MODULE_INVOICE=true`.
-2. Ouvrir `/admin`. La section "Facturation" doit apparaître dans la navigation.
-3. Naviguer vers `/admin/invoice/list`. La page du module doit se charger.
-4. Appeler `getModuleActions('invoice')` côté serveur. Les actions du module doivent être retournées.

docs/modules/INTERNAL_MODULE.md

@@ -1,218 +0,0 @@
-# Créer un module interne
-
-Un module interne vit dans `src/modules/` et fait partie du package `@zen/core`. Il a accès direct aux services du CMS sans passer par un contexte injecté.
-
----
-
-## Structure d'un module
-
-```
-src/modules/mon-module/
-├── module.config.js   # Obligatoire — navigation, pages, routes, cron, etc.
-├── db.js              # Optionnel — createTables() et dropTables()
-├── api.js             # Optionnel — routes REST
-├── cron.config.js     # Optionnel — tâches planifiées
-├── crud.js            # Optionnel — accès aux données
-├── admin/             # Composants React pour l'admin
-└── .env.example       # Variables d'environnement requises
-```
-
----
-
-## module.config.js
-
-C'est la source de vérité du module. On utilise `defineModule()` pour déclarer la configuration.
-
-```js
-import { lazy } from 'react';
-import { defineModule } from '../../core/modules/defineModule.js';
-
-const ListPage   = lazy(() => import('./admin/ListPage.js'));
-const CreatePage = lazy(() => import('./admin/CreatePage.js'));
-const EditPage   = lazy(() => import('./admin/EditPage.js'));
-
-export default defineModule({
-  name: 'mon-module',
-  displayName: 'Mon module',
-  version: '1.0.0',
-  description: 'Description courte.',
-
-  // Modules dont celui-ci dépend (vérification au démarrage)
-  dependencies: [],
-
-  // Variables d'environnement que ce module lit
-  envVars: ['ZEN_MON_MODULE_OPTION'],
-
-  // Navigation admin — un ou plusieurs objets de section
-  navigation: [
-    {
-      id: 'mon-module',
-      title: 'Mon module',
-      icon: 'SomeIcon',
-      items: [
-        { name: 'Liste', href: '/admin/mon-module/list', icon: 'SomeIcon' },
-        { name: 'Nouveau', href: '/admin/mon-module/new', icon: 'AddIcon' },
-      ],
-    },
-  ],
-
-  // Pages admin — chemin exact vers composant lazy
-  adminPages: {
-    '/admin/mon-module/list': ListPage,
-    '/admin/mon-module/new':  CreatePage,
-    '/admin/mon-module/edit': EditPage,
-  },
-
-  // Résolveur pour les routes dynamiques (non connues à la compilation)
-  // Retourner null si le chemin ne correspond pas
-  pageResolver(path) {
-    const parts = path.split('/').filter(Boolean);
-    if (parts[0] !== 'admin' || parts[1] !== 'mon-module') return null;
-    if (parts[2] === 'list') return ListPage;
-    if (parts[2] === 'new')  return CreatePage;
-    if (parts[2] === 'edit') return EditPage;
-    return null;
-  },
-
-  // Pages publiques accessibles sans authentification (/zen/mon-module/...)
-  publicPages: {},
-  publicRoutes: [],
-
-  // Widgets affichés sur le dashboard admin
-  dashboardWidgets: [],
-});
-```
-
----
-
-## db.js
-
-Si le module crée des tables, on exporte `createTables` et `dropTables`.
-
-```js
-import { query } from '../../core/database/index.js';
-import { tableExists } from '../../core/database/helpers.js';
-
-export async function createTables() {
-  const created = [];
-  const skipped = [];
-
-  if (!(await tableExists('zen_mon_module'))) {
-    await query(`
-      CREATE TABLE zen_mon_module (
-        id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-        titre      TEXT NOT NULL,
-        created_at TIMESTAMPTZ DEFAULT NOW()
-      )
-    `);
-    created.push('zen_mon_module');
-  } else {
-    skipped.push('zen_mon_module');
-  }
-
-  return { created, skipped };
-}
-
-export async function dropTables() {
-  await query('DROP TABLE IF EXISTS zen_mon_module CASCADE');
-}
-```
-
----
-
-## api.js
-
-Les routes API sont montées automatiquement sous `/api/zen/mon-module/...`.
-
-```js
-async function handleList(request) {
-  // ...
-  return Response.json({ items });
-}
-
-export default {
-  routes: [
-    { path: '/admin/mon-module/list', method: 'GET', handler: handleList, auth: 'admin' },
-    { path: '/mon-module/list',       method: 'GET', handler: handleList, auth: 'public' },
-  ],
-};
-```
-
-Valeurs acceptées pour `auth` : `'admin'` (JWT admin requis), `'user'` (JWT utilisateur requis), `'public'` (aucune auth).
-
----
-
-## cron.config.js
-
-```js
-import { maFonction } from './crud.js';
-
-export default {
-  jobs: [
-    {
-      name: 'mon-module:nettoyage',
-      schedule: '0 3 * * *',   // Tous les jours à 3h
-      handler: maFonction,
-      timezone: 'America/Toronto',
-    },
-  ],
-};
-```
-
----
-
-## Enregistrement — 2 étapes
-
-Après avoir créé les fichiers, on enregistre le module dans deux endroits.
-
-### 1. `src/modules/modules.registry.js`
-
-Ajouter le nom du module à `AVAILABLE_MODULES` :
-
-```js
-export const AVAILABLE_MODULES = [
-  'posts',
-  'mon-module', // ajout
-];
-```
-
-### 2. `src/modules/modules.pages.js`
-
-Importer la config et l'ajouter à `MODULE_CONFIGS` :
-
-```js
-import postsConfig    from './posts/module.config.js';
-import monModuleConfig from './mon-module/module.config.js'; // ajout
-
-const MODULE_CONFIGS = {
-  posts:      postsConfig,
-  'mon-module': monModuleConfig, // ajout
-};
-```
-
----
-
-## Activation
-
-Le module est ignoré au démarrage tant que sa variable d'environnement n'est pas définie :
-
-```bash
-# .env.local
-ZEN_MODULE_MON_MODULE=true
-```
-
-La règle de conversion : tirets et espaces deviennent des underscores, tout en majuscules.
-
-```
-mon-module  →  ZEN_MODULE_MON_MODULE
-post-types  →  ZEN_MODULE_POST_TYPES
-```
-
----
-
-## Vérification rapide
-
-1. Démarrer le serveur avec `ZEN_MODULE_MON_MODULE=true`.
-2. Ouvrir `/admin`. La section de navigation du module doit apparaître.
-3. Naviguer vers `/admin/mon-module/list`. La page doit se charger.
-4. Lancer `npx zen-db init`. La table `zen_mon_module` doit être créée.

package-lock.json

@@ -1,25 +1,26 @@
 {
   "name": "@zen/core",
-  "version": "1.3.11",
+  "version": "1.4.210",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zen/core",
-      "version": "1.3.11",
+      "version": "1.4.210",
       "license": "GPL-3.0-only",
       "dependencies": {
         "@headlessui/react": "^2.0.0",
         "@react-email/components": "^0.5.6",
         "@react-pdf/renderer": "^4.3.1",
         "dotenv": "^16.4.5",
-        "node-cron": "^3.0.3",
+        "node-cron": "^4.2.1",
         "pg": "^8.11.3",
         "resend": "^3.2.0",
         "stripe": "^14.0.0"
       },
       "bin": {
-        "zen-db": "dist/cli/database.js"
+        "zen-db": "dist/core/database/cli.js",
+        "zen-modules": "dist/core/modules/cli.js"
       },
       "devDependencies": {
         "react": "^19.0.0",
@@ -3653,43 +3654,11 @@
         "tslib": "^2.8.0"
       }
     },
-    "node_modules/next/node_modules/postcss": {
-      "version": "8.4.31",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
-      "integrity": "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==",
-      "funding": [
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/postcss/"
-        },
-        {
-          "type": "tidelift",
-          "url": "https://tidelift.com/funding/github/npm/postcss"
-        },
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
-      "license": "MIT",
-      "peer": true,
-      "dependencies": {
-        "nanoid": "^3.3.6",
-        "picocolors": "^1.0.0",
-        "source-map-js": "^1.0.2"
-      },
-      "engines": {
-        "node": "^10 || ^12 || >=14"
-      }
-    },
     "node_modules/node-cron": {
-      "version": "3.0.3",
-      "resolved": "https://registry.npmjs.org/node-cron/-/node-cron-3.0.3.tgz",
-      "integrity": "sha512-dOal67//nohNgYWb+nWmg5dkFdIwDm8EpeGYMekPMrngV3637lqnX0lbUcCtgibHTz6SEz7DAIjKvKDFYCnO1A==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/node-cron/-/node-cron-4.2.1.tgz",
+      "integrity": "sha512-lgimEHPE/QDgFlywTd8yTR61ptugX3Qer29efeyWw2rv259HtGBNn1vZVmp8lB9uo9wC0t/AT4iGqXxia+CJFg==",
       "license": "ISC",
-      "dependencies": {
-        "uuid": "8.3.2"
-      },
       "engines": {
         "node": ">=6.0.0"
       }
@@ -3913,6 +3882,35 @@
         "node": ">= 6"
       }
     },
+    "node_modules/postcss": {
+      "version": "8.5.10",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
     "node_modules/postcss-load-config": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-6.0.1.tgz",
@@ -5355,15 +5353,6 @@
       "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
       "license": "MIT"
     },
-    "node_modules/uuid": {
-      "version": "8.3.2",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
-      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
-      "license": "MIT",
-      "bin": {
-        "uuid": "dist/bin/uuid"
-      }
-    },
     "node_modules/vite-compatible-readable-stream": {
       "version": "3.6.1",
       "resolved": "https://registry.npmjs.org/vite-compatible-readable-stream/-/vite-compatible-readable-stream-3.6.1.tgz",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zen/core",
-  "version": "1.3.11",
-  "description": "Un CMS construit sur l'essentiel, rien de plus, rien de moins.",
+  "version": "1.4.210",
+  "description": "Une plateforme multi-usage construite sur l'essentiel, rien de plus, rien de moins.",
   "repository": {
     "type": "git",
     "url": "https://git.hyko.cx/zen/core.git"
@@ -15,22 +15,25 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    ".env.example"
   ],
   "scripts": {
     "build": "tsup && npm run build:css",
-    "build:css": "mkdir -p ./dist/shared/styles && cp ./src/shared/styles/zen.css ./dist/shared/styles/zen.css",
-    "prepublishOnly": "npm run build"
+    "build:css": "mkdir -p ./dist/shared/styles ./dist/shared/fonts && cp ./src/shared/styles/zen.css ./dist/shared/styles/zen.css && cp -r ./src/shared/fonts/. ./dist/shared/fonts/",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch --no-git-tag-version && npm i && git add package.json package-lock.json && git commit -m \"chore: bump version to $(node -p \"require('./package.json').version\")\" && git push && npm publish"
   },
   "bin": {
-    "zen-db": "./dist/cli/database.js"
+    "zen-db": "./dist/core/database/cli.js",
+    "zen-modules": "./dist/core/modules/cli.js"
   },
   "dependencies": {
     "@headlessui/react": "^2.0.0",
     "@react-email/components": "^0.5.6",
     "@react-pdf/renderer": "^4.3.1",
     "dotenv": "^16.4.5",
-    "node-cron": "^3.0.3",
+    "node-cron": "^4.2.1",
     "pg": "^8.11.3",
     "resend": "^3.2.0",
     "stripe": "^14.0.0"
@@ -45,45 +48,78 @@
     "next": ">=14.0.0",
     "react": "^19.0.0"
   },
+  "overrides": {
+    "postcss": "^8.5.10"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js"
     },
-    "./auth": {
+    "./features/auth": {
       "import": "./dist/features/auth/index.js"
     },
-    "./auth/actions": {
+    "./features/auth/actions": {
       "import": "./dist/features/auth/actions.js"
     },
-    "./auth/pages": {
-      "import": "./dist/features/auth/pages.js"
+    "./features/auth/server": {
+      "import": "./dist/features/auth/AuthPage.server.js"
     },
-    "./auth/page": {
-      "import": "./dist/features/auth/page.js"
+    "./features/auth/client": {
+      "import": "./dist/features/auth/AuthPage.client.js"
     },
-    "./auth/components": {
-      "import": "./dist/features/auth/components/index.js"
+    "./features/auth/pages": {
+      "import": "./dist/features/auth/pages/index.js"
     },
-    "./admin": {
+    "./features/admin": {
       "import": "./dist/features/admin/index.js"
     },
-    "./admin/actions": {
-      "import": "./dist/features/admin/actions.js"
+    "./features/admin/protect": {
+      "import": "./dist/features/admin/protect.js"
     },
-    "./admin/navigation": {
-      "import": "./dist/features/admin/navigation.server.js"
+    "./features/admin/server": {
+      "import": "./dist/features/admin/AdminPage.server.js"
     },
-    "./admin/pages": {
-      "import": "./dist/features/admin/pages.js"
+    "./features/admin/layout": {
+      "import": "./dist/features/admin/AdminLayout.server.js"
     },
-    "./admin/page": {
-      "import": "./dist/features/admin/page.js"
+    "./features/admin/client": {
+      "import": "./dist/features/admin/AdminPage.client.js"
+    },
+    "./features/admin/components": {
+      "import": "./dist/features/admin/components/index.js"
+    },
+    "./features/media": {
+      "import": "./dist/features/media/index.js"
+    },
+    "./features/media/picker": {
+      "import": "./dist/features/media/components/MediaPicker.client.js"
+    },
+    "./features/media/details-modal": {
+      "import": "./dist/features/media/components/MediaDetailsModal.client.js"
+    },
+    "./features/provider": {
+      "import": "./dist/features/provider/index.js"
+    },
+    "./users": {
+      "import": "./dist/core/users/index.js"
+    },
+    "./users/constants": {
+      "import": "./dist/core/users/constants.js"
+    },
+    "./modules": {
+      "import": "./dist/core/modules/index.js"
+    },
+    "./public-pages": {
+      "import": "./dist/core/public-pages/index.js"
+    },
+    "./public-pages/server": {
+      "import": "./dist/core/public-pages/PublicModulePage.server.js"
     },
     "./api": {
       "import": "./dist/core/api/index.js"
     },
-    "./zen/api": {
-      "import": "./dist/core/api/nx-route.js"
+    "./api/handler": {
+      "import": "./dist/core/api/route-handler.js"
     },
     "./database": {
       "import": "./dist/core/database/index.js"
@@ -112,47 +148,29 @@
     "./toast": {
       "import": "./dist/core/toast/index.js"
     },
-    "./provider": {
-      "import": "./dist/features/provider/index.js"
+    "./themes": {
+      "import": "./dist/core/themes/index.js"
     },
-    "./core/modules": {
-      "import": "./dist/core/modules/index.js"
-    },
-    "./core/modules/client": {
-      "import": "./dist/core/modules/client.js"
-    },
-    "./modules": {
-      "import": "./dist/modules/index.js"
-    },
-    "./modules/define": {
-      "import": "./dist/core/modules/defineModule.js"
-    },
-    "./modules/pages": {
-      "import": "./dist/modules/pages.js"
-    },
-    "./modules/actions": {
-      "import": "./dist/modules/modules.actions.js"
-    },
-    "./modules/storage": {
-      "import": "./dist/modules/modules.storage.js"
-    },
-    "./modules/posts/crud": {
-      "import": "./dist/modules/posts/crud.js"
-    },
-    "./modules/metadata": {
-      "import": "./dist/modules/modules.metadata.js"
-    },
-    "./modules/page": {
-      "import": "./dist/modules/page.js"
-    },
-    "./lib/metadata": {
-      "import": "./dist/shared/lib/metadata/index.js"
-    },
-    "./components": {
+    "./shared/components": {
       "import": "./dist/shared/components/index.js"
     },
-    "./icons": {
-      "import": "./dist/shared/Icons.js"
+    "./shared/components/BlockEditor/mediaLink": {
+      "import": "./dist/shared/components/BlockEditor/mediaLink.server.js"
+    },
+    "./shared/icons": {
+      "import": "./dist/shared/icons/index.js"
+    },
+    "./shared/metadata": {
+      "import": "./dist/shared/lib/metadata/index.js"
+    },
+    "./shared/logger": {
+      "import": "./dist/shared/lib/logger.js"
+    },
+    "./shared/config": {
+      "import": "./dist/shared/lib/appConfig.js"
+    },
+    "./shared/rate-limit": {
+      "import": "./dist/shared/lib/rateLimit.js"
     },
     "./styles/zen.css": {
       "default": "./dist/shared/styles/zen.css"

src/core/api/README.md

@@ -0,0 +1,202 @@
+# API Framework
+
+Ce répertoire est un **framework d'API générique**. Il ne connaît aucune feature spécifique — les features s'y enregistrent elles-mêmes. Ajouter une nouvelle route ne nécessite jamais de modifier `router.js`.
+
+---
+
+## Structure
+
+```
+src/core/api/
+├── index.js           Exports publics (routeRequest, requireAuth, apiSuccess, defineApiRoutes…)
+├── router.js          Orchestration : rate limit, CSRF, auth, dispatch
+├── runtime.js         État global persisté : resolver de session + registre des feature routes
+├── route-handler.js   Intégration Next.js App Router (GET/POST/PUT/DELETE/PATCH)
+├── define.js          defineApiRoutes() — validateur de définitions de routes
+├── respond.js         apiSuccess() / apiError() / getStatusCode() — utilitaires de réponse
+├── core-routes.js     Index des routes built-in (seul fichier à toucher pour un nouveau handler core)
+├── file-response.js   Réponse streaming pour les fichiers (GET /zen/api/storage/**)
+└── health.js          GET /zen/api/health
+
+src/features/auth/api.js     Routes /zen/api/users/* (vivent avec la feature auth)
+src/core/storage/api.js      Routes /zen/api/storage/** (vivent avec le module storage)
+```
+
+Les routes vivent **avec leur feature**, pas dans le framework. `src/core/api/` ne contient que l'infrastructure.
+
+---
+
+## Cycle de vie d'une requête
+
+```
+route-handler.js (GET / POST / PUT / DELETE / PATCH)
+  └─→ routeRequest(request, path)
+        ├─ Rate limit (IP, sauf GET /health)
+        ├─ CSRF (méthodes state-mutating uniquement)
+        └─ Boucle sur toutes les routes (core d'abord, modules ensuite)
+             ├─ matchRoute(pattern, path)   — exact, :param, /**
+             ├─ Auth enforcement (depuis la définition de la route)
+             │    'admin' → requireAdmin()  — session dans context.session
+             │    │          si `permission` est défini → hasPermission() → 403 si refusé
+             │    'user'  → requireAuth()   — session dans context.session
+             │    'public'→ aucun           — context.session = undefined
+             └─ handler(request, params, context)
+```
+
+---
+
+## Niveaux d'auth
+
+| Niveau | Qui peut appeler | `context.session` |
+|--------|-----------------|-------------------|
+| `'public'` | Tout le monde, sans cookie | `undefined` |
+| `'user'` | Utilisateur avec une session valide | `{ user: { id, email, name, role, … } }` |
+| `'admin'` | Utilisateur admin (`role === 'admin'`) | `{ user: { id, email, name, role: 'admin', … } }` |
+
+L'auth est **toujours déclarée dans la définition de route**, jamais dans le handler.
+
+---
+
+## Ajouter des routes à une feature core
+
+Deux étapes :
+
+**1. Créer un fichier `api.js` dans le répertoire de la feature :**
+
+```js
+// src/features/myfeature/api.js
+import { defineApiRoutes } from '../../core/api/define.js';
+import { apiSuccess, apiError } from '../../core/api/respond.js';
+
+async function handleGetSettings(_request, _params, _context) {
+  return apiSuccess({ theme: 'light' });
+}
+
+async function handleUpdateSettings(request, _params, { session }) {
+  const body = await request.json();
+  // ... validation + update ...
+  return apiSuccess({ success: true, message: 'Settings updated' });
+}
+
+export const routes = defineApiRoutes([
+  { path: '/settings', method: 'GET', handler: handleGetSettings,    auth: 'user'  },
+  { path: '/settings', method: 'PUT', handler: handleUpdateSettings,  auth: 'admin' },
+]);
+```
+
+**2. L'enregistrer dans `initializeZen()` (src/shared/lib/init.js) :**
+
+```js
+import { registerFeatureRoutes } from '../../core/api/index.js';
+import { routes as settingsRoutes } from '../../features/myfeature/api.js';
+
+registerFeatureRoutes(settingsRoutes);
+```
+
+**C'est tout.** Les routes sont disponibles à `GET /zen/api/settings` et `PUT /zen/api/settings`.
+
+> Note : `core-routes.js` n'est utilisé que pour les routes built-in de l'infrastructure (health, storage). Les routes de features passent par `registerFeatureRoutes()` dans `initializeZen()`.
+
+---
+
+## Ajouter des routes depuis un module
+
+Les modules définissent leurs routes dans leur propre `api.js` — le système de découverte les charge automatiquement. Aucune modification dans `src/core/api/` n'est nécessaire.
+
+```js
+// src/modules/mymodule/api.js
+import { defineApiRoutes } from '@zen/core/api';
+
+export default {
+  routes: defineApiRoutes([
+    { path: '/admin/mymodule/items', method: 'GET',  handler: handleList,   auth: 'admin'  },
+    { path: '/mymodule/:slug',       method: 'GET',  handler: handlePublic, auth: 'public' },
+  ])
+};
+```
+
+---
+
+## Signature des handlers
+
+```js
+async function handleSomething(request, params, context) {
+  // request  — objet Request Next.js
+  // params   — paramètres extraits du chemin { id: '42', … }
+  //            Pour les routes wildcard (/storage/**) : params.wildcard
+  // context  — { session? } — session présente si auth !== 'public'
+}
+```
+
+---
+
+## Utilitaires de réponse
+
+Toujours utiliser `apiSuccess` et `apiError` pour que l'intention soit explicite.
+
+```js
+import { apiSuccess, apiError } from '../../core/api/respond.js';
+
+// Succès — GET
+return apiSuccess({ user: { id, email, name } });
+
+// Succès — mutation (avec confirmation pour le frontend)
+return apiSuccess({ success: true, user: updatedUser, message: 'Profil mis à jour' });
+
+// Erreur
+return apiError('Not Found',    'Utilisateur introuvable');
+return apiError('Bad Request',  'Le nom est requis');
+return apiError('Forbidden',    'Accès refusé');
+```
+
+Codes d'erreur reconnus par `getStatusCode()` → HTTP status :
+
+| Code | Status |
+|------|--------|
+| `'Unauthorized'` | 401 |
+| `'Admin access required'` | 403 |
+| `'Forbidden'` | 403 |
+| `'Not Found'` | 404 |
+| `'Bad Request'` | 400 |
+| `'Too Many Requests'` | 429 |
+| `'Internal Server Error'` | 500 |
+
+---
+
+## defineApiRoutes()
+
+Valide les définitions de routes à l'import (au démarrage). Une erreur de configuration lève immédiatement une `TypeError` avec un message précis.
+
+Champs requis par route :
+
+| Champ | Type | Valeurs valides |
+|-------|------|-----------------|
+| `path` | `string` | Commence par `/`. Supporte `:param` et `/**` en fin |
+| `method` | `string` | `GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE` |
+| `handler` | `Function` | Signature : `(request, params, context) => Promise<Object>` |
+| `auth` | `string` | `'public'` \| `'user'` \| `'admin'` |
+
+Champs optionnels :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `skipRateLimit` | `boolean` | Exempte la route du rate limiting par IP (ex. health checks) |
+| `permission` | `string` | Sur une route `auth: 'admin'`, exige en plus cette clé de permission granulaire (ex. `'users.manage'`). Retourne 403 si l'utilisateur ne la possède pas. Voir `PERMISSIONS` dans `src/core/users/constants.js` |
+
+---
+
+## Note — handler storage
+
+Le handler storage (`src/core/storage/api.js`) est déclaré `auth: 'public'` mais effectue sa propre validation d'accès en interne, basée sur le chemin du fichier :
+
+- **Prefixes publics** (déclarés via `storagePublicPrefixes` dans chaque module) → aucune session requise
+- **`/users/{userId}/…`** → session requise ; l'utilisateur ne peut accéder qu'à ses propres fichiers (sauf admin)
+- **`/organizations/…`** → admin uniquement
+- **`/posts/…`** (non couverts par un prefix public) → admin uniquement
+- **Tout autre chemin** → refusé
+
+---
+
+## Compatibilité des modules existants
+
+Les handlers de modules existants avec la signature `(request, params)` continuent de fonctionner — JavaScript ignore les arguments supplémentaires non utilisés.

src/core/api/core-routes.js

@@ -0,0 +1,30 @@
+/**
+ * Core Route Index
+ *
+ * Contains only routes that are part of the core API infrastructure itself:
+ * the health check and the storage file-serving endpoint. Both live under
+ * src/core/ and have no feature-level dependencies.
+ *
+ * Feature routes (e.g. /users/*) are registered separately by each feature
+ * during initializeZen() via registerFeatureRoutes().
+ *
+ * To add a new core infrastructure handler:
+ *   1. Create the handler in its natural location under src/core/
+ *   2. Export `routes` from it using defineApiRoutes()
+ *   3. Add one line here: import + spread
+ *   4. Done — never touch router.js
+ */
+
+import { routes as healthRoutes }  from './health.js';
+import { routes as storageRoutes } from '../storage/api.js';
+
+/**
+ * Return all registered core infrastructure API routes.
+ * @returns {ReadonlyArray}
+ */
+export function getCoreRoutes() {
+  return [
+    ...healthRoutes,
+    ...storageRoutes,
+  ];
+}

src/core/api/define.js

@@ -0,0 +1,93 @@
+/**
+ * API Route Definition Helper
+ *
+ * Validates route definitions at module load time (startup), not at request
+ * time. A misconfigured route throws immediately — before any request is
+ * served — making integration errors impossible to miss.
+ *
+ * Usage (in any handler file or module api.js):
+ *   import { defineApiRoutes } from '../define.js';
+ *
+ *   export const routes = defineApiRoutes([
+ *     { path: '/health', method: 'GET', handler: handleHealth, auth: 'public' },
+ *   ]);
+ *
+ * Required fields per route:
+ *   path           {string}   Must start with '/'. Supports ':param' and trailing '/**'.
+ *   method         {string}   One of: GET | POST | PUT | PATCH | DELETE
+ *   handler        {Function} Async function — signature: (request, params, context)
+ *   auth           {string}   One of: 'public' | 'user' | 'admin'
+ *
+ * Optional fields per route:
+ *   skipRateLimit  {boolean}  When true, the router skips the per-IP rate limit
+ *                             check for this route. Use sparingly — only for routes
+ *                             that must remain accessible under high probe frequency
+ *                             (e.g. health checks from monitoring systems).
+ *   permission     {string}   When set on an 'admin' route, the router additionally
+ *                             verifies that the authenticated user holds this granular
+ *                             permission key (e.g. 'users.manage'). If the user lacks
+ *                             the permission, the request is rejected with 403 Forbidden.
+ *
+ * Auth levels:
+ *   'public'  Anyone can call this route. context.session is undefined.
+ *   'user'    Requires a valid session. context.session.user is set.
+ *   'admin'   Requires a valid session with role === 'admin'.
+ */
+
+const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const VALID_AUTH = new Set(['public', 'user', 'admin']);
+
+/**
+ * Validate and return a frozen route definition array.
+ *
+ * @param {Array<{path: string, method: string, handler: Function, auth: string}>} routes
+ * @returns {ReadonlyArray}
+ * @throws {TypeError} If any route definition is invalid
+ */
+export function defineApiRoutes(routes) {
+  if (!Array.isArray(routes)) {
+    throw new TypeError('defineApiRoutes: argument must be an array');
+  }
+
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i];
+    const at = `defineApiRoutes: route[${i}]`;
+
+    if (!route || typeof route !== 'object') {
+      throw new TypeError(`${at} must be an object`);
+    }
+    if (typeof route.path !== 'string' || !route.path.startsWith('/')) {
+      throw new TypeError(
+        `${at} — "path" must be a string starting with "/", got: ${JSON.stringify(route.path)}`
+      );
+    }
+    if (!VALID_METHODS.has(route.method)) {
+      throw new TypeError(
+        `${at} (${route.path}) — "method" must be one of ${[...VALID_METHODS].join(' | ')}, got: ${JSON.stringify(route.method)}`
+      );
+    }
+    if (typeof route.handler !== 'function') {
+      throw new TypeError(
+        `${at} (${route.method} ${route.path}) — "handler" must be a function`
+      );
+    }
+    if (!VALID_AUTH.has(route.auth)) {
+      throw new TypeError(
+        `${at} (${route.method} ${route.path}) — "auth" must be one of "public" | "user" | "admin", got: ${JSON.stringify(route.auth)}`
+      );
+    }
+    if (route.skipRateLimit !== undefined && typeof route.skipRateLimit !== 'boolean') {
+      throw new TypeError(
+        `${at} (${route.method} ${route.path}) — "skipRateLimit" must be a boolean when provided, got: ${JSON.stringify(route.skipRateLimit)}`
+      );
+    }
+    if (route.permission !== undefined && typeof route.permission !== 'string') {
+      throw new TypeError(
+        `${at} (${route.method} ${route.path}) — "permission" must be a string when provided, got: ${JSON.stringify(route.permission)}`
+      );
+    }
+  }
+
+  // Freeze to prevent accidental mutation of route definitions at runtime.
+  return Object.freeze(routes.map(r => Object.freeze({ ...r })));
+}

src/core/api/file-response.js

@@ -0,0 +1,57 @@
+/**
+ * File Response Builder
+ *
+ * Builds a NextResponse for streaming a file from storage.
+ * Encapsulates all file-serving semantics — MIME type rendering policy,
+ * Content-Disposition rules, security headers — in one place so the
+ * generic route handler stays agnostic about storage concerns.
+ *
+ * Policy:
+ *   - Image MIME types are served inline (required for <img> tags).
+ *   - All other types force a download to prevent in-browser rendering
+ *     of potentially dangerous content.
+ *   - Content-Disposition is always emitted explicitly; omitting it leaves
+ *     rendering decisions to browser heuristics, which vary by content-type
+ *     and browser version.
+ */
+
+import { NextResponse } from 'next/server';
+
+// MIME types that are safe to render inline (used in <img> tags).
+// All other types are forced to download.
+const INLINE_MIME_TYPES = new Set([
+  'image/jpeg', 'image/png', 'image/gif', 'image/webp',
+]);
+
+/**
+ * Build a NextResponse that streams a file from a storage result envelope.
+ *
+ * @param {{ body: *, contentType?: string, contentLength?: number, lastModified?: Date, filename?: string }} file
+ * @returns {NextResponse}
+ */
+export function buildFileResponse(file) {
+  const contentType = file.contentType || 'application/octet-stream';
+
+  const headers = {
+    'Content-Type': contentType,
+    'Cache-Control': 'private, max-age=3600',
+    'Last-Modified': file.lastModified?.toUTCString() ?? new Date().toUTCString(),
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+  };
+
+  if (file.contentLength != null) {
+    headers['Content-Length'] = String(file.contentLength);
+  }
+
+  if (INLINE_MIME_TYPES.has(contentType)) {
+    headers['Content-Disposition'] = 'inline';
+  } else if (file.filename) {
+    const encoded = encodeURIComponent(file.filename);
+    headers['Content-Disposition'] = `attachment; filename="${encoded}"; filename*=UTF-8''${encoded}`;
+  } else {
+    headers['Content-Disposition'] = 'attachment';
+  }
+
+  return new NextResponse(file.body, { status: 200, headers });
+}

src/core/api/handlers/storage.js

@@ -1,162 +0,0 @@
-/**
- * Storage API Handlers
- * Handles secure file access
- */
-
-import { validateSession } from '../../../features/auth/lib/session.js';
-import { cookies } from 'next/headers';
-import { getSessionCookieName } from '../../../shared/lib/appConfig.js';
-import { getAllStoragePublicPrefixes } from '@zen/core/modules/storage';
-import { getFile } from '@zen/core/storage';
-import { fail } from '../../../shared/lib/logger.js';
-
-// Get cookie name from environment or use default
-const COOKIE_NAME = getSessionCookieName();
-
-/**
- * Serve a file from storage with security validation
- * @param {Request} request - The request object
- * @param {string} fileKey - The file key/path in storage
- * @returns {Promise<Response|Object>} File response or error object
- */
-export async function handleGetFile(_request, fileKey) {
-  try {
-    // Reject any path that contains traversal sequences, empty segments, or
-    // absolute path indicators before splitting or passing to the storage backend.
-    // Next.js decodes URL percent-encoding before populating [...path], so
-    // '..' and '.' arrive as literal segment values here.
-    const rawSegments = fileKey.split('/');
-    if (
-      rawSegments.some(seg => seg === '..' || seg === '.' || seg === '') ||
-      fileKey.includes('\0')
-    ) {
-      return { error: 'Bad Request', message: 'Invalid file path' };
-    }
-
-    const pathParts = rawSegments;
-
-    // Public prefixes: declared by each module via defineModule() storagePublicPrefixes.
-    // Files whose path starts with a declared prefix are served without authentication.
-    // The path must have at least two segments beyond the prefix ({...prefix}/{id}/{filename})
-    // to prevent unintentional exposure of files at the root of the prefix.
-    const publicPrefixes = getAllStoragePublicPrefixes();
-    const matchedPrefix = publicPrefixes.find(prefix => fileKey.startsWith(prefix + '/'));
-    if (matchedPrefix) {
-      const prefixDepth = matchedPrefix.split('/').length;
-      if (pathParts.length < prefixDepth + 2) {
-        return { error: 'Bad Request', message: 'Invalid file path' };
-      }
-      const result = await getFile(fileKey);
-      if (!result.success) {
-        if (result.error.includes('NoSuchKey') || result.error.includes('not found')) {
-          return { error: 'Not Found', message: 'File not found' };
-        }
-        // Never forward raw storage error messages to the client.
-        return { error: 'Internal Server Error', message: 'Failed to retrieve file' };
-      }
-      return {
-        success: true,
-        file: {
-          body: result.data.body,
-          contentType: result.data.contentType,
-          contentLength: result.data.contentLength,
-          lastModified: result.data.lastModified
-        }
-      };
-    }
-
-    // Require auth for other paths
-    const cookieStore = await cookies();
-    const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-    if (!sessionToken) {
-      return {
-        error: 'Unauthorized',
-        message: 'Authentication required to access files'
-      };
-    }
-
-    const session = await validateSession(sessionToken);
-
-    if (!session) {
-      return {
-        error: 'Unauthorized',
-        message: 'Invalid or expired session'
-      };
-    }
-
-    // Security validation based on file path
-    if (pathParts[0] === 'users') {
-      // User files: users/{userId}/{category}/{filename}
-      const userId = pathParts[1];
-
-      // Users can only access their own files, unless they're admin
-      if (session.user.id !== userId && session.user.role !== 'admin') {
-        return {
-          error: 'Forbidden',
-          message: 'You do not have permission to access this file'
-        };
-      }
-    } else if (pathParts[0] === 'organizations') {
-      // Organization files: organizations/{orgId}/{category}/{filename}
-      // Only admins can access organization files
-      if (session.user.role !== 'admin') {
-        return {
-          error: 'Forbidden',
-          message: 'Admin access required for organization files'
-        };
-      }
-    } else if (pathParts[0] === 'posts') {
-      // Post files: posts/{type}/{id}/{filename}
-      // Private types (not in storagePublicPrefixes) require admin access
-      if (session.user.role !== 'admin') {
-        return {
-          error: 'Forbidden',
-          message: 'Admin access required for this file'
-        };
-      }
-    } else {
-      // Unknown file path pattern — deny by default
-      return {
-        error: 'Forbidden',
-        message: 'Invalid file path'
-      };
-    }
-
-    // Get file from storage
-    const result = await getFile(fileKey);
-
-    if (!result.success) {
-      if (result.error.includes('NoSuchKey') || result.error.includes('not found')) {
-        return {
-          error: 'Not Found',
-          message: 'File not found'
-        };
-      }
-      // Never forward raw storage errors (which may contain bucket names/keys) to clients.
-      return {
-        error: 'Internal Server Error',
-        message: 'Failed to retrieve file'
-      };
-    }
-
-    // Return the file data with proper headers
-    return {
-      success: true,
-      file: {
-        body: result.data.body,
-        contentType: result.data.contentType,
-        contentLength: result.data.contentLength,
-        lastModified: result.data.lastModified
-      }
-    };
-  } catch (error) {
-    // Log full error server-side; never surface internal details to the client.
-    fail(`Storage: error serving file: ${error.message}`);
-    return {
-      error: 'Internal Server Error',
-      message: 'Failed to retrieve file'
-    };
-  }
-}
-

src/core/api/handlers/users.js

@@ -1,602 +0,0 @@
-/**
- * Users API Handlers
- * Handles user-related API endpoints
- */
-
-import { validateSession } from '../../../features/auth/lib/session.js';
-import { cookies } from 'next/headers';
-import { query, updateById } from '@zen/core/database';
-import { getSessionCookieName } from '../../../shared/lib/appConfig.js';
-import { updateUser } from '../../../features/auth/lib/auth.js';
-import { uploadImage, deleteFile, generateUniqueFilename, generateUserFilePath, getFileExtension, FILE_TYPE_PRESETS, FILE_SIZE_LIMITS, validateUpload } from '@zen/core/storage';
-import { fail, info } from '../../../shared/lib/logger.js';
-
-// Get cookie name from environment or use default
-const COOKIE_NAME = getSessionCookieName();
-
-/** Maximum number of users returned per paginated request */
-const MAX_PAGE_LIMIT = 100;
-
-/**
- * Server-side whitelist of MIME types accepted for profile picture uploads.
- * The client-supplied file.type is NEVER trusted; this set is the authoritative
- * list. Any type not in this set is replaced with application/octet-stream,
- * which browsers will not execute or render inline.
- */
-const ALLOWED_IMAGE_MIME_TYPES = new Set([
-  'image/jpeg',
-  'image/png',
-  'image/webp',
-  'image/gif',
-]);
-
-/**
- * Return a generic, opaque error message suitable for client consumption.
- * Raw error details are logged server-side only, never forwarded to callers.
- * @param {unknown} error - The caught exception
- * @param {string} fallback - The safe message to surface to the client
- */
-function logAndObscureError(error, fallback) {
-  fail(`Internal handler error: ${error.message}`);
-  return fallback;
-}
-
-/**
- * Get current user information
- */
-export async function handleGetCurrentUser(request) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  // Return user data (without sensitive information)
-  return {
-    user: {
-      id: session.user.id,
-      email: session.user.email,
-      name: session.user.name,
-      role: session.user.role,
-      image: session.user.image,
-      emailVerified: session.user.email_verified,
-      createdAt: session.user.created_at
-    }
-  };
-}
-
-/**
- * Get user by ID (admin only)
- */
-export async function handleGetUserById(request, userId) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  // Check if user is admin
-  if (session.user.role !== 'admin') {
-    return {
-      error: 'Forbidden',
-      message: 'Admin access required'
-    };
-  }
-
-  // Get user from database
-  const result = await query(
-    'SELECT id, email, name, role, image, email_verified, created_at FROM zen_auth_users WHERE id = $1',
-    [userId]
-  );
-
-  if (result.rows.length === 0) {
-    return {
-      error: 'Not Found',
-      message: 'User not found'
-    };
-  }
-
-  const response = { user: result.rows[0] };
-
-  return response;
-}
-
-/**
- * Update user by ID (admin only)
- */
-export async function handleUpdateUserById(request, userId) {
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return { success: false, error: 'Unauthorized', message: 'No session token provided' };
-  }
-
-  const session = await validateSession(sessionToken);
-  if (!session) {
-    return { success: false, error: 'Unauthorized', message: 'Invalid or expired session' };
-  }
-  if (session.user.role !== 'admin') {
-    return { success: false, error: 'Forbidden', message: 'Admin access required' };
-  }
-
-  try {
-    const body = await request.json();
-    const allowedFields = ['name', 'role', 'email_verified'];
-    const updateData = { updated_at: new Date() };
-
-    for (const field of allowedFields) {
-      if (body[field] !== undefined) {
-        if (field === 'email_verified') {
-          updateData[field] = Boolean(body[field]);
-        } else if (field === 'role') {
-          const role = String(body[field]).toLowerCase();
-          if (['admin', 'user'].includes(role)) {
-            updateData[field] = role;
-          }
-        } else if (field === 'name' && body[field] != null) {
-          updateData[field] = String(body[field]).trim() || null;
-        }
-      }
-    }
-
-    const updated = await updateById('zen_auth_users', userId, updateData);
-    if (!updated) {
-      return { success: false, error: 'Not Found', message: 'User not found' };
-    }
-
-    const result = await query(
-      'SELECT id, email, name, role, image, email_verified, created_at FROM zen_auth_users WHERE id = $1',
-      [userId]
-    );
-    return {
-      success: true,
-      user: result.rows[0],
-      message: 'User updated successfully'
-    };
-  } catch (error) {
-    logAndObscureError(error, 'Failed to update user');
-    return {
-      success: false,
-      error: 'Internal Server Error',
-      message: 'Failed to update user'
-    };
-  }
-}
-
-/**
- * List all users (admin only)
- */
-export async function handleListUsers(request) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  // Check if user is admin
-  if (session.user.role !== 'admin') {
-    return {
-      error: 'Forbidden',
-      message: 'Admin access required'
-    };
-  }
-
-  // Get URL params for pagination and sorting.
-  // Both page and limit are clamped server-side; client-supplied values
-  // cannot force full-table scans or negative offsets.
-  const url = new URL(request.url);
-  const page = Math.max(1, parseInt(url.searchParams.get('page') || '1', 10) || 1);
-  const limit = Math.min(
-    Math.max(1, parseInt(url.searchParams.get('limit') || '10', 10) || 10),
-    MAX_PAGE_LIMIT
-  );
-  const offset = (page - 1) * limit;
-  
-  // Get sorting parameters
-  const sortBy = url.searchParams.get('sortBy') || 'created_at';
-  const sortOrder = url.searchParams.get('sortOrder') || 'desc';
-
-  // Whitelist allowed sort columns to prevent SQL injection
-  const allowedSortColumns = ['id', 'email', 'name', 'role', 'email_verified', 'created_at'];
-  const sortColumn = allowedSortColumns.includes(sortBy) ? sortBy : 'created_at';
-  
-  // Validate sort order
-  const order = sortOrder.toLowerCase() === 'asc' ? 'ASC' : 'DESC';
-
-  // Wrap the whitelisted column name in double-quotes to enforce identifier
-  // boundaries, preventing any future whitelist entry or edge case from
-  // being interpreted as SQL syntax.
-  const quotedSortColumn = `"${sortColumn}"`;
-
-  // Get users from database with dynamic sorting
-  const result = await query(
-    `SELECT id, email, name, role, image, email_verified, created_at FROM zen_auth_users ORDER BY ${quotedSortColumn} ${order} LIMIT $1 OFFSET $2`,
-    [limit, offset]
-  );
-
-  // Get total count
-  const countResult = await query('SELECT COUNT(*) FROM zen_auth_users');
-  const total = parseInt(countResult.rows[0].count);
-
-  return {
-    users: result.rows,
-    pagination: {
-      page,
-      limit,
-      total,
-      totalPages: Math.ceil(total / limit)
-    }
-  };
-}
-
-/**
- * Update current user profile
- */
-export async function handleUpdateProfile(request) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  try {
-    // Get update data from request body
-    const body = await request.json();
-    const { name } = body;
-
-    // Validate input
-    if (!name || !name.trim()) {
-      return {
-        success: false,
-        error: 'Bad Request',
-        message: 'Name is required'
-      };
-    }
-
-    // Prepare update data
-    const updateData = {
-      name: name.trim()
-    };
-
-    // Update user profile
-    const updatedUser = await updateUser(session.user.id, updateData);
-
-    // Return updated user data (without sensitive information)
-    return {
-      success: true,
-      user: {
-        id: updatedUser.id,
-        email: updatedUser.email,
-        name: updatedUser.name,
-        role: updatedUser.role,
-        image: updatedUser.image,
-        email_verified: updatedUser.email_verified,
-        created_at: updatedUser.created_at
-      },
-      message: 'Profile updated successfully'
-    };
-  } catch (error) {
-    logAndObscureError(error, 'Failed to update profile');
-    return {
-      success: false,
-      error: 'Internal Server Error',
-      message: 'Failed to update profile'
-    };
-  }
-}
-
-/**
- * Upload profile picture
- */
-export async function handleUploadProfilePicture(request) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  try {
-    // Get form data from request
-    const formData = await request.formData();
-    const file = formData.get('file');
-
-    if (!file) {
-      return {
-        success: false,
-        error: 'Bad Request',
-        message: 'No file provided'
-      };
-    }
-
-    // Read file buffer once — used for both content inspection and upload.
-    const buffer = Buffer.from(await file.arrayBuffer());
-
-    // Validate file — pass buffer for magic-byte / content-pattern inspection.
-    const validation = validateUpload({
-      filename: file.name,
-      size: file.size,
-      allowedTypes: FILE_TYPE_PRESETS.IMAGES,
-      maxSize: FILE_SIZE_LIMITS.AVATAR,
-      buffer,
-    });
-
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: 'Bad Request',
-        message: validation.errors.join(', ')
-      };
-    }
-
-    // Get current user to check for existing profile picture
-    const currentUser = await query(
-      'SELECT image FROM zen_auth_users WHERE id = $1',
-      [session.user.id]
-    );
-
-    let oldImageKey = null;
-    if (currentUser.rows.length > 0 && currentUser.rows[0].image) {
-      // The image field now contains the storage key directly
-      oldImageKey = currentUser.rows[0].image;
-    }
-
-    // Generate unique filename
-    const uniqueFilename = generateUniqueFilename(file.name, 'avatar');
-    
-    // Generate storage path
-    const key = generateUserFilePath(session.user.id, 'profile', uniqueFilename);
-
-    // Derive the authoritative content-type from the *validated file extension*,
-    // never from file.type which is fully attacker-controlled.  The extension
-    // has already been verified against the allowedTypes whitelist above, so
-    // mapping it deterministically here eliminates any client influence over
-    // the MIME type stored in R2 and subsequently served to other users.
-    const EXTENSION_TO_MIME = {
-      '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-      '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
-    };
-    const ext = getFileExtension(file.name).toLowerCase();
-    const contentType = EXTENSION_TO_MIME[ext] ?? 'application/octet-stream';
-
-    // Upload to storage
-    const uploadResult = await uploadImage({
-      key,
-      body: buffer,
-      contentType,
-      metadata: {
-        userId: session.user.id,
-        originalName: file.name
-      }
-    });
-
-    if (!uploadResult.success) {
-      return {
-        success: false,
-        error: 'Upload Failed',
-        message: uploadResult.error || 'Failed to upload image'
-      };
-    }
-
-    // Update user profile with storage key (not URL).
-    // The DB write is committed first. Only if it succeeds do we delete the old
-    // object; this ensures the database never references a key that no longer
-    // exists in storage. An orphaned old object is preferable to a broken DB ref.
-    let updatedUser;
-    try {
-      updatedUser = await updateUser(session.user.id, { image: key });
-    } catch (dbError) {
-      // DB write failed — roll back the uploaded object so storage stays clean.
-      try {
-        await deleteFile(key);
-      } catch (rollbackError) {
-        fail(`Rollback delete of newly uploaded object failed: ${rollbackError.message}`);
-      }
-      throw dbError;
-    }
-
-    // DB write succeeded. Now it is safe to remove the old object.
-    if (oldImageKey) {
-      try {
-        await deleteFile(oldImageKey);
-        info(`Deleted old profile picture: ${oldImageKey}`);
-      } catch (deleteError) {
-        // Non-fatal: log for operator cleanup; the DB is consistent.
-        fail(`Failed to delete old profile picture (orphaned object): ${deleteError.message}`);
-      }
-    }
-
-    // Return updated user data
-    return {
-      success: true,
-      user: {
-        id: updatedUser.id,
-        email: updatedUser.email,
-        name: updatedUser.name,
-        role: updatedUser.role,
-        image: updatedUser.image,
-        email_verified: updatedUser.email_verified,
-        created_at: updatedUser.created_at
-      },
-      message: 'Profile picture uploaded successfully'
-    };
-  } catch (error) {
-    logAndObscureError(error, 'Failed to upload profile picture');
-    return {
-      success: false,
-      error: 'Internal Server Error',
-      message: 'Failed to upload profile picture'
-    };
-  }
-}
-
-/**
- * Delete profile picture
- */
-export async function handleDeleteProfilePicture(request) {
-  // Get session token from cookies
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-
-  if (!sessionToken) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'No session token provided'
-    };
-  }
-
-  // Validate session
-  const session = await validateSession(sessionToken);
-
-  if (!session) {
-    return {
-      success: false,
-      error: 'Unauthorized',
-      message: 'Invalid or expired session'
-    };
-  }
-
-  try {
-    // Get current user to check for existing profile picture
-    const currentUser = await query(
-      'SELECT image FROM zen_auth_users WHERE id = $1',
-      [session.user.id]
-    );
-
-    if (currentUser.rows.length === 0) {
-      return {
-        success: false,
-        error: 'Not Found',
-        message: 'User not found'
-      };
-    }
-
-    const imageKey = currentUser.rows[0].image;
-    if (!imageKey) {
-      return {
-        success: false,
-        error: 'Bad Request',
-        message: 'No profile picture to delete'
-      };
-    }
-
-    // Update user profile to remove image URL
-    const updatedUser = await updateUser(session.user.id, {
-      image: null
-    });
-
-    // Delete image from storage
-    if (imageKey) {
-      try {
-        await deleteFile(imageKey);
-        info(`Deleted profile picture: ${imageKey}`);
-      } catch (deleteError) {
-        // Log error but don't fail the update
-        fail(`Failed to delete profile picture from storage: ${deleteError.message}`);
-      }
-    }
-
-    // Return updated user data
-    return {
-      success: true,
-      user: {
-        id: updatedUser.id,
-        email: updatedUser.email,
-        name: updatedUser.name,
-        role: updatedUser.role,
-        image: updatedUser.image,
-        email_verified: updatedUser.email_verified,
-        created_at: updatedUser.created_at
-      },
-      message: 'Profile picture deleted successfully'
-    };
-  } catch (error) {
-    logAndObscureError(error, 'Failed to delete profile picture');
-    return {
-      success: false,
-      error: 'Internal Server Error',
-      message: 'Failed to delete profile picture'
-    };
-  }
-}
-

src/core/api/health.js

@@ -1,14 +1,20 @@
 /**
  * Health Check Handler
- * Returns the status of the API and basic system information
  */
 
-export async function handleHealth() {
+import { defineApiRoutes } from './define.js';
+import { apiSuccess } from './respond.js';
+
+async function handleHealth() {
   // Return only a liveness signal. Process uptime and version strings are
   // operational fingerprinting data; exposing them unauthenticated aids
   // attackers in timing restarts and targeting known-vulnerable versions.
-  return {
+  return apiSuccess({
     status: 'ok',
     timestamp: new Date().toISOString()
-  };
+  });
 }
+
+export const routes = defineApiRoutes([
+  { path: '/health', method: 'GET', handler: handleHealth, auth: 'public', skipRateLimit: true }
+]);

src/core/api/index.js

@@ -1,20 +1,18 @@
 /**
- * Zen API Module
+ * Zen API — Public Surface
  *
- * This module exports API utilities for custom handlers
- * For route setup, import from '@zen/core/zen/api'
+ * Exports the router entry point, auth helpers, response utilities,
+ * the route definition helper, and the feature routes registry.
  */
 
-// Export router utilities (for custom handlers)
-export { routeRequest, getStatusCode, requireAuth, requireAdmin } from './router.js';
+// Router
+export { routeRequest, requireAuth, requireAdmin } from './router.js';
 
-// Export individual handlers (for custom usage)
-export { handleHealth } from './handlers/health.js';
-export {
-  handleGetCurrentUser, 
-  handleGetUserById, 
-  handleListUsers 
-} from './handlers/users.js';
+// Runtime state — session resolver + feature routes registry
+export { configureRouter, getSessionResolver, clearRouterConfig, registerApiRoutes, registerFeatureRoutes, getFeatureRoutes, clearFeatureRoutes } from './runtime.js';
 
-// Module API handlers are now self-contained in their respective modules
-// e.g., invoice handlers are in @zen/core/modules/invoice/api
+// Response utilities — use in all handlers (core and modules)
+export { apiSuccess, apiError, getStatusCode } from './respond.js';
+
+// Route definition helper — use in handler files and module api.js files
+export { defineApiRoutes } from './define.js';

src/core/api/nx-route.js

@@ -1,184 +0,0 @@
-/**
- * ZEN API Route Handler
- * 
- * This is the main catch-all route handler for the ZEN API under /zen/api/.
- * It should be used in a Next.js App Router route at: app/zen/api/[...path]/route.js
- */
-
-import { NextResponse } from 'next/server';
-import { routeRequest, getStatusCode } from './router.js';
-import { fail } from '../../shared/lib/logger.js';
-
-/**
- * Handle GET requests
- */
-export async function GET(request, { params }) {
-  try {
-    const resolvedParams = await params;
-    const path = resolvedParams.path || [];
-    const response = await routeRequest(request, path);
-    
-    // Check if this is a file response (from storage endpoint)
-    if (response.success && response.file) {
-      const contentType = response.file.contentType || 'application/octet-stream';
-      const headers = {
-        'Content-Type': contentType,
-        'Content-Length': response.file.contentLength?.toString() || '',
-        'Cache-Control': 'private, max-age=3600',
-        'Last-Modified': response.file.lastModified?.toUTCString() || new Date().toUTCString(),
-        'X-Content-Type-Options': 'nosniff',
-        'X-Frame-Options': 'DENY',
-      };
-
-      // Always emit an explicit Content-Disposition header — omitting it leaves
-      // rendering decisions to browser heuristics, which varies by content-type
-      // and browser version.  Image MIME types are served inline (required for
-      // <img> tags); every other type forces a download to prevent in-browser
-      // rendering of potentially dangerous content.
-      const INLINE_MIME_TYPES = new Set([
-        'image/jpeg', 'image/png', 'image/gif', 'image/webp',
-      ]);
-      if (INLINE_MIME_TYPES.has(contentType)) {
-        headers['Content-Disposition'] = 'inline';
-      } else if (response.file.filename) {
-        const encoded = encodeURIComponent(response.file.filename);
-        headers['Content-Disposition'] = `attachment; filename="${encoded}"; filename*=UTF-8''${encoded}`;
-      } else {
-        headers['Content-Disposition'] = 'attachment';
-      }
-
-      return new NextResponse(response.file.body, { status: 200, headers });
-    }
-    
-    // Regular JSON response
-    const statusCode = getStatusCode(response);
-    return NextResponse.json(response, { 
-      status: statusCode,
-      headers: {
-        'Content-Type': 'application/json'
-      }
-    });
-  } catch (error) {
-    fail(`API error: ${error.message}`);
-    return NextResponse.json(
-      {
-        error: 'Internal Server Error',
-        message: 'An unexpected error occurred. Please try again later.'
-      },
-      { status: 500 }
-    );
-  }
-}
-
-/**
- * Handle POST requests
- */
-export async function POST(request, { params }) {
-  try {
-    const resolvedParams = await params;
-    const path = resolvedParams.path || [];
-    const response = await routeRequest(request, path);
-    const statusCode = getStatusCode(response);
-
-    return NextResponse.json(response, { 
-      status: statusCode,
-      headers: {
-        'Content-Type': 'application/json'
-      }
-    });
-  } catch (error) {
-    fail(`API error: ${error.message}`);
-    return NextResponse.json(
-      {
-        error: 'Internal Server Error',
-        message: 'An unexpected error occurred. Please try again later.'
-      },
-      { status: 500 }
-    );
-  }
-}
-
-/**
- * Handle PUT requests
- */
-export async function PUT(request, { params }) {
-  try {
-    const resolvedParams = await params;
-    const path = resolvedParams.path || [];
-    const response = await routeRequest(request, path);
-    const statusCode = getStatusCode(response);
-
-    return NextResponse.json(response, { 
-      status: statusCode,
-      headers: {
-        'Content-Type': 'application/json'
-      }
-    });
-  } catch (error) {
-    fail(`API error: ${error.message}`);
-    return NextResponse.json(
-      {
-        error: 'Internal Server Error',
-        message: 'An unexpected error occurred. Please try again later.'
-      },
-      { status: 500 }
-    );
-  }
-}
-
-/**
- * Handle DELETE requests
- */
-export async function DELETE(request, { params }) {
-  try {
-    const resolvedParams = await params;
-    const path = resolvedParams.path || [];
-    const response = await routeRequest(request, path);
-    const statusCode = getStatusCode(response);
-
-    return NextResponse.json(response, { 
-      status: statusCode,
-      headers: {
-        'Content-Type': 'application/json'
-      }
-    });
-  } catch (error) {
-    fail(`API error: ${error.message}`);
-    return NextResponse.json(
-      {
-        error: 'Internal Server Error',
-        message: 'An unexpected error occurred. Please try again later.'
-      },
-      { status: 500 }
-    );
-  }
-}
-
-/**
- * Handle PATCH requests
- */
-export async function PATCH(request, { params }) {
-  try {
-    const resolvedParams = await params;
-    const path = resolvedParams.path || [];
-    const response = await routeRequest(request, path);
-    const statusCode = getStatusCode(response);
-
-    return NextResponse.json(response, { 
-      status: statusCode,
-      headers: {
-        'Content-Type': 'application/json'
-      }
-    });
-  } catch (error) {
-    fail(`API error: ${error.message}`);
-    return NextResponse.json(
-      {
-        error: 'Internal Server Error',
-        message: 'An unexpected error occurred. Please try again later.'
-      },
-      { status: 500 }
-    );
-  }
-}
-

src/core/api/respond.js

@@ -0,0 +1,78 @@
+/**
+ * API Response Utilities
+ *
+ * Consistent, named response creation for all API handlers — core and modules alike.
+ * Using these functions makes intent explicit at every return site.
+ *
+ * Usage:
+ *   import { apiSuccess, apiError } from '../respond.js';
+ *
+ *   return apiSuccess({ user });
+ *   return apiSuccess({ users }, { page, total, totalPages });
+ *   return apiError('Not Found', 'User not found');
+ */
+
+/**
+ * Create a successful API response payload.
+ *
+ * Returns the payload as-is — no envelope wrapping — so existing frontend
+ * consumers remain compatible. The function exists to make success paths
+ * explicit and searchable alongside apiError() calls.
+ *
+ * @param {Object} payload - The data to return to the client
+ * @returns {Object}
+ */
+export function apiSuccess(payload) {
+  return payload;
+}
+
+/**
+ * Create an error API response payload.
+ *
+ * The `code` field is read by getStatusCode() to derive the HTTP status.
+ * Always use one of the recognised codes below — any other value maps to 500.
+ *
+ * Valid codes → HTTP status:
+ *   'Unauthorized'          → 401
+ *   'Admin access required' → 403
+ *   'Forbidden'             → 403
+ *   'Not Found'             → 404
+ *   'Bad Request'           → 400
+ *   'Too Many Requests'     → 429
+ *   'Internal Server Error' → 500
+ *
+ * @param {string} code    - Machine-readable error code
+ * @param {string} message - User-facing message, safe for client exposure
+ * @returns {{ error: string, message: string }}
+ */
+export function apiError(code, message) {
+  return { error: code, message };
+}
+
+/**
+ * Derive an HTTP status code from a response payload.
+ * Reads the `error` field set by apiError().
+ *
+ * @param {Object} response
+ * @returns {number}
+ */
+export function getStatusCode(response) {
+  if (response.error) {
+    switch (response.error) {
+      case 'Unauthorized':
+        return 401;
+      case 'Forbidden':
+      case 'Admin access required':
+        return 403;
+      case 'Not Found':
+        return 404;
+      case 'Bad Request':
+        return 400;
+      case 'Too Many Requests':
+        return 429;
+      default:
+        return 500;
+    }
+  }
+  return 200;
+}

src/core/api/route-handler.js

@@ -0,0 +1,51 @@
+/**
+ * ZEN API Route Handler
+ *
+ * Catch-all Next.js App Router handler for all routes under /zen/api/.
+ * Place this file at: app/zen/api/[...path]/route.js
+ *
+ * All HTTP methods are handled by a single factory. GET additionally
+ * supports file streaming responses from the storage endpoint.
+ */
+
+import { NextResponse } from 'next/server';
+import { routeRequest } from './router.js';
+import { apiError, getStatusCode } from './respond.js';
+import { buildFileResponse } from './file-response.js';
+import { fail } from '@zen/core/shared/logger';
+
+const GENERIC_ERROR_MSG = 'An unexpected error occurred. Please try again later.';
+
+/**
+ * Create a Next.js route handler for a given HTTP method.
+ *
+ * @param {boolean} [serveFiles=false] - When true, file streaming responses are
+ *   returned directly instead of being wrapped in JSON. Only GET needs this.
+ * @returns {Function} Next.js App Router handler
+ */
+function makeHandler(serveFiles = false) {
+  return async function handler(request, { params }) {
+    try {
+      const path = (await params).path ?? [];
+      const response = await routeRequest(request, path);
+
+      if (serveFiles && response.success && response.file) {
+        return buildFileResponse(response.file);
+      }
+
+      return NextResponse.json(response, { status: getStatusCode(response) });
+    } catch (error) {
+      fail(`API error: ${error.message}`);
+      return NextResponse.json(
+        apiError('Internal Server Error', GENERIC_ERROR_MSG),
+        { status: 500 }
+      );
+    }
+  };
+}
+
+export const GET    = makeHandler(true);
+export const POST   = makeHandler();
+export const PUT    = makeHandler();
+export const PATCH  = makeHandler();
+export const DELETE = makeHandler();

src/core/api/router.js

@@ -1,43 +1,83 @@
 /**
  * API Router
- * Routes incoming requests to appropriate handlers
  *
- * This router supports both:
- * - Core routes (health, version, users, storage)
- * - Module routes (imported directly from module api.js files)
+ * Orchestre rate limiting, CSRF, enforcement d'auth et dispatch vers les handlers.
+ * N'a aucune connaissance des features spécifiques — les routes s'auto-enregistrent.
+ *
+ * Initialisation requise :
+ *   Appeler configureRouter({ resolveSession }) une fois au démarrage (dans initializeZen)
+ *   avant toute requête. Le resolver est fourni par la feature auth, ce qui garde
+ *   core/api/ libre de tout import feature.
+ *
+ * Cycle de vie d'une requête :
+ *   route-handler.js → routeRequest()
+ *     → rate limit (routes skipRateLimit exemptées)
+ *     → validation CSRF (méthodes state-mutating uniquement)
+ *     → matching sur toutes les routes (core en premier, puis features, puis modules)
+ *       → enforcement auth depuis la définition de route
+ *       → handler(request, params, context)
  */
 
-import { validateSession } from '../../features/auth/lib/session.js';
-import { cookies } from 'next/headers';
-import { getSessionCookieName } from '../../shared/lib/appConfig.js';
-import { getAllApiRoutes } from '../modules/index.js';
-import { checkRateLimit, getIpFromRequest, formatRetryAfter } from '../../features/auth/lib/rateLimit.js';
-import { fail } from '../../shared/lib/logger.js';
+import { getSessionCookieName } from '@zen/core/shared/config';
+import { checkRateLimit, getIpFromRequest, formatRetryAfter } from '@zen/core/shared/rate-limit';
+import { fail } from '@zen/core/shared/logger';
+import { hasPermission, PERMISSIONS } from '@zen/core/users';
+import { getCoreRoutes } from './core-routes.js';
+import { getFeatureRoutes, getSessionResolver } from './runtime.js';
+import { apiError } from './respond.js';
 
-// Core handlers
-import { handleHealth } from './handlers/health.js';
-import {
-  handleGetCurrentUser, 
-  handleGetUserById, 
-  handleListUsers,
-  handleUpdateProfile,
-  handleUpdateUserById,
-  handleUploadProfilePicture,
-  handleDeleteProfilePicture
-} from './handlers/users.js';
-import { handleGetFile } from './handlers/storage.js';
+export { configureRouter, getSessionResolver, clearRouterConfig } from './runtime.js';
 
-// Get cookie name from environment or use default
 const COOKIE_NAME = getSessionCookieName();
 
+// ---------------------------------------------------------------------------
+// Auth helpers
+// ---------------------------------------------------------------------------
+
 /**
- * Resolve the canonical application URL from environment variables.
- *
- * Priority:
- *   1. NEXT_PUBLIC_URL_DEV  — used when NODE_ENV=development
- *   2. NEXT_PUBLIC_URL      — used in production
- *
- * @returns {string|null}
+ * Exige une session valide. Lève une erreur si aucun cookie valide n'est présent.
+ * @returns {Promise<Object>} session
+ */
+export async function requireAuth() {
+  const { cookies } = await import('next/headers');
+  const cookieStore = await cookies();
+  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
+
+  if (!sessionToken) {
+    throw new Error('Unauthorized');
+  }
+
+  const session = await getSessionResolver()(sessionToken);
+
+  if (!session || !session.user) {
+    throw new Error('Unauthorized');
+  }
+
+  return session;
+}
+
+/**
+ * Exige une session avec la permission admin.access.
+ * @returns {Promise<Object>} session
+ */
+export async function requireAdmin() {
+  const session = await requireAuth();
+
+  const allowed = await hasPermission(session.user.id, PERMISSIONS.ADMIN_ACCESS);
+  if (!allowed) {
+    throw new Error('Admin access required');
+  }
+
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// CSRF
+// ---------------------------------------------------------------------------
+
+/**
+ * Résout l'URL canonique de l'application depuis les variables d'environnement.
+ * Priorité : NEXT_PUBLIC_URL_DEV (développement) → NEXT_PUBLIC_URL (production).
  */
 function resolveAppUrl() {
   if (process.env.NODE_ENV === 'development' && process.env.NEXT_PUBLIC_URL_DEV) {
@@ -47,17 +87,10 @@ function resolveAppUrl() {
 }
 
 /**
- * Verify that state-mutating requests (POST/PUT/PATCH/DELETE) originate from
- * the expected application origin, blocking cross-site request forgery.
- *
- * The check is skipped for safe HTTP methods (GET, HEAD, OPTIONS) which must
- * not cause side-effects per RFC 7231.
- *
- * The expected origin is resolved from environment variables (see resolveAppUrl).
- * If no URL is configured the check denies the request and logs an error.
- *
+ * Vérifie que les requêtes state-mutating proviennent de l'origine attendue.
+ * GET, HEAD et OPTIONS sont exemptés (RFC 7231).
  * @param {Request} request
- * @returns {boolean} true if the request passes CSRF validation
+ * @returns {boolean}
  */
 function passesCsrfCheck(request) {
   const safeMethods = new Set(['GET', 'HEAD', 'OPTIONS']);
@@ -82,7 +115,7 @@ function passesCsrfCheck(request) {
     return origin === expectedOrigin;
   }
 
-  // No Origin header: fall back to Referer (e.g., some older browsers).
+  // Pas d'en-tête Origin : repli sur Referer (anciens navigateurs).
   const referer = request.headers.get('referer');
   if (referer) {
     try {
@@ -92,260 +125,58 @@ function passesCsrfCheck(request) {
     }
   }
 
-  // Neither Origin nor Referer present — deny to be safe.
+  // Ni Origin ni Referer — refus par sécurité.
   return false;
 }
 
-/**
- * Get all module routes from the dynamic module registry
- * @returns {Array} Array of route definitions
- */
-function getModuleRoutes() {
-  // Use the dynamic module registry to get all routes
-  return getAllApiRoutes();
-}
+// ---------------------------------------------------------------------------
+// Route matching
+// ---------------------------------------------------------------------------
 
 /**
- * Check if user is authenticated
- * @param {Request} request - The request object
- * @returns {Promise<Object>} Session object if authenticated
- * @throws {Error} If not authenticated
- */
-async function requireAuth(request) {
-  const cookieStore = await cookies();
-  const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
-  
-  if (!sessionToken) {
-    throw new Error('Unauthorized');
-  }
-  
-  const session = await validateSession(sessionToken);
-  
-  if (!session || !session.user) {
-    throw new Error('Unauthorized');
-  }
-  
-  return session;
-}
-
-/**
- * Check if user is authenticated and is admin
- * @param {Request} request - The request object
- * @returns {Promise<Object>} Session object if authenticated and admin
- * @throws {Error} If not authenticated or not admin
- */
-async function requireAdmin(request) {
-  const session = await requireAuth(request);
-  
-  if (session.user.role !== 'admin') {
-    throw new Error('Admin access required');
-  }
-  
-  return session;
-}
-
-/**
- * Route an API request to the appropriate handler
- * @param {Request} request - The incoming request
- * @param {string[]} path - The path segments after /zen/api/
- * @returns {Promise<Object>} - The response data
- */
-export async function routeRequest(request, path) {
-  const method = request.method;
-
-  // Global IP-based rate limit for all API calls (health is exempt)
-  const isExempt = path[0] === 'health' && method === 'GET';
-  if (!isExempt) {
-    const ip = getIpFromRequest(request);
-    const rl = checkRateLimit(ip, 'api');
-    if (!rl.allowed) {
-      return {
-        error: 'Too Many Requests',
-        message: `Trop de requêtes. Réessayez dans ${formatRetryAfter(rl.retryAfterMs)}.`
-      };
-    }
-  }
-
-  // CSRF origin validation for state-mutating requests.
-  if (!passesCsrfCheck(request)) {
-    return { error: 'Forbidden', message: 'CSRF validation failed' };
-  }
-
-  // Try core routes first
-  const coreResult = await routeCoreRequest(request, path, method);
-  if (coreResult !== null) {
-    return coreResult;
-  }
-
-  // Try module routes (dynamically discovered)
-  const moduleResult = await routeModuleRequest(request, path, method);
-  if (moduleResult !== null) {
-    return moduleResult;
-  }
-
-  // No matching route — return a generic message without reflecting the
-  // requested method or path back to the caller (prevents route enumeration).
-  return {
-    error: 'Not Found',
-    message: 'The requested resource does not exist'
-  };
-}
-
-/**
- * Route core (non-module) requests
- * @param {Request} request - The incoming request
- * @param {string[]} path - The path segments
- * @param {string} method - HTTP method
- * @returns {Promise<Object|null>} Response or null if no match
- */
-async function routeCoreRequest(request, path, method) {
-  // Health check endpoint
-  if (path[0] === 'health' && method === 'GET') {
-    return await handleHealth();
-  }
-
-  // Storage endpoint - serve files securely
-  if (path[0] === 'storage' && method === 'GET') {
-    const fileKey = path.slice(1).join('/');
-    if (!fileKey) {
-      return {
-        error: 'Bad Request',
-        message: 'File path is required'
-      };
-    }
-    return await handleGetFile(request, fileKey);
-  }
-
-  // User endpoints
-  if (path[0] === 'users') {
-    // GET /zen/api/users - List all users (admin only)
-    if (path.length === 1 && method === 'GET') {
-      return await handleListUsers(request);
-    }
-
-    // GET /zen/api/users/me - Get current user
-    if (path[1] === 'me' && method === 'GET') {
-      return await handleGetCurrentUser(request);
-    }
-
-    // PUT /zen/api/users/profile - Update current user profile
-    if (path[1] === 'profile' && method === 'PUT') {
-      return await handleUpdateProfile(request);
-    }
-
-    // POST /zen/api/users/profile/picture - Upload profile picture
-    if (path[1] === 'profile' && path[2] === 'picture' && method === 'POST') {
-      return await handleUploadProfilePicture(request);
-    }
-
-    // DELETE /zen/api/users/profile/picture - Delete profile picture
-    if (path[1] === 'profile' && path[2] === 'picture' && method === 'DELETE') {
-      return await handleDeleteProfilePicture(request);
-    }
-
-    // GET /zen/api/users/:id - Get user by ID (admin only)
-    if (path[1] && path[1] !== 'me' && path[1] !== 'profile' && method === 'GET') {
-      return await handleGetUserById(request, path[1]);
-    }
-
-    // PUT /zen/api/users/:id - Update user by ID (admin only)
-    if (path[1] && path[1] !== 'me' && path[1] !== 'profile' && method === 'PUT') {
-      return await handleUpdateUserById(request, path[1]);
-    }
-  }
-
-  return null;
-}
-
-/**
- * Route module requests
- * @param {Request} request - The incoming request
- * @param {string[]} path - The path segments
- * @param {string} method - HTTP method
- * @returns {Promise<Object|null>} Response or null if no match
- */
-async function routeModuleRequest(request, path, method) {
-  // Get routes from enabled modules
-  const routes = getModuleRoutes();
-  
-  // Convert path array to path string
-  const pathString = '/' + path.join('/');
-  
-  // Find matching route
-  for (const route of routes) {
-    if (matchRoute(route.path, pathString) && route.method === method) {
-      // Check authentication
-      try {
-        if (route.auth === 'admin') {
-          await requireAdmin(request);
-        } else if (route.auth === 'user' || route.auth === 'auth') {
-          await requireAuth(request);
-        }
-        // 'public' or undefined means no auth required
-        
-        // Call the handler
-        if (typeof route.handler === 'function') {
-          // Extract path parameters
-          const params = extractPathParams(route.path, pathString);
-          return await route.handler(request, params);
-        }
-      } catch (err) {
-        // Only the two known auth-error strings are safe to surface verbatim.
-        // Any other exception (database errors, upstream API errors, etc.) must
-        // never reach the client raw — they can contain credentials, table names,
-        // or internal hostnames. Log the full error server-side only.
-        const SAFE_AUTH_MESSAGES = new Set(['Unauthorized', 'Admin access required']);
-        if (!SAFE_AUTH_MESSAGES.has(err.message)) {
-          fail(`Module route handler error: ${err.message}`);
-        }
-        return {
-          success: false,
-          error: SAFE_AUTH_MESSAGES.has(err.message) ? err.message : 'Internal Server Error'
-        };
-      }
-    }
-  }
-  
-  return null;
-}
-
-/**
- * Match a route pattern against a path
- * Supports path parameters like :id
- * @param {string} pattern - Route pattern (e.g., '/admin/invoices/:id')
- * @param {string} path - Actual path (e.g., '/admin/invoices/123')
- * @returns {boolean} True if matches
+ * Teste un pattern de route contre un chemin de requête.
+ *
+ * Supporte :
+ *   - Segments exacts : '/health'
+ *   - Paramètres nommés : '/users/:id'
+ *   - Wildcard greedy (fin uniquement) : '/storage/**'
+ *
+ * @param {string} pattern
+ * @param {string} path
+ * @returns {boolean}
  */
 function matchRoute(pattern, path) {
   const patternParts = pattern.split('/').filter(Boolean);
   const pathParts = path.split('/').filter(Boolean);
 
-  if (patternParts.length !== pathParts.length) {
-    return false;
+  const hasWildcard = patternParts[patternParts.length - 1] === '**';
+
+  if (hasWildcard) {
+    const fixedParts = patternParts.slice(0, -1);
+    if (pathParts.length < fixedParts.length) return false;
+    for (let i = 0; i < fixedParts.length; i++) {
+      if (fixedParts[i].startsWith(':')) continue;
+      if (fixedParts[i] !== pathParts[i]) return false;
     }
+    return true;
+  }
+
+  if (patternParts.length !== pathParts.length) return false;
 
   for (let i = 0; i < patternParts.length; i++) {
-    const patternPart = patternParts[i];
-    const pathPart = pathParts[i];
-    
-    // Skip parameter parts (they match anything)
-    if (patternPart.startsWith(':')) {
-      continue;
-    }
-    
-    if (patternPart !== pathPart) {
-      return false;
-    }
+    if (patternParts[i].startsWith(':')) continue;
+    if (patternParts[i] !== pathParts[i]) return false;
   }
 
   return true;
 }
 
 /**
- * Extract path parameters from a path
- * @param {string} pattern - Route pattern (e.g., '/admin/invoices/:id')
- * @param {string} path - Actual path (e.g., '/admin/invoices/123')
- * @returns {Object} Path parameters
+ * Extrait les paramètres de chemin nommés (et le wildcard) d'une route matchée.
+ *
+ * @param {string} pattern - Ex. '/users/:id'
+ * @param {string} path    - Ex. '/users/42'
+ * @returns {Object} params — paramètres nommés + `wildcard` optionnel
  */
 function extractPathParams(pattern, path) {
   const params = {};
@@ -353,42 +184,117 @@ function extractPathParams(pattern, path) {
   const pathParts = path.split('/').filter(Boolean);
 
   for (let i = 0; i < patternParts.length; i++) {
-    const patternPart = patternParts[i];
-    
-    if (patternPart.startsWith(':')) {
-      const paramName = patternPart.slice(1);
-      params[paramName] = pathParts[i];
+    const part = patternParts[i];
+    if (part === '**') {
+      params.wildcard = pathParts.slice(i).join('/');
+      break;
+    }
+    if (part.startsWith(':')) {
+      params[part.slice(1)] = pathParts[i];
     }
   }
 
   return params;
 }
 
+// ---------------------------------------------------------------------------
+// Main router
+// ---------------------------------------------------------------------------
+
+// Messages sûrs à exposer verbatim au client.
+const SAFE_AUTH_MESSAGES = new Set(['Unauthorized', 'Admin access required']);
+
+// Émis au plus une fois par lifetime de process pour éviter le log flooding.
+let _rateLimitUnavailableWarned = false;
+
 /**
- * Get the HTTP status code based on the response
- * @param {Object} response - The response object
- * @returns {number} - HTTP status code
+ * Route une requête API vers le handler approprié.
+ *
+ * @param {Request} request  - Requête Next.js entrante
+ * @param {string[]} path    - Segments de chemin après /zen/api/
+ * @returns {Promise<Object>} Payload de réponse (sérialisé en JSON par route-handler.js)
  */
-export function getStatusCode(response) {
-  if (response.error) {
-    switch (response.error) {
-      case 'Unauthorized':
-        return 401;
-      case 'Forbidden':
-      case 'Admin access required':
-        return 403;
-      case 'Not Found':
-        return 404;
-      case 'Bad Request':
-        return 400;
-      case 'Too Many Requests':
-        return 429;
-      default:
-        return 500;
+export async function routeRequest(request, path) {
+  const method = request.method;
+  const pathString = '/' + path.join('/');
+
+  // Fusion de toutes les routes — core en premier pour que les built-ins aient priorité.
+  // Le rate limit est différé après le matching pour pouvoir honorer skipRateLimit
+  // sans hardcoder de chemins dans le router.
+  const allRoutes = [...getCoreRoutes(), ...getFeatureRoutes()];
+
+  const matchedRoute = allRoutes.find(
+    route => matchRoute(route.path, pathString) && route.method === method
+  );
+
+  // Rate limit par IP. Les routes avec skipRateLimit: true sont exemptées
+  // (ex. GET /health pour que les sondes de monitoring ne consomment pas de quota).
+  if (!matchedRoute?.skipRateLimit) {
+    const ip = getIpFromRequest(request);
+    if (ip === 'unknown') {
+      // L'IP client ne peut pas être résolue — appliquer le rate limit sur la clé
+      // 'unknown' partagée effondrerait tout le trafic dans un seul bucket, permettant
+      // à un seul attaquant d'épuiser le quota et de dénier le service à tous les autres.
+      // Le rate limiting est donc suspendu jusqu'à ce qu'un reverse proxy de confiance
+      // soit configuré avec ZEN_TRUST_PROXY=true.
+      if (!_rateLimitUnavailableWarned) {
+        _rateLimitUnavailableWarned = true;
+        fail(
+          'Rate limiting inactive: client IP cannot be determined. ' +
+          'Set ZEN_TRUST_PROXY=true behind a verified reverse proxy to enable per-IP rate limiting.'
+        );
+      }
+    } else {
+      const rl = checkRateLimit(ip, 'api');
+      if (!rl.allowed) {
+        return apiError(
+          'Too Many Requests',
+          `Trop de requêtes. Réessayez dans ${formatRetryAfter(rl.retryAfterMs)}.`
+        );
       }
     }
-  return 200;
   }
 
-// Export auth helpers for use in module handlers
-export { requireAuth, requireAdmin };
+  // Validation CSRF pour les requêtes state-mutating.
+  if (!passesCsrfCheck(request)) {
+    return apiError('Forbidden', 'CSRF validation failed');
+  }
+
+  if (!matchedRoute) {
+    // Aucune route matchée — message générique sans refléter la méthode ou le chemin
+    // pour éviter l'énumération de routes.
+    return apiError('Not Found', 'The requested resource does not exist');
+  }
+
+  // Enforcement auth depuis la définition de route, avant d'appeler le handler.
+  const context = {};
+  try {
+    if (matchedRoute.auth === 'admin') {
+      context.session = await requireAdmin();
+      if (matchedRoute.permission) {
+        const allowed = await hasPermission(context.session.user.id, matchedRoute.permission);
+        if (!allowed) {
+          return apiError('Forbidden', 'Permission insuffisante');
+        }
+      }
+    } else if (matchedRoute.auth === 'user') {
+      context.session = await requireAuth();
+    }
+    // 'public' — context.session reste undefined
+  } catch (err) {
+    const code = SAFE_AUTH_MESSAGES.has(err.message) ? err.message : 'Internal Server Error';
+    if (!SAFE_AUTH_MESSAGES.has(err.message)) {
+      fail(`Auth error: ${err.message}`);
+    }
+    return apiError(code, code);
+  }
+
+  const params = extractPathParams(matchedRoute.path, pathString);
+
+  try {
+    return await matchedRoute.handler(request, params, context);
+  } catch (err) {
+    fail(`Route handler error [${method} ${matchedRoute.path}]: ${err.message}`);
+    return apiError('Internal Server Error', 'An unexpected error occurred. Please try again later.');
+  }
+}

src/core/api/runtime.js

@@ -0,0 +1,106 @@
+/**
+ * API Runtime State
+ *
+ * Centralise tout l'état global persisté de l'infrastructure API :
+ *   - Le resolver de session (injecté par la feature auth via configureRouter)
+ *   - Le registre des routes de features (peuplé via registerFeatureRoutes)
+ *
+ * Les deux utilisent le même pattern Symbol.for() + globalThis pour survivre
+ * aux hot-reloads Next.js sans réinitialiser l'état entre les recharges de modules.
+ *
+ * LIMITATION CONNUE : l'état est local au process. Dans un déploiement multi-worker
+ * ou serverless, chaque instance maintient son propre état. Pour les routes, cela
+ * implique que initializeZen() doit être appelé une fois par worker — ce qui est
+ * déjà le cas via instrumentation.js.
+ */
+
+// ---------------------------------------------------------------------------
+// Session resolver
+// ---------------------------------------------------------------------------
+
+const RESOLVER_KEY = Symbol.for('__ZEN_SESSION_RESOLVER__');
+
+/**
+ * Configure le router avec les dépendances de la feature auth.
+ * Doit être appelé une fois au démarrage avant toute requête.
+ *
+ * @param {{ resolveSession: (token: string) => Promise<Object|null> }} config
+ */
+export function configureRouter({ resolveSession }) {
+  if (typeof resolveSession !== 'function') {
+    throw new TypeError('configureRouter: resolveSession must be a function');
+  }
+  globalThis[RESOLVER_KEY] = resolveSession;
+}
+
+/**
+ * Retourne le resolver de session configuré.
+ * Utilisé par router.js et core/storage/api.js.
+ *
+ * @returns {(token: string) => Promise<Object|null>}
+ * @throws {Error} Si configureRouter n'a pas encore été appelé
+ */
+export function getSessionResolver() {
+  const resolver = globalThis[RESOLVER_KEY];
+  if (!resolver) {
+    throw new Error(
+      'Router not configured: call configureRouter({ resolveSession }) during initializeZen() before handling requests.'
+    );
+  }
+  return resolver;
+}
+
+/**
+ * Efface le resolver injecté.
+ * Destiné aux tests ou à la réinitialisation manuelle.
+ */
+export function clearRouterConfig() {
+  globalThis[RESOLVER_KEY] = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Feature routes registry
+// ---------------------------------------------------------------------------
+
+const REGISTRY_KEY = Symbol.for('__ZEN_FEATURE_ROUTES__');
+if (!globalThis[REGISTRY_KEY]) globalThis[REGISTRY_KEY] = [];
+/** @type {Array} */
+const _featureRoutes = globalThis[REGISTRY_KEY];
+
+/**
+ * Enregistre des routes API.
+ * Appelé une fois par feature core ou module externe pendant initializeZen()
+ * ou depuis le hook register() d'un module.
+ *
+ * @param {ReadonlyArray} routes - Définitions produites par defineApiRoutes()
+ */
+export function registerApiRoutes(routes) {
+  if (!Array.isArray(routes)) {
+    throw new TypeError('registerApiRoutes: routes must be an array');
+  }
+  _featureRoutes.push(...routes);
+}
+
+/**
+ * Alias rétro-compatible de registerApiRoutes.
+ * @deprecated Utiliser registerApiRoutes.
+ */
+export const registerFeatureRoutes = registerApiRoutes;
+
+/**
+ * Retourne toutes les routes de features enregistrées.
+ * Appelé à chaque requête par le router pour construire la liste complète.
+ *
+ * @returns {ReadonlyArray}
+ */
+export function getFeatureRoutes() {
+  return _featureRoutes;
+}
+
+/**
+ * Vide toutes les routes de features enregistrées.
+ * Destiné aux tests ou à la réinitialisation de l'état ZEN.
+ */
+export function clearFeatureRoutes() {
+  _featureRoutes.length = 0;
+}

src/core/cron/README.md

@@ -0,0 +1,132 @@
+# Cron Framework
+
+Ce répertoire est un **wrapper générique autour de `node-cron`**. Il ne connaît aucune tâche spécifique — les modules et features enregistrent leurs propres jobs. Ajouter un nouveau job ne nécessite jamais de modifier `src/core/cron/`.
+
+---
+
+## Structure
+
+```
+src/core/cron/
+└── index.js   schedule, stop, stopAll, trigger, validate, isRunning, getJobs, getStatus
+```
+
+---
+
+## Import
+
+```js
+import { schedule, stop, trigger } from '@zen/core/cron';
+```
+
+---
+
+## API
+
+### `schedule(name, cronSchedule, handler, options?)`
+
+Enregistre un job. Si un job du même nom existe déjà, il est stoppé et remplacé.
+
+```js
+schedule('daily-report', '0 9 * * *', async () => {
+  await sendReport();
+});
+
+schedule('every-5min', '*/5 * * * *', async () => {
+  await syncData();
+}, { timezone: 'America/New_York', runOnInit: true });
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Nom unique du job |
+| `cronSchedule` | `string` | Expression cron (5 ou 6 champs) |
+| `handler` | `async Function` | Fonction exécutée à chaque déclenchement |
+| `options.timezone` | `string` | Timezone IANA (défaut : `ZEN_TIMEZONE` ou `America/Toronto`) |
+| `options.runOnInit` | `boolean` | Exécuter immédiatement à l'enregistrement (défaut : `false`) |
+
+Retourne l'instance `node-cron` task.
+
+---
+
+### `stop(name)`
+
+Stoppe et supprime un job par son nom. Retourne `true` si le job existait, `false` sinon.
+
+### `stopAll()`
+
+Stoppe et supprime tous les jobs enregistrés.
+
+### `trigger(name)`
+
+Déclenche manuellement un job sans attendre son prochain tick. Lève une `Error` si le job n'existe pas.
+
+```js
+await trigger('daily-report');
+```
+
+### `validate(expression)`
+
+Valide une expression cron. Retourne `boolean`.
+
+### `isRunning(name)`
+
+Vérifie si un job est actuellement enregistré. Retourne `boolean`.
+
+### `getJobs()`
+
+Retourne la liste des noms de tous les jobs enregistrés (`string[]`).
+
+### `getStatus()`
+
+Retourne les métadonnées de tous les jobs enregistrés.
+
+```js
+{
+  'daily-report': {
+    schedule: '0 9 * * *',
+    timezone: 'America/Toronto',
+    registeredAt: '2026-04-24T09:00:00.000Z'
+  }
+}
+```
+
+---
+
+## Enregistrer un job depuis un module
+
+Les jobs vivent **avec leur feature ou module**, pas dans le framework. Enregistrer un job dans `initializeZen()` (`src/shared/lib/init.js`) :
+
+```js
+// src/modules/mymodule/cron.js
+import { schedule } from '@zen/core/cron';
+
+export function registerCronJobs() {
+  schedule('mymodule-sync', '*/15 * * * *', async () => {
+    await syncMyModule();
+  });
+}
+```
+
+```js
+// src/shared/lib/init.js
+import { registerCronJobs } from '../../modules/mymodule/cron.js';
+
+registerCronJobs();
+```
+
+---
+
+## Comportement Hot-Reload
+
+Les jobs sont stockés dans `globalThis[Symbol.for('__ZEN_CRON_JOBS__')]` — un store partagé qui survit aux invalidations de cache de modules de Next.js. Un job enregistré deux fois (hot-reload) remplace silencieusement l'ancien plutôt que de créer un doublon.
+
+---
+
+## Gestion des erreurs
+
+Les erreurs levées par un handler sont interceptées et loguées via `fail()` — elles ne font jamais crasher le processus.
+
+```
+✗ Cron daily-report: Connection timeout
+```

src/core/cron/index.js

@@ -7,13 +7,22 @@
  */
 
 import cron from 'node-cron';
-import { done, fail, info } from '../../shared/lib/logger.js';
+import { done, fail, info } from '@zen/core/shared/logger';
 
-// Store for all scheduled cron jobs
+// Shared store — survives Next.js hot-reload and module-cache invalidation
 const CRON_JOBS_KEY = Symbol.for('__ZEN_CRON_JOBS__');
 
 /**
- * Initialize cron jobs storage
+ * @typedef {Object} CronEntry
+ * @property {Object}   job          - node-cron task instance
+ * @property {Function} handler      - original handler function
+ * @property {string}   schedule     - cron expression
+ * @property {string}   timezone     - timezone used
+ * @property {string}   registeredAt - ISO timestamp of registration
+ */
+
+/**
+ * @returns {Map<string, CronEntry>}
  */
 function getJobsStorage() {
   if (!globalThis[CRON_JOBS_KEY]) {
@@ -23,66 +32,85 @@ function getJobsStorage() {
 }
 
 /**
- * Schedule a cron job
+ * Schedule a cron job.
+ *
+ * If a job with the same name already exists it is stopped and replaced.
+ *
  * @param {string}   name         - Unique name for the job
- * @param {string} schedule - Cron schedule expression
- * @param {Function} handler - Handler function to execute
- * @param {Object} options - Options
- * @param {string} options.timezone - Timezone (default: from env or America/Toronto)
- * @param {boolean} options.runOnInit - Run immediately on schedule (default: false)
- * @returns {Object} Cron job instance
+ * @param {string}   cronSchedule - Cron expression (5 or 6 fields)
+ * @param {Function} handler      - Async function to execute
+ * @param {Object}   [options]
+ * @param {string}   [options.timezone]   - IANA timezone (default: ZEN_TIMEZONE env or America/Toronto)
+ * @param {boolean}  [options.runOnInit]  - Run immediately when scheduled (default: false)
+ * @returns {Object} node-cron task instance
  *
  * @example
- * schedule('my-task', '0 9 * * *', async () => {
- *   console.log('Running every day at 9 AM');
+ * schedule('daily-report', '0 9 * * *', async () => {
+ *   await sendReport();
  * });
  *
  * @example
- * schedule('reminder', ''\''*\/5 5-17 * * *'\'', async () => {
- *   console.log('Every 5 minutes between 5 AM and 5 PM');
+ * schedule('every-5min', '*\/5 * * * *', async () => {
+ *   await syncData();
  * }, { timezone: 'America/New_York' });
  */
 export function schedule(name, cronSchedule, handler, options = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Cron job name must be a non-empty string');
+  }
+  if (!validate(cronSchedule)) {
+    throw new Error(`Invalid cron expression: "${cronSchedule}"`);
+  }
+  if (typeof handler !== 'function') {
+    throw new Error('Cron job handler must be a function');
+  }
+
   const jobs = getJobsStorage();
 
-  // Stop existing job with same name
+  // Replace existing job with same name
   if (jobs.has(name)) {
-    jobs.get(name).stop();
+    jobs.get(name).job.stop();
     info(`Cron replaced: ${name}`);
   }
 
   const timezone = options.timezone || process.env.ZEN_TIMEZONE || 'America/Toronto';
 
   const job = cron.schedule(cronSchedule, async () => {
-    info(`Cron ${name} running at ${new Date().toISOString()}`);
     try {
       await handler();
-      info(`Cron ${name} completed`);
     } catch (error) {
       fail(`Cron ${name}: ${error.message}`);
     }
-  }, {
-    scheduled: true,
+  }, { timezone });
+
+  if (options.runOnInit) {
+    handler().catch((error) => fail(`Cron ${name}: ${error.message}`));
+  }
+
+  jobs.set(name, {
+    job,
+    handler,
+    schedule: cronSchedule,
     timezone,
-    runOnInit: options.runOnInit || false
+    registeredAt: new Date().toISOString()
   });
 
-  jobs.set(name, job);
   done(`Cron scheduled: ${name} (${cronSchedule})`);
 
   return job;
 }
 
 /**
- * Stop a scheduled cron job
+ * Stop and remove a scheduled cron job.
+ *
  * @param {string} name - Job name
- * @returns {boolean} True if job was stopped
+ * @returns {boolean} True if the job existed and was stopped
  */
 export function stop(name) {
   const jobs = getJobsStorage();
 
   if (jobs.has(name)) {
-    jobs.get(name).stop();
+    jobs.get(name).job.stop();
     jobs.delete(name);
     info(`Cron stopped: ${name}`);
     return true;
@@ -92,67 +120,25 @@ export function stop(name) {
 }
 
 /**
- * Stop all cron jobs
+ * Stop and remove all scheduled cron jobs.
  */
 export function stopAll() {
   const jobs = getJobsStorage();
 
-  for (const [name, job] of jobs.entries()) {
-    job.stop();
+  for (const [name, entry] of jobs.entries()) {
+    entry.job.stop();
     info(`Cron stopped: ${name}`);
   }
 
   jobs.clear();
-  done('All cron jobs stopped');
 }
 
 /**
- * Get status of all cron jobs
- * @returns {Object} Status of all jobs
- */
-export function getStatus() {
-  const jobs = getJobsStorage();
-  const status = {};
-  
-  for (const [name] of jobs.entries()) {
-    status[name] = { running: true };
-  }
-  
-  return status;
-}
-
-/**
- * Check if a cron job is running
- * @param {string} name - Job name
- * @returns {boolean}
- */
-export function isRunning(name) {
-  const jobs = getJobsStorage();
-  return jobs.has(name);
-}
-
-/**
- * Validate a cron expression
- * @param {string} expression - Cron expression to validate
- * @returns {boolean} True if valid
- */
-export function validate(expression) {
-  return cron.validate(expression);
-}
-
-/**
- * Get list of all scheduled job names
- * @returns {string[]} Array of job names
- */
-export function getJobs() {
-  const jobs = getJobsStorage();
-  return Array.from(jobs.keys());
-}
-
-/**
- * Manually trigger a job by name
+ * Manually trigger a job by name, bypassing its schedule.
+ *
  * @param {string} name - Job name
  * @returns {Promise<void>}
+ * @throws {Error} If the job does not exist
  */
 export async function trigger(name) {
   const jobs = getJobsStorage();
@@ -162,22 +148,64 @@ export async function trigger(name) {
   }
 
   info(`Cron manual trigger: ${name}`);
-  // Note: node-cron doesn't expose the handler directly,
-  // so modules should keep their handler function accessible
+  await jobs.get(name).handler();
 }
 
-// Re-export the raw cron module for advanced usage
-export { cron };
+/**
+ * Validate a cron expression.
+ *
+ * @param {string} expression
+ * @returns {boolean}
+ */
+export function validate(expression) {
+  return cron.validate(expression);
+}
+
+/**
+ * Check whether a job is currently scheduled.
+ *
+ * @param {string} name - Job name
+ * @returns {boolean}
+ */
+export function isRunning(name) {
+  return getJobsStorage().has(name);
+}
+
+/**
+ * Return the names of all scheduled jobs.
+ *
+ * @returns {string[]}
+ */
+export function getJobs() {
+  return Array.from(getJobsStorage().keys());
+}
+
+/**
+ * Return metadata for all scheduled jobs.
+ *
+ * @returns {Object.<string, { schedule: string, timezone: string, registeredAt: string }>}
+ */
+export function getStatus() {
+  const status = {};
+
+  for (const [name, entry] of getJobsStorage().entries()) {
+    status[name] = {
+      schedule: entry.schedule,
+      timezone: entry.timezone,
+      registeredAt: entry.registeredAt
+    };
+  }
+
+  return status;
+}
 
-// Default export for convenience
 export default {
   schedule,
   stop,
   stopAll,
-  getStatus,
-  isRunning,
-  validate,
-  getJobs,
   trigger,
-  cron
+  validate,
+  isRunning,
+  getJobs,
+  getStatus
 };

src/core/database/README.md

@@ -0,0 +1,292 @@
+# Database
+
+Ce répertoire est le **module de base de données**. Il fournit une couche d'accès PostgreSQL générique : connexion, requêtes paramétrées, transactions et helpers CRUD. Il ne connaît aucune feature spécifique — les features l'importent pour leurs propres besoins.
+
+---
+
+## Structure
+
+```
+src/core/database/
+├── index.js    Exports publics (query, transaction, create, find, update…)
+├── db.js       Pool de connexion, DatabaseError, fonctions de requête bas niveau
+└── crud.js     Helpers CRUD (create, find, update, delete, count, exists…)
+```
+
+---
+
+## Variables d'environnement
+
+| Variable | Rôle |
+|----------|------|
+| `ZEN_DATABASE_URL` | URL de connexion PostgreSQL (tous environnements) |
+| `ZEN_DATABASE_URL_DEV` | URL de connexion en développement (prioritaire sur `ZEN_DATABASE_URL` si `NODE_ENV=development`) |
+| `ZEN_DB_SSL_DISABLED` | Mettre à `true` pour désactiver TLS entièrement (loopback local uniquement) |
+
+### Politique TLS
+
+| Environnement | Comportement |
+|---------------|-------------|
+| `production` | TLS activé, vérification du certificat serveur (`rejectUnauthorized: true`) |
+| Autres (`development`, `test`…) | TLS activé, vérification désactivée (accepte les certificats auto-signés) |
+| `ZEN_DB_SSL_DISABLED=true` | TLS désactivé (usage local uniquement) |
+
+---
+
+## DatabaseError
+
+Toutes les opérations base de données lèvent une `DatabaseError` en cas d'échec. Elle expose uniquement un message générique et le code d'erreur PostgreSQL (SQLSTATE), sans jamais retourner de nom de table, de contrainte ou de fragment SQL.
+
+```js
+import { DatabaseError } from '@zen/core/database';
+
+try {
+  await create('users', { email });
+} catch (error) {
+  if (error instanceof DatabaseError && error.code === '23505') {
+    // Violation de contrainte unique (ex: email déjà utilisé)
+  }
+}
+```
+
+Codes SQLSTATE courants :
+
+| Code | Signification |
+|------|--------------|
+| `23505` | Violation de contrainte unique (`UNIQUE`) |
+| `23503` | Violation de contrainte de clé étrangère (`FOREIGN KEY`) |
+| `23502` | Violation de contrainte `NOT NULL` |
+
+---
+
+## Fonctions de requête bas niveau (`db.js`)
+
+### `query(sql, params?)`
+
+Exécute une requête SQL paramétrée et retourne l'objet résultat complet `pg`.
+
+```js
+const result = await query('SELECT * FROM users WHERE id = $1', [userId]);
+// result.rows, result.rowCount…
+```
+
+### `queryOne(sql, params?)`
+
+Retourne la première ligne ou `null`.
+
+```js
+const user = await queryOne('SELECT * FROM users WHERE email = $1', [email]);
+```
+
+### `queryAll(sql, params?)`
+
+Retourne toutes les lignes sous forme de tableau.
+
+```js
+const posts = await queryAll('SELECT * FROM posts WHERE published = true');
+```
+
+### `transaction(callback)`
+
+Exécute plusieurs requêtes dans une transaction atomique. Rollback automatique en cas d'erreur.
+
+```js
+const result = await transaction(async (client) => {
+  const post = await client.query(
+    'INSERT INTO posts (title) VALUES ($1) RETURNING *',
+    ['Mon article']
+  );
+  await client.query(
+    'INSERT INTO post_tags (post_id, tag) VALUES ($1, $2)',
+    [post.rows[0].id, 'actu']
+  );
+  return post.rows[0];
+});
+```
+
+### `testConnection()`
+
+Vérifie que la connexion à la base est établie. Retourne `true` ou `false`.
+
+### `tableExists(tableName)`
+
+Vérifie si une table existe dans le schéma `public`. Retourne `true` ou `false`.
+
+```js
+if (!(await tableExists('users'))) {
+  // table absente — migration non appliquée
+}
+```
+
+---
+
+## Helpers CRUD (`crud.js`)
+
+Toutes les fonctions CRUD construisent du SQL **entièrement paramétré**. Les noms de tables et de colonnes passent par `safeIdentifier()` — injection SQL impossible.
+
+### `create(tableName, data, options?)`
+
+Insère un enregistrement et retourne la ligne créée (via `RETURNING *`).
+
+```js
+const user = await create('users', { email, name, role: 'user' });
+```
+
+Option `allowedColumns` (recommandée) : liste blanche explicite des colonnes autorisées. Toute clé absente de cette liste lève immédiatement une erreur.
+
+```js
+const user = await create('users', body, {
+  allowedColumns: ['email', 'name'],
+  // 'role' absent → une tentative de mass-assignment lèvera une erreur
+});
+```
+
+### `findById(tableName, id, idColumn?)`
+
+Retourne l'enregistrement correspondant à l'identifiant, ou `null`.
+
+```js
+const post = await findById('posts', 42);
+const user = await findById('users', slug, 'slug');
+```
+
+### `find(tableName, conditions?, options?)`
+
+Retourne un tableau d'enregistrements correspondant aux conditions.
+
+```js
+const published = await find('posts', { published: true }, {
+  orderBy: 'created_at DESC',
+  limit: 10,
+  offset: 0,
+});
+```
+
+Options disponibles :
+
+| Option | Type | Contrainte |
+|--------|------|-----------|
+| `orderBy` | `string` | `"colonne"` ou `"colonne ASC\|DESC"` |
+| `limit` | `number` | Entier entre 1 et 10 000 |
+| `offset` | `number` | Entier ≥ 0 |
+
+### `findOne(tableName, conditions)`
+
+Retourne le premier enregistrement correspondant, ou `null`.
+
+```js
+const user = await findOne('users', { email });
+```
+
+### `updateById(tableName, id, data, idColumn?, options?)`
+
+Met à jour un enregistrement par identifiant et retourne la ligne mise à jour, ou `null` si introuvable.
+
+```js
+const updated = await updateById('users', userId, { name: 'Alice' });
+
+// Avec whitelist
+const updated = await updateById('users', userId, body, 'id', {
+  allowedColumns: ['name', 'avatar_url'],
+});
+```
+
+### `update(tableName, conditions, data, options?)`
+
+Met à jour tous les enregistrements correspondant aux conditions. **Au moins une condition est obligatoire** — une mise à jour sans condition lève immédiatement une erreur.
+
+```js
+const rows = await update('posts', { author_id: userId }, { published: false });
+```
+
+### `deleteById(tableName, id, idColumn?)`
+
+Supprime un enregistrement par identifiant. Retourne `true` si supprimé, `false` sinon.
+
+```js
+const deleted = await deleteById('posts', postId);
+```
+
+### `deleteWhere(tableName, conditions)`
+
+Supprime tous les enregistrements correspondant aux conditions. **Au moins une condition est obligatoire** — une suppression sans condition lève immédiatement une erreur. Retourne le nombre de lignes supprimées.
+
+```js
+const count = await deleteWhere('sessions', { user_id: userId });
+```
+
+### `count(tableName, conditions?)`
+
+Retourne le nombre d'enregistrements correspondant aux conditions (ou le total si aucune condition).
+
+```js
+const total = await count('users');
+const admins = await count('users', { role: 'admin' });
+```
+
+### `exists(tableName, conditions)`
+
+Retourne `true` si au moins un enregistrement correspond aux conditions.
+
+```js
+const taken = await exists('users', { email });
+```
+
+---
+
+## Utilitaires de sécurité
+
+### `safeIdentifier(name)`
+
+Valide et encadre de guillemets doubles un identifiant SQL (nom de table ou de colonne). Autorise uniquement `[A-Za-z_][A-Za-z0-9_]*`, longueur max 63. Lève une erreur pour tout identifiant invalide.
+
+```js
+safeIdentifier('users')    // → '"users"'
+safeIdentifier('my-table') // → Error: SQL identifier contains disallowed characters
+```
+
+### `safeOrderBy(orderBy)`
+
+Valide une expression `ORDER BY` : `"colonne"` ou `"colonne ASC|DESC"`. Utilise `safeIdentifier` en interne.
+
+```js
+safeOrderBy('created_at DESC') // → '"created_at" DESC'
+safeOrderBy('1=1; DROP TABLE') // → Error
+```
+
+### `filterAllowedColumns(data, allowedColumns?)`
+
+Filtre un objet de données selon une liste blanche de colonnes. Sans liste blanche, retourne l'objet tel quel. Avec liste blanche, toute clé absente lève immédiatement une erreur.
+
+```js
+filterAllowedColumns({ name: 'Alice', role: 'admin' }, ['name'])
+// → Error: Column "role" is not in the permitted columns list
+```
+
+---
+
+## Usage depuis une feature
+
+```js
+// src/features/myfeature/db.js
+import { create, find, updateById, deleteById, exists } from '../../core/database/index.js';
+
+export async function createItem(data) {
+  return create('items', data, { allowedColumns: ['title', 'content', 'author_id'] });
+}
+
+export async function getPublishedItems() {
+  return find('items', { published: true }, { orderBy: 'created_at DESC', limit: 50 });
+}
+```
+
+## Usage depuis un module
+
+```js
+// src/modules/mymodule/crud.js
+import { create, findById } from '@zen/core/database';
+
+export async function createEntry(data) {
+  return create('mymodule_entries', data, { allowedColumns: ['title', 'slug'] });
+}
+```

src/core/database/cli.js

@@ -16,14 +16,11 @@ dotenv.config({ path: resolve(process.cwd(), '.env.local') });
 // The CLI always runs locally, so default to development to use ZEN_DATABASE_URL_DEV if set
 process.env.NODE_ENV = process.env.NODE_ENV || 'development';
 
-import { initDatabase, dropAuthTables, testConnection, closePool } from '../core/database/index.js';
+import { testConnection, closePool } from './index.js';
 import readline from 'readline';
-import { step, done, warn, fail } from '../shared/lib/logger.js';
+import { step, done, warn, fail } from '@zen/core/shared/logger';
 
-async function runCLI() {
-  const command = process.argv[2];
-
-  if (!command) {
+function printHelp() {
   console.log(`
 Zen Database CLI
 
@@ -33,22 +30,48 @@ Usage:
 Commands:
   init        Initialize database (create all required tables)
   test        Test database connection
-  drop        Drop all authentication tables (DANGER!)
+  drop        Drop all tables (DANGER!)
   help        Show this help message
 
 Example:
   npx zen-db init
   `);
+}
+
+/**
+ * Prompt the user for a confirmation answer.
+ * @param {string} question
+ * @returns {Promise<string>} The trimmed, lowercased answer
+ */
+function askConfirmation(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function runCLI() {
+  const command = process.argv[2];
+
+  if (!command) {
+    printHelp();
     process.exit(0);
   }
 
   try {
     switch (command) {
-      case 'init':
+      case 'init': {
         step('Initializing database...');
-        const result = await initDatabase();
-        done(`Created ${result.created.length} tables, skipped ${result.skipped.length} existing tables`);
+
+        const { initFeatures } = await import('../../features/init.js');
+        const featuresResult = await initFeatures();
+
+        done(`DB ready — ${featuresResult.created.length} tables created, ${featuresResult.skipped.length} skipped`);
         break;
+      }
 
       case 'test':
         step('Testing database connection...');
@@ -61,40 +84,22 @@ Example:
         }
         break;
 
-      case 'drop':
-        warn('This will delete all authentication tables!');
+      case 'drop': {
+        warn('This will delete all tables!');
         process.stdout.write('  Type "yes" to confirm or Ctrl+C to cancel...\n');
-
-        const rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout
-        });
-
-        rl.question('Confirm (yes/no): ', async (answer) => {
-          if (answer.toLowerCase() === 'yes') {
-            await dropAuthTables();
+        const answer = await askConfirmation('Confirm (yes/no): ');
+        if (answer === 'yes') {
+          const { dropFeatures } = await import('../../features/init.js');
+          await dropFeatures();
           done('Tables dropped successfully');
         } else {
           warn('Operation cancelled');
         }
-          rl.close();
-          process.exit(0);
-        });
-        return; // Don't close the process yet
+        break;
+      }
 
       case 'help':
-        console.log(`
-Zen Database CLI
-
-Commands:
-  init        Initialize database (create all required tables)
-  test        Test database connection
-  drop        Drop all authentication tables (DANGER!)
-  help        Show this help message
-
-Usage:
-  npx zen-db <command>
-        `);
+        printHelp();
         break;
 
       default:
@@ -103,12 +108,12 @@ Usage:
         process.exit(1);
     }
 
-    // Close the database connection pool
     await closePool();
     process.exit(0);
 
   } catch (error) {
     fail(`Error: ${error.message}`);
+    await closePool();
     process.exit(1);
   }
 }

src/core/database/crud.js

@@ -3,7 +3,31 @@
  * Provides convenient methods for Create, Read, Update, Delete operations
  */
 
-import { query, queryOne, queryAll } from './db.js';
+import { query, queryOne, queryAll } from './db.server.js';
+
+/**
+ * Filter a data object to only the columns present in allowedColumns.
+ * If allowedColumns is omitted or empty the original object is returned unchanged
+ * (backward-compatible default). When a whitelist IS provided, any key not in the
+ * list causes an immediate throw — mass-assignment of privileged columns (e.g.
+ * role, email_verified) is therefore impossible when callers supply a whitelist.
+ * @param {Object} data - Raw data object to filter
+ * @param {string[]|undefined} allowedColumns - Explicit column whitelist
+ * @returns {Object} Filtered data object
+ * @throws {Error} If data contains a column not present in allowedColumns
+ */
+function filterAllowedColumns(data, allowedColumns) {
+  if (!allowedColumns || allowedColumns.length === 0) return data;
+  const allowed = new Set(allowedColumns);
+  const filtered = {};
+  for (const key of Object.keys(data)) {
+    if (!allowed.has(key)) {
+      throw new Error(`Column "${key}" is not in the permitted columns list`);
+    }
+    filtered[key] = data[key];
+  }
+  return filtered;
+}
 
 /**
  * Validate and safely double-quote a single SQL identifier (table name, column name).
@@ -49,16 +73,39 @@ function safeOrderBy(orderBy) {
   return col;
 }
 
+/**
+ * Build a parameterized WHERE clause from a conditions object.
+ * @param {Object} conditions - Column/value pairs to match
+ * @param {number} startIndex - First $N placeholder index (default: 1)
+ * @returns {{ clause: string, values: Array }} SQL fragment and bound values
+ */
+function buildWhere(conditions, startIndex = 1) {
+  const values = [];
+  const clauses = Object.keys(conditions).map((key, index) => {
+    values.push(conditions[key]);
+    return `${safeIdentifier(key)} = $${startIndex + index}`;
+  });
+  return { clause: clauses.join(' AND '), values };
+}
+
 /**
  * Insert a new record into a table
  * @param {string} tableName - Name of the table
  * @param {Object} data - Object with column names as keys and values to insert
+ * @param {Object} [options={}] - Options
+ * @param {string[]} [options.allowedColumns] - Whitelist of permitted column names;
+ *   any key in data not present in this list throws immediately. Omit only when the
+ *   data object is already fully trusted and caller-constructed.
  * @returns {Promise<Object>} Inserted record with all fields
  */
-async function create(tableName, data) {
+async function create(tableName, data, { allowedColumns } = {}) {
+  if (!data || Object.keys(data).length === 0) {
+    throw new Error('create() requires at least one data field');
+  }
+  const safeData = filterAllowedColumns(data, allowedColumns);
   const safeTable = safeIdentifier(tableName);
-  const columns = Object.keys(data).map(safeIdentifier);
-  const values = Object.values(data);
+  const columns = Object.keys(safeData).map(safeIdentifier);
+  const values = Object.values(safeData);
   const placeholders = values.map((_, index) => `$${index + 1}`).join(', ');
 
   const sql = `
@@ -98,11 +145,9 @@ async function find(tableName, conditions = {}, options = {}) {
 
   // Build WHERE clause — column names are validated via safeIdentifier
   if (Object.keys(conditions).length > 0) {
-    const whereConditions = Object.keys(conditions).map((key, index) => {
-      values.push(conditions[key]);
-      return `${safeIdentifier(key)} = $${index + 1}`;
-    });
-    sql += ` WHERE ${whereConditions.join(' AND ')}`;
+    const { clause, values: whereValues } = buildWhere(conditions);
+    values.push(...whereValues);
+    sql += ` WHERE ${clause}`;
   }
 
   // Add ORDER BY — validated and quoted via safeOrderBy
@@ -149,14 +194,21 @@ async function findOne(tableName, conditions) {
  * @param {string} tableName - Name of the table
  * @param {number|string} id - ID of the record
  * @param {Object} data - Object with column names as keys and new values
- * @param {string} idColumn - Name of the ID column (default: 'id')
+ * @param {string} [idColumn='id'] - Name of the ID column
+ * @param {Object} [options={}] - Options
+ * @param {string[]} [options.allowedColumns] - Whitelist of permitted column names;
+ *   any key in data not in this list throws immediately.
  * @returns {Promise<Object|null>} Updated record or null if not found
  */
-async function updateById(tableName, id, data, idColumn = 'id') {
+async function updateById(tableName, id, data, idColumn = 'id', { allowedColumns } = {}) {
+  if (!data || Object.keys(data).length === 0) {
+    throw new Error('updateById() requires at least one data field');
+  }
+  const safeData = filterAllowedColumns(data, allowedColumns);
   const safeTable = safeIdentifier(tableName);
   const safeIdCol = safeIdentifier(idColumn);
-  const columns = Object.keys(data).map(safeIdentifier);
-  const values = Object.values(data);
+  const columns = Object.keys(safeData).map(safeIdentifier);
+  const values = Object.values(safeData);
 
   const setClause = columns.map((col, index) => `${col} = $${index + 1}`).join(', ');
 
@@ -176,34 +228,37 @@ async function updateById(tableName, id, data, idColumn = 'id') {
  * @param {string} tableName - Name of the table
  * @param {Object} conditions - Object with column names as keys and values to match
  * @param {Object} data - Object with column names as keys and new values
+ * @param {Object} [options={}] - Options
+ * @param {string[]} [options.allowedColumns] - Whitelist of permitted column names;
+ *   any key in data not in this list throws immediately.
  * @returns {Promise<Array>} Array of updated records
  */
-async function update(tableName, conditions, data) {
+async function update(tableName, conditions, data, { allowedColumns } = {}) {
   // Reject unconditional updates — a missing WHERE clause would silently mutate
   // every row in the table. Callers must always supply at least one condition.
   if (!conditions || Object.keys(conditions).length === 0) {
     throw new Error('update() requires at least one condition to prevent full-table mutation');
   }
+  if (!data || Object.keys(data).length === 0) {
+    throw new Error('update() requires at least one data field');
+  }
+  const safeData = filterAllowedColumns(data, allowedColumns);
   const safeTable = safeIdentifier(tableName);
-  const dataColumns = Object.keys(data).map(safeIdentifier);
-  const dataValues = Object.values(data);
+  const dataColumns = Object.keys(safeData).map(safeIdentifier);
+  const dataValues = Object.values(safeData);
 
   const setClause = dataColumns.map((col, index) => `${col} = $${index + 1}`).join(', ');
 
-  let paramIndex = dataValues.length + 1;
-  const whereConditions = Object.keys(conditions).map((key) => {
-    dataValues.push(conditions[key]);
-    return `${safeIdentifier(key)} = $${paramIndex++}`;
-  });
+  const { clause: whereClause, values: whereValues } = buildWhere(conditions, dataValues.length + 1);
 
   const sql = `
     UPDATE ${safeTable}
     SET ${setClause}
-    WHERE ${whereConditions.join(' AND ')}
+    WHERE ${whereClause}
     RETURNING *
   `;
 
-  const result = await query(sql, dataValues);
+  const result = await query(sql, [...dataValues, ...whereValues]);
   return result.rows;
 }
 
@@ -232,13 +287,8 @@ async function deleteWhere(tableName, conditions) {
   if (!conditions || Object.keys(conditions).length === 0) {
     throw new Error('deleteWhere() requires at least one condition to prevent full-table deletion');
   }
-  const values = [];
-  const whereConditions = Object.keys(conditions).map((key, index) => {
-    values.push(conditions[key]);
-    return `${safeIdentifier(key)} = $${index + 1}`;
-  });
-
-  const sql = `DELETE FROM ${safeIdentifier(tableName)} WHERE ${whereConditions.join(' AND ')} RETURNING *`;
+  const { clause, values } = buildWhere(conditions);
+  const sql = `DELETE FROM ${safeIdentifier(tableName)} WHERE ${clause} RETURNING *`;
   const result = await query(sql, values);
   return result.rowCount;
 }
@@ -251,14 +301,12 @@ async function deleteWhere(tableName, conditions) {
  */
 async function count(tableName, conditions = {}) {
   let sql = `SELECT COUNT(*) as count FROM ${safeIdentifier(tableName)}`;
-  const values = [];
+  let values = [];
 
   if (Object.keys(conditions).length > 0) {
-    const whereConditions = Object.keys(conditions).map((key, index) => {
-      values.push(conditions[key]);
-      return `${safeIdentifier(key)} = $${index + 1}`;
-    });
-    sql += ` WHERE ${whereConditions.join(' AND ')}`;
+    const { clause, values: whereValues } = buildWhere(conditions);
+    values = whereValues;
+    sql += ` WHERE ${clause}`;
   }
 
   const result = await queryOne(sql, values);
@@ -277,6 +325,9 @@ async function exists(tableName, conditions) {
 }
 
 export {
+  filterAllowedColumns,
+  safeIdentifier,
+  safeOrderBy,
   create,
   findById,
   find,

src/core/database/db.server.js

@@ -5,7 +5,23 @@
 
 import pkg from 'pg';
 const { Pool } = pkg;
-import { fail } from '../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
+
+/**
+ * Opaque error type thrown by all database operations.
+ * Exposes only a generic message and the pg error code (e.g. '23505') so
+ * callers can branch on well-known codes without receiving internal details
+ * such as table names, constraint names, or query fragments.
+ */
+export class DatabaseError extends Error {
+  /** @param {string} message - Safe, generic message */
+  /** @param {string|undefined} code - PostgreSQL error code (SQLSTATE), if any */
+  constructor(message, code) {
+    super(message);
+    this.name = 'DatabaseError';
+    if (code !== undefined) this.code = code;
+  }
+}
 
 let pool = null;
 
@@ -35,9 +51,16 @@ function getPool() {
 
     pool = new Pool({
       connectionString: databaseUrl,
-      // rejectUnauthorized MUST remain true in production to validate the server's
-      // TLS certificate chain and prevent man-in-the-middle attacks.
-      ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: true } : false,
+      // TLS policy:
+      //   production              → full TLS with server certificate verification
+      //   all other environments  → TLS encryption on, certificate verification off
+      //                             (prevents eavesdropping; allows self-signed certs in dev/ci)
+      //   ZEN_DB_SSL_DISABLED=true → opt-out of TLS entirely (local loopback only)
+      ssl: process.env.NODE_ENV === 'production'
+        ? { rejectUnauthorized: true }
+        : (process.env.ZEN_DB_SSL_DISABLED === 'true'
+            ? false
+            : { rejectUnauthorized: false }),
       max: 20, // Maximum number of clients in the pool
       idleTimeoutMillis: 30000, // Close idle clients after 30 seconds
       connectionTimeoutMillis: 2000, // Return an error after 2 seconds if connection could not be established
@@ -59,14 +82,14 @@ function getPool() {
  * @returns {Promise<Object>} Query result
  */
 async function query(sql, params = []) {
-  const client = getPool();
+  const dbPool = getPool(); // renamed — avoids shadowing module-level `pool`
 
   try {
-    const result = await client.query(sql, params);
+    const result = await dbPool.query(sql, params);
     return result;
   } catch (error) {
     fail(`DB query error: ${error.message}`);
-    throw error;
+    throw new DatabaseError('A database error occurred', error.code);
   }
 }
 
@@ -108,7 +131,7 @@ async function transaction(callback) {
   } catch (error) {
     await client.query('ROLLBACK');
     fail(`DB transaction error: ${error.message}`);
-    throw error;
+    throw new DatabaseError('A database transaction error occurred', error.code);
   } finally {
     client.release();
   }
@@ -139,6 +162,23 @@ async function testConnection() {
   }
 }
 
+/**
+ * Check if a table exists in the database
+ * @param {string} tableName - Name of the table to check
+ * @returns {Promise<boolean>} True if table exists, false otherwise
+ */
+async function tableExists(tableName) {
+  const result = await query(
+    `SELECT EXISTS (
+      SELECT FROM information_schema.tables
+      WHERE table_schema = 'public'
+      AND table_name = $1
+    )`,
+    [tableName]
+  );
+  return result.rows[0].exists;
+}
+
 export {
   query,
   queryOne,
@@ -146,6 +186,7 @@ export {
   transaction,
   getPool,
   closePool,
-  testConnection
+  testConnection,
+  tableExists
 };
 

src/core/database/index.js

@@ -5,17 +5,22 @@
 
 // Core database functions
 export {
+  DatabaseError,
   query,
   queryOne,
   queryAll,
   transaction,
   getPool,
   closePool,
-  testConnection
-} from './db.js';
+  testConnection,
+  tableExists
+} from './db.server.js';
 
 // CRUD helper functions
 export {
+  filterAllowedColumns,
+  safeIdentifier,
+  safeOrderBy,
   create,
   findById,
   find,
@@ -27,12 +32,3 @@ export {
   count,
   exists
 } from './crud.js';
-
-// Database initialization
-export {
-  initDatabase,
-  createAuthTables,
-  tableExists,
-  dropAuthTables
-} from './init.js';
-

src/core/database/init.js

@@ -1,185 +0,0 @@
-/**
- * Database Initialization
- * Creates required tables if they don't exist
- */
-
-import { query } from './db.js';
-import { step, done, warn, fail, info } from '../../shared/lib/logger.js';
-
-/**
- * Check if a table exists in the database
- * @param {string} tableName - Name of the table to check
- * @returns {Promise<boolean>} True if table exists, false otherwise
- */
-async function tableExists(tableName) {
-  const result = await query(
-    `SELECT EXISTS (
-      SELECT FROM information_schema.tables 
-      WHERE table_schema = 'public' 
-      AND table_name = $1
-    )`,
-    [tableName]
-  );
-  return result.rows[0].exists;
-}
-
-/**
- * Create authentication tables
- * @returns {Promise<void>}
- */
-async function createAuthTables() {
-  const tables = [
-    {
-      name: 'zen_auth_users',
-      sql: `
-        CREATE TABLE zen_auth_users (
-          id text NOT NULL PRIMARY KEY,
-          name text NOT NULL,
-          email text NOT NULL UNIQUE,
-          email_verified boolean NOT NULL DEFAULT false,
-          image text,
-          created_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
-          updated_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
-          role text DEFAULT 'user' CHECK (role IN ('admin', 'user'))
-        )
-      `
-    },
-    {
-      name: 'zen_auth_sessions',
-      sql: `
-        CREATE TABLE zen_auth_sessions (
-          id text NOT NULL PRIMARY KEY,
-          expires_at timestamptz NOT NULL,
-          token text NOT NULL UNIQUE,
-          created_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
-          updated_at timestamptz NOT NULL,
-          ip_address text,
-          user_agent text,
-          user_id text NOT NULL REFERENCES zen_auth_users (id) ON DELETE CASCADE
-        )
-      `
-    },
-    {
-      name: 'zen_auth_accounts',
-      sql: `
-        CREATE TABLE zen_auth_accounts (
-          id text NOT NULL PRIMARY KEY,
-          account_id text NOT NULL,
-          provider_id text NOT NULL,
-          user_id text NOT NULL REFERENCES zen_auth_users (id) ON DELETE CASCADE,
-          access_token text,
-          refresh_token text,
-          id_token text,
-          access_token_expires_at timestamptz,
-          refresh_token_expires_at timestamptz,
-          scope text,
-          password text,
-          created_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
-          updated_at timestamptz NOT NULL
-        )
-      `
-    },
-    {
-      name: 'zen_auth_verifications',
-      sql: `
-        CREATE TABLE zen_auth_verifications (
-          id text NOT NULL PRIMARY KEY,
-          identifier text NOT NULL,
-          value text NOT NULL,
-          token text NOT NULL,
-          expires_at timestamptz NOT NULL,
-          created_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL,
-          updated_at timestamptz DEFAULT CURRENT_TIMESTAMP NOT NULL
-        )
-      `
-    }
-  ];
-
-  const created = [];
-  const skipped = [];
-
-  for (const table of tables) {
-    const exists = await tableExists(table.name);
-    
-    if (!exists) {
-      await query(table.sql);
-      created.push(table.name);
-      done(`Created table: ${table.name}`);
-    } else {
-      skipped.push(table.name);
-      info(`Table already exists: ${table.name}`);
-    }
-  }
-
-  return {
-    created,
-    skipped,
-    success: true
-  };
-}
-
-/**
- * Initialize the database with all required tables
- * @returns {Promise<Object>} Result object with created and skipped tables
- */
-async function initDatabase() {
-  step('Initializing Zen database...');
-  
-  try {
-    const authResult = await createAuthTables();
-    
-    // Initialize modules
-    let modulesResult = { created: [], skipped: [] };
-    try {
-      const { initModules } = await import('../../modules/init.js');
-      modulesResult = await initModules();
-    } catch (error) {
-      // Modules might not be available or enabled
-      info('No modules to initialize or modules not available');
-    }
-    
-    done(`DB ready — auth: ${authResult.created.length} created, modules: ${modulesResult.created.length} created, ${authResult.skipped.length + modulesResult.skipped.length} skipped`);
-    
-    return {
-      created: [...authResult.created, ...modulesResult.created],
-      skipped: [...authResult.skipped, ...modulesResult.skipped],
-      success: true
-    };
-  } catch (error) {
-    fail(`DB initialization failed: ${error.message}`);
-    throw error;
-  }
-}
-
-/**
- * Drop all Zen authentication tables (use with caution!)
- * @returns {Promise<void>}
- */
-async function dropAuthTables() {
-  const tables = [
-    'zen_auth_verifications',
-    'zen_auth_accounts',
-    'zen_auth_sessions',
-    'zen_auth_users'
-  ];
-
-  warn('Dropping all Zen authentication tables...');
-  
-  for (const tableName of tables) {
-    const exists = await tableExists(tableName);
-    if (exists) {
-      await query(`DROP TABLE IF EXISTS "${tableName}" CASCADE`);
-      done(`Dropped table: ${tableName}`);
-    }
-  }
-  
-  done('All authentication tables dropped');
-}
-
-export {
-  initDatabase,
-  createAuthTables,
-  tableExists,
-  dropAuthTables
-};
-

src/core/email/README.md

@@ -0,0 +1,155 @@
+# Email Framework
+
+Ce répertoire fournit un **wrapper autour de [Resend](https://resend.com)** pour l'envoi d'emails, ainsi qu'un composant de mise en page React Email réutilisable. Il ne connaît aucun template métier — les features créent leurs propres templates et utilisent ce module pour l'envoi.
+
+---
+
+## Structure
+
+```
+src/core/email/
+├── index.js              sendEmail, sendBatchEmails
+└── templates/
+    ├── index.js           re-export
+    └── BaseLayout.js      composant de mise en page React Email
+```
+
+---
+
+## Import
+
+```js
+import { sendEmail, sendBatchEmails } from '@zen/core/email';
+import { BaseLayout } from '@zen/core/email/templates';
+```
+
+---
+
+## Variables d'environnement
+
+| Variable | Obligatoire | Description |
+|----------|-------------|-------------|
+| `ZEN_EMAIL_RESEND_APIKEY` | Oui | Clé API Resend |
+| `ZEN_EMAIL_FROM_ADDRESS` | Oui | Adresse expéditeur par défaut |
+| `ZEN_EMAIL_FROM_NAME` | Non | Nom affiché de l'expéditeur |
+| `ZEN_EMAIL_LOGO` | Non | URL du logo affiché dans `BaseLayout` |
+| `ZEN_EMAIL_LOGO_URL` | Non | URL de destination du lien autour du logo |
+| `ZEN_SUPPORT_EMAIL` | Non | Email affiché dans le footer si `supportSection` est activé |
+| `ZEN_NAME` | Non | Nom de l'application (fallback du nom affiché dans `BaseLayout`) |
+
+---
+
+## API
+
+### `sendEmail(email)`
+
+Envoie un email via Resend. Retourne `{ success, data, error }`.
+
+```js
+const result = await sendEmail({
+  to: 'user@example.com',
+  subject: 'Bienvenue',
+  html: '<p>Bonjour !</p>',
+});
+
+if (!result.success) {
+  console.error(result.error);
+}
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `to` | `string \| string[]` | Destinataire(s) |
+| `subject` | `string` | Objet de l'email |
+| `html` | `string` | Corps HTML |
+| `text` | `string` | Corps texte brut (optionnel) |
+| `from` | `string` | Adresse expéditeur (défaut : `ZEN_EMAIL_FROM_ADDRESS`) |
+| `fromName` | `string` | Nom expéditeur (défaut : `ZEN_EMAIL_FROM_NAME`) |
+| `replyTo` | `string` | Adresse de réponse (optionnel) |
+| `attachments` | `object[]` | Pièces jointes Resend (optionnel) |
+| `tags` | `object[]` | Tags Resend (optionnel) |
+
+---
+
+### `sendBatchEmails(emails)`
+
+Envoie plusieurs emails en une seule requête batch Resend. Retourne `{ success, data, error }`.
+
+```js
+await sendBatchEmails([
+  { to: 'a@example.com', subject: 'Sujet A', html: '<p>A</p>' },
+  { to: 'b@example.com', subject: 'Sujet B', html: '<p>B</p>' },
+]);
+```
+
+Chaque objet du tableau accepte les mêmes paramètres que `sendEmail`.
+
+---
+
+## BaseLayout
+
+Composant React Email (`@react-email/components`) qui fournit une structure cohérente : logo ou nom de l'app, titre optionnel, contenu, footer avec copyright et lien support.
+
+```jsx
+import { render } from '@react-email/render';
+import { BaseLayout } from '@zen/core/email/templates';
+
+const html = await render(
+  <BaseLayout
+    preview="Votre commande est confirmée"
+    title="Commande confirmée"
+    supportSection
+  >
+    <Text>Merci pour votre achat.</Text>
+  </BaseLayout>
+);
+
+await sendEmail({ to: 'user@example.com', subject: 'Commande confirmée', html });
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `preview` | `string` | Texte de prévisualisation (snippet email) |
+| `title` | `string` | Titre affiché en haut du corps |
+| `children` | `ReactNode` | Contenu de l'email |
+| `companyName` | `string` | Nom affiché si pas de logo (défaut : `ZEN_NAME` ou `ZEN`) |
+| `logoURL` | `string` | URL du logo (défaut : `ZEN_EMAIL_LOGO`) |
+| `supportSection` | `boolean` | Afficher le lien support dans le footer (défaut : `false`) |
+| `supportEmail` | `string` | Email support (défaut : `ZEN_SUPPORT_EMAIL`) |
+
+---
+
+## Créer un template depuis une feature
+
+Les templates vivent **avec leur feature**, pas dans ce répertoire.
+
+```jsx
+// src/features/auth/emails/WelcomeEmail.js
+import { BaseLayout } from '@zen/core/email/templates';
+import { Text, Button } from '@react-email/components';
+
+export const WelcomeEmail = ({ name, loginUrl }) => (
+  <BaseLayout preview={`Bienvenue, ${name}`} title="Bienvenue !">
+    <Text>Bonjour {name}, votre compte est prêt.</Text>
+    <Button href={loginUrl}>Se connecter</Button>
+  </BaseLayout>
+);
+```
+
+```js
+// src/features/auth/emails/sendWelcome.js
+import { render } from '@react-email/render';
+import { sendEmail } from '@zen/core/email';
+import { WelcomeEmail } from './WelcomeEmail.js';
+
+export async function sendWelcomeEmail({ to, name, loginUrl }) {
+  const html = await render(<WelcomeEmail name={name} loginUrl={loginUrl} />);
+  return sendEmail({ to, subject: 'Bienvenue !', html });
+}
+```
+
+---
+
+## Gestion des erreurs
+
+`sendEmail` et `sendBatchEmails` ne lèvent jamais d'exception — toute erreur est capturée, loguée via `fail()`, et retournée dans `{ success: false, error }`. L'appelant vérifie `result.success`.

src/core/email/index.js

@@ -1,67 +1,27 @@
-/**
- * Email Utility using Resend
- * Centralized email sending functionality for the entire package
- */
-
 import { Resend } from 'resend';
-import { done, fail, info } from '../../shared/lib/logger.js';
+import { done, fail, info } from '@zen/core/shared/logger';
 
-/**
- * Initialize Resend client
- */
 let resendClient = null;
 
 function getResendClient() {
   if (!resendClient) {
     const apiKey = process.env.ZEN_EMAIL_RESEND_APIKEY;
-    if (!apiKey) {
-      throw new Error('ZEN_EMAIL_RESEND_APIKEY environment variable is not set');
-    }
+    if (!apiKey) throw new Error('ZEN_EMAIL_RESEND_APIKEY environment variable is not set');
     resendClient = new Resend(apiKey);
   }
   return resendClient;
 }
 
-/**
- * Format sender address with name if available
- * @param {string} email - Email address
- * @param {string} name - Sender name (optional)
- * @returns {string} Formatted sender address
- */
-function formatSenderAddress(email, name) {
-  if (name && name.trim()) {
-    return `${name.trim()} <${email}>`;
-  }
-  return email;
+function resolveFrom(from, fromName) {
+  const address = from || process.env.ZEN_EMAIL_FROM_ADDRESS;
+  if (!address) throw new Error('ZEN_EMAIL_FROM_ADDRESS environment variable is not set');
+  const name = fromName || process.env.ZEN_EMAIL_FROM_NAME;
+  return name?.trim() ? `${name.trim()} <${address}>` : address;
 }
 
-/**
- * Send an email using Resend
- * @param {Object} options - Email options
- * @param {string} options.to - Recipient email address
- * @param {string} options.subject - Email subject
- * @param {string} options.html - HTML content of the email
- * @param {string} options.text - Plain text content of the email (optional)
- * @param {string} options.from - Sender email address (optional, defaults to ZEN_EMAIL_FROM_ADDRESS)
- * @param {string} options.fromName - Sender name (optional, defaults to ZEN_EMAIL_FROM_NAME)
- * @param {string} options.replyTo - Reply-to email address (optional)
- * @param {Array} options.attachments - Email attachments (optional)
- * @param {Object} options.tags - Email tags for tracking (optional)
- * @returns {Promise<Object>} Resend response
- */
-async function sendEmail({ to, subject, html, text, from, fromName, replyTo, attachments, tags }) {
-  try {
-    const resend = getResendClient();
-    
-    // Default from address and name
-    const fromAddress = from || process.env.ZEN_EMAIL_FROM_ADDRESS || 'noreply@example.com';
-    const senderName = fromName || process.env.ZEN_EMAIL_FROM_NAME;
-    
-    // Format sender with name if available
-    const formattedFrom = formatSenderAddress(fromAddress, senderName);
-    
-    const emailData = {
-      from: formattedFrom,
+function buildPayload({ to, subject, html, text, from, fromName, replyTo, attachments, tags }) {
+  return {
+    from: resolveFrom(from, fromName),
     to,
     subject,
     html,
@@ -70,142 +30,36 @@ async function sendEmail({ to, subject, html, text, from, fromName, replyTo, att
     ...(attachments && { attachments }),
     ...(tags && { tags })
   };
+}
 
-    const response = await resend.emails.send(emailData);
-    
-    // Resend returns { data: { id: "..." }, error: null } or { data: null, error: { message: "..." } }
+async function sendEmail(email) {
+  try {
+    const response = await getResendClient().emails.send(buildPayload(email));
     if (response.error) {
       fail(`Email Resend error: ${response.error.message || response.error}`);
-      return {
-        success: false,
-        data: null,
-        error: response.error.message || 'Failed to send email'
-      };
+      return { success: false, data: null, error: response.error.message || 'Failed to send email' };
     }
-    
-    const emailId = response.data?.id || response.id;
-    info(`Email sent to ${to} — ID: ${emailId}`);
-    
-    return {
-      success: true,
-      data: response.data || response,
-      error: null
-    };
+    info(`Email sent to ${email.to} — ID: ${response.data?.id}`);
+    return { success: true, data: response.data, error: null };
   } catch (error) {
     fail(`Email send failed: ${error.message}`);
-    return {
-      success: false,
-      data: null,
-      error: error.message
-    };
+    return { success: false, data: null, error: error.message };
   }
 }
 
-/**
- * Send an authentication-related email
- * Uses default ZEN_EMAIL_FROM_ADDRESS and ZEN_EMAIL_FROM_NAME
- * @param {Object} options - Email options
- * @param {string} options.to - Recipient email address
- * @param {string} options.subject - Email subject
- * @param {string} options.html - HTML content of the email
- * @param {string} options.text - Plain text content of the email (optional)
- * @param {string} options.replyTo - Reply-to email address (optional)
- * @returns {Promise<Object>} Resend response
- */
-async function sendAuthEmail({ to, subject, html, text, replyTo }) {
-  return sendEmail({
-    to,
-    subject,
-    html,
-    text,
-    replyTo
-  });
-}
-
-/**
- * Send an application-related email
- * Uses default ZEN_EMAIL_FROM_ADDRESS and ZEN_EMAIL_FROM_NAME
- * @param {Object} options - Email options
- * @param {string} options.to - Recipient email address
- * @param {string} options.subject - Email subject
- * @param {string} options.html - HTML content of the email
- * @param {string} options.text - Plain text content of the email (optional)
- * @param {string} options.replyTo - Reply-to email address (optional)
- * @param {Array} options.attachments - Email attachments (optional)
- * @param {Object} options.tags - Email tags for tracking (optional)
- * @returns {Promise<Object>} Resend response
- */
-async function sendAppEmail({ to, subject, html, text, replyTo, attachments, tags }) {
-  return sendEmail({
-    to,
-    subject,
-    html,
-    text,
-    replyTo,
-    attachments,
-    tags
-  });
-}
-
-/**
- * Send a batch of emails
- * @param {Array<Object>} emails - Array of email objects
- * @returns {Promise<Array<Object>>} Array of Resend responses
- */
 async function sendBatchEmails(emails) {
   try {
-    const resend = getResendClient();
-    
-    const emailsData = emails.map(email => {
-      const fromAddress = email.from || process.env.ZEN_EMAIL_FROM_ADDRESS || 'noreply@example.com';
-      const fromName = email.fromName || process.env.ZEN_EMAIL_FROM_NAME;
-      const formattedFrom = formatSenderAddress(fromAddress, fromName);
-      
-      return {
-        from: formattedFrom,
-        to: email.to,
-        subject: email.subject,
-        html: email.html,
-        ...(email.text && { text: email.text }),
-        ...(email.replyTo && { reply_to: email.replyTo }),
-        ...(email.attachments && { attachments: email.attachments }),
-        ...(email.tags && { tags: email.tags })
-      };
-    });
-    
-    const response = await resend.batch.send(emailsData);
-    
-    // Handle Resend error response
+    const response = await getResendClient().batch.send(emails.map(buildPayload));
     if (response.error) {
       fail(`Email batch Resend error: ${response.error.message || response.error}`);
-      return {
-        success: false,
-        data: null,
-        error: response.error.message || 'Failed to send batch emails'
-      };
+      return { success: false, data: null, error: response.error.message || 'Failed to send batch emails' };
     }
-    
     done(`Email batch of ${emails.length} sent`);
-    
-    return {
-      success: true,
-      data: response.data || response,
-      error: null
-    };
+    return { success: true, data: response.data, error: null };
   } catch (error) {
     fail(`Email batch send failed: ${error.message}`);
-    return {
-      success: false,
-      data: null,
-      error: error.message
-    };
+    return { success: false, data: null, error: error.message };
   }
 }
 
-export {
-  sendEmail,
-  sendAuthEmail,
-  sendAppEmail,
-  sendBatchEmails
-};
-
+export { sendEmail, sendBatchEmails };

src/core/email/templates/BaseLayout.js

@@ -25,11 +25,12 @@ export const BaseLayout = ({
 	companyName,
 	logoURL,
 	supportSection = false,
-	supportEmail = 'support@zenya.test'
+	supportEmail
 }) => {
 	const appName = companyName || process.env.ZEN_NAME || 'ZEN';
 	const logoSrc = logoURL || process.env.ZEN_EMAIL_LOGO || null;
 	const logoHref = process.env.ZEN_EMAIL_LOGO_URL || null;
+	const resolvedSupportEmail = supportEmail || process.env.ZEN_SUPPORT_EMAIL;
 	const currentYear = new Date().getFullYear();
 
 	return (
@@ -68,11 +69,11 @@ export const BaseLayout = ({
 
 						<Text className="text-[12px] leading-[20px] text-neutral-400 m-0">
 							© {currentYear} — {appName}. Tous droits réservés.
-							{supportSection && (
+							{supportSection && resolvedSupportEmail && (
 								<>
 									{' · '}
-									<Link href={`mailto:${supportEmail}`} className="text-neutral-400 underline">
-										{supportEmail}
+									<Link href={`mailto:${resolvedSupportEmail}`} className="text-neutral-400 underline">
+										{resolvedSupportEmail}
 									</Link>
 								</>
 							)}

src/core/email/templates/PasswordChangedEmail.jsx

@@ -1,41 +0,0 @@
-/**
- * Password Changed Confirmation Email Template
- */
-
-import { Section, Text } from "@react-email/components";
-import { BaseLayout } from "./BaseLayout";
-
-export const PasswordChangedEmail = ({ 
-  email, 
-  companyName 
-}) => {
-  const appName = companyName || process.env.ZEN_NAME || 'ZEN';
-  const supportEmail = process.env.ZEN_SUPPORT_EMAIL || 'support@zenya.test';
-  
-  return (
-    <BaseLayout
-      preview={`Votre mot de passe a été modifié – ${appName}`}
-      title="Mot de passe modifié"
-      companyName={companyName}
-      supportSection={true}
-      supportEmail={supportEmail}
-    >
-      <Text className="text-[14px] leading-[24px] text-neutral-600 mt-[4px] mb-[24px]">
-        Ceci confirme que le mot de passe de votre compte <span className="font-medium text-neutral-900">{appName}</span> a bien été modifié.
-      </Text>
-
-      <Section style={{ border: '1px solid #E5E5E5' }} className="bg-neutral-100 rounded-[12px] p-[20px] my-[24px]">
-        <Text className="text-[12px] font-medium text-neutral-400 m-0 mb-[4px] uppercase tracking-wider">
-          Compte
-        </Text>
-        <Text className="text-[14px] font-medium text-neutral-900 m-0">
-          {email}
-        </Text>
-      </Section>
-
-      <Text className="text-[12px] leading-[20px] text-neutral-400 m-0">
-        Si vous n'êtes pas à l'origine de cette modification, contactez immédiatement notre équipe de support.
-      </Text>
-    </BaseLayout>
-  );
-};

src/core/email/templates/PasswordResetEmail.jsx

@@ -1,49 +0,0 @@
-/**
- * Password Reset Email Template
- */
-
-import { Button, Section, Text, Link } from "@react-email/components";
-import { BaseLayout } from "./BaseLayout";
-
-export const PasswordResetEmail = ({ 
-  email, 
-  resetUrl, 
-  companyName 
-}) => {
-  const appName = companyName || process.env.ZEN_NAME || 'ZEN';
-  const supportEmail = process.env.ZEN_SUPPORT_EMAIL || 'support@zenya.test';
-  
-  return (
-    <BaseLayout
-      preview={`Réinitialisez votre mot de passe pour ${appName}`}
-      title="Réinitialisation du mot de passe"
-      companyName={companyName}
-      supportSection={true}
-      supportEmail={supportEmail}
-    >
-      <Text className="text-[14px] leading-[24px] text-neutral-600 mt-[4px] mb-[24px]">
-        Nous avons reçu une demande de réinitialisation du mot de passe pour votre compte <span className="font-medium text-neutral-900">{appName}</span>. Cliquez sur le bouton ci-dessous pour en choisir un nouveau.
-      </Text>
-
-      <Section className="mt-[28px] mb-[32px]">
-        <Button
-          href={resetUrl}
-          className="bg-neutral-900 rounded-[8px] text-white font-medium px-[20px] py-[11px] no-underline text-[13px]"
-        >
-          Réinitialiser le mot de passe
-        </Button>
-      </Section>
-
-      <Text className="text-[12px] leading-[20px] text-neutral-400 m-0">
-        Ce lien expire dans 1 heure. Si vous n'êtes pas à l'origine de cette demande, ignorez ce message — votre mot de passe ne sera pas modifié.
-      </Text>
-
-      <Text className="text-[12px] leading-[20px] text-neutral-400 m-0 mt-[8px]">
-        Lien :{' '}
-        <Link href={resetUrl} className="text-neutral-400 underline break-all">
-          {resetUrl}
-        </Link>
-      </Text>
-    </BaseLayout>
-  );
-};

src/core/email/templates/VerificationEmail.jsx

@@ -1,49 +0,0 @@
-/**
- * Email Verification Template
- */
-
-import { Button, Section, Text, Link } from "@react-email/components";
-import { BaseLayout } from "./BaseLayout";
-
-export const VerificationEmail = ({ 
-  email, 
-  verificationUrl, 
-  companyName 
-}) => {
-  const appName = companyName || process.env.ZEN_NAME || 'ZEN';
-  const supportEmail = process.env.ZEN_SUPPORT_EMAIL || 'support@zenya.test';
-  
-  return (
-    <BaseLayout
-      preview={`Confirmez votre adresse courriel pour ${appName}`}
-      title="Confirmez votre adresse courriel"
-      companyName={companyName}
-      supportSection={true}
-      supportEmail={supportEmail}
-    >
-      <Text className="text-[14px] leading-[24px] text-neutral-600 mt-[4px] mb-[24px]">
-        Merci de vous être inscrit sur <span className="font-medium text-neutral-900">{appName}</span>. Cliquez sur le bouton ci-dessous pour confirmer votre adresse courriel.
-      </Text>
-
-      <Section className="mt-[28px] mb-[32px]">
-        <Button
-          href={verificationUrl}
-          className="bg-neutral-900 rounded-[8px] text-white font-medium px-[20px] py-[11px] no-underline text-[13px]"
-        >
-          Confirmer mon courriel
-        </Button>
-      </Section>
-
-      <Text className="text-[12px] leading-[20px] text-neutral-400 m-0">
-        Ce lien expire dans 24 heures. Si vous n'avez pas créé de compte, ignorez ce message.
-      </Text>
-
-      <Text className="text-[12px] leading-[20px] text-neutral-400 m-0 mt-[8px]">
-        Lien :{' '}
-        <Link href={verificationUrl} className="text-neutral-400 underline break-all">
-          {verificationUrl}
-        </Link>
-      </Text>
-    </BaseLayout>
-  );
-};

src/core/email/templates/index.js

@@ -1,71 +1 @@
-/**
- * Email Templates
- * Export all email templates and render functions
- */
-
-import { render } from '@react-email/components';
-import { VerificationEmail } from './VerificationEmail.jsx';
-import { PasswordResetEmail } from './PasswordResetEmail.jsx';
-import { PasswordChangedEmail } from './PasswordChangedEmail.jsx';
-
-// Export JSX components
-export { VerificationEmail } from './VerificationEmail.jsx';
-export { PasswordResetEmail } from './PasswordResetEmail.jsx';
-export { PasswordChangedEmail } from './PasswordChangedEmail.jsx';
-export { BaseLayout } from './BaseLayout.jsx';
-
-/**
- * Render verification email to HTML
- * @param {string} verificationUrl - The verification URL
- * @param {string} email - User's email address
- * @param {string} companyName - Company name (optional)
- * @returns {Promise<string>} Rendered HTML
- */
-export async function renderVerificationEmail(verificationUrl, email, companyName) {
-  return await render(
-    <VerificationEmail 
-      email={email}
-      verificationUrl={verificationUrl}
-      companyName={companyName}
-    />
-  );
-}
-
-/**
- * Render password reset email to HTML
- * @param {string} resetUrl - The password reset URL
- * @param {string} email - User's email address
- * @param {string} companyName - Company name (optional)
- * @returns {Promise<string>} Rendered HTML
- */
-export async function renderPasswordResetEmail(resetUrl, email, companyName) {
-  return await render(
-    <PasswordResetEmail 
-      email={email}
-      resetUrl={resetUrl}
-      companyName={companyName}
-    />
-  );
-}
-
-/**
- * Render password changed email to HTML
- * @param {string} email - User's email address
- * @param {string} companyName - Company name (optional)
- * @returns {Promise<string>} Rendered HTML
- */
-export async function renderPasswordChangedEmail(email, companyName) {
-  return await render(
-    <PasswordChangedEmail 
-      email={email}
-      companyName={companyName}
-    />
-  );
-}
-
-// Legacy exports for backward compatibility
-export const getVerificationEmailTemplate = renderVerificationEmail;
-export const getPasswordResetTemplate = renderPasswordResetEmail;
-export const getPasswordChangedTemplate = renderPasswordChangedEmail;
-
-
+export { BaseLayout } from './BaseLayout.js';

src/core/modules/README.md

@@ -0,0 +1,47 @@
+# Modules
+
+Registre runtime des modules `@zen/module-*` activés dans le projet consommateur. Voir [docs/MODULES.md](../../../docs/MODULES.md) pour le guide complet de création d'un module.
+
+## Architecture
+
+Les modules sont activés via un **manifeste statique** généré dans le projet consommateur (`app/.zen/modules.generated.js`). Le manifeste fait des `import * as ...` statiques pour chaque package et appelle `register()` au top level. Importé par `instrumentation.js` (serveur) et `app/layout.js` (client), il rend l'arbre d'imports du module visible aux deux bundles Next.js — Turbopack et Webpack le bundlent comme n'importe quel autre fichier source.
+
+Le manifeste est régénéré par `npx zen-modules sync` (typiquement depuis le `postinstall` + les scripts `dev` / `build` du projet).
+
+## API
+
+```js
+import {
+  registerModules,
+  registerModule,
+  getRegisteredModules,
+  getRegisteredModule,
+  findInstalledModuleNames,
+  validateModuleEnvVars,
+} from '@zen/core/modules';
+```
+
+| Fonction | Usage |
+|----------|-------|
+| `registerModules(modules)` | Appelée par `initializeZen({ modules })`. Peuple le registre interne à partir du manifeste. |
+| `registerModule(mod)` | Bas niveau — utilisé par `registerModules`. |
+| `getRegisteredModules()` | Retourne tous les modules connus (utilisé par `zen-db init` et l'env validation). |
+| `findInstalledModuleNames({ cwd })` | Scan readonly du `package.json` du projet — utilisé par le CLI `zen-modules sync`. |
+| `validateModuleEnvVars(modules)` | Logge un warning par variable d'env requise absente. |
+
+## Forme attendue d'un module
+
+Le point d'entrée d'un package `@zen/module-X` doit exporter :
+
+| Export | Type | Obligatoire |
+|--------|------|-------------|
+| `manifest` | `{ name, version, permissions?, envVars? }` | oui |
+| `register` | `() => void \| Promise<void>` | oui |
+| `createTables` | `async () => { created?, skipped? }` | si le module a des tables |
+| `dropTables` | `async () => void` | si le module a des tables |
+
+Le code du module doit être pré-compilé avant publication (transformation JSX, voir [docs/MODULES.md](../../../docs/MODULES.md)).
+
+## CLI
+
+`npx zen-modules sync` — régénère `app/.zen/modules.generated.js`. Idempotent : pas d'écriture si le contenu est inchangé.

src/core/modules/cli.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Zen Modules CLI
+ *
+ * Génère `app/.zen/modules.generated.js` à partir des dépendances `@zen/module-*`
+ * détectées dans le `package.json` du projet consommateur. Le fichier généré est
+ * ensuite importé par `instrumentation.js` (côté serveur) et par `app/layout.js`
+ * (côté client) pour rendre les modules visibles aux deux bundles Next.js.
+ *
+ * Usage : `npx zen-modules sync`
+ *
+ * Conçu pour être appelé depuis postinstall + dev/build du projet consommateur.
+ * Idempotent : si le contenu généré est identique au fichier existant, aucune
+ * écriture n'est effectuée.
+ */
+
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { step, done, warn, fail } from '@zen/core/shared/logger';
+import { findInstalledModuleNames, moduleHasClientEntry } from './discover.server.js';
+
+const OUTPUT_SERVER = 'app/.zen/modules.generated.js';
+const OUTPUT_CLIENT = 'app/.zen/modules.client.js';
+
+function safeIdentifier(name, idx) {
+  // `@zen/module-posts` → `m0_zen_module_posts`
+  const cleaned = name.replace(/[^a-zA-Z0-9]/g, '_');
+  return `m${idx}_${cleaned}`;
+}
+
+function renderServerManifest(names) {
+  const header = '// AUTO-GÉNÉRÉ par `npx zen-modules sync` — ne pas modifier à la main.\n';
+
+  if (names.length === 0) {
+    return header + '\nexport const modules = [];\n';
+  }
+
+  const imports = names
+    .map((name, i) => `import * as ${safeIdentifier(name, i)} from '${name}';`)
+    .join('\n');
+
+  const entries = names
+    .map((name, i) => `  { name: '${name}', exports: ${safeIdentifier(name, i)} },`)
+    .join('\n');
+
+  return [
+    header,
+    imports,
+    '',
+    'export const modules = [',
+    entries,
+    '];',
+    '',
+    '// Top-level await : déclenche register() de chaque module au moment de l\'import',
+    '// côté serveur. instrumentation.js importe ce fichier au boot.',
+    'await Promise.all(modules.map(m => m.exports.register?.()));',
+    '',
+  ].join('\n');
+}
+
+function renderClientManifest(clientNames) {
+  // Exporte un Component React `ZenModulesClient` que le layout consommateur doit
+  // RENDRE dans son tree (`<ZenModulesClient />`). C'est le seul moyen fiable
+  // sous Next.js 15+/Turbopack pour garantir que les side-effects top-level
+  // (registerPage, registerWidget) s'exécutent côté browser. Un simple
+  // `import './.zen/modules.client.js'` dans un Server Component met bien le
+  // fichier dans le bundle client mais n'en exécute jamais le code top-level
+  // — la transformation 'use client' s'applique aux Components, pas aux
+  // side-effect imports orphelins.
+  //
+  // Importe `@zen/module-X/client` (sous-entrée 'use client') et NON le main
+  // entry du module — le main entry tire createTables/registerApiRoutes/etc.
+  // qui dépendent de pg/fs/net et ne peuvent pas être bundlés pour le browser.
+  const header = [
+    '// AUTO-GÉNÉRÉ par `npx zen-modules sync` — ne pas modifier à la main.',
+    "'use client';",
+    '',
+  ].join('\n');
+
+  const body = [
+    'export default function ZenModulesClient() {',
+    '  return null;',
+    '}',
+    '',
+  ].join('\n');
+
+  if (clientNames.length === 0) return header + '\n' + body;
+
+  const imports = clientNames.map(name => `import '${name}/client';`).join('\n');
+  return [header, imports, '', body].join('\n');
+}
+
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+async function writeIfChanged(path, contents) {
+  const prev = await readIfExists(path);
+  if (prev === contents) return false;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents, 'utf-8');
+  return true;
+}
+
+async function syncCommand({ cwd = process.cwd() } = {}) {
+  const names = await findInstalledModuleNames({ cwd });
+  const clientNames = [];
+  for (const name of names) {
+    if (await moduleHasClientEntry(name, cwd)) clientNames.push(name);
+  }
+
+  const serverCount = `(${names.length} module${names.length === 1 ? '' : 's'})`;
+  const clientCount = `(${clientNames.length} client entr${clientNames.length === 1 ? 'y' : 'ies'})`;
+
+  const serverPath = resolve(cwd, OUTPUT_SERVER);
+  const clientPath = resolve(cwd, OUTPUT_CLIENT);
+
+  const wroteServer = await writeIfChanged(serverPath, renderServerManifest(names));
+  const wroteClient = await writeIfChanged(clientPath, renderClientManifest(clientNames));
+
+  if (!wroteServer && !wroteClient) {
+    step(`zen-modules: manifests already up to date ${serverCount} ${clientCount}`);
+    return;
+  }
+
+  if (wroteServer) done(`zen-modules: wrote ${OUTPUT_SERVER} ${serverCount}`);
+  if (wroteClient) done(`zen-modules: wrote ${OUTPUT_CLIENT} ${clientCount}`);
+  for (const name of names) {
+    const hasClient = clientNames.includes(name);
+    step(`  → ${name}${hasClient ? '  (+ /client)' : ''}`);
+  }
+}
+
+function printHelp() {
+  console.log(`
+Zen Modules CLI
+
+Usage:
+  npx zen-modules <command>
+
+Commands:
+  sync     Régénère app/.zen/modules.generated.js à partir des @zen/module-*
+           déclarés dans le package.json du projet courant.
+  help     Affiche cette aide.
+`);
+}
+
+const [, , command] = process.argv;
+
+try {
+  switch (command) {
+    case 'sync':
+      await syncCommand();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      printHelp();
+      break;
+    default:
+      warn(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+} catch (err) {
+  fail(`zen-modules: ${err.message}`);
+  process.exit(1);
+}

src/core/modules/client.js

@@ -1,32 +0,0 @@
-/**
- * Client-Safe Module Registry Access
- * 
- * This file ONLY exports functions that are safe to use in client components.
- * It does NOT export discovery, loader, or initialization functions that
- * might import server-only modules like database code.
- * 
- * NOTE: Most registry functions return empty results on the client because
- * the registry is populated on the server during discovery. For client-side
- * module page loading, use the loaders from modules.pages.js instead.
- */
-
-// Only export registry getter functions (no discovery/loader functions)
-export {
-  getModule,
-  getAllModules,
-  getEnabledModules,
-  isModuleRegistered,
-  isModuleEnabled,
-  getAllApiRoutes,
-  getAllAdminNavigation,
-  getAdminPage,
-  getAllCronJobs,
-  getAllPublicRoutes,
-  getAllDatabaseSchemas,
-  getModuleMetadataGenerator,
-  getAllModuleMetadata,
-} from './registry.js';
-
-// NOTE: getModulePublicPages is NOT exported here because it relies on the
-// server-side registry which is empty on the client. Use getModulePublicPageLoader()
-// from '@zen/core/modules/pages' instead for client-side public page loading.

src/core/modules/defineModule.js

@@ -1,59 +0,0 @@
-/**
- * defineModule — helper to declare a ZEN module.
- *
- * Used for both internal modules (src/modules/) and external npm packages.
- *
- * @param {Object} config - Module configuration
- * @returns {Object} Normalized module configuration
- */
-export function defineModule(config) {
-  if (!config || typeof config !== 'object') {
-    throw new Error('[defineModule] Config must be an object.');
-  }
-
-  if (!config.name || typeof config.name !== 'string') {
-    throw new Error('[defineModule] Field "name" is required (e.g. "invoice").');
-  }
-
-  return {
-    // Identity
-    version: '1.0.0',
-    displayName: config.name.charAt(0).toUpperCase() + config.name.slice(1),
-    description: '',
-
-    // Dependencies and environment variables
-    dependencies: [],
-    envVars: [],
-
-    // Admin UI
-    navigation: null,
-    adminPages: {},
-    pageResolver: null,
-
-    // Public pages
-    publicPages: {},
-    publicRoutes: [],
-    dashboardWidgets: [],
-
-    // Server actions for public pages
-    actions: {},
-
-    // SEO metadata generators
-    metadata: {},
-
-    // Storage prefixes served publicly (no auth). Format: 'posts/blogue', 'assets/docs'
-    storagePublicPrefixes: [],
-
-    // Database (optional) — { createTables, dropTables }
-    db: null,
-
-    // Initialization callback (optional) — setup(ctx)
-    setup: null,
-
-    // Spread last so all fields above can be overridden
-    ...config,
-
-    // Internal marker — do not override
-    __isZenModule: true,
-  };
-}

src/core/modules/discover.server.js

@@ -0,0 +1,206 @@
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { info, warn } from '@zen/core/shared/logger';
+import { registerModule } from './registry.js';
+
+/**
+ * Sources de modules `@zen/module-*` activés dans le projet consommateur.
+ *
+ * Le projet consommateur fournit un manifeste statique (généré par
+ * `npx zen-modules sync`) et le passe à `initializeZen({ modules })`. Le
+ * manifeste a la forme :
+ *
+ *   import * as posts from '@zen/module-posts';
+ *   export const modules = [{ name: '@zen/module-posts', exports: posts }];
+ *   await Promise.all(modules.map(m => m.exports.register?.()));
+ *
+ * Le `import *` rend l'arbre d'imports du module visible aux deux bundles
+ * Next.js (server + client) ; Turbopack/Webpack le bundlent comme n'importe
+ * quel autre fichier source. C'est ce qui permet au module de référencer du
+ * JSX, `next/headers`, `next/navigation`, etc. — chaque côté reçoit la bonne
+ * condition.
+ *
+ * Cette fonction ne fait QUE peupler le registre interne du core (pour que
+ * `getRegisteredModules()` retourne les bons objets côté serveur). Le top-level
+ * await dans le manifeste a déjà appelé `register()` au moment de son import.
+ */
+export function registerModules(modules) {
+  if (!Array.isArray(modules)) return;
+
+  for (const entry of modules) {
+    const ex = entry?.exports;
+    const name = entry?.name ?? ex?.manifest?.name ?? '<unknown>';
+
+    if (!ex?.manifest || typeof ex.register !== 'function') {
+      warn(`zen-modules: "${name}" missing manifest/register — skipping`);
+      continue;
+    }
+
+    registerModule({
+      manifest: ex.manifest,
+      register: ex.register,
+      createTables: ex.createTables,
+      dropTables: ex.dropTables,
+    });
+    info(`zen-modules: registered ${ex.manifest.name}@${ex.manifest.version ?? '?'}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers de scan (utilisés par le CLI `zen-modules sync` et l'env validation).
+// ---------------------------------------------------------------------------
+
+const NAME_PREFIX = /^(@zen\/module-|zen-module-)/;
+
+export function isCandidateName(name) {
+  return NAME_PREFIX.test(name);
+}
+
+export async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Résout le chemin du `package.json` d'un module installé. Ne dépend PAS de
+ * `require.resolve(name)` (qui peut échouer si la sous-entrée `./package.json`
+ * n'est pas exposée par `exports`) ni de `import.meta.resolve` (variable selon
+ * la version Node). On remonte simplement depuis `projectCwd` en cherchant
+ * `node_modules/<name>/package.json` à chaque niveau — c'est le mécanisme de
+ * résolution npm standard.
+ */
+function resolveModulePackageJson(name, projectCwd) {
+  let dir = projectCwd;
+  while (true) {
+    const candidate = join(dir, 'node_modules', name, 'package.json');
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+      return { path: candidate, pkg };
+    } catch {
+      // pas trouvé à ce niveau, remonter
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export async function isThirdPartyModule(name, projectCwd) {
+  const found = resolveModulePackageJson(name, projectCwd);
+  return Array.isArray(found?.pkg?.keywords) && found.pkg.keywords.includes('zen-module');
+}
+
+/**
+ * Vérifie si un module installé expose une sous-entrée `./client` dans son
+ * `package.json#exports`. Utilisé par le CLI `zen-modules sync` pour décider
+ * si le manifeste client doit l'importer. Les modules sans partie cliente
+ * (modules purement back-end / API / DB) ne sont pas inclus dans le manifeste
+ * client — ça évite d'embarquer leur graphe d'imports serveur dans le bundle
+ * browser.
+ */
+export async function moduleHasClientEntry(name, projectCwd) {
+  const found = resolveModulePackageJson(name, projectCwd);
+  return Boolean(found?.pkg?.exports?.['./client']);
+}
+
+/**
+ * Scanne `package.json` du projet consommateur et retourne la liste des noms
+ * de packages `@zen/module-*` (ou compatibles). N'effectue AUCUN import — le
+ * CLI `zen-modules sync` consomme cette liste pour générer le manifeste
+ * statique.
+ */
+export async function findInstalledModuleNames({ cwd = process.cwd() } = {}) {
+  const pkg = await readJson(resolve(cwd, 'package.json'));
+  if (!pkg) return [];
+
+  const allDeps = {
+    ...(pkg.dependencies ?? {}),
+    ...(pkg.devDependencies ?? {}),
+  };
+
+  const out = [];
+  for (const name of Object.keys(allDeps)) {
+    if (isCandidateName(name) || (await isThirdPartyModule(name, cwd))) {
+      out.push(name);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Résout l'URL ESM du main entry d'un module à partir de son `package.json`.
+ * On lit `exports['.'].import` puis `main`, sinon `./index.js` par défaut.
+ * Pas de `require.resolve` : un module `@zen/module-*` peut déclarer uniquement
+ * la condition `"import"` (ESM-only) — la résolution CJS échouerait alors avec
+ * "No exports main defined". Comme on a déjà localisé le `package.json` via
+ * `resolveModulePackageJson`, on construit l'URL nous-mêmes.
+ */
+function resolveModuleEntryUrl(found) {
+  const pkgDir = dirname(found.path);
+  const main = found.pkg?.exports?.['.']?.import ?? found.pkg?.main ?? './index.js';
+  return pathToFileURL(resolve(pkgDir, main)).href;
+}
+
+/**
+ * Variante "Node-only" du chargement de modules — utilisée par le CLI
+ * `zen-db init` qui ne passe jamais par un bundler. Charge dynamiquement
+ * chaque module depuis `node_modules/` du projet, pour que le CLI ait accès
+ * à `manifest`, `createTables`, `dropTables`. Ne déclenche PAS `register()`
+ * (la chaîne register-server tirerait des imports Next.js incompatibles avec
+ * le contexte CLI).
+ *
+ * À ne PAS utiliser depuis le runtime Next.js — utiliser le manifeste statique
+ * via `initializeZen({ modules })`.
+ */
+export async function loadModulesForCli({ cwd = process.cwd() } = {}) {
+  const names = await findInstalledModuleNames({ cwd });
+
+  for (const name of names) {
+    const found = resolveModulePackageJson(name, cwd);
+    if (!found) {
+      warn(`zen-modules: cannot find package "${name}" in node_modules`);
+      continue;
+    }
+
+    let mod;
+    try {
+      mod = await import(resolveModuleEntryUrl(found));
+    } catch (err) {
+      warn(`zen-modules: failed to import "${name}" — ${err.message}`);
+      continue;
+    }
+
+    if (!mod.manifest || typeof mod.register !== 'function') {
+      warn(`zen-modules: "${name}" missing manifest/register — skipping`);
+      continue;
+    }
+
+    registerModule({
+      manifest: mod.manifest,
+      register: mod.register,
+      createTables: mod.createTables,
+      dropTables: mod.dropTables,
+    });
+    info(`zen-modules: loaded ${mod.manifest.name}@${mod.manifest.version ?? '?'}`);
+  }
+}
+
+/**
+ * Valide les variables d'environnement requises par chaque module.
+ * Ne lance pas — log un warning pour chaque variable absente.
+ */
+export function validateModuleEnvVars(modules) {
+  for (const mod of modules) {
+    const envVars = mod.manifest?.envVars ?? [];
+    for (const v of envVars) {
+      if (v.required && !process.env[v.key]) {
+        warn(`zen-modules: ${mod.manifest.name} requires env var "${v.key}" — ${v.description ?? ''}`);
+      }
+    }
+  }
+}

src/core/modules/discovery.js

@@ -1,310 +0,0 @@
-/**
- * Module Discovery System
- * Auto-discovers and registers modules from the modules directory.
- * Also handles registration of external modules passed via zen.config.js.
- */
-
-import { registerModule, clearRegistry } from './registry.js';
-import { getAvailableModules } from '../../modules/modules.registry.js';
-import { step, done, warn, fail, info } from '../../shared/lib/logger.js';
-
-/**
- * Check if a module is enabled via environment variable
- * @param {string} moduleName - Module name
- * @returns {boolean}
- */
-export function isModuleEnabledInEnv(moduleName) {
-  const envVar = `ZEN_MODULE_${moduleName.toUpperCase().replace(/-/g, '_')}`;
-  return process.env[envVar] === 'true';
-}
-
-/**
- * Discover and register all modules
- * @param {Object} options - Discovery options
- * @param {boolean} options.force - Force re-discovery
- * @returns {Promise<Object>} Discovery result
- */
-export async function discoverModules(options = {}) {
-  const { force = false } = options;
-  
-  const DISCOVERY_KEY = Symbol.for('__ZEN_MODULES_DISCOVERED__');
-  
-  if (globalThis[DISCOVERY_KEY] && !force) {
-    warn('modules already discovered, skipping');
-    return { alreadyDiscovered: true };
-  }
-
-  if (force) {
-    clearRegistry();
-  }
-
-  step('Discovering modules...');
-  
-  const discovered = [];
-  const enabled = [];
-  const skipped = [];
-  const errors = [];
-  
-  const knownModules = getAvailableModules();
-  
-  for (const moduleName of knownModules) {
-    try {
-      const isEnabled = isModuleEnabledInEnv(moduleName);
-      
-      if (!isEnabled) {
-        skipped.push(moduleName);
-        continue;
-      }
-      
-      // Load module configuration
-      const moduleConfig = await loadModuleConfig(moduleName);
-      
-      if (moduleConfig) {
-        // Load additional components (db, cron, api)
-        const components = await loadModuleComponents(moduleName);
-        
-        // Register the module
-        registerModule(moduleName, {
-          ...moduleConfig,
-          ...components,
-          enabled: true
-        });
-        
-        discovered.push(moduleName);
-        enabled.push(moduleName);
-        info(`Registered ${moduleName}`);
-      }
-    } catch (error) {
-      errors.push({ module: moduleName, error: error.message });
-      fail(`Error loading ${moduleName}: ${error.message}`);
-    }
-  }
-
-  globalThis[DISCOVERY_KEY] = true;
-  
-  return { discovered, enabled, skipped, errors };
-}
-
-/**
- * Load module configuration from module.config.js
- * @param {string} moduleName - Module name
- * @returns {Promise<Object|null>} Module configuration
- */
-async function loadModuleConfig(moduleName) {
-  try {
-    const config = await import(`../../modules/${moduleName}/module.config.js`);
-    const moduleConfig = config.default || config;
-
-    return {
-      name: moduleConfig.name || moduleName,
-      displayName: moduleConfig.displayName || moduleName.charAt(0).toUpperCase() + moduleName.slice(1),
-      version: moduleConfig.version || '1.0.0',
-      description: moduleConfig.description || `${moduleName} module`,
-      dependencies: moduleConfig.dependencies || [],
-      envVars: moduleConfig.envVars || [],
-      // Admin config: navigation + page path markers (components loaded client-side)
-      admin: buildAdminConfig(moduleConfig),
-      // Public routes metadata (components loaded client-side)
-      public: moduleConfig.publicRoutes?.length
-        ? { routes: moduleConfig.publicRoutes }
-        : undefined,
-    };
-  } catch (error) {
-    // No module.config.js — use defaults silently
-    return {
-      name: moduleName,
-      displayName: moduleName.charAt(0).toUpperCase() + moduleName.slice(1),
-      version: '1.0.0',
-      description: `${moduleName} module`
-    };
-  }
-}
-
-/**
- * Load additional module components (db, cron, api)
- * Note: Metadata is loaded from modules.metadata.js (static registry)
- * @param {string} moduleName - Module name
- * @returns {Promise<Object>} Module components
- */
-async function loadModuleComponents(moduleName) {
-  const components = {};
-  
-  // Load API routes
-  try {
-    const api = await import(`../../modules/${moduleName}/api.js`);
-    components.api = api.default || api;
-  } catch (error) {
-    // API is optional
-  }
-  
-  // Load cron configuration
-  try {
-    const cron = await import(`../../modules/${moduleName}/cron.config.js`);
-    components.cron = cron.default || cron;
-  } catch (error) {
-    // Cron is optional
-  }
-  
-  // Load database configuration
-  try {
-    const db = await import(`../../modules/${moduleName}/db.js`);
-    if (db.createTables) {
-      components.db = {
-        init: db.createTables,
-        drop: db.dropTables
-      };
-    }
-  } catch (error) {
-    // DB is optional
-  }
-  
-  return components;
-}
-
-/**
- * Register external modules provided via zen.config.js.
- * Skips any module whose ZEN_MODULE_<NAME>=true env var is not set.
- *
- * @param {Array} modules - Array of module configs created with defineModule()
- * @returns {Promise<Object>} { registered, skipped, errors }
- */
-export async function registerExternalModules(modules = []) {
-  const registered = [];
-  const skipped = [];
-  const errors = [];
-
-  for (const moduleConfig of modules) {
-    const moduleName = moduleConfig?.name;
-
-    if (!moduleName) {
-      errors.push({ module: '(unknown)', error: 'Missing "name" field.' });
-      continue;
-    }
-
-    try {
-      if (!isModuleEnabledInEnv(moduleName)) {
-        skipped.push(moduleName);
-        continue;
-      }
-
-      // Build registry entry from the external module config
-      const adminConfig = buildAdminConfig(moduleConfig);
-
-      const moduleData = {
-        name: moduleName,
-        displayName: moduleConfig.displayName || moduleName,
-        version: moduleConfig.version || '1.0.0',
-        description: moduleConfig.description || '',
-        dependencies: moduleConfig.dependencies || [],
-        envVars: moduleConfig.envVars || [],
-        admin: adminConfig,
-        public: moduleConfig.publicRoutes?.length
-          ? { routes: moduleConfig.publicRoutes }
-          : undefined,
-        actions: moduleConfig.actions || {},
-        metadata: moduleConfig.metadata || {},
-        db: moduleConfig.db
-          ? { init: moduleConfig.db.createTables, drop: moduleConfig.db.dropTables }
-          : undefined,
-        cron: moduleConfig.cron || undefined,
-        api: moduleConfig.api || undefined,
-        enabled: true,
-        external: true,
-      };
-
-      registerModule(moduleName, moduleData);
-
-      // Call setup(ctx) if provided.
-      // Pass the module's declared envVars so the restricted config.get()
-      // enforces least-privilege access to environment variables.
-      if (typeof moduleConfig.setup === 'function') {
-        const ctx = await buildModuleContext(moduleConfig.envVars || []);
-        await moduleConfig.setup(ctx);
-      }
-
-      registered.push(moduleName);
-      info(`Registered external ${moduleName}`);
-    } catch (error) {
-      errors.push({ module: moduleName, error: error.message });
-      fail(`Error registering external ${moduleName}: ${error.message}`);
-    }
-  }
-
-  return { registered, skipped, errors };
-}
-
-/**
- * Build admin config object from a module config (shared with loadModuleConfig).
- * @param {Object} moduleConfig
- * @returns {Object|undefined}
- */
-function buildAdminConfig(moduleConfig) {
-  if (!moduleConfig.navigation && !moduleConfig.adminPages) return undefined;
-
-  const adminConfig = {};
-
-  if (moduleConfig.navigation) {
-    adminConfig.navigation = moduleConfig.navigation;
-  }
-
-  if (moduleConfig.adminPages) {
-    adminConfig.pages = {};
-    for (const path of Object.keys(moduleConfig.adminPages)) {
-      adminConfig.pages[path] = true;
-    }
-  }
-
-  return adminConfig;
-}
-
-/**
- * Build the context object injected into module setup() callbacks.
- * All services are lazy-initialized internally — importing them is safe.
- *
- * The config.get accessor is intentionally restricted: a module may only read
- * environment variables that it has declared in its own envVars list.  This
- * prevents a malicious or compromised third-party module from reading unrelated
- * secrets (e.g. STRIPE_SECRET_KEY, ZEN_DATABASE_URL) via ctx.config.get().
- *
- * @param {string[]} [allowedKeys=[]] - env var names this module declared
- * @returns {Promise<Object>} ctx
- */
-async function buildModuleContext(allowedKeys = []) {
-  const [db, email, storage, payments] = await Promise.all([
-    import('../../core/database/index.js'),
-    import('../../core/email/index.js'),
-    import('../../core/storage/index.js'),
-    import('../../core/payments/index.js'),
-  ]);
-
-  const allowedSet = new Set(allowedKeys);
-
-  return {
-    db,
-    email,
-    storage,
-    payments,
-    config: {
-      /**
-       * Read an env var — only variables declared in the module's envVars list
-       * are accessible. Any other key returns undefined and logs a violation.
-       */
-      get: (key) => {
-        if (!allowedSet.has(key)) {
-          fail(`[Security] Module attempted to read undeclared env var "${key}" — access denied`);
-          return undefined;
-        }
-        return process.env[key];
-      },
-    },
-  };
-}
-
-/**
- * Reset module discovery (useful for testing)
- */
-export function resetDiscovery() {
-  const DISCOVERY_KEY = Symbol.for('__ZEN_MODULES_DISCOVERED__');
-  globalThis[DISCOVERY_KEY] = false;
-  clearRegistry();
-}

src/core/modules/index.js

@@ -1,43 +1,2 @@
-/**
- * Module System Entry Point
- * Exports all module-related functionality
- */
-
-// Discovery
-export {
-  discoverModules,
-  registerExternalModules,
-  isModuleEnabledInEnv,
-  resetDiscovery
-} from './discovery.js';
-
-// Registry (server-side only - these functions rely on the registry populated during discovery)
-export {
-  registerModule,
-  getModule,
-  getAllModules,
-  getEnabledModules,
-  isModuleRegistered,
-  isModuleEnabled,
-  clearRegistry,
-  getAllApiRoutes,
-  getAllAdminNavigation,
-  getAdminPage,
-  getAllCronJobs,
-  getAllPublicRoutes,
-  getAllDatabaseSchemas,
-  getModuleMetadataGenerator,
-  getAllModuleMetadata,
-  getModulePublicPages // returns route metadata only, use modules.pages.js for components
-} from './registry.js';
-
-// Loader
-export {
-  initializeModules,
-  initializeModuleDatabases,
-  startModuleCronJobs,
-  stopModuleCronJobs,
-  getCronJobStatus,
-  resetModuleLoader,
-  getModuleStatus
-} from './loader.js';
+export { registerModule, getRegisteredModules, getRegisteredModule, clearRegisteredModules } from './registry.js';
+export { registerModules, findInstalledModuleNames, moduleHasClientEntry, loadModulesForCli, validateModuleEnvVars } from './discover.server.js';

src/core/modules/loader.js

@@ -1,244 +0,0 @@
-/**
- * Module Loader
- * Handles loading and initializing modules
- */
-
-import { discoverModules, resetDiscovery } from './discovery.js';
-import {
-  getAllModules,
-  getEnabledModules,
-  getAllCronJobs,
-  getAllDatabaseSchemas,
-  isModuleEnabled
-} from './registry.js';
-import { step, done, warn, fail, info } from '../../shared/lib/logger.js';
-
-// Use globalThis to track initialization state
-const INIT_KEY = Symbol.for('__ZEN_MODULES_INITIALIZED__');
-const CRON_JOBS_KEY = Symbol.for('__ZEN_MODULE_CRON_JOBS__');
-
-/**
- * Initialize all modules
- * Discovers modules, initializes databases, and starts cron jobs
- * @param {Object} options - Initialization options
- * @param {boolean} options.skipCron - Skip starting cron jobs
- * @param {boolean} options.skipDb - Skip database initialization
- * @param {boolean} options.force - Force re-initialization
- * @returns {Promise<Object>} Initialization result
- */
-export async function initializeModules(options = {}) {
-  const { skipCron = false, skipDb = false, force = false } = options;
-  
-  // Prevent multiple initializations
-  if (globalThis[INIT_KEY] && !force) {
-    warn('modules already initialized, skipping');
-    return { alreadyInitialized: true };
-  }
-
-  step('Initializing modules...');
-  
-  const result = {
-    discovery: null,
-    database: { created: [], skipped: [], errors: [] },
-    cron: { started: [], errors: [] }
-  };
-  
-  try {
-    // Step 1: Discover modules
-    result.discovery = await discoverModules({ force });
-    
-    // Step 2: Initialize databases
-    if (!skipDb) {
-      result.database = await initializeModuleDatabases();
-    }
-    
-    // Step 3: Start cron jobs
-    if (!skipCron) {
-      result.cron = await startModuleCronJobs();
-    }
-    
-    globalThis[INIT_KEY] = true;
-    done('Modules initialized');
-
-  } catch (error) {
-    fail(`Module initialization failed: ${error.message}`);
-    result.error = error.message;
-  }
-  
-  return result;
-}
-
-/**
- * Initialize databases for all enabled modules
- * @returns {Promise<Object>} Database initialization result
- */
-export async function initializeModuleDatabases() {
-  step('Initializing module databases...');
-  
-  const schemas = getAllDatabaseSchemas();
-  const result = {
-    created: [],
-    skipped: [],
-    errors: []
-  };
-  
-  for (const schema of schemas) {
-    try {
-      if (schema.init && typeof schema.init === 'function') {
-        const initResult = await schema.init();
-        
-        if (initResult?.created) {
-          result.created.push(...initResult.created);
-        }
-        if (initResult?.skipped) {
-          result.skipped.push(...initResult.skipped);
-        }
-        
-        info(`DB ready: ${schema.module}`);
-      }
-    } catch (error) {
-      result.errors.push({
-        module: schema.module,
-        error: error.message
-      });
-      fail(`DB init error for ${schema.module}: ${error.message}`);
-    }
-  }
-  
-  return result;
-}
-
-/**
- * Start cron jobs for all enabled modules
- * @returns {Promise<Object>} Cron job start result
- */
-export async function startModuleCronJobs() {
-  step('Starting cron jobs...');
-  
-  // Stop existing cron jobs first
-  stopModuleCronJobs();
-  
-  const jobs = getAllCronJobs();
-  const result = {
-    started: [],
-    errors: []
-  };
-  
-  // Initialize cron jobs storage
-  if (!globalThis[CRON_JOBS_KEY]) {
-    globalThis[CRON_JOBS_KEY] = new Map();
-  }
-  
-  for (const job of jobs) {
-    try {
-      if (job.handler && typeof job.handler === 'function') {
-        // Dynamic import of node-cron
-        const cron = (await import('node-cron')).default;
-        
-        const cronJob = cron.schedule(job.schedule, async () => {
-          info(`Cron ${job.name} running at ${new Date().toISOString()}`);
-          try {
-            await job.handler();
-            info(`Cron ${job.name} completed`);
-          } catch (error) {
-            fail(`Cron ${job.name}: ${error.message}`);
-          }
-        }, {
-          scheduled: true,
-          timezone: job.timezone || process.env.ZEN_TIMEZONE || 'America/Toronto'
-        });
-        
-        globalThis[CRON_JOBS_KEY].set(job.name, cronJob);
-        result.started.push(job.name);
-        info(`Cron ready: ${job.name} (${job.schedule})`);
-      }
-    } catch (error) {
-      result.errors.push({
-        job: job.name,
-        module: job.module,
-        error: error.message
-      });
-      fail(`Cron error for ${job.name}: ${error.message}`);
-    }
-  }
-  
-  return result;
-}
-
-/**
- * Stop all module cron jobs
- */
-export function stopModuleCronJobs() {
-  if (globalThis[CRON_JOBS_KEY]) {
-    for (const [name, job] of globalThis[CRON_JOBS_KEY].entries()) {
-      try {
-        job.stop();
-        info(`Cron stopped: ${name}`);
-      } catch (error) {
-        fail(`Error stopping cron ${name}: ${error.message}`);
-      }
-    }
-    globalThis[CRON_JOBS_KEY].clear();
-  }
-}
-
-/**
- * Get status of all cron jobs
- * @returns {Object} Cron job status
- */
-export function getCronJobStatus() {
-  const status = {};
-  
-  if (globalThis[CRON_JOBS_KEY]) {
-    for (const [name, job] of globalThis[CRON_JOBS_KEY].entries()) {
-      status[name] = {
-        running: true // node-cron doesn't expose a running state easily
-      };
-    }
-  }
-  
-  return status;
-}
-
-/**
- * Reset module loader (useful for testing)
- */
-export function resetModuleLoader() {
-  stopModuleCronJobs();
-  resetDiscovery();
-  globalThis[INIT_KEY] = false;
-}
-
-/**
- * Get module status
- * @returns {Object} Status of all modules
- */
-export function getModuleStatus() {
-  const modules = getAllModules();
-  const enabled = getEnabledModules();
-  const cronStatus = getCronJobStatus();
-  
-  return {
-    totalModules: modules.size,
-    enabledModules: enabled.length,
-    modules: Array.from(modules.entries()).map(([name, data]) => ({
-      name,
-      enabled: data.enabled,
-      displayName: data.displayName,
-      version: data.version,
-      hasApi: !!data.api,
-      hasAdmin: !!data.admin,
-      hasCron: !!data.cron,
-      hasDb: !!data.db,
-      hasPublic: !!data.public
-    })),
-    cronJobs: cronStatus
-  };
-}
-
-// Re-export useful functions from registry
-export {
-  isModuleEnabled,
-  getAllModules,
-  getEnabledModules
-} from './registry.js';

src/core/modules/registry.js

@@ -1,293 +1,45 @@
 /**
- * Module Registry
- * Stores and manages all discovered modules
+ * Registre des modules `@zen/module-*` chargés.
+ *
+ * Un module est un package npm exportant :
+ *   - manifest      : { name, version, permissions?, envVars? }
+ *   - register      : () => void | Promise<void>
+ *   - createTables  : async () => { created?: string[], skipped?: string[] }
+ *   - dropTables    : async () => void
+ *
+ * La découverte (`discover.server.js`) lit le package.json du projet
+ * consommateur et appelle registerModule() pour chaque dépendance détectée.
+ *
+ * Persisté via Symbol.for sur globalThis pour survivre aux hot-reloads.
  */
 
-// Use globalThis to persist registry across module reloads
-const REGISTRY_KEY = Symbol.for('__ZEN_MODULE_REGISTRY__');
+const REGISTRY_KEY = Symbol.for('__ZEN_MODULES_REGISTRY__');
+if (!globalThis[REGISTRY_KEY]) globalThis[REGISTRY_KEY] = new Map();
+/** @type {Map<string, object>} */
+const registry = globalThis[REGISTRY_KEY];
 
-/**
- * Initialize or get the module registry
- * @returns {Map} Module registry map
- */
-function getRegistry() {
-  if (!globalThis[REGISTRY_KEY]) {
-    globalThis[REGISTRY_KEY] = new Map();
+export function registerModule(mod) {
+  if (!mod || typeof mod !== 'object') {
+    throw new TypeError('registerModule: argument must be an object');
   }
-  return globalThis[REGISTRY_KEY];
+  const { manifest } = mod;
+  if (!manifest || typeof manifest.name !== 'string' || !manifest.name) {
+    throw new TypeError('registerModule: module.manifest.name must be a non-empty string');
+  }
+  if (typeof mod.register !== 'function') {
+    throw new TypeError(`registerModule(${manifest.name}): module.register must be a function`);
+  }
+  registry.set(manifest.name, mod);
 }
 
-/**
- * Register a module in the registry
- * @param {string} name - Module name
- * @param {Object} moduleData - Module configuration and components
- */
-export function registerModule(name, moduleData) {
-  const registry = getRegistry();
-  registry.set(name, {
-    ...moduleData,
-    registeredAt: new Date().toISOString()
-  });
+export function getRegisteredModules() {
+  return [...registry.values()];
 }
 
-/**
- * Get a registered module by name
- * @param {string} name - Module name
- * @returns {Object|null} Module data or null
- */
-export function getModule(name) {
-  const registry = getRegistry();
-  return registry.get(name) || null;
+export function getRegisteredModule(name) {
+  return registry.get(name);
 }
 
-/**
- * Get all registered modules
- * @returns {Map} All registered modules
- */
-export function getAllModules() {
-  return getRegistry();
-}
-
-/**
- * Get all enabled modules
- * @returns {Array} Array of enabled module data
- */
-export function getEnabledModules() {
-  const registry = getRegistry();
-  const enabled = [];
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled) {
-      enabled.push({ name, ...data });
-    }
-  }
-  
-  return enabled;
-}
-
-/**
- * Check if a module is registered
- * @param {string} name - Module name
- * @returns {boolean}
- */
-export function isModuleRegistered(name) {
-  const registry = getRegistry();
-  return registry.has(name);
-}
-
-/**
- * Check if a module is enabled
- * @param {string} name - Module name
- * @returns {boolean}
- */
-export function isModuleEnabled(name) {
-  const module = getModule(name);
-  return module?.enabled === true;
-}
-
-/**
- * Clear the module registry (useful for testing)
- */
-export function clearRegistry() {
-  const registry = getRegistry();
+export function clearRegisteredModules() {
   registry.clear();
 }
-
-/**
- * Get all API routes from enabled modules
- * @returns {Array} Array of route definitions
- */
-export function getAllApiRoutes() {
-  const routes = [];
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.api?.routes) {
-      routes.push(...data.api.routes.map(route => ({
-        ...route,
-        module: name
-      })));
-    }
-  }
-  
-  return routes;
-}
-
-/**
- * Get all admin navigation sections from enabled modules
- * @param {string} pathname - Current pathname for active state
- * @returns {Array} Array of navigation sections
- */
-export function getAllAdminNavigation(pathname) {
-  const sections = [];
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.admin?.navigation) {
-      const nav = data.admin.navigation;
-      
-      // Handle function or object navigation
-      const section = typeof nav === 'function' ? nav(pathname) : nav;
-
-      if (section) {
-        // Support array of sections (e.g. one per post type)
-        const sectionList = Array.isArray(section) ? section : [section];
-        for (const s of sectionList) {
-          if (s.items) {
-            s.items = s.items.map(item => ({
-              ...item,
-              current: pathname.startsWith(item.href)
-            }));
-          }
-          sections.push({ ...s, module: name });
-        }
-      }
-    }
-  }
-  
-  return sections;
-}
-
-/**
- * Get admin page info for a given path
- * 
- * Returns module info if the path is registered as an admin page.
- * The actual component is loaded client-side via modules.pages.js
- * 
- * @param {string} path - Page path (e.g., '/admin/invoice/invoices')
- * @returns {Object|null} Object with { module, path } or null
- */
-export function getAdminPage(path) {
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.admin?.pages) {
-      if (data.admin.pages[path]) {
-        return { module: name, path };
-      }
-    }
-  }
-  
-  return null;
-}
-
-/**
- * Get all cron jobs from enabled modules
- * @returns {Array} Array of cron job definitions
- */
-export function getAllCronJobs() {
-  const jobs = [];
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.cron?.jobs) {
-      jobs.push(...data.cron.jobs.map(job => ({
-        ...job,
-        module: name
-      })));
-    }
-  }
-  
-  return jobs;
-}
-
-/**
- * Get public routes from enabled modules
- * @returns {Array} Array of public route definitions
- */
-export function getAllPublicRoutes() {
-  const routes = [];
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.public?.routes) {
-      routes.push(...data.public.routes.map(route => ({
-        ...route,
-        module: name
-      })));
-    }
-  }
-  
-  return routes;
-}
-
-/**
- * Get database schemas from all enabled modules
- * @returns {Array} Array of database schema definitions
- */
-export function getAllDatabaseSchemas() {
-  const schemas = [];
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.db) {
-      schemas.push({
-        module: name,
-        ...data.db
-      });
-    }
-  }
-  
-  return schemas;
-}
-
-/**
- * Get a specific metadata generator function from a module.
- * Use this when you need to call a generator directly (e.g. for Next.js generateMetadata).
- *
- * To get the full metadata object for a module, use getModuleMetadata() from modules.metadata.js.
- *
- * @param {string} moduleName - Module name (e.g., 'invoice')
- * @param {string} type - Metadata type key (e.g., 'payment', 'pdf', 'receipt')
- * @returns {Function|null} Metadata generator function or null if not found
- */
-export function getModuleMetadataGenerator(moduleName, type) {
-  const module = getModule(moduleName);
-  
-  if (module?.enabled && module?.metadata) {
-    // If type is specified, return the specific generator
-    if (type && module.metadata[type]) {
-      return module.metadata[type];
-    }
-    // If no type, return the default (first one or 'payment')
-    return module.metadata.payment || module.metadata[Object.keys(module.metadata)[0]] || null;
-  }
-  
-  return null;
-}
-
-/**
- * Get all metadata configurations from enabled modules
- * @returns {Object} Object mapping module names to their metadata configs
- */
-export function getAllModuleMetadata() {
-  const metadata = {};
-  const registry = getRegistry();
-  
-  for (const [name, data] of registry.entries()) {
-    if (data.enabled && data.metadata) {
-      metadata[name] = data.metadata;
-    }
-  }
-  
-  return metadata;
-}
-
-/**
- * Get public routes configuration from a module
- * 
- * NOTE: This function only returns route metadata, not components.
- * For loading public page components, use getModulePublicPageLoader() from modules.pages.js
- * 
- * @param {string} moduleName - Module name
- * @returns {Object|null} Public routes config or null
- */
-export function getModulePublicPages(moduleName) {
-  const module = getModule(moduleName);
-  
-  if (module?.enabled && module?.public) {
-    return module.public;
-  }
-  
-  return null;
-}

src/core/payments/README.md

@@ -0,0 +1,225 @@
+# Payments Framework
+
+Ce répertoire fournit un **wrapper autour de [Stripe](https://stripe.com)** pour la gestion des paiements : sessions de checkout, intents, clients, remboursements et webhooks.
+
+---
+
+## Structure
+
+```
+src/core/payments/
+├── index.js     re-export
+└── stripe.js    wrapper Stripe
+```
+
+---
+
+## Import
+
+```js
+import {
+  isEnabled,
+  getPublishableKey,
+  createCheckoutSession,
+  createPaymentIntent,
+  getCheckoutSession,
+  getPaymentIntent,
+  verifyWebhookSignature,
+  createCustomer,
+  getOrCreateCustomer,
+  listPaymentMethods,
+  createRefund,
+} from '@zen/core/payments';
+```
+
+---
+
+## Variables d'environnement
+
+| Variable | Obligatoire | Description |
+|----------|-------------|-------------|
+| `STRIPE_SECRET_KEY` | Oui | Clé secrète Stripe (côté serveur) |
+| `STRIPE_PUBLISHABLE_KEY` | Oui | Clé publique Stripe (côté client) |
+| `STRIPE_WEBHOOK_SECRET` | Pour les webhooks | Secret de signature des webhooks Stripe |
+| `ZEN_CURRENCY` | Non | Devise par défaut pour les payment intents (défaut : `cad`) |
+
+---
+
+## API
+
+### `isEnabled()`
+
+Retourne `true` si `STRIPE_SECRET_KEY` et `STRIPE_PUBLISHABLE_KEY` sont définis. Utiliser pour conditionner l'affichage des fonctionnalités de paiement.
+
+```js
+if (isEnabled()) {
+  // afficher le bouton de paiement
+}
+```
+
+---
+
+### `getPublishableKey()`
+
+Retourne la clé publique Stripe, ou `null` si absente. Passer au client pour initialiser Stripe.js ou `@stripe/react-stripe-js`.
+
+```js
+const key = getPublishableKey();
+```
+
+---
+
+### `createCheckoutSession(options)`
+
+Crée une session Stripe Checkout. Retourne la session Stripe.
+
+```js
+const session = await createCheckoutSession({
+  lineItems: [{ price: 'price_xxx', quantity: 1 }],
+  successUrl: 'https://example.com/success',
+  cancelUrl: 'https://example.com/cancel',
+  customerEmail: 'user@example.com',
+  mode: 'payment',
+});
+
+// Rediriger l'utilisateur vers session.url
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `lineItems` | `object[]` | Lignes de commande Stripe |
+| `successUrl` | `string` | URL de retour après paiement réussi |
+| `cancelUrl` | `string` | URL de retour après annulation |
+| `customerEmail` | `string` | Email pré-rempli dans le formulaire (optionnel) |
+| `clientReferenceId` | `string` | Identifiant interne pour rapprochement (optionnel) |
+| `metadata` | `object` | Métadonnées Stripe (optionnel) |
+| `mode` | `string` | `'payment'`, `'subscription'` ou `'setup'` (défaut : `'payment'`) |
+
+---
+
+### `createPaymentIntent(options)`
+
+Crée un PaymentIntent Stripe. Retourne le PaymentIntent.
+
+```js
+const intent = await createPaymentIntent({
+  amount: 4999, // en centimes
+  currency: 'eur',
+  metadata: { orderId: '123' },
+});
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `amount` | `number` | Montant en centimes |
+| `currency` | `string` | Devise ISO (défaut : `ZEN_CURRENCY` ou `cad`) |
+| `metadata` | `object` | Métadonnées Stripe (optionnel) |
+| `automaticPaymentMethods` | `object` | Config des méthodes de paiement (défaut : `{ enabled: true }`) |
+
+---
+
+### `getCheckoutSession(sessionId)`
+
+Récupère une session Checkout par son identifiant. À utiliser dans la route `successUrl` pour confirmer le paiement.
+
+```js
+const session = await getCheckoutSession(sessionId);
+```
+
+---
+
+### `getPaymentIntent(paymentIntentId)`
+
+Récupère un PaymentIntent par son identifiant.
+
+```js
+const intent = await getPaymentIntent(paymentIntentId);
+```
+
+---
+
+### `verifyWebhookSignature(payload, signature)`
+
+Vérifie la signature d'un webhook Stripe et retourne l'événement. Lève une erreur si la signature est invalide ou si `STRIPE_WEBHOOK_SECRET` est absent.
+
+```js
+// Next.js Route Handler
+export async function POST(req) {
+  const payload = await req.text();
+  const signature = req.headers.get('stripe-signature');
+
+  let event;
+  try {
+    event = await verifyWebhookSignature(payload, signature);
+  } catch (err) {
+    return new Response('Signature invalide', { status: 400 });
+  }
+
+  if (event.type === 'checkout.session.completed') {
+    // traiter la commande
+  }
+
+  return new Response('OK');
+}
+```
+
+Le `payload` doit être le corps brut de la requête (non parsé).
+
+---
+
+### `createCustomer(options)`
+
+Crée un client Stripe. Retourne le client.
+
+```js
+const customer = await createCustomer({
+  email: 'user@example.com',
+  name: 'Jean Dupont',
+  metadata: { userId: '42' },
+});
+```
+
+---
+
+### `getOrCreateCustomer(email, defaultData)`
+
+Retourne le client Stripe existant pour cet email, ou en crée un nouveau. Utilise une clé d'idempotence dérivée de l'email pour limiter les doublons en cas d'appels concurrents.
+
+```js
+const customer = await getOrCreateCustomer('user@example.com', {
+  name: 'Jean Dupont',
+  metadata: { userId: '42' },
+});
+```
+
+---
+
+### `listPaymentMethods(customerId, type)`
+
+Retourne la liste des méthodes de paiement d'un client.
+
+```js
+const methods = await listPaymentMethods(customer.id, 'card');
+```
+
+Le paramètre `type` est optionnel (défaut : `'card'`).
+
+---
+
+### `createRefund(options)`
+
+Crée un remboursement. Retourne le remboursement Stripe.
+
+```js
+const refund = await createRefund({
+  paymentIntentId: 'pi_xxx',
+  amount: 1000, // partiel, en centimes (optionnel — total si absent)
+  reason: 'requested_by_customer', // optionnel
+});
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `paymentIntentId` | `string` | Identifiant du PaymentIntent à rembourser |
+| `amount` | `number` | Montant en centimes (optionnel, remboursement total si absent) |
+| `reason` | `string` | Raison Stripe : `duplicate`, `fraudulent`, `requested_by_customer` (optionnel) |

src/core/payments/index.js

@@ -1,7 +1 @@
-/**
- * Payments Module Entry Point
- * Re-exports all payment utilities
- */
-
 export * from './stripe.js';
-export { default as stripe } from './stripe.js';

src/core/payments/stripe.js

@@ -1,71 +1,32 @@
-/**
- * Stripe Payment Utilities
- * Generic Stripe integration for payment processing
- * 
- * Usage in modules:
- * import { createCheckoutSession, isEnabled } from '@zen/core/stripe';
- */
+import { createHash } from 'crypto';
+import Stripe from 'stripe';
 
-/**
- * Get Stripe instance
- * @returns {Promise<Object>} Stripe instance
- */
-export async function getStripe() {
+let _stripe = null;
+
+export function getStripe() {
   const secretKey = process.env.STRIPE_SECRET_KEY;
 
   if (!secretKey) {
     throw new Error('Stripe is not configured. Please set STRIPE_SECRET_KEY environment variable.');
   }
 
-  const Stripe = (await import('stripe')).default;
-  return new Stripe(secretKey, {
-    apiVersion: '2023-10-16',
-  });
+  if (!_stripe) {
+    _stripe = new Stripe(secretKey, { apiVersion: '2023-10-16' });
+  }
+
+  return _stripe;
 }
 
-/**
- * Check if Stripe is enabled
- * @returns {boolean}
- */
 export function isEnabled() {
   return !!(process.env.STRIPE_SECRET_KEY && process.env.STRIPE_PUBLISHABLE_KEY);
 }
 
-/**
- * Get Stripe publishable key (for client-side)
- * @returns {string|null}
- */
 export function getPublishableKey() {
   return process.env.STRIPE_PUBLISHABLE_KEY || null;
 }
 
-/**
- * Create a checkout session
- * @param {Object} options - Checkout options
- * @param {Array} options.lineItems - Line items for checkout
- * @param {string} options.successUrl - Success redirect URL
- * @param {string} options.cancelUrl - Cancel redirect URL
- * @param {string} options.customerEmail - Customer email
- * @param {Object} options.metadata - Additional metadata
- * @param {string} options.mode - Payment mode (default: 'payment')
- * @returns {Promise<Object>} Stripe session object
- * 
- * @example
- * const session = await createCheckoutSession({
- *   lineItems: [{
- *     price_data: {
- *       currency: 'usd',
- *       product_data: { name: 'Product' },
- *       unit_amount: 1000,
- *     },
- *     quantity: 1,
- *   }],
- *   successUrl: 'https://example.com/success',
- *   cancelUrl: 'https://example.com/cancel',
- * });
- */
 export async function createCheckoutSession(options) {
-  const stripe = await getStripe();
+  const stripe = getStripe();
 
   const {
     lineItems,
@@ -74,12 +35,10 @@ export async function createCheckoutSession(options) {
     customerEmail,
     metadata = {},
     mode = 'payment',
-    paymentMethodTypes = ['card'],
     clientReferenceId,
   } = options;
 
   const sessionConfig = {
-    payment_method_types: paymentMethodTypes,
     line_items: lineItems,
     mode,
     success_url: successUrl,
@@ -87,27 +46,14 @@ export async function createCheckoutSession(options) {
     metadata,
   };
 
-  if (customerEmail) {
-    sessionConfig.customer_email = customerEmail;
+  if (customerEmail) sessionConfig.customer_email = customerEmail;
+  if (clientReferenceId) sessionConfig.client_reference_id = clientReferenceId;
+
+  return stripe.checkout.sessions.create(sessionConfig);
 }
 
-  if (clientReferenceId) {
-    sessionConfig.client_reference_id = clientReferenceId;
-  }
-  
-  return await stripe.checkout.sessions.create(sessionConfig);
-}
-
-/**
- * Create a payment intent
- * @param {Object} options - Payment options
- * @param {number} options.amount - Amount in cents
- * @param {string} options.currency - Currency code
- * @param {Object} options.metadata - Additional metadata
- * @returns {Promise<Object>} Stripe payment intent
- */
 export async function createPaymentIntent(options) {
-  const stripe = await getStripe();
+  const stripe = getStripe();
 
   const {
     amount,
@@ -116,7 +62,7 @@ export async function createPaymentIntent(options) {
     automaticPaymentMethods = { enabled: true },
   } = options;
 
-  return await stripe.paymentIntents.create({
+  return stripe.paymentIntents.create({
     amount,
     currency,
     metadata,
@@ -124,62 +70,27 @@ export async function createPaymentIntent(options) {
   });
 }
 
-/**
- * Retrieve a checkout session
- * @param {string} sessionId - Session ID
- * @returns {Promise<Object>} Stripe session
- */
 export async function getCheckoutSession(sessionId) {
-  const stripe = await getStripe();
-  return await stripe.checkout.sessions.retrieve(sessionId);
+  return getStripe().checkout.sessions.retrieve(sessionId);
 }
 
-/**
- * Retrieve a payment intent
- * @param {string} paymentIntentId - Payment intent ID
- * @returns {Promise<Object>} Stripe payment intent
- */
 export async function getPaymentIntent(paymentIntentId) {
-  const stripe = await getStripe();
-  return await stripe.paymentIntents.retrieve(paymentIntentId);
+  return getStripe().paymentIntents.retrieve(paymentIntentId);
 }
 
-/**
- * Verify webhook signature
- * @param {string} payload - Raw request body
- * @param {string} signature - Stripe-Signature header
- * @param {string} secret - Webhook secret (optional, uses env if not provided)
- * @returns {Promise<Object>} Verified event
- */
-export async function verifyWebhookSignature(payload, signature, secret = null) {
-  const stripe = await getStripe();
-  const webhookSecret = secret || process.env.STRIPE_WEBHOOK_SECRET;
+export async function verifyWebhookSignature(payload, signature) {
+  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
 
   if (!webhookSecret) {
     throw new Error('Stripe webhook secret is not configured');
   }
 
-  return stripe.webhooks.constructEvent(payload, signature, webhookSecret);
+  return getStripe().webhooks.constructEvent(payload, signature, webhookSecret);
 }
 
-/**
- * Create a customer
- * @param {Object} options - Customer options
- * @param {string} options.email - Customer email
- * @param {string} options.name - Customer name
- * @param {Object} options.metadata - Additional metadata
- * @returns {Promise<Object>} Stripe customer
- */
 export async function createCustomer(options) {
-  const stripe = await getStripe();
-  
   const { email, name, metadata = {} } = options;
-  
-  return await stripe.customers.create({
-    email,
-    name,
-    metadata,
-  });
+  return getStripe().customers.create({ email, name, metadata });
 }
 
 /**
@@ -190,93 +101,28 @@ export async function createCustomer(options) {
  * for the same email, we use an idempotency key derived from the email address.
  * If a duplicate is created despite this guard (extremely unlikely), operators
  * should merge duplicates via the Stripe dashboard or a reconciliation job.
- *
- * @param {string} email - Customer email
- * @param {Object} defaultData - Default data if creating new customer
- * @returns {Promise<Object>} Stripe customer
  */
 export async function getOrCreateCustomer(email, defaultData = {}) {
-  const stripe = await getStripe();
+  const stripe = getStripe();
 
-  // Search for existing customer first.
-  const existing = await stripe.customers.list({
-    email,
-    limit: 1,
-  });
+  const existing = await stripe.customers.list({ email, limit: 1 });
+  if (existing.data.length > 0) return existing.data[0];
 
-  if (existing.data.length > 0) {
-    return existing.data[0];
-  }
-
-  // Use a deterministic idempotency key so that concurrent requests for the
-  // same email address result in a single Stripe customer even if both pass
-  // the list-check above before either create completes.
-  const { createHash } = await import('crypto');
   const idempotencyKey = 'get-or-create-customer-' + createHash('sha256').update(email).digest('hex');
-
-  return await stripe.customers.create(
-    { email, ...defaultData },
-    { idempotencyKey }
-  );
+  return stripe.customers.create({ email, ...defaultData }, { idempotencyKey });
 }
 
-/**
- * List customer's payment methods
- * @param {string} customerId - Customer ID
- * @param {string} type - Payment method type (default: 'card')
- * @returns {Promise<Array>} List of payment methods
- */
 export async function listPaymentMethods(customerId, type = 'card') {
-  const stripe = await getStripe();
-  
-  const methods = await stripe.paymentMethods.list({
-    customer: customerId,
-    type,
-  });
-  
+  const methods = await getStripe().paymentMethods.list({ customer: customerId, type });
   return methods.data;
 }
 
-/**
- * Create a refund
- * @param {Object} options - Refund options
- * @param {string} options.paymentIntentId - Payment intent to refund
- * @param {number} options.amount - Amount to refund in cents (optional, full refund if not specified)
- * @param {string} options.reason - Reason for refund
- * @returns {Promise<Object>} Stripe refund
- */
 export async function createRefund(options) {
-  const stripe = await getStripe();
-  
   const { paymentIntentId, amount, reason } = options;
 
-  const refundConfig = {
-    payment_intent: paymentIntentId,
-  };
+  const refundConfig = { payment_intent: paymentIntentId };
+  if (amount) refundConfig.amount = amount;
+  if (reason) refundConfig.reason = reason;
 
-  if (amount) {
-    refundConfig.amount = amount;
+  return getStripe().refunds.create(refundConfig);
 }
-  
-  if (reason) {
-    refundConfig.reason = reason;
-  }
-  
-  return await stripe.refunds.create(refundConfig);
-}
-
-// Default export for convenience
-export default {
-  getStripe,
-  isEnabled,
-  getPublishableKey,
-  createCheckoutSession,
-  createPaymentIntent,
-  getCheckoutSession,
-  getPaymentIntent,
-  verifyWebhookSignature,
-  createCustomer,
-  getOrCreateCustomer,
-  listPaymentMethods,
-  createRefund,
-};

src/core/pdf/README.md

@@ -0,0 +1,142 @@
+# PDF Framework
+
+Ce répertoire re-exporte les primitives de [`@react-pdf/renderer`](https://react-pdf.org) et fournit un utilitaire de nommage de fichiers. Il ne contient aucun template métier — les features créent leurs propres documents et utilisent ce module pour le rendu.
+
+---
+
+## Structure
+
+```
+src/core/pdf/
+└── index.js     re-exports @react-pdf/renderer + getFilename
+```
+
+---
+
+## Import
+
+```js
+import {
+  renderToBuffer,
+  Document,
+  Page,
+  View,
+  Text,
+  Image,
+  Link,
+  StyleSheet,
+  Font,
+  getFilename,
+} from '@zen/core/pdf';
+```
+
+---
+
+## API
+
+### `renderToBuffer(element)`
+
+Rend un document React PDF en `Buffer`. Retourne une `Promise<Buffer>`.
+
+```js
+import { renderToBuffer, Document, Page, Text } from '@zen/core/pdf';
+
+const buffer = await renderToBuffer(
+  <Document>
+    <Page>
+      <Text>Bonjour</Text>
+    </Page>
+  </Document>
+);
+```
+
+Utiliser ce buffer pour servir le PDF en réponse HTTP ou l'écrire sur disque.
+
+---
+
+### `getFilename(prefix, identifier, date?)`
+
+Retourne un nom de fichier normalisé pour un PDF.
+
+```js
+getFilename('invoice', '12345')
+// 'invoice-12345-2024-01-15.pdf'
+
+getFilename('receipt', 'ORD-99', new Date('2024-06-01'))
+// 'receipt-ORD-99-2024-06-01.pdf'
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `string` | Type de document (`invoice`, `receipt`, etc.) |
+| `identifier` | `string` | Identifiant unique (numéro de commande, ID, etc.) |
+| `date` | `Date` | Date du document (défaut : aujourd'hui) |
+
+---
+
+### Primitives re-exportées
+
+Toutes les primitives de `@react-pdf/renderer` sont disponibles directement depuis `@zen/core/pdf` :
+
+| Export | Description |
+|--------|-------------|
+| `Document` | Racine d'un document PDF |
+| `Page` | Page du document |
+| `View` | Conteneur (équivalent `div`) |
+| `Text` | Bloc de texte |
+| `Image` | Image (URL ou base64) |
+| `Link` | Lien hypertexte |
+| `StyleSheet` | Création de styles (similaire à `StyleSheet.create` React Native) |
+| `Font` | Enregistrement de polices personnalisées |
+
+---
+
+## Créer un template depuis une feature
+
+Les templates vivent **avec leur feature**, pas dans ce répertoire.
+
+```jsx
+// src/features/orders/pdf/InvoiceDocument.js
+import { Document, Page, View, Text, StyleSheet } from '@zen/core/pdf';
+
+const styles = StyleSheet.create({
+  page: { padding: 40 },
+  title: { fontSize: 20, marginBottom: 16 },
+});
+
+export const InvoiceDocument = ({ order }) => (
+  <Document>
+    <Page style={styles.page}>
+      <Text style={styles.title}>Facture #{order.number}</Text>
+      <Text>{order.customerName}</Text>
+    </Page>
+  </Document>
+);
+```
+
+```js
+// src/features/orders/pdf/sendInvoice.js
+import { renderToBuffer, getFilename } from '@zen/core/pdf';
+import { InvoiceDocument } from './InvoiceDocument.js';
+
+export async function generateInvoicePdf(order) {
+  const buffer = await renderToBuffer(<InvoiceDocument order={order} />);
+  const filename = getFilename('invoice', order.number);
+  return { buffer, filename };
+}
+```
+
+```js
+// Next.js Route Handler
+export async function GET(req, { params }) {
+  const order = await getOrder(params.id);
+  const { buffer, filename } = await generateInvoicePdf(order);
+
+  return new Response(buffer, {
+    headers: {
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': `attachment; filename="${filename}"`,
+    },
+  });
+}
+```

src/core/pdf/index.js

@@ -1,121 +1,9 @@
-/**
- * PDF Generation Utilities
- * Wrapper around @react-pdf/renderer for PDF generation
- * 
- * Usage in modules:
- * import { renderToBuffer } from '@zen/core/pdf';
- */
-
-import { renderToBuffer as reactPdfRenderToBuffer } from '@react-pdf/renderer';
-import React from 'react';
+export { renderToBuffer, Document, Page, View, Text, Image, Link, StyleSheet, Font } from '@react-pdf/renderer';
 
 /**
- * Render a React PDF document to a buffer
- * @param {React.Element} document - React PDF document element
- * @returns {Promise<Buffer>} PDF buffer
- * 
- * @example
- * import { Document, Page, Text } from '@react-pdf/renderer';
- * 
- * const MyDoc = () => (
- *   <Document>
- *     <Page>
- *       <Text>Hello World</Text>
- *     </Page>
- *   </Document>
- * );
- * 
- * const buffer = await renderToBuffer(<MyDoc />);
- */
-export async function renderToBuffer(document) {
-  return await reactPdfRenderToBuffer(document);
-}
-
-/**
- * Create a React element for PDF rendering
- * @param {Function} Component - React component
- * @param {Object} props - Component props
- * @returns {React.Element}
- */
-export function createElement(Component, props) {
-  return React.createElement(Component, props);
-}
-
-/**
- * Get a suggested filename for a PDF
- * @param {string} prefix - Filename prefix
- * @param {string|number} identifier - Unique identifier
- * @param {Date} date - Date for the filename (default: today)
- * @returns {string} Suggested filename
- * 
- * @example
- * getFilename('invoice', '12345'); // 'invoice-12345-2024-01-15.pdf'
+ * Get a suggested filename for a PDF.
+ * @example getFilename('invoice', '12345') // 'invoice-12345-2024-01-15.pdf'
  */
 export function getFilename(prefix, identifier, date = new Date()) {
-  const dateStr = date.toISOString().split('T')[0];
-  return `${prefix}-${identifier}-${dateStr}.pdf`;
+  return `${prefix}-${identifier}-${date.toISOString().split('T')[0]}.pdf`;
 }
-
-/**
- * Convert centimeters to points (for PDF dimensions)
- * @param {number} cm - Centimeters
- * @returns {number} Points
- */
-export function cmToPoints(cm) {
-  return cm * 28.3465;
-}
-
-/**
- * Convert inches to points (for PDF dimensions)
- * @param {number} inches - Inches
- * @returns {number} Points
- */
-export function inchesToPoints(inches) {
-  return inches * 72;
-}
-
-/**
- * Convert millimeters to points (for PDF dimensions)
- * @param {number} mm - Millimeters
- * @returns {number} Points
- */
-export function mmToPoints(mm) {
-  return mm * 2.83465;
-}
-
-/**
- * Common page sizes in points
- */
-export const PAGE_SIZES = {
-  A4: { width: 595.28, height: 841.89 },
-  LETTER: { width: 612, height: 792 },
-  LEGAL: { width: 612, height: 1008 },
-  A3: { width: 841.89, height: 1190.55 },
-  A5: { width: 419.53, height: 595.28 },
-};
-
-// Re-export react-pdf components for convenience
-export { 
-  Document,
-  Page,
-  View,
-  Text,
-  Image,
-  Link,
-  StyleSheet,
-  Font,
-  PDFViewer,
-  BlobProvider,
-  PDFDownloadLink,
-} from '@react-pdf/renderer';
-
-// Default export
-export default {
-  renderToBuffer,
-  createElement,
-  getFilename,
-  cmToPoints,
-  inchesToPoints,
-  mmToPoints,
-  PAGE_SIZES,
-};

src/core/public-pages/PublicModulePage.server.js

@@ -0,0 +1,28 @@
+import { notFound } from 'next/navigation';
+import { getPublicModulePage } from './registry.js';
+
+/**
+ * Composant serveur RSC catch-all pour `/zen/<module>/<...>`.
+ *
+ * Next.js route ce composant via un segment `[...path]`. Le premier segment
+ * identifie le module ; le reste est passé au composant enregistré qui fait
+ * son propre routage interne.
+ *
+ * `/zen/api/...` est intercepté en amont par la route API (`route.js`) qui
+ * est plus spécifique pour Next.js — ce composant ne le verra jamais en
+ * pratique, mais on garde le filtre par sûreté.
+ */
+export default async function PublicModulePage({ params }) {
+  const resolved = await params;
+  const path = Array.isArray(resolved?.path) ? resolved.path : [];
+
+  if (path.length === 0) notFound();
+  const [moduleName, ...rest] = path;
+  if (moduleName === 'api') notFound();
+
+  const entry = getPublicModulePage(moduleName);
+  if (!entry) notFound();
+
+  const { Component } = entry;
+  return <Component params={resolved} segments={rest} />;
+}

src/core/public-pages/README.md

@@ -0,0 +1,37 @@
+# Public Module Pages
+
+Registre runtime pour les pages publiques `/zen/<module>/<...>` ajoutées par les modules externes.
+
+## Concept
+
+Tout chemin `/zen/<segment>/...` (sauf `/zen/api/...` réservé aux routes API) est résolu vers le composant enregistré sous `<segment>`. Le module gère son routage interne.
+
+## API
+
+```js
+import { registerPublicModulePage } from '@zen/core/public-pages';
+
+registerPublicModulePage({
+  moduleName: 'billing',
+  Component: BillingRouter,
+  title: 'Facturation',
+});
+```
+
+Le composant reçoit `{ params, segments }` :
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `params` | `object` | Paramètres Next.js résolus (incluant `path`). |
+| `segments` | `string[]` | Segments d'URL après `/zen/<moduleName>/`. Le module fait son propre routage. |
+
+Exemple : `/zen/billing/invoice/abc-123` → `segments = ['invoice', 'abc-123']`.
+
+## Câblage côté projet consommateur
+
+Le scaffolder `@zen/start` génère automatiquement `app/zen/[...path]/page.js` qui ré-exporte le composant serveur. Aucune action manuelle requise.
+
+## Restrictions
+
+- Le moduleName `api` est réservé et lève une exception à l'enregistrement.
+- Un seul composant par moduleName ; un appel ultérieur écrase le précédent.

src/core/public-pages/index.js

@@ -0,0 +1 @@
+export { registerPublicModulePage, getPublicModulePage, getPublicModulePages } from './registry.js';

src/core/public-pages/registry.js

@@ -0,0 +1,36 @@
+/**
+ * Registre runtime des pages publiques `/zen/<module>/<...>`.
+ *
+ * Chaque module externe enregistre un composant racine pour son namespace.
+ * Le composant reçoit `{ params, segments }` où `segments` est le tableau
+ * de chemins après `/zen/<module>/` ; le module fait son propre routage interne.
+ *
+ * Le préfixe `api` est réservé : tout enregistrement sous moduleName === 'api'
+ * est rejeté pour éviter les collisions avec les routes API.
+ */
+
+const REGISTRY_KEY = Symbol.for('__ZEN_PUBLIC_MODULE_PAGES__');
+if (!globalThis[REGISTRY_KEY]) globalThis[REGISTRY_KEY] = new Map();
+/** @type {Map<string, { moduleName: string, Component: any, title?: string }>} */
+const registry = globalThis[REGISTRY_KEY];
+
+export function registerPublicModulePage({ moduleName, Component, title }) {
+  if (typeof moduleName !== 'string' || !moduleName) {
+    throw new TypeError('registerPublicModulePage: "moduleName" must be a non-empty string');
+  }
+  if (moduleName === 'api') {
+    throw new Error('registerPublicModulePage: "api" is a reserved namespace under /zen/');
+  }
+  if (typeof Component !== 'function' && typeof Component !== 'object') {
+    throw new TypeError(`registerPublicModulePage(${moduleName}): "Component" must be a React component`);
+  }
+  registry.set(moduleName, { moduleName, Component, title });
+}
+
+export function getPublicModulePage(moduleName) {
+  return registry.get(moduleName);
+}
+
+export function getPublicModulePages() {
+  return [...registry.values()];
+}

src/core/storage/README.md

@@ -0,0 +1,283 @@
+# Storage
+
+Ce répertoire est le **module de stockage de fichiers**. Il fournit une couche d'accès générique aux providers S3-compatibles (Cloudflare R2, Backblaze B2) : upload, téléchargement, suppression, listage, URL présignées et validation de fichiers. Il gère également le système de contrôle d'accès aux fichiers servis via HTTP.
+
+Il ne connaît aucune feature spécifique — les features l'importent pour leurs propres besoins et enregistrent leurs propres policies d'accès.
+
+---
+
+## Structure
+
+```
+src/core/storage/
+├── index.js         Exports publics (uploadFile, deleteFile, validateUpload…)
+├── api.js           Route HTTP /zen/api/storage/** avec contrôle d'accès par chemin
+├── storage-config.js  Enregistrement des policies et préfixes publics
+├── utils.js         Validation de fichiers, MIME types, magic bytes
+├── signing.js       Signature AWS Signature V4 pour requêtes S3-compatibles
+├── cloudflare-r2.js Configuration provider Cloudflare R2
+└── backblaze.js     Configuration provider Backblaze B2
+```
+
+---
+
+## Variables d'environnement
+
+| Variable | Rôle |
+|----------|------|
+| `ZEN_STORAGE_PROVIDER` | Provider à utiliser : `r2` (défaut) ou `backblaze` |
+| `ZEN_R2_ACCOUNT_ID` | ID de compte Cloudflare (R2) |
+| `ZEN_R2_ACCESS_KEY_ID` | Clé d'accès R2 |
+| `ZEN_R2_SECRET_ACCESS_KEY` | Secret R2 |
+| `ZEN_R2_BUCKET_NAME` | Nom du bucket R2 |
+| `ZEN_B2_KEY_ID` | ID de clé Backblaze B2 |
+| `ZEN_B2_APPLICATION_KEY` | Clé d'application Backblaze B2 |
+| `ZEN_B2_BUCKET_NAME` | Nom du bucket Backblaze B2 |
+| `ZEN_B2_ENDPOINT` | Endpoint S3 Backblaze (ex: `s3.us-west-004.backblazeb2.com`) |
+
+---
+
+## Système de contrôle d'accès
+
+### Principe : tout est privé par défaut
+
+Aucun fichier n'est accessible sans configuration explicite. Pour qu'un fichier soit servi via `/zen/api/storage/**`, son chemin doit correspondre à l'un des deux mécanismes déclarés pendant `initializeZen()` : un préfixe public ou une policy d'accès.
+
+### Préfixes publics
+
+Les fichiers dont le chemin commence par un préfixe public sont servis **sans authentification**. Utile pour les assets publics (logos, images de produits…).
+
+Le chemin doit avoir au minimum la forme `{prefixe}/{id}/{fichier}` — un préfixe seul ne suffit pas à exposer des fichiers.
+
+```js
+// src/features/myfeature/storage-policies.js
+export const storagePublicPrefixes = ['products'];
+// products/abc123/photo.webp → accessible sans session
+```
+
+### Policies d'accès (chemins privés)
+
+Pour les chemins privés, une policy doit correspondre au premier segment du chemin (`pathParts[0]`). Deux types sont disponibles :
+
+| Type | Règle |
+|------|-------|
+| `owner` | `pathParts[1]` doit être l'ID de l'utilisateur connecté. Les admins ont accès à tout. |
+| `admin` | L'utilisateur doit avoir le rôle `admin`. |
+
+```js
+// src/features/myfeature/storage-policies.js
+export const storageAccessPolicies = [
+  { prefix: 'users',     type: 'owner' },  // users/{userId}/...
+  { prefix: 'invoices',  type: 'admin'  },  // invoices/...
+];
+```
+
+### Enregistrement dans initializeZen()
+
+```js
+// src/shared/lib/init.js
+import { registerStoragePolicies, registerStoragePublicPrefixes } from '@zen/core/storage';
+import { storageAccessPolicies, storagePublicPrefixes } from '../../features/myfeature/storage-policies.js';
+
+registerStoragePolicies(storageAccessPolicies);
+registerStoragePublicPrefixes(storagePublicPrefixes); // si nécessaire
+```
+
+L'enregistrement est **additif** — plusieurs features peuvent appeler `registerStoragePolicies` indépendamment.
+
+---
+
+## Fonctions d'opération
+
+Toutes les fonctions retournent un objet `{ success, data, error }`. Elles ne lèvent jamais d'exception — les erreurs sont journalisées côté serveur et encapsulées dans `error`.
+
+### `uploadFile({ key, body, contentType, metadata?, cacheControl? })`
+
+Upload générique.
+
+```js
+const result = await uploadFile({
+  key: 'users/abc123/profile/avatar_xxx.webp',
+  body: buffer,
+  contentType: 'image/webp',
+  metadata: { userId: 'abc123' },
+});
+if (!result.success) throw new Error(result.error);
+```
+
+### `uploadImage({ key, body, contentType, metadata? })`
+
+Équivalent à `uploadFile` avec `Cache-Control: public, max-age=31536000` (1 an).
+
+### `deleteFile(key)`
+
+Supprime un fichier.
+
+```js
+await deleteFile('users/abc123/profile/avatar_xxx.webp');
+```
+
+### `deleteFiles(keys[])`
+
+Suppression en lot (S3 DeleteObjects). Retourne les clés supprimées et les erreurs éventuelles.
+
+```js
+const { data } = await deleteFiles(['a.jpg', 'b.jpg']);
+// data.deleted → [{ Key: 'a.jpg' }, …]
+// data.errors  → []
+```
+
+### `getFile(key)`
+
+Récupère le contenu et les métadonnées d'un fichier.
+
+```js
+const { data } = await getFile('users/abc123/profile/avatar.webp');
+// data.body, data.contentType, data.contentLength, data.lastModified, data.metadata
+```
+
+### `getFileMetadata(key)`
+
+Requête HEAD : métadonnées uniquement, sans télécharger le contenu.
+
+### `fileExists(key)`
+
+Retourne `true` si le fichier existe.
+
+```js
+if (await fileExists('users/abc123/profile/avatar.webp')) { … }
+```
+
+### `listFiles({ prefix?, maxKeys?, continuationToken? })`
+
+Liste les fichiers avec pagination (max 1 000 par appel).
+
+```js
+const { data } = await listFiles({ prefix: 'users/abc123/', maxKeys: 100 });
+// data.files → [{ key, size, lastModified, etag }, …]
+// data.isTruncated, data.nextContinuationToken
+```
+
+### `getPresignedUrl({ key, expiresIn?, operation? })`
+
+Génère une URL signée temporaire. `expiresIn` en secondes (défaut 3600, max 604 800 = 7 jours). `operation` : `'get'` (défaut) ou `'put'`.
+
+```js
+const { data } = await getPresignedUrl({ key: 'docs/contrat.pdf', expiresIn: 300 });
+// data.url → URL signée valide 5 minutes
+```
+
+### `copyFile({ sourceKey, destinationKey })`
+
+Copie un fichier dans le même bucket.
+
+### `moveFile({ sourceKey, destinationKey })`
+
+Copie puis supprime la source. Si la suppression échoue, le fichier copié est conservé (non-fatal).
+
+### `proxyFile(key, { filename? })`
+
+Récupère un fichier pour le streamer directement au client.
+
+---
+
+## Validation de fichiers
+
+### `validateUpload({ filename, size, allowedTypes, maxSize, buffer? })`
+
+Validation complète avant upload. Retourne `{ valid, errors[] }`.
+
+```js
+const { valid, errors } = validateUpload({
+  filename: file.name,
+  size:     buffer.byteLength,
+  allowedTypes: FILE_TYPE_PRESETS.IMAGES,
+  maxSize:      FILE_SIZE_LIMITS.AVATAR,
+  buffer,
+});
+if (!valid) return apiError('Bad Request', errors[0]);
+```
+
+Couches de validation appliquées dans l'ordre :
+1. Nom de fichier requis
+2. SVG explicitement interdit (risque d'exécution de scripts)
+3. Extension contre la liste blanche `allowedTypes`
+4. Taille contre `maxSize`
+5. *(si buffer fourni)* Magic bytes — assertion positive que l'extension correspond au contenu réel
+6. *(si buffer fourni)* Scan des 512 premiers octets pour HTML/SVG/XML (défense contre les fichiers polyglots)
+
+### `FILE_TYPE_PRESETS`
+
+| Constante | Extensions |
+|-----------|-----------|
+| `IMAGES` | `.jpg` `.jpeg` `.png` `.gif` `.webp` |
+| `IMAGES_NO_GIF` | `.jpg` `.jpeg` `.png` `.webp` |
+| `DOCUMENTS` | `.pdf` `.doc` `.docx` `.xls` `.xlsx` `.ppt` `.pptx` `.txt` `.csv` |
+| `PDF_ONLY` | `.pdf` |
+| `VIDEOS` | `.mp4` `.avi` `.mov` `.wmv` |
+| `AUDIO` | `.mp3` `.wav` |
+| `ARCHIVES` | `.zip` `.rar` `.7z` `.tar` `.gz` |
+
+### `FILE_SIZE_LIMITS`
+
+| Constante | Limite |
+|-----------|--------|
+| `AVATAR` | 5 MB |
+| `IMAGE` | 10 MB |
+| `DOCUMENT` | 50 MB |
+| `VIDEO` | 500 MB |
+| `LARGE_FILE` | 1 GB |
+
+### Fonctions utilitaires
+
+| Fonction | Description |
+|----------|-------------|
+| `generateUniqueFilename(originalName, prefix?)` | Génère `{prefix}_{timestamp}_{hash}{ext}` |
+| `getFileExtension(filename)` | Retourne l'extension avec le point (`.jpg`) ou `''` |
+| `getMimeType(filename)` | Retourne le MIME type depuis l'extension |
+| `validateFileType(filename, allowedTypes)` | Vérifie l'extension contre une liste |
+| `validateFileSize(size, maxSize)` | Vérifie la taille |
+| `formatFileSize(bytes)` | Formate en lisible humain (`1.5 MB`) |
+| `sanitizeFilename(filename)` | Supprime les caractères spéciaux |
+
+---
+
+## Usage depuis une feature
+
+```js
+// src/features/media/api.js
+import { uploadImage, deleteFile, validateUpload, FILE_TYPE_PRESETS, FILE_SIZE_LIMITS, generateUniqueFilename } from '../../core/storage/index.js';
+
+export async function uploadAvatar(userId, file, buffer) {
+  const { valid, errors } = validateUpload({
+    filename:     file.name,
+    size:         buffer.byteLength,
+    allowedTypes: FILE_TYPE_PRESETS.IMAGES,
+    maxSize:      FILE_SIZE_LIMITS.AVATAR,
+    buffer,
+  });
+  if (!valid) throw new Error(errors[0]);
+
+  const filename = generateUniqueFilename(file.name, 'avatar');
+  const key = `users/${userId}/profile/${filename}`;
+
+  const result = await uploadImage({ key, body: buffer, contentType: getMimeType(file.name) });
+  if (!result.success) throw new Error('Upload failed');
+
+  return key;
+}
+```
+
+```js
+// src/features/media/storage-policies.js  ← la feature déclare ses propres policies
+export const storageAccessPolicies = [
+  { prefix: 'users', type: 'owner' },
+];
+```
+
+## Usage depuis un module
+
+```js
+// src/modules/mymodule/actions.js
+import { uploadFile, deleteFile, generateUniqueFilename } from '@zen/core/storage';
+```

src/core/storage/api.js

@@ -0,0 +1,131 @@
+/**
+ * Storage Feature — API Routes
+ *
+ * Serves files from storage with path-based access control.
+ *
+ * Auth note: this route is declared as auth: 'public' in the route definition
+ * because access policy depends on the file path, not a single role.
+ * The handler enforces its own rules:
+ *   - Public prefix paths  → no session required
+ *   - All other paths      → session required; access governed by registered policies
+ *   - Unknown paths        → denied
+ *
+ * Call registerStoragePolicies() and registerStoragePublicPrefixes() during
+ * initializeZen before the first request, following the same pattern as
+ * registerFeatureRoutes in core/api/runtime.js.
+ */
+
+import { getSessionCookieName } from '@zen/core/shared/config';
+import { getSessionResolver } from '../api/router.js';
+import { getFile } from './index.js';
+import { fail } from '@zen/core/shared/logger';
+import { defineApiRoutes } from '../api/define.js';
+import { apiError } from '../api/respond.js';
+import { getStoragePublicPrefixes, getStorageAccessPolicies } from './storage-config.js';
+
+const COOKIE_NAME = getSessionCookieName();
+
+// ─── Handlers ─────────────────────────────────────────────────────────────────
+
+async function handleGetFile(_request, { wildcard: fileKey }) {
+  try {
+    if (!fileKey) {
+      return apiError('Bad Request', 'File path is required');
+    }
+
+    // Reject path traversal sequences, empty segments, and null bytes before
+    // passing the key to the storage backend. Next.js decodes percent-encoding
+    // before populating [...path], so '..' and '.' arrive as literal values.
+    const pathParts = fileKey.split('/');
+    if (
+      pathParts.some(seg => seg === '..' || seg === '.' || seg === '') ||
+      fileKey.includes('\0')
+    ) {
+      return apiError('Bad Request', 'Invalid file path');
+    }
+
+    // Public prefixes: declared by each module via defineModule() storagePublicPrefixes.
+    // Files whose path starts with a declared prefix are served without authentication.
+    // The path must have at least two segments beyond the prefix
+    // ({...prefix}/{id}/{filename}) to prevent unintentional root-level exposure.
+    const publicPrefixes = getStoragePublicPrefixes();
+    const matchedPrefix  = publicPrefixes.find(prefix => fileKey.startsWith(prefix + '/'));
+    if (matchedPrefix) {
+      const prefixDepth = matchedPrefix.split('/').length;
+      if (pathParts.length < prefixDepth + 2) {
+        return apiError('Bad Request', 'Invalid file path');
+      }
+      return await fetchFile(fileKey);
+    }
+
+    // Require authentication for all other paths.
+    const { cookies } = await import('next/headers');
+    const cookieStore  = await cookies();
+    const sessionToken = cookieStore.get(COOKIE_NAME)?.value;
+
+    if (!sessionToken) {
+      return apiError('Unauthorized', 'Authentication required to access files');
+    }
+
+    const session = await getSessionResolver()(sessionToken);
+
+    if (!session) {
+      return apiError('Unauthorized', 'Invalid or expired session');
+    }
+
+    // Path-based access control driven by policies declared in each module.
+    const policies = getStorageAccessPolicies();
+    const policy   = policies.find(p => pathParts[0] === p.prefix);
+
+    if (!policy) {
+      return apiError('Forbidden', 'Invalid file path');
+    }
+
+    if (policy.type === 'owner') {
+      // Owner-scoped: pathParts[1] is the resource owner ID (e.g. users/{userId}/...)
+      if (session.user.id !== pathParts[1] && session.user.role !== 'admin') {
+        return apiError('Forbidden', 'You do not have permission to access this file');
+      }
+    } else if (policy.type === 'admin') {
+      if (session.user.role !== 'admin') {
+        return apiError('Forbidden', 'Admin access required for this file');
+      }
+    }
+
+    return await fetchFile(fileKey);
+  } catch (error) {
+    // Log full error server-side; never surface internal details to the client.
+    fail(`Storage: error serving file: ${error.message}`);
+    return apiError('Internal Server Error', 'Failed to retrieve file');
+  }
+}
+
+async function fetchFile(fileKey) {
+  const result = await getFile(fileKey);
+
+  if (!result.success) {
+    if (result.error.includes('NoSuchKey') || result.error.includes('not found')) {
+      return apiError('Not Found', 'File not found');
+    }
+    // Never forward raw storage error messages (which may contain bucket names
+    // or internal keys) to the client.
+    return apiError('Internal Server Error', 'Failed to retrieve file');
+  }
+
+  return {
+    success: true,
+    file: {
+      body:          result.data.body,
+      contentType:   result.data.contentType,
+      contentLength: result.data.contentLength,
+      lastModified:  result.data.lastModified,
+    },
+  };
+}
+
+// auth: 'public' — the handler enforces path-based access control internally.
+// The router calls it without a session; the handler reads cookies itself for
+// non-public paths.
+export const routes = defineApiRoutes([
+  { path: '/storage/**', method: 'GET', handler: handleGetFile, auth: 'public' }
+]);

src/core/storage/backblaze.js

@@ -0,0 +1,28 @@
+/**
+ * Backblaze B2 provider config (S3-compatible API).
+ * Reads ZEN_STORAGE_* environment variables.
+ *
+ * Endpoint format: s3.<region>.backblazeb2.com (e.g. s3.us-west-004.backblazeb2.com)
+ */
+
+export function getConfig() {
+  const host            = process.env.ZEN_STORAGE_ENDPOINT;
+  const region          = process.env.ZEN_STORAGE_REGION;
+  const accessKeyId     = process.env.ZEN_STORAGE_ACCESS_KEY;
+  const secretAccessKey = process.env.ZEN_STORAGE_SECRET_KEY;
+  const bucket          = process.env.ZEN_STORAGE_BUCKET;
+
+  if (!host || !accessKeyId || !secretAccessKey) {
+    throw new Error(
+      'Backblaze B2 credentials are not configured. Please set ZEN_STORAGE_ENDPOINT, ZEN_STORAGE_ACCESS_KEY, and ZEN_STORAGE_SECRET_KEY.'
+    );
+  }
+  if (!bucket) {
+    throw new Error('ZEN_STORAGE_BUCKET environment variable is not set.');
+  }
+  if (!region) {
+    throw new Error('ZEN_STORAGE_REGION environment variable is not set.');
+  }
+
+  return { accessKeyId, secretAccessKey, bucket, host, region };
+}

src/core/storage/cloudflare-r2.js

@@ -0,0 +1,23 @@
+/**
+ * Cloudflare R2 provider config.
+ * Reads ZEN_STORAGE_* environment variables.
+ */
+
+export function getConfig() {
+  const host            = process.env.ZEN_STORAGE_ENDPOINT;
+  const region          = process.env.ZEN_STORAGE_REGION ?? 'auto';
+  const accessKeyId     = process.env.ZEN_STORAGE_ACCESS_KEY;
+  const secretAccessKey = process.env.ZEN_STORAGE_SECRET_KEY;
+  const bucket          = process.env.ZEN_STORAGE_BUCKET;
+
+  if (!host || !accessKeyId || !secretAccessKey) {
+    throw new Error(
+      'Storage credentials are not configured. Please set ZEN_STORAGE_ENDPOINT, ZEN_STORAGE_ACCESS_KEY, and ZEN_STORAGE_SECRET_KEY.'
+    );
+  }
+  if (!bucket) {
+    throw new Error('ZEN_STORAGE_BUCKET environment variable is not set.');
+  }
+
+  return { accessKeyId, secretAccessKey, bucket, host, region };
+}

src/core/storage/index.js

@@ -1,265 +1,33 @@
-/**
- * Zen Storage Module - Cloudflare R2
- * Provides file upload, download, deletion, and management functionality
- * Uses native fetch + crypto (AWS Signature V4) — no external dependencies
- */
+import { createHash } from 'crypto';
+import { fail, warn, info } from '@zen/core/shared/logger';
+import {
+  signRequest,
+  buildPresignedUrl,
+  toBuffer,
+  xmlFirst,
+  xmlAll,
+  sanitizeHeaderValue,
+  escapeXml,
+  metaToHeaders,
+  headersToMeta,
+  encodePath,
+} from './signing.js';
 
-import { createHmac, createHash } from 'crypto';
-import { fail, warn, info } from '../../shared/lib/logger.js';
+// ─── Provider selection ───────────────────────────────────────────────────────
 
-// ─── AWS Signature V4 ────────────────────────────────────────────────────────
-
-function sha256hex(data) {
-  return createHash('sha256').update(data).digest('hex');
+async function getConfig() {
+  const provider = process.env.ZEN_STORAGE_PROVIDER ?? 'r2';
+  const { getConfig: providerGetConfig } = provider === 'backblaze'
+    ? await import('./backblaze.js')
+    : await import('./cloudflare-r2.js');
+  return providerGetConfig();
 }
 
-function hmac(key, data) {
-  return createHmac('sha256', Buffer.isBuffer(key) ? key : Buffer.from(key)).update(data).digest();
-}
+// ─── Storage functions ────────────────────────────────────────────────────────
 
-function hmacHex(key, data) {
-  return createHmac('sha256', Buffer.isBuffer(key) ? key : Buffer.from(key)).update(data).digest('hex');
-}
-
-function amzDate(date) {
-  return date.toISOString().replace(/[:\-]|\.\d{3}/g, '');
-}
-
-function dateStamp(date) {
-  return date.toISOString().slice(0, 10).replace(/-/g, '');
-}
-
-/**
- * Encode a string per AWS Signature V4 spec (encodes everything except A-Z a-z 0-9 - _ . ~)
- */
-function encodeS3(str) {
-  return encodeURIComponent(str)
-    .replace(/!/g, '%21')
-    .replace(/'/g, '%27')
-    .replace(/\(/g, '%28')
-    .replace(/\)/g, '%29')
-    .replace(/\*/g, '%2A');
-}
-
-/**
- * Encode a URI path, encoding each segment individually (preserving slashes)
- */
-function encodePath(path) {
-  return path
-    .split('/')
-    .map(segment => (segment ? encodeS3(segment) : ''))
-    .join('/');
-}
-
-function signingKey(secret, ds, region, service) {
-  const kDate = hmac('AWS4' + secret, ds);
-  const kRegion = hmac(kDate, region);
-  const kService = hmac(kRegion, service);
-  return hmac(kService, 'aws4_request');
-}
-
-/**
- * Sign an S3 request using AWS Signature V4.
- * Returns the full URL and the headers object to pass to fetch.
- */
-function signRequest({ method, host, path, query = {}, extraHeaders = {}, bodyBuffer, config, date }) {
-  const { accessKeyId, secretAccessKey } = config;
-  const region = 'auto';
-  const service = 's3';
-
-  const ts = amzDate(date);
-  const ds = dateStamp(date);
-  const bodyHash = sha256hex(bodyBuffer ?? Buffer.alloc(0));
-
-  const headers = {
-    host,
-    'x-amz-date': ts,
-    'x-amz-content-sha256': bodyHash,
-    ...extraHeaders,
-  };
-
-  const sortedHeaderKeys = Object.keys(headers).sort();
-  const canonicalHeaders = sortedHeaderKeys.map(k => `${k}:${headers[k]}\n`).join('');
-  const signedHeaders = sortedHeaderKeys.join(';');
-
-  const canonicalQueryString = Object.keys(query)
-    .sort()
-    .map(k => `${encodeS3(k)}=${encodeS3(query[k])}`)
-    .join('&');
-
-  const canonicalRequest = [
-    method,
-    encodePath(path),
-    canonicalQueryString,
-    canonicalHeaders,
-    signedHeaders,
-    bodyHash,
-  ].join('\n');
-
-  const scope = `${ds}/${region}/${service}/aws4_request`;
-  const stringToSign = ['AWS4-HMAC-SHA256', ts, scope, sha256hex(canonicalRequest)].join('\n');
-
-  const sig = hmacHex(signingKey(secretAccessKey, ds, region, service), stringToSign);
-  const auth = `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${sig}`;
-
-  const requestHeaders = { ...headers, Authorization: auth };
-  delete requestHeaders.host;
-
-  const url = canonicalQueryString
-    ? `https://${host}${path}?${canonicalQueryString}`
-    : `https://${host}${path}`;
-
-  return { url, headers: requestHeaders };
-}
-
-/**
- * Build a presigned URL (signature embedded in query string, no Authorization header).
- * The payload is marked UNSIGNED-PAYLOAD so no body hash is needed at signing time.
- */
-function buildPresignedUrl({ method, host, path, expiresIn, config, date }) {
-  const { accessKeyId, secretAccessKey } = config;
-  const region = 'auto';
-  const service = 's3';
-
-  const ts = amzDate(date);
-  const ds = dateStamp(date);
-  const scope = `${ds}/${region}/${service}/aws4_request`;
-
-  const query = {
-    'X-Amz-Algorithm': 'AWS4-HMAC-SHA256',
-    'X-Amz-Credential': `${accessKeyId}/${scope}`,
-    'X-Amz-Date': ts,
-    'X-Amz-Expires': String(expiresIn),
-    'X-Amz-SignedHeaders': 'host',
-  };
-
-  const canonicalQueryString = Object.keys(query)
-    .sort()
-    .map(k => `${encodeS3(k)}=${encodeS3(query[k])}`)
-    .join('&');
-
-  const canonicalRequest = [
-    method,
-    encodePath(path),
-    canonicalQueryString,
-    `host:${host}\n`,
-    'host',
-    'UNSIGNED-PAYLOAD',
-  ].join('\n');
-
-  const stringToSign = ['AWS4-HMAC-SHA256', ts, scope, sha256hex(canonicalRequest)].join('\n');
-  const sig = hmacHex(signingKey(secretAccessKey, ds, region, service), stringToSign);
-
-  return `https://${host}${path}?${canonicalQueryString}&X-Amz-Signature=${sig}`;
-}
-
-// ─── Config ──────────────────────────────────────────────────────────────────
-
-function getConfig() {
-  const region = process.env.ZEN_STORAGE_REGION;
-  const accessKeyId = process.env.ZEN_STORAGE_ACCESS_KEY;
-  const secretAccessKey = process.env.ZEN_STORAGE_SECRET_KEY;
-  const bucket = process.env.ZEN_STORAGE_BUCKET;
-
-  if (!region || !accessKeyId || !secretAccessKey) {
-    throw new Error(
-      'Storage credentials are not configured. Please set ZEN_STORAGE_REGION, ZEN_STORAGE_ACCESS_KEY, and ZEN_STORAGE_SECRET_KEY.'
-    );
-  }
-  if (!bucket) {
-    throw new Error('ZEN_STORAGE_BUCKET environment variable is not set');
-  }
-
-  return {
-    accessKeyId,
-    secretAccessKey,
-    bucket,
-    host: `${region}.r2.cloudflarestorage.com`,
-  };
-}
-
-// ─── Minimal XML helpers ─────────────────────────────────────────────────────
-
-function xmlFirst(xml, tag) {
-  const m = xml.match(new RegExp(`<${tag}[^>]*>(.*?)</${tag}>`, 's'));
-  return m ? m[1] : null;
-}
-
-function xmlAll(xml, tag) {
-  const re = new RegExp(`<${tag}[^>]*>(.*?)</${tag}>`, 'gs');
-  const results = [];
-  let m;
-  while ((m = re.exec(xml)) !== null) results.push(m[1]);
-  return results;
-}
-
-// ─── Body normalizer ─────────────────────────────────────────────────────────
-
-async function toBuffer(body) {
-  if (Buffer.isBuffer(body)) return body;
-  if (body instanceof Uint8Array) return Buffer.from(body);
-  if (typeof body === 'string') return Buffer.from(body, 'utf8');
-  if (body instanceof Blob) return Buffer.from(await body.arrayBuffer());
-  return Buffer.from(body);
-}
-
-// ─── Sanitization helpers ─────────────────────────────────────────────────────
-
-/**
- * Strip HTTP header injection characters (\r, \n, \0) from a header value.
- * A value containing these characters would break the canonical request format
- * and could allow an attacker to inject arbitrary signed headers.
- */
-function sanitizeHeaderValue(value) {
-  return String(value).replace(/[\r\n\0]/g, '');
-}
-
-/**
- * Escape XML special characters to prevent injection into the DeleteObjects payload.
- */
-function escapeXml(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;');
-}
-
-// ─── Metadata header helpers ─────────────────────────────────────────────────
-
-function metaToHeaders(metadata) {
-  return Object.fromEntries(
-    Object.entries(metadata).map(([k, v]) => [
-      `x-amz-meta-${sanitizeHeaderValue(k).toLowerCase()}`,
-      sanitizeHeaderValue(v),
-    ])
-  );
-}
-
-function headersToMeta(headers) {
-  return Object.fromEntries(
-    [...headers.entries()]
-      .filter(([k]) => k.startsWith('x-amz-meta-'))
-      .map(([k, v]) => [k.replace('x-amz-meta-', ''), v])
-  );
-}
-
-// ─── Storage functions ───────────────────────────────────────────────────────
-
-/**
- * Upload a file to storage
- * @param {Object} options
- * @param {string} options.key - File path/key in the bucket
- * @param {Buffer|string|Uint8Array|Blob} options.body - File content
- * @param {string} options.contentType - MIME type
- * @param {Object} options.metadata - Optional metadata key-value pairs
- * @param {string} options.cacheControl - Optional cache control header
- * @returns {Promise<Object>}
- */
 async function uploadFile({ key, body, contentType, metadata = {}, cacheControl }) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}/${key}`;
     const date = new Date();
     const bodyBuffer = await toBuffer(body);
@@ -270,16 +38,7 @@ async function uploadFile({ key, body, contentType, metadata = {}, cacheControl
       ...(cacheControl && { 'cache-control': sanitizeHeaderValue(cacheControl) }),
     };
 
-    const { url, headers } = signRequest({
-      method: 'PUT',
-      host: config.host,
-      path,
-      extraHeaders,
-      bodyBuffer,
-      config,
-      date,
-    });
-
+    const { url, headers } = signRequest({ method: 'PUT', host: config.host, path, extraHeaders, bodyBuffer, config, date });
     const response = await fetch(url, { method: 'PUT', headers, body: bodyBuffer });
 
     if (!response.ok) {
@@ -294,27 +53,13 @@ async function uploadFile({ key, body, contentType, metadata = {}, cacheControl
   }
 }
 
-/**
- * Upload an image with optimized settings
- * @param {Object} options
- * @param {string} options.key - File path/key in the bucket
- * @param {Buffer|Blob} options.body - Image content
- * @param {string} options.contentType - Image MIME type
- * @param {Object} options.metadata - Optional metadata
- * @returns {Promise<Object>}
- */
 async function uploadImage({ key, body, contentType, metadata = {} }) {
   return uploadFile({ key, body, contentType, metadata, cacheControl: 'public, max-age=31536000' });
 }
 
-/**
- * Delete a file from storage
- * @param {string} key - File path/key to delete
- * @returns {Promise<Object>}
- */
 async function deleteFile(key) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}/${key}`;
     const date = new Date();
 
@@ -333,14 +78,9 @@ async function deleteFile(key) {
   }
 }
 
-/**
- * Delete multiple files from storage
- * @param {string[]} keys - Array of file paths/keys to delete
- * @returns {Promise<Object>}
- */
 async function deleteFiles(keys) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}`;
     const date = new Date();
 
@@ -384,14 +124,9 @@ async function deleteFiles(keys) {
   }
 }
 
-/**
- * Get a file from storage
- * @param {string} key - File path/key to retrieve
- * @returns {Promise<Object>} File data with metadata
- */
 async function getFile(key) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}/${key}`;
     const date = new Date();
 
@@ -425,14 +160,9 @@ async function getFile(key) {
   }
 }
 
-/**
- * Get file metadata without downloading the file
- * @param {string} key - File path/key
- * @returns {Promise<Object>} File metadata
- */
 async function getFileMetadata(key) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}/${key}`;
     const date = new Date();
 
@@ -463,27 +193,14 @@ async function getFileMetadata(key) {
   }
 }
 
-/**
- * Check if a file exists in storage
- * @param {string} key - File path/key to check
- * @returns {Promise<boolean>}
- */
 async function fileExists(key) {
   const result = await getFileMetadata(key);
   return result.success;
 }
 
-/**
- * List files in a directory/prefix
- * @param {Object} options
- * @param {string} options.prefix - Directory prefix (e.g., 'users/123/')
- * @param {number} options.maxKeys - Maximum number of keys to return (default: 1000)
- * @param {string} options.continuationToken - Token for pagination
- * @returns {Promise<Object>}
- */
 async function listFiles({ prefix = '', maxKeys = 1000, continuationToken } = {}) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path = `/${config.bucket}`;
     const date = new Date();
 
@@ -515,38 +232,22 @@ async function listFiles({ prefix = '', maxKeys = 1000, continuationToken } = {}
       etag:         (xmlFirst(block, 'ETag') || '').replace(/"/g, ''),
     }));
 
-    return {
-      success: true,
-      data: { files, isTruncated, nextContinuationToken, count: files.length },
-      error: null,
-    };
+    return { success: true, data: { files, isTruncated, nextContinuationToken, count: files.length }, error: null };
   } catch (error) {
     fail(`Storage list files failed: ${error.message}`);
     return { success: false, data: null, error: error.message };
   }
 }
 
-/**
- * Generate a presigned URL for temporary access to a file
- * @param {Object} options
- * @param {string} options.key - File path/key
- * @param {number} options.expiresIn - URL expiration time in seconds (default: 3600)
- * @param {string} options.operation - 'get' or 'put' (default: 'get')
- * @returns {Promise<Object>}
- */
 async function getPresignedUrl({ key, expiresIn = 3600, operation = 'get' }) {
   try {
-    const config = getConfig();
+    const config = await getConfig();
     const path   = `/${config.bucket}/${key}`;
     const date   = new Date();
     const method = operation === 'put' ? 'PUT' : 'GET';
 
     // R2/S3 max presigned URL lifetime is 7 days (604800 seconds)
     const validExpiresIn = Math.min(Math.max(Math.floor(Number(expiresIn)), 1), 604800);
-    if (!Number.isFinite(validExpiresIn)) {
-      throw new Error('expiresIn must be a finite positive number');
-    }
-
     const url = buildPresignedUrl({ method, host: config.host, path, expiresIn: validExpiresIn, config, date });
 
     return { success: true, data: { key, url, expiresIn: validExpiresIn, operation }, error: null };
@@ -556,45 +257,36 @@ async function getPresignedUrl({ key, expiresIn = 3600, operation = 'get' }) {
   }
 }
 
-/**
- * Copy a file within the same bucket
- * @param {Object} options
- * @param {string} options.sourceKey - Source file path/key
- * @param {string} options.destinationKey - Destination file path/key
- * @returns {Promise<Object>}
- */
 async function copyFile({ sourceKey, destinationKey }) {
   try {
-    const getResult = await getFile(sourceKey);
-    if (!getResult.success) return getResult;
+    const config = await getConfig();
+    const path   = `/${config.bucket}/${destinationKey}`;
+    const date   = new Date();
 
-    const uploadResult = await uploadFile({
-      key: destinationKey,
-      body: getResult.data.body,
-      contentType: getResult.data.contentType,
-      metadata: getResult.data.metadata,
+    const { url, headers } = signRequest({
+      method: 'PUT',
+      host: config.host,
+      path,
+      extraHeaders: { 'x-amz-copy-source': `/${config.bucket}/${encodePath(sourceKey)}` },
+      config,
+      date,
     });
 
-    if (uploadResult.success) {
-      info(`Storage: copied ${sourceKey} → ${destinationKey}`);
+    const response = await fetch(url, { method: 'PUT', headers });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Copy failed (${response.status}): ${text}`);
     }
 
-    return uploadResult;
+    info(`Storage: copied ${sourceKey} → ${destinationKey}`);
+    return { success: true, data: { key: destinationKey, bucket: config.bucket }, error: null };
   } catch (error) {
     fail(`Storage copy failed: ${error.message}`);
     return { success: false, data: null, error: error.message };
   }
 }
 
-/**
- * Proxy a file from storage, returning a handler-ready response object.
- * Use this instead of presigned URLs to avoid exposing storage URLs to clients.
- * The returned object is consumed directly by the API router to stream the file.
- * @param {string} key - File path/key to retrieve
- * @param {Object} options
- * @param {string} [options.filename] - Optional download filename (Content-Disposition)
- * @returns {Promise<Object>}
- */
 async function proxyFile(key, { filename } = {}) {
   const result = await getFile(key);
   if (!result.success) return { success: false, error: result.error };
@@ -609,13 +301,6 @@ async function proxyFile(key, { filename } = {}) {
   };
 }
 
-/**
- * Move a file (copy + delete source)
- * @param {Object} options
- * @param {string} options.sourceKey - Source file path/key
- * @param {string} options.destinationKey - Destination file path/key
- * @returns {Promise<Object>}
- */
 async function moveFile({ sourceKey, destinationKey }) {
   try {
     const copyResult = await copyFile({ sourceKey, destinationKey });
@@ -635,7 +320,8 @@ async function moveFile({ sourceKey, destinationKey }) {
   }
 }
 
-// Export utility functions
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
 export {
   generateUniqueFilename,
   getFileExtension,
@@ -643,17 +329,12 @@ export {
   validateFileType,
   validateFileSize,
   formatFileSize,
-  generateUserFilePath,
-  generateOrgFilePath,
-  generatePostFilePath,
   sanitizeFilename,
-  validateImageDimensions,
   validateUpload,
   FILE_TYPE_PRESETS,
   FILE_SIZE_LIMITS,
 } from './utils.js';
 
-// Export storage functions
 export {
   uploadFile,
   uploadImage,
@@ -668,3 +349,5 @@ export {
   copyFile,
   moveFile,
 };
+
+export { registerStoragePolicies, registerStoragePublicPrefixes, clearStorageConfig } from './storage-config.js';

src/core/storage/signing.js

@@ -0,0 +1,198 @@
+/**
+ * AWS Signature V4 — internal helpers for S3-compatible storage providers.
+ * Not exported from package.json; only imported by provider implementations.
+ */
+
+import { createHmac, createHash } from 'crypto';
+
+// ─── Crypto primitives ───────────────────────────────────────────────────────
+
+export function sha256hex(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * HMAC-SHA256. Pass encoding='hex' for a hex string; omit for a Buffer.
+ */
+export function hmac(key, data, encoding) {
+  return createHmac('sha256', Buffer.isBuffer(key) ? key : Buffer.from(key))
+    .update(data)
+    .digest(encoding);
+}
+
+export function amzDate(date) {
+  return date.toISOString().replace(/[:\-]|\.\d{3}/g, '');
+}
+
+export function dateStamp(date) {
+  return date.toISOString().slice(0, 10).replace(/-/g, '');
+}
+
+// ─── URI encoding ────────────────────────────────────────────────────────────
+
+/**
+ * Encode a string per AWS Signature V4 spec (encodes everything except A-Z a-z 0-9 - _ . ~)
+ */
+export function encodeS3(str) {
+  return encodeURIComponent(str)
+    .replace(/!/g, '%21')
+    .replace(/'/g, '%27')
+    .replace(/\(/g, '%28')
+    .replace(/\)/g, '%29')
+    .replace(/\*/g, '%2A');
+}
+
+/**
+ * Encode a URI path, encoding each segment individually (preserving slashes)
+ */
+export function encodePath(path) {
+  return path.split('/').map(seg => (seg ? encodeS3(seg) : '')).join('/');
+}
+
+// ─── Signing key ─────────────────────────────────────────────────────────────
+
+function signingKey(secret, ds, region, service) {
+  const kDate    = hmac('AWS4' + secret, ds);
+  const kRegion  = hmac(kDate, region);
+  const kService = hmac(kRegion, service);
+  return hmac(kService, 'aws4_request');
+}
+
+// ─── Request signing ─────────────────────────────────────────────────────────
+
+/**
+ * Sign an S3 request using AWS Signature V4.
+ * Returns the full URL and the headers object to pass to fetch.
+ */
+export function signRequest({ method, host, path, query = {}, extraHeaders = {}, bodyBuffer, config, date }) {
+  const { accessKeyId, secretAccessKey, region } = config;
+  const service = 's3';
+
+  const ts       = amzDate(date);
+  const ds       = dateStamp(date);
+  const bodyHash = sha256hex(bodyBuffer ?? Buffer.alloc(0));
+
+  const headers = { host, 'x-amz-date': ts, 'x-amz-content-sha256': bodyHash, ...extraHeaders };
+
+  const sortedKeys        = Object.keys(headers).sort();
+  const canonicalHeaders  = sortedKeys.map(k => `${k}:${headers[k]}\n`).join('');
+  const signedHeaders     = sortedKeys.join(';');
+
+  const canonicalQueryString = Object.keys(query)
+    .sort()
+    .map(k => `${encodeS3(k)}=${encodeS3(query[k])}`)
+    .join('&');
+
+  const canonicalRequest = [method, encodePath(path), canonicalQueryString, canonicalHeaders, signedHeaders, bodyHash].join('\n');
+
+  const scope       = `${ds}/${region}/${service}/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', ts, scope, sha256hex(canonicalRequest)].join('\n');
+  const sig         = hmac(signingKey(secretAccessKey, ds, region, service), stringToSign, 'hex');
+  const auth        = `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${sig}`;
+
+  const requestHeaders = { ...headers, Authorization: auth };
+  delete requestHeaders.host;
+
+  const url = canonicalQueryString
+    ? `https://${host}${path}?${canonicalQueryString}`
+    : `https://${host}${path}`;
+
+  return { url, headers: requestHeaders };
+}
+
+/**
+ * Build a presigned URL (signature embedded in query string, no Authorization header).
+ * The payload is marked UNSIGNED-PAYLOAD so no body hash is needed at signing time.
+ */
+export function buildPresignedUrl({ method, host, path, expiresIn, config, date }) {
+  const { accessKeyId, secretAccessKey, region } = config;
+  const service = 's3';
+
+  const ts    = amzDate(date);
+  const ds    = dateStamp(date);
+  const scope = `${ds}/${region}/${service}/aws4_request`;
+
+  const query = {
+    'X-Amz-Algorithm':     'AWS4-HMAC-SHA256',
+    'X-Amz-Credential':    `${accessKeyId}/${scope}`,
+    'X-Amz-Date':          ts,
+    'X-Amz-Expires':       String(expiresIn),
+    'X-Amz-SignedHeaders': 'host',
+  };
+
+  const canonicalQueryString = Object.keys(query)
+    .sort()
+    .map(k => `${encodeS3(k)}=${encodeS3(query[k])}`)
+    .join('&');
+
+  const canonicalRequest = [method, encodePath(path), canonicalQueryString, `host:${host}\n`, 'host', 'UNSIGNED-PAYLOAD'].join('\n');
+  const stringToSign     = ['AWS4-HMAC-SHA256', ts, scope, sha256hex(canonicalRequest)].join('\n');
+  const sig              = hmac(signingKey(secretAccessKey, ds, region, service), stringToSign, 'hex');
+
+  return `https://${host}${path}?${canonicalQueryString}&X-Amz-Signature=${sig}`;
+}
+
+// ─── XML helpers ─────────────────────────────────────────────────────────────
+
+export function xmlFirst(xml, tag) {
+  const m = xml.match(new RegExp(`<${tag}[^>]*>(.*?)</${tag}>`, 's'));
+  return m ? m[1] : null;
+}
+
+export function xmlAll(xml, tag) {
+  const re = new RegExp(`<${tag}[^>]*>(.*?)</${tag}>`, 'gs');
+  const results = [];
+  let m;
+  while ((m = re.exec(xml)) !== null) results.push(m[1]);
+  return results;
+}
+
+// ─── Body normalizer ─────────────────────────────────────────────────────────
+
+export async function toBuffer(body) {
+  if (Buffer.isBuffer(body))     return body;
+  if (body instanceof Uint8Array) return Buffer.from(body);
+  if (typeof body === 'string')  return Buffer.from(body, 'utf8');
+  if (body instanceof Blob)      return Buffer.from(await body.arrayBuffer());
+  return Buffer.from(body);
+}
+
+// ─── Security helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Strip HTTP header injection characters (\r, \n, \0) from a header value.
+ */
+export function sanitizeHeaderValue(value) {
+  return String(value).replace(/[\r\n\0]/g, '');
+}
+
+/**
+ * Escape XML special characters to prevent injection into the DeleteObjects payload.
+ */
+export function escapeXml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// ─── Metadata helpers ─────────────────────────────────────────────────────────
+
+export function metaToHeaders(metadata) {
+  return Object.fromEntries(
+    Object.entries(metadata).map(([k, v]) => [
+      `x-amz-meta-${sanitizeHeaderValue(k).toLowerCase()}`,
+      sanitizeHeaderValue(v),
+    ])
+  );
+}
+
+export function headersToMeta(headers) {
+  return Object.fromEntries(
+    [...headers.entries()]
+      .filter(([k]) => k.startsWith('x-amz-meta-'))
+      .map(([k, v]) => [k.replace('x-amz-meta-', ''), v])
+  );
+}

src/core/storage/storage-config.js

@@ -0,0 +1,44 @@
+/**
+ * Storage API runtime configuration.
+ *
+ * Additive registration — mirrors core/api/runtime.js:
+ *   registerStoragePolicies(policies)       called by features during initializeZen()
+ *   registerStoragePublicPrefixes(prefixes) called by features during initializeZen()
+ *   clearStorageConfig()                    called by resetZenInitialization() / tests
+ *
+ * getStorageAccessPolicies() and getStoragePublicPrefixes() are read-only readers
+ * used internally by api.js — they are not re-exported from index.js.
+ */
+
+const POLICIES_KEY = Symbol.for('__ZEN_STORAGE_POLICIES__');
+const PREFIXES_KEY = Symbol.for('__ZEN_STORAGE_PUBLIC_PREFIXES__');
+
+if (!globalThis[POLICIES_KEY]) globalThis[POLICIES_KEY] = [];
+if (!globalThis[PREFIXES_KEY]) globalThis[PREFIXES_KEY] = [];
+
+export function registerStoragePolicies(policies) {
+  if (!Array.isArray(policies)) {
+    throw new TypeError('registerStoragePolicies: policies must be an array');
+  }
+  globalThis[POLICIES_KEY].push(...policies);
+}
+
+export function registerStoragePublicPrefixes(prefixes) {
+  if (!Array.isArray(prefixes)) {
+    throw new TypeError('registerStoragePublicPrefixes: prefixes must be an array');
+  }
+  globalThis[PREFIXES_KEY].push(...prefixes);
+}
+
+export function clearStorageConfig() {
+  globalThis[POLICIES_KEY].length = 0;
+  globalThis[PREFIXES_KEY].length = 0;
+}
+
+export function getStoragePublicPrefixes() {
+  return globalThis[PREFIXES_KEY];
+}
+
+export function getStorageAccessPolicies() {
+  return globalThis[POLICIES_KEY];
+}

src/core/storage/utils.js

@@ -4,7 +4,6 @@
  */
 
 import crypto from 'crypto';
-import { warn } from '../../shared/lib/logger.js';
 
 /**
  * Generate a unique filename with timestamp and random hash
@@ -31,15 +30,7 @@ export function getFileExtension(filename) {
   return lastDot === -1 ? '' : filename.substring(lastDot).toLowerCase();
 }
 
-/**
- * Get MIME type from file extension
- * @param {string} filename - Filename or extension
- * @returns {string} MIME type
- */
-export function getMimeType(filename) {
-  const ext = getFileExtension(filename).toLowerCase();
-  
-  const mimeTypes = {
+const MIME_TYPES = {
   // Images
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
@@ -84,7 +75,14 @@ export function getMimeType(filename) {
   '.css': 'text/css',
 };
 
-  return mimeTypes[ext] || 'application/octet-stream';
+/**
+ * Get MIME type from file extension
+ * @param {string} filename - Filename or extension
+ * @returns {string} MIME type
+ */
+export function getMimeType(filename) {
+  const ext = getFileExtension(filename).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
 }
 
 /**
@@ -136,39 +134,6 @@ export function formatFileSize(bytes, decimals = 2) {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
 }
 
-/**
- * Generate a storage path for a user's file
- * @param {string|number} userId - User ID
- * @param {string} category - File category (e.g., 'profile', 'documents')
- * @param {string} filename - Filename
- * @returns {string} Storage path (e.g., 'users/123/profile/filename.jpg')
- */
-export function generateUserFilePath(userId, category, filename) {
-  return `users/${userId}/${category}/${filename}`;
-}
-
-/**
- * Generate a storage path for organization/tenant files
- * @param {string|number} orgId - Organization/tenant ID
- * @param {string} category - File category
- * @param {string} filename - Filename
- * @returns {string} Storage path
- */
-export function generateOrgFilePath(orgId, category, filename) {
-  return `organizations/${orgId}/${category}/${filename}`;
-}
-
-/**
- * Generate a storage path for a post image, scoped by post type.
- * @param {string} typeKey - Post type key (e.g. 'blogue', 'cve')
- * @param {string|number} postIdOrSlug - Post ID or slug (use timestamp for pre-creation uploads)
- * @param {string} filename - Filename
- * @returns {string} Storage path (e.g., 'posts/blogue/123/filename.jpg')
- */
-export function generatePostFilePath(typeKey, postIdOrSlug, filename) {
-  return `posts/${typeKey}/${postIdOrSlug}/${filename}`;
-}
-
 /**
  * Sanitize filename by removing special characters
  * @param {string} filename - Original filename
@@ -187,36 +152,6 @@ export function sanitizeFilename(filename) {
   return sanitized + ext;
 }
 
-/**
- * Validate image dimensions from buffer
- * Note: This is a basic implementation. For production, consider using a library like 'sharp'
- * @param {Buffer} buffer - Image buffer
- * @param {Object} constraints - Dimension constraints
- * @param {number} constraints.maxWidth - Maximum width
- * @param {number} constraints.maxHeight - Maximum height
- * @param {number} constraints.minWidth - Minimum width
- * @param {number} constraints.minHeight - Minimum height
- * @returns {Promise<Object>} Validation result with dimensions
- */
-export async function validateImageDimensions(buffer, constraints = {}) {
-  // SECURITY: This function previously returned { valid: true } unconditionally,
-  // silently bypassing all dimension constraints. That behaviour is unsafe —
-  // callers that invoke this function expect enforcement, not a no-op.
-  //
-  // Returning valid=false with a clear diagnostic forces callers to either
-  // install 'sharp' (the recommended path) or explicitly handle the
-  // unvalidated case themselves. Never silently approve what cannot be checked.
-  warn('Storage: validateImageDimensions — dimension enforcement unavailable. Install "sharp" to enable pixel-level validation.');
-  return {
-    valid: false,
-    width: null,
-    height: null,
-    message:
-      'Image dimension validation is not configured. ' +
-      'Install "sharp" and implement validateImageDimensions before enforcing size constraints.',
-  };
-}
-
 /**
  * Common file type presets
  */
@@ -336,12 +271,9 @@ export function validateUpload({ filename, size, allowedTypes, maxSize, buffer }
   }
 
   // Explicitly reject SVG regardless of allowedTypes — SVG can carry JavaScript.
-  if (filename) {
-    const ext = filename.split('.').pop()?.toLowerCase();
-    if (ext === 'svg') {
+  if (filename && getFileExtension(filename) === '.svg') {
     errors.push('SVG files are not permitted due to script execution risk');
   }
-  }
 
   if (allowedTypes && !validateFileType(filename, allowedTypes)) {
     const typesList = allowedTypes.join(', ');

src/core/themes/README.md

@@ -0,0 +1,153 @@
+# Themes
+
+Ce répertoire gère le thème clair/sombre de l'interface. Il expose des utilitaires client pour lire, appliquer et réagir au thème, ainsi qu'un script d'initialisation à injecter dans `<head>` pour éviter le flash au chargement.
+
+---
+
+## Structure
+
+```
+src/core/themes/
+└── index.js    THEME_INIT_SCRIPT, getStoredTheme, applyTheme, getThemeIcon, ThemeWatcher, useTheme
+```
+
+---
+
+## Import
+
+```js
+import {
+  THEME_INIT_SCRIPT,
+  getStoredTheme,
+  applyTheme,
+  getThemeIcon,
+  ThemeWatcher,
+  useTheme,
+} from '@zen/core/themes';
+```
+
+Tous les exports sont marqués `'use client'`.
+
+---
+
+## API
+
+### `THEME_INIT_SCRIPT`
+
+Script inline à injecter dans `<head>` avant le premier rendu. Il lit `localStorage` et applique la classe `dark` sur `<html>` immédiatement, ce qui évite le flash de thème (FOUC).
+
+```jsx
+// app/layout.js
+import { THEME_INIT_SCRIPT } from '@zen/core/themes';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+---
+
+### `getStoredTheme()`
+
+Lit le thème enregistré dans `localStorage`. Retourne `'light'`, `'dark'` ou `'auto'`.
+
+```js
+const theme = getStoredTheme(); // 'light' | 'dark' | 'auto'
+```
+
+---
+
+### `applyTheme(theme)`
+
+Applique un thème en modifiant `document.documentElement` et en mettant à jour `localStorage`. En mode `'auto'`, retire la préférence stockée et suit le système.
+
+| Valeur | Comportement |
+|--------|-------------|
+| `'light'` | Retire la classe `dark`, stocke `'light'` |
+| `'dark'` | Ajoute la classe `dark`, stocke `'dark'` |
+| `'auto'` | Retire la valeur stockée, suit `prefers-color-scheme` |
+
+```js
+applyTheme('dark');
+applyTheme('auto');
+```
+
+---
+
+### `getThemeIcon(theme, systemIsDark)`
+
+Retourne le composant icône correspondant au thème actuel.
+
+| Thème | `systemIsDark` | Icône retournée |
+|-------|----------------|-----------------|
+| `'light'` | - | `Sun01Icon` |
+| `'dark'` | - | `Moon02Icon` |
+| `'auto'` | `true` | `MoonCloudIcon` |
+| `'auto'` | `false` | `SunCloud01Icon` |
+
+```jsx
+const Icon = getThemeIcon(theme, systemIsDark);
+return <Icon />;
+```
+
+---
+
+### `ThemeWatcher`
+
+Composant sans rendu qui écoute les changements de `prefers-color-scheme`. Si aucune préférence n'est stockée dans `localStorage`, il met à jour la classe `dark` automatiquement quand le système change.
+
+```jsx
+// Placer une fois dans le layout racine, après THEME_INIT_SCRIPT.
+import { ThemeWatcher } from '@zen/core/themes';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <ThemeWatcher />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+### `useTheme()`
+
+Hook qui expose le thème actuel et une fonction de basculement cyclique. Synchronise l'état avec `localStorage` et le système au montage.
+
+Retourne `{ theme, toggle, systemIsDark }`.
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `theme` | `'light' \| 'dark' \| 'auto'` | Thème actif |
+| `toggle` | `() => void` | Passe au thème suivant dans le cycle |
+| `systemIsDark` | `boolean` | Indique si le système est en mode sombre |
+
+Le cycle de basculement dépend de la préférence système :
+- Système clair : `auto` -> `dark` -> `light` -> `auto`
+- Système sombre : `auto` -> `light` -> `dark` -> `auto`
+
+```jsx
+import { useTheme, getThemeIcon } from '@zen/core/themes';
+
+export function ThemeToggle() {
+  const { theme, toggle, systemIsDark } = useTheme();
+  const Icon = getThemeIcon(theme, systemIsDark);
+
+  return (
+    <button onClick={toggle}>
+      <Icon />
+    </button>
+  );
+}
+```

src/core/themes/index.js

@@ -0,0 +1,83 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { Sun01Icon, Moon02Icon, SunCloud01Icon, MoonCloudIcon } from '@zen/core/shared/icons';
+
+// Script à injecter dans <head> pour appliquer le thème avant le premier rendu (anti-FOUC).
+export const THEME_INIT_SCRIPT = `(function(){try{var t=localStorage.getItem('theme'),d=window.matchMedia('(prefers-color-scheme: dark)').matches;if(t==='dark'||(!t&&d))document.documentElement.classList.add('dark');}catch(e){}})();`;
+
+const THEME_ICONS = {
+    light: Sun01Icon,
+    dark: Moon02Icon,
+};
+
+export function getStoredTheme() {
+    const stored = localStorage.getItem('theme');
+    if (stored === 'light' || stored === 'dark') return stored;
+    return 'auto';
+}
+
+export function applyTheme(theme) {
+    if (theme === 'dark') {
+        document.documentElement.classList.add('dark');
+        localStorage.setItem('theme', 'dark');
+    } else if (theme === 'light') {
+        document.documentElement.classList.remove('dark');
+        localStorage.setItem('theme', 'light');
+    } else {
+        localStorage.removeItem('theme');
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        document.documentElement.classList.toggle('dark', prefersDark);
+    }
+}
+
+export function getThemeIcon(theme, systemIsDark) {
+    if (theme === 'auto') return systemIsDark ? MoonCloudIcon : SunCloud01Icon;
+    return THEME_ICONS[theme];
+}
+
+function getNextTheme(current) {
+    const systemIsDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    if (current === 'auto') return systemIsDark ? 'light' : 'dark';
+    if (current === 'dark') return systemIsDark ? 'auto' : 'light';
+    return systemIsDark ? 'dark' : 'auto';
+}
+
+export function ThemeWatcher() {
+    useEffect(() => {
+        const mq = window.matchMedia('(prefers-color-scheme: dark)');
+        function onSystemChange(e) {
+            if (localStorage.getItem('theme')) return;
+            document.documentElement.classList.toggle('dark', e.matches);
+        }
+        mq.addEventListener('change', onSystemChange);
+        return () => mq.removeEventListener('change', onSystemChange);
+    }, []);
+
+    return null;
+}
+
+export function useTheme() {
+    const [theme, setTheme] = useState('auto');
+    const [systemIsDark, setSystemIsDark] = useState(false);
+
+    useEffect(() => {
+        setTheme(getStoredTheme());
+        setSystemIsDark(window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+        const mq = window.matchMedia('(prefers-color-scheme: dark)');
+        function onSystemChange(e) {
+            setSystemIsDark(e.matches);
+        }
+        mq.addEventListener('change', onSystemChange);
+        return () => mq.removeEventListener('change', onSystemChange);
+    }, []);
+
+    function toggle() {
+        const next = getNextTheme(theme);
+        setTheme(next);
+        applyTheme(next);
+    }
+
+    return { theme, toggle, systemIsDark };
+}

src/core/toast/README.md

@@ -0,0 +1,145 @@
+# Toast
+
+Ce répertoire fournit un **système de notifications toast** basé sur un contexte React. Il expose un provider, un hook, et un conteneur à placer dans le layout. Les features utilisent le hook pour déclencher des notifications.
+
+---
+
+## Structure
+
+```
+src/core/toast/
+├── index.js              Toast, ToastProvider, useToast, ToastContainer
+├── ToastContext.js        contexte, provider, hook useToast
+├── ToastContainer.js      conteneur à monter dans le layout
+└── Toast.js              composant d'affichage individuel
+```
+
+---
+
+## Import
+
+```js
+import { ToastProvider, useToast, ToastContainer } from '@zen/core/toast';
+```
+
+---
+
+## Mise en place
+
+Entourer le layout avec `ToastProvider` et y placer `ToastContainer`.
+
+```jsx
+import { ToastProvider, ToastContainer } from '@zen/core/toast';
+
+export default function RootLayout({ children }) {
+  return (
+    <ToastProvider>
+      {children}
+      <ToastContainer />
+    </ToastProvider>
+  );
+}
+```
+
+`useToast` lève une erreur si appelé hors du `ToastProvider`.
+
+---
+
+## API
+
+### `useToast()`
+
+Hook qui expose les méthodes et l'état courant des toasts.
+
+```js
+const { success, error, warning, info, addToast, removeToast, clearAllToasts } = useToast();
+```
+
+**Méthodes de raccourci**
+
+```js
+success('Modifications enregistrées.');
+error('La connexion a échoué.');
+warning('Session sur le point d'expirer.');
+info('Une mise à jour est disponible.');
+```
+
+Chaque méthode accepte un message et un objet `options` optionnel pour surcharger les paramètres par défaut.
+
+```js
+success('Fichier importé.', { duration: 3000, dismissible: false });
+```
+
+Toutes retournent l'`id` du toast créé.
+
+**`addToast(toast)`**
+
+Crée un toast à partir d'un objet complet.
+
+```js
+const id = addToast({
+  type: 'success',
+  message: 'Profil mis à jour.',
+  title: 'Enregistré',
+  duration: 4000,
+  dismissible: true,
+});
+```
+
+| Paramètre | Type | Défaut | Description |
+|-----------|------|--------|-------------|
+| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | `'info'` | Variante visuelle |
+| `message` | `string` | — | Corps du toast |
+| `title` | `string` | Selon `type` | Titre affiché (optionnel) |
+| `duration` | `number` | `5000` | Durée en ms avant disparition automatique. `0` pour désactiver |
+| `dismissible` | `boolean` | `true` | Afficher le bouton de fermeture |
+
+Durées par défaut selon le type : `error` → 7000 ms, `warning` → 6000 ms, `success` / `info` → 5000 ms.
+
+**`removeToast(id)`**
+
+Supprime un toast immédiatement par son `id`.
+
+**`clearAllToasts()`**
+
+Supprime tous les toasts actifs.
+
+---
+
+## ToastContainer
+
+Composant à placer une seule fois dans le layout. Affiche les toasts en bas à droite de l'écran, empilés avec une animation de survol.
+
+```jsx
+<ToastContainer maxToasts={5} />
+```
+
+| Prop | Type | Défaut | Description |
+|------|------|--------|-------------|
+| `maxToasts` | `number` | `5` | Nombre maximum de toasts visibles simultanément |
+
+Au survol du toast le plus récent, la pile se déploie pour afficher tous les toasts à leur taille réelle.
+
+---
+
+## Déclencher un toast depuis une feature
+
+```js
+// src/features/auth/actions/login.js
+import { useToast } from '@zen/core/toast';
+
+export function useLoginActions() {
+  const { success, error } = useToast();
+
+  async function login(credentials) {
+    const result = await loginRequest(credentials);
+    if (result.success) {
+      success('Connexion réussie.');
+    } else {
+      error('Identifiants incorrects.');
+    }
+  }
+
+  return { login };
+}
+```

src/core/toast/Toast.js

@@ -7,7 +7,7 @@ import {
     AlertCircleIcon,
     InformationCircleIcon,
     CancelCircleIcon
-} from '../../shared/Icons.js';
+} from '@zen/core/shared/icons';
 
 const Toast = ({ 
     id, 

src/core/toast/ToastContext.js

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { createContext, useContext, useState, useCallback } from 'react';
+import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
 
 const ToastContext = createContext();
 
@@ -88,7 +88,7 @@ export const ToastProvider = ({ children }) => {
         });
     }, [addToast]);
 
-    const value = {
+    const value = useMemo(() => ({
         toasts,
         addToast,
         removeToast,
@@ -97,7 +97,7 @@ export const ToastProvider = ({ children }) => {
         error,
         warning,
         info,
-    };
+    }), [toasts, addToast, removeToast, clearAllToasts, success, error, warning, info]);
 
     return (
         <ToastContext.Provider value={value}>

src/core/users/README.md

@@ -0,0 +1,274 @@
+# Users
+
+Ce répertoire gère les utilisateurs, l'authentification par identifiants, les sessions, les rôles et les permissions. Il constitue la couche de données auth du projet : les features l'appellent, il ne connaît pas les features.
+
+---
+
+## Structure
+
+```
+src/core/users/
+├── index.js          re-exports publics
+├── auth.js           register, login, mot de passe, vérification email
+├── session.js        création, validation, suppression de sessions
+├── queries.js        lecture et mise à jour des utilisateurs
+├── roles.js          CRUD des rôles, assignation aux utilisateurs
+├── permissions.js    hasPermission, getUserPermissions
+├── constants.js      PERMISSIONS, PERMISSION_DEFINITIONS, getPermissionGroups
+├── verifications.js  tokens de vérification email et de réinitialisation
+├── emailChange.js    tokens de changement d'adresse email
+├── password.js       hashPassword, verifyPassword, generateToken, generateId
+└── db.js             helpers internes
+```
+
+---
+
+## Import
+
+```js
+import {
+  register, login, requestPasswordReset, resetPassword, verifyUserEmail, updateUser,
+  createSession, validateSession, deleteSession, deleteUserSessions, refreshSession,
+  getUserById, getUserByEmail, countUsers, listUsers, updateUserById,
+  createRole, updateRole, deleteRole, listRoles, getRoleById,
+  getUserRoles, assignUserRole, revokeUserRole,
+  hasPermission, getUserPermissions,
+  PERMISSIONS, PERMISSION_DEFINITIONS, getPermissionGroups,
+  hashPassword, verifyPassword, generateToken, generateId,
+} from '@zen/core/users';
+```
+
+---
+
+## API
+
+### `register(userData, options?)`
+
+Crée un compte utilisateur avec vérification des contraintes mot de passe. Le premier utilisateur enregistré reçoit le rôle `admin`. Retourne `{ user, verificationToken }`.
+
+```js
+const { user, verificationToken } = await register(
+  { email: 'alice@example.com', password: 'Secret1', name: 'Alice' },
+  {
+    onEmailVerification: async (email, token) => {
+      await sendVerificationEmail({ to: email, token });
+    },
+  }
+);
+```
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `email` | `string` | Adresse email (max 254 caractères) |
+| `password` | `string` | Mot de passe (8-128 caractères, au moins 1 majuscule, 1 minuscule, 1 chiffre) |
+| `name` | `string` | Nom affiché (max 100 caractères) |
+| `onEmailVerification` | `async (email, token) => void` | Callback pour envoyer le token de vérification |
+
+---
+
+### `login(credentials, sessionOptions?)`
+
+Vérifie les identifiants et crée une session. Retourne `{ user, session }`. Lève une erreur si les identifiants sont incorrects.
+
+```js
+const { user, session } = await login(
+  { email: 'alice@example.com', password: 'Secret1' },
+  { ipAddress: req.ip, userAgent: req.headers['user-agent'] }
+);
+```
+
+---
+
+### `requestPasswordReset(email)`
+
+Génère un token de réinitialisation (expire dans 1 heure). Retourne `{ success: true, token }` même si l'email est inconnu, pour éviter l'énumération.
+
+```js
+const { token } = await requestPasswordReset('alice@example.com');
+```
+
+---
+
+### `resetPassword(data, options?)`
+
+Valide le token et met à jour le mot de passe. Retourne `{ success: true }`.
+
+```js
+await resetPassword(
+  { email: 'alice@example.com', token, newPassword: 'NewSecret1' },
+  { onPasswordChanged: async (email) => { /* envoyer confirmation */ } }
+);
+```
+
+---
+
+### `verifyUserEmail(userId)`
+
+Marque l'email de l'utilisateur comme vérifié.
+
+```js
+await verifyUserEmail(user.id);
+```
+
+---
+
+### `updateUser(userId, data)`
+
+Met à jour les champs autorisés du profil : `name`, `image`, `language`.
+
+```js
+await updateUser(user.id, { name: 'Alice Martin' });
+```
+
+---
+
+### `createSession(userId, options?)`
+
+Crée une session valide 30 jours. Retourne l'objet session.
+
+```js
+const session = await createSession(user.id, { ipAddress: '127.0.0.1', userAgent: '...' });
+```
+
+---
+
+### `validateSession(token)`
+
+Valide un token de session. Renouvelle automatiquement la session si elle expire dans moins de 20 jours. Retourne `{ session, user, sessionRefreshed }` ou `null`.
+
+```js
+const result = await validateSession(token);
+if (!result) {
+  // session expirée ou invalide
+}
+```
+
+---
+
+### `deleteSession(token)` / `deleteUserSessions(userId)`
+
+Supprime une session ou toutes les sessions d'un utilisateur.
+
+```js
+await deleteSession(token);
+await deleteUserSessions(user.id);
+```
+
+---
+
+### `getUserById(id)` / `getUserByEmail(email)`
+
+Récupère un utilisateur par son id ou son email.
+
+```js
+const user = await getUserById('abc123');
+const user = await getUserByEmail('alice@example.com');
+```
+
+---
+
+### `listUsers(options?)`
+
+Liste les utilisateurs avec pagination et tri. Retourne `{ users, pagination }`.
+
+```js
+const { users, pagination } = await listUsers({ page: 1, limit: 20, sortBy: 'created_at', sortOrder: 'desc' });
+```
+
+| Paramètre | Défaut | Description |
+|-----------|--------|-------------|
+| `page` | `1` | Page courante |
+| `limit` | `10` | Résultats par page (max 100) |
+| `sortBy` | `'created_at'` | Colonne de tri (`id`, `email`, `name`, `role`, `email_verified`, `created_at`) |
+| `sortOrder` | `'desc'` | `'asc'` ou `'desc'` |
+
+---
+
+### `updateUserById(id, fields)`
+
+Met à jour les champs autorisés d'un utilisateur : `name`, `role`, `email_verified`, `image`, `language`.
+
+```js
+await updateUserById(user.id, { role: 'editor', email_verified: true });
+```
+
+---
+
+### Rôles
+
+```js
+const roles = await listRoles();
+const role = await getRoleById(id);
+
+const role = await createRole({ name: 'Modérateur', description: 'Peut gérer les utilisateurs', color: '#3b82f6' });
+
+await updateRole(roleId, {
+  name: 'Modérateur',
+  permissionKeys: [PERMISSIONS.USERS_VIEW, PERMISSIONS.USERS_MANAGE],
+});
+
+await deleteRole(roleId); // impossible sur les rôles système
+
+const userRoles = await getUserRoles(userId);
+await assignUserRole(userId, roleId);
+await revokeUserRole(userId, roleId);
+```
+
+Les rôles système (`is_system = true`) peuvent être renommés mais leurs permissions ne peuvent pas être modifiées. Ils ne peuvent pas être supprimés.
+
+L'endpoint `DELETE /zen/api/users/:id/roles/:roleId` applique une règle de sécurité supplémentaire : un utilisateur ne peut pas se retirer un rôle qui lui accorde `users.manage` s'il n'en a pas d'autre. Cela évite qu'un administrateur se retrouve dans l'impossibilité de se redonner la permission. Cette vérification est faite au niveau du handler API et ne concerne pas la fonction `revokeUserRole` elle-même.
+
+---
+
+### Permissions
+
+```js
+const canManageRoles = await hasPermission(userId, PERMISSIONS.ROLES_MANAGE);
+const keys = await getUserPermissions(userId);
+```
+
+`PERMISSIONS` contient toutes les clés disponibles. `PERMISSION_DEFINITIONS` expose le label, la description et le groupe de chaque permission. `getPermissionGroups()` retourne les permissions regroupées par `group_name`.
+
+| Groupe | Clés |
+|--------|------|
+| Administration | `admin.access` |
+| Utilisateurs | `users.view`, `users.manage` |
+| Rôles | `roles.view`, `roles.manage` |
+
+---
+
+### Changement d'email
+
+```js
+import { createEmailChangeToken, verifyEmailChangeToken, applyEmailChange } from '@zen/core/users/emailChange';
+
+const token = await createEmailChangeToken(userId, 'new@example.com');
+
+// Plus tard, lors de la confirmation :
+const result = await verifyEmailChangeToken(token);
+if (result) {
+  await applyEmailChange(result.userId, result.newEmail);
+}
+```
+
+Le token expire dans 24 heures. `verifyEmailChangeToken` retourne `null` si le token est invalide ou expiré.
+
+---
+
+## Gestion des erreurs
+
+`register`, `login`, `resetPassword` lèvent des erreurs typées (`Error`) avec des messages en français. Les fonctions de requête (`getUserById`, etc.) retournent `null` si l'entrée n'existe pas. Les callbacks `onEmailVerification` et `onPasswordChanged` sont exécutés sans bloquer le flux principal : une erreur dans le callback est loguée mais n'interrompt pas l'opération.
+
+---
+
+## Tables utilisées
+
+| Table | Description |
+|-------|-------------|
+| `zen_auth_users` | Comptes utilisateurs |
+| `zen_auth_accounts` | Identifiants par provider (`credential`) |
+| `zen_auth_sessions` | Sessions actives |
+| `zen_auth_verifications` | Tokens de vérification email, reset mot de passe, changement email |
+| `zen_auth_roles` | Rôles |
+| `zen_auth_role_permissions` | Permissions associées aux rôles |
+| `zen_auth_user_roles` | Rôles assignés aux utilisateurs |

src/core/users/auth.js

@@ -1,36 +1,20 @@
-/**
- * Authentication Logic
- * Main authentication functions for user registration, login, and password management
- */
-
-import { create, findOne, updateById, count } from '../../../core/database/crud.js';
+import { query, create, findOne, updateById, count } from '@zen/core/database';
 import { hashPassword, verifyPassword, generateId } from './password.js';
 import { createSession } from './session.js';
-import { fail } from '../../../shared/lib/logger.js';
-import { createEmailVerification, createPasswordReset, verifyResetToken, deleteResetToken, sendPasswordChangedEmail } from './email.js';
+import { fail } from '@zen/core/shared/logger';
+import { createEmailVerification, createPasswordReset, verifyResetToken, deleteResetToken, verifyAccountSetupToken, deleteAccountSetupToken } from './verifications.js';
 
-/**
- * Register a new user
- * @param {Object} userData - User registration data
- * @param {string} userData.email - User email
- * @param {string} userData.password - User password
- * @param {string} userData.name - User name
- * @returns {Promise<Object>} Created user and session
- */
-async function register(userData) {
+async function register(userData, { onEmailVerification } = {}) {
   const { email, password, name } = userData;
 
-  // Validate required fields
   if (!email || !password || !name) {
     throw new Error('L\'e-mail, le mot de passe et le nom sont requis');
   }
 
-  // Validate email length (maximum 254 characters - RFC standard)
   if (email.length > 254) {
     throw new Error('L\'e-mail doit contenir 254 caractères ou moins');
   }
 
-  // Validate password length (minimum 8, maximum 128 characters)
   if (password.length < 8) {
     throw new Error('Le mot de passe doit contenir au moins 8 caractères');
   }
@@ -39,7 +23,6 @@ async function register(userData) {
     throw new Error('Le mot de passe doit contenir 128 caractères ou moins');
   }
 
-  // Validate password complexity (1 uppercase, 1 lowercase, 1 number)
   const hasUppercase = /[A-Z]/.test(password);
   const hasLowercase = /[a-z]/.test(password);
   const hasNumber = /\d/.test(password);
@@ -48,31 +31,25 @@ async function register(userData) {
     throw new Error('Le mot de passe doit contenir au moins une majuscule, une minuscule et un chiffre');
   }
 
-  // Validate name length (maximum 100 characters)
   if (name.length > 100) {
     throw new Error('Le nom doit contenir 100 caractères ou moins');
   }
 
-  // Validate name is not empty after trimming
   if (name.trim().length === 0) {
     throw new Error('Le nom ne peut pas être vide');
   }
 
-  // Check if user already exists
   const existingUser = await findOne('zen_auth_users', { email });
   if (existingUser) {
     throw new Error('Un utilisateur avec cet e-mail existe déjà');
   }
 
-  // Check if this is the first user - if so, make them admin
   const userCount = await count('zen_auth_users');
   const role = userCount === 0 ? 'admin' : 'user';
 
-  // Hash password
   const hashedPassword = await hashPassword(password);
-  
-  // Create user
   const userId = generateId();
+
   const user = await create('zen_auth_users', {
     id: userId,
     email,
@@ -83,7 +60,6 @@ async function register(userData) {
     updated_at: new Date()
   });
 
-  // Create account with password
   const accountId = generateId();
   await create('zen_auth_accounts', {
     id: accountId,
@@ -94,38 +70,46 @@ async function register(userData) {
     updated_at: new Date()
   });
 
-  // Create email verification token
-  const verification = await createEmailVerification(email);
-  
-  return {
-    user,
-    verificationToken: verification.token
-  };
+  // Assign admin role to first user via the new roles system
+  if (role === 'admin') {
+    try {
+      const adminRole = await query(`SELECT id FROM zen_auth_roles WHERE name = 'admin'`);
+      if (adminRole.rows.length > 0) {
+        await query(
+          `INSERT INTO zen_auth_user_roles (user_id, role_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
+          [user.id, adminRole.rows[0].id]
+        );
+      }
+    } catch (err) {
+      fail(`register: failed to assign admin role to first user: ${err.message}`);
+    }
+  }
+
+  const verification = await createEmailVerification(email);
+
+  if (onEmailVerification) {
+    try {
+      await onEmailVerification(email, verification.token);
+    } catch (err) {
+      fail(`register: failed to send verification email: ${err.message}`);
+    }
+  }
+
+  return { user, verificationToken: verification.token };
 }
 
-/**
- * Login a user
- * @param {Object} credentials - Login credentials
- * @param {string} credentials.email - User email
- * @param {string} credentials.password - User password
- * @param {Object} sessionOptions - Session options (ipAddress, userAgent)
- * @returns {Promise<Object>} User and session
- */
 async function login(credentials, sessionOptions = {}) {
   const { email, password } = credentials;
 
-  // Validate required fields
   if (!email || !password) {
     throw new Error('L\'e-mail et le mot de passe sont requis');
   }
 
-  // Find user
   const user = await findOne('zen_auth_users', { email });
   if (!user) {
     throw new Error('E-mail ou mot de passe incorrect');
   }
 
-  // Find account with password
   const account = await findOne('zen_auth_accounts', {
     user_id: user.id,
     provider_id: 'credential'
@@ -135,65 +119,38 @@ async function login(credentials, sessionOptions = {}) {
     throw new Error('E-mail ou mot de passe incorrect');
   }
 
-  // Verify password
   const isValid = await verifyPassword(password, account.password);
   if (!isValid) {
     throw new Error('E-mail ou mot de passe incorrect');
   }
 
-  // Create session
   const session = await createSession(user.id, sessionOptions);
 
-  return {
-    user,
-    session
-  };
+  return { user, session };
 }
 
-/**
- * Request a password reset
- * @param {string} email - User email
- * @returns {Promise<Object>} Reset token
- */
 async function requestPasswordReset(email) {
-  // Validate email
   if (!email) {
     throw new Error('L\'e-mail est requis');
   }
 
-  // Check if user exists
   const user = await findOne('zen_auth_users', { email });
   if (!user) {
-    // Don't reveal if user exists or not
     return { success: true };
   }
 
-  // Create password reset token
   const reset = await createPasswordReset(email);
 
-  return {
-    success: true,
-    token: reset.token
-  };
+  return { success: true, token: reset.token };
 }
 
-/**
- * Reset password with token
- * @param {Object} resetData - Reset data
- * @param {string} resetData.email - User email
- * @param {string} resetData.token - Reset token
- * @param {string} resetData.newPassword - New password
- * @returns {Promise<Object>} Success status
- */
-async function resetPassword(resetData) {
+async function resetPassword(resetData, { onPasswordChanged } = {}) {
   const { email, token, newPassword } = resetData;
 
-  // Validate required fields
   if (!email || !token || !newPassword) {
     throw new Error('L\'e-mail, le jeton et le nouveau mot de passe sont requis');
   }
 
-  // Validate password length (minimum 8, maximum 128 characters)
   if (newPassword.length < 8) {
     throw new Error('Le mot de passe doit contenir au moins 8 caractères');
   }
@@ -202,7 +159,6 @@ async function resetPassword(resetData) {
     throw new Error('Le mot de passe doit contenir 128 caractères ou moins');
   }
 
-  // Validate password complexity (1 uppercase, 1 lowercase, 1 number)
   const hasUppercase = /[A-Z]/.test(newPassword);
   const hasLowercase = /[a-z]/.test(newPassword);
   const hasNumber = /\d/.test(newPassword);
@@ -211,21 +167,16 @@ async function resetPassword(resetData) {
     throw new Error('Le mot de passe doit contenir au moins une majuscule, une minuscule et un chiffre');
   }
 
-  // Authoritative token verification — this check must live here so that any
-  // caller that imports resetPassword() directly (bypassing the server-action
-  // layer) cannot reset a password with an arbitrary or omitted token.
   const tokenValid = await verifyResetToken(email, token);
   if (!tokenValid) {
     throw new Error('Jeton de réinitialisation invalide ou expiré');
   }
 
-  // Find user
   const user = await findOne('zen_auth_users', { email });
   if (!user) {
     throw new Error('Jeton de réinitialisation invalide');
   }
 
-  // Find account
   const account = await findOne('zen_auth_accounts', {
     user_id: user.id,
     provider_id: 'credential'
@@ -235,34 +186,26 @@ async function resetPassword(resetData) {
     throw new Error('Compte introuvable');
   }
 
-  // Hash new password
   const hashedPassword = await hashPassword(newPassword);
 
-  // Update password
   await updateById('zen_auth_accounts', account.id, {
     password: hashedPassword,
     updated_at: new Date()
   });
 
-  // Delete reset token
   await deleteResetToken(email);
 
-  // Send password changed confirmation email
+  if (onPasswordChanged) {
     try {
-    await sendPasswordChangedEmail(email);
+      await onPasswordChanged(email);
     } catch (error) {
-    // Log error but don't fail the password reset process
       fail(`Auth: failed to send password changed email to ${email}: ${error.message}`);
     }
+  }
 
   return { success: true };
 }
 
-/**
- * Verify user email
- * @param {string} userId - User ID
- * @returns {Promise<Object>} Updated user
- */
 async function verifyUserEmail(userId) {
   return await updateById('zen_auth_users', userId, {
     email_verified: true,
@@ -270,12 +213,6 @@ async function verifyUserEmail(userId) {
   });
 }
 
-/**
- * Update user profile
- * @param {string} userId - User ID
- * @param {Object} updateData - Data to update
- * @returns {Promise<Object>} Updated user
- */
 async function updateUser(userId, updateData) {
   const allowedFields = ['name', 'image', 'language'];
   const filteredData = {};
@@ -291,11 +228,68 @@ async function updateUser(userId, updateData) {
   return await updateById('zen_auth_users', userId, filteredData);
 }
 
-export {
-  register,
-  login,
-  requestPasswordReset,
-  resetPassword,
-  verifyUserEmail,
-  updateUser
-};
+async function completeAccountSetup({ email, token, password }) {
+  if (!email || !token || !password) {
+    throw new Error('L\'e-mail, le jeton et le mot de passe sont requis');
+  }
+
+  if (password.length < 8) {
+    throw new Error('Le mot de passe doit contenir au moins 8 caractères');
+  }
+
+  if (password.length > 128) {
+    throw new Error('Le mot de passe doit contenir 128 caractères ou moins');
+  }
+
+  const hasUppercase = /[A-Z]/.test(password);
+  const hasLowercase = /[a-z]/.test(password);
+  const hasNumber = /\d/.test(password);
+
+  if (!hasUppercase || !hasLowercase || !hasNumber) {
+    throw new Error('Le mot de passe doit contenir au moins une majuscule, une minuscule et un chiffre');
+  }
+
+  const tokenValid = await verifyAccountSetupToken(email, token);
+  if (!tokenValid) {
+    throw new Error('Lien d\'invitation invalide ou expiré');
+  }
+
+  const user = await findOne('zen_auth_users', { email });
+  if (!user) {
+    throw new Error('Lien d\'invitation invalide');
+  }
+
+  const hashedPassword = await hashPassword(password);
+
+  const existingAccount = await findOne('zen_auth_accounts', {
+    user_id: user.id,
+    provider_id: 'credential'
+  });
+
+  if (existingAccount) {
+    await updateById('zen_auth_accounts', existingAccount.id, {
+      password: hashedPassword,
+      updated_at: new Date()
+    });
+  } else {
+    await create('zen_auth_accounts', {
+      id: generateId(),
+      account_id: email,
+      provider_id: 'credential',
+      user_id: user.id,
+      password: hashedPassword,
+      updated_at: new Date()
+    });
+  }
+
+  await updateById('zen_auth_users', user.id, {
+    email_verified: true,
+    updated_at: new Date()
+  });
+
+  await deleteAccountSetupToken(email);
+
+  return { success: true };
+}
+
+export { register, login, requestPasswordReset, resetPassword, verifyUserEmail, updateUser, completeAccountSetup };

src/core/users/constants.js

@@ -0,0 +1,32 @@
+/**
+ * Static permission definitions — single source of truth.
+ * No server-side imports: safe to use in both client and server code.
+ */
+
+export const PERMISSIONS = {
+  ADMIN_ACCESS:  'admin.access',
+  USERS_VIEW:    'users.view',
+  USERS_MANAGE:  'users.manage',
+  ROLES_VIEW:    'roles.view',
+  ROLES_MANAGE:  'roles.manage',
+};
+
+export const PERMISSION_DEFINITIONS = [
+  { key: 'admin.access',  name: 'Accès au panneau admin',   description: "Permet d'accéder à l'interface d'administration.",                              group_name: 'Administration' },
+  { key: 'users.view',    name: 'Voir les utilisateurs',    description: 'Permet de consulter la liste des membres et leurs profils.',                    group_name: 'Utilisateurs' },
+  { key: 'users.manage',  name: 'Gérer les utilisateurs',   description: 'Permet de créer, modifier et supprimer des comptes membres.',                   group_name: 'Utilisateurs' },
+  { key: 'roles.view',    name: 'Voir les rôles',           description: 'Permet de consulter la liste des rôles et leurs permissions.',                  group_name: 'Rôles' },
+  { key: 'roles.manage',  name: 'Gérer les rôles',          description: 'Permet de créer, modifier et supprimer des rôles.',                            group_name: 'Rôles' },
+];
+
+/**
+ * Returns permissions grouped by group_name.
+ * @returns {Object.<string, Array>}
+ */
+export function getPermissionGroups() {
+  return PERMISSION_DEFINITIONS.reduce((acc, perm) => {
+    if (!acc[perm.group_name]) acc[perm.group_name] = [];
+    acc[perm.group_name].push(perm);
+    return acc;
+  }, {});
+}

src/core/users/db.js

@@ -0,0 +1,182 @@
+import { query, tableExists } from '@zen/core/database';
+import { generateId } from './password.js';
+import { done, warn } from '@zen/core/shared/logger';
+import { PERMISSION_DEFINITIONS } from './constants.js';
+import { registerPermissions, getRegisteredPermissions } from './permissions-registry.js';
+
+const USER_ROLE_PERMISSIONS = [];
+
+const ROLE_TABLES = [
+  {
+    name: 'zen_auth_roles',
+    sql: `
+      CREATE TABLE zen_auth_roles (
+        id text NOT NULL PRIMARY KEY,
+        name text NOT NULL UNIQUE,
+        description text,
+        color text DEFAULT '#6b7280',
+        is_system boolean NOT NULL DEFAULT false,
+        created_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP
+      )
+    `
+  },
+  {
+    name: 'zen_auth_permissions',
+    sql: `
+      CREATE TABLE zen_auth_permissions (
+        key text NOT NULL PRIMARY KEY,
+        name text NOT NULL,
+        description text,
+        group_name text NOT NULL
+      )
+    `
+  },
+  {
+    name: 'zen_auth_role_permissions',
+    sql: `
+      CREATE TABLE zen_auth_role_permissions (
+        role_id text NOT NULL REFERENCES zen_auth_roles(id) ON DELETE CASCADE,
+        permission_key text NOT NULL REFERENCES zen_auth_permissions(key) ON DELETE CASCADE,
+        PRIMARY KEY (role_id, permission_key)
+      )
+    `
+  },
+  {
+    name: 'zen_auth_user_roles',
+    sql: `
+      CREATE TABLE zen_auth_user_roles (
+        user_id text NOT NULL REFERENCES zen_auth_users(id) ON DELETE CASCADE,
+        role_id text NOT NULL REFERENCES zen_auth_roles(id) ON DELETE CASCADE,
+        PRIMARY KEY (user_id, role_id)
+      )
+    `
+  }
+];
+
+async function dropRoleCheckConstraint() {
+  await query(`
+    DO $$ DECLARE cname text;
+    BEGIN
+      SELECT conname INTO cname FROM pg_constraint
+      WHERE conrelid = 'zen_auth_users'::regclass AND contype = 'c' AND conname LIKE '%role%';
+      IF cname IS NOT NULL THEN
+        EXECUTE 'ALTER TABLE zen_auth_users DROP CONSTRAINT ' || quote_ident(cname);
+      END IF;
+    END$$;
+  `);
+}
+
+async function migratePermissions() {
+  // Migrate users.edit / users.delete → users.manage
+  await query(`
+    INSERT INTO zen_auth_role_permissions (role_id, permission_key)
+      SELECT DISTINCT role_id, 'users.manage'
+      FROM zen_auth_role_permissions
+      WHERE permission_key IN ('users.edit', 'users.delete')
+      AND EXISTS (SELECT 1 FROM zen_auth_permissions WHERE key = 'users.manage')
+    ON CONFLICT DO NOTHING
+  `);
+  await query(`DELETE FROM zen_auth_role_permissions WHERE permission_key IN ('users.edit', 'users.delete')`);
+  await query(`DELETE FROM zen_auth_permissions WHERE key IN ('users.edit', 'users.delete')`);
+}
+
+async function seedDefaultRolesAndPermissions() {
+  // S'assure que les permissions core sont dans le registre, puis seed depuis
+  // le registre — qui contient core + permissions enregistrées par les modules.
+  registerPermissions(PERMISSION_DEFINITIONS);
+  const allPermissions = getRegisteredPermissions();
+
+  for (const perm of allPermissions) {
+    await query(
+      `INSERT INTO zen_auth_permissions (key, name, description, group_name)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (key) DO UPDATE SET name = EXCLUDED.name, description = EXCLUDED.description, group_name = EXCLUDED.group_name`,
+      [perm.key, perm.name, perm.description, perm.group_name]
+    );
+  }
+
+  await migratePermissions();
+
+  // Admin role
+  const adminRoleId = generateId();
+  await query(
+    `INSERT INTO zen_auth_roles (id, name, description, color, is_system) VALUES ($1, $2, $3, $4, $5) ON CONFLICT (name) DO NOTHING`,
+    [adminRoleId, 'admin', 'Accès complet à toutes les fonctionnalités', '#ef4444', true]
+  );
+  const adminRole = await query(`SELECT id FROM zen_auth_roles WHERE name = 'admin'`);
+  const adminId = adminRole.rows[0].id;
+
+  // Toute permission présente dans le catalogue est attribuée au rôle admin —
+  // y compris les permissions ajoutées par les modules après le premier init.
+  await query(
+    `INSERT INTO zen_auth_role_permissions (role_id, permission_key)
+     SELECT $1, key FROM zen_auth_permissions
+     ON CONFLICT DO NOTHING`,
+    [adminId]
+  );
+
+  // User role
+  const userRoleId = generateId();
+  await query(
+    `INSERT INTO zen_auth_roles (id, name, description, color, is_system) VALUES ($1, $2, $3, $4, $5) ON CONFLICT (name) DO NOTHING`,
+    [userRoleId, 'user', 'Accès de base en lecture', '#6b7280', true]
+  );
+  const userRole = await query(`SELECT id FROM zen_auth_roles WHERE name = 'user'`);
+  const userId = userRole.rows[0].id;
+
+  for (const permKey of USER_ROLE_PERMISSIONS) {
+    await query(
+      `INSERT INTO zen_auth_role_permissions (role_id, permission_key) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
+      [userId, permKey]
+    );
+  }
+
+  // Assign admin role to the first user if no user-roles exist yet
+  const userRolesCount = await query(`SELECT COUNT(*) FROM zen_auth_user_roles`);
+  if (parseInt(userRolesCount.rows[0].count) === 0) {
+    const firstUser = await query(`SELECT id FROM zen_auth_users ORDER BY created_at ASC LIMIT 1`);
+    if (firstUser.rows.length > 0) {
+      await query(
+        `INSERT INTO zen_auth_user_roles (user_id, role_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
+        [firstUser.rows[0].id, adminId]
+      );
+    }
+  }
+}
+
+export async function createTables() {
+  const created = [];
+  const skipped = [];
+
+  // Drop legacy CHECK constraint on zen_auth_users.role if it exists
+  await dropRoleCheckConstraint();
+
+  for (const table of ROLE_TABLES) {
+    const exists = await tableExists(table.name);
+    if (!exists) {
+      await query(table.sql);
+      created.push(table.name);
+      done(`Created table: ${table.name}`);
+    } else {
+      skipped.push(table.name);
+    }
+  }
+
+  await seedDefaultRolesAndPermissions();
+
+  return { created, skipped };
+}
+
+export async function dropTables() {
+  const dropOrder = [...ROLE_TABLES].reverse().map(t => t.name);
+  warn('Dropping all Zen role/permission tables...');
+  for (const tableName of dropOrder) {
+    const exists = await tableExists(tableName);
+    if (exists) {
+      await query(`DROP TABLE IF EXISTS "${tableName}" CASCADE`);
+      done(`Dropped table: ${tableName}`);
+    }
+  }
+  done('All role/permission tables dropped');
+}

src/core/users/emailChange.js

@@ -0,0 +1,62 @@
+import crypto from 'crypto';
+import { query, create, deleteWhere, updateById } from '@zen/core/database';
+import { generateToken, generateId } from './password.js';
+
+export async function createEmailChangeToken(userId, newEmail) {
+  const token = generateToken(32);
+  const expiresAt = new Date();
+  expiresAt.setHours(expiresAt.getHours() + 24);
+
+  await deleteWhere('zen_auth_verifications', { identifier: 'email_change:' + userId });
+
+  await create('zen_auth_verifications', {
+    id: generateId(),
+    identifier: 'email_change:' + userId,
+    value: newEmail,
+    token,
+    expires_at: expiresAt,
+    updated_at: new Date(),
+  });
+
+  return token;
+}
+
+export async function verifyEmailChangeToken(token) {
+  const result = await query(
+    "SELECT * FROM zen_auth_verifications WHERE identifier LIKE 'email_change:%' AND token = $1",
+    [token]
+  );
+
+  if (result.rows.length === 0) return null;
+
+  const record = result.rows[0];
+
+  // Timing-safe comparison — same-length buffer padding prevents length-based timing leaks.
+  const storedBuf = Buffer.from(record.token, 'utf8');
+  const providedBuf = Buffer.from(
+    token.length === record.token.length ? token : record.token,
+    'utf8'
+  );
+  const tokensMatch = crypto.timingSafeEqual(storedBuf, providedBuf) && token.length === record.token.length;
+  if (!tokensMatch) return null;
+
+  if (new Date(record.expires_at) < new Date()) {
+    await deleteWhere('zen_auth_verifications', { id: record.id });
+    return null;
+  }
+
+  const userId = record.identifier.slice('email_change:'.length);
+  const newEmail = record.value;
+
+  await deleteWhere('zen_auth_verifications', { id: record.id });
+
+  return { userId, newEmail };
+}
+
+export async function applyEmailChange(userId, newEmail) {
+  await updateById('zen_auth_users', userId, { email: newEmail, updated_at: new Date() });
+  await query(
+    'UPDATE zen_auth_accounts SET account_id = $1, updated_at = $2 WHERE user_id = $3 AND provider_id = $4',
+    [newEmail, new Date(), userId, 'credential']
+  );
+}

src/core/users/index.js

@@ -0,0 +1,17 @@
+export { getUserById, getUserByEmail, countUsers, listUsers, updateUserById } from './queries.js';
+export { register, login, requestPasswordReset, resetPassword, verifyUserEmail, updateUser } from './auth.js';
+export { createSession, validateSession, deleteSession, deleteUserSessions, refreshSession } from './session.js';
+export { createEmailVerification, verifyEmailToken, createPasswordReset, verifyResetToken, deleteResetToken } from './verifications.js';
+export { hashPassword, verifyPassword, generateToken, generateId } from './password.js';
+export { listRoles, getRoleById, createRole, updateRole, deleteRole, getUserRoles, assignUserRole, revokeUserRole } from './roles.js';
+export {
+  PERMISSIONS,
+  PERMISSION_DEFINITIONS,
+  getPermissionGroups,
+  hasPermission,
+  getUserPermissions,
+  registerPermission,
+  registerPermissions,
+  getRegisteredPermissions,
+  getRegisteredPermissionKeys,
+} from './permissions.js';

src/core/users/password.js

@@ -1,21 +1,8 @@
-/**
- * Password Hashing and Verification
- * Provides secure password hashing using bcrypt
- */
-
 import crypto from 'crypto';
 
-/**
- * Hash a password using scrypt (Node.js native)
- * @param {string} password - Plain text password
- * @returns {Promise<string>} Hashed password
- */
 async function hashPassword(password) {
   return new Promise((resolve, reject) => {
-    // Generate a salt
     const salt = crypto.randomBytes(16).toString('hex');
-    
-    // Hash password with salt using scrypt
     crypto.scrypt(password, salt, 64, (err, derivedKey) => {
       if (err) reject(err);
       resolve(salt + ':' + derivedKey.toString('hex'));
@@ -23,22 +10,13 @@ async function hashPassword(password) {
   });
 }
 
-/**
- * Verify a password against a hash
- * @param {string} password - Plain text password
- * @param {string} hash - Hashed password
- * @returns {Promise<boolean>} True if password matches, false otherwise
- */
 async function verifyPassword(password, hash) {
   return new Promise((resolve, reject) => {
     const [salt, key] = hash.split(':');
-
     crypto.scrypt(password, salt, 64, (err, derivedKey) => {
       if (err) { reject(err); return; }
       try {
         const storedKey = Buffer.from(key, 'hex');
-        // timingSafeEqual requires identical lengths; if the stored hash is
-        // malformed the lengths will differ and we reject without leaking timing.
         if (storedKey.length !== derivedKey.length) { resolve(false); return; }
         resolve(crypto.timingSafeEqual(storedKey, derivedKey));
       } catch {
@@ -48,26 +26,12 @@ async function verifyPassword(password, hash) {
   });
 }
 
-/**
- * Generate a random token
- * @param {number} length - Token length in bytes (default: 32)
- * @returns {string} Random token
- */
 function generateToken(length = 32) {
   return crypto.randomBytes(length).toString('hex');
 }
 
-/**
- * Generate a random ID
- * @returns {string} Random ID
- */
 function generateId() {
   return crypto.randomUUID();
 }
 
-export {
-  hashPassword,
-  verifyPassword,
-  generateToken,
-  generateId
-};
+export { hashPassword, verifyPassword, generateToken, generateId };

src/core/users/permissions-registry.js

@@ -0,0 +1,47 @@
+/**
+ * Registre runtime des permissions.
+ *
+ * Le core enregistre ses permissions au boot (initializeZen) ; chaque module
+ * externe enregistre les siennes via son hook register(). Le registre alimente
+ * à la fois le seed BD (zen-db init) et la validation runtime (updateRole).
+ *
+ * Le registre est un singleton process-local persisté via Symbol.for sur
+ * globalThis pour survivre aux hot-reloads Next.js.
+ */
+
+const REGISTRY_KEY = Symbol.for('__ZEN_PERMISSIONS_REGISTRY__');
+if (!globalThis[REGISTRY_KEY]) globalThis[REGISTRY_KEY] = new Map();
+/** @type {Map<string, { key: string, name: string, description?: string, group_name: string }>} */
+const registry = globalThis[REGISTRY_KEY];
+
+export function registerPermission({ key, name, description, group_name }) {
+  if (typeof key !== 'string' || !key) {
+    throw new TypeError('registerPermission: "key" must be a non-empty string');
+  }
+  if (typeof name !== 'string' || !name) {
+    throw new TypeError(`registerPermission(${key}): "name" must be a non-empty string`);
+  }
+  if (typeof group_name !== 'string' || !group_name) {
+    throw new TypeError(`registerPermission(${key}): "group_name" must be a non-empty string`);
+  }
+  registry.set(key, { key, name, description: description ?? null, group_name });
+}
+
+export function registerPermissions(list) {
+  if (!Array.isArray(list)) {
+    throw new TypeError('registerPermissions: argument must be an array');
+  }
+  for (const perm of list) registerPermission(perm);
+}
+
+export function getRegisteredPermissions() {
+  return [...registry.values()];
+}
+
+export function getRegisteredPermissionKeys() {
+  return new Set(registry.keys());
+}
+
+export function clearRegisteredPermissions() {
+  registry.clear();
+}

src/core/users/permissions.js

@@ -0,0 +1,32 @@
+import { query } from '@zen/core/database';
+export { PERMISSIONS, PERMISSION_DEFINITIONS, getPermissionGroups } from './constants.js';
+export {
+  registerPermission,
+  registerPermissions,
+  getRegisteredPermissions,
+  getRegisteredPermissionKeys,
+} from './permissions-registry.js';
+
+export async function hasPermission(userId, permissionKey) {
+  const result = await query(
+    `SELECT 1
+     FROM zen_auth_user_roles ur
+     JOIN zen_auth_role_permissions rp ON rp.role_id = ur.role_id
+     WHERE ur.user_id = $1
+       AND rp.permission_key = $2
+     LIMIT 1`,
+    [userId, permissionKey]
+  );
+  return result.rows.length > 0;
+}
+
+export async function getUserPermissions(userId) {
+  const result = await query(
+    `SELECT DISTINCT rp.permission_key
+     FROM zen_auth_user_roles ur
+     JOIN zen_auth_role_permissions rp ON rp.role_id = ur.role_id
+     WHERE ur.user_id = $1`,
+    [userId]
+  );
+  return result.rows.map(r => r.permission_key);
+}

src/core/users/queries.js

@@ -0,0 +1,46 @@
+import { query, findOne, updateById, count } from '@zen/core/database';
+
+const MAX_PAGE_LIMIT = 100;
+const ALLOWED_SORT_COLUMNS = ['id', 'email', 'name', 'role', 'email_verified', 'created_at'];
+
+async function getUserById(id) {
+  return findOne('zen_auth_users', { id });
+}
+
+async function getUserByEmail(email) {
+  return findOne('zen_auth_users', { email });
+}
+
+async function countUsers() {
+  return count('zen_auth_users');
+}
+
+async function listUsers({ page = 1, limit = 10, sortBy = 'created_at', sortOrder = 'desc' } = {}) {
+  const safePage = Math.max(1, page);
+  const safeLimit = Math.min(Math.max(1, limit), MAX_PAGE_LIMIT);
+  const offset = (safePage - 1) * safeLimit;
+  const sortColumn = ALLOWED_SORT_COLUMNS.includes(sortBy) ? sortBy : 'created_at';
+  const order = sortOrder.toLowerCase() === 'asc' ? 'ASC' : 'DESC';
+
+  const result = await query(
+    `SELECT id, email, name, role, image, email_verified, created_at FROM zen_auth_users ORDER BY "${sortColumn}" ${order} LIMIT $1 OFFSET $2`,
+    [safeLimit, offset]
+  );
+  const total = await countUsers();
+
+  return {
+    users: result.rows,
+    pagination: { page: safePage, limit: safeLimit, total, totalPages: Math.ceil(total / safeLimit) }
+  };
+}
+
+async function updateUserById(id, fields) {
+  const allowed = ['name', 'role', 'email_verified', 'image', 'language', 'updated_at'];
+  const data = { updated_at: new Date() };
+  for (const key of allowed) {
+    if (fields[key] !== undefined) data[key] = fields[key];
+  }
+  return updateById('zen_auth_users', id, data);
+}
+
+export { getUserById, getUserByEmail, countUsers, listUsers, updateUserById };

src/core/users/roles.js

@@ -0,0 +1,138 @@
+import { query, transaction } from '@zen/core/database';
+import { generateId } from './password.js';
+import { getRegisteredPermissionKeys } from './permissions-registry.js';
+
+export async function listRoles() {
+  const result = await query(
+    `SELECT r.*,
+       COUNT(DISTINCT rp.permission_key)::int AS permission_count,
+       COUNT(DISTINCT ur.user_id)::int AS user_count
+     FROM zen_auth_roles r
+     LEFT JOIN zen_auth_role_permissions rp ON rp.role_id = r.id
+     LEFT JOIN zen_auth_user_roles ur ON ur.role_id = r.id
+     GROUP BY r.id
+     ORDER BY r.created_at ASC`
+  );
+  return result.rows;
+}
+
+export async function getRoleById(id) {
+  const roleResult = await query(
+    `SELECT * FROM zen_auth_roles WHERE id = $1`,
+    [id]
+  );
+  if (roleResult.rows.length === 0) return null;
+
+  const permsResult = await query(
+    `SELECT permission_key FROM zen_auth_role_permissions WHERE role_id = $1`,
+    [id]
+  );
+
+  return {
+    ...roleResult.rows[0],
+    permission_keys: permsResult.rows.map(r => r.permission_key)
+  };
+}
+
+export async function createRole({ name, description = null, color = '#6b7280' }) {
+  if (!name || !name.trim()) throw new Error('Role name is required');
+
+  const id = generateId();
+  const result = await query(
+    `INSERT INTO zen_auth_roles (id, name, description, color, is_system)
+     VALUES ($1, $2, $3, $4, false)
+     RETURNING *`,
+    [id, name.trim(), description || null, color]
+  );
+  return result.rows[0];
+}
+
+export async function updateRole(roleId, { name, description, color, permissionKeys }) {
+  const role = await query(`SELECT is_system FROM zen_auth_roles WHERE id = $1`, [roleId]);
+  if (role.rows.length === 0) throw new Error('Role not found');
+
+  const isSystem = role.rows[0].is_system;
+
+  return transaction(async (client) => {
+    const updateFields = [];
+    const values = [];
+    let idx = 1;
+
+    if (name !== undefined) {
+      if (!name.trim()) throw new Error('Role name cannot be empty');
+      updateFields.push(`name = $${idx++}`);
+      values.push(name.trim());
+    }
+    if (description !== undefined) {
+      updateFields.push(`description = $${idx++}`);
+      values.push(description || null);
+    }
+    if (color !== undefined) {
+      updateFields.push(`color = $${idx++}`);
+      values.push(color);
+    }
+    updateFields.push(`updated_at = $${idx++}`);
+    values.push(new Date());
+    values.push(roleId);
+
+    const updated = await client.query(
+      `UPDATE zen_auth_roles SET ${updateFields.join(', ')} WHERE id = $${idx} RETURNING *`,
+      values
+    );
+
+    if (!isSystem && permissionKeys !== undefined) {
+      const validKeys = getRegisteredPermissionKeys();
+      const safeKeys = [...new Set(permissionKeys)].filter(k => validKeys.has(k));
+      await client.query(`DELETE FROM zen_auth_role_permissions WHERE role_id = $1`, [roleId]);
+      for (const key of safeKeys) {
+        await client.query(
+          `INSERT INTO zen_auth_role_permissions (role_id, permission_key) VALUES ($1, $2)`,
+          [roleId, key]
+        );
+      }
+    }
+
+    const perms = await client.query(
+      `SELECT permission_key FROM zen_auth_role_permissions WHERE role_id = $1`,
+      [roleId]
+    );
+
+    return {
+      ...updated.rows[0],
+      permission_keys: perms.rows.map(r => r.permission_key)
+    };
+  });
+}
+
+export async function deleteRole(roleId) {
+  const result = await query(`SELECT is_system FROM zen_auth_roles WHERE id = $1`, [roleId]);
+  if (result.rows.length === 0) throw new Error('Role not found');
+  if (result.rows[0].is_system) throw new Error('Cannot delete a system role');
+
+  await query(`DELETE FROM zen_auth_roles WHERE id = $1`, [roleId]);
+}
+
+export async function getUserRoles(userId) {
+  const result = await query(
+    `SELECT r.* FROM zen_auth_roles r
+     JOIN zen_auth_user_roles ur ON ur.role_id = r.id
+     WHERE ur.user_id = $1
+     ORDER BY r.created_at ASC`,
+    [userId]
+  );
+  return result.rows;
+}
+
+export async function assignUserRole(userId, roleId) {
+  await query(
+    `INSERT INTO zen_auth_user_roles (user_id, role_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
+    [userId, roleId]
+  );
+}
+
+export async function revokeUserRole(userId, roleId) {
+  await query(
+    `DELETE FROM zen_auth_user_roles WHERE user_id = $1 AND role_id = $2`,
+    [userId, roleId]
+  );
+}

src/core/users/session.js

@@ -1,25 +1,10 @@
-/**
- * Session Management
- * Handles user session creation, validation, and deletion
- */
-
-import { create, findOne, deleteWhere, updateById } from '../../../core/database/crud.js';
+import { create, findOne, deleteWhere, updateById } from '@zen/core/database';
 import { generateToken, generateId } from './password.js';
 
-/**
- * Create a new session for a user
- * @param {string} userId - User ID
- * @param {Object} options - Session options (ipAddress, userAgent)
- * @returns {Promise<Object>} Session object with token
- */
 async function createSession(userId, options = {}) {
   const { ipAddress, userAgent } = options;
-  
-  // Generate session token
   const token = generateToken(32);
   const sessionId = generateId();
-  
-  // Session expires in 30 days
   const expiresAt = new Date();
   expiresAt.setDate(expiresAt.getDate() + 30);
 
@@ -36,103 +21,59 @@ async function createSession(userId, options = {}) {
   return session;
 }
 
-/**
- * Validate a session token
- * @param {string} token - Session token
- * @returns {Promise<Object|null>} Session object with user data or null if invalid
- */
 async function validateSession(token) {
   if (!token) return null;
 
   const session = await findOne('zen_auth_sessions', { token });
-  
   if (!session) return null;
 
-  // Check if session is expired
   if (new Date(session.expires_at) < new Date()) {
     await deleteSession(token);
     return null;
   }
 
-  // Get user data
   const user = await findOne('zen_auth_users', { id: session.user_id });
-  
   if (!user) {
     await deleteSession(token);
     return null;
   }
 
-  // Auto-refresh session if it expires in less than 20 days
   const now = new Date();
   const expiresAt = new Date(session.expires_at);
   const daysUntilExpiry = Math.ceil((expiresAt - now) / (1000 * 60 * 60 * 24));
 
   let sessionRefreshed = false;
-  
   if (daysUntilExpiry < 20) {
-    // Extend session to 30 days from now
     const newExpiresAt = new Date();
     newExpiresAt.setDate(newExpiresAt.getDate() + 30);
-    
     await updateById('zen_auth_sessions', session.id, {
       expires_at: newExpiresAt,
       updated_at: new Date()
     });
-    
-    // Update the session object with new expiration
     session.expires_at = newExpiresAt;
     sessionRefreshed = true;
   }
 
-  return {
-    session,
-    user,
-    sessionRefreshed
-  };
+  return { session, user, sessionRefreshed };
 }
 
-/**
- * Delete a session
- * @param {string} token - Session token
- * @returns {Promise<number>} Number of deleted sessions
- */
 async function deleteSession(token) {
   return await deleteWhere('zen_auth_sessions', { token });
 }
 
-/**
- * Delete all sessions for a user
- * @param {string} userId - User ID
- * @returns {Promise<number>} Number of deleted sessions
- */
 async function deleteUserSessions(userId) {
   return await deleteWhere('zen_auth_sessions', { user_id: userId });
 }
 
-/**
- * Refresh a session (extend expiration)
- * @param {string} token - Session token
- * @returns {Promise<Object|null>} Updated session or null
- */
 async function refreshSession(token) {
   const session = await findOne('zen_auth_sessions', { token });
-  
   if (!session) return null;
-  
-  // Extend session by 30 days
   const expiresAt = new Date();
   expiresAt.setDate(expiresAt.getDate() + 30);
-  
   return await updateById('zen_auth_sessions', session.id, {
     expires_at: expiresAt,
     updated_at: new Date()
   });
 }
 
-export {
-  createSession,
-  validateSession,
-  deleteSession,
-  deleteUserSessions,
-  refreshSession
-};
+export { createSession, validateSession, deleteSession, deleteUserSessions, refreshSession };

src/core/users/verifications.js

@@ -0,0 +1,149 @@
+import crypto from 'crypto';
+import { create, findOne, deleteWhere } from '@zen/core/database';
+import { generateToken, generateId } from './password.js';
+
+async function createEmailVerification(email) {
+  const token = generateToken(32);
+  const expiresAt = new Date();
+  expiresAt.setHours(expiresAt.getHours() + 24);
+
+  await deleteWhere('zen_auth_verifications', { identifier: 'email_verification', value: email });
+
+  const verification = await create('zen_auth_verifications', {
+    id: generateId(),
+    identifier: 'email_verification',
+    value: email,
+    token,
+    expires_at: expiresAt,
+    updated_at: new Date()
+  });
+
+  return { ...verification, token };
+}
+
+async function verifyEmailToken(email, token) {
+  const verification = await findOne('zen_auth_verifications', {
+    identifier: 'email_verification',
+    value: email
+  });
+
+  if (!verification) return false;
+
+  // Timing-safe comparison — always operate on same-length buffers so that a
+  // wrong-length guess yields no measurable timing difference from a wrong-value guess.
+  const storedBuf   = Buffer.from(verification.token, 'utf8');
+  const providedBuf = Buffer.from(
+    token.length === verification.token.length ? token : verification.token,
+    'utf8'
+  );
+  const tokensMatch = crypto.timingSafeEqual(storedBuf, providedBuf)
+                      && token.length === verification.token.length;
+  if (!tokensMatch) return false;
+
+  if (new Date(verification.expires_at) < new Date()) {
+    await deleteWhere('zen_auth_verifications', { id: verification.id });
+    return false;
+  }
+
+  await deleteWhere('zen_auth_verifications', { id: verification.id });
+  return true;
+}
+
+async function createPasswordReset(email) {
+  const token = generateToken(32);
+  const expiresAt = new Date();
+  expiresAt.setHours(expiresAt.getHours() + 1);
+
+  await deleteWhere('zen_auth_verifications', { identifier: 'password_reset', value: email });
+
+  const reset = await create('zen_auth_verifications', {
+    id: generateId(),
+    identifier: 'password_reset',
+    value: email,
+    token,
+    expires_at: expiresAt,
+    updated_at: new Date()
+  });
+
+  return { ...reset, token };
+}
+
+async function verifyResetToken(email, token) {
+  const reset = await findOne('zen_auth_verifications', {
+    identifier: 'password_reset',
+    value: email
+  });
+
+  if (!reset) return false;
+
+  // Timing-safe comparison — same rationale as verifyEmailToken above.
+  const storedBuf   = Buffer.from(reset.token, 'utf8');
+  const providedBuf = Buffer.from(
+    token.length === reset.token.length ? token : reset.token,
+    'utf8'
+  );
+  const tokensMatch = crypto.timingSafeEqual(storedBuf, providedBuf)
+                      && token.length === reset.token.length;
+  if (!tokensMatch) return false;
+
+  if (new Date(reset.expires_at) < new Date()) {
+    await deleteWhere('zen_auth_verifications', { id: reset.id });
+    return false;
+  }
+
+  return true;
+}
+
+function deleteResetToken(email) {
+  return deleteWhere('zen_auth_verifications', { identifier: 'password_reset', value: email });
+}
+
+async function createAccountSetup(email) {
+  const token = generateToken(32);
+  const expiresAt = new Date();
+  expiresAt.setHours(expiresAt.getHours() + 48);
+
+  await deleteWhere('zen_auth_verifications', { identifier: 'account_setup', value: email });
+
+  const setup = await create('zen_auth_verifications', {
+    id: generateId(),
+    identifier: 'account_setup',
+    value: email,
+    token,
+    expires_at: expiresAt,
+    updated_at: new Date()
+  });
+
+  return { ...setup, token };
+}
+
+async function verifyAccountSetupToken(email, token) {
+  const setup = await findOne('zen_auth_verifications', {
+    identifier: 'account_setup',
+    value: email
+  });
+
+  if (!setup) return false;
+
+  const storedBuf   = Buffer.from(setup.token, 'utf8');
+  const providedBuf = Buffer.from(
+    token.length === setup.token.length ? token : setup.token,
+    'utf8'
+  );
+  const tokensMatch = crypto.timingSafeEqual(storedBuf, providedBuf)
+                      && token.length === setup.token.length;
+  if (!tokensMatch) return false;
+
+  if (new Date(setup.expires_at) < new Date()) {
+    await deleteWhere('zen_auth_verifications', { id: setup.id });
+    return false;
+  }
+
+  return true;
+}
+
+function deleteAccountSetupToken(email) {
+  return deleteWhere('zen_auth_verifications', { identifier: 'account_setup', value: email });
+}
+
+export { createEmailVerification, verifyEmailToken, createPasswordReset, verifyResetToken, deleteResetToken, createAccountSetup, verifyAccountSetupToken, deleteAccountSetupToken };

src/features/admin/AdminLayout.server.js

@@ -0,0 +1,27 @@
+import AdminShell from './components/AdminShell.js';
+import { protectAdmin } from './protect.js';
+import { buildNavigationSections, buildBottomNavItems } from './navigation.js';
+import { logoutAction } from '@zen/core/features/auth/actions';
+import { getAppName } from '@zen/core';
+import { getUserPermissions } from '@zen/core/users';
+import './widgets/index.server.js';
+
+export default async function AdminLayout({ children }) {
+  const session = await protectAdmin();
+  const appName = getAppName();
+  const permissions = await getUserPermissions(session.user.id);
+  const navigationSections = buildNavigationSections('/', permissions);
+  const bottomNavItems = buildBottomNavItems('/');
+
+  return (
+    <AdminShell
+      user={session.user}
+      onLogout={logoutAction}
+      appName={appName}
+      navigationSections={navigationSections}
+      bottomNavItems={bottomNavItems}
+    >
+      {children}
+    </AdminShell>
+  );
+}

src/features/admin/AdminPage.client.js

@@ -0,0 +1,34 @@
+'use client';
+
+import { getPage } from './registry.js';
+import './pages/DashboardPage.client.js';
+import './pages/UsersPage.client.js';
+import './pages/RolesPage.client.js';
+import './pages/ProfilePage.client.js';
+import './pages/SettingsPage.client.js';
+import './pages/ConfirmEmailChangePage.client.js';
+import './widgets/index.client.js';
+import './devkit/DevkitPage.client.js';
+import '../media/pages/MediaPage.client.js';
+
+export default function AdminPageClient({ params, user, widgetData, appConfig, devkitEnabled }) {
+  const parts = params?.admin || [];
+  const [first] = parts;
+
+  const slug = first || 'dashboard';
+  const page = getPage(slug) || getPage('dashboard');
+
+  if (!page) return null;
+
+  const { Component } = page;
+  if (slug === 'dashboard') {
+    return <Component user={user} stats={widgetData} />;
+  }
+  if (slug === 'settings') {
+    return <Component user={user} appConfig={appConfig} />;
+  }
+  if (slug === 'devkit') {
+    return <Component user={user} params={parts} devkitEnabled={devkitEnabled} />;
+  }
+  return <Component user={user} params={parts} />;
+}

src/features/admin/AdminPage.server.js

@@ -0,0 +1,28 @@
+import AdminPageClient from './AdminPage.client.js';
+import { protectAdmin } from './protect.js';
+import { collectWidgetData } from './registry.js';
+import { getAppConfig, getPublicBaseUrl } from '@zen/core';
+import { isDevkitEnabled } from '../../shared/lib/appConfig.js';
+import { getUserPermissions } from '@zen/core/users';
+
+export default async function AdminPage({ params }) {
+  const resolvedParams = await params;
+  const session = await protectAdmin();
+  const [widgetData, permissions] = await Promise.all([
+    collectWidgetData(),
+    getUserPermissions(session.user.id),
+  ]);
+  const appConfig = { ...getAppConfig(), siteUrl: getPublicBaseUrl() };
+  const devkitEnabled = isDevkitEnabled();
+  const user = { ...session.user, permissions };
+
+  return (
+    <AdminPageClient
+      params={resolvedParams}
+      user={user}
+      widgetData={widgetData}
+      appConfig={appConfig}
+      devkitEnabled={devkitEnabled}
+    />
+  );
+}

src/features/admin/README.md

@@ -0,0 +1,324 @@
+# Admin
+
+Ce répertoire fournit l'interface d'administration complète : layout, navigation, tableau de bord, gestion des utilisateurs et des rôles. Il expose un **registre runtime** pour permettre aux projets consommateurs d'ajouter des widgets, des entrées de navigation et des pages sans modifier le core.
+
+> Le pattern `zen.extensions.js` documenté ici reste valide pour les extensions in-projet (extensions ad hoc spécifiques à une app). Pour distribuer une extension réutilisable comme un package npm, consulter [docs/MODULES.md](../../../docs/MODULES.md) — la même API d'enregistrement s'utilise mais le module est auto-découvert via les `dependencies` du projet consommateur.
+
+---
+
+## Structure
+
+```
+src/features/admin/
+├── index.js                    buildNavigationSections, registre (Next.js-free)
+├── protect.js                  gardes d'accès
+├── navigation.js               buildNavigationSections, buildBottomNavItems, getNavItemBasePath, findActiveNavContext
+├── registry.js                 registre runtime d'extensions
+├── AdminLayout.server.js       layout RSC de l'admin
+├── AdminPage.server.js         page RSC racine (protège + collecte les données widgets)
+├── AdminPage.client.js         shell client
+├── components/
+│   ├── index.js                re-export
+│   ├── AdminHeader.js
+│   ├── AdminShell.js
+│   ├── AdminSidebar.js
+│   ├── AdminTop.js
+│   ├── RoleEditModal.client.js
+│   ├── ThemeToggle.js
+│   ├── UserCreateModal.client.js
+│   └── UserEditModal.client.js
+├── devkit/
+│   ├── ComponentsPage.client.js
+│   ├── DevkitPage.client.js
+│   └── IconsPage.client.js
+├── pages/
+│   ├── ConfirmEmailChangePage.client.js
+│   ├── DashboardPage.client.js
+│   ├── ProfilePage.client.js
+│   ├── RolesPage.client.js
+│   ├── SettingsPage.client.js
+│   └── UsersPage.client.js
+└── widgets/
+    ├── index.client.js         auto-registration des widgets core (côté client)
+    ├── index.server.js         auto-registration des widgets core (côté serveur)
+    ├── users.client.js         widget Utilisateurs (composant)
+    └── users.server.js         widget Utilisateurs (fetcher)
+```
+
+---
+
+## Import
+
+```js
+// Gardes RSC — chemin dédié (next/navigation + next/headers, non compatible turbopackIgnore)
+import { protectAdmin, isAdmin } from '@zen/core/features/admin/protect';
+
+// Registre et navigation — compatible modules externes
+import { buildNavigationSections } from '@zen/core/features/admin';
+import {
+  registerWidget,
+  registerWidgetFetcher,
+  registerNavItem,
+  registerNavSection,
+  registerPage,
+} from '@zen/core/features/admin';
+```
+
+---
+
+## Pages intégrées
+
+| Route | Page |
+|-------|------|
+| `/admin/dashboard` | Tableau de bord avec widgets |
+| `/admin/users` | Liste, création et gestion des utilisateurs |
+| `/admin/roles` | Gestion des rôles et permissions |
+| `/admin/settings` | Paramètres de l'application |
+| `/admin/profile` | Profil de l'utilisateur connecté |
+| `/admin/confirm-email-change` | Confirmation de changement d'email |
+
+---
+
+## API
+
+### `protectAdmin(options?)`
+
+Garde serveur. Redirige si l'utilisateur n'est pas connecté ou n'a pas la permission `ADMIN_ACCESS`. Retourne la session courante.
+
+```js
+const session = await protectAdmin();
+// session.user est disponible
+```
+
+| Option | Type | Défaut | Description |
+|--------|------|--------|-------------|
+| `redirectTo` | `string` | `'/auth/login'` | Redirection si non authentifié |
+| `forbiddenRedirect` | `string` | `'/'` | Redirection si non autorisé |
+
+---
+
+### `isAdmin()`
+
+Vérifie si l'utilisateur courant a la permission `ADMIN_ACCESS`. Retourne `boolean`.
+
+```js
+const admin = await isAdmin();
+if (!admin) return null;
+```
+
+---
+
+### `buildNavigationSections(pathname, userPermissions?)`
+
+Construit les sections de navigation pour la sidebar à partir du registre. Marque l'entrée active selon `pathname`. Les items dont le champ `permission` n'est pas présent dans `userPermissions` sont automatiquement exclus ; si tous les items d'une section sont exclus, la section disparaît également.
+
+```js
+const permissions = await getUserPermissions(session.user.id);
+const sections = buildNavigationSections('/admin/users', permissions);
+// [{ id, title, icon, items: [{ name, href, icon, current }] }]
+```
+
+---
+
+## Registre d'extensions
+
+Le registre permet d'ajouter des widgets, des entrées de navigation et des pages sans toucher au core. Les enregistrements se font via des imports à effet de bord dans le layout racine du projet consommateur.
+
+### Ajouter un widget
+
+Un widget est composé de deux parties : un fetcher serveur qui collecte les données, et un composant client qui les affiche.
+
+```js
+// app/admin/orders/ordersWidget.server.js
+import { registerWidgetFetcher } from '@zen/core/features/admin';
+import { countOrders } from './orders.server.js';
+
+registerWidgetFetcher('orders', async () => ({
+  total: await countOrders(),
+}));
+```
+
+```js
+// app/admin/orders/ordersWidget.client.js
+'use client';
+import { registerWidget } from '@zen/core/features/admin';
+import { StatCard } from '@zen/core/shared/components';
+
+function OrdersWidget({ data, loading }) {
+  return (
+    <StatCard
+      title="Commandes"
+      value={loading ? '-' : String(data?.total ?? 0)}
+      loading={loading}
+    />
+  );
+}
+
+registerWidget({ id: 'orders', Component: OrdersWidget, order: 20 });
+```
+
+Le composant reçoit `data` (retour du fetcher) et `loading` (booléen). Si le fetcher échoue, `data` est `null` et `loading` reste `false`.
+
+**`registerWidgetFetcher(id, fetcher)`**
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | Identifiant unique du widget |
+| `fetcher` | `async () => object` | Fonction serveur qui retourne les données |
+
+**`registerWidget({ id, Component, order?, permission? })`**
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | Identifiant unique (doit correspondre au fetcher) |
+| `Component` | `ReactComponent` | Composant client affiché dans le tableau de bord |
+| `order` | `number` | Position dans la grille (défaut : `0`) |
+| `permission` | `string` | Clé de permission requise pour voir ce widget (ex. `'users.view'`). Le widget est masqué si l'utilisateur ne possède pas cette permission. |
+
+---
+
+### Ajouter une entrée de navigation
+
+```js
+import { registerNavSection, registerNavItem } from '@zen/core/features/admin';
+
+registerNavSection({ id: 'commerce', title: 'Commerce', icon: 'ShoppingBag03Icon', order: 30 });
+
+registerNavItem({
+  id: 'orders',
+  label: 'Commandes',
+  icon: 'ShoppingBag03Icon',
+  href: '/admin/orders',
+  sectionId: 'commerce',
+  order: 10,
+  permission: 'orders.view', // optionnel — masqué si l'utilisateur n'a pas cette permission
+});
+```
+
+**`registerNavSection({ id, title, icon, order? })`**
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | Identifiant unique de la section |
+| `title` | `string` | Titre affiché dans la sidebar |
+| `icon` | `string` | Nom d'icône Hugeicons |
+| `order` | `number` | Ordre d'affichage (défaut : `0`) |
+
+**`registerNavItem({ id, label, icon, href, basePath?, sectionId?, order?, position?, permission? })`**
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | Identifiant unique de l'entrée |
+| `label` | `string` | Texte affiché |
+| `icon` | `string` | Nom d'icône Hugeicons |
+| `href` | `string` | URL de destination (cible du clic dans la sidebar) |
+| `basePath` | `string` | Préfixe de routes considérées « sous » cette entrée — utilisé pour souligner l'item actif et construire le fil d'Ariane sur les sous-routes (`/edit/:id`, `/new`...). Auto-déduit : si `href` finit par `/list`, on retire le `/list` ; sinon `basePath = href`. À spécifier explicitement uniquement quand l'auto-déduction ne suffit pas. |
+| `sectionId` | `string` | Section parente (défaut : `'main'`) |
+| `order` | `number` | Ordre d'affichage (défaut : `0`) |
+| `position` | `string` | `'bottom'` pour épingler en bas de la sidebar |
+| `permission` | `string` | Clé de permission requise pour voir cette entrée (ex. `'orders.view'`). L'entrée est masquée si l'utilisateur ne possède pas cette permission. |
+
+#### Item actif et fil d'Ariane
+
+L'item « actif » dans la sidebar est celui dont le `basePath` matche le préfixe **le plus long** du pathname courant. Sur `/admin/posts/blogue/edit/1`, l'item « Posts » (basePath `/admin/posts/blogue`) est souligné ; sur `/admin/posts/blogue/taxonomies/categories`, c'est l'item « Catégories » qui gagne car son basePath est plus spécifique.
+
+Le fil d'Ariane se construit automatiquement à partir de cet item :
+
+- `[icon] > <section.title> > <item.label>` — si la section contient plusieurs items
+- `[icon] > <item.label>` — si la section ne contient que cet item et qu'ils portent le même nom (ex : section "Utilisateurs" + item "Utilisateurs")
+- Suivi de `> Nouveau` ou `> Modification` quand l'URL contient `/new` ou `/edit/:id` après le basePath.
+
+Pour personnaliser les labels d'action, enregistrer une page avec un slug `<root>:new` ou `<root>:edit` :
+
+```js
+registerPage({ slug: 'posts:edit', breadcrumbLabel: "Modifier l'article" });
+registerPage({ slug: 'posts:new',  breadcrumbLabel: 'Nouvel article' });
+```
+
+(`<root>` = premier segment d'URL après `/admin/`, ex : `posts` pour `/admin/posts/blogue/edit/1`.)
+
+---
+
+### Ajouter une page
+
+```js
+import { registerPage } from '@zen/core/features/admin';
+import OrdersPage from './OrdersPage.js';
+
+registerPage({
+  slug: 'orders',
+  Component: OrdersPage,
+  title: 'Commandes',
+});
+```
+
+La page est rendue sous `/admin/<slug>`. `AdminPage.client.js` résout le composant à partir du slug dans les paramètres de route.
+
+**`registerPage({ slug, Component, title?, breadcrumbLabel? })`**
+
+| Paramètre | Type | Description |
+|-----------|------|-------------|
+| `slug` | `string` | Segment d'URL sous `/admin/` |
+| `Component` | `ReactComponent` | Composant client rendu pour cette route |
+| `title` | `string` | Titre de la page (optionnel) |
+| `breadcrumbLabel` | `string` | Label du fil d'Ariane (optionnel, défaut : `title`) |
+
+---
+
+## Câbler les extensions dans le projet consommateur
+
+Regrouper tous les enregistrements dans un fichier de point d'entrée unique, puis l'importer une seule fois depuis le layout racine.
+
+```js
+// app/zen.extensions.js
+import './admin/orders/ordersWidget.server.js';
+import './admin/orders/ordersWidget.client.js';
+import { registerNavSection, registerNavItem, registerPage } from '@zen/core/features/admin';
+import OrdersPage from './admin/orders/OrdersPage.js';
+
+registerNavSection({ id: 'commerce', title: 'Commerce', icon: 'ShoppingBag03Icon', order: 30 });
+registerNavItem({ id: 'orders', label: 'Commandes', icon: 'ShoppingBag03Icon', href: '/admin/orders', sectionId: 'commerce', permission: 'orders.view' });
+registerPage({ slug: 'orders', Component: OrdersPage, title: 'Commandes' });
+```
+
+```js
+// app/layout.js
+import './zen.extensions'; // les side effects enregistrent tout
+```
+
+---
+
+## DevKit
+
+Le DevKit est une section de l'admin réservée au développement. Il expose une galerie de composants et un catalogue d'icônes. Il s'active via la variable d'environnement `ZEN_DEVKIT_ENABLED=true` et n'est jamais rendu en production.
+
+| Route | Contenu |
+|-------|---------|
+| `/admin/devkit/components` | Galerie des composants partagés |
+| `/admin/devkit/icons` | Catalogue d'icônes Hugeicons |
+
+---
+
+## Ajouter un widget core
+
+Les widgets intégrés au core suivent le même pattern que les widgets consommateurs, avec une étape supplémentaire : déclarer les fichiers dans les index d'auto-registration.
+
+```js
+// src/features/admin/widgets/myWidget.server.js
+import { registerWidgetFetcher } from '../registry.js';
+registerWidgetFetcher('myWidget', async () => ({ ... }));
+
+// src/features/admin/widgets/index.server.js
+import './myWidget.server.js'; // ajouter cette ligne
+```
+
+```js
+// src/features/admin/widgets/myWidget.client.js
+'use client';
+import { registerWidget } from '../registry.js';
+// ...
+registerWidget({ id: 'myWidget', Component: MyWidget, order: 20 });
+
+// src/features/admin/widgets/index.client.js
+import './myWidget.client.js'; // ajouter cette ligne
+```

src/features/admin/actions.js

@@ -1,12 +0,0 @@
-/**
- * Admin Server Actions
- * 
- * These are exported separately from admin/index.js to avoid bundling
- * server-side code (which includes database imports) into client components.
- * 
- * Usage:
- * import { getDashboardStats, getModuleDashboardStats } from '@zen/core/admin/actions';
- */
-
-export { getDashboardStats } from './actions/statsActions.js';
-export { getAllModuleDashboardStats as getModuleDashboardStats } from '@zen/core/modules/actions';

src/features/admin/actions/statsActions.js

@@ -1,80 +0,0 @@
-/**
- * Admin Stats Actions
- * Server-side actions for core dashboard statistics
- * 
- * Module-specific stats are handled by each module's dashboard actions.
- * See src/modules/{module}/dashboard/statsActions.js
- * 
- * Usage in your Next.js app:
- * 
- * ```javascript
- * // app/(admin)/admin/[...admin]/page.js
- * import { protectAdmin } from '@zen/core/admin';
- * import { getDashboardStats, getModuleDashboardStats } from '@zen/core/admin/actions';
- * import { AdminPagesClient } from '@zen/core/admin/pages';
- * 
- * export default async function AdminPage({ params }) {
- *   const { user } = await protectAdmin();
- *   
- *   // Fetch core dashboard stats
- *   const statsResult = await getDashboardStats();
- *   const dashboardStats = statsResult.success ? statsResult.stats : null;
- *   
- *   // Fetch module dashboard stats (for dynamic widgets)
- *   const moduleStats = await getModuleDashboardStats();
- *   
- *   return (
- *     <AdminPagesClient 
- *       params={params} 
- *       user={user}
- *       dashboardStats={dashboardStats}
- *       moduleStats={moduleStats}
- *     />
- *   );
- * }
- * ```
- */
-
-'use server';
-
-import { query } from '@zen/core/database';
-import { fail } from '../../../shared/lib/logger.js';
-
-/**
- * Get total number of users
- * @returns {Promise<number>}
- */
-async function getTotalUsersCount() {
-  try {
-    const result = await query(
-      `SELECT COUNT(*) as count FROM zen_auth_users`
-    );
-    return parseInt(result.rows[0].count) || 0;
-  } catch (error) {
-    fail(`Error getting users count: ${error.message}`);
-    return 0;
-  }
-}
-
-/**
- * Get core dashboard statistics
- * @returns {Promise<Object>}
- */
-export async function getDashboardStats() {
-  try {
-    const totalUsers = await getTotalUsersCount();
-
-    return {
-      success: true,
-      stats: {
-        totalUsers,
-      }
-    };
-  } catch (error) {
-    fail(`Error getting dashboard stats: ${error.message}`);
-    return { 
-      success: false, 
-      error: error.message || 'Failed to get dashboard statistics' 
-    };
-  }
-}

src/features/admin/components/AdminHeader.js

@@ -1,213 +1,30 @@
 'use client';
 
-import React from 'react';
-import { Menu, Transition } from '@headlessui/react';
-import { Fragment } from 'react';
-import { ChevronDownIcon } from '../../../shared/Icons.js';
 import { useRouter } from 'next/navigation';
-import ThemeToggle from './ThemeToggle';
+import { Button } from '@zen/core/shared/components';
 
-const AdminHeader = ({ isMobileMenuOpen, setIsMobileMenuOpen, user, onLogout, appName = 'ZEN' }) => {
+const AdminHeader = ({ title, description, backHref, backLabel = '← Retour', action }) => {
   const router = useRouter();
 
-    const getImageUrl = (imageKey) => {
-        if (!imageKey) return null;
-        return `/zen/api/storage/${imageKey}`;
-    };
-    
-    const handleLogout = async () => {
-        try {
-            if (onLogout) {
-                const result = await onLogout();
-                if (result && result.success) {
-                    router.push('/auth/login');
-                } else {
-                    console.error('Logout failed:', result?.error);
-                    router.push('/auth/login');
-                }
-            } else {
-                router.push('/auth/login');
-            }
-        } catch (error) {
-            console.error('Logout error:', error);
-            router.push('/auth/login');
-        }
-    };
-
-    const getUserInitials = (name) => {
-        if (!name) return 'U';
-        return name
-            .split(' ')
-            .map(n => n[0])
-            .join('')
-            .toUpperCase()
-            .slice(0, 2);
-    };
-
-    const quickLinks = [];
-
-    const userInitials = getUserInitials(user?.name);
-
   return (
-        <header className="bg-white dark:bg-black border-b border-neutral-200 dark:border-neutral-800/70 sticky top-0 z-30 h-14 flex items-center w-full">
-            <div className="flex items-center justify-between lg:justify-end px-4 lg:px-6 py-2 w-full">
-                {/* Left section - Mobile menu button + Logo (hidden on desktop) */}
-                <div className="flex items-center space-x-3 lg:hidden">
-                    <button
-                        onClick={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
-                        className="p-2 rounded-lg bg-neutral-100 dark:bg-neutral-900/50 border border-neutral-200 dark:border-neutral-700/50 text-neutral-900 dark:text-white hover:bg-neutral-200 dark:hover:bg-neutral-800 transition-colors duration-200"
-                        aria-label="Toggle menu"
-                    >
-                        <svg className={`h-5 w-5 transition-transform duration-200 ${isMobileMenuOpen ? 'rotate-90' : ''}`} fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d={isMobileMenuOpen ? "M6 18L18 6M6 6l12 12" : "M4 6h16M4 12h16M4 18h16"} />
-                        </svg>
-                    </button>
-                    <h1 className="text-neutral-900 dark:text-white font-semibold text-lg">{appName}</h1>
-                </div>
-
-                {/* Right Section - Theme Toggle + Quick Links + Profile */}
-                <div className="flex items-center space-x-3 sm:space-x-4">
-                    {/* Quick Links - Hidden on very small screens */}
-                    <nav className="hidden sm:flex items-center space-x-4 lg:space-x-6">
-                        {quickLinks.map((link) => (
-                            <a
-                                key={link.name}
-                                href={link.href}
-                                className="text-sm text-neutral-600 dark:text-neutral-300 hover:text-neutral-900 dark:hover:text-white transition-colors duration-200"
-                            >
-                                {link.name}
-                            </a>
-                        ))}
-                    </nav>
-
-                    {/* Theme Toggle */}
-                    <ThemeToggle />
-
-                    {/* User Profile Menu */}
-                    <Menu as="div" className="relative">
-                        <Menu.Button className="cursor-pointer flex items-center space-x-2 sm:space-x-3 px-2 sm:px-3 py-2 rounded-xl hover:bg-neutral-100 dark:hover:bg-neutral-800/50 transition-all duration-200 group ui-open:bg-neutral-100 dark:ui-open:bg-neutral-800/50 outline-none">
-                            {/* Avatar for desktop - hidden on mobile */}
-                            <div className="hidden sm:flex items-center space-x-3">
-                                {getImageUrl(user?.image) && (
-                                    <img
-                                        src={getImageUrl(user.image)}
-                                        alt={user?.name || 'User'}
-                                        className="w-8 h-8 rounded-lg object-cover"
-                                    />
-                                )}
-                                <div className="text-left">
-                                    <p className="text-sm font-medium text-neutral-900 dark:text-white">{user?.name || 'User'}</p>
-                                </div>
-                            </div>
-                            {/* Avatar for mobile - visible on mobile only */}
-                            <div className="sm:hidden">
-                                {getImageUrl(user?.image) && (
-                                    <img
-                                        src={getImageUrl(user.image)}
-                                        alt={user?.name || 'User'}
-                                        className="w-8 h-8 rounded-lg object-cover"
-                                    />
-                                )}
-                            </div>
-                            <ChevronDownIcon className="h-4 w-4 text-neutral-400 transition-transform duration-200 ui-open:rotate-180" />
-                        </Menu.Button>
-
-                        <Transition
-                            as={Fragment}
-                            enter="transition ease-out duration-200"
-                            enterFrom="opacity-0 -translate-y-2"
-                            enterTo="opacity-100 translate-y-0"
-                            leave="transition ease-in duration-150"
-                            leaveFrom="opacity-100 translate-y-0"
-                            leaveTo="opacity-0 -translate-y-2"
-                        >
-                            <Menu.Items className="absolute right-0 mt-2 w-56 sm:w-64 bg-white dark:bg-neutral-900/95 backdrop-blur-sm border border-neutral-200 dark:border-neutral-700/50 rounded-xl shadow-xl z-50 outline-none">
-                                <div className="p-4 border-b border-neutral-200 dark:border-neutral-700/50">
-                                    <div className="flex items-center space-x-3">
-                                        {getImageUrl(user?.image) && (
-                                            <img
-                                                src={getImageUrl(user.image)}
-                                                alt={user?.name || 'User'}
-                                                className="w-10 h-10 rounded-lg object-cover"
-                                            />
-                                        )}
+    <div className="flex items-center justify-between">
+      <div className="flex items-center gap-3">
         <div>
-                                            <p className="text-sm font-medium text-neutral-900 dark:text-white">{user?.name || 'User'}</p>
-                                            <p className="text-xs text-neutral-400">{user?.email || 'email@example.com'}</p>
-                                        </div>
-                                    </div>
-                                </div>
-                                
-                                {/* Quick Links for mobile */}
-                                {quickLinks.length > 0 && (
-                                    <div className="sm:hidden py-2 border-b border-neutral-200 dark:border-neutral-700/50">
-                                        {quickLinks.map((link) => (
-                                            <Menu.Item key={link.name}>
-                                                {({ active }) => (
-                                                    <a 
-                                                        href={link.href} 
-                                                        className={`flex items-center px-4 py-3 text-sm transition-all duration-200 ${
-                                                            active 
-                                                                ? 'bg-neutral-100 dark:bg-neutral-800/50 text-neutral-900 dark:text-white' 
-                                                                : 'text-neutral-600 dark:text-neutral-300'
-                                                        }`}
-                                                    >
-                                                        <svg className="mr-3 h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                                                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-                                                        </svg>
-                                                        {link.name}
-                                                    </a>
+          <h1 className="text-lg sm:text-xl font-semibold text-neutral-900 dark:text-white">{title}</h1>
+          {description && (
+            <p className="mt-1 text-[13px] text-neutral-500 dark:text-neutral-400">{description}</p>
           )}
-                                            </Menu.Item>
-                                        ))}
         </div>
+      </div>
+      <div className='flex gap-2'>
+        {backHref && (
+          <Button variant="secondary" onClick={() => router.push(backHref)}>
+            {backLabel}
+          </Button>
         )}
-                                
-                                <div className="py-2">
-                                    <Menu.Item>
-                                        {({ active }) => (
-                                            <a 
-                                                href="/admin/profile" 
-                                                className={`flex items-center px-4 py-3 text-sm transition-all duration-200 group ${
-                                                    active 
-                                                        ? 'bg-neutral-100 dark:bg-neutral-800/50 text-neutral-900 dark:text-white' 
-                                                        : 'text-neutral-600 dark:text-neutral-300'
-                                                }`}
-                                            >
-                                                <svg className="mr-3 h-4 w-4 group-hover:scale-110 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                                                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
-                                                </svg>
-                                                Mon profil
-                                            </a>
-                                        )}
-                                    </Menu.Item>
-                                    
-                                    <div className="border-t border-neutral-200 dark:border-neutral-700/50 mt-2 pt-2">
-                                        <Menu.Item>
-                                            {({ active }) => (
-                                                <button 
-                                                    onClick={handleLogout}
-                                                    className={`w-full flex items-center px-4 py-3 text-sm transition-all duration-200 group text-left ${
-                                                        active 
-                                                            ? 'bg-red-500/10 text-red-300' 
-                                                            : 'text-red-400'
-                                                    }`}
-                                                >
-                                                    <svg className="mr-3 h-4 w-4 group-hover:scale-110 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                                                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1" />
-                                                    </svg>
-                                                    Se déconnecter
-                                                </button>
-                                            )}
-                                        </Menu.Item>
+        {action}
       </div>
     </div>
-                            </Menu.Items>
-                        </Transition>
-                    </Menu>
-                </div>
-            </div>
-        </header>
   );
 };
 

src/features/admin/components/AdminPages.js

@@ -1,85 +0,0 @@
-'use client';
-
-/**
- * Admin Pages Component
- * 
- * This component handles both core admin pages and module pages.
- * Module pages are loaded dynamically on the client where hooks work properly.
- */
-
-import { Suspense } from 'react';
-import DashboardPage from './pages/DashboardPage.js';
-import UsersPage from './pages/UsersPage.js';
-import UserEditPage from './pages/UserEditPage.js';
-import ProfilePage from './pages/ProfilePage.js';
-import { getModulePageLoader } from '../../../modules/modules.pages.js';
-
-// Loading component for suspense
-function PageLoading() {
-  return (
-    <div className="flex items-center justify-center min-h-[400px]">
-      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-white"></div>
-    </div>
-  );
-}
-
-export default function AdminPagesClient({
-  params,
-  user,
-  dashboardStats = null,
-  moduleStats = {},
-  modulePageInfo = null,
-  routeInfo = null,
-  enabledModules = {}
-}) {
-  // If this is a module page, render it with lazy loading
-  if (modulePageInfo && routeInfo) {
-    const LazyComponent = getModulePageLoader(modulePageInfo.module, modulePageInfo.path);
-    if (LazyComponent) {
-      // Build props for the page
-      const pageProps = { user };
-      if (routeInfo.action === 'edit' && routeInfo.id) {
-        // Add ID props for edit pages (modules may use different prop names)
-        pageProps.id = routeInfo.id;
-        pageProps.invoiceId = routeInfo.id;
-        pageProps.clientId = routeInfo.id;
-        pageProps.itemId = routeInfo.id;
-        pageProps.categoryId = routeInfo.id;
-        pageProps.transactionId = routeInfo.id;
-        pageProps.recurrenceId = routeInfo.id;
-        pageProps.templateId = routeInfo.id;
-        pageProps.postId = routeInfo.id;
-      }
-      
-      return (
-        <Suspense fallback={<PageLoading />}>
-          <LazyComponent {...pageProps} />
-        </Suspense>
-      );
-    }
-  }
-
-  // Determine core page from routeInfo or params
-  let currentPage = 'dashboard';
-  if (routeInfo?.path) {
-    const parts = routeInfo.path.split('/').filter(Boolean);
-    currentPage = parts[1] || 'dashboard'; // /admin/[page]
-  } else if (params?.admin) {
-    currentPage = params.admin[0] || 'dashboard';
-  }
-
-  // Core page components mapping (non-module pages)
-  const usersPageComponent = routeInfo?.action === 'edit' && routeInfo?.id
-    ? () => <UserEditPage userId={routeInfo.id} user={user} enabledModules={enabledModules} />
-    : () => <UsersPage user={user} />;
-
-  const corePages = {
-    dashboard: () => <DashboardPage user={user} stats={dashboardStats} moduleStats={moduleStats} enabledModules={enabledModules} />,
-    users: usersPageComponent,
-    profile: () => <ProfilePage user={user} />,
-  };
-
-  // Render the appropriate core page or default to dashboard
-  const CorePageComponent = corePages[currentPage];
-  return CorePageComponent ? <CorePageComponent /> : <DashboardPage user={user} stats={dashboardStats} moduleStats={moduleStats} enabledModules={enabledModules} />;
-}

src/features/admin/components/AdminShell.js

@@ -1,25 +1,32 @@
 'use client';
 
-import AdminSidebar from './AdminSidebar';
 import { useState } from 'react';
-import AdminHeader from './AdminHeader';
+import AdminSidebar from './AdminSidebar.js';
+import AdminTop from './AdminTop.js';
 
-export default function AdminPagesLayout({ children, user, onLogout, appName, enabledModules, navigationSections }) {
+export default function AdminShell({ children, user, onLogout, appName, navigationSections, bottomNavItems }) {
   const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
 
   return (
-    <div className="flex h-screen overflow-hidden bg-white dark:bg-black">
+    <div className="flex h-screen overflow-hidden bg-white dark:bg-black font-ibm-plex-sans">
       <AdminSidebar
         isMobileMenuOpen={isMobileMenuOpen}
         setIsMobileMenuOpen={setIsMobileMenuOpen}
         appName={appName}
-        enabledModules={enabledModules}
         navigationSections={navigationSections}
+        bottomNavItems={bottomNavItems}
       />
       <div className="flex-1 flex flex-col min-w-0">
-        <AdminHeader isMobileMenuOpen={isMobileMenuOpen} setIsMobileMenuOpen={setIsMobileMenuOpen} user={user} onLogout={onLogout} appName={appName} />
+        <AdminTop
+          isMobileMenuOpen={isMobileMenuOpen}
+          setIsMobileMenuOpen={setIsMobileMenuOpen}
+          user={user}
+          onLogout={onLogout}
+          appName={appName}
+          navigationSections={navigationSections}
+        />
         <main className="flex-1 overflow-y-auto bg-neutral-50 dark:bg-black">
-          <div className="px-4 sm:px-6 lg:px-8 xl:px-12 pt-4 sm:pt-6 lg:pt-8 pb-32 max-w-[1400px] mx-auto">
+          <div className="px-8 py-7 pb-32 max-w-[1920px] mx-auto">
             {children}
           </div>
         </main>

src/features/admin/components/AdminSidebar.js

@@ -3,62 +3,59 @@
 import React, { useState, useEffect } from 'react';
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
-import * as Icons from '../../../shared/Icons.js';
-import { ChevronDownIcon } from '../../../shared/Icons.js';
+import * as Icons from '@zen/core/shared/icons';
+import { ArrowDown01Icon } from '@zen/core/shared/icons';
 
 /**
  * Resolve icon name (string) to icon component
  * Icons are passed as strings from server to avoid serialization issues
  */
 function resolveIcon(iconNameOrComponent) {
-    // If it's already a component (function), return it
     if (typeof iconNameOrComponent === 'function') {
         return iconNameOrComponent;
     }
-    // If it's a string, look up in Icons
     if (typeof iconNameOrComponent === 'string') {
         return Icons[iconNameOrComponent] || Icons.DashboardSquare03Icon;
     }
-    // Default fallback
     return Icons.DashboardSquare03Icon;
 }
 
-const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledModules, navigationSections: serverNavigationSections }) => {
+const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledModules, navigationSections: serverNavigationSections, bottomNavItems = [] }) => {
     const pathname = usePathname();
 
-    // State to manage collapsed sections (all open by default)
-    const [collapsedSections, setCollapsedSections] = useState(new Set());
+    const isItemActive = (item) => {
+        const basePath = item.basePath || item.href;
+        return pathname === item.href || pathname === basePath || pathname.startsWith(basePath + '/');
+    };
+
+    const [collapsedSections, setCollapsedSections] = useState(() => {
+        const initial = new Set();
+        serverNavigationSections.forEach(section => {
+            const isActive = section.items.some(isItemActive);
+            if (!isActive) initial.add(section.id);
+        });
+        return initial;
+    });
 
-    // Function to toggle a section's state
     const toggleSection = (sectionId) => {
-        // Find the section to check if it has active items
-        const section = navigationSections.find(s => s.id === sectionId);
-        
-        // Don't allow collapsing sections with active items
-        if (section && isSectionActive(section)) {
-            return;
-        }
-        
         setCollapsedSections(prev => {
-            const newCollapsed = new Set(prev);
-            if (newCollapsed.has(sectionId)) {
-                newCollapsed.delete(sectionId);
+            const next = new Set(prev);
+            if (next.has(sectionId)) {
+                next.delete(sectionId);
             } else {
-                newCollapsed.add(sectionId);
+                next.add(sectionId);
             }
-            return newCollapsed;
+            return next;
         });
     };
 
-    // Handle mobile menu closure when clicking on a link
     const handleMobileLinkClick = () => {
         setIsMobileMenuOpen(false);
     };
 
-    // Close mobile menu on screen size change
     useEffect(() => {
         const handleResize = () => {
-            if (window.innerWidth >= 1024) { // lg breakpoint
+            if (window.innerWidth >= 1024) {
                 setIsMobileMenuOpen(false);
             }
         };
@@ -67,49 +64,59 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
         return () => window.removeEventListener('resize', handleResize);
     }, [setIsMobileMenuOpen]);
 
-    // Function to check if any item in a section is currently active
     const isSectionActive = (section) => {
         return section.items.some(item => item.current);
     };
 
-    // Function to check if a section should be rendered as a direct link
     const shouldRenderAsDirectLink = (section) => {
-        // Check if there's only one item and it has the same name as the section
         return section.items.length === 1 &&
                section.items[0].name.toLowerCase() === section.title.toLowerCase();
     };
 
-    // Update collapsed sections when pathname changes to ensure active sections are open
-    useEffect(() => {
-        setCollapsedSections(prev => {
-            const newSet = new Set(prev);
-            // Add any sections that have active items to ensure they stay open
-            navigationSections.forEach(section => {
-                if (isSectionActive(section)) {
-                    newSet.add(section.id);
-                }
-            });
-            return newSet;
-        });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [pathname]);
+    // Recalcule `current` côté client pour suivre les navigations Link sans
+    // dépendre d'un re-render serveur. Règle alignée sur navigation.js :
+    // match le plus long (href exact > basePath préfixe), un seul item actif.
+    const matchLen = (item) => {
+        if (pathname === item.href) return item.href.length;
+        const basePath = item.basePath || item.href;
+        if (pathname === basePath) return basePath.length;
+        if (pathname.startsWith(basePath + '/')) return basePath.length;
+        return 0;
+    };
+
+    let activeItemRef = null;
+    let activeItemLen = 0;
+    for (const section of serverNavigationSections) {
+        for (const item of section.items) {
+            const len = matchLen(item);
+            if (len > activeItemLen) {
+                activeItemRef = item;
+                activeItemLen = len;
+            }
+        }
+    }
 
-    // Use server-provided navigation sections if available, otherwise use core-only fallback
-    // Server navigation includes module navigation, fallback only has core pages
-    // Update the 'current' property based on the actual pathname (client-side)
     const navigationSections = serverNavigationSections.map(section => ({
         ...section,
         items: section.items.map(item => ({
             ...item,
-            current: pathname === item.href || pathname.startsWith(item.href + '/')
+            current: item === activeItemRef,
         }))
     }));
 
-    // Function to render a complete navigation section
+    const base = 'w-full flex items-center justify-between px-[10px] py-[7px] rounded-lg text-[13px] transition-colors duration-[120ms] ease-out';
+    const inactive = 'font-normal text-neutral-500 dark:text-neutral-400 hover:bg-neutral-100 dark:hover:bg-neutral-900 hover:text-neutral-900 dark:hover:text-white';
+
+    const parentBase = `${base}`;
+    const parentActif = 'bg-neutral-100 dark:bg-neutral-900 text-black dark:text-white font-medium';
+    const parentActifOuvert = 'text-black dark:text-white font-medium hover:bg-neutral-100 dark:hover:bg-neutral-900';
+
+    const subItemBase = base;
+    const subItemActif = 'bg-neutral-100 dark:bg-neutral-900 text-black dark:text-white font-medium';
+
     const renderNavSection = (section) => {
         const Icon = resolveIcon(section.icon);
 
-        // If section should be rendered as a direct link
         if (shouldRenderAsDirectLink(section)) {
             const item = section.items[0];
             return (
@@ -117,18 +124,14 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
                     <Link
                         href={item.href}
                         onClick={handleMobileLinkClick}
-                        className={`${
-                            item.current
-                                ? 'bg-neutral-100 dark:bg-neutral-800 text-neutral-900 dark:text-white'
-                                : 'text-neutral-900 dark:text-white hover:text-neutral-500 dark:hover:text-neutral-300'
-                        } w-full flex items-center justify-between border-y border-neutral-200 dark:border-neutral-800/70 px-4 py-2.5 -mb-[1px] text-[13px] tracking-wide transition-colorsduration-0`}
+                        className={`${parentBase} ${item.current ? parentActif : inactive}`}
                     >
-                        <div className="flex items-center">
-                            <Icon className="mr-3 h-4 w-4 flex-shrink-0" />
+                        <div className="flex items-center gap-2">
+                            <Icon className="h-[15px] w-[15px] flex-shrink-0" />
                             <span>{section.title}</span>
                         </div>
                         {item.badge && (
-                            <span className="bg-red-500 text-white text-xs px-1.5 py-0.5 rounded-full font-medium">
+                            <span className="bg-red-500 text-white text-[10px] px-1.5 py-0.5 rounded-lg font-medium">
                                 {item.badge}
                             </span>
                         )}
@@ -137,33 +140,33 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
             );
         }
 
-        // Regular section with expandable sub-items
-        const isCollapsed = !collapsedSections.has(section.id);
+        const isCollapsed = collapsedSections.has(section.id);
+        const isActive = isSectionActive(section);
 
         return (
             <div key={section.id}>
                 <button
                     onClick={() => toggleSection(section.id)}
-                    className="cursor-pointer w-full flex items-center justify-between border-y border-neutral-200 dark:border-neutral-800/70 px-4 py-2.5 -mb-[1px] text-[13px] text-neutral-900 dark:text-white tracking-wide hover:text-neutral-500 dark:hover:text-neutral-300 transition-colorsduration-0"
+                    className={`cursor-pointer ${parentBase} ${isActive && isCollapsed ? parentActif : isActive ? parentActifOuvert : inactive}`}
                 >
-                    <div className="flex items-center">
-                        <Icon className="mr-3 h-4 w-4 flex-shrink-0" />
+                    <div className="flex items-center gap-2">
+                        <Icon className="h-[15px] w-[15px] flex-shrink-0" />
                         <span>{section.title}</span>
                     </div>
-                    <ChevronDownIcon 
-                        className={`h-3 w-3 ${
+                    <ArrowDown01Icon
+                        className={`h-3 w-3 transition-transform duration-[120ms] ease-out ${
                             isCollapsed ? '-rotate-90' : 'rotate-0'
                         }`}
                     />
                 </button>
                 <div
-                    className={`overflow-hidden ${
+                    className={`overflow-hidden transition-all duration-[120ms] ease-out ${
                         isCollapsed
                             ? 'max-h-0 opacity-0'
                             : 'max-h-[1000px] opacity-100'
                     }`}
                 >
-                    <ul className="flex flex-col gap-0">
+                    <ul className="flex flex-col">
                         {section.items.map(renderNavItem)}
                     </ul>
                 </div>
@@ -171,26 +174,19 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
         );
     };
 
-    // Function to render a navigation item
     const renderNavItem = (item) => {
-        const Icon = resolveIcon(item.icon);
         return (
             <li key={item.name}>
                 <Link
                     href={item.href}
                     onClick={handleMobileLinkClick}
-                    className={`${
-                        item.current
-                            ? 'bg-neutral-100 dark:bg-neutral-800 text-neutral-900 dark:text-white'
-                            : 'text-neutral-500 dark:text-neutral-400 hover:bg-neutral-100 dark:hover:bg-neutral-800/50 hover:text-neutral-900 dark:hover:text-white'
-                    } group flex items-center justify-between px-4 py-1.5 text-[12px] font-medium transition-allduration-0`}
+                    className={`${subItemBase} ${item.current ? subItemActif : inactive}`}
                 >
                     <div className="flex items-center">
-                        <Icon className="mr-3 h-3.5 w-3.5 flex-shrink-0" />
-                        {item.name}
+                        <span className="pl-[25px]">{item.name}</span>
                     </div>
                     {item.badge && (
-                        <span className="bg-red-500 text-white text-xs px-1.5 py-0.5 rounded-full font-medium">
+                        <span className="bg-red-500 text-white text-[10px] px-1.5 py-0.5 rounded-lg font-medium">
                             {item.badge}
                         </span>
                     )}
@@ -204,7 +200,7 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
             {/* Mobile overlay */}
             {isMobileMenuOpen && (
                 <div
-                    className="lg:hidden fixed inset-0 bg-black/50 backdrop-blur-sm z-40"
+                    className="lg:hidden fixed inset-0 bg-black/50 z-40"
                     onClick={() => setIsMobileMenuOpen(false)}
                 />
             )}
@@ -212,20 +208,39 @@ const AdminSidebar = ({ isMobileMenuOpen, setIsMobileMenuOpen, appName, enabledM
             {/* Sidebar */}
             <div className={`
                 ${isMobileMenuOpen ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'}
-                fixed lg:static inset-y-0 left-0 z-40 w-64 bg-white dark:bg-black border-r border-neutral-200 dark:border-neutral-800/70 flex flex-col h-screen transition-transform duration-300 ease-in-out
+                fixed lg:static inset-y-0 left-0 z-40 w-[230px] bg-white dark:bg-black border-r border-neutral-200 dark:border-neutral-800/70 flex flex-col h-screen transition-transform duration-[120ms] ease-out
             `}>
-                {/* Logo Section */}
-                <Link href="/admin" className="px-4 h-14 flex items-center justify-start gap-2 border-b border-neutral-200 dark:border-neutral-800/70">
-                    <h1 className="text-neutral-900 dark:text-white font-semibold">{appName}</h1>
-                    <span className="bg-red-700/10 border border-red-600/20 text-red-600 uppercase text-[10px] leading-none px-2 py-1 rounded-full font-semibold">
-                        Admin
-                    </span>
+                {/* Logo */}
+                <Link href="/admin/dashboard" className="px-4 h-12 flex items-center justify-start gap-2 border-b border-neutral-200 dark:border-neutral-800/70">
+                    <h1 className="text-neutral-900 dark:text-white font-semibold text-sm">{appName}</h1>
                 </Link>
 
                 {/* Navigation */}
-                <nav className="flex-1 px-0 overflow-y-auto flex flex-col gap-0 pb-12 -mt-[1px]">
+                <nav className="flex-1 px-2 py-2 overflow-y-auto flex flex-col">
                     {navigationSections.map(renderNavSection)}
                 </nav>
+
+                {/* Bottom pinned items */}
+                {bottomNavItems.length > 0 && (
+                    <div className="px-2 py-2 border-t border-neutral-200 dark:border-neutral-800/70 shrink-0">
+                        {bottomNavItems.map((item) => {
+                            const Icon = resolveIcon(item.icon);
+                            return (
+                                <Link
+                                    key={item.href}
+                                    href={item.href}
+                                    onClick={handleMobileLinkClick}
+                                    className={`${base} ${item.current ? parentActif : inactive}`}
+                                >
+                                    <div className="flex items-center gap-2">
+                                        <Icon className="h-[15px] w-[15px] flex-shrink-0" />
+                                        <span>{item.name}</span>
+                                    </div>
+                                </Link>
+                            );
+                        })}
+                    </div>
+                )}
             </div>
         </>
     );

src/features/admin/components/AdminTop.js

@@ -0,0 +1,225 @@
+'use client';
+
+import { Fragment, useState, useEffect } from 'react';
+import { Menu, MenuButton, MenuItem, MenuItems, Transition } from '@headlessui/react';
+import { ArrowDown01Icon, ArrowRight01Icon, Menu01Icon, User03Icon, DashboardSquare03Icon, Logout02Icon } from '@zen/core/shared/icons';
+import { UserAvatar } from '@zen/core/shared/components';
+import { useRouter, usePathname } from 'next/navigation';
+import { getPage } from '../registry.js';
+import { useTheme, getThemeIcon } from '@zen/core/themes';
+import Link from 'next/link';
+
+const AdminTop = ({ isMobileMenuOpen, setIsMobileMenuOpen, user, onLogout, appName = 'ZEN', navigationSections = [] }) => {
+    const router = useRouter();
+    const pathname = usePathname();
+    const [pageTitle, setPageTitle] = useState('');
+
+    useEffect(() => {
+        const segments = pathname.replace(/^\/admin\/?/, '').split('/').filter(Boolean);
+        const slug = segments[0] || 'dashboard';
+        setPageTitle(getPage(slug)?.title || '');
+    }, [pathname]);
+
+    const handleLogout = async () => {
+        try {
+            if (onLogout) {
+                const result = await onLogout();
+                if (result && result.success) {
+                    router.push('/auth/login');
+                } else {
+                    console.error('Logout failed:', result?.error);
+                    router.push('/auth/login');
+                }
+            } else {
+                router.push('/auth/login');
+            }
+        } catch (error) {
+            console.error('Logout error:', error);
+            router.push('/auth/login');
+        }
+    };
+
+    const { theme, toggle, systemIsDark } = useTheme();
+    const ThemeIcon = getThemeIcon(theme, systemIsDark);
+    const themeLabel = theme === 'light' ? 'Mode clair' : theme === 'dark' ? 'Mode sombre' : 'Thème système';
+
+    const buildBreadcrumbs = () => {
+        const crumbs = [{ icon: DashboardSquare03Icon, href: '/admin/dashboard' }];
+        const after = pathname.replace(/^\/admin\/?/, '');
+        const segments = after.split('/').filter(Boolean);
+
+        if (!after || !segments.length || (segments[0] === 'dashboard' && segments.length === 1)) {
+            crumbs.push({ label: pageTitle });
+            return crumbs;
+        }
+
+        // Localise l'item actif via match le plus long (href exact > basePath préfixe).
+        // On recalcule côté client pour rester aligné sur AdminSidebar et suivre les
+        // navigations Link sans dépendre d'un re-render serveur du layout.
+        const matchLen = (item) => {
+            if (pathname === item.href) return item.href.length;
+            const basePath = item.basePath || item.href;
+            if (pathname === basePath) return basePath.length;
+            if (pathname.startsWith(basePath + '/')) return basePath.length;
+            return 0;
+        };
+
+        let activeSection = null;
+        let activeItem = null;
+        let activeLen = 0;
+        for (const section of navigationSections) {
+            for (const item of section.items) {
+                const len = matchLen(item);
+                if (len > activeLen) {
+                    activeSection = section;
+                    activeItem = item;
+                    activeLen = len;
+                }
+            }
+        }
+
+        if (!activeItem) {
+            // Page enregistrée hors navigation (ex : /admin/profile).
+            crumbs.push({ label: pageTitle });
+            return crumbs;
+        }
+
+        // Préfixer la section uniquement si elle ne se résume pas à un item unique
+        // du même nom (cas « direct link » dans la sidebar — section.title === item.name,
+        // ex : section "Utilisateurs" + item "Utilisateurs").
+        if (activeSection.title !== activeItem.name) {
+            crumbs.push({ label: activeSection.title });
+        }
+
+        const isExactPage = pathname === activeItem.href;
+        crumbs.push({ label: activeItem.name, href: isExactPage ? undefined : activeItem.href });
+
+        // Action de sous-route : segment juste après le basePath (/edit/:id, /new).
+        const basePath = activeItem.basePath || activeItem.href;
+        const trail = pathname.startsWith(basePath)
+            ? pathname.slice(basePath.length).split('/').filter(Boolean)
+            : [];
+        const action = trail[0];
+        if (action === 'new') {
+            const page = getPage(`${segments[0]}:new`);
+            crumbs.push({ label: page?.breadcrumbLabel || page?.title || 'Nouveau' });
+        } else if (action === 'edit') {
+            const page = getPage(`${segments[0]}:edit`);
+            crumbs.push({ label: page?.breadcrumbLabel || page?.title || 'Modification' });
+        }
+
+        return crumbs;
+    };
+
+    const breadcrumbs = buildBreadcrumbs();
+
+    return (
+        <header className="bg-white dark:bg-black border-b border-neutral-200 dark:border-neutral-800/70 sticky top-0 z-30 h-12 flex items-center w-full">
+            <div className="flex items-center justify-between px-4 lg:px-6 py-2 w-full">
+                {/* Left section — Mobile menu button + Logo / Desktop breadcrumb */}
+                <div className="flex items-center space-x-3 lg:hidden">
+                    <button
+                        onClick={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
+                        className="p-1 rounded-md text-neutral-500 dark:text-neutral-400 hover:text-neutral-900 dark:hover:text-white transition-colors duration-150"
+                        aria-label="Toggle menu"
+                    >
+                        <Menu01Icon className="h-5 w-5 transition-transform duration-200" />
+                    </button>
+                    <h1 className="text-neutral-900 dark:text-white font-semibold text-sm">{appName}</h1>
+                </div>
+
+                {/* Desktop breadcrumb — always rendered to keep user menu pinned right */}
+                <div className="hidden lg:flex items-center gap-1.5 text-[13px]">
+                    {breadcrumbs.length > 0 && breadcrumbs.map((crumb, i) => (
+                        <Fragment key={i}>
+                            {i > 0 && (
+                                <ArrowRight01Icon className="w-3 h-3 text-neutral-400 dark:text-neutral-600 flex-shrink-0" />
+                            )}
+                            {crumb.icon ? (
+                                <button
+                                    onClick={() => router.push(crumb.href)}
+                                    className="text-neutral-500 dark:text-neutral-400 hover:text-neutral-900 dark:hover:text-white transition-colors cursor-pointer"
+                                >
+                                    <crumb.icon className="w-4 h-4" />
+                                </button>
+                            ) : crumb.href ? (
+                                <button
+                                    onClick={() => router.push(crumb.href)}
+                                    className="text-neutral-500 dark:text-neutral-400 hover:text-neutral-900 dark:hover:text-white transition-colors cursor-pointer"
+                                >
+                                    {crumb.label}
+                                </button>
+                            ) : (
+                                <span className="text-neutral-900 dark:text-white font-medium">{crumb.label}</span>
+                            )}
+                        </Fragment>
+                    ))}
+                </div>
+
+                {/* Right section — Profile */}
+                <div className="flex items-center gap-3 sm:gap-4">
+                    {/* User Profile Menu */}
+                    <Menu as="div" className="relative">
+                        <MenuButton className="cursor-pointer flex items-center gap-2.5 px-2.5 py-1.5 rounded-xl hover:bg-black/5 dark:hover:bg-white/5 transition-colors duration-200 outline-none group">
+                            <UserAvatar user={user} size="sm" />
+                            {/* Name — desktop only */}
+                            <span className="hidden sm:block text-[13px] leading-none font-medium text-neutral-800 dark:text-white">
+                                {user?.name || 'User'}
+                            </span>
+                            <ArrowDown01Icon className="w-3.5 h-3.5 shrink-0 text-neutral-400 dark:text-neutral-600 transition-transform duration-200 group-data-open:rotate-180" />
+                        </MenuButton>
+
+                        <Transition
+                            as={Fragment}
+                            enter="transition ease-out duration-150"
+                            enterFrom="opacity-0 translate-y-1"
+                            enterTo="opacity-100 translate-y-0"
+                            leave="transition ease-in duration-100"
+                            leaveFrom="opacity-100 translate-y-0"
+                            leaveTo="opacity-0 translate-y-1"
+                        >
+                            <MenuItems className="absolute right-0 mt-4 w-48 outline-none rounded-xl border border-black/8 dark:border-white/8 bg-white dark:bg-[#0B0B0B] shadow-lg overflow-hidden z-50">
+                                <div className="p-1.5 flex flex-col gap-0.5">
+                                    {/* Profile */}
+                                    <MenuItem>
+                                        <Link
+                                            href="/admin/profile"
+                                            className="cursor-pointer w-full flex items-center gap-2 px-[7px] py-[10px] rounded-lg text-[13px] leading-none text-neutral-500 dark:text-neutral-400 transition-colors duration-[120ms] ease-out data-focus:bg-neutral-100 dark:data-focus:bg-white/5 data-focus:text-neutral-900 dark:data-focus:text-white"
+                                        >
+                                            <User03Icon className="w-4 h-4 shrink-0" />
+                                            Mon profil
+                                        </Link>
+                                    </MenuItem>
+
+                                    {/* Theme — pas de MenuItem pour ne pas fermer le menu au clic */}
+                                    <button
+                                        onClick={toggle}
+                                        className="cursor-pointer w-full flex items-center gap-2 px-[7px] py-[10px] rounded-lg text-[13px] leading-none text-neutral-500 dark:text-neutral-400 hover:bg-amber-50 dark:hover:bg-amber-500/10 hover:text-amber-500 dark:hover:text-amber-400 transition-colors duration-150"
+                                    >
+                                        <ThemeIcon className="w-4 h-4 shrink-0" />
+                                        {themeLabel}
+                                    </button>
+
+                                    <div className="h-px bg-black/6 dark:bg-white/6 my-0.5" />
+
+                                    {/* Logout */}
+                                    <MenuItem>
+                                        <button
+                                            onClick={handleLogout}
+                                            className="cursor-pointer w-full flex items-center gap-2 px-[7px] py-[10px] rounded-lg text-[13px] leading-none text-red-700 dark:text-red-600 transition-colors duration-150 text-left data-focus:bg-red-700/10 dark:data-focus:bg-red-700/20"
+                                        >
+                                            <Logout02Icon className="w-4 h-4 shrink-0" />
+                                            Se déconnecter
+                                        </button>
+                                    </MenuItem>
+                                </div>
+                            </MenuItems>
+                        </Transition>
+                    </Menu>
+                </div>
+            </div>
+        </header>
+    );
+};
+
+export default AdminTop;