FR Accueil

Guide Kengela

kokéngela (lingala) - veiller, garder, être vigilant. Kengela est un socle identité & accès Zero Trust pour applications multi-tenant en TypeScript : authentification + autorisation + fédération d'identité + conformité, composé de ports purs (@kengela/contracts), d'un cœur sans vendor et d'adapters interchangeables.

Ce guide couvre l'installation, l'utilisation et le développement du monorepo. Tous les extraits de code s'appuient sur les signatures réelles des paquets @kengela/*, vérifiées dans le code source. Chaque page est autonome (elle sert aussi de page de wiki GitHub).

🇬🇧 English version : English guide (wiki : Home). 🇫🇷 Vous lisez la version française.

Table des matières — les fondamentaux

#	Page	Sujet
0	Prise en main	Installer (dual ESM+CJS), composer un premier PDP, exécuter un check() de bout en bout : allow, deny, step-up.
1	Architecture	Les 3 anneaux, la doctrine « le port est un sas », le lint anti-vendor, le flux de décision Zero Trust, le pont Principal.
2	Autorisation	Grammaire des permissions, grants & relations, policies déclaratives (CEL), conditional access, obligations & step-up, decision logs.
3	Authentification	Credential timing-safe (argon2id / bcrypt + needsRehash), sessions, MFA/TOTP complet, better-auth, crypto-shredding.
4	Fédération d'identité	iam-mapping (6 sources → DirectoryProfile), schéma SCIM Kengela, scim-server (découverte + validation + Entra), LDAP.
5	Intégration NestJS	KengelaAuthzGuard, décorateurs, jeton KENGELA_PDP, StepUpRequiredException, module d'exemple.
6	Conformité & PII	Classification, minimisation, redaction, rétention, effacement (crypto-shredding), PiiAccessLogSink.
7	Développer un adapter	Ajouter un adapter : implémenter un port, interface vendor NARROW, fake de test, DEBT.md, conventions strictes, dual build.
8	Sécurité	Posture Zero Trust, contrôles vérifiés et cartographie de conformité.

Recettes d'implémentation — « comment je branche Kengela chez moi »

Chaque recette est copier-coller, adossée aux signatures réelles du code, et distingue ce qui est fourni par Kengela de ce que l'application écrit elle-même. Choisis selon ton backend d'identité.

Scénario	Recette
NestJS + auth native (argon2) + Prisma — le chemin par défaut recommandé	Recette : NestJS + native + Prisma
better-auth comme backend d'authentification (session déléguée)	Recette : better-auth
Provisioning SCIM 2.0 depuis Microsoft Entra ID (Azure AD)	Recette : SCIM / Entra
Fédération annuaire LDAP / Active Directory	Recette : LDAP / AD
Autorisation RBAC + ABAC (CEL), obligations, step-up, decision logs	Recette : autorisation RBAC/ABAC
Conformité RGPD : chiffrement de champ per-tenant, crypto-shredding, rétention	Recette : PII / RGPD

Recettes combinées (plusieurs briques ensemble)

Combo	Recette
better-auth + PII — compte délégué à better-auth, chiffrement de champ + effacement	Combo : better-auth + PII
SCIM/Entra + autorisation — user provisionné depuis Entra → grants → décision RBAC/ABAC	Combo : SCIM/Entra + authz
Full stack — NestJS + native + Prisma + MFA + authz + PII, un seul composition root	Combo : full stack

Les 12 paquets en un coup d'œil

Paquet	Anneau	Rôle
@kengela/contracts	contracts	Ports & types purs - l'invariant du projet, zéro vendor, zéro implémentation.
@kengela/authz-core	core	Moteur d'autorisation : RBAC scopé + relation org + ABAC (CEL) + step-up ; deny-by-default, fail-closed.
@kengela/iam-mapping	core	Normalisation 6 sources IdP → DirectoryProfile + schéma SCIM canonique + moteur de règles.
@kengela/pii	core	Conformité RGPD : classification, minimisation, redaction, rétention.
@kengela/adapter-expr-cel	adapter	Moteur CEL (conditions ABAC + fonctions de dates déterministes).
@kengela/adapter-authn-native	adapter	Credential timing-safe, sessions, MFA/TOTP, AES-256-GCM, field cipher + crypto-shredding.
@kengela/adapter-authn-better-auth	adapter	IdentityPort au-dessus de better-auth (peer dependency).
@kengela/adapter-persistence-prisma	adapter	AuthorizationRepository / SessionStore / PolicyStore / stores MFA via une interface Prisma narrow.
@kengela/adapter-directory-ldap	adapter	Connecteur AD / LDAP (ldapts) → DirectoryProfile.
@kengela/scim-server	adapter	Cœur SCIM 2.0 Users + Groups + découverte + conformité Entra + validation.
@kengela/nestjs	intégration	Guard deny-by-default + décorateurs + step-up.
@kengela/connector-translog	connecteur	Mapping du schéma TransLog Pro vers les ports Kengela (référence d'intégration).

Principes directeurs (à garder en tête)

1. Zero Trust : aucune confiance par défaut. Le point de décision (PDP) est deny-by-default, évalué par requête, avec rechargement des droits (anti-staleness).
2. Fail-closed : la moindre incertitude (condition inévaluable, session expirée, tenant non résoluble) se résout en refus, jamais en accès.
3. Isolation multi-tenant au cœur : la frontière tenant est vérifiée dans le PDP lui-même, pas déléguée aveuglément à l'app.
4. Le port est un sas, pas une planque : le cœur ne connaît aucun vendor ; chaque adapter enveloppe une techno derrière une interface NARROW, et trace sa dette dans DEBT.md.
5. Composition à la carte : une application n'installe que les paquets qu'elle utilise.

Vérifier l'ensemble

pnpm install
pnpm -r build && pnpm -r test   # TS6 strict, ESLint strictTypeChecked, tout vert
pnpm lint:arch                  # garde-fou anti-vendor sur le cœur (dependency-cruiser)

Voir aussi PUBLISHING.md (publication & consommation npm).