authGuard

Middleware d’authentification JWT pour les routes Next.js. Vérifie la présence et la validité d’un token JWT stocké dans le cookie auth, protège les routes privées et injecte les headers utilisateur (x-user-id, x-user-role, x-user-permissions) dans la requête.

Utilisation de base — Fichier proxy

Créer un fichier src/proxy.ts dans votre projet Next.js et utiliser authGuardpour protéger les routes.

import { authGuard } from "@ramses1er/cbk-toolkit/server";
import type { NextRequest } from "next/server";

export async function proxy(request: NextRequest) {
  return authGuard(request, {
    publicRoutes: ["/", "/api/login", "/api/logout"],
    loginUrl: "/",
    jwtSecret: process.env.JWT_SECRET!,
  });
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|img/|manifest|sw).*)"],
};

Routes publiques avec wildcard

Les routes publiques peuvent utiliser le suffixe /*pour correspondre à un préfixe. Toute route commençant par ce préfixe sera accessible sans authentification.

authGuard(request, {
  publicRoutes: [
    "/",
    "/api/public/*",   // /api/public/status, /api/public/health, etc.
    "/blog/*",         // /blog/article-1, /blog/category/dev, etc.
  ],
  loginUrl: "/login",
  jwtSecret: process.env.JWT_SECRET!,
});

Comportement — Flux d’authentification

Route publique→ la requête passe sans vérification (NextResponse.next()).
Token absent → redirection vers loginUrl avec ?error=authentification_requise.
Token invalide ou expiré→ redirection vers loginUrl avec ?error=token_invalide.
Token valide → injection des headers x-user-id, x-user-role et x-user-permissions, puis la requête continue.

API de référence

Propriété	Type	Défaut	Description
`authGuard(request, options)`
request	NextRequest	requis	Requête entrante Next.js
options	AuthGuardOptions	requis	Configuration du guard
`AuthGuardOptions`
publicRoutes	string[]	requis	Routes publiques (support `/*` wildcard)
loginUrl	string	requis	URL de redirection si non authentifié
jwtSecret	string	requis	Clé secrète JWT (HS256)
Headers injectés (sur token valide)
x-user-id	string	—	ID de l’utilisateur extrait du token
x-user-role	string	—	Rôle de l’utilisateur
x-user-permissions	string	—	Permissions séparées par des virgules

Types TypeScript

interface AuthGuardOptions {
  publicRoutes: string[];
  loginUrl: string;
  jwtSecret: string;
}

// Payload attendu dans le JWT
interface JwtPayload {
  id: string;
  role: string;
  permissions?: string[];
}