@cedvict/http-guardian 0.0.1-next.0 → 0.0.1-next.11

package/dist/guards/bearerRefreshGuard.d.ts

@@ -0,0 +1,45 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type BearerRefreshTokens = {
+    accessToken: string;
+    refreshToken?: string;
+};
+export type BearerRefreshGuardOptions = {
+    /** Appelé sur 401 pour obtenir un nouveau token. */
+    refreshFn: () => Promise<BearerRefreshTokens>;
+    /** Appelé si le refresh échoue (logout, redirect login, etc.). */
+    onAuthFailed?: (error: unknown) => void | Promise<void>;
+    /**
+     * Hook optionnel : appelé avec le résultat de refreshFn() **avant** que les
+     * requêtes en queue ne soient rejouées. Permet à l'application de persister
+     * le nouveau token (localStorage, signal, etc.) de façon atomique.
+     *
+     * Si non fourni, le guard se contente de laisser `auth.getToken` retourner
+     * la nouvelle valeur (l'application doit donc l'avoir mise à jour ailleurs,
+     * typiquement dans `refreshFn` lui-même).
+     */
+    onTokenRefreshed?: (tokens: BearerRefreshTokens) => void | Promise<void>;
+    /**
+     * Ne pas tenter de refresh si la requête originale matche ce predicate.
+     * Ex: ne pas refresh sur `/auth/login`, `/auth/refresh`.
+     */
+    skipRefreshFor?: (ctx: RequestContext) => boolean;
+    /** Statuts qui déclenchent un refresh (défaut: [401]). */
+    triggerStatuses?: number[];
+    /** Délai max d'attente d'une requête en queue (défaut: 30_000 ms). */
+    queueTimeoutMs?: number;
+};
+/**
+ * Guard de refresh JWT Bearer avec queue / single-flight.
+ *
+ * Sur 401, un seul `refreshFn()` est invoqué ; toutes les autres requêtes 401
+ * reçues pendant ce refresh attendent dans une queue partagée :
+ * - si refresh OK → toutes sont rejouées avec le nouveau token (header
+ *   `Authorization` ré-injecté via `auth.getToken()`).
+ * - si refresh KO → toutes sont rejetées et `onAuthFailed(error)` est appelé
+ *   une seule fois.
+ *
+ * Anti-boucle : un retry n'engendre jamais un nouveau refresh.
+ */
+export declare function bearerRefreshGuard(opts: BearerRefreshGuardOptions): Guard;
+//# sourceMappingURL=bearerRefreshGuard.d.ts.map

package/dist/guards/bearerRefreshGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearerRefreshGuard.d.ts","sourceRoot":"","sources":["../../src/guards/bearerRefreshGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,oDAAoD;IACpD,SAAS,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE9C,kEAAkE;IAClE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;IAElD,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAgBF;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,KAAK,CAgEzE"}

package/dist/guards/cookieSafeRefreshGuard.d.ts

@@ -0,0 +1,40 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type CookieSafeRefreshGuardOptions = {
+    /**
+     * Endpoint refresh (absolu ou relatif)
+     * ex: "/auth/refresh" ou "https://api.example.com/auth/refresh"
+     */
+    refreshPath: string;
+    /** Méthode refresh (souvent POST) */
+    refreshMethod?: "POST" | "GET";
+    /** Statuts qui déclenchent refresh. Default: [401, 419] */
+    triggerStatuses?: number[];
+    /** Nombre max de replays de la requête originale. Default: 1 */
+    maxRetry?: number;
+    /**
+     * Exclure certains paths (pathname) de la logique refresh.
+     * Ex: ["/auth/refresh", "/health"]
+     */
+    excludePaths?: string[];
+    /**
+     * Si refresh renvoie 429 Too Many Requests,
+     * on stoppe les refresh jusqu’à une date (cooldown).
+     * Default: true
+     */
+    honorRetryAfter?: boolean;
+    /** Décider si on refresh selon ctx + status */
+    shouldRefresh?: (ctx: RequestContext, status: number) => boolean;
+    /** Hook: appelé quand refresh échoue (utile pour redirect login) */
+    onRefreshFailed?: (info: {
+        status?: number;
+        url: string;
+        reason?: string;
+    }) => void;
+    /** Hook: appelé quand refresh réussit */
+    onRefreshSuccess?: (info: {
+        url: string;
+    }) => void;
+};
+export declare function cookieSafeRefreshGuard(opts: CookieSafeRefreshGuardOptions): Guard;
+//# sourceMappingURL=cookieSafeRefreshGuard.d.ts.map

package/dist/guards/cookieSafeRefreshGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookieSafeRefreshGuard.d.ts","sourceRoot":"","sources":["../../src/guards/cookieSafeRefreshGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAO7D,MAAM,MAAM,6BAA6B,GAAG;IAC1C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAE/B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAEjE,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAEpF,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACpD,CAAC;AAoDF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,KAAK,CAyIjF"}

package/dist/guards/correlationIdGuard.d.ts

@@ -0,0 +1,18 @@
+import type { Guard } from "./types.js";
+export type CorrelationIdGuardOptions = {
+    /** Header pour l'ID corrélation (défaut: 'X-Correlation-Id'). */
+    headerName?: string;
+    /** Générateur d'ID (défaut: crypto.randomUUID si dispo, sinon fallback). */
+    generator?: () => string;
+    /** Si présent en réponse, copier dans `ctx.meta.correlationId`. */
+    readResponseHeader?: boolean;
+};
+/**
+ * Guard qui injecte un header `X-Correlation-Id` (UUID par défaut) sur chaque
+ * requête, et lit le header de réponse pour le copier dans `ctx.meta.correlationId`.
+ *
+ * L'ID est **stable entre retries** : un ID est généré une seule fois par
+ * requête originale (mémorisé sur le ctx), pour préserver la traçabilité.
+ */
+export declare function correlationIdGuard(opts?: CorrelationIdGuardOptions): Guard;
+//# sourceMappingURL=correlationIdGuard.d.ts.map

package/dist/guards/correlationIdGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlationIdGuard.d.ts","sourceRoot":"","sources":["../../src/guards/correlationIdGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,yBAAyB,GAAG;IACtC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IAEzB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAqBF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,yBAA8B,GAAG,KAAK,CAwC9E"}

package/dist/guards/csrfGuard.d.ts

@@ -0,0 +1,25 @@
+import type { Guard } from "./types.js";
+export type CsrfGuardOptions = {
+    /** Lit `document.cookie` (browser only). Ex: 'csrf_token'. */
+    tokenFromCookie?: string;
+    /** Source custom (storage, signal, observable, etc.). */
+    tokenFromStorage?: () => string | null | Promise<string | null>;
+    /**
+     * Lit le token depuis un header de réponse précédent (mémorisé en interne).
+     * Ex: header 'X-CSRF-Token' renvoyé par /auth/login.
+     */
+    tokenFromHeader?: string;
+    /** Header HTTP à injecter (défaut: 'X-CSRF-Token'). */
+    headerName?: string;
+    /** Méthodes mutantes (défaut: ['POST', 'PUT', 'PATCH', 'DELETE']). */
+    applyTo?: string[];
+};
+/**
+ * Guard d'injection de header CSRF sur méthodes mutantes.
+ *
+ * SSR-safety : si `tokenFromCookie` est utilisé hors browser, le guard skippe
+ * silencieusement (pas de header injecté). Combiner avec `tokenFromStorage`
+ * pour fournir un fallback côté serveur.
+ */
+export declare function csrfGuard(opts?: CsrfGuardOptions): Guard;
+//# sourceMappingURL=csrfGuard.d.ts.map

package/dist/guards/csrfGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrfGuard.d.ts","sourceRoot":"","sources":["../../src/guards/csrfGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChE;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAwBF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,gBAAqB,GAAG,KAAK,CAqD5D"}

package/dist/guards/idempotencyGuard.d.ts

@@ -0,0 +1,25 @@
+import type { Guard } from "./types.js";
+export type IdempotencyGuardOptions = {
+    /** Header (défaut: 'X-Idempotency-Key'). */
+    headerName?: string;
+    /** Méthodes ciblées (défaut: ['POST', 'PUT', 'PATCH']). */
+    applyTo?: string[];
+    /** Générateur (défaut: crypto.randomUUID si dispo, sinon fallback). */
+    generator?: () => string;
+    /**
+     * Si l'utilisateur fournit déjà une key (via `RequestOptions.idempotencyKey`,
+     * via `ctx.idempotencyKey`, via `ctx.meta.idempotencyKey` ou directement
+     * via header), la respecter (défaut: true).
+     */
+    respectExisting?: boolean;
+};
+/**
+ * Guard qui injecte un header `X-Idempotency-Key` (UUID par défaut) sur les
+ * méthodes mutantes (POST/PUT/PATCH).
+ *
+ * **Stable entre retries** : la clé est générée une seule fois par requête
+ * originale (mémorisée sur le ctx) ; rejouer la même requête utilise donc la
+ * même clé — sinon l'idempotence côté serveur est cassée.
+ */
+export declare function idempotencyGuard(opts?: IdempotencyGuardOptions): Guard;
+//# sourceMappingURL=idempotencyGuard.d.ts.map

package/dist/guards/idempotencyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotencyGuard.d.ts","sourceRoot":"","sources":["../../src/guards/idempotencyGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,uBAAuB,GAAG;IACpC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IAEzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAoBF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG,KAAK,CAqC1E"}

package/dist/guards/instrumentGuard.d.ts

@@ -0,0 +1,12 @@
+import type { Guard } from "./types.js";
+type InstrumentOptions = {
+    name: string;
+    log?: (line: string, data?: any) => void;
+    include?: RegExp;
+    exclude?: RegExp;
+    logInit?: boolean;
+    stack?: boolean;
+};
+export declare function instrumentGuard(opts: InstrumentOptions, guard: Guard): Guard;
+export {};
+//# sourceMappingURL=instrumentGuard.d.ts.map

package/dist/guards/instrumentGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentGuard.d.ts","sourceRoot":"","sources":["../../src/guards/instrumentGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AASxC,KAAK,iBAAiB,GAAG;IAEvB,IAAI,EAAE,MAAM,CAAC;IAGb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAGzC,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAIlB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AA0CF,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAiE5E"}

package/dist/guards/retryGuard.d.ts

@@ -0,0 +1,12 @@
+import type { Guard } from "./types.js";
+/**
+ * Simple retry guard for transient HTTP statuses.
+ * Note: this doesn't retry network errors thrown by fetch itself (those are handled by the client wrapper).
+ */
+export declare function retryGuard(opts?: {
+    retries?: number;
+    retryOn?: number[];
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}): Guard;
+//# sourceMappingURL=retryGuard.d.ts.map

package/dist/guards/retryGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryGuard.d.ts","sourceRoot":"","sources":["../../src/guards/retryGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAkB5H"}

package/dist/guards/types.d.ts

@@ -0,0 +1,3 @@
+import type { RequestContext } from "../internal/context.js";
+export type Guard = (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+//# sourceMappingURL=types.d.ts.map

package/dist/guards/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guards/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC"}

package/dist/guards/unauthorizedGuard.d.ts

@@ -0,0 +1,19 @@
+import type { Guard } from "./types.js";
+import type { RequestContext } from "../internal/context.js";
+export type UnauthorizedGuardOptions = {
+    onUnauthorized: (ctx: {
+        url: string;
+        status: number;
+    }) => void;
+    statuses?: number[];
+    ignoreNoAuth?: boolean;
+    once?: boolean;
+    cooldownMs?: number;
+    shouldHandle?: (ctx: RequestContext, status: number) => boolean;
+    excludePaths?: string[];
+};
+/**
+ * Centralizes “unauthorized” handling (redirect/logout) with anti-spam.
+ */
+export declare function unauthorizedGuard(opts: UnauthorizedGuardOptions): Guard;
+//# sourceMappingURL=unauthorizedGuard.d.ts.map

package/dist/guards/unauthorizedGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorizedGuard.d.ts","sourceRoot":"","sources":["../../src/guards/unauthorizedGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAa7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,cAAc,EAAE,CAAC,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,KAAK,CA6CvE"}