@spfn/auth 0.1.0-alpha.0 → 0.1.0-alpha.86

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 INFLIKE Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -203,6 +203,256 @@ app.bind(myProtectedRoute, [authenticate], async (c) => {
 
 ---
 
+## Next.js Integration
+
+The `@spfn/auth/nextjs` adapter provides seamless authentication integration for Next.js applications with automatic JWT injection and session management.
+
+### Features
+
+- **Automatic JWT Generation** - Generates JWT from HttpOnly cookie sessions
+- **Server-Side Interceptor** - Auto-inject JWT in server components and API routes
+- **Client-Side Proxy** - Auto-inject JWT for browser requests via `/api/actions`
+- **High-Level Auth API** - Simple wrappers with automatic key generation
+- **Session Helpers** - Server-side session management utilities
+
+### Installation
+
+```typescript
+import { authApi } from '@spfn/auth/nextjs';
+```
+
+### 1. High-Level Auth API
+
+The `authApi` object provides simplified authentication functions with automatic key generation and session management:
+
+```typescript
+import { authApi } from '@spfn/auth/nextjs';
+
+// ✅ Register (automatic key generation + session)
+const result = await authApi.register({
+  email: 'user@example.com',
+  password: 'SecurePass123!',
+  verificationToken: '...' // from verification code
+});
+// → Automatically generates keypair, stores in session cookie
+
+// ✅ Login (automatic key generation + rotation)
+const result = await authApi.login({
+  email: 'user@example.com',
+  password: 'SecurePass123!'
+});
+// → Automatically generates new keypair, rotates old key
+
+// ✅ Logout (revokes current key)
+await authApi.logout();
+
+// ✅ Rotate Key (before 90-day expiry)
+await authApi.rotateKey();
+```
+
+**No manual key generation needed!** The `authApi` handles:
+- ES256 keypair generation
+- Public key registration with server
+- Private key storage in encrypted HttpOnly cookies
+- Automatic key rotation on login
+
+### 2. Server-Side JWT Injection
+
+For server components and API routes, use the `createAuthInterceptor`:
+
+```typescript
+// app/api/protected/route.ts
+import { UniversalClient } from '@spfn/core/client';
+import { createAuthInterceptor } from '@spfn/auth/nextjs';
+
+// Create client with auth interceptor
+const client = new UniversalClient({
+  baseURL: process.env.SPFN_API_URL!,
+  requestInterceptor: createAuthInterceptor()
+});
+
+export async function GET() {
+  // JWT is automatically injected from session cookie
+  const data = await client.call(someContract);
+  return Response.json(data);
+}
+```
+
+**How it works:**
+1. Reads `session` HttpOnly cookie
+2. Unseals session to get `privateKey`, `keyId`, `userId`
+3. Generates JWT signed with `privateKey`
+4. Adds `Authorization: Bearer <jwt>` header automatically
+
+### 3. Client-Side Proxy Setup
+
+For browser requests, set up the Next.js API Route proxy:
+
+```typescript
+// app/api/actions/[...path]/route.ts
+export {
+  GET,
+  POST,
+  PUT,
+  DELETE,
+  PATCH
+} from '@spfn/auth/nextjs/proxy';
+```
+
+Then use `UniversalClient` from browser:
+
+```typescript
+'use client';
+import { UniversalClient } from '@spfn/core/client';
+
+const client = new UniversalClient({
+  baseURL: '/api/actions' // Proxy endpoint
+});
+
+// Browser → /api/actions/user/profile → SPFN API (with JWT injected)
+const user = await client.call(getUserContract);
+```
+
+**How it works:**
+1. Browser makes request to `/api/actions/*`
+2. Proxy reads `session` cookie (server-side only)
+3. Generates JWT from session
+4. Forwards request to SPFN API with `Authorization` header
+5. Returns response to browser
+
+### 4. Session Helpers
+
+Direct session management utilities:
+
+```typescript
+import {
+  saveSession,
+  getSession,
+  clearSession
+} from '@spfn/auth/nextjs';
+
+// Save session data (encrypted HttpOnly cookie)
+await saveSession({
+  userId: '123',
+  privateKey: '...',
+  keyId: 'uuid',
+  algorithm: 'ES256'
+}, 60 * 60 * 24 * 7); // 7 days
+
+// Get current session
+const session = await getSession();
+console.log(session?.userId);
+
+// Clear session
+await clearSession();
+```
+
+### 5. JWT Helper (Manual Usage)
+
+Generate JWT from session manually if needed:
+
+```typescript
+import { generateJWTFromSession } from '@spfn/auth/nextjs';
+
+const jwt = await generateJWTFromSession();
+// → Returns signed JWT or null if no session
+```
+
+### Updated Middleware (No X-Key-Id Required)
+
+The authenticate middleware now extracts `keyId` from the JWT payload, so you **no longer need** to send the `X-Key-Id` header:
+
+```typescript
+// ❌ Old way (deprecated)
+fetch('/api/protected', {
+  headers: {
+    'Authorization': `Bearer ${jwt}`,
+    'X-Key-Id': keyId  // ← No longer needed!
+  }
+});
+
+// ✅ New way
+fetch('/api/protected', {
+  headers: {
+    'Authorization': `Bearer ${jwt}`  // keyId extracted from JWT
+  }
+});
+```
+
+The middleware flow:
+1. Decode JWT to extract `keyId` (without verification)
+2. Fetch public key from database using `keyId`
+3. Verify JWT signature with public key
+4. Validate user and attach to context
+
+### Complete Next.js Example
+
+```typescript
+// app/auth/login/route.ts
+import { authApi } from '@spfn/auth/nextjs';
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+
+  try {
+    const result = await authApi.login({ email, password });
+    return Response.json({ success: true, userId: result.userId });
+  } catch (error) {
+    return Response.json({ success: false, error: error.message }, { status: 401 });
+  }
+}
+
+// app/dashboard/page.tsx (Server Component)
+import { UniversalClient } from '@spfn/core/client';
+import { createAuthInterceptor } from '@spfn/auth/nextjs';
+
+const client = new UniversalClient({
+  baseURL: process.env.SPFN_API_URL!,
+  requestInterceptor: createAuthInterceptor()
+});
+
+export default async function Dashboard() {
+  // JWT automatically injected
+  const user = await client.call(getUserContract);
+
+  return <div>Welcome {user.email}</div>;
+}
+
+// app/profile/page.tsx (Client Component)
+'use client';
+import { UniversalClient } from '@spfn/core/client';
+
+const client = new UniversalClient({
+  baseURL: '/api/actions'
+});
+
+export default function Profile() {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    // Browser → Proxy → SPFN API (JWT auto-injected)
+    client.call(getUserContract).then(setUser);
+  }, []);
+
+  return <div>{user?.email}</div>;
+}
+```
+
+### Environment Variables
+
+```bash
+# Required for session encryption
+SPFN_AUTH_SESSION_SECRET=your-32-char-secret-key
+
+# SPFN API URL (server-side)
+SPFN_API_URL=http://localhost:8790
+
+# Public API URL (optional, for client-side)
+NEXT_PUBLIC_API_URL=http://localhost:8790
+```
+
+---
+
 ## Service Layer (Reusable Business Logic)
 
 The `@spfn/auth` package provides **service functions** that encapsulate all business logic, making it easy to create custom authentication flows while reusing the same secure logic.
@@ -1166,8 +1416,8 @@ if (shouldRotate) {
 
 ```bash
 # .env
-JWT_SECRET=your-secret-key-change-in-production  # For legacy tokens
-JWT_EXPIRES_IN=7d                                 # Token expiry
+SPFN_AUTH_JWT_SECRET=your-secret-key-change-in-production  # For legacy tokens
+SPFN_AUTH_JWT_EXPIRES_IN=7d                                 # Token expiry
 ```
 
 ---
@@ -1196,12 +1446,70 @@ This creates the auth schema with 8 tables:
 
 ### 2. Configure Environment Variables
 
+#### Core Settings (Required)
+
 ```bash
 # .env
-JWT_SECRET=your-secret-key-change-in-production
-JWT_EXPIRES_IN=7d
+
+# ========================================
+# Core Authentication Settings (Required)
+# ========================================
+
+# JWT Token Settings
+SPFN_AUTH_JWT_SECRET=your-secret-key-change-in-production  # JWT signing secret (REQUIRED)
+SPFN_AUTH_JWT_EXPIRES_IN=7d                                 # JWT token expiry (default: 7d)
+
+# Verification Token Settings
+SPFN_AUTH_VERIFICATION_TOKEN_SECRET=separate-secret-key     # Optional: separate secret for verification tokens
+                                                            # If not set, uses SPFN_AUTH_JWT_SECRET
+
+# Password Hashing
+SPFN_AUTH_BCRYPT_SALT_ROUNDS=10                            # bcrypt salt rounds (default: 10)
+                                                            # Higher = more secure but slower (10-12 recommended)
+
+# ========================================
+# Client-Side Settings (Optional)
+# ========================================
+
+# Session Management (for client-side session encryption)
+SPFN_AUTH_SESSION_SECRET=session-encryption-key             # Required if using client-side session features
+
+# API URL Configuration (for client-side API calls)
+SPFN_API_URL=http://localhost:8790                         # SPFN API server URL
+NEXT_PUBLIC_API_URL=http://localhost:8790                   # Next.js public API URL (takes precedence)
+
+# Environment
+NODE_ENV=production                               # production | development
 ```
 
+#### Admin Account Creation (Optional)
+
+See [Section 3: Create Initial Admin Accounts](#3-create-initial-admin-accounts-optional) below for details.
+
+d---
+
+### Legacy Environment Variables (Backward Compatibility)
+
+For backward compatibility, the package also supports legacy environment variable names without the `SPFN_AUTH_` prefix. The new prefixed versions take precedence:
+
+```bash
+# Legacy (still supported, but deprecated)
+JWT_SECRET=...
+JWT_EXPIRES_IN=...
+VERIFICATION_TOKEN_SECRET=...
+BCRYPT_SALT_ROUNDS=...
+SESSION_SECRET=...
+
+ADMIN_ACCOUNTS=...
+ADMIN_EMAILS=...
+ADMIN_PASSWORDS=...
+ADMIN_ROLES=...
+ADMIN_EMAIL=...
+ADMIN_PASSWORD=...
+```
+
+**Recommendation:** Use the new `SPFN_AUTH_*` prefixed variables to avoid conflicts with other packages.
+
 ### 3. Create Initial Admin Accounts (Optional)
 
 You can automatically create admin accounts on server startup using environment variables. Three formats are supported:
@@ -1212,7 +1520,7 @@ Allows full control over each account's configuration.
 
 ```bash
 # .env
-ADMIN_ACCOUNTS='[
+SPFN_AUTH_ADMIN_ACCOUNTS='[
   {
     "email": "super@example.com",
     "password": "super-password",
@@ -1249,14 +1557,14 @@ Quick setup for multiple accounts with basic configuration.
 
 ```bash
 # .env
-ADMIN_EMAILS=super@example.com,admin@example.com,user@example.com
-ADMIN_PASSWORDS=super-pass,admin-pass,user-pass
-ADMIN_ROLES=superadmin,admin,user  # Optional, defaults to 'user'
+SPFN_AUTH_ADMIN_EMAILS=super@example.com,admin@example.com,user@example.com
+SPFN_AUTH_ADMIN_PASSWORDS=super-pass,admin-pass,user-pass
+SPFN_AUTH_ADMIN_ROLES=superadmin,admin,user  # Optional, defaults to 'user'
 ```
 
 **Requirements:**
-- `ADMIN_EMAILS` and `ADMIN_PASSWORDS` must have the same number of items
-- `ADMIN_ROLES` is optional (defaults to `user` for each account)
+- `SPFN_AUTH_ADMIN_EMAILS` and `SPFN_AUTH_ADMIN_PASSWORDS` must have the same number of items
+- `SPFN_AUTH_ADMIN_ROLES` is optional (defaults to `user` for each account)
 - All accounts will have `passwordChangeRequired: true`
 
 ---
@@ -1267,8 +1575,8 @@ For backward compatibility, you can create a single superadmin account.
 
 ```bash
 # .env
-ADMIN_EMAIL=admin@example.com
-ADMIN_PASSWORD=secure-password
+SPFN_AUTH_ADMIN_EMAIL=admin@example.com
+SPFN_AUTH_ADMIN_PASSWORD=secure-password
 ```
 
 This creates a single account with: