kyzen | Kyzen | Primitives Docs
Primitives

kyzen

The Koze quickstart auth library — credentials, sessions, RBAC, OAuth, rate-limiting, Turnstile

A starter, not a standard

kyzen is the Koze quickstart auth library. It gets you to "users can sign in" fast — credentials, sessions, role-based permissions, rate limiting, OAuth, Turnstile bot protection — driven by a single config object passed to a middleware factory.

It's a starter, not a standard. The framework has no built-in auth; kyzen plugs in via ordinary middleware, the same shape any other auth library would use. If you outgrow it (federated identity, complex authorization graphs, custom session backends), swap it out — nothing else in your app cares.

What it gives you

  • Credentials and sessions: Email and password signup, signin, signout, session cookies, current-user lookup, and password reset flows.
  • Magic links: Passwordless email sign-in with Cloudflare Email Service or your own sender callback, plus session creation on link consume.
  • Auth context: Use getAuth() for lazy session access, role checks, cookie helpers, redirects, and auth-aware JSON responses.
  • OAuth and RBAC: Configure GitHub or Google login, define roles, and check permissions with wildcard support.
  • Runtime controls: Protect routes, throttle requests, and require Turnstile verification before route handlers run.

Not the same as Cloudflare Access

kyzen answers "is this app user signed in?" — verified against your D1 database via session cookies.

Cloudflare Access answers "is this user from my org?" — verified at the edge against your IdP, surfaced as a JWT in cf-access-jwt-assertion.

The two compose orthogonally. An admin panel can require both: Access at the edge for org employees + kyzen for any other identity surface. Either, neither, or both — all valid.

See Cloudflare Access for the framework primitive.

Package model

The package is split into focused runtime modules:

  • credentials and sessions
  • magic-link sign-in
  • low-level auth context
  • activity logging
  • OAuth providers
  • guards
  • rate limiting
  • Turnstile verification
  • organization-aware multi-tenancy

When to swap this out

Reasonable signals to outgrow kyzen:

  • You need WebAuthn / passkeys.
  • You need federated identity beyond the included OAuth providers (e.g. SAML, OIDC against arbitrary providers).
  • You want sessions in something other than D1 (Redis, JWT, KV).
  • You need fine-grained permission graphs beyond role → permission lists.
  • You need MFA, non-email magic links, or device-based session pinning.
  • Your team prefers a battle-tested third-party for security-critical surface area.

When that day comes: replace the kyzenAuthMiddleware step with whatever you're swapping to, drop kyzen from your deps, and the rest of your app keeps working. That's the point of middleware-only integration — it's the same kind of seam Express / Hono / Next.js give you.