@gftdcojp/auth

Zero-config authentication package for Next.js applications with Firebase integration.

Features

✅ Zero-config setup - Works out of the box
✅ Firebase integration - Built-in Firebase Auth support
✅ Next.js compatible - Optimized for Next.js App Router
✅ TypeScript support - Full TypeScript definitions
✅ Session management - Secure cookie-based sessions
✅ Multi-tenant support - Firebase tenant support
✅ Middleware support - Next.js middleware integration

Installation

npm install @gftdcojp/auth
# or
yarn add @gftdcojp/auth
# or
pnpm add @gftdcojp/auth

Quick Start

1. Environment Setup

Create a .env.local file with your Firebase configuration:

# Firebase Admin SDK (Required for server-side operations)
FIREBASE_PROJECT_ID=your-firebase-project-id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxx@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

# Optional: Cookie security keys (generate random strings)
AUTH_COOKIE_SIG_KEY_1="your-64-character-random-key-1"
AUTH_COOKIE_SIG_KEY_2="your-64-character-random-key-2"

2. Client Setup

// app/layout.tsx
'use client'

import { AuthProvider, createClientAuthConfig } from '@gftdcojp/auth'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  // Zero-config setup
  const authConfig = createClientAuthConfig()

  return (
    <html lang="en">
      <body>
        <AuthProvider config={authConfig}>
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}

3. Using Authentication

// app/page.tsx
'use client'

import { useAuth } from '@gftdcojp/auth'

export default function HomePage() {
  const { user, isLoading, logout, getAfterLoginUrl } = useAuth()

  if (isLoading) return <div>Loading...</div>

  if (!user) {
    return (
      <div>
        <h1>Welcome!</h1>
        <p>Please sign in to continue.</p>
        <a href="/signin">Sign In</a>
      </div>
    )
  }

  return (
    <div>
      <h1>Welcome, {user.displayName}!</h1>
      <p>Email: {user.email}</p>
      <button onClick={() => logout().then(() => window.location.href = '/signin')}>
        Logout
      </button>
    </div>
  )
}

Advanced Configuration

Custom Redirect URLs

// Custom redirects for your application
const authConfig = createClientAuthConfig({
  redirects: {
    afterLogin: '/dashboard',    // Custom login redirect
    afterLogout: '/welcome',     // Custom logout redirect
    onAuthError: '/help',        // Custom error redirect
  }
})

API Server Configuration

// If you have a custom API server
const authConfig = createClientAuthConfig({
  api: {
    baseUrl: 'https://your-api-server.com',
    loginEndpoint: '/api/custom/login',
    sessionEndpoint: '/api/custom/session',
    logoutEndpoint: '/api/custom/logout',
  }
})

API Reference

Client Hooks

`useAuth()`

Returns authentication state and methods.

const {
  user,           // UserProfile | null
  accessToken,    // string | null
  isLoading,      // boolean
  loginWithIdToken, // (idToken: string, tenantId?: string) => Promise<void>
  logout,         // () => Promise<void>
  refreshToken,   // () => Promise<void>
  getAfterLoginUrl,   // () => string
  getAfterLogoutUrl,  // () => string
  getAuthErrorUrl,    // () => string
} = useAuth()

Configuration Functions

`createClientAuthConfig(overrides?)`

Creates client-side authentication configuration.

`createServerAuthConfig(overrides?)`

Creates server-side authentication configuration.

Components

`<AuthProvider config={authConfig}>`

Provides authentication context to your application.

Server-Side Usage

API Routes

// app/api/auth/login/route.ts
import { createGFTDAuth, createServerAuthConfig } from '@gftdcojp/auth'

const authConfig = createServerAuthConfig()
const auth = createGFTDAuth(authConfig)

export async function POST(request: Request) {
  const { idToken } = await request.json()

  const result = await auth.handleLogin({ idToken })

  if (result.success) {
    // Set session cookie
    const response = NextResponse.json({ user: result.user })
    response.cookies.set('session', result.accessToken!)
    return response
  }

  return NextResponse.json({ error: result.error }, { status: 401 })
}

Middleware

// middleware.ts
import { createAuthMiddleware, createServerAuthConfig } from '@gftdcojp/auth'

const authConfig = createServerAuthConfig()
const middleware = createAuthMiddleware({
  authConfig,
  publicPaths: ['/', '/signin', '/api/auth/login']
})

export default middleware

Firebase Configuration

The package requires the following Firebase environment variables:

FIREBASE_PROJECT_ID - Your Firebase project ID
FIREBASE_CLIENT_EMAIL - Firebase service account email
FIREBASE_PRIVATE_KEY - Firebase service account private key

Getting Firebase Credentials

Go to Firebase Console
Select your project
Go to Project Settings → Service Accounts
Generate a new private key
Download the JSON file
Extract the values for the environment variables

Security

Uses HTTP-only, Secure cookies for session management
Supports cookie signature verification
Firebase Admin SDK for secure token validation
Built-in CSRF protection

License

Support

For issues and questions, please open an issue on GitHub.