based-auth/readme.md

A Next.js/Node.js authentication and wallet API kit for Ethereum and Solana, with utilities for serialization and contract interaction, designed for serverless and API route usage.

> **Note:**
> This package is for server-side (API, server actions, backend) use only.
> There are no frontend (React) components or hooks exported.
> Do not import this package in client-side code.

# based-auth (actions)

A Next.js/Node.js authentication and wallet API kit for Ethereum and Solana, with utilities for serialization and contract interaction, designed for serverless and API route usage.

---


## Features

- NextAuth-based multi-provider authentication (Google, GitHub, Twitter, EVM/Solana wallet)
- Social and wallet login support
- Secure server-side contract interaction endpoints (EVM/Solana)
- Serialization/deserialization helpers for cross-network data
- User profile management and keypair generation
- All API endpoints and helpers are SSR/serverless-friendly

---


## Installation

```bash
yarn add based-auth
```

> **Peer dependencies:**
>
> - `next-auth`
> - `ethers`
> - `@solana/web3.js`
> - `@coral-xyz/anchor`
> - `tweetnacl`
> - `bip39`
> - `shortid`
> - `based-shared` (if using shared types)

---


## Usage

### 1. API Route Handlers

You can use the provided handlers in your Next.js API routes or server actions.

```ts
// pages/api/auth/[...nextauth].ts
import { handlers } from "based-auth/actions";
export default handlers;
```

Or for app directory:

```ts
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "based-auth/actions";
export const { GET, POST } = handlers;
```

### 2. Auth Helpers

You can use the exported helpers for authentication and session management:

```ts
import { auth, signIn, signOut } from "based-auth/actions";

// Usage in server actions or API routes
const session = await auth();
await signIn(/* ... */);
await signOut(/* ... */);
```

### 3. Web3 Handler

For server-side contract interaction (social wallet, EVM, Solana):

```ts
import { basedAuthHandler } from "based-auth/actions";

// In your API route:
export const POST = basedAuthHandler;
```

- Supports operations: `"transfer"`, `"write-contract"` (see source for details)
- Only available to authenticated users with a social profile

### 4. Serialization Utilities

For encoding/decoding cross-network data:

```ts
import { serialize, deserialize } from "based-auth/actions";

const encoded = serialize({ value: 123n });
const decoded = deserialize(encoded, "eth"); // or "sol"
```

---


## Environment Variables

Set the following in your `.env`:

```
AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_TWITTER_ID=...
AUTH_TWITTER_SECRET=...
AUTH_SECRET=...
PREFIX_HASH=your_secret_for_keypair_generation
```

---


## API

### Exports

- `handlers` – NextAuth API route handlers (for Next.js API/app routes)
- `auth` – Helper to get the current session (async)
- `signIn` – Helper to sign in a user (async)
- `signOut` – Helper to sign out a user (async)
- `basedAuthHandler` – POST handler for server-side web3 operations (transfer, write-contract)
- `serialize` – Serialize cross-network data (bigint, BN, SolanaPublicKey)
- `deserialize` – Deserialize cross-network data

### Advanced/Utility (internal, but useful for extension)

- `saveSocialUser`, `saveWalletUser`, `updateOrCreateUserProfile` (user profile management)
- `createKeypairs` (deterministic keypair generation for EVM/Solana/Sui)

---


## Example: Next.js API Route

```ts
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "based-auth/actions";
export const { GET, POST } = handlers;
```

## Example: Server-side Web3

```ts
// app/api/web3/route.ts
import { basedAuthHandler } from "based-auth/actions";
export const POST = basedAuthHandler;
```

---


## Notes

- This package is **server-only**: do not use in client/browser code.
- All web3 operations are protected and require authentication.
- Serialization utilities are provided for safe cross-network data handling.
- User profile and keypair helpers are available for advanced use.

---


**For more details, see the source code in `src/actions/utils/`.**