@nodefony/security 10.0.0-alpha.1

package/dist/types/nodefony/src/webhook/webhookSignature.d.ts

@@ -0,0 +1,20 @@
+import { Buffer } from "node:buffer";
+/**
+ * Décode un secret `whsec_<base64>` en octets de clé HMAC. Tolère un secret déjà
+ * sans préfixe (base64 brut).
+ */
+export declare function parseWebhookSecret(secret: string): Buffer;
+/** Construit la base à signer : `{id}.{timestamp}.{body}` (Standard Webhooks). */
+export declare function buildSignatureBase(id: string, timestampS: number, body: string): string;
+/**
+ * Signe un message webhook (Standard Webhooks `v1`). Retourne la valeur du header
+ * `webhook-signature` : `v1,<base64(HMAC-SHA256(secret, base))>`.
+ *
+ * @param secret - secret `whsec_…` de l'endpoint (en clair).
+ * @param id - identifiant du message (`webhook-id`).
+ * @param timestampS - horodatage epoch **secondes** (`webhook-timestamp`).
+ * @param body - corps JSON sérialisé envoyé.
+ */
+export declare function signStandardWebhook(secret: string, id: string, timestampS: number, body: string): string;
+/** En-têtes de signature Standard Webhooks à poser sur la requête sortante. */
+export declare function webhookSignatureHeaders(secret: string, id: string, timestampS: number, body: string): Record<string, string>;

package/dist/types/nodefony/src/webhook/webhookSort.d.ts

@@ -0,0 +1,39 @@
+import type { IPageQuery } from "nodefony";
+/**
+ * **Le vocabulaire de tri des endpoints webhook**, en noms PUBLICS — ceux qu'un
+ * client écrit dans l'URL (`?order=failureCount:DESC`), jamais des noms de
+ * colonne.
+ *
+ * Il vit ici, chez le propriétaire du contrat (`@nodefony/security`), et non dans
+ * chaque backend : c'est ce qui garantit qu'une console offre le même tri, que
+ * l'application tourne sur mémoire, SQL ou Mongo. Un store dont le schéma nomme
+ * un champ autrement traduit **chez lui** — cf {@link translateWebhookOrderMongo}.
+ *
+ * - `createdAt` / `updatedAt` — quand l'abonnement a été posé, quand il a bougé ;
+ * - `url` — la destination, colonne principale de la console ;
+ * - `enabled` — regroupe les abonnements coupés ;
+ * - `failureCount` — « qui échoue le plus », l'axe d'exploitation d'un webhook ;
+ * - `id` — utile surtout en départage.
+ *
+ * **Ce qui n'y est PAS, et pourquoi** : `lastDeliveryAt`, `lastDeliveryStatus` et
+ * `lastDeliveryError` sont *nullables* — un endpoint qui n'a jamais livré n'a pas
+ * de dernière livraison — et le placement des valeurs absentes n'est pas le même
+ * d'un moteur à l'autre (PostgreSQL les met en tête d'un tri `DESC`, SQLite,
+ * MySQL et le tri en mémoire en queue). Les déclarer offrirait un tri dont
+ * l'ordre dépendrait de la base configurée.
+ *
+ * ⚠️ Cette liste est aussi une **garde de sécurité**, pas seulement une capacité :
+ * un nom de champ ne se lie pas en paramètre SQL, il se **concatène** dans le
+ * `ORDER BY`. Tout backend qui construit sa requête à la main filtre donc avec
+ * elle, en défense en profondeur — sans compter sur le fait que le data plane
+ * ait déjà refusé.
+ */
+export declare const WEBHOOK_SORTABLE_FIELDS: readonly ["createdAt", "updatedAt", "url", "enabled", "failureCount", "id"];
+/**
+ * Ordre contractuel appliqué quand le client n'en demande aucun : les
+ * abonnements les plus récents d'abord, départagés par identifiant pour rester
+ * **déterministe** à horodatage égal — sans ce tiebreaker, deux endpoints créés
+ * dans la même milliseconde peuvent changer de page entre deux appels, et l'un
+ * des deux ne jamais apparaître.
+ */
+export declare const WEBHOOK_DEFAULT_ORDER: NonNullable<IPageQuery["order"]>;

package/dist/types/nodefony/src/webhook/webhookStoreRegistry.d.ts

@@ -0,0 +1,31 @@
+import type { Container } from "nodefony";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import type { IWebhookStore } from "../../contracts/IWebhookStore.js";
+/**
+ * Registre de **fabriques de stores d'endpoints webhook** — résout un nom
+ * (`memory`, `drizzle`, `mongoose`…) vers une instance, SANS coupler le cœur à un
+ * backend en dur.
+ *
+ * Convention-frère de `totpSecretStoreRegistry` / `tokenStoreRegistry` : le
+ * builtin sans dépendance (`memory`) s'enregistre au chargement du module ; les
+ * adapters lourds s'enregistrent depuis LEUR module (`import type { IWebhookStore }`,
+ * effacé à la compilation → 0 dép runtime, 0 cycle).
+ *
+ * Pas de builtin `file` (un endpoint n'est pas un fichier de session) ni `redis`
+ * (la config durable ne vit pas dans un cache ; Redis servira la *queue de
+ * livraison* cross-pod, pas ce contrat).
+ */
+export interface IWebhookStoreFactoryContext {
+    /** Container DI — résolution de services (ORM…). */
+    readonly container: Container;
+    /** Config sécurité validée + gelée. */
+    readonly config: ISecurityConfig;
+}
+/** Fabrique d'un store d'endpoints webhook pour un nom donné. */
+export type WebhookStoreFactory = (ctx: IWebhookStoreFactoryContext) => IWebhookStore;
+/** Enregistre (ou remplace) la fabrique d'un store d'endpoints webhook. */
+export declare function registerWebhookStore(name: string, factory: WebhookStoreFactory): void;
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+export declare function getWebhookStoreFactory(name: string): WebhookStoreFactory | undefined;
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+export declare function listWebhookStores(): string[];