@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/service/certificates.d.ts

@@ -0,0 +1,246 @@
+import type pkg from "node-forge";
+import { Service, Module } from "nodefony";
+/**
+ * Type-valeur du backend node-forge runtime (objet `.pki`/`.md`). L'import type
+ * `pkg` sert pour les namespaces de types (`pkg.pki.Certificate`) ; `ForgeModule`
+ * pour la valeur chargée dynamiquement (node-forge est un module `export =`).
+ */
+type ForgeModule = typeof import("node-forge");
+/** Algorithmes de hachage de signature autorisés (SHA-1 banni). */
+export type CertHash = "sha256" | "sha384" | "sha512";
+/** Stratégie de fourniture du certificat exposée en configuration. */
+export type CertStrategyConfig = "auto" | "mkcert" | "selfsigned" | "explicit";
+export interface OpensslOptions {
+    /** Taille de la clé RSA (bits). */
+    size: number;
+    /** Algorithme de hachage de la signature (jamais SHA-1). */
+    hash: CertHash;
+    /** Durée de validité du certificat (jours). */
+    validityDays: number;
+    /** Recul de `notBefore` (minutes) — tolérance au décalage d'horloge client. */
+    backdateMinutes: number;
+    /** Attributs du sujet/issuer (commonName, organizationName…). */
+    attrs: pkg.pki.CertificateField[];
+}
+/** Options de génération du certificat TLS en mode développement. */
+export interface CertificateDevOptions {
+    /**
+     * Préférer `mkcert` (CA locale ajoutée au trust store système) pour générer
+     * le certificat de dev. Donne un HTTPS sans erreur navigateur — indispensable
+     * pour les sous-ressources cross-origin (Vite) et le WSS du HMR.
+     * Si `mkcert` est absent, on retombe sur un auto-signé node-forge (non trusté).
+     * Ignoré hors `development`.
+     */
+    useMkcert: boolean;
+}
+/** Subject Alternative Name explicite (sinon dérivé du kernel). */
+export interface CertificateSanOptions {
+    /** Noms DNS (RFC 5280 §4.2.1.6) — font foi pour la vérification d'hôte. */
+    dns: string[];
+    /** Adresses IP. */
+    ip: string[];
+}
+export interface CertificateOptions {
+    /**
+     * Comment fournir le certificat. `auto` (défaut) résout mkcert (dev) →
+     * auto-signé ; `explicit` charge `key`/`cert` fournis (prod). La génération
+     * est un confort de DÉVELOPPEMENT — en production, fournir un vrai certificat
+     * (Let's Encrypt, ingress, reverse-proxy) : Nodefony n'est pas une CA.
+     */
+    strategy?: CertStrategyConfig;
+    openssl: OpensslOptions;
+    dev: CertificateDevOptions;
+    san?: CertificateSanOptions;
+    /** Permissions POSIX de la clé privée écrite (0600 = owner-only). */
+    privateKeyMode?: number;
+    path?: string;
+    keyPath?: string;
+    certPath?: string;
+    caPath?: string;
+    key?: string | Buffer;
+    cert?: string | Buffer;
+    ca?: string | Buffer;
+}
+interface filesCertType {
+    path: string;
+    variable: string | Buffer | null;
+}
+/** Résumé introspectable du certificat serveur (CLI + futur endpoint Studio). */
+export interface CertificateInfo {
+    /** Stratégie effective ayant fourni le certificat. */
+    strategy: CertStrategyConfig;
+    certPath: string;
+    keyPath: string;
+    fullchainPath: string;
+    /** Ancre de confiance à passer au client (`--cacert`/`ca`) — si présente. */
+    caPath?: string;
+    /** Renseignés si un certificat est présent (parsé). */
+    commonName?: string;
+    san?: string[];
+    validFrom?: string;
+    validTo?: string;
+    signatureAlgorithm?: string;
+    serial?: string;
+}
+/**
+ * Service de fourniture du certificat TLS du serveur HTTPS/WSS.
+ *
+ * Trois stratégies : `explicit` (certificat fourni en config — le cas de
+ * PRODUCTION), `mkcert` (CA locale trustée, confort de dev) et `selfsigned`
+ * (auto-signé node-forge, secours). La génération est réservée au
+ * DÉVELOPPEMENT : en production sans certificat fourni, le service crie un
+ * avertissement (Nodefony n'est pas une autorité de certification).
+ *
+ * Conformité (génération auto-signée) : signature SHA-256 (jamais SHA-1,
+ * RFC 5280 / CA-B Forum), numéro de série aléatoire 128 bits unique
+ * (RFC 5280 §4.1.2.2), SAN qui fait foi (RFC 6125), `notBefore` reculé,
+ * clé privée écrite en `0600`.
+ */
+declare class Certificate extends Service {
+    module: Module;
+    files: filesCertType[];
+    keysPair: pkg.pki.rsa.KeyPair | null;
+    certForge: pkg.pki.Certificate | null;
+    ca: Buffer | string | null;
+    key: Buffer | string | null;
+    cert: Buffer | string | null;
+    fullchainPem: Buffer | string | null;
+    publicKeyPem: Buffer | string | null;
+    rootCertPem: Buffer | string | null;
+    intermediateCertPem: Buffer | string | null;
+    /** CAROOT résolu de mkcert (null tant que non détecté / indisponible). */
+    private mkcertCaRoot;
+    /**
+     * Backend crypto node-forge, chargé PARESSEUSEMENT. La génération de
+     * certificat est un confort de DÉVELOPPEMENT : en production avec un
+     * certificat fourni (`strategy: "explicit"`), cette grosse dépendance n'est
+     * jamais importée (règle perf-mémoire — pas de dep chargée « au cas où »).
+     */
+    private forge;
+    path: string;
+    serverPath: string;
+    caPath: string;
+    publicKeyPath: string;
+    privateKeyPath: string;
+    certPath: string;
+    fullchainPath: string;
+    constructor(module: Module);
+    /** Accès typé aux options du service (Service.options est volontairement lâche). */
+    private get certOptions();
+    /** Vrai en environnement de développement (mkcert réservé à ce mode). */
+    private isDev;
+    /**
+     * Charge node-forge à la demande (idempotent) — uniquement sur le chemin de
+     * GÉNÉRATION (selfsigned / mkcert / inspection). Le chemin `explicit` (prod)
+     * ne l'appelle jamais.
+     */
+    loadForge(): Promise<ForgeModule>;
+    /** Accès au backend forge déjà chargé (lève si `loadForge` n'a pas été appelé). */
+    private get forgeLib();
+    init(): Promise<this>;
+    /**
+     * Numéro de série X.509 — RFC 5280 §4.1.2.2 : entier positif unique par CA.
+     * 128 bits aléatoires (≥ 64 bits d'entropie exigés par le CA/Browser Forum
+     * contre les attaques par collision) ; bit de poids fort à 0 pour garantir un
+     * entier positif en encodage DER ; ≤ 20 octets.
+     */
+    private static generateSerialHex;
+    setFiles(): void;
+    private checkCertificates;
+    private ensureDirectoriesExist;
+    /**
+     * Génère (ou recharge) le certificat serveur selon la stratégie résolue :
+     * `explicit` (fourni en config / prod), `mkcert` (dev, CA trustée) ou
+     * `selfsigned` (auto-signé node-forge, secours). Régénère automatiquement si
+     * le certificat présent sur disque n'est pas adéquat pour la stratégie active
+     * (expiré, SHA-1, SAN incomplet).
+     *
+     * @param force - forcer la régénération même si un certificat valide existe
+     */
+    generateServerCertificates(force?: boolean): Promise<this>;
+    /**
+     * Résout la stratégie effective à partir de `certificates.strategy` :
+     * - `explicit` : `key` + `cert` fournis (prod, Let's Encrypt…). Forcé →
+     *   erreur si absents.
+     * - `mkcert` : dev + binaire mkcert + CA locale présents. Forcé hors dev →
+     *   retombe sur `selfsigned` avec avertissement.
+     * - `selfsigned` : auto-signé node-forge (fallback). En PRODUCTION, crie un
+     *   avertissement : la génération n'est pas le rôle d'un serveur de prod.
+     */
+    private resolveStrategy;
+    /** `key` + `cert` présents en config (chemin fichier ou Buffer) → cert fourni. */
+    private hasExplicitCert;
+    /**
+     * Détecte mkcert : binaire dans le PATH + CA racine générée (rootCA.pem).
+     * @returns le chemin CAROOT, ou null si indisponible.
+     */
+    private detectMkcert;
+    /**
+     * SAN effectif : config explicite si fournie, sinon dérivé du kernel
+     * (localhost + domain en DNS ; loopback en IP). Une IP littérale (ex. domain
+     * `127.0.0.1` en dev) est classée en `ip`, pas en `dns` (RFC 6125).
+     */
+    private derivedSan;
+    /** Hostnames DNS couverts par le SAN. */
+    private sanDnsNames;
+    /** Adresses IP couvertes par le SAN. */
+    private sanIps;
+    /** Hostnames passés à mkcert (DNS + IP du SAN). */
+    private certHostnames;
+    /**
+     * Génère le certificat de dev via mkcert (signé par la CA locale trustée).
+     * Écrit cert + clé privée (mkcert), puis dérive clé publique, fullchain et CA.
+     */
+    private generateWithMkcert;
+    /**
+     * Vérifie que le certificat présent sur disque convient à la stratégie :
+     * - expiration (RFC 5280 §4.1.2.5) : un cert expiré est inadéquat.
+     * - **SAN** couvrant les hostnames requis (les DEUX stratégies) : si le SAN
+     *   demandé change (ex. `nodefony.com` ajouté via NF_BIND_ALL), on régénère.
+     * - `mkcert` : émis par la CA mkcert (issuer organisation contient "mkcert").
+     * - `selfsigned` : signature non SHA-1.
+     * @returns false si absent, illisible ou inadéquat → déclenche la régénération.
+     */
+    private isCertAdequate;
+    /** Le SAN présent couvre-t-il tous les noms DNS requis (RFC 6125) ? */
+    private sanCovers;
+    /** Charge un certificat fourni en config (chemin fichier ou Buffer). */
+    private loadExplicitCert;
+    /** Résout un matériel TLS : Buffer renvoyé tel quel, string lue comme chemin. */
+    private resolveMaterial;
+    createFullChain(): string;
+    readCerticates(): Promise<this>;
+    writeCertificates(force?: boolean): Promise<this>;
+    /**
+     * Durcit les permissions de la clé privée (et de son dossier) après écriture
+     * — garantit `0600` même si l'umask du process était permissif (la clé écrite
+     * par mkcert passe aussi par ici). Échec silencieux hors POSIX.
+     */
+    private restrictPrivateKey;
+    generateKeys(): pkg.pki.rsa.KeyPair;
+    generatePrivateKeyPem(): Buffer;
+    generatePublickeyPem(): Buffer;
+    generateCertPem(): Buffer;
+    createCertificate(): pkg.pki.Certificate;
+    /** subjectAltName de l'auto-signé : DNS + IP (config explicite sinon dérivé). */
+    private altNames;
+    setExtension(): void;
+    /**
+     * Signe le certificat avec le hachage configuré (SHA-256 par défaut).
+     * SHA-1 est INTERDIT (collision SHAttered 2017, CA/Browser Forum depuis 2016) :
+     * `node-forge` signe en SHA-1 par défaut si on ne passe pas de digest → on en
+     * passe toujours un.
+     */
+    sign(): void;
+    /**
+     * Résumé introspectable du certificat serveur courant — réutilisé par la
+     * commande CLI `certificates` et un futur endpoint d'admin Studio (parité
+     * CLI ↔ Web). Parse le certificat chargé (charge node-forge à la demande).
+     */
+    describe(): Promise<CertificateInfo>;
+    /** Nom lisible de l'OID d'algorithme de signature. */
+    private oidName;
+    /** Digest node-forge correspondant au hachage configuré (jamais SHA-1). */
+    private digestFor;
+}
+export default Certificate;

package/dist/types/nodefony/service/error-renderer.d.ts

@@ -0,0 +1,74 @@
+import type { IErrorRenderer, IErrorHttpResult, IErrorWebsocketResult } from "../interfaces/IErrorRenderer.js";
+import type { IHttpContext, IWebsocketContext } from "../interfaces/IContext.js";
+/**
+ * Force du signal « la base ne porte pas ce que le code demande ».
+ *
+ * Deux niveaux, parce que les pilotes ne disent pas la chose avec la même
+ * autorité — et parce que leurs lecteurs n'ont pas le même coût d'erreur.
+ *
+ * - `certain` : un code dédié le dit (PostgreSQL, MySQL). Rien d'autre ne
+ *   produit ce code.
+ * - `probable` : SQLite, dont le code est générique, mais dont le message
+ *   porte une signature figée (cf {@link SQLITE_SCHEMA_PREFIXES}).
+ */
+export type SchemaMismatchConfidence = "certain" | "probable";
+/**
+ * Reconnaît, dans une erreur ou l'une de ses causes, un schéma en retard sur
+ * le code — et dit avec quelle FORCE.
+ *
+ * Détecteur UNIQUE de ce fait dans tout le framework : le corps d'erreur rendu
+ * au développeur le lit, et le rechargement d'un instantané au démarrage
+ * aussi. Deux reconnaissances de la même chose divergeraient en silence, et
+ * chacune passerait ses propres tests.
+ *
+ * Chaque lecteur choisit son SEUIL, et c'est là que la graduation sert. Le
+ * corps d'erreur n'accepte que `certain` : il nomme des tables à un client, et
+ * une aide qui se trompe de cause coûte plus cher que pas d'aide du tout. Un
+ * appelant qui sait déjà ce qu'il a demandé — une table précise, au démarrage —
+ * peut accepter `probable` : il ne publie rien, il décide seulement de ne pas
+ * hurler.
+ *
+ * Même descente dans `cause` que {@link isUniqueViolation}, et pour la même
+ * raison : Drizzle enveloppe toute erreur de pilote dans un `DrizzleQueryError`
+ * dont le `code` vaut `undefined`. Sans elle, la reconnaissance ne mord jamais.
+ *
+ * Ne coûte rien au chemin nominal : ne tourne que sur une erreur déjà levée.
+ *
+ * @param error - erreur remontée par un pilote, éventuellement enveloppée.
+ * @returns la force du signal, ou `null` si rien ne dit ça.
+ */
+export declare function schemaMismatchOf(error: unknown): SchemaMismatchConfidence | null;
+/**
+ * Default Nodefony error renderer — preserves the legacy JSON error shape.
+ *
+ * HTTP body (unchanged across the migration):
+ *   {
+ *     code:    <http status>,
+ *     message: <error message>,
+ *     error:   <HttpError.toJSON() — stack, controller, action, jsonResponse...>,
+ *     nodefony: { requestId, scheme, name, version, environment, debug, ... },
+ *     result:  null,
+ *   }
+ *
+ * WS close frame:
+ *   code:   clamped to WS range (1000-4999), 1011 if HTTP-style code, 500→1011
+ *   reason: error.message
+ *
+ * Stateless singleton — zero per-request allocation. Override via
+ * `httpKernel.setErrorRenderer(custom)` for prod hardening or RFC 7807.
+ */
+declare class DefaultErrorRenderer implements IErrorRenderer {
+    renderHttp(error: Error, context: IHttpContext): IErrorHttpResult;
+    renderWebsocket(error: Error, context: IWebsocketContext): IErrorWebsocketResult;
+    private toHttpError;
+    /**
+     * Ramène un `code` d'erreur à un statut HTTP réellement émettable.
+     *
+     * Le filtre de type n'est pas défensif « au cas où » : `nodefonyError.parseMessage`
+     * RECOPIE le code de l'erreur source, et pilotes comme Node en produisent des
+     * textuels (`"ENOENT"`, `"ECONNRESET"`, `"23505"`). Sans lui, la chaîne partait
+     * telle quelle en statut de réponse et le serveur répondait hors RFC 9110 §15.
+     */
+    private normalizeHttpStatus;
+}
+export default DefaultErrorRenderer;