@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/config/config.d.ts

@@ -0,0 +1,295 @@
+import { z } from "zod";
+declare const areaSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    security: z.ZodDefault<z.ZodBoolean>;
+    stateless: z.ZodDefault<z.ZodBoolean>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        first: "first";
+    }>>;
+    authenticators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    entryPoint: z.ZodOptional<z.ZodString>;
+    host: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    realtime: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const securityConfigSchema: z.ZodObject<{
+    encoders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<{
+            argon2id: "argon2id";
+            bcrypt: "bcrypt";
+        }>>;
+        memoryKiB: z.ZodDefault<z.ZodNumber>;
+        timeCost: z.ZodDefault<z.ZodNumber>;
+        parallelism: z.ZodDefault<z.ZodNumber>;
+        rounds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    roleHierarchy: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    areas: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        pattern: z.ZodString;
+        security: z.ZodDefault<z.ZodBoolean>;
+        stateless: z.ZodDefault<z.ZodBoolean>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            first: "first";
+        }>>;
+        authenticators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        entryPoint: z.ZodOptional<z.ZodString>;
+        host: z.ZodOptional<z.ZodString>;
+        resource: z.ZodOptional<z.ZodString>;
+        realtime: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    realtimeChannels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        pattern: z.ZodString;
+        authenticated: z.ZodOptional<z.ZodBoolean>;
+        roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    cors: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        credentials: z.ZodDefault<z.ZodBoolean>;
+        methods: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowedHeaders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        exposedHeaders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxAgeS: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    csrf: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        fetchMetadata: z.ZodDefault<z.ZodBoolean>;
+        sameSite: z.ZodDefault<z.ZodEnum<{
+            Lax: "Lax";
+            None: "None";
+            Strict: "Strict";
+        }>>;
+        checkOrigin: z.ZodDefault<z.ZodBoolean>;
+        strictSameSite: z.ZodDefault<z.ZodBoolean>;
+        trustedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    headers: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        hsts: z.ZodDefault<z.ZodBoolean>;
+        hstsMaxAgeS: z.ZodDefault<z.ZodNumber>;
+        csp: z.ZodDefault<z.ZodString>;
+        cspNonces: z.ZodDefault<z.ZodBoolean>;
+        frameguard: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            sameorigin: "sameorigin";
+        }>>;
+        noSniff: z.ZodDefault<z.ZodBoolean>;
+        referrerPolicy: z.ZodDefault<z.ZodEnum<{
+            "no-referrer": "no-referrer";
+            "no-referrer-when-downgrade": "no-referrer-when-downgrade";
+            origin: "origin";
+            "origin-when-cross-origin": "origin-when-cross-origin";
+            "same-origin": "same-origin";
+            "strict-origin": "strict-origin";
+            "strict-origin-when-cross-origin": "strict-origin-when-cross-origin";
+            "unsafe-url": "unsafe-url";
+        }>>;
+        hidePoweredBy: z.ZodDefault<z.ZodBoolean>;
+        coop: z.ZodOptional<z.ZodEnum<{
+            "same-origin": "same-origin";
+            "same-origin-allow-popups": "same-origin-allow-popups";
+            "unsafe-none": "unsafe-none";
+        }>>;
+        coep: z.ZodOptional<z.ZodEnum<{
+            credentialless: "credentialless";
+            "require-corp": "require-corp";
+            "unsafe-none": "unsafe-none";
+        }>>;
+        corp: z.ZodOptional<z.ZodEnum<{
+            "cross-origin": "cross-origin";
+            "same-origin": "same-origin";
+            "same-site": "same-site";
+        }>>;
+        originAgentCluster: z.ZodOptional<z.ZodBoolean>;
+        permissionsPolicy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    rateLimit: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        freeAttempts: z.ZodDefault<z.ZodNumber>;
+        baseDelayS: z.ZodDefault<z.ZodNumber>;
+        capDelayS: z.ZodDefault<z.ZodNumber>;
+        maxTracked: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    jwt: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        alg: z.ZodDefault<z.ZodEnum<{
+            EdDSA: "EdDSA";
+            RS256: "RS256";
+        }>>;
+        accessTtlS: z.ZodDefault<z.ZodNumber>;
+        refreshTtlS: z.ZodDefault<z.ZodNumber>;
+        rotateRefresh: z.ZodDefault<z.ZodBoolean>;
+        jwks: z.ZodDefault<z.ZodBoolean>;
+        audiences: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        issuer: z.ZodOptional<z.ZodString>;
+        keystore: z.ZodDefault<z.ZodObject<{
+            keySetJson: z.ZodOptional<z.ZodString>;
+            dir: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    tokenStore: z.ZodDefault<z.ZodObject<{
+        store: z.ZodDefault<z.ZodString>;
+        gcIntervalS: z.ZodDefault<z.ZodNumber>;
+        gcJitter: z.ZodDefault<z.ZodBoolean>;
+        retentionRevokedDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    passkeys: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        rpId: z.ZodOptional<z.ZodString>;
+        rpName: z.ZodOptional<z.ZodString>;
+        origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        userVerification: z.ZodDefault<z.ZodEnum<{
+            discouraged: "discouraged";
+            preferred: "preferred";
+            required: "required";
+        }>>;
+        residentKey: z.ZodDefault<z.ZodEnum<{
+            discouraged: "discouraged";
+            preferred: "preferred";
+            required: "required";
+        }>>;
+        authenticatorAttachment: z.ZodDefault<z.ZodEnum<{
+            any: "any";
+            "cross-platform": "cross-platform";
+            platform: "platform";
+        }>>;
+        attestation: z.ZodDefault<z.ZodEnum<{
+            direct: "direct";
+            enterprise: "enterprise";
+            none: "none";
+        }>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxPerUser: z.ZodDefault<z.ZodNumber>;
+        challengeTtlS: z.ZodDefault<z.ZodNumber>;
+        store: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    totp: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        issuer: z.ZodOptional<z.ZodString>;
+        algorithm: z.ZodDefault<z.ZodEnum<{
+            SHA1: "SHA1";
+            SHA256: "SHA256";
+            SHA512: "SHA512";
+        }>>;
+        digits: z.ZodDefault<z.ZodNumber>;
+        period: z.ZodDefault<z.ZodNumber>;
+        window: z.ZodDefault<z.ZodNumber>;
+        recoveryCodes: z.ZodDefault<z.ZodNumber>;
+        encryptionKey: z.ZodOptional<z.ZodString>;
+        store: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    resourceServer: z.ZodDefault<z.ZodObject<{
+        issuers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            issuer: z.ZodString;
+            jwksUri: z.ZodOptional<z.ZodString>;
+            algorithms: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                ES256: "ES256";
+                ES384: "ES384";
+                ES512: "ES512";
+                Ed25519: "Ed25519";
+                EdDSA: "EdDSA";
+                PS256: "PS256";
+                PS384: "PS384";
+                PS512: "PS512";
+                RS256: "RS256";
+                RS384: "RS384";
+                RS512: "RS512";
+            }>>>;
+            typ: z.ZodOptional<z.ZodString>;
+            requiredClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            subjectMapping: z.ZodDefault<z.ZodEnum<{
+                prefixed: "prefixed";
+                subject: "subject";
+            }>>;
+        }, z.core.$strict>>>;
+        subjectPolicy: z.ZodDefault<z.ZodEnum<{
+            ephemeral: "ephemeral";
+            require: "require";
+        }>>;
+        ephemeralRoles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        cooldownMs: z.ZodDefault<z.ZodNumber>;
+        cacheMaxAgeMs: z.ZodDefault<z.ZodNumber>;
+        clockToleranceS: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    tokenExchange: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    oauth2: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        defaultRoles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowSignup: z.ZodDefault<z.ZodBoolean>;
+        successRedirect: z.ZodDefault<z.ZodString>;
+        failureRedirect: z.ZodDefault<z.ZodString>;
+        providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            clientId: z.ZodString;
+            clientSecret: z.ZodString;
+            redirectUri: z.ZodString;
+            issuer: z.ZodOptional<z.ZodString>;
+            scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            successRedirect: z.ZodOptional<z.ZodString>;
+            failureRedirect: z.ZodOptional<z.ZodString>;
+            defaultRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    apiKeys: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        prefix: z.ZodDefault<z.ZodString>;
+        defaultExpiryDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        lastUsedThrottleS: z.ZodDefault<z.ZodNumber>;
+        maxPerSubject: z.ZodDefault<z.ZodNumber>;
+        allowedScopes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+    webhooks: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        signAlg: z.ZodDefault<z.ZodEnum<{
+            sha256: "sha256";
+        }>>;
+        timestampToleranceS: z.ZodDefault<z.ZodNumber>;
+        denyPrivateIps: z.ZodDefault<z.ZodBoolean>;
+        snapshotTtlS: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        autoDisableThreshold: z.ZodDefault<z.ZodNumber>;
+        deliveryTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxConcurrent: z.ZodDefault<z.ZodNumber>;
+        maxQueue: z.ZodDefault<z.ZodNumber>;
+        allowHttp: z.ZodDefault<z.ZodBoolean>;
+        store: z.ZodDefault<z.ZodString>;
+        encryptionKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    audit: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        store: z.ZodDefault<z.ZodString>;
+        immutable: z.ZodDefault<z.ZodBoolean>;
+        stream: z.ZodDefault<z.ZodBoolean>;
+        retentionDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    studio: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        exposure: z.ZodDefault<z.ZodEnum<{
+            localhost: "localhost";
+            private: "private";
+            public: "public";
+        }>>;
+        allowedIps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        requireMfa: z.ZodDefault<z.ZodBoolean>;
+        auditAllActions: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Entrée du builder (champs avec défaut optionnels). */
+export type ISecurityConfigInput = z.input<typeof securityConfigSchema>;
+/** Config normalisée et gelée (sortie du builder, lue par le firewall). */
+export type ISecurityConfig = z.output<typeof securityConfigSchema>;
+/** Config d'une zone normalisée. */
+export type ISecurityAreaConfig = z.output<typeof areaSchema>;
+/**
+ * Défauts du module, matérialisés depuis le schéma (source unique — tous les
+ * `.default()` : Zero Trust, CORS strict, Studio OFF). Toujours valides par
+ * construction ; passés au `super(..., config)` du Module class.
+ */
+declare const config: ISecurityConfig;
+export default config;

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -0,0 +1,27 @@
+import type { ISecurityConfig, ISecurityConfigInput } from "./config.js";
+/**
+ * Builder type-safe de la configuration de sécurité Nodefony (PUR — ne retape
+ * JAMAIS un défaut : source unique = `./config.ts`, le schéma Zod commenté).
+ *
+ * ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+ * pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+ * la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+ * env + freeze) et publie le JSON Schema Studio.
+ *
+ * Valide + normalise + gèle ; conflits de patterns de zones détectés au boot.
+ */
+export type { ISecurityConfig, ISecurityConfigInput, ISecurityAreaConfig, } from "./config.js";
+/**
+ * Valide + normalise + gèle la configuration de sécurité.
+ *
+ * @param config - configuration brute de l'app (sections omises = défauts sûrs).
+ * @returns config gelée prête pour le firewall.
+ * @throws ZodError si invalide ; Error si deux zones partagent un pattern.
+ */
+export declare function defineSecurityConfig(config?: ISecurityConfigInput): ISecurityConfig;
+/**
+ * JSON Schema introspectable de la config sécurité — **Studio génère son
+ * formulaire d'édition depuis ça** (labels/types/défauts/descriptions),
+ * sans UI hardcodée. Surface du data plane `/nodefony/security/api/config/schema`.
+ */
+export declare function securityConfigJsonSchema(): unknown;

package/dist/types/nodefony/contracts/IAccessVoter.d.ts

@@ -0,0 +1,23 @@
+import type { IToken } from "./IToken.js";
+/**
+ * Vote d'un {@link IAccessVoter}. Stratégie firewall = affirmative + DENY veto :
+ * un seul DENY bloque ; sinon un GRANT suffit ; tous ABSTAIN → DENY (Zero Trust).
+ */
+export declare enum VoterVote {
+    GRANT = "GRANT",
+    DENY = "DENY",
+    ABSTAIN = "ABSTAIN"
+}
+/**
+ * Voter contextuel (niveau C de l'autorisation, P6.8) — décide d'un accès en
+ * fonction du token ET du sujet (ex. « cet user édite-t-il SON projet ? »).
+ *
+ * Découverts par DI au boot (`@injectable`), indexés par `supports()`. Killer
+ * feature pour le métier complexe (multi-tenant, ownership).
+ */
+export interface IAccessVoter {
+    /** Ce voter sait-il décider de cet attribut/sujet ? */
+    supports(attribute: string, subject?: unknown): boolean;
+    /** Vote pour l'attribut donné sur le sujet donné. */
+    vote(token: IToken, attribute: string, subject?: unknown): Promise<VoterVote>;
+}

package/dist/types/nodefony/contracts/IApiKey.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Vue **publique** d'une clé API (PAT) — projection de `IAccessTokenRecord`
+ * **sans le secret ni son hash** (jamais exposés après création). C'est la forme
+ * renvoyée par la console (« mes clés ») et le data plane Studio.
+ */
+export interface IApiKeyView {
+    /** Identifiant public de la clé (révocation, affichage). */
+    id: string;
+    /** Préfixe public affichable (`<prefix>_<pubid>`, ex. `nf_a1b2c3d4`). */
+    prefix: string | null;
+    /** Libellé humain (« CI deploy », « app mobile »). */
+    name: string;
+    /** Capacités accordées (axe distinct des rôles RBAC). */
+    scopes: string[];
+    /** Porteur (id utilisateur ou service account). */
+    subjectId: string;
+    /** Discriminant du porteur. */
+    subjectType: "user" | "service";
+    /** Organisation/tenant (`null` = global). */
+    tenantId: string | null;
+    /** Création (epoch ms). */
+    createdAt: number;
+    /** Expiration (epoch ms) ou `null` (sans expiration). */
+    expiresAt: number | null;
+    /** Dernier usage (epoch ms) ou `null` (jamais utilisée). */
+    lastUsedAt: number | null;
+    /**
+     * Adresse du dernier usage, ou `null`. C'est ce qui permet à un porteur de
+     * reconnaître une clé qui a servi ailleurs que là où il l'a déployée — donc de
+     * dater une fuite. Dépouillée de `X-Forwarded-For` selon `trustProxy`.
+     */
+    lastUsedIp: string | null;
+    /** Agent du dernier usage, ou `null` (même usage : reconnaître l'inattendu). */
+    lastUsedUserAgent: string | null;
+    /** Révocation (epoch ms) ou `null` (active). */
+    revokedAt: number | null;
+}
+/**
+ * Résultat d'une **création** de clé — la vue publique **+ le token en clair**.
+ * Le `token` n'est disponible qu'ICI, une seule fois : il n'est jamais stocké
+ * (seul son `sha256` l'est) ni re-dérivable. La console l'affiche puis l'oublie.
+ */
+export interface IApiKeyCreated extends IApiKeyView {
+    /** Secret EN CLAIR — affiché UNE seule fois (RFC : « shown once »). */
+    token: string;
+}
+/**
+ * Capacités/contraintes d'émission des clés API — exposées à la console (« Mes
+ * clés ») pour un formulaire de création **honnête** : plafond par porteur,
+ * catalogue de scopes, préfixe public, durée par défaut. **Aucune valeur
+ * sensible** (config publique : le préfixe figure déjà dans chaque clé).
+ */
+export interface IApiKeyCapabilities {
+    /** Émission de clés activée en config (`apiKeys.enabled`). */
+    enabled: boolean;
+    /** Marqueur public des clés (`<prefix>_…`, ex. `nf`). */
+    prefix: string;
+    /** Expiration par défaut en jours (`null` = sans expiration). */
+    defaultExpiryDays: number | null;
+    /** Plafond de clés ACTIVES par porteur (création au-delà → 409). */
+    maxPerSubject: number;
+    /** Catalogue de scopes autorisés (`null` = libre : tout scope non vide accepté). */
+    allowedScopes: string[] | null;
+}
+/** Options de création d'une clé API. */
+export interface ICreateApiKeyOptions {
+    /** Libellé humain (obligatoire, non vide). */
+    name: string;
+    /** Capacités demandées (⊆ `apiKeys.allowedScopes` si un catalogue est défini). */
+    scopes?: string[];
+    /** Durée de vie en jours ; `null` = sans expiration ; omis = défaut config. */
+    expiresInDays?: number | null;
+    /** Tenant/organisation (multi-tenant) ; `null` = global. */
+    tenantId?: string | null;
+}

package/dist/types/nodefony/contracts/IAuditEvent.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Modèle d'un **événement de sécurité** auditable (P6.14) — login, refus d'accès,
+ * émission/révocation de jeton, défense CSRF/CORS, verrou de frame WS. Vocabulaire
+ * MÉTIER de sécurité, distinct du log technique du trafic (`AuditLogEntry`,
+ * `@nodefony/http` P3.1, 1 PDU/requête) : ici on trace une **transition d'état**
+ * de sécurité, pas chaque requête. Sérialisable JSON (stream WS + persistance).
+ *
+ * Règle d'or : un **secret n'entre JAMAIS** dans un événement (ni mot de passe, ni
+ * jeton, ni cookie) — seule sa *présence* est tracée via {@link IAuditEvent.flags}.
+ */
+/**
+ * Sous-système de sécurité concerné — axe de filtrage principal de la console
+ * d'audit (Studio P6.15). Fermé : la liste des sous-systèmes est stable.
+ *
+ * ⚠️ Quatre catégories sont RÉSERVÉES — déclarées au contrat mais **sans émetteur à
+ * ce jour** (aucun `record({ category: … })` ne les produit) : `oauth`, `csrf`,
+ * `cors`, `config`. La console Studio ne propose donc PAS de filtre pour elles (un
+ * filtre qui ne rend jamais rien induit en erreur — cf `studio/.../auditModel.ts`).
+ * En câbler une = ajouter son émetteur ICI (l'émetteur), puis la métadonnée
+ * d'affichage dans `AUDIT_CATEGORIES`. Émettent réellement : auth, authz, token,
+ * session, webauthn, ws, webhook.
+ */
+export type AuditCategory = "auth" | "authz" | "token" | "session" | "oauth" | "webauthn" | "csrf" | "cors" | "ws" | "webhook" | "config";
+/**
+ * Issue d'une action de sécurité. La distinction `failure`/`denied` est utile à
+ * l'auditeur : `failure` = l'acteur a échoué une preuve (brute-force, signature
+ * invalide) ; `denied` = une **politique** a refusé un acteur même bien formé
+ * (rôle manquant, origine interdite, plancher WS) — signal d'accès non autorisé.
+ */
+export type AuditOutcome = "success" | "failure" | "denied";
+/** Drapeaux de **présence** de matériel sensible (jamais la valeur). */
+export interface IAuditEventFlags {
+    /** Un en-tête `Authorization` était présent. */
+    hasAuthorization?: boolean;
+    /** Un cookie était présent. */
+    hasCookie?: boolean;
+}
+/**
+ * Un événement de sécurité journalisé. `id`/`ts` sont posés par l'`AuditService`
+ * (l'émetteur ne fournit qu'un {@link IAuditEventDraft}) → un seul appel système
+ * d'horodatage, centralisé hors des points d'émission.
+ */
+export interface IAuditEvent {
+    /** Identifiant unique dans le process (corrélation + curseur de pagination). */
+    id: string;
+    /** Horodatage (epoch ms, `Date.now()`), posé par le service. */
+    ts: number;
+    /** Sous-système concerné — axe de filtrage principal. */
+    category: AuditCategory;
+    /**
+     * Action conventionnée `<sujet>.<verbe>` (ex. `"login.success"`,
+     * `"access.denied"`, `"token.revoked"`, `"session.opened"`). String **ouverte**
+     * (la liste grandit lot par lot) — PAS un enum fermé, qui coupleraient
+     * `IAuditEvent` à chaque point d'émission. Table de référence : README §Audit.
+     */
+    action: string;
+    /** Issue de l'action. */
+    outcome: AuditOutcome;
+    /**
+     * Acteur : identité (`token.getUserIdentifier()`) ou `null` si anonyme/non
+     * identifié (tentative pré-authentification). Un **libellé d'identité**, jamais
+     * un secret.
+     */
+    actor: string | null;
+    /**
+     * Ressource visée (zone firewall, route, canal WS, attribut d'autorisation) —
+     * descripteur léger ; jamais le corps ni les en-têtes de la requête.
+     */
+    resource?: string | null;
+    /**
+     * Raison **machine** stable et filtrable (ex. `"invalid_credentials"`,
+     * `"throttled"`, `"veto"`, `"origin_mismatch"`) — PAS un message libre traduit.
+     */
+    reason?: string | null;
+    /** IP source si disponible (audit « from where »). */
+    ip?: string | null;
+    /** User-Agent source si disponible. */
+    userAgent?: string | null;
+    /** Id de requête (corrélation log ↔ audit via l'ALS, P1.4) ; `null` hors requête. */
+    requestId?: string | null;
+    /**
+     * **Présence** (jamais la valeur) de matériel sensible au moment de l'événement
+     * — calque `AuditLogEntry.hasAuthorization`. Trace « un cookie / un Authorization
+     * était là » sans jamais journaliser le secret lui-même.
+     */
+    flags?: IAuditEventFlags;
+    /** Extras applicatifs libres (anti-migration) ; absents par défaut. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Champs fournis par l'**émetteur** d'un événement — l'`AuditService` y ajoute
+ * `id` + `ts`. Garde les points d'émission concis et sans appel système d'horloge.
+ */
+export type IAuditEventDraft = Omit<IAuditEvent, "id" | "ts">;

package/dist/types/nodefony/contracts/IAuditStore.d.ts

@@ -0,0 +1,80 @@
+import type { IPage, IPageQuery } from "nodefony";
+import type { AuditCategory, AuditOutcome, IAuditEvent, IAuditEventDraft } from "./IAuditEvent.js";
+/**
+ * Filtre de lecture du journal d'audit (console Studio P6.15, data plane P6.14
+ * Lot 3) — {@link IPageQuery} + les critères propres au journal. Tous les
+ * critères sont **AND** ; absents = non filtrant.
+ *
+ * Pagination par **curseur** (jamais `offset`) : un journal reçoit des écritures
+ * pendant qu'on le parcourt, un décalage numérique glisserait d'une page à
+ * l'autre. Le curseur est **opaque** — sa forme appartient au store, l'appelant
+ * ne fait que repasser le {@link IPage.nextCursor} reçu.
+ *
+ * `q` (hérité) n'est **pas** appliqué : filtrer un journal se fait par ses axes
+ * (catégorie / issue / acteur / action / requête / fenêtre), pas en plein texte.
+ */
+export interface IAuditListQuery extends IPageQuery {
+    /** Restreint à un sous-système. */
+    category?: AuditCategory;
+    /** Restreint à une issue (`success`/`failure`/`denied`). */
+    outcome?: AuditOutcome;
+    /** Restreint à un acteur (égalité exacte de l'identifiant). */
+    actor?: string;
+    /** Restreint à une action conventionnée (`"login.success"`…). */
+    action?: string;
+    /** Restreint aux événements d'une **requête** (corrélation trace ↔ audit, P6.15). */
+    requestId?: string;
+    /** Borne basse d'horodatage (epoch ms, inclus). */
+    since?: number;
+    /** Borne haute d'horodatage (epoch ms, inclus). */
+    until?: number;
+}
+/**
+ * Journal d'audit **append-only** (tamper-evident) — état serveur des événements
+ * de sécurité. **Pluggable** par backend (mémoire/fichier/ORM/Loki) comme
+ * `ITokenStore`. La référence mémoire borne le volume (anti-fuite) ; un backend
+ * partagé (ORM/Redis) sert le multi-pod et la rétention longue.
+ *
+ * `append` est la SEULE écriture : pas d'`update` ni de `delete` ciblé — seul le
+ * `gc` (rétention) retire des entrées. L'immuabilité est la garantie d'audit.
+ */
+export interface IAuditStore {
+    /** Ajoute un événement (immuable, jamais modifié ensuite). */
+    append(event: IAuditEvent): Promise<void>;
+    /**
+     * Lit **une page** d'événements filtrés, du plus récent au plus ancien —
+     * l'implémentation ne matérialise jamais plus que `limit` événements.
+     *
+     * `total` n'est renseigné que si `withTotal` n'est pas `false` (un `COUNT`
+     * filtré sur un journal de rétention longue se paie) ; {@link IPage.hasNext}
+     * et {@link IPage.nextCursor} sont fiables dans les deux cas.
+     */
+    listPage(query: IAuditListQuery): Promise<IPage<IAuditEvent>>;
+    /**
+     * Purge les événements au-delà de la fenêtre de rétention. À planifier
+     * périodiquement par le propriétaire du store (timer `unref`). Sans appel, un
+     * backend sans TTL natif s'accumule jusqu'à sa borne de volume.
+     *
+     * @returns nombre d'événements purgés.
+     */
+    gc(now?: number): Promise<number>;
+}
+/**
+ * Face **émission** du journal, vue par les points sensibles (firewall,
+ * authenticators, controllers OAuth/WebAuthn). `record` est **synchrone et
+ * fire-and-forget** : l'audit ne doit JAMAIS bloquer ni faire échouer le flux
+ * métier (un store en panne se solde par un log d'erreur, pas par un login KO).
+ * No-op à coût nul si l'audit est désactivé.
+ */
+export interface IAuditSink {
+    /**
+     * Journalise un événement : pose `id`+`ts`, persiste (best-effort) et notifie
+     * les abonnés live. Aucun effet (aucune allocation côté service) si désactivé.
+     */
+    record(event: IAuditEventDraft): void;
+    /**
+     * S'abonne au flux live des événements (bridge WS, P6.14 Lot 4). Renvoie une
+     * fonction de désabonnement (cleanup obligatoire — pas de listener orphelin).
+     */
+    subscribe(listener: (event: IAuditEvent) => void): () => void;
+}

package/dist/types/nodefony/contracts/IAuthenticator.d.ts

@@ -0,0 +1,66 @@
+import type { ContextType } from "@nodefony/http";
+import type { IToken } from "./IToken.js";
+import type { ISecuredArea } from "./ISecuredArea.js";
+/**
+ * Stratégie d'authentification — pattern « authenticator » : une classe = une
+ * façon de prouver qui on est. Pas de Bridge/Factory (héritage Passport/YAML
+ * abandonné).
+ *
+ * Une zone sécurisée ({@link ISecuredArea}) liste les noms d'authenticators à
+ * exécuter selon son `mode` : `"first"` (le premier dont `supports()` est vrai
+ * authentifie) ou `"all"` (tous doivent passer — MFA, le dernier porte
+ * l'identité). Cycle : `createToken()` extrait le credential (token non
+ * authentifié), `authenticate()` valide et promeut ou `throw` (→ 401).
+ *
+ * Implémentations : `AnonymousAuthenticator`, `UserPasswordAuthenticator`,
+ * `SessionAuthenticator`, `JwtAuthenticator`, `ApiKeyAuthenticator`.
+ *
+ * Le login social ne passe **pas** par un authenticator : `OAuth2Service`
+ * échange le code, provisionne l'utilisateur et ouvre une session BFF — c'est
+ * ensuite `SessionAuthenticator` qui ré-authentifie les requêtes suivantes.
+ */
+export interface IAuthenticator {
+    /** Nom logique (référencé dans `area.authenticators`). */
+    readonly name: string;
+    /** Peut-on extraire un credential de cette requête ? (sinon authenticator suivant). */
+    supports(context: ContextType): boolean;
+    /** Construit un token NON authentifié depuis la requête (extraction credential). */
+    createToken(context: ContextType): Promise<IToken>;
+    /** Valide le token (vérifie le credential) ou `throw` une AuthenticationError. */
+    authenticate(token: IToken): Promise<IToken>;
+    /** Hook succès — pose le token (cookie JWT, log audit S1…). */
+    onSuccess(context: ContextType, token: IToken): Promise<void>;
+    /** Hook échec — log audit, throttling (J2)… Le 401 + challenge sont posés par le firewall. */
+    onFailure(context: ContextType, error: Error): Promise<void>;
+    /**
+     * Challenge `WWW-Authenticate` (RFC 7235 : tout 401 DOIT en porter un).
+     * Le firewall pose celui du premier authenticator de la zone qui en déclare.
+     * Ex. `'Basic realm="nodefony", charset="UTF-8"'`, `'Bearer'`.
+     *
+     * La ZONE est passée parce qu'un défi peut dépendre d'elle — le pointeur
+     * `resource_metadata` de la RFC 9728 nomme la ressource, et une instance
+     * d'authenticator est partagée entre toutes les zones qui la listent. Sans
+     * cet argument, un authenticator ne pouvait rendre qu'un défi constant, donc
+     * muet sur la ressource réellement visée.
+     *
+     * @param area - zone qui a refusé ; absente si l'appelant n'en a pas
+     */
+    challenge?(area?: ISecuredArea): string;
+    /**
+     * Vérifie AU BOOT que la zone qui référence cet authenticator lui donne ce
+     * dont il a besoin — sinon `throw`, et la configuration n'existe pas.
+     *
+     * Appelée une fois par zone qui le liste, avant la première requête. C'est
+     * l'authenticator qui dit ce qu'il exige, jamais le firewall : celui-ci ne
+     * connaît aucun nom en dur, et un plugin tiers doit pouvoir poser ses propres
+     * exigences sans qu'on touche au cœur.
+     *
+     * Le contrôle vaut d'être fait ici plutôt qu'à la première requête, où il se
+     * manifesterait par un 401 sans cause visible, chez un seul appelant, un jour
+     * quelconque.
+     *
+     * @param area - la zone qui référence cet authenticator
+     * @throws Error si la zone ne remplit pas les conditions d'emploi
+     */
+    validateArea?(area: ISecuredArea): void;
+}