npm package: @futureverse/next-auth
Description: Provides an OAuth authentication provider for FuturePass with Next-Auth (Auth.js). This package enables server-side authentication in Next.js applications.
Latest version: 1.0.6

# Futureverse Next Auth

Provides an OAuth authentication provider for FuturePass with Next-Auth (Auth.js). This package enables server-side authentication in Next.js applications.

## Installation

npm:
```bash
npm install @futureverse/next-auth next-auth@beta --save
```

```bash
npm install wagmi viem @tanstack/react-query
```

yarn:
```bash
yarn add @futureverse/next-auth next-auth@beta
yarn add wagmi viem @tanstack/react-query
```

## Usage

### 1. Configure Next-Auth

**auth.ts**
```typescript
import NextAuth from 'next-auth';
import Futureverse from '@futureverse/next-auth/provider';
import { createNextAuthClient } from '@futureverse/next-auth';
import { QueryClient } from '@tanstack/react-query';

const clientId = '<your-futureverse-client-id>';

// Optional configuration
const authorizationUrl = 'https://login.passonline.cloud'; // Optional - defaults to production
const signerURL = 'https://signer.passonline.cloud'; // Optional - defaults to production  
const issuer = 'https://login.futureverse.cloud'; // Optional - defaults to production

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    Futureverse({
      clientId,
      authority: authorizationUrl, // Optional
      issuer, // Optional
    }),
  ],
  session: {
    strategy: 'jwt',
  },
  secret: process.env.AUTH_SECRET, // Required - add to your .env file
  callbacks: {
    async jwt({ token, profile }) {
      // On first sign in, profile exists
      if (profile) {
        token.eoa = profile.eoa;
        token.custodian = profile.custodian;
        token.chainId = profile.chainId;
        token.futurepass = profile.futurepass;
        token.sub = profile.sub ?? undefined;
        token.profile = profile.profile;
      }
      return token;
    },
    async session({ session, token }) {
      session.user.eoa = token.eoa;
      session.user.custodian = token.custodian;
      session.user.chainId = token.chainId;
      session.user.futurepass = token.futurepass;
      session.user.sub = token.sub;
      session.user.profile = token.profile;
      return session;
    },
  },
});

// Create the Futureverse Next Auth client for client-side operations
export const authClient = createNextAuthClient({
  clientId,
  authorizationURL: authorizationUrl, // Optional
  signerURL, // Optional
  issuer, // Optional
  chainId: 7672, // Optional - defaults to TRN Mainnet
  hostWeb3SigningDomain: 'localhost:3000',
});

// Create query client
export const queryClient = new QueryClient();
```

### 2. Setup API Route

**app/api/auth/[...nextauth]/route.ts**
```typescript
import { handlers } from '@/auth';

export const { GET, POST } = handlers;
```

### 3. Using Authentication

**Server Components**
```tsx
import { auth } from '@/auth';

export default async function Page() {
  const session = await auth();
  
  if (!session) {
    return <div>Not authenticated</div>;
  }
  
  return (
    <div>
      <p>Welcome {session.user.futurepass}</p>
      <p>EOA: {session.user.eoa}</p>
    </div>
  );
}
```

**Client Components**
```tsx
'use client';

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

export default function AuthButton() {
  const { data: session } = useSession();
  
  if (session) {
    return (
      <button onClick={() => signOut()}>
        Sign out
      </button>
    );
  }
  
  return (
    <button onClick={() => signIn('futureverse')}>
      Sign in with FuturePass
    </button>
  );
}
```

## Session Types

The session object includes FuturePass-specific fields:

```typescript
interface Session {
  user: {
    email?: string | null;
    name?: string | null;
    image?: string | null;
    eoa?: string;
    custodian?: string;
    chainId?: number;
    futurepass?: string;
    sub?: string;
    profile?: any;
  };
}
```

## Environment Variables

Add to your `.env.local`:

```env
AUTH_SECRET=your-auth-secret-here
```

Generate a secret using:
```bash
openssl rand -base64 32
```

## Integration with Auth UI

For a complete authentication UI experience, use [@futureverse/auth-ui](https://www.npmjs.com/package/@futureverse/auth-ui) which provides pre-built authentication components and flows for both Web3 wallets and FuturePass custodial authentication.


## Learn More

- [Next-Auth Documentation](https://authjs.dev/)
- [Futureverse Auth UI](https://www.npmjs.com/package/@futureverse/auth-ui)
- [Futureverse Auth React](https://www.npmjs.com/package/@futureverse/auth-react)