fastify-xauth-better

Production-ready Fastify plugin for Better Auth with multi-instance support, organizations, 2FA, audit logging, and email templates. Supports multiple simultaneous auth configurations (e.g., admin + user) each with independent cookie namespaces, route prefixes, and middleware.

Installation

npm install @xenterprises/fastify-xauth-better better-auth @prisma/client

Quick Start

import Fastify from "fastify";
import xAuthBetter from "@xenterprises/fastify-xauth-better";
import { PrismaClient } from "@prisma/client";

const fastify = Fastify();
const prisma = new PrismaClient();

await fastify.register(xAuthBetter, {
  prisma,
  configs: [
    {
      name: "user",
      secret: process.env.AUTH_SECRET, // min 32 chars
      baseURL: "http://localhost:3000",
      basePath: "/api/auth",
      prefix: "/api",
    },
  ],
});

// Protected route — session validated automatically
fastify.get("/api/profile", async (request) => {
  return { user: request.user };
});

await fastify.listen({ port: 3000 });

Options

Plugin Options

Instance Config (XAuthBetterConfig)

Advanced Options

Audit Log Options

Methods

fastify.xAuthBetter decorator

Instance methods

Each instance returned by fastify.xAuthBetter.get(name) or .default exposes:

• requireAuth() — Returns an auth-required preHandler middleware
• requireRole(roles) — Returns a global role-based access control preHandler
• requireOrg() — Returns org-membership-required preHandler; populates request.organization
• requireOrgRole(roles) — Returns an org-scoped role preHandler (requires requireOrg() first)
• getSession(request) — Resolves session from headers/cookies without middleware
• auditLog.log(event, data) — Writes an audit event to AuthAuditLog
• pruneAuditLogs(options) — Deletes old audit log records

Request Properties

When prefix is configured, the auth middleware sets:

Multi-Instance Setup

await fastify.register(xAuthBetter, {
  prisma,
  configs: [
    {
      name: "admin",
      secret: process.env.ADMIN_SECRET,
      baseURL: "http://localhost:3000",
      basePath: "/api/auth/admin",
      prefix: "/api/admin",
      roles: ["superadmin", "admin"],
    },
    {
      name: "user",
      secret: process.env.USER_SECRET,
      baseURL: "http://localhost:3000",
      basePath: "/api/auth/user",
      prefix: "/api/user",
      roles: ["contractor", "homeowner"],
    },
  ],
});

const adminAuth = fastify.xAuthBetter.get("admin");
const userAuth  = fastify.xAuthBetter.get("user");

Organizations

{
  organizations: {
    enabled: true,
    orgIdHeader: "X-Organization-Id",     // default
    orgIdFromUrl: /^\/orgs\/([^\/]+)/,    // RegExp — first capture group is the org ID (default: null)
  }
}

When organizations.enabled is true, requireOrg() resolves the organization ID in this order:

1. URL path — organizations.orgIdFromUrl is matched against request.url; the first capture group wins.
2. HTTP header — the organizations.orgIdHeader request header (looked up case-insensitively).
3. Session — the session's activeOrganizationId (requires requireAuth() or a prefix to have populated request.auth first).
4. Route param — falls back to request.params.orgId when none of the above produce an ID.

When organizations are disabled (the default), requireOrg() uses request.params.orgId only.

If no org ID can be resolved, the middleware responds 400 Bad Request. The resolved ID is validated through Better Auth's organization API: 404 Not Found if the org doesn't exist or isn't accessible, 403 Forbidden if the authenticated user is not a member. On success, request.organization is set to the full org data (id, name, slug, logo, metadata, createdAt, members) plus the current user's org-scoped role. Membership is always validated server-side — a user cannot access another organization's data by switching the header or URL.

Email Templates

6 built-in templates with {{variable}} substitution:

Email delivery requires @xenterprises/fastify-xemail or the email-outbox plugin to be registered.

Error Reference

Registration fails fast with real Errors. All registration messages start with xauthbetter: and name the option with a usage example:

At runtime, middleware sends standard Fastify error bodies: 401 (no/invalid session), 403 (role or org membership failure), 400 (missing org id), 404 (organization not found), 500 (org context load failure). Middleware logs error.message only — never full error objects — so auth-library errors can't leak request context into logs.

Environment Variables

This plugin never reads process.env. All values — secrets, OAuth credentials, URLs — arrive via app.register(xAuthBetter, { ... }) options. Set env vars in your own config layer (e.g. @xenterprises/fastify-xconfig) and pass them in:

Secure cookies are not driven by NODE_ENV: advanced.useSecureCookies defaults to true statically — set it to false explicitly for local development over plain HTTP. Note that Better Auth itself may consult env vars internally for its own defaults; explicit config values always take precedence.

How It Works

On registration each config is validated and merged with defaults, then a Better Auth instance is created with a Prisma adapter and the configured plugins (admin, bearer, 2FA, magic links, organizations). A catch-all Fastify route at basePath/* bridges Fastify request/reply to the Web API Request/Response format expected by Better Auth's handler. When prefix is set, an onRequest hook validates sessions for all matching routes (skipping basePath and any excludedPaths), then attaches request.user, request.auth, and optionally request.organization for downstream handlers. All instances are exposed via fastify.xAuthBetter for programmatic access to middleware factories, audit logging, and session utilities.

AI Context

package: "@xenterprises/fastify-xauth-better"
type: fastify-plugin
use-when: Production auth with Better Auth — multi-instance, organizations, 2FA, magic links, audit logging, social OAuth
decorator: fastify.xAuthBetter (get, default, configs, pruneAuditLogs)
request-decorators: request.user, request.auth, request.organization
requires: Prisma client with Better Auth schema, secret ≥ 32 chars per config
env: consumer-set only — the plugin never reads process.env; pass secrets/OAuth credentials via register options (DATABASE_URL feeds your own Prisma client)
multi-instance: each configs[] entry gets its own auth instance, route prefix, and cookie namespace