Skip to content

README.md

Latest commit

 

History

History
128 lines (90 loc) · 3.7 KB

README.md

File metadata and controls

128 lines (90 loc) · 3.7 KB

@scratchyjs/auth

Authentication for the Scratchy framework, powered by Better Auth. Provides a server-side auth factory, a Fastify plugin that resolves sessions on every request, typed request.session / request.user decorators, and preHandler hooks for protecting routes.

Installation

pnpm add @scratchyjs/auth

Usage

1. Create the auth instance

// src/auth.ts
import { createAuth } from "@scratchyjs/auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";

export const auth = createAuth({
  secret: process.env.BETTER_AUTH_SECRET,
  trustedOrigins: ["http://localhost:3000"],
  emailAndPassword: { enabled: true },
  database: drizzleAdapter(db, { provider: "pg" }),
});

2. Register the Fastify plugin

Register after the database plugin so fastify.db is available.

import { auth } from "./auth.js";
import authPlugin from "@scratchyjs/auth/plugin";

await server.register(authPlugin, { auth });

// Every request now has:
//   request.session  — AuthSession | null
//   request.user     — AuthUser    | null

3. Protect routes

import { requireAdmin, requireAuth } from "@scratchyjs/auth/hooks";

// Authenticated users only (HTTP 401 otherwise)
fastify.get("/profile", { preHandler: requireAuth }, (request) => {
  return request.user;
});

// Admin users only (HTTP 401 / 403 otherwise)
fastify.delete("/users/:id", { preHandler: requireAdmin }, async (request) => {
  const { id } = request.params as { id: string };
  await deleteUser(id);
  return { success: true };
});

4. Browser client

import { createAuthClient } from "@scratchyjs/auth/client";

const authClient = createAuthClient({ baseURL: "/api/auth" });

await authClient.signIn.email({ email, password });
await authClient.signOut();
const session = await authClient.getSession();

API

createAuth(options)

Thin wrapper around betterAuth(). Accepts any valid Better Auth options. Returns an AuthInstance.

createAuthClient(options)

Creates a browser-side Better Auth client. options.baseURL should point to your auth endpoint (default /api/auth).

authPlugin (Fastify plugin)

Registers fastify-better-auth and adds an onRequest hook that resolves the session and sets request.session (AuthSession | null) and request.user (AuthUser | null).

Options

Option Type Description
auth AuthInstance The instance returned by createAuth().

requireAuth(request, reply, done)

Fastify preHandler hook. Sends HTTP 401 when request.session is null.

requireAdmin(request, reply, done)

Fastify preHandler hook. Sends HTTP 401 when unauthenticated; HTTP 403 when request.session.user.role !== "admin".

Auth Endpoints

Once the plugin is registered, Better Auth mounts these routes under /api/auth:

Method Path Description
POST /api/auth/sign-up/email Register a new user
POST /api/auth/sign-in/email Sign in with email/password
POST /api/auth/sign-out Sign out
GET /api/auth/get-session Get current session
POST /api/auth/forgot-password Request password reset
POST /api/auth/reset-password Reset password

Documentation

https://scratchyjs.com/sessions