Serveur · Guide pratique

Middleware API

Authentifiez les requêtes Effect HttpApi, obtenez une session typée et imposez les exigences utilisateur et organisation côté serveur.

AuthMiddleware relie une application Effect HttpApi à Krakstack Auth. Il transmet le contexte sûr de la requête, accepte les témoins navigateur et les clés x-api-key, puis fournit AuthService aux gestionnaires.

Ajouter le middleware à l'API

import { AuthMiddleware } from "@krak-stack/auth/server";
import { HttpApi } from "effect/http-api";

export const AppApi = HttpApi.make("AppApi")
  .add(CoursesApiGroup)
  .prefix("/api")
  .middleware(AuthMiddleware);

Le middleware rend AuthService disponible; il n'exige pas automatiquement un utilisateur sur chaque endpoint. Un gestionnaire public peut appeler getSession(), tandis qu'un gestionnaire protégé doit appeler une méthode require*.

Fournir la couche

import { AuthMiddleware } from "@krak-stack/auth/server";
import { Layer } from "effect";
import { FetchHttpClient } from "effect/http";
import { HttpApiBuilder } from "effect/http-api";

const AuthLive = AuthMiddleware.layer();

export const ApiLive = HttpApiBuilder.layer(AppApi).pipe(
  Layer.provide(AuthLive),
  Layer.provide(FetchHttpClient.layer),
);

La couche lit KRAKSTACK_AUTH_URL et KRAKSTACK_AUTH_SERVICE_API_KEY. La clé autorise les consultations serveur de confiance et ne doit jamais atteindre le navigateur.

Exiger une identité

import { AuthService } from "@krak-stack/auth/server";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const auth = yield* AuthService;
  const session = yield* auth.requireUserOrganization();

  return {
    userId: session.user.id,
    organizationId: session.session.activeOrganizationId,
  };
});

Méthode	Exigence	Résultat
`getSession()`	Aucune	Session ou `null`
`requireSession()`	Témoin ou clé API valide	Session authentifiée
`requireUser()`	Session avec utilisateur	Utilisateur non nul
`requireOrganization()`	Organisation active	Identifiant d'organisation typé
`requireUserOrganization()`	Utilisateur et organisation	Session entièrement précisée

Les méthodes require* échouent avec HttpApiError.Unauthorized, ce qui permet à HttpApi de produire la bonne réponse sans gestion générale d'exceptions.

Témoins et clés API

Les requêtes navigateur incluent leurs identifiants afin que le middleware transmette le témoin de session. Les clients machine de confiance envoient x-api-key. Le middleware valide la clé et construit la même frontière de session typée.

N'acceptez jamais un identifiant utilisateur, organisation ou rôle fourni par un en-tête comme preuve d'accès. Utilisez les valeurs de AuthService dans les filtres de base de données.

Usurpation d'organisation

L'usurpation est refusée par défaut. Pour un mode d'aperçu volontairement limité, autorisez uniquement des couples méthode-chemin explicites :

const AuthLive = AuthMiddleware.layer({
  allowedOrganizationImpersonationRoutes: [
    { method: "GET", path: "/api/preview/courses" },
    { method: "POST", path: "/api/auth/sign-out" },
  ],
});

Gardez cette liste en lecture seule autant que possible. Les segments dynamiques utilisent :param et doivent avoir le même nombre de segments que la requête.

Autorisation métier

Le middleware établit l'identité, mais les services doivent encore :

Lire l'utilisateur et l'organisation depuis AuthService.
Vérifier l'adhésion ou le rôle requis.
Inclure l'utilisateur ou l'organisation dans chaque filtre de données pertinent.
Retourner Forbidden si l'identité est connue mais insuffisante, et Unauthorized si elle manque.

Ajouter le middleware à l'API#

Fournir la couche#

Exiger une identité#

Témoins et clés API#

Usurpation d'organisation#