---
title: "Référence d'API — nodefony — runtime"
source: docs/api/core/runtime.md
url: https://nodefony.github.io/nodefony-core/docs/api/core/runtime/
---


[Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › runtime

> Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `nodefony`

`import { … } from "nodefony"` — 112 symboles.

### Classes (8)

#### `CursorOrderError`

```ts
class CursorOrderError extends nodefonyError
```

Erreur levée quand un store paginant par **curseur** reçoit un `IPageQuery.order` : il ne peut pas l'honorer, et l'avaler mentirait.

- `constructor(fields: readonly string[])`

#### `GcScheduler`

```ts
class GcScheduler
```

Timer de maintenance déterministe, jittéré et désarmable. Voir la doc du module pour le rationnel complet.

- `constructor(opts: IGcSchedulerOptions)`
- `get armed(): boolean` — `true` si l'ordonnanceur est armé (délai initial en cours OU timer récurrent).
- `start(): boolean` — Arme l'ordonnanceur.
- `runNow(): Promise<void>` — Exécute une passe **immédiatement** — point d'entrée public (le timer l'appelle ; un worker cron / une commande batch peut l'appeler à sa place).
- `stop(): void` — Désarme les timers (idempotent) — à appeler au shutdown.

#### `PageQueryError`

```ts
class PageQueryError extends nodefonyError
```

Erreur d'une requête de page mal formée ou non honorable par le point d'entrée : `order` sur un endpoint qui ne trie pas, champ hors allowlist, sens de tri inconnu.

- `constructor(message: string)`

#### `PaginationModeError`

```ts
class PaginationModeError extends nodefonyError
```

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.

- `constructor(received: PaginationMode, supported: PaginationMode)`

#### `RequestContext`

```ts
class RequestContext
```

AsyncLocalStorage facade — single shared instance per process. Lazily constructed so importing this module has zero cost if `run()` is never called (the ALS allocation is the only cost).

- `static run<T>(payload: RequestContextPayload, fn: () => T): T` — Enter a new request scope.
- `static get(): RequestContextPayload` — Returns the current payload, or `undefined` outside any request scope.
- `static getRequestId(): string` — Shortcut — returns the current requestId or `undefined`.
- `static getUser(): unknown` — Rend l'utilisateur posé par le pare-feu, BRUT — y compris l'utilisateur anonyme d'une zone qui accepte l'anonymat.
- `static getAuthenticatedUser(): IRequestUser | null` — Rend l'utilisateur AUTHENTIFIÉ de la requête, ou `null` : hors zone du pare-feu, ou anonyme (jeton non authentifié).
- `static isAnonymous(): boolean` — Dit si la requête est servie à un ANONYME par le pare-feu : jeton non authentifié d'une zone qui accepte l'anonymat.
- `static getContext<T = unknown>(): T` — Shortcut — returns the current transport context (V4.1) or `undefined`.
- `static getUserId(): string | null` — Rend l'`id` de l'utilisateur AUTHENTIFIÉ de l'unité de travail, ou `null`.
- `static getScope(): IScope` — Rend le scope DI de la requête en cours : le conteneur propre à CETTE requête, ou `undefined` s'il n'y en a pas d'ouvert.
- `static requireScope(): IScope` — Comme `getScope`, mais lève quand aucun scope ouvert n'est disponible — pour le code qui n'a pas de sens hors d'une requête.
- `static release(store: RequestContextPayload): void` — Vide un magasin dont l'unité de travail est finie : requête HTTP, connexion WebSocket, appel `api.request`, action temps réel décorée.
- `static set<K extends keyof RequestContextPayload>(key: K, value: RequestContextPayload[K]): void` — Mutate the current payload in place.
- `static isProfiling(): boolean` — `true` si un buffer de profiling de requêtes ORM est actif sur le scope courant (dev + `HttpKernel` profiler activé).
- `static pushQuery(query: IProfilerQuery): void` — Pousse une requête ORM dans le buffer de profiling du scope courant.

#### `RevocationWatch`

```ts
class RevocationWatch<T>
```

Registre des connexions longues à identité révocable, re-validées périodiquement — la SEULE implémentation, partagée par le hub WebSocket et les flux SSE : une garde que l'un des transports n'aurait pas serait le chemin qu'un attaquant prendrait.

- `constructor(policy: IRevocationPolicy<T>)`
- `get size(): number` — Nombre d'entrées inscrites.
- `register(entry: T): void` — Inscrit une entrée ; démarre le tick à la première.
- `unregister(entry: T): void` — Retire une entrée (idempotent) ; arrête le tick quand le registre se vide.
- `revalidate(): Promise<void>` — Re-valide toutes les entrées et ferme celles dont l'identité est morte.
- `refreshIdentity(identifier: string): number` — Ferme, tout de suite, les entrées qui ont figé cette identité — ses droits ont changé (`IDENTITY_CHANGED_EVENT`).

#### `SchemaValidationError`

```ts
class SchemaValidationError extends Error
```

Erreur levée quand une entrée ne satisfait pas son schéma — l'unique erreur de validation des routes à schéma.

- `readonly code = 422` — Statut HTTP équivalent.
- `readonly issues: readonly ISchemaValidationIssue[]` — Les anomalies, toutes parties confondues.
- `constructor(issues: readonly ISchemaValidationIssue[])`

#### `TimeoutError`

```ts
class TimeoutError extends Error
```

Erreur levée par `withTimeout` quand le délai est dépassé — distincte d'un rejet métier pour que l'appelant puisse différencier « lent/figé » de « a échoué » (ex. politique de boot : timeout d'un module critique en prod).

- `readonly timeoutMs: number` — Délai (ms) qui a été dépassé.
- `constructor(timeoutMs: number, label?: string)`

### Fonctions (31)

#### `assertPageQuery`

```ts
function assertPageQuery(query: IPageQuery, mode: PaginationMode): void
```

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.

#### `bearerToken`

```ts
function bearerToken(header: unknown): string | null
```

Rend le jeton porté par un en-tête `Authorization`, ou `null`.

#### `compareByOrder`

```ts
function compareByOrder<T>(order: NonNullable<IPageQuery["order"]>, read: FieldReader<T>): (a: T, b: T) => number
```

Fabrique le comparateur d'un `order` du contrat de page — **le** tri en mémoire de Nodefony, partagé par tous les stores qui n'ont pas de moteur pour le faire à leur place.

#### `countFacets`

```ts
function countFacets<S extends Readonly<Record<string, object>>>(facets: S, count: (query: S[keyof S]) => number | Promise<number>): Promise<FacetCounts<S>>
```

Compte plusieurs **facettes** d'une même collection en un seul geste.

#### `facetDimensions`

```ts
function facetDimensions(facets: Readonly<Record<string, object>>): string[]
```

Les champs qu'une table de facettes **décompose** — donc ceux qu'un client ne peut pas filtrer sur l'endpoint qui les rend.

#### `findLegacyEnvFiles`

```ts
function findLegacyEnvFiles(opts?: ILoadEnvOptions): string[]
```

Les fichiers de l'ANCIENNE convention (Vite / Next.js) présents dans une application : `.env.local`, `.env.<mode>`, `.env.<mode>.local`.

#### `frameIndexOf`

```ts
function frameIndexOf(id: string, connection: string): number | null
```

Le rang de la frame si `id` en est une de `connection`, sinon `null` — un identifiant qui ne fait que COMMENCER comme la connexion n'en est pas une.

#### `frameRequestId`

```ts
function frameRequestId(connection: string, n: number): string
```

L'identifiant de la `n`-ième frame d'une connexion.

#### `identityHint`

```ts
function identityHint(kernel: IKernel | null): string | null
```

Le geste qui donne une IDENTITÉ dans cette application — ou `null`.

#### `isDocVisible`

```ts
function isDocVisible(scope: DocScope | null, frameworkRepository: boolean): boolean
```

Une page de cette portée se montre-t-elle dans ce décor ?

#### `isFrameworkRepository`

```ts
function isFrameworkRepository(projectRoot: string): boolean
```

Cette racine est-elle le dépôt du framework lui-même ?

#### `isLoginPageSkin`

```ts
function isLoginPageSkin(value: unknown): value is LoginPageSkin
```

Dit si une valeur nomme un habillage connu.

#### `isStandardSchema`

```ts
function isStandardSchema(value: unknown): value is IStandardSchemaV1
```

Indique si une valeur implémente Standard Schema v1. Sert aux contrôles de démarrage : un appelant JavaScript peut passer n'importe quoi.

#### `legacyEnvMessage`

```ts
function legacyEnvMessage(files: readonly string[]): string
```

Le message qui accompagne le refus de `findLegacyEnvFiles` : ce qu'il faut faire de chaque fichier, sans avoir à ouvrir la documentation.

#### `loadEnv`

```ts
function loadEnv(opts?: ILoadEnvOptions): number
```

Charge `.env` dans `process.env`, SANS jamais écraser une variable déjà présente : le shell et l'orchestrateur gagnent toujours.

#### `loginPagePath`

```ts
function loginPagePath(from?: string, page?: string): string
```

Adresse de la page de connexion qui ramène à `from` une fois connecté — le lien « Se connecter » d'une page applicative.

#### `loginPageSkinFile`

```ts
function loginPageSkinFile(skin: LoginPageSkin): string | null
```

Fichier de la feuille d'un habillage, relatif à `LOGIN_PAGE_ASSETS_BASE`.

#### `oauth2AuthorizePath`

```ts
function oauth2AuthorizePath(provider: string, from?: string, back?: string): string
```

Adresse qui démarre la connexion par un fournisseur : à ouvrir en navigation PLEINE PAGE, jamais par `fetch` — le navigateur doit suivre les redirections vers le fournisseur et revenir avec le cookie de session posé au retour.

#### `parseFilters`

```ts
function parseFilters<const S extends IFilterSpec>(source: PageQuerySource, spec: S, options?: IParseFiltersOptions): FilterValues<S>
```

**Le** lecteur de filtres : transforme une source clé→valeur en filtres validés, selon la spec déclarée par la ressource. Fonction **pure**.

#### `parsePageQuery`

```ts
function parsePageQuery(source: PageQuerySource, options?: IParsePageQueryOptions): IPageQuery
```

**Le** traducteur d'une requête de page : transforme une source clé→valeur en `IPageQuery` borné et validé. Fonction **pure** — aucun accès au kernel, à l'ALS ni à la requête HTTP.

#### `pickOrder`

```ts
function pickOrder(order: IPageQuery["order"], allowed: readonly string[], fallback: NonNullable<IPageQuery["order"]>): NonNullable<IPageQuery["order"]>
```

Retient d'un `order` demandé les seuls couples dont le champ est **déclaré triable**, et retombe sur l'ordre par défaut s'il n'en reste aucun.

#### `readBearerHeader`

```ts
function readBearerHeader(header: unknown): BearerHeader
```

Lit un en-tête `Authorization` et dit ce qu'il porte.

#### `readDocScope`

```ts
function readDocScope(publish: unknown): DocScope | null
```

Lit la clé de frontmatter `publish` d'une page de documentation.

#### `readSessionAuthentication`

```ts
function readSessionAuthentication(session: IMetaBagReader | null): ISessionAuthentication | null
```

Lit quand et comment une session a été ouverte.

#### `redactSecrets`

```ts
function redactSecrets(line: string): string
```

Renvoie `line` avec les secrets connus masqués par `***`.

#### `redactUrlCredentials`

```ts
function redactUrlCredentials(text: string): string
```

Masque le mot de passe de toute URL contenue dans `text` (`user:***@hôte`).

#### `renameOrderFields`

```ts
function renameOrderFields(order: NonNullable<IPageQuery["order"]>, aliases: Readonly<Record<string, string>>): NonNullable<IPageQuery["order"]>
```

Réécrit les noms de champs d'un `order` selon une table d'alias — le pont entre le vocabulaire **public** (celui de l'URL) et le schéma d'un backend.

#### `safeRedirectPath`

```ts
function safeRedirectPath(value: unknown, fallback?: string): string
```

Rend `value` si c'est un chemin LOCAL sûr, sinon `fallback`.

#### `standardJsonSchemaOf`

```ts
function standardJsonSchemaOf(schema: IStandardSchemaV1): IStandardJsonSchemaConverter | null
```

Le convertisseur JSON Schema d'un schéma, s'il en expose un.

#### `toSchemaValidationIssues`

```ts
function toSchemaValidationIssues(issues: ReadonlyArray<IStandardSchemaIssue>, part?: string): ISchemaValidationIssue[]
```

Normalise les anomalies d'un schéma : segments objet `{ key }` dépliés, clés converties en texte (un `Symbol` ferait lever `Array.join`), partie de l'entrée rattachée.

#### `withTimeout`

```ts
function withTimeout<T>(promise: PromiseLike<T>, timeoutMs: number, label?: string): Promise<T>
```

Résout avec la valeur de `promise` si elle se règle avant `timeoutMs`, sinon rejette avec une `TimeoutError`.

### Constantes (32)

#### `AUTH_API_BASE`

```ts
const AUTH_API_BASE = "/nodefony/security/api/auth"
```

Base des routes de session : connexion, second facteur, déconnexion, identité.

#### `AUTH_LOGIN_PATH`

```ts
const AUTH_LOGIN_PATH = "/nodefony/security/api/auth/login"
```

Route de connexion par session : `POST` avec `{username, password}`.

#### `AUTH_LOGIN_TOTP_PATH`

```ts
const AUTH_LOGIN_TOTP_PATH = "/nodefony/security/api/auth/login/totp"
```

Second facteur après un `202 mfaRequired` : `POST` avec `{code}` (TOTP ou code de récupération).

#### `AUTH_LOGOUT_PATH`

```ts
const AUTH_LOGOUT_PATH = "/nodefony/security/api/auth/logout"
```

Déconnexion : `POST`, idempotente ; rend `logoutUrl` quand la session venait d'un fournisseur.

#### `AUTH_ME_PATH`

```ts
const AUTH_ME_PATH = "/nodefony/security/api/auth/me"
```

Identité de la session courante : `GET`, toujours `200` — `{ user }`, ou `{ user: null }` sans session.

#### `DEFAULT_LOGIN_PAGE_SKIN`

```ts
const DEFAULT_LOGIN_PAGE_SKIN: LoginPageSkin
```

Habillage servi quand la configuration n'en choisit aucun.

#### `ENV_FILE`

```ts
const ENV_FILE = ".env"
```

Le SEUL fichier d'environnement que Nodefony charge : les valeurs du POSTE (secrets de développement compris), jamais commité.

#### `IDENTITY_CHANGED_EVENT`

```ts
const IDENTITY_CHANGED_EVENT = "onIdentityChanged"
```

Événement kernel — les droits d'une identité ont changé (ses rôles, par exemple), sans qu'elle soit morte. Une connexion longue a FIGÉ cette identité à l'ouverture : elle doit se fermer pour que le client se reconnecte avec l'identité à jour. Re-lire la base à chaque tick pour le détecter coûterait une lecture par connexion ; l'événement ne coûte rien tant que rien ne change. Charge utile : `IIdentityChangedEvent`.

#### `INSECURE_TRANSPORT_MESSAGE`

```ts
const INSECURE_TRANSPORT_MESSAGE = "Credentials must be sent over HTTPS"
```

Refus d'un secret de connexion reçu en clair (HTTP) en production — corps `error` d'une réponse 403 des routes de connexion.

#### `LOGIN_PAGE_ASSETS_BASE`

```ts
const LOGIN_PAGE_ASSETS_BASE = "/nodefony/security/login"
```

Base des fichiers de la page de connexion par défaut (script, feuille de style). Distincte de la page elle-même, dont le chemin se règle (`loginPage.path`) : ces fichiers ne changent pas d'adresse quand la page en change.

#### `LOGIN_PAGE_LAYOUTS`

```ts
const LOGIN_PAGE_LAYOUTS: readonly [ "card", "split", "bare" ]
```

Modes de mise en page de la page de connexion par défaut.

#### `LOGIN_PAGE_PATH`

```ts
const LOGIN_PAGE_PATH = "/login"
```

Chemin par défaut de la page de connexion servie par le framework.

#### `LOGIN_PAGE_SCRIPT_PATH`

```ts
const LOGIN_PAGE_SCRIPT_PATH = "/nodefony/security/login/login.js"
```

Script de la page de connexion par défaut (bundle `nodefony/login.js`).

#### `LOGIN_PAGE_SKINS`

```ts
const LOGIN_PAGE_SKINS: readonly [ "frontispiece", "ledger", "horizon", "console", "blueprint", "dots", "minimal", "enterprise", "photo-card" ]
```

Habillages de la page de connexion par défaut (`loginPage.skin`).

#### `LOGIN_PAGE_SKIN_SPECS`

```ts
const LOGIN_PAGE_SKIN_SPECS: Readonly<Record<LoginPageSkin, ILoginPageSkinSpec>>
```

Mise en page et fond de chaque habillage — le `Record` exige les neuf.

#### `LOGIN_PAGE_STYLE_PATH`

```ts
const LOGIN_PAGE_STYLE_PATH = "/nodefony/security/login/login.css"
```

Feuille de style de la page de connexion par défaut.

#### `LOGIN_PAGE_THEME_KEY`

```ts
const LOGIN_PAGE_THEME_KEY = "nf-login-theme"
```

Clé du stockage local où la page de connexion par défaut retient le thème choisi (`light` ou `dark`). Le gabarit la lit avant le premier rendu, le script de la page l'écrit à la bascule.

#### `MFA_METHOD_TOTP`

```ts
const MFA_METHOD_TOTP = "totp"
```

Méthode de second facteur « code à usage unique » : un code TOTP, ou un code de récupération, présenté à `AUTH_LOGIN_TOTP_PATH`.

#### `OAUTH2_API_BASE`

```ts
const OAUTH2_API_BASE = "/nodefony/security/api/oauth2"
```

Base de la connexion par un fournisseur externe (OAuth 2.0 / OpenID Connect).

#### `OAUTH2_CANCELLED_REASON`

```ts
const OAUTH2_CANCELLED_REASON = "access_denied"
```

Code OAuth 2.0 d'une annulation par l'utilisateur (RFC 6749 §4.1.2.1).

#### `OAUTH2_FAILED_REASON`

```ts
const OAUTH2_FAILED_REASON = "failed"
```

Valeur de `reason` que le callback OAuth pose sur l'écran d'échec quand la cause n'est pas un code normalisé du fournisseur (`state` invalide, échange du code refusé, compte non provisionné). Seule `access_denied` dit une ANNULATION ; toute autre valeur est un échec à annoncer.

#### `OAUTH2_PROVIDERS_PATH`

```ts
const OAUTH2_PROVIDERS_PATH = "/nodefony/security/api/oauth2/providers"
```

Fournisseurs de connexion configurés : `GET` → `{ providers: {name, label}[] }`.

#### `PAGE_QUERY_KEYS`

```ts
const PAGE_QUERY_KEYS: ReadonlySet<string>
```

Les clés que le contrat de page revendique sur le fil — **source unique**.

#### `REVOCATION_REVALIDATE_MS`

```ts
const REVOCATION_REVALIDATE_MS = 30000
```

Période de re-validation des connexions à identité RÉVOCABLE, en ms.

#### `SESSION_AMR_KEY`

```ts
const SESSION_AMR_KEY = "amr"
```

Clé de métadonnée : méthodes d'authentification utilisées (RFC 8176).

#### `SESSION_AUTH_AT_KEY`

```ts
const SESSION_AUTH_AT_KEY = "authAt"
```

Clé de métadonnée : heure de l'authentification (millisecondes epoch).

#### `UNKNOWN_COUNT`

```ts
const UNKNOWN_COUNT = -1
```

Ce qu'un store rend quand il ne PEUT pas compter — convention de tous les backends du dépôt (`countSessions`, `countTokens`, `countEndpoints`).

#### `WEBAUTHN_API_BASE`

```ts
const WEBAUTHN_API_BASE = "/nodefony/security/api/webauthn"
```

Base des cérémonies WebAuthn (passkeys).

#### `WEBAUTHN_LOGIN_OPTIONS_PATH`

```ts
const WEBAUTHN_LOGIN_OPTIONS_PATH = "/nodefony/security/api/webauthn/login/options"
```

Défi de connexion par passkey : `POST` (corps vide) → options WebAuthn en JSON.

#### `WEBAUTHN_LOGIN_VERIFY_PATH`

```ts
const WEBAUTHN_LOGIN_VERIFY_PATH = "/nodefony/security/api/webauthn/login/verify"
```

Vérification de la passkey : `POST` avec `{response}` → ouvre la session.

#### `WEBAUTHN_STATUS_PATH`

```ts
const WEBAUTHN_STATUS_PATH = "/nodefony/security/api/webauthn/status"
```

État de la connexion par passkey : `GET` → `{ enabled: boolean }`, toujours `200` quand le service existe. Les cérémonies répondent `503` quand les passkeys sont coupées ; cette route permet à un écran de connexion de ne pas proposer un bouton voué à cet échec.

#### `isPlainObject`

```ts
const isPlainObject: (obj: unknown) => obj is Record<string, unknown>
```

Vérifie qu'un objet est un "plain object" — `{}` ou `Object.create(null)`.

### Interfaces (23)

#### `IGcSchedulerOptions`

```ts
interface IGcSchedulerOptions
```

Options de construction d'un `GcScheduler`.

- `intervalS: number` — Intervalle entre deux passes, en **secondes**.
- `run: () => unknown` — La passe de maintenance (typiquement `() => store.gc()`).
- `jitter?: boolean` — Étale le **départ** d'un délai aléatoire borné (anti *thundering herd* en cluster).
- `onError?: (error: unknown) => void` — Reçoit l'erreur d'une passe qui a levé (sinon l'échec est silencieux).
- `initialDelayMs?: number` — Délai fixe avant la **première** passe (ms, défaut `30_000`) — laisse finir le boot avant de scanner.
- `jitterCapMs?: number` — Plafond du jitter (ms, défaut `60_000`) — borne le retard de la 1ʳᵉ passe.

#### `IIdentityChangedEvent`

```ts
interface IIdentityChangedEvent
```

Charge utile de `IDENTITY_CHANGED_EVENT`.

- `readonly identifier: string` — Identifiant de connexion de l'identité dont les droits ont changé.

#### `ILoadEnvOptions`

```ts
interface ILoadEnvOptions
```

Options de `loadEnv` — où lire, et quels noms de l'ancienne convention signaler.

- `runtimeEnv?: string` — Mode RUNTIME (`"development"` | `"production"`) = NODE_ENV.
- `appEnv?: string` — Environnement de DÉPLOIEMENT (string libre : `staging` / `canary`…) = APP_ENV / NF_ENV.
- `cwd?: string` — Racine du projet où chercher les fichiers (défaut `process.cwd()`).

#### `ILoginPageDescription`

```ts
interface ILoginPageDescription
```

Ce que la page de connexion par défaut doit afficher, décrit par la sécurité et lu par le contrôleur qui la sert.

- `readonly path: string` — Chemin où la page est servie (`loginPage.path`).
- `readonly title: string | null` — Titre de la page, ou `null` pour le titre par défaut.
- `readonly logo: string | null` — Adresse du logo, ou `null` pour celui de Nodefony.
- `readonly template: string | null` — Gabarit `.eta` de l'application qui remplace celui du framework, ou `null`.
- `readonly heading: string | null` — Titre de la carte et de l'onglet, ou `null` pour « Se connecter ».
- `readonly subtitle: string | null` — Ligne sous le titre, ou `null` pour la phrase déduite des moyens proposés.
- `readonly stylesheet: string | null` — Feuille de l'application chargée APRÈS celle du framework, ou `null`.
- `readonly providersFirst: boolean` — Les fournisseurs passent-ils avant le formulaire (quand il y en a) ?
- `readonly hero: ILoginPageHero | false | null` — Panneau d'illustration : `null` = vitrine Nodefony, `false` = marque seule, sinon le contenu qui la remplace.
- `readonly footer: boolean` — Pied de page : protections de la session et mention du framework.
- `readonly skin: LoginPageSkin` — Habillage : feuille chargée entre celle du framework et celle de l'application.
- `readonly layout: LoginPageLayout` — Mode de mise en page (`loginPage.layout`, sinon celui de l'habillage).
- `readonly password: boolean` — Le formulaire identifiant et mot de passe est-il proposé ?
- `readonly passkey: boolean` — La connexion par passkey est-elle proposée ?
- `readonly previewPicker: boolean` — Sélecteur d'aperçu demandé (`loginPage.previewPicker`) ; la page ne l'affiche qu'en développement.
- `readonly previewHook?: string | null` — Chemin de l'application appelé en `POST` (`{ skin, layout }`) avant chaque rechargement de l'aperçu (`loginPage.previewHook`), ou `null`/absent.
- `readonly providers: readonly ILoginPageProvider[]` — Fournisseurs à proposer, dans l'ordre de la configuration.

#### `ILoginPageHero`

```ts
interface ILoginPageHero
```

Contenu du panneau d'illustration qui REMPLACE la vitrine Nodefony. Texte seul, échappé au rendu : l'image du panneau passe par la feuille de l'application (`--nf-login-hero-image`), jamais par une adresse injectée dans le balisage.

- `readonly heading: string` — Accroche du panneau.
- `readonly text: string | null` — Phrase sous l'accroche, ou `null`.

#### `ILoginPageProvider`

```ts
interface ILoginPageProvider
```

Fournisseur d'identité proposé sur la page de connexion.

- `readonly name: string` — Nom du fournisseur, tel qu'il figure dans l'adresse d'autorisation.
- `readonly label: string` — Libellé affiché sur le bouton.
- `readonly icon: string | null` — Image du bouton (chemin servi par l'application ou URL), ou `null` pour l'icône du framework (marque GitHub, sinon une clé).

#### `ILoginPageSkinSpec`

```ts
interface ILoginPageSkinSpec
```

Ce qu'un habillage impose au gabarit, au-delà de sa feuille.

- `readonly layout: LoginPageLayout` — Mise en page pour laquelle l'habillage est dessiné, sauf `layout` explicite.
- `readonly backdrop: boolean` — Fond de page décoré (motif, image) : le pied passe alors sur une pastille pleine pour rester lisible (`<body data-backdrop>`).

#### `IParseFiltersOptions`

```ts
interface IParseFiltersOptions
```

Réglages de lecture d'un point d'entrée qui porte plus que des filtres.

- `accepts?: readonly string[]` — Paramètres que ce point d'entrée lit **lui-même**, hors filtres — une projection (`?include=author`), un format de sortie, une clé propre au transport.

#### `IParsePageQueryOptions`

```ts
interface IParsePageQueryOptions
```

Réglages d'un point d'entrée paginé : ses bornes et ce qu'il accepte de trier.

- `defaultLimit?: number` — Taille de page quand le client n'en demande pas.
- `maxLimit?: number` — Cap dur : une demande supérieure est **ramenée** à ce plafond (jamais refusée — un client qui demande trop ne mérite pas une erreur, il mérite une page).
- `sortable?: readonly string[]` — Champs sur lesquels ce point d'entrée sait trier — l'**allowlist** qui rend `order` exploitable.
- `searchable?: boolean` — Ce point d'entrée sait-il **chercher** (`?q=`) — c'est-à-dire relayer `q` jusqu'à un store qui l'honore.

#### `IProfilerQuery`

```ts
interface IProfilerQuery
```

Une requête ORM (SQL/NoSQL) capturée pendant le scope de requête, pour le profiler dev-only. Shape canonique partagée par tous les adapters ORM et le Profiler `@nodefony/http` (structurellement identique à `ProfileQuery`).

- `sql: string` — Requête (SQL ou commande NoSQL), tronquée si volumineuse.
- `startMs?: number` — Début relatif (`performance.now()`, ms) — même horloge que `PhaseTiming.startMs` du Context, donc la requête se PLACE dans le waterfall des phases (le SQL apparaît DANS la barre `action`), au lieu de …
- `durationMs: number` — Durée d'exécution en ms.
- `rows?: number` — Lignes affectées/retournées, si connu.
- `connector?: string` — Connecteur émetteur (`drizzle`, `mongoose`…).

#### `IRequestUser`

```ts
interface IRequestUser
```

L'utilisateur AUTHENTIFIÉ d'une requête, tel que le lit un contrôleur (`this.user`). Contrat minimal du cœur, que l'`IUser` de `@nodefony/user` satisfait : le framework le type sans dépendre du paquet des comptes.

- `readonly id: string` — Identifiant interne (UUID).
- `readonly identifier: string` — Identifiant de connexion (login, e-mail).
- `readonly roles: readonly string[]` — Rôles accordés, sans hiérarchie résolue.

#### `IRevocationPolicy`

```ts
interface IRevocationPolicy<T>
```

Ce que le registre sait faire d'une entrée — fourni par son propriétaire.

- `isValid(entry: T): Promise<boolean> | boolean` — L'identité de l'entrée est-elle toujours valable ?
- `revoke(entry: T): void` — Ferme la connexion de l'entrée — appelée une fois, l'entrée déjà retirée.
- `identityOf?(entry: T): string` — Identifiant de connexion de l'identité figée par l'entrée — `undefined` si elle n'en porte pas.
- `refresh?(entry: T): void` — Ferme l'entrée pour que son client se RECONNECTE avec une identité à jour — à distinguer de `revoke`, qui signifie « identité morte ».
- `periodMs?: number` — Période du tick, en ms.

#### `ISchemaValidationIssue`

```ts
interface ISchemaValidationIssue
```

Une anomalie de validation, normalisée : chemin en clés textuelles, et partie de l'entrée qui l'a portée.

- `readonly message: string` — Message lisible.
- `readonly path: readonly string[]` — Chemin de la valeur fautive DANS sa partie (`["author", "email"]`).
- `readonly in?: string` — La partie de l'entrée : `body`, `query`, `params`, `headers`…

#### `ISessionAuthentication`

```ts
interface ISessionAuthentication
```

Comment une session a été authentifiée.

- `readonly at: number` — Heure de l'authentification, en millisecondes epoch.
- `readonly amr: readonly string[]` — Méthodes utilisées (RFC 8176) ; vide quand un fournisseur a authentifié.

#### `IStandardJsonSchemaConverter`

```ts
interface IStandardJsonSchemaConverter
```

Convertisseur JSON Schema optionnel (Standard JSON Schema v1), exposé par certaines bibliothèques sous `~standard.jsonSchema` (Zod 4 le fait). Sert à DÉCRIRE un schéma — console d'administration, documentation —, jamais à valider.

- `readonly input: (options: { readonly target: string; }) => Record<string, unknown>` — JSON Schema du type d'entrée ; peut lever si la conversion est impossible.

#### `IStandardSchemaFailure`

```ts
interface IStandardSchemaFailure
```

Résultat d'une validation en échec.

- `readonly issues: ReadonlyArray<IStandardSchemaIssue>` — Les anomalies relevées.

#### `IStandardSchemaIssue`

```ts
interface IStandardSchemaIssue
```

Une anomalie rendue par un schéma en échec.

- `readonly message: string` — Message lisible de l'anomalie.
- `readonly path?: ReadonlyArray<PropertyKey | IStandardSchemaPathSegment>` — Chemin de la valeur fautive, s'il y en a un.

#### `IStandardSchemaPathSegment`

```ts
interface IStandardSchemaPathSegment
```

Un segment de chemin d'anomalie, sous sa forme objet.

- `readonly key: PropertyKey` — La clé du segment.

#### `IStandardSchemaProps`

```ts
interface IStandardSchemaProps<Input = unknown, Output = Input>
```

Les propriétés `~standard` d'un schéma.

- `readonly version: 1` — Version de la spécification.
- `readonly vendor: string` — Bibliothèque qui implémente le schéma (`zod`, `valibot`…).
- `readonly validate: (value: unknown, options?: { readonly libraryOptions?: Record<string, unknown>; }) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>` — Valide une valeur inconnue ; synchrone, sauf si le schéma est asynchrone.
- `readonly types?: IStandardSchemaTypes<Input, Output>` — Types inférés, pour la compilation.

#### `IStandardSchemaSuccess`

```ts
interface IStandardSchemaSuccess<Output>
```

Résultat d'une validation réussie.

- `readonly value: Output` — La valeur validée, éventuellement transformée par le schéma.
- `readonly issues?: undefined` — Absent en cas de succès.

#### `IStandardSchemaTypes`

```ts
interface IStandardSchemaTypes<Input = unknown, Output = Input>
```

Types portés par un schéma (présents à la compilation seulement).

- `readonly input: Input` — Le type accepté en entrée.
- `readonly output: Output` — Le type rendu après validation.

#### `IStandardSchemaV1`

```ts
interface IStandardSchemaV1<Input = unknown, Output = Input>
```

Un schéma conforme à Standard Schema v1 — Zod 4, Valibot, ArkType…

- `readonly "~standard": IStandardSchemaProps<Input, Output>` — Les propriétés de la spécification.

#### `RequestContextPayload`

```ts
interface RequestContextPayload
```

- `requestId: string`
- `scheme?: string`
- `user?: unknown` — Set by the security firewall after `afterAuth` (P6).
- `traceparent?: string` — W3C traceparent header for OpenTelemetry compatibility (P2.7).
- `queries?: IProfilerQuery[]` — Buffer de requêtes ORM du profiler — **présent uniquement en dev** quand le `HttpKernel` l'alloue (profiler actif).
- `context?: unknown` — Contexte transport courant (`HttpContext` / `WebsocketContext`), posé par `HttpKernel` à l'entrée du scope (V4.1).
- `scope?: IScope` — Scope DI de la requête — le même objet que `context.container`.
- `body?: unknown` — Corps de la requête posé par le **pont WS-RPC `api.request`** (mutations) : en WebSocket il n'existe aucun corps HTTP parsé, donc le pont transporte la charge utile de la frame ici (per-invocation via …
- `idempotencyKey?: string` — Clé d'idempotence (modèle Stripe) portée par une **mutation** du data plane admin : posée par le pont WS (`params.idempotencyKey`) ou lue de l'en-tête HTTP `Idempotency-Key`.
- `renderSink?: { body?: string | Buffer; status?: number; }` — Puits de CAPTURE du rendu, posé par le **pont WS-RPC `api.request`** : une action user peut répondre par un RENDU (`renderJson`/`renderView`) au lieu d'une valeur nue.
- `invocation?: unknown` — Profil de l'**invocation** en cours (`FrameProfile` de `@nodefony/http`), posé par le pont WS-RPC.
- `resolver?: unknown` — Résolution de l'**appel** en cours quand elle n'est pas celle du contexte : le pont WS-RPC `api.request` crée un résolveur PAR APPEL, sans le ranger sur `context.resolver` — qui reste celui de la conn …
- `token?: unknown` — Jeton d'authentification posé par le pare-feu après `afterAuth` (rôles, périmètres, attributs).

### Types (18)

#### `BearerHeader`

```ts
type BearerHeader = { kind: "absent"; } | { kind: "empty"; } | { kind: "other"; } | { kind: "token"; token: string; }
```

Ce que porte un en-tête `Authorization` — et surtout ce qu'il NE porte pas.

#### `DocScope`

```ts
type DocScope = "user" | "core" | "none"
```

À qui une page de documentation s'adresse : `user` (qui se sert de Nodefony), `core` (qui développe le framework, dans son dépôt), `none` (personne — elle reste dans git, nulle part ailleurs).

#### `FacetCount`

```ts
type FacetCount = number | null
```

Valeur d'un compteur tel qu'il traverse HTTP : un nombre, ou `null` quand le backend branché ne sait pas répondre.

#### `FacetCounts`

```ts
type FacetCounts<S> = { [K in keyof S]: FacetCount; }
```

Les compteurs rendus, une clé par facette déclarée.

#### `FieldReader`

```ts
type FieldReader<T> = (item: T, field: string) => unknown
```

Lit la valeur d'un champ triable sur un élément. Chaque store fournit la sienne : le nom du champ est **public** (celui de l'URL), la façon de l'atteindre est interne.

#### `FilterDef`

```ts
type FilterDef = FilterKind | readonly string[] | FilterEach
```

Définition d'UN filtre : sa nature, la **liste fermée** de ses valeurs, ou l'une des deux répétée (`FilterEach`).

#### `FilterKind`

```ts
type FilterKind = "string" | "boolean" | "int" | "uuid" | "objectId"
```

Nature d'un filtre — ce qui suffit à le lire depuis une source clé→valeur.

#### `FilterValue`

```ts
type FilterValue<D extends FilterDef> = D extends { each: infer E; } ? ScalarFilterValue<E>[] : ScalarFilterValue<D>
```

Le type JavaScript qu'une définition de filtre produit une fois lue — un **tableau** pour un filtre `{ each }`, la valeur seule sinon.

#### `FilterValues`

```ts
type FilterValues<S extends IFilterSpec> = { -readonly [K in keyof S]?: FilterValue<S[K]>; }
```

Les filtres lus, **typés depuis la spec** : une énumération rend son union de littéraux, `boolean` rend un booléen, `int` un nombre.

#### `IFacetSpec`

```ts
type IFacetSpec<Q> = Readonly<Record<string, Partial<Q>>>
```

Déclaration des facettes d'une ressource : nom public → filtre de sa requête de liste.

#### `IFilterSpec`

```ts
type IFilterSpec = Readonly<Record<string, FilterDef>>
```

Ce qu'un point d'entrée sait filtrer : nom public → définition.

#### `InferSchemaInput`

```ts
type InferSchemaInput<S extends IStandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"]
```

Le type qu'accepte un schéma.

#### `InferSchemaOutput`

```ts
type InferSchemaOutput<S extends IStandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"]
```

Le type que rend un schéma validé.

#### `LoginPageLayout`

```ts
type LoginPageLayout = (typeof LOGIN_PAGE_LAYOUTS)[number]
```

Un mode de mise en page de la page de connexion (`loginPage.layout`).

#### `LoginPageSkin`

```ts
type LoginPageSkin = (typeof LOGIN_PAGE_SKINS)[number]
```

Un habillage de la page de connexion (`loginPage.skin`).

#### `PageQuerySource`

```ts
type PageQuerySource = Readonly<Record<string, unknown>>
```

Source d'où extraire une requête de page, **agnostique de sa provenance** : une query string déjà parsée (`?limit=20&offset=40`), le corps JSON d'une requête `QUERY` (RFC 10008), ou tout autre porteur clé→valeur.

#### `PaginationMode`

```ts
type PaginationMode = "offset" | "cursor"
```

Les deux modes de pagination du contrat `IPageQuery`, **mutuellement exclusifs** : un backend n'expose que l'un (`IPageQuery.offset` navigation directe, ou `IPageQuery.cursor` navigation « après ce jeton »). Cf le TSDoc d'`IPageQuery` : « un backend n'expose qu'un mode ; le store le déclare ».

#### `StandardSchemaResult`

```ts
type StandardSchemaResult<Output> = IStandardSchemaSuccess<Output> | IStandardSchemaFailure
```

Résultat de `~standard.validate`.

---

[← Toutes les références d'API](../../)