nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/runtime/bearer.js

@@ -0,0 +1,84 @@
+//#region src/runtime/bearer.ts
+/**
+* Extraction du jeton d'un en-tête `Authorization: Bearer …` — sans expression
+* régulière, et volontairement.
+*
+* Le motif d'origine, `/^bearer\s+(.+)$/i`, était dupliqué dans deux
+* authentificateurs et **quadratique** : `\s+` suivi de `(.+)` laisse le moteur
+* essayer chaque point de découpage entre les deux quantificateurs. Un client
+* anonyme envoyant `Bearer ` suivi de milliers d'espaces faisait donc brûler du
+* temps processeur à chaque requête — sur la boucle d'événements, qui est
+* unique. Aggravant : le test de support s'exécute AVANT toute authentification,
+* donc le coût se paie pour un porteur qui n'a rien prouvé, et la taille
+* d'en-tête tolérée par Node (16 Kio) suffit largement à le rendre sensible.
+*
+* Ici, tout est linéaire : une comparaison de préfixe, un saut d'espaces, une
+* découpe. Aucun retour arrière n'est possible parce qu'il n'y a pas d'automate.
+*
+* **Séparateur restreint à l'espace et à la tabulation** : c'est ce que la
+* RFC 9110 §5.6.3 autorise entre le schéma et ses paramètres (`OWS`). `\s`
+* acceptait retours à la ligne et espaces Unicode — plus permissif que la norme,
+* pour aucun bénéfice.
+*
+* ## Pourquoi au CŒUR, et pas dans le module de sécurité
+*
+* Deux couches lisent le même en-tête sans pouvoir se voir : les
+* authentificateurs de `@nodefony/security`, et la porte MCP, dont le protocole
+* vit ici. Une frontière de paquets aurait imposé une copie — or une copie de
+* cette fonction ne diverge pas bruyamment : elle diverge sur un cas limite
+* (`Bearer …`, `Bearer` sans séparateur) que chaque copie continue de
+* passer dans ses propres tests. La règle « 1 règle = 1 implémentation » veut
+* donc qu'elle vive au niveau que les deux peuvent atteindre — le plus bas.
+*
+* Elle est ici, et non dans un dossier `mcp/`, parce qu'elle ne doit rien à ce
+* protocole : c'est de la sémantique HTTP, lue à chaque requête entrante.
+*/
+/** Le schéma, en minuscules — comparé sans allouer de version normalisée. */
+const SCHEME = "bearer";
+/**
+* Lit un en-tête `Authorization` et dit ce qu'il porte.
+*
+* @param header - la valeur brute de l'en-tête (absente, d'un autre schéma, ou
+*          vide — aucun de ces cas ne lève).
+* @returns le verdict de lecture ; jamais une exception.
+*/
+function readBearerHeader(header) {
+	if (typeof header !== "string" || header.length === 0) return { kind: "absent" };
+	if (header.length < 6) return { kind: "other" };
+	if (header.slice(0, 6).toLowerCase() !== SCHEME) return { kind: "other" };
+	let i = 6;
+	if (i === header.length) return { kind: "empty" };
+	const first = header.charCodeAt(i);
+	if (first !== 32 && first !== 9) return { kind: "other" };
+	while (i < header.length) {
+		const c = header.charCodeAt(i);
+		if (c !== 32 && c !== 9) break;
+		i++;
+	}
+	const token = header.slice(i).trimEnd();
+	return token.length > 0 ? {
+		kind: "token",
+		token
+	} : { kind: "empty" };
+}
+/**
+* Rend le jeton porté par un en-tête `Authorization`, ou `null`.
+*
+* Projection de {@link readBearerHeader} pour les appelants que la NUANCE ne
+* regarde pas — un authentificateur qui cherche un porteur et passe la main s'il
+* n'y en a pas. Une porte qui doit RÉPONDRE (401 ? 400 ? anonyme ?) lit le
+* verdict complet : sans lui, elle ne peut pas distinguer « rien présenté » de
+* « mal présenté », et elle tranche donc toujours du mauvais côté pour l'un des
+* deux.
+*
+* @param header - la valeur brute de l'en-tête (peut être absente ou d'un autre
+*          schéma — les deux rendent `null`, jamais une exception).
+* @returns le jeton débarrassé de ses espaces de tête et de queue, ou `null` si
+*          l'en-tête n'est pas un `Bearer` valide ou ne porte aucun jeton.
+*/
+function bearerToken(header) {
+	const lu = readBearerHeader(header);
+	return lu.kind === "token" ? lu.token : null;
+}
+//#endregion
+export { bearerToken, readBearerHeader };

package/dist/node/runtime/engineEnvironment.js

@@ -0,0 +1,79 @@
+//#region src/runtime/engineEnvironment.ts
+/**
+* Mode retenu lorsque ni l'environnement ni la commande n'en désignent un.
+*
+* 🔴 **`development`, et c'est un choix de SÛRETÉ.** Le raisonnement, parce
+* qu'il se reprendra le jour où quelqu'un voudra l'inverser :
+*
+* Ce défaut ne s'applique QUE si `NODE_ENV` est absent ET que la commande
+* n'exprime aucune intention. Or aucun serveur ne démarre dans cet état : les
+* trois lanceurs posent leur mode eux-mêmes (`ProdCommand`, `DevCommand`,
+* `ClusterCommand`), et il n'existe pas d'autre façon d'en lancer un. Le défaut
+* ne gouverne donc que les commandes UTILITAIRES — `inspect`, `check`, `env`,
+* `security:*` — tapées, dans leur écrasante majorité, sur un poste de
+* développement. Le défaut doit protéger le cas où l'information manque, et
+* l'information manque là.
+*
+* ⚠️ **Ce n'est pas le « 12-factor » qui le justifie** : sa section Config
+* déconseille au contraire les *environment groups* comme `NODE_ENV`, et rien
+* n'oblige un orchestrateur à le poser. Ce qui garantit le mode en production
+* ici est FACTUEL, pas doctrinal — l'image générée pose
+* `ENV NODE_ENV=production`, et les lanceurs déclarent leur intention. Ce qui
+* relève vraiment du 12-factor est la PRÉCÉDENCE : l'ambiant l'emporte sur
+* l'intention de la commande.
+*
+* Risque résiduel, nommé plutôt que masqué : une commande utilitaire lancée sur
+* un déploiement de production SANS `NODE_ENV` et HORS image officielle partira
+* en `development`. Le symétrique — le poste de développement traité comme la
+* production — est ce qui a réellement cassé trois fois : un jeton émis contre
+* la mauvaise configuration, une inspection montrant les modules de production
+* sur une machine de développement, et un contrôle de banc comparant deux
+* applications distinctes. Aucun n'a levé la moindre erreur.
+*/
+const DEFAULT_ENGINE_ENVIRONMENT = "development";
+/**
+* Le défaut à retenir SELON que `NODE_ENV` a été posé ou non.
+*
+* 🔴 **Poser `NODE_ENV` est un ACTE DE DÉPLOIEMENT ; ne rien poser est l'état
+* d'un poste de développement.** C'est toute la distinction, et l'ignorer a
+* failli coûter cher : une première version de cette règle rendait
+* `development` dès que `NODE_ENV` ne désignait aucun mode moteur — donc pour
+* `staging`, `canary`, `prod-eu`, `test`. Un déploiement de pré-production
+* aurait chargé les modules `policy:"dev"` (console d'administration, outillage
+* de développement) et détaillé ses traces. La suite de tests l'a arrêté.
+*
+* Les valeurs non-moteur ne sont donc PAS traitées comme une absence : elles
+* nomment un déploiement, et un déploiement tourne comme la production. Seule
+* l'absence TOTALE de la variable désigne un poste de développement.
+*
+* Une chaîne vide compte comme POSÉE — on ne peut pas distinguer « vidée par
+* erreur » de « vidée exprès », et le choix conservateur ne coûte qu'une
+* commande utilitaire, là où l'inverse expose une console d'administration.
+*
+* @param nodeEnv - `process.env.NODE_ENV` tel quel, `undefined` s'il est absent.
+* @returns le mode à retenir quand rien d'autre ne le désigne.
+*/
+function defaultEngineEnvironment(nodeEnv) {
+	return nodeEnv === void 0 ? DEFAULT_ENGINE_ENVIRONMENT : "production";
+}
+/**
+* Le mode MOTEUR que désigne une étiquette d'environnement — le « collapse ».
+*
+* 🔴 Tout ce qui n'est pas `dev`/`development` tourne comme la PRODUCTION :
+* `staging`, `canary`, `prod-eu` nomment un déploiement, et un déploiement est
+* optimisé, gated et tracé comme la production.
+*
+* Écrite ici, et nulle part ailleurs : cette règle décide à la fois de ce que
+* le Kernel FAIT au démarrage et de ce que `doctor --env` PRÉDIT. Deux copies
+* qui divergent feraient annoncer un déploiement que l'application ne produit
+* pas — le pire défaut possible pour un outil dont c'est tout le propos.
+*
+* @param raw - l'étiquette telle qu'elle est posée (`NODE_ENV`, `--env`, …).
+* @returns `"development"` ou `"production"` — jamais les formes courtes
+*          `dev`/`prod`, que ce collapse a justement pour rôle de résoudre.
+*/
+function engineModeOf(raw) {
+	return raw === "dev" || raw === "development" ? "development" : "production";
+}
+//#endregion
+export { DEFAULT_ENGINE_ENVIRONMENT, defaultEngineEnvironment, engineModeOf };

package/dist/node/runtime/loadEnv.js

@@ -0,0 +1,105 @@
+import { parseEnv } from "node:util";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/runtime/loadEnv.ts
+/**
+* Charge les fichiers `.env` du projet dans `process.env`, en cascade et SANS
+* jamais écraser une variable déjà présente.
+*
+* **Convention B (Vite / Next.js)** — règle : les fichiers `*.local` (gitignorés,
+* secrets/machine) priment TOUJOURS sur les committés ; à rang égal, le plus
+* spécifique gagne. Nodefony ajoute un 2ᵉ axe : `appEnv` (déploiement) est plus
+* spécifique que `runtimeEnv` (mode). Précédence, du PLUS fort au PLUS faible :
+*
+* ```
+*   process.env              ← shell / orchestrateur k8s (gagne TOUJOURS)
+*   > .env.<appEnv>.local     ┐ gitignorés (*.local)       ┐ si appEnv défini
+*   > .env.<runtimeEnv>.local │                            │ & ≠ runtimeEnv
+*   > .env.local              ┘                            │
+*   > .env.<appEnv>           ┐ committés (non-secrets)    ┘
+*   > .env.<runtimeEnv>       │
+*   > .env                    ┘ défauts communs (le + faible)
+* ```
+*
+* Mécanique : on lit du **plus** prioritaire au **moins** prioritaire et on
+* n'assigne QUE les clés encore absentes de `process.env`. Une variable déjà
+* posée — shell, orchestrateur, ou fichier plus prioritaire déjà traité — n'est
+* jamais réécrite → la précédence ci-dessus en découle naturellement.
+*
+* Parse natif `node:util.parseEnv` (Node ≥ 21) → **zéro dépendance**. Un fichier
+* absent ou illisible est ignoré silencieusement (tout `.env` est optionnel).
+*
+* Appelé une seule fois au démarrage du bin CLI, **AVANT `new CliKernel()`** : les
+* configs de modules lisent `process.env` au boot (ex. `REDIS_*` dans
+* `defineRedisConfig`), l'env doit donc être peuplé en amont.
+*
+* @param opts - {@link ILoadEnvOptions} (runtimeEnv / appEnv / cwd).
+* @returns le nombre de variables effectivement injectées (diagnostic / tests).
+*/
+/**
+* Les fichiers de la cascade, du PLUS prioritaire au MOINS prioritaire.
+*
+* Extrait de {@link loadEnv} pour être la source UNIQUE de cet ordre : la
+* commande `nodefony env` l'affiche, et un ordre affiché qui différerait de
+* l'ordre appliqué serait pire que pas d'affichage du tout — c'est exactement ce
+* qu'un utilisateur croirait sur parole en cherchant pourquoi sa variable est
+* ignorée.
+*
+* @param opts - `runtimeEnv` (mode) et `appEnv` (déploiement).
+* @returns les noms de fichiers, ordonnés ; ne dit pas lesquels existent.
+*/
+function envFileOrder(opts = {}) {
+	const { runtimeEnv, appEnv } = opts;
+	const deployEnv = appEnv && appEnv !== runtimeEnv ? appEnv : void 0;
+	const files = [];
+	if (deployEnv) files.push(`.env.${deployEnv}.local`);
+	if (runtimeEnv) files.push(`.env.${runtimeEnv}.local`);
+	files.push(".env.local");
+	if (deployEnv) files.push(`.env.${deployEnv}`);
+	if (runtimeEnv) files.push(`.env.${runtimeEnv}`);
+	files.push(".env");
+	return files;
+}
+/**
+* L'environnement EFFECTIF d'un projet, sans toucher à `process.env`.
+*
+* Même cascade et même précédence que {@link loadEnv} — dont c'est désormais le
+* moteur —, mais rendue plutôt qu'injectée. Elle sert à tout ce qui doit LIRE
+* l'environnement d'une application sans être cette application : un diagnostic
+* lancé depuis un poste voit ainsi ce que l'app verra, alors que `process.env`
+* nu ne montre que ce que le terminal a posé.
+*
+* 🔴 C'est exactement le trou que `doctor` portait : le dialecte du connecteur
+* était déduit de `process.env` seul, donc une application dont l'URL vit dans
+* `.env.local` — le chemin que le gabarit PRESCRIT — voyait chacune de ses
+* entités accusée d'être écrite pour le mauvais moteur.
+*
+* @param base - l'environnement de départ, qui GAGNE sur les fichiers.
+* @param opts - la cascade à lire (racine, mode runtime, environnement de déploiement).
+* @returns un objet neuf ; ni `base` ni `process.env` ne sont modifiés.
+*/
+function resolveEnvCascade(base, opts = {}) {
+	const { cwd = process.cwd() } = opts;
+	const merged = { ...base };
+	for (const file of envFileOrder(opts)) {
+		let parsed;
+		try {
+			parsed = parseEnv(readFileSync(resolve(cwd, file), "utf8"));
+		} catch {
+			continue;
+		}
+		for (const key in parsed) if (merged[key] === void 0) merged[key] = parsed[key];
+	}
+	return merged;
+}
+function loadEnv(opts = {}) {
+	const resolved = resolveEnvCascade(process.env, opts);
+	let injected = 0;
+	for (const key in resolved) if (process.env[key] === void 0) {
+		process.env[key] = resolved[key];
+		injected++;
+	}
+	return injected;
+}
+//#endregion
+export { envFileOrder, loadEnv, resolveEnvCascade };

package/dist/node/runtime/pageFacets.js

@@ -0,0 +1,85 @@
+//#region src/runtime/pageFacets.ts
+/**
+* Ce qu'un store rend quand il ne PEUT pas compter — convention de tous les
+* backends du dépôt (`countSessions`, `countTokens`, `countEndpoints`).
+*
+* Une valeur sentinelle plutôt qu'une exception : ne pas savoir compter est un
+* état nominal d'un backend en curseur, pas une panne.
+*/
+const UNKNOWN_COUNT = -1;
+/**
+* Compte plusieurs **facettes** d'une même collection en un seul geste.
+*
+* Une facette est une question fermée posée à la collection entière — « combien
+* de sessions authentifiées ? », « combien de clés révoquées ? ». C'est ce que
+* les cartes en tête d'un écran d'administration prétendent afficher, et ce
+* qu'elles calculaient jusqu'ici **sur la page chargée** : avec une fenêtre de
+* 25 lignes, une carte annonçant « 3 comptes actifs » décrit trois lignes
+* visibles, pas l'annuaire. Un nombre présenté sans qualificatif est lu comme un
+* total ; le corriger d'une mention en petits caractères ne le rend pas vrai.
+*
+* L'algorithme vit ici en **un seul exemplaire** ; ce qui varie d'une ressource
+* à l'autre est la **donnée** — la table des facettes — qui se déclare à côté du
+* contrat de la ressource, jamais sous forme de fonction.
+*
+* Aucune facette n'est dérivée d'une autre (`inactive = total - active`) : deux
+* facettes peuvent se recouvrir (un compte peut être à la fois désactivé et
+* verrouillé), et une soustraction rendrait alors un nombre que rien ne compte.
+* Chaque facette est une question posée telle quelle au store.
+*
+* @param facets - nom public → filtre à appliquer. Un filtre vide compte tout.
+* @param count - le compteur du store, appelé une fois par facette. Il rend
+*   {@link UNKNOWN_COUNT} lorsqu'il ne sait pas compter.
+* @returns un compteur par facette, `null` là où le store a répondu « inconnu ».
+*
+* @remarks **Cold path d'administration.** Les facettes partent en parallèle
+*   (une requête `COUNT` chacune) : c'est acceptable pour quatre questions
+*   posées à l'ouverture d'un écran, et ce ne serait pas acceptable dans un
+*   chemin de requête. Ne pas rejouer ces comptages à chaque tour de page — ils
+*   ne dépendent ni de `limit`, ni de `offset`, ni de l'ordre.
+*
+* @example
+* ```ts
+* const SESSION_FACETS = {
+*   total: {},
+*   authenticated: { authenticated: true },
+*   anonymous: { authenticated: false },
+* } as const satisfies IFacetSpec<ISessionListQuery>;
+*
+* const counts = await countFacets(SESSION_FACETS, (q) => storage.countSessions(q));
+* // → { total: 1204, authenticated: 87, anonymous: 1117 }   (Redis : que des null)
+* ```
+*/
+async function countFacets(facets, count) {
+	const names = Object.keys(facets);
+	const values = await Promise.all(names.map(async (name) => {
+		const n = await count(facets[name]);
+		return Number.isFinite(n) && n >= 0 ? n : null;
+	}));
+	const out = {};
+	for (let i = 0; i < names.length; i++) out[names[i]] = values[i];
+	return out;
+}
+/**
+* Les champs qu'une table de facettes **décompose** — donc ceux qu'un client ne
+* peut pas filtrer sur l'endpoint qui les rend.
+*
+* Poser `?status=active` sur un endpoint dont les facettes sont justement les
+* états produirait une réponse qui se contredit : le total suivrait le filtre,
+* et chaque facette l'écraserait par le sien (« 5 clés au total, dont 538
+* révoquées »). Ce n'est pas un cas tordu, c'est le cas NOMINAL — un client
+* envoie naturellement le même query string à la liste et aux compteurs.
+*
+* Sert donc de garde : la spec de filtre d'un endpoint de statistiques ne doit
+* contenir aucune de ces clés, ce qu'un test vérifie par ressource.
+*
+* @param facets - la table déclarée.
+* @returns les noms de champs apparaissant dans au moins une facette, triés.
+*/
+function facetDimensions(facets) {
+	const out = /* @__PURE__ */ new Set();
+	for (const facet of Object.values(facets)) for (const key of Object.keys(facet)) out.add(key);
+	return [...out].sort();
+}
+//#endregion
+export { UNKNOWN_COUNT, countFacets, facetDimensions };

package/dist/node/runtime/pageFilters.js

@@ -0,0 +1,103 @@
+import { PAGE_QUERY_KEYS, PageQueryError, singleValue } from "./pageQuery.js";
+//#region src/runtime/pageFilters.ts
+/** Une définition est-elle répétable ? (discriminant de {@link FilterEach}) */
+const isEach = (def) => typeof def === "object" && !Array.isArray(def);
+/**
+* Valide et convertit UNE valeur brute selon une nature scalaire — le cœur de
+* la lecture, partagé par les filtres simples et par chaque occurrence d'un
+* filtre `{ each }`. Les écrire deux fois les aurait fait diverger : c'est
+* exactement ce qui s'était produit dans les data planes, où la variante
+* multi-valeurs validait moins que la variante simple.
+*
+* @throws {@link PageQueryError} (`code` 400) si la valeur ne correspond pas.
+*/
+function coerce(raw, def, name) {
+	if (Array.isArray(def)) {
+		if (!def.includes(raw)) throw new PageQueryError(`Invalid value "${raw}" for "${name}". Accepted: ${def.join(", ")}.`);
+		return raw;
+	}
+	if (def === "boolean") {
+		if (raw !== "true" && raw !== "false") throw new PageQueryError(`Invalid value "${raw}" for "${name}" (expected true or false).`);
+		return raw === "true";
+	}
+	if (def === "int") {
+		const n = Number.parseInt(raw, 10);
+		if (!Number.isFinite(n) || String(n) !== raw.trim()) throw new PageQueryError(`Invalid value "${raw}" for "${name}" (expected an integer).`);
+		return n;
+	}
+	return raw;
+}
+/**
+* **Le** lecteur de filtres : transforme une source clé→valeur en filtres
+* validés, selon la spec déclarée par la ressource. Fonction **pure**.
+*
+* Il remplace les lectures `one(query, "x")` que chaque data plane recopiait —
+* une vingtaine dans le dépôt, avec autant de coercitions maison. Ce n'est pas
+* la répétition qui coûtait, c'est ce qu'elles faisaient toutes : **accepter
+* puis jeter**. `?revoked=oui` posait le filtre à `undefined`, `?category=zzz`
+* tombait hors de l'énumération, `?enbaled=true` n'existait pour personne — et
+* dans les trois cas la réponse était une page NON filtrée, que le client lit
+* comme le résultat de son filtre. Le tri a cessé de faire ça ; les filtres le
+* faisaient encore.
+*
+* Trois refus, tous en `400` :
+*
+* | Cas                                | Exemple                    |
+* | ---------------------------------- | -------------------------- |
+* | valeur mal formée                  | `?revoked=oui`             |
+* | valeur hors énumération            | `?category=zzz`            |
+* | paramètre reconnu par personne     | `?enbaled=true`            |
+*
+* Le troisième est le plus important et le moins évident : sans lui, une faute
+* de frappe dans une URL d'administration rend silencieusement la collection
+* ENTIÈRE. Les clés du contrat de page ({@link PAGE_QUERY_KEYS}) sont bien sûr
+* admises — c'est le même URL qui porte les deux.
+*
+* @param source - la query string parsée, ou le corps d'une requête `QUERY`.
+* @param spec - ce que ce point d'entrée sait filtrer.
+* @param options - paramètres que l'appelant lit lui-même (voir
+*   {@link IParseFiltersOptions.accepts}).
+* @returns les filtres présents et valides (les absents ne sont pas posés).
+* @throws {@link PageQueryError} (`code` 400) sur l'un des trois cas ci-dessus.
+*
+* @example
+* ```ts
+* const TOKEN_FILTERS = {
+*   subjectId: "string",
+*   revoked: "boolean",
+*   kind: ["pat", "refresh"],
+* } as const satisfies IFilterSpec;
+*
+* const page = parsePageQuery(request.query, { sortable });
+* const filters = parseFilters(request.query, TOKEN_FILTERS);
+* return store.listPage({ ...page, ...filters });
+* ```
+*/
+function parseFilters(source, spec, options = {}) {
+	const out = {};
+	const accepts = options.accepts;
+	for (const key of Object.keys(source)) {
+		if (PAGE_QUERY_KEYS.has(key)) continue;
+		if (accepts?.includes(key)) continue;
+		if (!Object.hasOwn(spec, key)) {
+			const known = Object.keys(spec);
+			throw new PageQueryError(known.length ? `Unknown parameter "${key}". Filterable fields: ${known.join(", ")}.` : `Unknown parameter "${key}"; this endpoint has no filters.`);
+		}
+	}
+	for (const [name, def] of Object.entries(spec)) {
+		if (isEach(def)) {
+			const raw = source[name];
+			if (raw === void 0) continue;
+			const values = (Array.isArray(raw) ? raw : [raw]).filter((v) => v !== "");
+			if (values.length === 0) continue;
+			out[name] = values.map((v) => coerce(v, def.each, name));
+			continue;
+		}
+		const raw = singleValue(source, name);
+		if (raw === void 0 || raw === "") continue;
+		out[name] = coerce(raw, def, name);
+	}
+	return out;
+}
+//#endregion
+export { parseFilters };

package/dist/node/runtime/pageGuard.js

@@ -0,0 +1,84 @@
+import nodefonyError from "../Error.js";
+//#region src/runtime/pageGuard.ts
+/**
+* Erreur levée quand un `listPage` reçoit le champ de pagination du mode que son
+* store **ne sait pas honorer** — un `cursor` pour un store offset, ou un `offset`
+* de navigation pour un store curseur.
+*
+* `code = 400` : c'est une erreur du **client** (mauvais paramètre), jamais une
+* panne serveur. Avant ce garde-fou, le champ hors-mode était **avalé en silence**
+* (un client curseur bouclait indéfiniment sur la page 1 d'un store offset, cf
+* l'écart F27/F51 du registre doc↔code). Le data plane admin (`AdminApiController`)
+* traduit ce `code` en statut HTTP 400 au lieu du 500 générique.
+*/
+var PaginationModeError = class extends nodefonyError {
+	/**
+	* @param received - le mode dont un champ a été fourni (celui de trop).
+	* @param supported - le mode réellement supporté par le store.
+	*/
+	constructor(received, supported) {
+		super(`Pagination mode mismatch: this store paginates by "${supported}", but a "${received}" parameter was supplied. Pass "${supported}" only (offset and cursor are mutually exclusive per the IPage contract).`, 400);
+	}
+};
+/**
+* Erreur levée quand un store paginant par **curseur** reçoit un
+* {@link IPageQuery.order} : il ne peut pas l'honorer, et l'avaler mentirait.
+*
+* Ce n'est pas une limite d'implémentation, c'est la nature du curseur : le
+* jeton encode une **position dans un ordre total**, celui-là même que le store
+* applique. Le rendre paramétrable rendrait tout jeton déjà émis ininterprétable
+* — la page suivante sauterait ou répéterait des lignes, silencieusement, ce qui
+* est le pire défaut possible sur un journal d'audit.
+*
+* `code = 400` : c'est le client qui demande une capacité que ce point d'entrée
+* n'a pas. Un backend curseur qui saurait trier devrait d'abord embarquer
+* l'ordre DANS son curseur ; il déclarerait alors `sortableFields` et cette
+* garde serait à revoir avec lui — pas avant.
+*/
+var CursorOrderError = class extends nodefonyError {
+	/** @param fields - les champs de tri demandés, dans l'ordre reçu. */
+	constructor(fields) {
+		super(`Sorting is not supported by a cursor-paginated store (requested: ${fields.join(", ")}). The cursor encodes a position in the store's own total order; changing that order would invalidate every token already issued. Drop "order", or use an offset-paginated backend.`, 400);
+	}
+};
+/**
+* Fait respecter le contrat « un store expose UN seul mode » au point d'entrée
+* d'un `listPage`, sur la requête **brute** reçue de l'appelant (avant qu'elle ne
+* soit normalisée) : rejette explicitement le champ du mode non supporté plutôt
+* que de l'ignorer sans un mot.
+*
+* Chaque store connaît son mode **statiquement** (constante de l'implémentation) et
+* appelle ce garde-fou en première ligne. À placer côté store — jamais dans un
+* helper de pagination en aval (`paginate()`), qui reçoit une requête déjà
+* reconstruite d'où le champ hors-mode a pu disparaître, laissant la violation
+* passer inaperçue.
+*
+* **Valeurs neutres tolérées** (pas une navigation) : un `cursor` **vide** côté
+* offset et un `offset` **0** côté curseur désignent tous deux « le début » — ils
+* ne trahissent aucune intention du mauvais mode et ne sont donc pas rejetés. Seule
+* une vraie navigation du mode adverse (`cursor` non vide, `offset > 0`) lève.
+*
+* **Le mode curseur refuse aussi le TRI** ({@link CursorOrderError}) : son ordre
+* est imposé par le jeton, pas choisi par l'appelant. Le data plane le refuse
+* déjà en amont (aucun endpoint curseur ne déclare `sortable`), mais un appelant
+* interne — un autre service, un test, un futur endpoint — fabrique son
+* `IPageQuery` à la main ; sans cette ligne, son `order` était ignoré sans un
+* mot par les six stores curseur du dépôt.
+*
+* @param query - la requête de page brute reçue par le store.
+* @param mode - le mode que le store sait honorer.
+* @throws {@link PaginationModeError} (`code` 400) si le champ du mode adverse est
+*   présent avec une valeur de navigation.
+* @throws {@link CursorOrderError} (`code` 400) si un `order` non vide est fourni
+*   à un store curseur.
+*/
+function assertPageQuery(query, mode) {
+	if (mode === "offset") {
+		if (typeof query.cursor === "string" && query.cursor !== "") throw new PaginationModeError("cursor", "offset");
+		return;
+	}
+	if (typeof query.offset === "number" && query.offset > 0) throw new PaginationModeError("offset", "cursor");
+	if (query.order && query.order.length > 0) throw new CursorOrderError(query.order.map(([field]) => field));
+}
+//#endregion
+export { CursorOrderError, PaginationModeError, assertPageQuery };