Home

Kengela Guide

kokéngela (Lingala) - to watch over, to guard, to stay vigilant. Kengela is a Zero Trust identity & access foundation for multi-tenant TypeScript applications: authentication + authorization + identity federation + compliance, built from pure ports (@kengela/contracts), a vendor-free core, and interchangeable adapters.

This guide covers installing, using, and developing the monorepo. Every code snippet relies on the real signatures of the @kengela/* packages, verified against the source. Each page is self-contained (it also serves as a GitHub wiki page).

🇫🇷 Version française : Guide français (wiki : FR-Accueil). 🇬🇧 You are reading the English version.

Table of contents: the fundamentals

#	Page	Topic
0	Getting started	Install (dual ESM+CJS), compose a first PDP, run an end-to-end check(): allow, deny, step-up.
1	Architecture	The 3 rings, the "a port is an airlock" doctrine, the anti-vendor lint, the Zero Trust decision flow, the Principal bridge.
2	Authorization	Permission grammar, grants & relations, declarative policies (CEL), conditional access, obligations & step-up, decision logs.
3	Authentication	Timing-safe credentials (argon2id / bcrypt + needsRehash), sessions, full MFA/TOTP, better-auth, crypto-shredding.
4	Identity federation	iam-mapping (6 sources → DirectoryProfile), the Kengela SCIM schema, scim-server (discovery + validation + Entra), LDAP.
5	NestJS integration	KengelaAuthzGuard, decorators, the KENGELA_PDP token, StepUpRequiredException, an example module.
6	Compliance & PII	Classification, minimization, redaction, retention, erasure (crypto-shredding), PiiAccessLogSink.
7	Developing an adapter	Add an adapter: implement a port, a NARROW vendor interface, a test fake, DEBT.md, strict conventions, dual build.
8	Security	Zero Trust posture, verified controls, and compliance mapping.

Implementation recipes: "how do I wire Kengela into my app?"

Each recipe is copy-paste, backed by the code's real signatures, and separates what is provided by Kengela from what the application writes itself. Pick the one that matches your identity backend.

Scenario	Recipe
NestJS + native auth (argon2) + Prisma — the recommended default path	Recipe: NestJS + native + Prisma
better-auth as the authentication backend (delegated session)	Recipe: better-auth
SCIM 2.0 provisioning from Microsoft Entra ID (Azure AD)	Recipe: SCIM / Entra
LDAP / Active Directory directory federation	Recipe: LDAP / AD
RBAC + ABAC (CEL) authorization, obligations, step-up, decision logs	Recipe: RBAC/ABAC authorization
GDPR compliance: per-tenant field encryption, crypto-shredding, retention	Recipe: PII / GDPR

Combined recipes (several building blocks together)

Combo	Recipe
better-auth + PII — account delegated to better-auth, field encryption + erasure	Combo: better-auth + PII
SCIM/Entra + authorization — user provisioned from Entra → grants → RBAC/ABAC decision	Combo: SCIM/Entra + authz
Full stack — NestJS + native + Prisma + MFA + authz + PII in a single composition root	Combo: full stack

The 12 packages at a glance

Package	Ring	Role
@kengela/contracts	contracts	Pure ports & types - the project's invariant, zero vendor, zero implementation.
@kengela/authz-core	core	Authorization engine: scoped RBAC + org relation + ABAC (CEL) + step-up; deny-by-default, fail-closed.
@kengela/iam-mapping	core	Normalize 6 IdP sources → DirectoryProfile + canonical SCIM schema + rule engine.
@kengela/pii	core	GDPR compliance: classification, minimization, redaction, retention.
@kengela/adapter-expr-cel	adapter	CEL engine (ABAC conditions + deterministic date functions).
@kengela/adapter-authn-native	adapter	Timing-safe credentials, sessions, MFA/TOTP, AES-256-GCM, field cipher + crypto-shredding.
@kengela/adapter-authn-better-auth	adapter	IdentityPort on top of better-auth (peer dependency).
@kengela/adapter-persistence-prisma	adapter	AuthorizationRepository / SessionStore / PolicyStore / MFA & PII stores via a narrow Prisma interface.
@kengela/adapter-directory-ldap	adapter	AD / LDAP connector (ldapts) → DirectoryProfile.
@kengela/scim-server	adapter	SCIM 2.0 core: Users + Groups + discovery + Entra compliance + validation.
@kengela/nestjs	integration	Deny-by-default guard + decorators + step-up.
@kengela/connector-translog	connector	Maps the TransLog Pro schema onto the Kengela ports (integration reference).

Guiding principles (keep these in mind)

1. Zero Trust: no implicit trust. The decision point (PDP) is deny-by-default, evaluated per request, reloading grants (anti-staleness).
2. Fail-closed: any uncertainty (unevaluable condition, expired session, unresolvable tenant) resolves to a denial, never to access.
3. Multi-tenant isolation at the core: the tenant boundary is checked inside the PDP itself, not blindly delegated to the app.
4. A port is an airlock, not a hideout: the core knows no vendor; each adapter wraps a technology behind a NARROW interface and records its debt in DEBT.md.
5. A la carte composition: an application installs only the packages it uses.

Verify everything

pnpm install
pnpm -r build && pnpm -r test   # TS6 strict, ESLint strictTypeChecked, all green
pnpm lint:arch                  # anti-vendor guardrail on the core (dependency-cruiser)

See also PUBLISHING.md (npm publishing & consumption).