Authentication with Better Auth

pnpm add better-auth @prisma/client @prisma/adapter-libsql @libsql/client
pnpm add -D prisma

import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: { path: "prisma/migrations" },
  datasource: { url: process.env.DATABASE_URL ?? "file:./data/auth.db" },
});

generator client {
  provider = "prisma-client"
  output   = "../src/server/generated/prisma"
}

datasource db {
  provider = "sqlite"
}

model User {
  id            String    @id
  name          String
  email         String
  emailVerified Boolean   @default(false)
  image         String?
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  sessions      Session[]
  accounts      Account[]

  @@unique([email])
  @@map("user")
}

// Session, Account and Verification: see the sample's schema.

{
  "scripts": {
    "dev": "lumiose typegen && prisma generate && prisma migrate deploy && lumiose dev",
    "build": "lumiose typegen && prisma generate && lumiose build",
    "typecheck": "lumiose typegen && prisma generate && lumiose check",
    "db:migrate": "prisma migrate deploy"
  }
}

// src/server/db.server.ts
import { PrismaLibSql } from "@prisma/adapter-libsql";
import { env } from "lumiose";
import { PrismaClient } from "./generated/prisma/client.ts";

let client: PrismaClient | undefined;

export function prisma(): PrismaClient {
  client ??= new PrismaClient({
    adapter: new PrismaLibSql({ url: env("DATABASE_URL") ?? "file:./data/auth.db" }),
  });
  return client;
}

// src/server/auth.server.ts
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { env, href, locals, redirect, url, type RequestContext } from "lumiose";
import { forwardedFor, parseTrustedProxies } from "./client-address.server.ts";
import { prisma } from "./db.server.ts";

function createAuth(trustedProxies: string[]) {
  return betterAuth({
    secret: env("BETTER_AUTH_SECRET"),
    baseURL: env("BETTER_AUTH_URL"),
    database: prismaAdapter(prisma(), { provider: "sqlite" }),
    emailAndPassword: { enabled: true },
    // The rate limiter (on in production) keys requests by client address.
    advanced: { ipAddress: { trustedProxies } },
  });
}

let instance: { auth: ReturnType<typeof createAuth>; trustedProxies: string[] } | undefined;

function setup() {
  if (instance === undefined) {
    const trustedProxies = parseTrustedProxies(env("TRUSTED_PROXIES"));
    instance = { auth: createAuth(trustedProxies), trustedProxies };
  }
  return instance;
}

export function auth(): ReturnType<typeof createAuth> {
  return setup().auth;
}

/** `{ user, session }` of a signed-in request. */
export type AuthSession = ReturnType<typeof createAuth>["$Infer"]["Session"];

declare module "lumiose" {
  interface Locals {
    /** Set by src/middleware.ts: the signed-in user and session, or `null`. */
    session: AuthSession | null;
  }
}

/** The session of a page that needs one; without one, redirects to the sign-in page and back. */
export function requireSession(): AuthSession {
  const session = locals().session;
  if (session === null) {
    const { pathname, search } = url();
    redirect(`${href("/sign-in")}?next=${encodeURIComponent(pathname + search)}`);
  }
  return session;
}

/** `next` when it is a path on this site, else `fallback`: never a redirect to another site. */
export function safeNext(next: string | null, fallback: string = href("/dashboard")): string {
  return next !== null && /^\/(?![/\\])/.test(next) ? next : fallback;
}

// authHandler(), authRequest(), authError() and redirectWithCookies(): below.

// src/server/client-address.server.ts
/** `X-Forwarded-For` to hand to Better Auth, or `undefined` when the host knows no address. */
export function forwardedFor(
  headers: Headers,
  clientAddress: string | undefined,
  trustedProxies: readonly string[],
): string | undefined {
  // Without trusted proxies, the client's own X-Forwarded-For is ignored: it could pick any address.
  const chain = trustedProxies.length > 0 ? headers.get("x-forwarded-for") : null;
  const hops = [chain, clientAddress].filter((hop): hop is string => hop != null && hop !== "");
  return hops.length === 0 ? undefined : hops.join(", ");
}

// src/server/auth.server.ts, continued
type AuthContext = Pick<RequestContext, "request" | "url" | "platform">;

function clientHeaders(ctx: AuthContext, headers: Headers): Headers {
  const { trustedProxies } = setup();
  const forwarded = forwardedFor(ctx.request.headers, ctx.platform.clientAddress, trustedProxies);
  if (forwarded === undefined) headers.delete("x-forwarded-for");
  else headers.set("x-forwarded-for", forwarded);
  return headers;
}

/** Better Auth's HTTP API for a request, with the client's address for its rate limiter. */
export function authHandler(ctx: AuthContext): Promise<Response> {
  const headers = clientHeaders(ctx, new Headers(ctx.request.headers));
  return auth().handler(new Request(ctx.request, { headers }));
}

// src/routes/api/auth/[...all]/route.ts
import type { Endpoint } from "lumiose";
import { authHandler } from "../../../../server/auth.server.ts";

export const GET: Endpoint<"/api/auth/[...all]"> = (ctx) => authHandler(ctx);
export const POST: Endpoint<"/api/auth/[...all]"> = (ctx) => authHandler(ctx);

// src/middleware.ts
import { getSessionCookie } from "better-auth/cookies";
import type { Middleware } from "lumiose";
import { auth } from "./server/auth.server.ts";

const middleware: Middleware = async (ctx, next) => {
  ctx.locals.session = null;
  // Without a session cookie the visitor is signed out: no database query. (This is also the case
  // while prerendering.) Better Auth's own routes read the session themselves.
  if (getSessionCookie(ctx.request) === null || ctx.url.pathname.startsWith("/api/auth/")) {
    return next();
  }
  const { response: session, headers } = await auth().api.getSession({
    headers: ctx.request.headers,
    returnHeaders: true,
  });
  ctx.locals.session = session;
  const response = await next();
  // Better Auth extends a session that passed its update age: send the renewed cookie along.
  const cookies = headers.getSetCookie();
  if (cookies.length === 0) return response;
  const renewed = new Response(response.body, response);
  for (const cookie of cookies) renewed.headers.append("set-cookie", cookie);
  return renewed;
};

export default middleware;

// src/routes/dashboard/page.stsx
import { href, response, Title } from "lumiose";
import { requireSession } from "../../server/auth.server.ts";

export default function Dashboard() {
  const { user, session } = requireSession();
  response().setHeader("cache-control", "private, no-store");
  return (
    <main>
      <Title>Dashboard</Title>
      <p>
        Signed in as <strong>{user.name}</strong> ({user.email}).
      </p>
      <p>Your session lasts until {session.expiresAt.toISOString().slice(0, 10)}.</p>
      <form method="post" action={href("/sign-out")}>
        <button>Sign out</button>
      </form>
    </main>
  );
}

// src/server/auth.server.ts, continued
/** Posts `body` to a Better Auth endpoint (`/sign-in/email`) through its HTTP handler. */
export function authRequest(
  ctx: AuthContext,
  path: `/${string}`,
  body: unknown,
): Promise<Response> {
  const headers = new Headers({ "content-type": "application/json" });
  for (const name of ["cookie", "origin", "referer", "user-agent"]) {
    const value = ctx.request.headers.get(name);
    if (value !== null) headers.set(name, value);
  }
  const request = new Request(new URL(`/api/auth${path}`, ctx.url), {
    method: "POST",
    headers: clientHeaders(ctx, headers),
    body: JSON.stringify(body),
  });
  return auth().handler(request);
}

/** The message of a failed Better Auth response: "Invalid email or password", "Too many requests…". */
export async function authError(response: Response): Promise<string> {
  const body = (await response.json().catch(() => null)) as { message?: unknown } | null;
  return typeof body?.message === "string" ? body.message : response.statusText;
}

/** A 303 redirect that sets the cookies of a Better Auth response. */
export function redirectWithCookies(location: string, headers: Headers): Response {
  const response = new Response(null, { status: 303, headers: { location } });
  for (const cookie of headers.getSetCookie()) response.headers.append("set-cookie", cookie);
  return response;
}

// src/routes/sign-in/page.stsx
import { actionData, fail, Title, type ActionContext, type ActionData } from "lumiose";
import { authError, authRequest, redirectWithCookies, safeNext } from "../../server/auth.server.ts";

export const action = async (ctx: ActionContext<"/sign-in">) => {
  const form = await ctx.formData();
  const email = String(form.get("email") ?? "").trim();
  const password = String(form.get("password") ?? "");
  const response = await authRequest(ctx, "/sign-in/email", { email, password });
  // A wrong password (401) or too many attempts (429): Better Auth's message.
  if (!response.ok) return fail(response.status, { email, message: await authError(response) });
  return redirectWithCookies(safeNext(ctx.url.searchParams.get("next")), response.headers);
};

export default function SignIn() {
  return <SignInForm failed={actionData<typeof action>()} />;
}

function SignInForm(props: { failed: ActionData<typeof action> | undefined }) {
  return (
    <main>
      <Title>Sign in</Title>
      {/* No action attribute: the form posts to this URL, `?next=` included. */}
      <form method="post">
        <input type="email" name="email" value={props.failed?.email ?? ""} required />
        <input type="password" name="password" required />
        <p role="alert">{props.failed?.message}</p>
        <button>Sign in</button>
      </form>
    </main>
  );
}

export const action = async (ctx: ActionContext<"/sign-out">) => {
  if (ctx.locals.session === null) return redirectWithCookies(href("/"), new Headers());
  const { headers } = await auth().api.signOut({
    headers: ctx.request.headers,
    returnHeaders: true,
  });
  return redirectWithCookies(href("/"), headers); // the headers clear the cookies
};

// src/lib/auth-client.ts
import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient(); // calls /api/auth/* on the page's origin

// src/islands/AccountMenu.stsx (shortened), used as <AccountMenu client:load /> in the layout
import { href, onMount, signal } from "lumiose";
import { authClient } from "../lib/auth-client.ts";

export function AccountMenu() {
  // `undefined` until the session has loaded: no links that may be wrong.
  const account = signal<{ name: string } | null | undefined>(undefined);

  onMount(() =>
    // Called at once with the current value; the returned unsubscribe runs on unmount.
    authClient.useSession.subscribe(({ data, isPending }) => {
      if (!isPending) account.set(data === null ? null : { name: data.user.name });
    }),
  );

  async function signOut() {
    await authClient.signOut();
    location.assign(href("/"));
  }

  return (
    <div class="account">
      {account() === null ? <a href={href("/sign-in")}>Sign in</a> : null}
      {account() ? (
        <button type="button" onClick={signOut}>
          Sign out {account()?.name}
        </button>
      ) : null}
    </div>
  );
}

// src/server/auth.server.ts
import { emailOTP } from "better-auth/plugins";
import { sendMail } from "./mailer.server.ts";

function createAuth(trustedProxies: string[]) {
  return betterAuth({
    // secret, baseURL, database and advanced as above; keep emailAndPassword for passwords too.
    user: {
      // Set by the onboarding form; until then, the guard below sends the account there.
      additionalFields: { onboardedAt: { type: "date", required: false, input: false } },
    },
    plugins: [
      emailOTP({
        expiresIn: 300, // seconds: the default
        allowedAttempts: 3, // wrong codes before the code is void: the default
        storeOTP: "hashed", // the database keeps a hash of the code
        async sendVerificationOTP({ email, otp, type }) {
          if (type !== "sign-in") return;
          // Not awaited: the response does not wait for the mail server (Better Auth's advice).
          sendMail({
            to: email,
            subject: "Your sign-in code",
            text: `Your code is ${otp}. It expires in 5 minutes.`,
          }).catch((error: unknown) => console.error("The sign-in code was not sent", error));
        },
      }),
    ],
  });
}

model User {
  // Better Auth's fields, as above, and:
  onboardedAt   DateTime?
}

/// A sign-in in progress: the email a code went to, behind a random id.
model SignInChallenge {
  id        String   @id
  email     String
  expiresAt DateTime

  @@map("sign_in_challenge")
}

// src/server/mailer.server.ts
export interface Mail {
  to: string;
  subject: string;
  text: string;
}

export async function sendMail(mail: Mail): Promise<void> {
  if (import.meta.env.DEV) {
    // Development: the server's console, and nowhere else.
    console.info(`\n[mail] to ${mail.to}: ${mail.subject}\n${mail.text}\n`);
    return;
  }
  // Production: your email provider's API, or SMTP.
  throw new Error("sendMail(): no mail provider is set up");
}

// src/server/sign-in-challenge.server.ts
import { prisma } from "./db.server.ts";

/** As long as the code lives (`expiresIn`). */
const LIFETIME_MS = 5 * 60 * 1000;

/** Stores a sign-in for `email`; returns its random id, which is all the URL carries. */
export async function createChallenge(email: string): Promise<string> {
  const id = crypto.randomUUID();
  const db = prisma();
  await db.signInChallenge.deleteMany({ where: { expiresAt: { lt: new Date() } } });
  await db.signInChallenge.create({
    data: { id, email, expiresAt: new Date(Date.now() + LIFETIME_MS) },
  });
  return id;
}

/** The email of a sign-in that has not expired, or `undefined`. */
export async function challengeEmail(id: string): Promise<string | undefined> {
  const challenge = await prisma().signInChallenge.findUnique({ where: { id } });
  return challenge !== null && challenge.expiresAt > new Date() ? challenge.email : undefined;
}

export async function deleteChallenge(id: string): Promise<void> {
  await prisma().signInChallenge.deleteMany({ where: { id } });
}

/** Resolves once `Date.now()` reaches `deadline`. */
export function sleepUntil(deadline: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, Math.max(0, deadline - Date.now())));
}

// src/routes/sign-in/page.stsx
import { actionData, fail, href, redirect, Title, type ActionContext } from "lumiose";
import { authError, authRequest } from "../../server/auth.server.ts";
import { createChallenge, sleepUntil } from "../../server/sign-in-challenge.server.ts";

export const action = async (ctx: ActionContext<"/sign-in">) => {
  // Every answer takes this long, so the time Better Auth takes does not tell whether an
  // account has this email.
  const deadline = Date.now() + 1000;
  const form = await ctx.formData();
  const email = String(form.get("email") ?? "")
    .trim()
    .toLowerCase();
  const response = await authRequest(ctx, "/email-otp/send-verification-otp", {
    email,
    type: "sign-in",
  });
  if (!response.ok) {
    // An invalid address (400) or too many requests (429): neither depends on an account.
    const message = await authError(response);
    await sleepUntil(deadline);
    return fail(response.status, { email, message });
  }
  const challenge = await createChallenge(email);
  await sleepUntil(deadline);
  // The random id in the URL, never the email; `?next=` goes along.
  redirect(href("/sign-in/code/[challenge]", { challenge }) + ctx.url.search);
};

export default function SignIn() {
  const failed = actionData<typeof action>();
  return (
    <main>
      <Title>Sign in</Title>
      {/* No action attribute: the form posts to this URL, `?next=` included. */}
      <form method="post">
        <input
          type="email"
          name="email"
          value={failed?.email ?? ""}
          autocomplete="email"
          required
        />
        <p role="alert">{failed?.message}</p>
        <button>Email me a code</button>
      </form>
    </main>
  );
}

// src/routes/sign-in/code/[challenge]/page.stsx
import { actionData, fail, href, Title, type ActionContext } from "lumiose";
import {
  authError,
  authRequest,
  redirectWithCookies,
  safeNext,
} from "../../../../server/auth.server.ts";
import { challengeEmail, deleteChallenge } from "../../../../server/sign-in-challenge.server.ts";

export const action = async (ctx: ActionContext<"/sign-in/code/[challenge]">) => {
  const { challenge } = ctx.params;
  const email = await challengeEmail(challenge);
  if (email === undefined) return fail(410, { message: "The code has expired. Ask for a new one." });
  const form = await ctx.formData();
  const otp = String(form.get("code") ?? "").replace(/\s/g, "");
  // Signs the account in, or creates it and signs it in: the response sets the session cookie.
  const response = await authRequest(ctx, "/sign-in/email-otp", { email, otp });
  // A wrong or expired code (400), a fourth try (403), too many requests (429).
  if (!response.ok) return fail(response.status, { message: await authError(response) });
  await deleteChallenge(challenge);
  return redirectWithCookies(safeNext(ctx.url.searchParams.get("next")), response.headers);
};

export default function EnterCode() {
  const failed = actionData<typeof action>();
  return (
    <main>
      <Title>Enter your code</Title>
      {/* Not the address: anyone with this URL could read it. */}
      <p>We sent a 6-digit code to the address you entered. It expires in 5 minutes.</p>
      <form method="post">
        <input name="code" inputmode="numeric" autocomplete="one-time-code" required />
        <p role="alert">{failed?.message}</p>
        <button>Sign in</button>
      </form>
      <a href={href("/sign-in")}>Use another address, or get a new code</a>
    </main>
  );
}

// src/routes/(app)/middleware.ts: every route in the (app) group
import { href, type Middleware } from "lumiose";

const onboarded: Middleware = (ctx, next) => {
  const { session } = ctx.locals; // set by src/middleware.ts, which runs first
  const back = `?next=${encodeURIComponent(ctx.url.pathname + ctx.url.search)}`;
  if (session === null) return Response.redirect(new URL(href("/sign-in") + back, ctx.url), 303);
  if (!session.user.onboardedAt) {
    return Response.redirect(new URL(href("/onboarding") + back, ctx.url), 303);
  }
  return next();
};

export default onboarded;

// src/routes/onboarding/page.stsx: outside the group, so the guard does not send it to itself
import { actionData, fail, href, redirect, Title, type ActionContext } from "lumiose";
import { requireSession, safeNext } from "../../server/auth.server.ts";
import { prisma } from "../../server/db.server.ts";

export const action = async (ctx: ActionContext<"/onboarding">) => {
  const { session } = ctx.locals;
  if (session === null) redirect(href("/sign-in"));
  const form = await ctx.formData();
  const name = String(form.get("name") ?? "").trim();
  if (name === "") return fail(400, { name, message: "Enter your name." });
  await prisma().user.update({
    where: { id: session.user.id },
    data: { name, onboardedAt: new Date() },
  });
  redirect(safeNext(ctx.url.searchParams.get("next")));
};

export default function Onboarding() {
  const { user } = requireSession();
  const failed = actionData<typeof action>();
  return (
    <main>
      <Title>Welcome</Title>
      <form method="post">
        <input name="name" value={failed?.name ?? user.name} autocomplete="name" required />
        <p role="alert">{failed?.message}</p>
        <button>Continue</button>
      </form>
    </main>
  );
}