Introduction

Keyloom is a framework‑agnostic authentication and authorization framework for TypeScript. It focuses on clean primitives, strong typing, and an excellent DX while staying unopinionated about your runtime and data layer. Use it in modern TypeScript apps with a minimal core, an ergonomic Next.js integration, and a growing set of adapters and providers.

• TypeScript first: strongly‑typed config and helpers
• Framework agnostic core: bring your own runtime; plug in integrations when you need them
• Minimal surface area: focus on auth flows and policies; keep your app code simple

Why Keyloom?

Most auth libraries either lock you into one stack or hide critical details behind magic. Keyloom takes a different approach:

• Pluggable by design: adapters for your database layer (Prisma, Drizzle, SQL/NoSQL) and providers for OAuth (GitHub, Google, Discord, …)
• Clear separation of concerns: configuration lives in keyloom.config.ts, middleware and helpers live in thin, testable modules
• Route‑level visibility rules: declare public/private/role‑gated visibility and let the middleware enforce it
• DX without surprises: consistent TypeScript APIs, minimal boilerplate, and a CLI that scaffolds what you need

If you want a modern, security‑minded auth system that fits your stack instead of forcing you to fit it, Keyloom is for you.

Features

Core Architecture

• TypeScript‑first core (@keyloom/core) with a simple, declarative config: keyloom.config.ts
• Framework‑agnostic design with dedicated packages for platform integrations (e.g. @keyloom/nextjs)
• Pluggable Adapters (@keyloom/adapters):
  • Prisma (first‑class template), Drizzle
  • SQL drivers: pg, mysql2
  • Mongo
  • Custom adapters supported
• OAuth Providers (@keyloom/providers): GitHub, Google, Discord (and extensible)

Sessions

• Strategies: database or jwt
• TTL and rolling sessions: ttlMinutes, rolling
• Cookie controls: sameSite, secure defaults; configurable for your environment

Authorization & RBAC

• Built‑in role‑based access control: enable with rbac: { enabled: true }
• Express roles inline or via config; combine with route visibility for fine‑grained control

Route‑Level Visibility (Next.js)

• Middleware integrates with a route manifest to enforce:
  • public
  • private (aka !public)
  • role‑gated rules (role:admin, etc.)
• Legacy publicRoutes support for simple setups
• Optional “verify at edge” mode for stricter session checks

Next.js Integration (@keyloom/nextjs)

• Drop‑in middleware (createAuthMiddleware) for App Router
• Works with route manifests generated by the Keyloom CLI (planned/under development)
• Edge‑safe config option (no Node APIs in middleware config)

Example: Minimal Config + Middleware

import { defineKeyloom } from "@keyloom/core";
import { memoryAdapter } from "@keyloom/core";
// In production, use PrismaAdapter / your DB adapter

export default defineKeyloom({
  baseUrl: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
  session: { strategy: "database", ttlMinutes: 60, rolling: true },
  adapter: memoryAdapter(),
  providers: [],
  rbac: { enabled: false },
  cookie: { sameSite: "lax" },
  secrets: { authSecret: process.env.AUTH_SECRET ?? "dev-secret" },
});

import { createAuthMiddleware } from "@keyloom/nextjs/middleware";
import config from "@/keyloom.config";

export default createAuthMiddleware(config, {
  publicRoutes: ["/", "/sign-in"],
  // verifyAtEdge: false,
  // routes: compiledManifest, // when using declarative route visibility
});

export const config = {
  matcher: ["/((?!_next|.*\\.(?:ico|png|jpg|svg|css|js|map)).*)"],
};

CLI & Scaffolding (@keyloom/cli)

• keyloom init project setup
• Detects package manager, Next.js, router
• Scaffolds keyloom.config.ts, middleware, and provider/adapter wiring
• Templates for Prisma/Drizzle and common OAuth providers

Security‑minded Defaults

• Sensible cookie and session defaults
• Encourages edge‑safe middleware configuration
• Clear separation between runtime config and secret management

Developer Experience

• Strong TypeScript types across config and middleware
• Explicit, readable code paths; minimal magic
• Works with your existing build and testing tools

LLMs.txt

This documentation is AI‑friendly:

• Entire documentation as plain text: /llms-full.txt
• Per‑page MDX/Markdown by appending .mdx to the page URL (rewrite to /llms.mdx/:path*)

Access the documentation at:

• Full documentation: https://keyloom.markdegraaff.com/llms-full.txt
• Individual pages: https://keyloom.markdegraaff.com/docs/[page-path].mdx

If you’re integrating an AI assistant or RAG pipeline, start by fetching /llms-full.txt, or fetch specific pages with the .mdx suffix.