Authentication API

Ecclesia uses Auth.js (NextAuth v5) with JWT strategy for authentication.

Configuration

Auth configuration lives in three files:

Session Object

The session is extended beyond the default Auth.js session:

interface Session {
  user: {
    id: string; // User UUID
    name: string; // Display name
    email: string; // Email address
    role: UserRole; // RBAC role
    organizationId: string; // Scoping organization
    organizationName: string; // Display name
  };
}

Server-Side Authentication

In Server Components

import { auth } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    redirect("/auth/login");
  }

  return <div>Welcome, {session.user.name}</div>;
}

In Server Actions

"use server";
import { auth } from "@/auth";

export async function protectedAction() {
  const session = await auth();
  if (!session?.user) {
    return { error: "Unauthorized" };
  }
  // proceed...
}

In API Routes

import { auth } from "@/auth";
import { NextResponse } from "next/server";

export async function GET() {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
  // proceed...
}

Client-Side Authentication

Auth Provider

The app wraps children with <AuthProvider> in the root layout:

// app/layout.tsx
import { AuthProvider } from "@/components/providers/auth-provider";

<AuthProvider>{children}</AuthProvider>;

useSession Hook

"use client";
import { useSession } from "next-auth/react";

function UserInfo() {
  const { data: session, status } = useSession();

  if (status === "loading") return <Skeleton />;
  if (!session) return <LoginButton />;

  return <span>{session.user.name}</span>;
}

Sign In / Sign Out

import { signIn, signOut } from "next-auth/react";

// Sign in
await signIn("credentials", {
  email: "user@example.com",
  password: "password",
  redirect: false,
});

// Sign out
await signOut({ callbackUrl: "/auth/login" });

Type Extensions

Auth.js types are extended in types/next-auth.d.ts:

declare module "next-auth" {
  interface User {
    role: UserRole;
    organizationId: string;
    organizationName: string;
  }

  interface Session {
    user: User & DefaultSession["user"];
  }
}