Krate Docs

#Authentication

Sign-in with OAuth, passwords, magic links, passkeys and two-factor authentication, configured from krate.config.

@krate/auth adds sign-in to a Krate app. It follows the model of NextAuth (Auth.js): a defineAuth() instance, provider objects, callbacks, adapters, and a handler that serves /api/auth/*. It also ships what NextAuth leaves to plugins: two-factor authentication, passkeys, route protection driven by config, and a browser client.

  • 56 built-in OAuth and OpenID Connect providers, plus a generic provider for any other.
  • Credentials, email magic links and Resend.
  • JWT sessions (encrypted, stored in a cookie) or database sessions.
  • Drizzle adapter for SQLite, PostgreSQL and MySQL.
  • TOTP two-factor authentication with backup codes.
  • Passkeys (WebAuthn) with ES256, EdDSA and RS256.
  • Runs in Krate's embedded runtime, so API routes and middleware need no Node.js process.

#Quick start

npm install @krate/auth

Declare the parts that are data in krate.config.ts:

import { defineConfig } from "@krate/core";

export default defineConfig({
  auth: {
    providers: [{ id: "github" }, { id: "google" }],
    pages: { signIn: "/login" },
    protect: [{ source: "/dashboard" }],
  },
});

Create the instance in code. This is where callbacks, adapters and credentials logic live:

import { defineAuth } from "@krate/auth";

export const auth = defineAuth({});

Mount the handler as one catch-all API route:

import { auth } from "../../auth";

export const GET = auth.handlers.GET;
export const POST = auth.handlers.POST;

Save that as src/api/auth/[...all].ts, and the instance above as src/auth.ts. Protect pages with middleware:

import { auth } from "./src/auth";

export function middleware(request: Request) {
  return auth.middleware(request);
}

Set the secret and the provider credentials in .env:

AUTH_SECRET=<output of: openssl rand -base64 33>
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=

Register http://localhost:3000/api/auth/callback/github (and the same path for each provider) as the OAuth redirect URI. Visit /api/auth/signin for the built-in sign-in page, or build your own and use the browser client.

#Configuration

Everything that is plain data goes in the auth key of krate.config.ts. The compiler validates it (unknown keys are warned about, invalid values fail the build) and delivers it to your API routes and middleware. Anything that needs a function stays in defineAuth(). When both set the same option, the code wins. Lists such as protect are merged.

Key Default Description
enabled true when something is configured Set false to turn the handlers and middleware off
basePath "/api/auth" Where the handler is mounted
trustHost false Trust the request host. Needed in production unless AUTH_URL is set
debug false Log debug messages
providers [] { id, type?, name?, enabled?, options? }, see Providers
session.strategy "jwt", or "database" when an adapter is set Where the session lives
session.maxAge 30 days Seconds a session stays valid
session.updateAge 1 day Seconds between session refreshes
pages built-in pages signIn, signOut, error, verifyRequest, newUser, twoFactor
cookies secure on https prefix, secure, sameSite, domain
adapter.dialect none "sqlite", "postgres" or "mysql"
adapter.tables user, account, ... Rename tables: users, accounts, sessions, verificationTokens, authenticators, twoFactors
twoFactor off See Two-factor authentication
passkeys off See Passkeys
protect [] See Protecting routes
rateLimit 20 per 60 seconds enabled, max, window (seconds)
redirects none signedIn, signedOut, allowed (extra origins callback URLs may use)
linking.automatic false Link a provider account to an existing user with the same email

Secrets never belong in config. A provider option named clientSecret, secret, password, apiKey, privateKey or token fails the build with a hint to use an environment variable instead, because config values are compiled into the server bundle.

session.strategy: "database", twoFactor.enabled and passkeys.enabled all need adapter.dialect, and the build says so when it is missing. The dialect in config only declares intent and names the tables. The adapter itself is created in code, as shown below.

#Environment variables

Variable Purpose
AUTH_SECRET Required. Encrypts sessions and signs state. A list is accepted in code for rotation
AUTH_URL Public URL of the app. Set it in production
AUTH_TRUST_HOST true to trust the request host (behind a proxy you control)
AUTH_<PROVIDER>_ID OAuth client id, for example AUTH_GITHUB_ID
AUTH_<PROVIDER>_SECRET OAuth client secret
AUTH_<PROVIDER>_ISSUER Issuer or base URL for providers that need one
AUTH_RESEND_KEY API key for the Resend provider
AUTH_DEBUG true to log debug messages

NEXTAUTH_SECRET and NEXTAUTH_URL are read as fallbacks, and the older <PROVIDER>_CLIENT_ID and <PROVIDER>_CLIENT_SECRET names work as well.

#Providers

Declare a built-in provider by id. Its credentials come from the environment:

auth: {
  providers: [
    { id: "github" },
    { id: "google", options: { scope: "openid email profile" } },
    { id: "okta", name: "Company SSO" },
  ],
}

Built-in ids: 42-school, apple, asgardeo, atlassian, auth0, authentik, azure-ad-b2c, bitbucket, box, cognito, coinbase, descope, discord, dribbble, dropbox, duende-identityserver6, facebook, fusionauth, github, gitlab, google, hubspot, huggingface, kakao, keycloak, kinde, line, linkedin, logto, mastodon, mattermost, microsoft-entra-id, naver, netlify, notion, okta, onelogin, orcid, osu, patreon, pinterest, reddit, roblox, salesforce, slack, spotify, strava, twitch, twitter, webex, wikimedia, workos, yandex, zitadel, zoho and zoom.

Providers that run on your own tenant or instance take their issuer from AUTH_<PROVIDER>_ISSUER (Auth0, Okta, Keycloak, Cognito, Authentik, GitLab self-hosted, Mastodon, Mattermost and similar). Microsoft Entra ID reads options.tenantId and defaults to the multi-tenant endpoint.

The same providers are exported as functions when you want code-level control:

import { defineAuth, github, google } from "@krate/auth";

export const auth = defineAuth({
  providers: [
    github({ allowDangerousEmailAccountLinking: false }),
    google({ clientId: process.env.GOOGLE_ID, clientSecret: process.env.GOOGLE_SECRET }),
  ],
});

#Any other OAuth or OpenID Connect service

auth: {
  providers: [
    { id: "acme", type: "oidc", options: { issuer: "https://sso.acme.example" } },
    {
      id: "legacy",
      type: "oauth",
      options: {
        authorization: "https://legacy.example/oauth/authorize",
        token: "https://legacy.example/oauth/token",
        userinfo: "https://legacy.example/api/me",
        scope: "profile email",
      },
    },
  ],
}

Use genericOAuth() in code when you need a profile function to map the provider's response to a user.

Authorization uses the code flow with PKCE and a state cookie, and a nonce for OpenID Connect. The ID token's issuer, audience, expiry and nonce are validated. Its signature is not, because the token is received directly from the token endpoint over TLS (OpenID Connect Core, section 3.1.3.7).

#Sign in with Apple

Apple wants a client secret that is a short-lived JWT. Generate it from the .p8 key:

import { apple, appleClientSecret } from "@krate/auth";

const clientSecret = appleClientSecret({
  teamId: process.env.APPLE_TEAM_ID!,
  keyId: process.env.APPLE_KEY_ID!,
  clientId: process.env.AUTH_APPLE_ID!,
  privateKey: process.env.APPLE_PRIVATE_KEY!,
});

export const auth = defineAuth({ providers: [apple({ clientSecret })] });

The secret is valid for up to six months, so regenerate it when the app starts rather than storing it.

#Credentials

Checking a password is your code, so credentials providers are declared in defineAuth():

import { defineAuth, credentials } from "@krate/auth";
import { verifyPassword } from "./lib/passwords";
import { findUserByEmail } from "../db/queries/users";

export const auth = defineAuth({
  providers: [
    credentials({
      async authorize({ email, password }) {
        const user = await findUserByEmail(email);
        if (!user || !(await verifyPassword(password, user.passwordHash))) return null;
        return { id: user.id, name: user.name, email: user.email };
      },
    }),
  ],
});

Return null for a failed sign-in. Do not say which half was wrong. Failed attempts are rate limited per client address and per email.

The email provider needs an adapter, because the one-time token is stored hashed in the verification token table:

import { defineAuth, resend } from "@krate/auth";

export const auth = defineAuth({
  adapter,
  providers: [resend({ from: "App <login@example.com>" })],
});

resend() reads AUTH_RESEND_KEY. For another service use email({ sendVerificationRequest }) and send the url you are given. Links expire after 24 hours (maxAge) and work once. Addresses are trimmed and lowercased.

#Sessions

With the JWT strategy the session is an encrypted token (AES-256-GCM, key derived from AUTH_SECRET) in an HttpOnly cookie, split across cookies when it grows past 4 KB. With the database strategy the cookie holds an opaque id and the row lives in your database.

Read the session on the server:

import { auth } from "../auth";

export async function GET(request: Request) {
  const session = await auth.auth(request);
  if (!session) return Response.json({ error: "unauthorized" }, { status: 401 });
  return Response.json({ id: session.user.id, email: session.user.email });
}

In a server component, a server action or a route handler, call auth() with no argument: it reads the session of the request being served, like Auth.js auth(). In a server action or a route handler it also refreshes a database session cookie that is due. The auth.auth(request) form keeps working everywhere else (API routes on the embedded runtime that receive a Request, middleware).

import { auth } from "../auth";

export default async function Account() {
  const session = await auth.auth();
  if (!session) return <a href="/signin">Sign in</a>;
  return <p>{session.user.email}</p>;
}

The session has the shape { user: { id, name, email, image, role?, twoFactorEnabled? }, expires }. Add your own fields with callbacks:

export const auth = defineAuth({
  callbacks: {
    jwt({ token, user }) {
      if (user) token.plan = user.plan;
      return token;
    },
    session({ session, token }) {
      return { ...session, plan: token?.plan };
    },
  },
});
Callback Use
signIn({ user, account, profile }) Return false to deny, or a path to redirect to
redirect({ url, baseUrl }) Control where users land after sign-in or sign-out
jwt({ token, user, account, trigger }) Add claims. trigger is "signIn", "signUp" or "update"
session({ session, token, user }) Shape what auth() and /api/auth/session return
authorized({ request, auth }) Decide per request in middleware

Events (signIn, signOut, createUser, updateUser, linkAccount, session, twoFactorEnabled, twoFactorDisabled, passkeyRegistered) are passed to events for side effects such as audit logs.

#Signing in and out on the server

auth.signIn(provider, { redirectTo }) and auth.signOut({ redirectTo }) run the same flow as the CSRF-protected POST /api/auth/signin/:provider and POST /api/auth/signout, from a server action or a route handler (the server action origin check replaces the CSRF token). They set the same cookies, then redirect: an OAuth sign-in redirects to the provider, a sign-out clears the session cookie and redirects to redirectTo.

// src/api/signin/discord.ts
import { auth } from "../../auth";

export async function GET() {
  await auth.signIn("discord", { redirectTo: "/dashboard" });
}
function SignOutButton() {
  async function signOutAction() {
    "use server";
    await auth.signOut({ redirectTo: "/" });
  }
  return <form action={signOutAction}><button>Sign out</button></form>;
}
  • Both throw Krate's redirect signal, so code after the await does not run. Pass redirect: false to get the target URL back instead.
  • signIn() also takes the credentials or email fields (signIn("credentials", { email, password, redirectTo })) and, as a third argument, extra authorization parameters ({ prompt: "consent" }).
  • A call with no provider redirects to pages.signIn.
  • They need the request scope Krate sets up for server actions and route handlers on the Node and embedded runtimes; a server component can only read (auth()). Elsewhere, pass nothing and use the browser client.
  • A server action may redirect to an absolute URL this way (the provider). A redirect a server action only returns ({ redirect }) must still be a path of your site.

callbacks.signIn runs after the user and account rows exist (Auth.js runs it first), so a denied sign-in leaves the row behind and creates no session.

#Database adapter

import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";
import { DrizzleAdapter, createSqliteSchema } from "@krate/auth/drizzle";

export const schema = createSqliteSchema();
export const db = drizzle(createClient({ url: process.env.DATABASE_URL! }));
export const adapter = DrizzleAdapter(db, schema);

Pass adapter to defineAuth({ adapter }). Use createPgSchema() with a drizzle-orm/node-postgres or PGlite client for PostgreSQL, and createMysqlSchema() for MySQL. The adapter is tested against SQLite (libsql) and PostgreSQL (PGlite). The MySQL schema and DDL are generated and checked, but the suite has no live MySQL server, so try it against yours before relying on it.

Export the tables from your schema file so drizzle-kit includes them in migrations:

import { createSqliteSchema } from "@krate/auth/drizzle/sqlite";

export const { users, accounts, sessions, verificationTokens, authenticators, twoFactors } =
  createSqliteSchema();

For quick starts and tests, authTablesSql(dialect) from @krate/auth/drizzle/ddl returns CREATE TABLE IF NOT EXISTS statements. MemoryAdapter() from @krate/auth/memory keeps everything in memory for development.

If you rename tables with auth.adapter.tables, the schema factories read the names while running under Krate. Tools that run outside Krate, such as drizzle-kit, do not see your config, so pass the same names to the factory: createSqliteSchema({ users: "app_users" }).

Emails are stored lowercased. A provider account is unique on (provider, providerAccountId).

#Account linking

If a user signs in with a provider whose email already belongs to another account, sign-in fails with OAuthAccountNotLinked. This stops someone from taking over an account through a provider that does not verify emails. Set linking.automatic or a provider's allowDangerousEmailAccountLinking only for providers that do verify them. A user who is already signed in can link another provider by signing in with it.

#Protecting routes

List rules in config and call auth.middleware. Patterns match a path and everything below it:

auth: {
  protect: [
    { source: "/admin", roles: ["admin"], status: 404 },
    { source: "/api/private", status: 401 },
    { source: "/account", redirect: "/login" },
    { source: "/dashboard" },
  ],
}
Pattern Matches
/dashboard /dashboard and everything below it
/users/:id One segment, and below
/users/* Exactly one segment
/docs/** or /docs/:path* Any depth
/files/:rest+ At least one more segment

The first matching rule wins. Anonymous users get a redirect to the sign-in page with callbackUrl for pages, or 401 for API requests and requests that accept JSON. redirect sends them to a specific page, and status answers with 401, 403 or 404 instead. roles compares against session.user.role and answers 403 (or 404) when it does not match. The auth routes themselves are never blocked.

For logic that does not fit a rule, use the authorized callback. It runs for every request the middleware sees:

export const auth = defineAuth({
  callbacks: {
    authorized({ request, auth }) {
      if (new URL(request.url).pathname.startsWith("/members")) return Boolean(auth);
      return true;
    },
  },
});

Return true to allow, false to send the user to sign in, or a Response. Middleware fails closed: if the session cannot be read it answers 503. With database sessions the adapter is called from middleware, so run middleware on a runtime where your database driver works. See Middleware.

#Two-factor authentication

Enable it in config and create the adapter with two-factor storage (the Drizzle adapter has it):

auth: {
  adapter: { dialect: "sqlite" },
  twoFactor: { enabled: true, issuer: "My App" },
}

Users enrol while signed in:

Request Result
POST /api/auth/2fa/setup A new secret and an otpauth:// URL to show as a QR code
POST /api/auth/2fa/enable with { code } Confirms the code, returns 10 backup codes once
GET /api/auth/2fa/status { enabled, pending, backupCodesRemaining, required }
POST /api/auth/2fa/backup-codes with { code } Replaces the backup codes. Needs a current app code
POST /api/auth/2fa/disable with { code } Turns it off. Accepts an app code or a backup code

After enrolment, every sign-in method (credentials, OAuth, magic links) stops short of creating a session and redirects to /api/auth/2fa, or to pages.twoFactor. The user submits an app code or a backup code to POST /api/auth/2fa/verify, and only then receives the session. A sign-in that used a user-verified passkey counts as two factors and skips the challenge.

Details that matter:

  • Codes are RFC 6238 TOTP (SHA-1, 6 digits, 30 seconds by default; SHA-256 and SHA-512 are available). The window accepts one step either side.
  • A code is accepted once. The last used step is stored, so a code that was just used cannot be replayed.
  • The shared secret is encrypted at rest with a key derived from AUTH_SECRET. Changing the secret without keeping the old one in the rotation list makes enrolled secrets unreadable.
  • Backup codes are stored as salted hashes and each works once.
  • Verification attempts are limited to 5 per window for each user.
  • With twoFactor.required, signed-in users who have not enrolled get session.user.twoFactorSetupRequired: true. Enforce it in the authorized callback or in your UI.

#Passkeys

auth: {
  adapter: { dialect: "sqlite" },
  passkeys: { enabled: true, rpName: "My App" },
}

Passkeys can create an account, sign a user in without a username (discoverable credentials), and be added to an existing account. Defaults are userVerification: "preferred", residentKey: "required" and a 60 second timeout. rpId defaults to the host name, and origins lists extra origins allowed to run the ceremony (for example a separate front end).

Request Purpose
POST /api/auth/passkey/register/options Start registration. Signed in: adds a passkey. Anonymous: creates an account (email, name optional)
POST /api/auth/passkey/register/verify Finish registration with the browser's credential
POST /api/auth/passkey/authenticate/options Start a sign-in
POST /api/auth/passkey/authenticate/verify Finish a sign-in
GET /api/auth/passkey/list The signed-in user's passkeys
POST /api/auth/passkey/delete with { credentialID } Remove one of their own passkeys

The server verifies the challenge, origin, relying party hash, user presence, user verification when required, and the signature. The signature counter must increase, which detects cloned authenticators. Each challenge is stored once and consumed on use, so a captured request cannot be replayed.

Known limits: attestation statements are not verified (the server records the format and trusts the credential, which is how sign-in passkeys are normally used), and an anonymous registration for an email that already has an account answers 409 so the person signs in and adds the passkey from their account.

#Browser client

import { signIn, signOut, getSession, twoFactor, registerPasskey, signInWithPasskey } from "@krate/auth/client";

await signIn("github", { callbackUrl: "/dashboard" });
await signIn("credentials", { email, password, redirect: false });
await signInWithPasskey();
await registerPasskey({ passkeyName: "Laptop" });

const challenge = await signIn("credentials", { email, password });
if (challenge.twoFactorRequired) await twoFactor.verify(code);

await signOut();

signIn returns { ok, error, url, twoFactorRequired } and navigates to the result unless you pass redirect: false. The client also exposes getSession, getCsrfToken, getProviders, updateSession, twoFactor.{status,setup,enable,disable,regenerateBackupCodes,verify}, listPasskeys, deletePasskey and isPasskeySupported. Call configureAuthClient({ basePath }) if you changed the mount path.

#Endpoints

Method and path Purpose
GET /providers Configured providers
GET /csrf CSRF token, also sets its cookie
GET /session, POST /session Read the session, or update it with { data }
GET /signin, POST /signin/:provider Sign-in page, or start an OAuth or email sign-in
GET /callback/:provider OAuth and magic link return
POST /callback/credentials Credentials sign-in
GET /signout, POST /signout Confirmation page, or sign out
GET /error, GET /verify-request Built-in status pages
/2fa/*, /passkey/* See above

All paths are relative to basePath. Requests that send a JSON body, an Accept: application/json header or X-Auth-Return-Redirect: 1 get JSON ({ url } instead of a redirect, { error } instead of an error page).

#Security notes

  • Every state-changing request needs the CSRF token (cookie plus matching field or X-CSRF-Token header) and, when an Origin header is present, a same-origin value.
  • Callback URLs must be relative or on the app's own origin (or listed in redirects.allowed). Anything else falls back to the home page.
  • Sign-in, verification and ceremony endpoints are rate limited. The counters live in each worker's memory, so run behind a proxy rate limit as well for a multi-instance deployment.
  • In production, set AUTH_URL or trustHost. Without one the handler refuses to guess its own origin.
  • Cookies are HttpOnly, SameSite=Lax, and use the __Secure- and __Host- prefixes on https.
  • Session and state tokens are encrypted, bound to the cookie they belong to, and rejected after maxAge. List more than one secret in code to rotate.

#Coming from NextAuth

NextAuth Krate
NextAuth({ ... }) in auth.ts defineAuth({ ... }), with data options in krate.config.ts
export const { handlers, auth, signIn, signOut } = NextAuth(...) The same line with defineAuth(...): handlers, auth(), signIn() and signOut() keep their names and work in server components, actions and route handlers. defineAuth also takes a function that returns the options, evaluated on first use
next-auth/providers/discord discord from @krate/auth. A provider listed without being called (providers: [GitHub]) works as in Auth.js
next-auth/react @krate/auth/client: signIn, signOut, getSession, getCsrfToken, getProviders. useSession and SessionProvider have no equivalent
app/api/auth/[...nextauth]/route.ts src/api/auth/[...all].ts
middleware.ts with export { auth as middleware } export function middleware(request) { return auth.middleware(request); }
@auth/drizzle-adapter DrizzleAdapter(db, createSqliteSchema())
AUTH_SECRET, AUTH_GITHUB_ID The same names
callbacks, events, pages, session The same shapes
Auth.js cookie names (authjs.session-token, __Secure-authjs.session-token, __Host-authjs.csrf-token, authjs.callback-url, authjs.pkce.code_verifier, authjs.state) cookies: { prefix: "authjs" } produces exactly these names. Without it the prefix is krate-auth
cookies: { sessionToken: { name } } per-cookie overrides, theme, useSecureCookies Not supported. Use cookies.prefix and cookies.secure
Discord issuer: "https://discord.com" Supported: Discord stays plain OAuth and the RFC 9207 iss callback parameter is checked against the issuer when both are present

krate migrate nextjs does this port for you, see Migrating from Next.js. Keep @auth/drizzle-adapter when your tables already exist: it implements the Adapter interface defineAuth expects, and with cookies.prefix: "authjs" existing database sessions keep working.

Differences to know: with the JWT strategy the session token is an encrypted JWT like NextAuth's, but not byte-compatible, so existing JWT sessions end when you switch. The database tables are named like the Auth.js ones with authenticators for passkeys and twoFactors added, and users gains role and twoFactorEnabled.

Last updated: 2026-11-17

Contributors: Noinkin