Better Auth Patterns

Overview

Implement authentication and authorization using Better Auth with TRPC procedures following the project’s established patterns.

When to Use This Skill

• Configuring Better Auth settings
• Creating protected TRPC procedures
• Implementing organization/project access control
• Working with sessions and user roles
• Setting up OAuth providers

Auth Configuration

// apps/web-app/src/auth/auth.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { admin, organization } from "better-auth/plugins";

export const auth = betterAuth({
  baseURL: serverEnv.BETTER_AUTH_URL,
  secret: serverEnv.BETTER_AUTH_SECRET,
  database: drizzleAdapter(db, {
    provider: "pg",
    schema: {
      user: usersTable,
      session: sessionsTable,
      account: accountsTable,
      verification: verificationsTable,
      organization: organizationsTable,
      member: membersTable,
      invitation: invitationsTable,
    },
  }),
  session: {
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 5 minutes cache
    },
  },
  socialProviders: {
    google: {
      clientId: serverEnv.GOOGLE_CLIENT_ID,
      clientSecret: serverEnv.GOOGLE_CLIENT_SECRET,
    },
  },
  emailAndPassword: { enabled: true },
  plugins: [
    admin(),
    organization({ sendInvitationEmail: async () => {} }),
  ],
});

Auth-Related Database Tables

Core Tables:

• usersTable – User accounts with role field (admin | user)
• sessionsTable – Auth sessions with activeOrganizationId
• accountsTable – OAuth accounts (stores access/refresh tokens)

Organization Tables:

• organizationsTable – Organizations
• membersTable – Organization members with role (owner | admin | member)
• invitationsTable – Pending invitations

Project Tables:

• projectsTable – Projects (belong to organizations)
• projectMembersTable – Project members with role (admin | editor | viewer)

TRPC Context & Session

// apps/web-app/src/infrastructure/trpc/init.ts
export const createTRPCContext = async ({
  headers,
}: {
  headers: Headers;
}) => {
  const session = await auth.api.getSession({ headers });
  return { db, session, headers };
};

Protected Procedure Patterns

Base Auth Procedures

// apps/web-app/src/infrastructure/trpc/procedures/auth.ts
const enforceUserIsAuthenticated = t.middleware(
  ({ ctx, next }) => {
    if (!ctx.session?.user) throw unauthorizedError();
    return next({
      ctx: {
        session: { ...ctx.session, user: ctx.session.user },
        userId: ctx.session.user.id as UserId,
      },
    });
  }
);

const enforceUserIsAdmin = t.middleware(
  async ({ ctx, next }) => {
    if (
      !ctx.session?.user ||
      ctx.session.user.role !== "admin"
    )
      throw unauthorizedError();
    return next({ ctx });
  }
);

export const publicProcedure = t.procedure
  .use(debugMiddleware)
  .use(sentryMiddleware);
export const protectedProcedure = publicProcedure.use(
  enforceUserIsAuthenticated
);
export const adminProcedure = publicProcedure.use(
  enforceUserIsAdmin
);

Organization Access Procedures

// apps/web-app/src/infrastructure/trpc/procedures/organization.ts
import { OrganizationId } from "@project/common";

// Member access - any org member
export const protectedOrganizationMemberProcedure =
  protectedProcedure
    .input(
      Schema.standardSchemaV1(
        Schema.Struct({ organizationId: OrganizationId })
      )
    )
    .use(async function isMemberOfOrganization(opts) {
      const memberAccess = await opts.ctx.db
        .select()
        .from(membersTable)
        .where(
          and(
            eq(
              membersTable.organizationId,
              opts.input.organizationId
            ),
            eq(membersTable.userId, opts.ctx.userId)
          )
        )
        .limit(1);

      if (memberAccess.length === 0)
        throw forbiddenError(
          "You are not a member of this organization"
        );

      return opts.next({
        ctx: {
          member: memberAccess[0],
          organizationId: opts.input.organizationId,
        },
      });
    });

// Admin access - org admin/owner only
export const protectedOrganizationAdminProcedure =
  protectedProcedure
    .input(
      Schema.standardSchemaV1(
        Schema.Struct({ organizationId: OrganizationId })
      )
    )
    .use(async function isAdminOfOrganization(opts) {
      const memberAccess = await opts.ctx.db
        .select()
        .from(membersTable)
        .where(
          and(
            eq(
              membersTable.organizationId,
              opts.input.organizationId
            ),
            eq(membersTable.userId, opts.ctx.userId),
            or(
              eq(membersTable.role, "admin"),
              eq(membersTable.role, "owner")
            )
          )
        )
        .limit(1);

      if (memberAccess.length === 0)
        throw forbiddenError("Admin access required");

      return opts.next({
        ctx: {
          member: memberAccess[0],
          organizationId: opts.input.organizationId,
        },
      });
    });

Project Access Procedures

// apps/web-app/src/infrastructure/trpc/procedures/project-access.ts

// Single optimized query - checks both org and project membership
export const protectedProjectMemberProcedure =
  protectedProcedure
    .input(
      Schema.standardSchemaV1(
        Schema.Struct({ projectId: ProjectId })
      )
    )
    .use(async function hasProjectAccess(opts) {
      const result = await ctx.db
        .select({
          projectId: projectsTable.id,
          organizationId: projectsTable.organizationId,
          orgMemberRole: membersTable.role,
          projectMemberRole: projectMembersTable.role,
        })
        .from(projectsTable)
        .leftJoin(
          membersTable,
          and(
            eq(
              membersTable.organizationId,
              projectsTable.organizationId
            ),
            eq(membersTable.userId, ctx.userId)
          )
        )
        .leftJoin(
          projectMembersTable,
          and(
            eq(
              projectMembersTable.projectId,
              projectsTable.id
            ),
            eq(projectMembersTable.userId, ctx.userId)
          )
        )
        .where(eq(projectsTable.id, projectId));

      // Org admins get automatic project admin access
      const isOrgAdmin =
        data.orgMemberRole === "admin" ||
        data.orgMemberRole === "owner";
      if (isOrgAdmin) {
        return opts.next({
          ctx: {
            project,
            projectRole: "admin",
            orgRole: data.orgMemberRole,
          },
        });
      }
      // Check explicit project membership...
    });

// Chained procedure for admin-only
export const protectedProjectAdminProcedure =
  protectedProjectMemberProcedure.use(
    async function requiresProjectAdmin(opts) {
      if (
        ctx.orgRole === "admin" ||
        ctx.orgRole === "owner" ||
        ctx.projectRole === "admin"
      )
        return opts.next({ ctx });
      throw forbiddenError(
        "Project admin permissions required"
      );
    }
  );

Available Procedures Summary

Client-Side Auth

// apps/web-app/src/auth/auth-client.ts
import { createAuthClient } from "better-auth/react";
import {
  adminClient,
  organizationClient,
} from "better-auth/client/plugins";

export const authClient = createAuthClient({
  betterAuthBaseUrl,
  plugins: [adminClient(), organizationClient()],
});

export const { signIn, signOut, useSession, getSession } =
  authClient;

// Sign in with redirect
export const signInWithEmail = async (
  email: string,
  password: string,
  callbackURL = "/app/dashboard"
) => {
  return withAuthRedirect(
    (callbacks) =>
      signIn.email({ email, password }, callbacks),
    callbackURL
  );
};

export const signInWithGoogle = async (
  callbackURL = "/app/dashboard"
) => {
  return signIn.social({ provider: "google", callbackURL });
};

Admin API Usage

// Using Better Auth server API in TRPC procedures
export const router = {
  setUserAdmin: adminProcedure.mutation(
    async ({ ctx, input }) => {
      const users = await auth.api.listUsers({
        headers: ctx.headers,
        query: {
          searchField: "email",
          searchValue: input.email,
        },
      });
      await auth.api.setRole({
        headers: ctx.headers,
        body: {
          userId: user.id,
          role: input.isAdmin ? "admin" : "user",
        },
      });
    }
  ),

  banUser: adminProcedure.mutation(
    async ({ ctx, input }) => {
      await auth.api.banUser({
        headers: ctx.headers,
        body: { userId: input.userId, banReason },
      });
    }
  ),
};

Key Rules

1. Use appropriate procedure for access level needed
2. Org admins get automatic project access – don’t duplicate checks
3. Single query for access checks – use JOINs, not multiple queries
4. Pass headers to auth.api calls for session context
5. Chain procedures for more specific access (e.g., protectedProjectAdminProcedure)