Better Auth

Better Auth is an open-source TypeScript authentication library that runs inside your app and keeps users in your own database. Behind auth, it gives you sign-in with no hosted identity service to sign up for. Pick it when you want users in your own Postgres and no third-party user directory. The auth spec proposes Better Auth and Clerk as the two drivers that make auth stable in 0.3.

auth:
  driver: better-auth

Before you start

There is no account to create; you run Better Auth yourself.

1. Pick the database that holds users and sessions, such as your Postgres, and apply Better Auth's schema to it.
2. Generate a long random secret that Better Auth uses to sign and encrypt its tokens, one per environment.
3. Register any social providers you offer, such as a GitHub OAuth app, and keep their client secrets.

Configure

auth:
  driver: better-auth
  methods: [passkeys]
  # [to be decided] key names; suggested secrets: BETTER_AUTH_SECRET and the users database connection

The auth spec does not define the driver's credential keys yet; they take secret: references when it does.

Use it

import { auth } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);   // 401 with MAIN-AUTH-0001 if not signed in
  return Response.json(session.user);
}

Local development and testing

Use the local auth driver in development, or run Better Auth against a local database. In tests, createTestApp() from @mainsdk/testing puts auth on its in-memory fake, and chaos.on("auth", { outage: true }) checks that auth.require() fails closed.

What MainSDK adds on top

• Short-lived, HttpOnly, Secure, SameSite sessions with rotating refresh tokens.
• Passkeys by default, phishing-resistant.
• Fails closed when the driver cannot reach its store.
• Every recovery audited, never weaker than sign-in.

See Sign-in and sessions.

Limits and notes

• Users live in your database, so their residency follows where you host it; MainSDK's regions are US, EU and India.
• The Better Auth driver is in the auth spec's first driver ticket with Clerk, held to the auth conformance suite.
• auth.raw() returns the library's instance for features auth does not wrap; mainsdk check lists every use.

Swap to or from it

auth:
  driver: clerk   # was better-auth

FAQ

Do I need a Better Auth account? No. It is a library; you need a database and a secret.

Can I keep my existing Better Auth setup? Yes. The driver runs on your existing tables (byo-identity).

Next

• Sign-in and sessions
• Clerk, GitHub and Postgres
• Swap a driver