Core Authentication Configuration

/**
 * Configure NextAuth.js for authentication handling
 * @param options - Authentication configuration options
 * @returns Authentication handler function or response
 */
function NextAuth(options: AuthOptions): any;
function NextAuth(req: NextApiRequest, res: NextApiResponse, options: AuthOptions): any;
function NextAuth(req: NextRequest, res: RouteHandlerContext, options: AuthOptions): any;

// App Router (app/api/auth/[...nextauth]/route.ts)
import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";

const handler = NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
});

export { handler as GET, handler as POST };

// Pages API (pages/api/auth/[...nextauth].ts)
import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";

export default NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
});

/**
 * Complete configuration interface for NextAuth.js
 */
interface AuthOptions {
  /** Array of authentication providers for signing in */
  providers: Provider[];
  /** Random string used to hash tokens, sign cookies and generate cryptographic keys */
  secret?: string;  
  /** Session configuration options */
  session?: Partial<SessionOptions>;
  /** JWT configuration options */
  jwt?: Partial<JWTOptions>;
  /** URLs for custom pages */
  pages?: Partial<PagesOptions>;
  /** Lifecycle callback functions */
  callbacks?: Partial<CallbacksOptions>;
  /** Event handler functions */
  events?: Partial<EventCallbacks>;
  /** Database adapter for session and user management */
  adapter?: Adapter;
  /** Enable debug messages */
  debug?: boolean;
  /** Custom logger implementation */
  logger?: Partial<LoggerInstance>;
  /** UI theme configuration */
  theme?: Theme;
  /** Force secure cookies (HTTPS only) */
  useSecureCookies?: boolean;
  /** Custom cookie options */
  cookies?: Partial<CookiesOptions>;
}

/**
 * Session configuration options
 */
interface SessionOptions {
  /** Session storage strategy - "jwt" for stateless, "database" for server-side storage */
  strategy: "jwt" | "database";
  /** Maximum session age in seconds (default: 30 days) */
  maxAge: number;
  /** How frequently to update session expiry in seconds (default: 24 hours) */
  updateAge: number;
  /** Custom session token generator function */
  generateSessionToken?: () => Awaitable<string>;
}

/**
 * JWT configuration options
 */
interface JWTOptions {
  /** Secret used for JWT signing and encryption */
  secret: string;
  /** Maximum JWT age in seconds */
  maxAge: number;
  /** Custom JWT encoding function */
  encode?: (params: JWTEncodeParams) => Awaitable<string>;
  /** Custom JWT decoding function */
  decode?: (params: JWTDecodeParams) => Awaitable<JWT | null>;
}

interface JWTEncodeParams {
  /** JWT payload to encode */
  token?: JWT;
  /** Secret for encryption */
  secret: string;
  /** Maximum age in seconds */
  maxAge?: number;
  /** Salt for key derivation */
  salt?: string;
}

interface JWTDecodeParams {
  /** JWT token string to decode */
  token?: string;
  /** Secret for decryption */
  secret: string;
  /** Salt for key derivation */
  salt?: string;
}

/**
 * Custom page URLs configuration
 */
interface PagesOptions {
  /** Custom sign in page URL */
  signIn?: string;
  /** Custom sign out page URL */
  signOut?: string;
  /** Custom error page URL */
  error?: string;
  /** Custom email verification page URL */
  verifyRequest?: string;
  /** Custom new user registration page URL */
  newUser?: string;
}

export default NextAuth({
  providers: [...],
  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
  },
});

/**
 * Callback functions for customizing authentication flow
 */
interface CallbacksOptions<P = Profile, A = Account> {
  /** Control whether user is allowed to sign in */
  signIn?: (params: {
    user: User | AdapterUser;
    account: A | null;
    profile?: P;
    email?: { verificationRequest?: boolean };
    credentials?: Record<string, CredentialInput>;
  }) => Awaitable<string | boolean>;
  
  /** Control where user is redirected after authentication */
  redirect?: (params: {
    url: string;
    baseUrl: string;
  }) => Awaitable<string>;
  
  /** Customize session object sent to client */
  session?: (params: {
    session: Session;
    token: JWT;
    user: AdapterUser;
    newSession?: any;
    trigger?: "update";
  }) => Awaitable<Session | DefaultSession>;
  
  /** Customize JWT token contents */
  jwt?: (params: {
    token: JWT;
    user: User | AdapterUser;
    account: A | null;
    profile?: P;
    trigger?: "signIn" | "signUp" | "update";
    isNewUser?: boolean;
    session?: any;
  }) => Awaitable<JWT>;
}

export default NextAuth({
  providers: [...],
  callbacks: {
    async signIn({ user, account, profile }) {
      // Allow sign in only for specific email domains
      if (account?.provider === "google") {
        return user.email?.endsWith("@company.com") ?? false;
      }
      return true;
    },
    async session({ session, token }) {
      // Add user ID to session
      session.user.id = token.sub;
      return session;
    },
    async jwt({ token, user, account, profile }) {
      // Add account type to token on first sign in
      if (account) {
        token.accountType = account.type;
      }
      return token;
    },
  },
});

/**
 * Event handler functions for authentication lifecycle events
 */
interface EventCallbacks {
  /** Triggered when user signs in */
  signIn?: (message: { user: User; account: Account | null; profile?: Profile; isNewUser?: boolean }) => Awaitable<void>;
  /** Triggered when user signs out */
  signOut?: (message: { session: Session; token: JWT }) => Awaitable<void>;
  /** Triggered when new user is created */
  createUser?: (message: { user: User }) => Awaitable<void>;
  /** Triggered when user profile is updated */
  updateUser?: (message: { user: User }) => Awaitable<void>;
  /** Triggered when provider account is linked */
  linkAccount?: (message: { user: User; account: Account; profile: Profile }) => Awaitable<void>;
  /** Triggered when session is accessed */
  session?: (message: { session: Session; token: JWT }) => Awaitable<void>;
}

/**
 * Cookie configuration options
 */
interface CookiesOptions {
  sessionToken?: CookieOption;
  callbackUrl?: CookieOption;
  csrfToken?: CookieOption;
  pkceCodeVerifier?: CookieOption;
  state?: CookieOption;
  nonce?: CookieOption;
}

interface CookieOption {
  name: string;
  options: CookieSerializeOptions;
}

/**
 * Theme configuration for NextAuth.js UI
 */
interface Theme {
  colorScheme?: "light" | "dark" | "auto";
  logo?: string;
  brandColor?: string;
  buttonText?: string;
}

export default NextAuth({
  providers: [...],
  theme: {
    colorScheme: "dark",
    brandColor: "#1976d2",
    logo: "https://example.com/logo.png",
    buttonText: "#ffffff",
  },
});

interface User extends DefaultUser {
  id: string;
  name?: string | null;
  email?: string | null;
  image?: string | null;
}

interface DefaultUser {
  id: string;
  name?: string | null;
  email?: string | null;
  image?: string | null;
}

interface Account extends Partial<TokenSetParameters> {
  providerAccountId: string;
  userId?: string;
  provider: string;
  type: ProviderType;
  access_token?: string;
  refresh_token?: string;
  expires_at?: number;
  token_type?: string;
  scope?: string;
  id_token?: string;
  session_state?: string;
}

interface Profile extends Record<string, any> {
  sub?: string;
  name?: string;
  email?: string;
  image?: string;
}

type Awaitable<T> = T | PromiseLike<T>;
type ISODateString = string;