@spfn/auth 0.2.0-beta.8 → 0.2.0-beta.81

package/README.md

@@ -1,65 +1,43 @@
-# @spfn/auth - Technical Documentation
+# @spfn/auth — Authentication, OAuth, and RBAC for SPFN
 
-**Version:** 0.1.0-alpha.88
-**Status:** Alpha - Internal Development
+Asymmetric client-signed JWT auth (ES256/RS256), OTP verification, OAuth 2.0 (pluggable
+provider registry; Google, GitHub, Kakao, and Naver built in), session cookies for Next.js, and runtime RBAC.
+Routes are exposed under the `/_auth/*` namespace and reached through a type-safe `authApi`
+client. Requires `@spfn/core`; Next.js is an optional peer (`^15 || ^16`).
 
-> **Note:** This is a technical documentation for developers working on the @spfn/auth package.
-> For user-facing documentation, see [SPFN Documentation](https://spfn.dev/docs).
+## Install
 
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Architecture](#architecture)
-- [Package Structure](#package-structure)
-- [Module Exports](#module-exports)
-- [Email & SMS Services](#email--sms-services)
-- [Email Templates](#email-templates)
-- [Server-Side API](#server-side-api)
-- [Database Schema](#database-schema)
-- [RBAC System](#rbac-system)
-- [Next.js Adapter](#nextjs-adapter)
-- [Testing](#testing)
-- [Development Workflow](#development-workflow)
-- [Known Issues](#known-issues)
-- [Roadmap](#roadmap)
-
----
-
-## Overview
-
-`@spfn/auth` is an authentication and authorization package for the SPFN framework, providing:
-
-- **Asymmetric JWT Authentication** - Client-signed tokens using ES256/RS256
-- **User Management** - Email/phone-based identity with bcrypt hashing
-- **Multi-Factor Authentication** - OTP verification via email/SMS
-- **Session Management** - Public key rotation with 90-day expiry
-- **Role-Based Access Control** - Flexible RBAC with runtime role/permission management
-- **Next.js Integration** - Session helpers and server-side guards
+```bash
+pnpm add @spfn/auth
+```
 
-### Design Principles
+## Import paths
 
-1. **Security First** - Asymmetric cryptography, no shared secrets
-2. **Type Safety** - Full TypeScript support with Typebox validation
-3. **Framework Integration** - Seamless SPFN plugin architecture
-4. **Extensibility** - Service layer for custom authentication flows
-5. **Developer Experience** - Clear separation of concerns, reusable components
+Five entry points (from `package.json` `exports`). Picking the wrong one breaks the build —
+`/server` and `/nextjs/*` pull in Node/`server-only` code and must never reach the browser bundle.
 
----
+```typescript
+import { authApi, authRouteMap }      from '@spfn/auth';          // isomorphic: client + route map + types/constants
+import { authRouter, authenticate }   from '@spfn/auth/server';   // SERVER ONLY: router, services, repos, middleware, helpers
+import { /* hooks/components */ }      from '@spfn/auth/client';   // browser only (currently empty — WIP)
+import { env, envSchema }             from '@spfn/auth/config';    // validated env proxy + schema
+import { InvalidCredentialsError }    from '@spfn/auth/errors';    // error classes + authErrorRegistry
+import '@spfn/auth/nextjs/api';                                    // SERVER: auto-registers RPC interceptors (side-effect)
+import { RequireAuth, getSession }    from '@spfn/auth/nextjs/server'; // SERVER: RSC guards, session helpers, OAuth handler
+import { OAuthCallback }              from '@spfn/auth/nextjs/client';  // 'use client' OAuth callback component
+```
 
-## Installation
+> Database entities (`users`, `userPublicKeys`, …) and all services/repositories are exported
+> from `@spfn/auth/server`, **not** from the root `@spfn/auth`.
 
-### 1. Install Package
+## Setup (4 wiring points)
 
-```bash
-pnpm add @spfn/auth
-```
+Auth needs four edits in the consuming app. All four are required for the flow to work end to end.
 
-### 2. Configure Server
+### 1. Lifecycle — `server.config.ts`
 
-#### Add Lifecycle to `server.config.ts`
+`createAuthLifecycle()` validates env before DB connect, then seeds admin accounts and
+initializes RBAC after the DB is ready. Pass custom roles/permissions here (see RBAC below).
 
 ```typescript
 import { defineServerConfig } from '@spfn/core/server';
@@ -68,1895 +46,651 @@ import { appRouter } from './router';
 
 export default defineServerConfig()
     .port(8790)
-    .host('0.0.0.0')
     .routes(appRouter)
-    .lifecycle(createAuthLifecycle())  // Add auth lifecycle
+    .lifecycle(createAuthLifecycle())
     .build();
 ```
 
-#### Register Router in `router.ts`
+### 2. Router + global middleware — `router.ts`
+
+`authRouter` (the package's `mainAuthRouter`) is merged via `.packages()`; `authenticate` is
+applied globally via `.use()`. Public routes opt out per-route with `.skip(['auth'])`.
 
 ```typescript
 import { defineRouter } from '@spfn/core/route';
-import { authRouter } from '@spfn/auth/server';
+import { authRouter, authenticate } from '@spfn/auth/server';
+import { getHealth } from './routes/health';
 
 export const appRouter = defineRouter({
-    // Auth routes (fixed namespace)
-    auth: authRouter,
+    getHealth,
+    // ...your routes
+})
+    .packages([authRouter])   // mounts /_auth/* and exposes routes on authApi
+    .use([authenticate]);     // global auth middleware
 
-    // ... your other routes
-});
+export type AppRouter = typeof appRouter;
 ```
 
-### 3. Configure Client (Next.js)
+### 3. Next.js interceptor — RPC proxy route
 
-#### Register Router Metadata and Errors in `api-client.ts`
+The interceptor handles session cookies, JWT signing, and key management automatically.
+Import it for its side-effect (it self-registers); it must run before the proxy is created.
 
 ```typescript
-import { createApi } from '@spfn/core/nextjs';
-import type { AppRouter } from '@/server/router';
-import { appMetadata as authAppMetadata } from "@spfn/auth";
-import { authErrorRegistry } from "@spfn/auth/errors";
-import { appMetadata } from '@/server/router.metadata';
-import { errorRegistry } from "@spfn/core/errors";
-
-export const api = createApi<AppRouter>({
-    metadata: { ...appMetadata, ...authAppMetadata },
-    errorRegistry: errorRegistry.concat(authErrorRegistry),
-});
-```
+// app/api/rpc/[routeName]/route.ts
+import '@spfn/auth/nextjs/api';        // side-effect: registers auth interceptors
+import { createRpcProxy } from '@spfn/core/nextjs/server';
+import { authRouteMap } from '@spfn/auth';
+import { routeMap } from '@/generated/route-map';
 
-### 4. Environment Variables
-
-```bash
-# Required
-SPFN_AUTH_JWT_SECRET=your-secret-key
-SPFN_AUTH_VERIFICATION_TOKEN_SECRET=your-verification-secret
-DATABASE_URL=postgresql://...
-
-# Next.js (required)
-SPFN_AUTH_SESSION_SECRET=your-32-char-secret
-
-# Optional
-SPFN_AUTH_JWT_EXPIRES_IN=7d
-SPFN_AUTH_BCRYPT_SALT_ROUNDS=10
-SPFN_AUTH_SESSION_TTL=7d
-
-# AWS SES (Email)
-SPFN_AUTH_AWS_REGION=ap-northeast-2
-SPFN_AUTH_AWS_SES_ACCESS_KEY_ID=AKIA...
-SPFN_AUTH_AWS_SES_SECRET_ACCESS_KEY=...
-SPFN_AUTH_AWS_SES_FROM_EMAIL=noreply@yourdomain.com
-
-# AWS SNS (SMS)
-SPFN_AUTH_AWS_SNS_ACCESS_KEY_ID=AKIA...
-SPFN_AUTH_AWS_SNS_SECRET_ACCESS_KEY=...
-SPFN_AUTH_AWS_SNS_SENDER_ID=MyApp
+export const { GET, POST } = createRpcProxy({ routeMap: { ...routeMap, ...authRouteMap } });
 ```
 
-### 5. Run Migrations
+### 4. Run migrations
 
 ```bash
-# Generate migrations (if needed)
-pnpm spfn db generate
-
-# Run migrations
+pnpm spfn db generate   # only if entities changed
 pnpm spfn db migrate
 ```
 
----
-
-## Architecture
-
-### High-Level Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     @spfn/auth Package                       │
-├─────────────────────────────────────────────────────────────┤
-│                                                               │
-│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
-│  │    Server     │  │    Next.js    │  │    Client     │   │
-│  │   (server.ts) │  │   (nextjs/*)  │  │  (client.ts)  │   │
-│  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘   │
-│          │                   │                   │           │
-│  ┌───────▼───────────────────▼───────────────────▼───────┐  │
-│  │              Common Types & Entities                   │  │
-│  │                   (index.ts)                           │  │
-│  └────────────────────────────────────────────────────────┘  │
-│                                                               │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Module Separation
-
-The package is split into three distinct entry points to ensure proper code separation:
-
-1. **Common Module** (`@spfn/auth`)
-   - Database entities (users, roles, permissions)
-   - TypeScript types and interfaces
-   - RBAC type definitions
-   - Can be imported anywhere (server/client)
-
-2. **Server Module** (`@spfn/auth/server`)
-   - Server-only code (marked with Node.js APIs)
-   - Routes, services, repositories
-   - Middleware, helpers (JWT, password)
-   - RBAC initialization
-   - **Never** import in client-side code
-
-3. **Client Module** (`@spfn/auth/client`)
-   - Client-only code (React hooks, components)
-   - Currently in development (placeholders only)
-   - **Never** import in server-side code
-
-4. **Next.js Adapter** (`@spfn/auth/nextjs/*`)
-   - Next.js-specific integrations
-   - `@spfn/auth/nextjs/api` - Interceptors for API routes
-   - `@spfn/auth/nextjs/server` - Server Components guards & session helpers
-
-### Asymmetric JWT Flow
-
-```
-┌──────────┐                                    ┌──────────┐
-│  Client  │                                    │  Server  │
-└────┬─────┘                                    └────┬─────┘
-     │                                               │
-     │ 1. Generate ES256 keypair                    │
-     │    (privateKey stored locally)               │
-     │                                               │
-     │ 2. POST /_auth/register                      │
-     │    { email, password, publicKey, keyId }     │
-     ├──────────────────────────────────────────────>│
-     │                                               │
-     │                            3. Store publicKey │
-     │                               (user_public_keys)
-     │                                               │
-     │ 4. Sign JWT with privateKey                  │
-     │    payload: { userId, keyId }                │
-     │                                               │
-     │ 5. Request with Authorization header         │
-     │    Authorization: Bearer <jwt>               │
-     ├──────────────────────────────────────────────>│
-     │                                               │
-     │                      6. Decode JWT → keyId   │
-     │                         Fetch publicKey      │
-     │                         Verify signature     │
-     │                                               │
-     │                                    7. Success │
-     │<──────────────────────────────────────────────┤
-     │                                               │
-```
-
-**Key Points:**
-- Server **never** knows the private key
-- Each client has a unique keypair
-- JWT verification uses stored public key
-- No shared secrets (unlike HMAC-based JWT)
-
----
-
-## Package Structure
-
-```
-packages/auth/
-├── dist/                      # Compiled output (tsup)
-│   ├── index.js              # Common exports
-│   ├── index.d.ts
-│   ├── server.js             # Server exports
-│   ├── server.d.ts
-│   ├── client.js             # Client exports (minimal)
-│   ├── client.d.ts
-│   ├── config/               # Configuration module
-│   ├── errors/               # Error classes
-│   ├── nextjs/               # Next.js adapter
-│   └── server/               # Server implementation
-│
-├── migrations/                # Drizzle database migrations
-│   └── *.sql
-│
-├── src/
-│   ├── index.ts              # Common entry point
-│   ├── server.ts             # Server entry point
-│   ├── client.ts             # Client entry point
-│   │
-│   ├── config/               # Configuration system
-│   │   ├── index.ts
-│   │   ├── schema.ts         # Env var schema
-│   │   └── types.ts
-│   │
-│   ├── errors/               # Error definitions
-│   │   ├── index.ts
-│   │   └── auth-errors.ts
-│   │
-│   ├── lib/                  # Shared code
-│   │   └── contracts/        # Typebox schemas
-│   │
-│   ├── server/               # Server-side implementation
-│   │   ├── entities/         # Drizzle ORM entities
-│   │   ├── services/         # Business logic layer
-│   │   ├── repositories/     # Database access layer
-│   │   ├── routes/           # HTTP route handlers
-│   │   ├── middleware/       # Auth middleware
-│   │   ├── helpers/          # JWT, password, context
-│   │   ├── rbac/             # RBAC types and builtins
-│   │   ├── lib/              # Server utilities
-│   │   ├── lifecycle.ts      # SPFN lifecycle hooks
-│   │   ├── setup.ts          # Initialization
-│   │   ├── logger.ts         # Logging
-│   │   └── types.ts          # Server types
-│   │
-│   ├── nextjs/               # Next.js adapter
-│   │   ├── api.ts            # Interceptor exports
-│   │   ├── server.ts         # Server Components guards
-│   │   ├── session-helpers.ts# Session management
-│   │   ├── interceptors/     # Request interceptors
-│   │   └── guards/           # Auth guards
-│   │
-│   └── client/               # Client-side (WIP)
-│       ├── hooks/            # React hooks (TODO)
-│       ├── store/            # Zustand store (TODO)
-│       └── components/       # UI components (TODO)
-│
-├── package.json              # Package configuration + SPFN plugin config
-├── tsup.config.ts            # Build configuration
-├── drizzle.config.ts         # Database migration config
-└── README.md                 # This file
-```
-
-### Layer Responsibilities
-
-#### 1. **Routes Layer** (`src/server/routes/`)
-- Thin HTTP handlers
-- Request validation (Typebox)
-- Delegates to services
-- Returns responses
-
-#### 2. **Services Layer** (`src/server/services/`)
-- Business logic
-- Transaction management
-- Reusable functions
-- Can be used outside of routes
-
-#### 3. **Repositories Layer** (`src/server/repositories/`)
-- Database access only
-- CRUD operations
-- No business logic
-- Drizzle ORM queries
-
-#### 4. **Helpers Layer** (`src/server/helpers/`)
-- Utility functions (JWT, password hashing)
-- Context accessors (getAuth, getUser)
-- Stateless operations
-
----
-
-## Module Exports
-
-### Common Module (`@spfn/auth`)
-
-**Entities:**
-```typescript
-import {
-  users,
-  userPublicKeys,
-  verificationCodes,
-  roles,
-  permissions,
-  rolePermissions,
-  userPermissions,
-  userInvitations,
-  userSocialAccounts,
-  userProfiles
-} from '@spfn/auth';
-```
-
-**Types:**
-```typescript
-import type {
-  User,
-  UserPublicKey,
-  VerificationCode,
-  Role,
-  Permission,
-  // ... etc
-} from '@spfn/auth';
-```
-
-**RBAC:**
-```typescript
-import {
-  BUILTIN_ROLES,
-  BUILTIN_PERMISSIONS,
-  BUILTIN_ROLE_PERMISSIONS
-} from '@spfn/auth';
-
-import type {
-  RoleConfig,
-  PermissionConfig,
-  InitializeAuthOptions,
-  BuiltinRoleName,
-  BuiltinPermissionName
-} from '@spfn/auth';
-```
-
----
-
-### Server Module (`@spfn/auth/server`)
-
-**Router:**
-```typescript
-import { authRouter } from '@spfn/auth/server';
-
-// Explicit registration in your app router
-export const appRouter = defineRouter({
-  auth: authRouter,  // Mounts at /_auth/*
-});
-```
-
-**Services:**
-```typescript
-import {
-  // Auth
-  checkAccountExistsService,
-  registerService,
-  loginService,
-  logoutService,
-  changePasswordService,
-
-  // Verification
-  sendVerificationCodeService,
-  verifyCodeService,
-
-  // Key Management
-  registerPublicKeyService,
-  rotateKeyService,
-  revokeKeyService,
-
-  // User
-  getUserByIdService,
-  getUserByEmailService,
-  getUserByPhoneService,
-  updateUserService,
-  updateLastLoginService,
-
-  // RBAC
-  initializeAuth,
-
-  // Permission
-  getUserPermissions,
-  hasPermission,
-  hasAnyPermission,
-  hasAllPermissions,
-  hasRole,
-  hasAnyRole,
-
-  // Role
-  createRole,
-  updateRole,
-  deleteRole,
-  addPermissionToRole,
-  removePermissionFromRole,
-  setRolePermissions,
-  getAllRoles,
-  getRoleByName,
-  getRolePermissions,
-
-  // Invitation
-  createInvitation,
-  getInvitationByToken,
-  getInvitationWithDetails,
-  validateInvitation,
-  acceptInvitation,
-  listInvitations,
-  cancelInvitation,
-  deleteInvitation,
-  expireOldInvitations,
-  resendInvitation,
-
-  // Session
-  getAuthSessionService,
-  getUserProfileService,
-
-  // Email
-  sendEmail,
-  registerEmailProvider,
-
-  // SMS
-  sendSMS,
-  registerSMSProvider,
-
-  // Email Templates
-  registerEmailTemplates,
-  getVerificationCodeTemplate,
-  getWelcomeTemplate,
-  getPasswordResetTemplate,
-  getInvitationTemplate,
-} from '@spfn/auth/server';
-```
-
-**Repositories:**
-```typescript
-import {
-  usersRepository,
-  keysRepository,
-  rolesRepository,
-  permissionsRepository,
-  verificationCodesRepository,
-  invitationsRepository,
-  rolePermissionsRepository,
-  userPermissionsRepository,
-  userProfilesRepository,
-} from '@spfn/auth/server';
-```
-
-**Middleware:**
-```typescript
-import {
-  authenticate,
-  requirePermissions,
-  requireRole,
-} from '@spfn/auth/server';
-
-// Usage
-app.bind(
-  myContract,
-  [authenticate, requirePermissions('user:delete')],
-  async (c) => {
-    // Handler
-  }
-);
-```
-
-**Helpers:**
-```typescript
-import {
-  // Context
-  getAuth,
-  getUser,
-  getUserId,
-  getKeyId,
-
-  // JWT
-  generateToken,       // Legacy server-signed (deprecated)
-  verifyToken,         // Legacy server-signed (deprecated)
-  verifyClientToken,   // Client-signed asymmetric JWT
-  decodeToken,         // Decode without verification (debugging)
-  verifyKeyFingerprint,
-
-  // Password
-  hashPassword,
-  verifyPassword,
-} from '@spfn/auth/server';
-```
-
-**Lifecycle:**
-```typescript
-import { createAuthLifecycle } from '@spfn/auth/server';
-
-// SPFN plugin lifecycle hooks
-const lifecycle = createAuthLifecycle();
-```
-
----
-
-### Client Module (`@spfn/auth/client`)
-
-> **Status:** Work in Progress - Placeholders only
-
-```typescript
-// Currently empty exports
-import {} from '@spfn/auth/client';
-```
-
-**Planned:**
-- React hooks (useAuth, useSession)
-- Zustand store
-- UI components (LoginForm, etc.)
-
----
-
-### Configuration Module (`@spfn/auth/config`)
-
-```typescript
-import { env, envSchema } from '@spfn/auth/config';
-
-// Access environment variables (validated at startup)
-console.log(env.SPFN_AUTH_JWT_SECRET);
-console.log(env.SPFN_AUTH_JWT_EXPIRES_IN);
-console.log(env.SPFN_AUTH_BCRYPT_SALT_ROUNDS);
-
-// envSchema can be used for custom validation
-```
-
----
+The API client needs no auth-specific config. `authApi` is also available standalone:
+
+```typescript
+import { authApi } from '@spfn/auth';
+const session = await authApi.getAuthSession.call({});   // → GET /_auth/session
+```
+
+## Environment variables
+
+Set across **two files** by audience. Server-only secrets go in `.env.server`; values the
+Next.js runtime needs (session cookie crypto) go in `.env.local`. Names only below — supply
+real secret values out of band, never commit them.
+
+| Var | File | Required | Notes |
+|-----|------|----------|-------|
+| `DATABASE_URL` | both | yes | Postgres connection |
+| `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` | `.env.server` | yes | OTP / verification token signing |
+| `SPFN_AUTH_SESSION_SECRET` | `.env.local` | yes | ≥32 chars, AES-256 session cookie encryption (validated: entropy/unique-char checks) |
+| `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` | `.env.server` | web OAuth | OAuth token keyring: comma-separated `<keyId>:<base64-32-byte-key>` entries; first key is active |
+| `SPFN_API_URL` | `.env.local` | — | default `http://localhost:8790` |
+| `SPFN_AUTH_SESSION_TTL` | both | — | default `7d` (e.g. `7d`, `12h`, `45m`) |
+| `SPFN_AUTH_JWT_SECRET` / `SPFN_AUTH_JWT_EXPIRES_IN` | `.env.server` | — | legacy server-signed JWT mode only |
+| `SPFN_AUTH_BCRYPT_SALT_ROUNDS` | `.env.server` | — | default `12` (native bcrypt, off the event loop) |
+| `SPFN_AUTH_COOKIE_SECURE` | both | — | override Secure flag (defaults to `NODE_ENV==='production'`) |
+| `SPFN_AUTH_ADMIN_*` | `.env.server` | — | admin seeding (see below) |
+| `SPFN_AUTH_GOOGLE_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | enables Google OAuth when both set |
+| `SPFN_AUTH_GOOGLE_SCOPES` | `.env.server` | — | comma-separated; default `email,profile` |
+| `SPFN_AUTH_GOOGLE_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/google/callback` — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
+| `SPFN_AUTH_KAKAO_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | REST API key enables Kakao Login; secret is included when configured |
+| `SPFN_AUTH_KAKAO_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scope `account_email`; callback `/_auth/oauth/kakao/callback` |
+| `SPFN_AUTH_NAVER_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | both values enable Naver Login |
+| `SPFN_AUTH_NAVER_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/naver/callback` |
+| `SPFN_AUTH_GITHUB_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | both values enable GitHub OAuth |
+| `SPFN_AUTH_GITHUB_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scopes `read:user,user:email`; callback `/_auth/oauth/github/callback` |
+| `SPFN_AUTH_GOOGLE_NATIVE_CLIENT_IDS` | `.env.server` | — | comma-separated client IDs accepted as native id_token audience (iOS/Android/web); enables Google native sign-in |
+| `SPFN_AUTH_APPLE_CLIENT_IDS` | `.env.server` | — | comma-separated Apple client IDs (bundle ID / Services ID); enables Apple native sign-in |
+| `SPFN_AUTH_OAUTH_SUCCESS_URL` | `.env.server` | — | default `/auth/callback` |
+| `SPFN_AUTH_OAUTH_ERROR_URL` | `.env.server` | — | default `/auth/error?error={error}` |
+| `SPFN_AUTH_RESERVED_USERNAMES` / `_USERNAME_MIN_LENGTH` / `_USERNAME_MAX_LENGTH` | `.env.server` | — | username rules |
+| `NEXT_PUBLIC_SPFN_API_URL` / `NEXT_PUBLIC_SPFN_APP_URL` | `.env.local` | — | browser-facing URLs for OAuth redirects |
+
+Read validated values via `import { env } from '@spfn/auth/config'` (a proxy validated at
+startup). `envSchema` carries descriptions/defaults.
+
+### Admin seeding
+
+`createAuthLifecycle()` creates admin accounts on startup from env, in priority order. Seeded
+accounts are auto email-verified, `status: 'active'`, `passwordChangeRequired: true`.
+
+- **JSON (recommended):** `SPFN_AUTH_ADMIN_ACCOUNTS` — array of `{email, password, role?, phone?, passwordChangeRequired?}`. `role` defaults to `user` (`user` | `admin` | `superadmin`).
+- **CSV:** `SPFN_AUTH_ADMIN_EMAILS` + `SPFN_AUTH_ADMIN_PASSWORDS` + `SPFN_AUTH_ADMIN_ROLES`.
+- **Single (legacy):** `SPFN_AUTH_ADMIN_EMAIL` + `SPFN_AUTH_ADMIN_PASSWORD` → always `superadmin`.
+
+## Routes
+
+All routes mount at `/_auth/*` and are reached through `authApi.<name>.call({ body })`. Public
+routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-signed-jwt>`.
+
+| `authApi` method | HTTP | Auth | Purpose |
+|------------------|------|------|---------|
+| `checkAccountExists` | POST `/_auth/exists` | public | email/phone existence check |
+| `sendVerificationCode` | POST `/_auth/codes` | public | send 6-digit OTP |
+| `verifyCode` | POST `/_auth/codes/verify` | public | verify OTP → verification token |
+| `register` | POST `/_auth/register` | public | create user + register public key |
+| `login` | POST `/_auth/login` | public | password login + new session key |
+| `logout` | POST `/_auth/logout` | yes | revoke current key |
+| `rotateKey` | POST `/_auth/keys/rotate` | yes | rotate public key before 90-day expiry |
+| `changePassword` | PUT `/_auth/password` | yes | change password |
+| `getAuthSession` | GET `/_auth/session` | yes | current session/user |
+| `issueOneTimeToken` | POST | yes | short-lived token (e.g. SSE handshake) |
+| `checkUsername` / `updateUsername` / `updateLocale` | — | mixed | username availability/update, locale |
+| `getUserProfile` / `updateUserProfile` | — | yes | profile read/update |
+| `createInvitation` / `acceptInvitation` / `listInvitations` / `cancelInvitation` / `resendInvitation` / `deleteInvitation` / `getInvitation` | — | mixed | invitation flow |
+| `requestAccountDeletion` | POST `/_auth/deletion/request` | yes | request account deletion (re-auth gated) — see [Account Deletion & Recovery](#account-deletion--recovery) |
+| `cancelAccountDeletion` | POST `/_auth/deletion/cancel` | public | cancel a pending deletion (credential-based recovery) |
+| `listRoles` / `createAdminRole` / `updateAdminRole` / `deleteAdminRole` / `updateUserRole` | — | superadmin | admin RBAC management |
+| OAuth routes | — | — | see OAuth section |
+
+Auth uses **asymmetric, client-signed JWTs**: the client generates an ES256/RS256 keypair,
+sends the public key on register/login, signs request JWTs locally, and the server verifies
+with the stored public key (`keyId` carried in the JWT). The server never holds a private key.
+Keys expire after 90 days — rotate with `rotateKey`.
+
+### Writing protected routes (route DSL)
+
+This is the current SPFN route DSL — `route.<method>().input().use().skip().handler()` registered
+via `defineRouter`. Access auth state through the context helpers, not by reading raw context.
+
+```typescript
+import { route } from '@spfn/core/route';
+import { authenticate, requirePermissions, optionalAuth } from '@spfn/auth/server';
+import { getAuth, getOptionalAuth } from '@spfn/auth/server';
+
+// Protected (global `authenticate` already applies; helpers read the context)
+export const getMe = route.get('/me')
+    .handler(async (c) =>
+    {
+        const { user, userId, role, locale } = getAuth(c);
+        return { id: userId, email: user.email, role };
+    });
 
-### Errors Module (`@spfn/auth/errors`)
+// Permission-gated (all required); use requireAnyPermission for OR, requireRole for roles
+export const deleteUser = route.delete('/users/:id')
+    .use([authenticate, requirePermissions('user:delete')])
+    .handler(async (c) => { /* ... */ });
 
-```typescript
-import {
-  // Auth namespace (contains all error classes)
-  AuthError,
-
-  // Individual error classes
-  InvalidCredentialsError,
-  InvalidTokenError,
-  TokenExpiredError,
-  KeyExpiredError,
-  AccountDisabledError,
-  AccountAlreadyExistsError,
-  InvalidVerificationCodeError,
-  InvalidVerificationTokenError,
-  InvalidKeyFingerprintError,
-  VerificationTokenPurposeMismatchError,
-  VerificationTokenTargetMismatchError,
-  InsufficientPermissionsError,
-  InsufficientRoleError,
-
-  // Error registry for client-side error handling
-  authErrorRegistry,
-} from '@spfn/auth/errors';
+// Public + optional user context. optionalAuth auto-skips global 'auth' — no .skip needed
+export const getProducts = route.get('/products')
+    .use([optionalAuth])
+    .handler(async (c) =>
+    {
+        const auth = getOptionalAuth(c);   // AuthContext | undefined
+        return auth ? personalized(auth.userId) : publicList();
+    });
 ```
 
----
+Context helpers from `@spfn/auth/server`: `getAuth`, `getOptionalAuth`, `getUser`, `getUserId`,
+`getRole`, `getLocale`, `getKeyId`. Middleware: `authenticate`, `optionalAuth`,
+`requirePermissions`, `requireAnyPermission`, `requireRole`, `roleGuard`, `oneTimeTokenAuth`.
 
-### Next.js Adapter (`@spfn/auth/nextjs/*`)
-
-#### `@spfn/auth/nextjs/api`
-
-```typescript
-import {
-  authInterceptors,
-  loginRegisterInterceptor,
-  generalAuthInterceptor,
-  keyRotationInterceptor,
-} from '@spfn/auth/nextjs/api';
+## OAuth
 
-// Auto-registers interceptors on import
-import '@spfn/auth/nextjs/api';
-```
+OAuth uses a **pluggable provider registry** — not hardcoded branches. The built-in `google`,
+`github`, `kakao`, and `naver` web providers self-register on module load; `apple` provides native
+`id_token` sign-in. External packages add providers at runtime with `registerOAuthProvider()`.
+Google, GitHub, and Naver each require their client ID and secret; Kakao requires its REST API
+key (and sends its optional client secret when configured).
 
-#### `@spfn/auth/nextjs/server`
+Client flow: call `authApi.getGoogleOAuthUrl.call({ body: { returnUrl } })`, redirect the browser
+to the returned `authUrl`, and render `OAuthCallback` on your success page. The Next.js interceptor
+manages the keypair → pending-session-cookie → full-session handoff transparently.
 
-```typescript
-import {
-  // Guards (Server Components)
-  RequireAuth,
-  RequireRole,
-  RequirePermission,
-
-  // Auth Utils
-  getUserRole,
-  getUserPermissions,
-  hasAnyRole,
-  hasAnyPermission,
-
-  // Session Helpers
-  saveSession,
-  getSession,
-  clearSession,
-
-  // Types
-  type SessionData,
-  type PublicSession,
-  type SaveSessionOptions,
-} from '@spfn/auth/nextjs/server';
+```tsx
+// app/auth/callback/page.tsx
+export { OAuthCallback as default } from '@spfn/auth/nextjs/client';
 ```
 
-**Session Helpers Usage:**
 ```typescript
-// Save session (Server Actions / Route Handlers)
-await saveSession({
-  userId: '123',
-  privateKey: '...',
-  keyId: 'uuid',
-  algorithm: 'ES256',
+import { authApi } from '@spfn/auth';
+const { authUrl } = await authApi.getGoogleOAuthUrl.call({
+    body: {
+        returnUrl: '/dashboard',
+        metadata: { birthDate: '2000-01-01', termsAgreed: true },
+    },
 });
-
-// Get session (read-only, safe in Server Components)
-const session = await getSession();
-
-// Clear session
-await clearSession();
+window.location.href = authUrl;
 ```
 
-**Guard Usage:**
-```typescript
-// app/dashboard/page.tsx
-import { RequireAuth } from '@spfn/auth/nextjs/server';
-
-export default async function DashboardPage()
-{
-  return (
-    <RequireAuth redirectTo="/login">
-      <div>Protected content</div>
-    </RequireAuth>
-  );
-}
-```
-
----
-
-## Email & SMS Services
-
-### Email Service
+GitHub, Kakao, and Naver use the provider-generic URL route:
 
-The email service uses AWS SES by default, with fallback to console logging in development.
-
-**Send Email:**
 ```typescript
-import { sendEmail } from '@spfn/auth/server';
-
-await sendEmail({
-  to: 'user@example.com',
-  subject: 'Welcome!',
-  text: 'Plain text content',
-  html: '<h1>HTML content</h1>',
-  purpose: 'welcome',  // for logging
+const { authUrl } = await authApi.getProviderOAuthUrl.call({
+    params: { provider: 'github' }, // or 'kakao', 'naver'
+    body: {
+        returnUrl: '/dashboard',
+        metadata: { birthDate: '2000-01-01', termsAgreed: true },
+    },
 });
+window.location.href = authUrl;
+```
+
+Both convenience URL APIs seal `metadata` into the encrypted OAuth state. On a new social
+signup, the callback passes it to `beforeRegister` and `authRegisterEvent`; existing-account
+logins do not run the registration hook.
+
+Built-in OAuth routes: `POST /_auth/oauth/google/url`, `GET /_auth/oauth/google` (redirect),
+`GET /_auth/oauth/google/callback`, `POST /_auth/oauth/finalize`, `GET /_auth/oauth/providers`,
+plus the provider-generic `POST /_auth/oauth/start`. `getGoogleAccessToken(userId)` returns a
+valid Google access token (auto-refreshing via stored refresh token when near expiry; throws if
+no Google account is linked or no refresh token is available).
+
+Kakao's `is_email_valid` and `is_email_verified` claims are both required before its email can
+link an existing SPFN account. GitHub uses the primary email from `/user/emails` (needs the
+`user:email` scope) and treats it as verified only when GitHub marks it verified; without that
+scope it falls back to the public profile email, unverified. Naver provides an email address but no verified-email claim, so
+Naver login never links an existing account by email; new Naver users can verify and add their
+email through the application's normal onboarding flow. Until then, the OAuth account is identified
+by its provider and provider user ID, so its user row may have both email and phone unset.
+
+### OAuth callback origin (web app host + rewrite)
+
+The callback's CSRF check is a double-submit: the Next.js interceptor sets an `oauth_csrf`
+cookie on the **web app host**, and the callback compares it against the nonce sealed in the
+state. Host-only cookies never reach a different host, so **the provider callback must return
+to the web app origin** — redirect URIs default to
+`{NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL}/_auth/oauth/<provider>/callback`.
+
+The app forwards `/_auth/*` to the API with a standard rewrite (**required** — without it the
+callback 404s on the web host, including in local dev):
+
+```javascript
+// next.config.js
+const nextConfig = {
+    async rewrites()
+    {
+        return [
+            {
+                source: '/_auth/:path*',
+                destination: `${process.env.SPFN_API_URL}/_auth/:path*`,
+            },
+        ];
+    },
+};
 ```
 
-**Custom Email Provider:**
-```typescript
-import { registerEmailProvider } from '@spfn/auth/server';
-
-// Register SendGrid provider
-registerEmailProvider({
-  name: 'sendgrid',
-  sendEmail: async ({ to, subject, text, html }) => {
-    // Your SendGrid implementation
-    return { success: true, messageId: '...' };
-  },
-});
-```
+Register each **web app host** callback URL in its provider console, for example
+`https://app.example.com/_auth/oauth/kakao/callback` and
+`https://app.example.com/_auth/oauth/naver/callback`.
 
----
+The cookie name also carries a `_${PORT}` suffix from the process that set it (the Next.js
+process), which differs from the API process in a split deployment — the callback therefore
+matches every `spfn_oauth_csrf*` cookie candidate against the state nonce, so no PORT
+coordination is needed.
 
-### SMS Service
+One caveat: the direct `POST /_auth/oauth/start` flow (no Next.js interceptor) sets its CSRF
+cookie on the **API host**. If you use that flow in a split deployment, set
+the corresponding provider redirect URI explicitly to the API host callback instead.
 
-The SMS service uses AWS SNS by default.
+### Native social sign-in (mobile / web id_token)
 
-**Send SMS:**
-```typescript
-import { sendSMS } from '@spfn/auth/server';
+For native apps — and for Apple on Android/web, which has no native SDK — the client obtains an
+`id_token` from the platform SDK and posts it to **`POST /_auth/oauth/:provider/native`**. No
+authorization code, no client secret: the server verifies the id_token against the provider's
+JWKS (signature, issuer, audience, expiry, nonce), links/creates the user, and **registers the
+client's public key**. It returns `{ userId, keyId, isNewUser }` — *not* a token. The client mints
+its own Bearer client token by signing with the on-device private key (the same client-signs /
+server-verifies model as the rest of auth).
 
-await sendSMS({
-  phone: '+821012345678',  // E.164 format
-  message: 'Your code is: 123456',
-  purpose: 'verification',
-});
-```
+Enable per provider by declaring the accepted audiences: `SPFN_AUTH_GOOGLE_NATIVE_CLIENT_IDS` for
+Google (the web `SPFN_AUTH_GOOGLE_CLIENT_ID` is also accepted) and `SPFN_AUTH_APPLE_CLIENT_IDS` for
+Apple. Apple is native-only here — its web OAuth (code-exchange) methods throw.
 
-**Custom SMS Provider:**
 ```typescript
-import { registerSMSProvider } from '@spfn/auth/server';
-
-// Register Twilio provider
-registerSMSProvider({
-  name: 'twilio',
-  sendSMS: async ({ phone, message }) => {
-    // Your Twilio implementation
-    return { success: true, messageId: '...' };
-  },
+await authApi.oauthNative.call({
+    params: { provider: 'apple' },                 // or 'google'
+    body: { idToken, nonce, publicKey, keyId, fingerprint, algorithm: 'ES256', profile: { name } },
 });
+// → { userId, keyId, isNewUser }; client then signs its own ES256 Bearer token with keyId
 ```
 
----
+The `nonce` is the **raw** nonce the client used; Apple hashes it (SHA-256) into the token, so send
+the raw value for either provider. `profile.name` captures the name Apple returns only on first
+sign-in. Trade-off: skipping code exchange means no Apple refresh token / server-side revoke —
+revoke SPFN access by revoking the registered key instead.
 
-## Email Templates
+### Custom providers
 
-### Built-in Templates
+Implement `OAuthProvider` and register it. `SOCIAL_PROVIDERS` is `['google','apple','github','kakao','naver','superself']`. Implement the optional `verifyNativeIdToken(idToken, { nonce })` to support native id_token sign-in.
 
-| Template | Function | Purpose |
-|----------|----------|---------|
-| `verificationCode` | `getVerificationCodeTemplate` | Verification codes (registration, login, password reset) |
-| `welcome` | `getWelcomeTemplate` | Welcome email after registration |
-| `passwordReset` | `getPasswordResetTemplate` | Password reset link |
-| `invitation` | `getInvitationTemplate` | User invitation |
-
-**Usage:**
 ```typescript
-import { getVerificationCodeTemplate, sendEmail } from '@spfn/auth/server';
-
-const { subject, text, html } = getVerificationCodeTemplate({
-  code: '123456',
-  purpose: 'registration',
-  expiresInMinutes: 5,
-  appName: 'MyApp',
-});
+import {
+    registerOAuthProvider, getOAuthProvider, getRegisteredProviders,
+    oauthCallbackService,
+    type OAuthProvider, type NormalizedIdentity, type OAuthTokens,
+} from '@spfn/auth/server';
 
-await sendEmail({ to: 'user@example.com', subject, text, html });
+registerOAuthProvider(myProvider);   // same id re-registers (override)
 ```
 
----
-
-### Custom Templates
+### OAuth token encryption and key rotation
 
-Register custom templates to override defaults with your brand design:
+Web OAuth access and refresh tokens are encrypted at rest with AES-256-GCM. Token encryption is
+separate from session-cookie encryption: `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` is backend-only and
+must never be exposed to the Next.js process. Generate a key with `openssl rand -base64 32` and
+assign it a non-secret key ID:
 
-```typescript
-import { registerEmailTemplates } from '@spfn/auth/server';
-
-// Register at app initialization (e.g., server.config.ts)
-registerEmailTemplates({
-  // Override verification code template
-  verificationCode: ({ code, purpose, expiresInMinutes, appName }) => ({
-    subject: `[${appName}] Your verification code`,
-    text: `Your code: ${code}\nExpires in ${expiresInMinutes} minutes.`,
-    html: `
-      <div style="font-family: Arial, sans-serif;">
-        <img src="https://myapp.com/logo.png" alt="Logo" />
-        <h1>Verification Code</h1>
-        <div style="font-size: 32px; font-weight: bold;">${code}</div>
-        <p>This code expires in ${expiresInMinutes} minutes.</p>
-      </div>
-    `,
-  }),
-
-  // Override invitation template
-  invitation: ({ inviteLink, inviterName, roleName, appName }) => ({
-    subject: `${inviterName} invited you to ${appName}`,
-    text: `Accept invitation: ${inviteLink}`,
-    html: `
-      <h1>You're Invited!</h1>
-      <p>${inviterName} invited you to join ${appName} as ${roleName}.</p>
-      <a href="${inviteLink}">Accept Invitation</a>
-    `,
-  }),
-});
+```dotenv
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v2:<base64-32-byte-key>
 ```
 
-**Template Parameters:**
-
-| Template | Parameters |
-|----------|------------|
-| `verificationCode` | `code`, `purpose`, `expiresInMinutes?`, `appName?` |
-| `welcome` | `email`, `appName?` |
-| `passwordReset` | `resetLink`, `expiresInMinutes?`, `appName?` |
-| `invitation` | `inviteLink`, `inviterName?`, `roleName?`, `appName?` |
-
----
-
-## Server-Side API
-
-### Public Routes (No Authentication)
-
-All routes are automatically registered at `/_auth/*` via SPFN plugin system.
-
-#### `POST /_auth/exists`
+For zero-downtime rotation, prepend the new key and retain old keys for decryption:
 
-Check if account exists.
-
-**Request:**
-```typescript
-{
-  email?: string;
-  phone?: string;  // E.164 format
-}
-```
-
-**Response:**
-```typescript
-{
-  exists: boolean;
-  identifier: string;
-  identifierType: 'email' | 'phone';
-}
+```dotenv
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v3:<new-key>,v2:<old-key>
 ```
 
----
-
-#### `POST /_auth/codes`
+New writes use the first key. Reads using an older key, the legacy session-secret-derived `enc:v1`
+format, or historical plaintext are automatically re-encrypted with the active key. Keep every old
+key available until all rows have been read or explicitly migrated; removing a referenced key makes
+those tokens undecryptable. Ciphertext is bound to `provider`, `providerUserId`, and token type
+(`access` or `refresh`) with authenticated data, preventing ciphertext from being moved to another
+account or field.
 
-Send verification code.
-
-**Request:**
-```typescript
-{
-  target: string;           // Email or phone
-  targetType: 'email' | 'phone';
-  purpose: 'registration' | 'login' | 'password_reset';
-}
-```
+Deployments that need a KMS or per-account envelope encryption can call
+`configureOAuthTokenCipher()` from `@spfn/auth/server` before the server starts. The custom cipher
+receives the same account/token context and owns its key rotation policy.
 
-**Response:**
-```typescript
-{
-  success: boolean;
-  expiresAt: string;        // ISO 8601
-}
-```
+**Integration contract for custom providers:**
 
----
+- The built-in provider-generic callback route handles any registered provider. A custom callback is
+  only needed when the provider does not follow the standard `code` / `state` response contract.
+- If a custom callback calls `oauthCallbackService()` directly, wrap the route in `Transactional()`
+  (`import { Transactional } from '@spfn/core/db'`).
+- The provider `id` must be in `SOCIAL_PROVIDERS` (`enumText`, plain text — adding a value needs **no**
+  DB migration).
+- `auth.login` / `auth.register` events now carry any `SOCIAL_PROVIDERS` value in `provider` —
+  update any `switch(provider)` in subscribers.
 
-#### `POST /_auth/codes/verify`
+## Sessions (Next.js)
 
-Verify OTP code.
+Sessions are HttpOnly cookies encrypted with `SPFN_AUTH_SESSION_SECRET` (JWE), holding the
+client private key + `keyId` (`SessionData`: `{ userId, privateKey, keyId, algorithm }`). The
+interceptor reads them to sign outbound RPC JWTs. From `@spfn/auth/nextjs/server`:
 
-**Request:**
 ```typescript
-{
-  target: string;
-  targetType: 'email' | 'phone';
-  code: string;             // 6 digits
-  purpose: 'registration' | 'login' | 'password_reset';
-}
-```
+import { saveSession, getSession, clearSession } from '@spfn/auth/nextjs/server';
 
-**Response:**
-```typescript
-{
-  valid: boolean;
-  verificationToken?: string;  // 15min JWT for registration
-}
+await saveSession({ userId: '123', privateKey: '...', keyId: 'uuid', algorithm: 'ES256' });
+const session = await getSession();   // read-only, safe in Server Components
+await clearSession();
 ```
 
----
-
-#### `POST /_auth/register`
-
-Register new user.
+RSC guards (redirect when unmet) — `RequireAuth`, `RequireRole`, `RequirePermission`:
 
-**Request:**
-```typescript
-{
-  email?: string;
-  phone?: string;
-  verificationToken: string;  // From /codes/verify
-  password: string;           // Min 8 chars
-  publicKey: string;          // Base64 DER (SPKI)
-  keyId: string;              // UUID v4
-  fingerprint: string;        // SHA-256 hex (64 chars)
-  algorithm: 'ES256' | 'RS256';
-  keySize?: number;
-}
-```
+```tsx
+import { RequireAuth, RequireRole } from '@spfn/auth/nextjs/server';
 
-**Response:**
-```typescript
+export default async function AdminPage()
 {
-  userId: string;
-  email?: string;
-  phone?: string;
+    return (
+        <RequireAuth redirectTo="/login">
+            <RequireRole roles={['admin', 'superadmin']} redirectTo="/forbidden">
+                <Dashboard />
+            </RequireRole>
+        </RequireAuth>
+    );
 }
 ```
 
----
-
-#### `POST /_auth/login`
+Also exported: `getAuthSessionData`, `getUserRole`, `getUserPermissions`, `hasAnyRole`,
+`hasAnyPermission`, the OAuth pending-session helpers, and `createOAuthCallbackHandler`.
 
-User login.
+## RBAC
 
-**Request:**
-```typescript
-{
-  email?: string;
-  phone?: string;
-  password: string;
-  publicKey: string;          // New key for session
-  keyId: string;
-  fingerprint: string;
-  oldKeyId?: string;          // Revoke previous key
-  algorithm: 'ES256' | 'RS256';
-  keySize?: number;
-}
-```
+Built-in roles: `superadmin` (priority 100), `admin` (80), `user` (10). Built-in permissions:
+`auth:self:manage`, `user:read|write|delete|invite`, `rbac:role:manage`, `rbac:permission:manage`.
+Custom roles/permissions are declared on the lifecycle (preferred — runs on startup) or via
+`initializeAuth(options)`.
 
-**Response:**
 ```typescript
-{
-  userId: string;
-  email?: string;
-  phone?: string;
-  passwordChangeRequired: boolean;
-}
+createAuthLifecycle({
+    roles: [{ name: 'editor', displayName: 'Editor', priority: 30 }],
+    permissions: [{ name: 'post:publish', displayName: 'Publish Posts', category: 'content' }],
+    rolePermissions: { editor: ['post:publish'] },
+});
 ```
 
----
-
-### Authenticated Routes (Require JWT)
+Programmatic checks (server): `hasPermission`, `hasAnyPermission`, `hasAllPermissions`, `hasRole`,
+`hasAnyRole`, `getUserRole`, `getUserPermissions`. Runtime role admin: `createRole`, `updateRole`,
+`deleteRole`, `setRolePermissions`, `addPermissionToRole`, `removePermissionFromRole`,
+`getAllRoles`, `getRoleByName`, `getRolePermissions`.
 
-**Authentication:**
-- Header: `Authorization: Bearer <jwt>`
-- JWT payload must contain: `{ userId, keyId }`
-- Server extracts `keyId` from JWT, fetches public key, verifies signature
+## Events
 
----
+`@spfn/auth` emits decoupled events (via `@spfn/core/event`). Subscribe for welcome emails,
+analytics, onboarding, etc. Client-supplied `metadata` on register/OAuth flows is forwarded verbatim.
 
-#### `POST /_auth/logout`
-
-Logout and revoke current key.
-
-**Request:**
 ```typescript
-{}  // Empty body
-```
+import { authLoginEvent, authRegisterEvent, invitationCreatedEvent, invitationAcceptedEvent } from '@spfn/auth/server';
 
-**Response:**
-```typescript
+authRegisterEvent.subscribe(async ({ userId, email, provider, metadata }) =>
 {
-  success: boolean;
-}
+    if (email) await sendWelcome(email);
+});
 ```
 
----
+Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `InvitationCreatedPayload`,
+`InvitationAcceptedPayload`, `AuthDeletionRequestedPayload`, `AuthDeletionCancelledPayload`,
+`AuthDeletionCompletedPayload`. These events also bind to `@spfn/core/job` jobs via `.on(event)`.
 
-#### `POST /_auth/keys/rotate`
+## Registration gate (`beforeRegister`)
 
-Rotate public key before expiry (90 days).
+Events fire *after* the user exists — they cannot reject a registration. For server-enforced
+signup policy (age gate, invite-only domains, block lists) inject a validator with
+`configureAuth`; it runs **before the user row is created** on every registration channel:
+`credentials` (email/phone register), `oauth` (new-user social signup, web + native), and
+`invitation` (acceptance). Throwing rejects the registration; `RegistrationRejectedError` (403)
+is the recommended error. The hook receives the same `metadata` the app supplied to
+`register` / OAuth start / the invitation — never credentials.
 
-**Request:**
 ```typescript
-{
-  publicKey: string;          // New public key
-  keyId: string;              // New UUID
-  fingerprint: string;
-  algorithm: 'ES256' | 'RS256';
-  keySize?: number;
-}
-```
+import { configureAuth, RegistrationRejectedError } from '@spfn/auth/server';
 
-**Response:**
-```typescript
-{
-  success: boolean;
-  keyId: string;
-}
+configureAuth({
+    beforeRegister: async ({ channel, provider, email, phone, metadata }) =>
+    {
+        if (!isOldEnough(metadata?.birthDate))
+        {
+            throw new RegistrationRejectedError({ message: 'Age requirement not met' });
+        }
+    },
+});
 ```
 
----
-
-#### `PUT /_auth/password`
-
-Change password.
-
-**Request:**
-```typescript
-{
-  currentPassword: string;
-  newPassword: string;        // Min 8 chars
-}
-```
+Notes:
+- Runs after built-in checks (verification token, duplicate account) — existing error
+  precedence is unchanged, and the hook cannot be probed without a valid verification token.
+- Not called when an OAuth login links a social account to an existing user, nor for admin
+  seeding in `initializeAuth()`.
+- OAuth signups have no client-typed fields unless you pass `metadata` at OAuth start — decide
+  per channel (reject, or allow and collect during onboarding).
+- On the `oauth` channel `email` is the provider-reported address and may be **unverified**
+  (the created account then stores `email` as `null`). The context carries
+  `emailVerified` — an email-based allow/block policy must check it before trusting `email`.
+- The hook runs **inside the registration DB transaction** on every channel — keep it fast.
+  A slow call (e.g. an external policy API) holds a pooled DB connection open per signup.
+- On the **web** OAuth flow a rejection surfaces as the standard OAuth error redirect
+  (302 to the app's OAuth error URL, message only) — not a 403 JSON response. The native
+  OAuth flow, credentials, and invitation channels return the error status (403) directly.
+
+## One-Time Token
+
+For short-lived authenticated handshakes (e.g. SSE) where a `Bearer` header is awkward: issue
+with `authApi.issueOneTimeToken`, protect the consuming route with the `oneTimeTokenAuth`
+middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a custom TTL/store.
+
+## Account Deletion & Recovery
+
+Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate
+purge, and a pluggable app-data cleanup hook. Not covered by this feature: re-signup email
+blind-index/hashing (a purged account's email becomes reusable immediately — see the project's
+PII protection track for blind-index re-signup prevention), backup beyond-use handling, DSR
+intake/response workflows, and webhook fan-out — those are app/ops concerns.
+
+```
+active ──request (re-auth)──> pending_deletion ──grace period elapses (cron)──> deleted (anonymize) | row removed (hard-delete)
+  ^                                  │
+  └───────────cancel (re-auth)───────┘        immediate = grace period of 0, same pipeline
+```
+
+- **Request** — `POST /_auth/deletion/request` (authenticated). Step-up re-auth: password
+  holders confirm with `password`; OAuth-only/passwordless accounts confirm with a
+  `verificationToken` from `/_auth/codes` + `/_auth/codes/verify` (`purpose: 'account_deletion'`).
+  On success: status → `pending_deletion`, every active session key is revoked, a
+  `account_deletion_requests` audit row is created, `auth.deletion.requested` fires, and (if
+  the user has an email and `sendNotifications` is on) a notice is sent with the scheduled purge
+  date.
+- **Login is blocked while pending** — password login, OAuth login, and the `authenticate`
+  middleware all reject a `pending_deletion` account with `AccountPendingDeletionError` (403,
+  `details.purgeScheduledAt`) instead of the generic `AccountDisabledError`, so the client can
+  show a recovery prompt.
+- **Cancel (recovery)** — `POST /_auth/deletion/cancel` (public — sessions were revoked at
+  request time, so there's no Bearer token to authenticate with). Credential-based: email/phone
+  plus `password` or a fresh `verificationToken`. On success, status → `active`; the user still
+  needs to log in separately afterward.
+- **Purge job** — sweeps `account_deletion_requests` for rows past their grace period and
+  destroys the account. Register it explicitly (see below); it is **not** wired up by
+  `createAuthLifecycle()` automatically.
+- **Admin / GDPR-response entry points** — `requestAccountDeletionService(userId, { requestedBy: 'admin', immediate })`
+  and `purgeUserService(userId)` are exported for app-side admin routes / DSR handling; the app
+  owns the route and its authorization.
 
-**Response:**
 ```typescript
-{
-  success: boolean;
-}
-```
-
----
-
-## Database Schema
-
-### Core Tables
-
-#### `users`
-
-Main user identity table.
-
-```sql
-CREATE TABLE users (
-  id BIGSERIAL PRIMARY KEY,
-  email TEXT UNIQUE,
-  phone TEXT UNIQUE,
-  password_hash TEXT NOT NULL,
-  password_change_required BOOLEAN DEFAULT false,
-  role_id BIGINT REFERENCES roles(id) NOT NULL,
-  status TEXT NOT NULL CHECK (status IN ('active', 'inactive', 'suspended')),
-  email_verified_at TIMESTAMP,
-  phone_verified_at TIMESTAMP,
-  last_login_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-
-  CONSTRAINT users_identifier_check CHECK (
-    (email IS NOT NULL) OR (phone IS NOT NULL)
-  )
-);
-```
+import { defineServerConfig } from '@spfn/core/server';
+import { createAuthLifecycle, authJobRouter } from '@spfn/auth/server';
 
-**Key Points:**
-- At least one of `email` OR `phone` required
-- `passwordHash` is bcrypt ($2b$10$..., 60 chars)
-- `roleId` references roles table (NOT NULL)
-
----
-
-#### `user_public_keys`
-
-Stores client public keys for JWT verification.
-
-```sql
-CREATE TABLE user_public_keys (
-  id BIGSERIAL PRIMARY KEY,
-  user_id BIGINT REFERENCES users(id) ON DELETE CASCADE,
-  key_id TEXT UNIQUE NOT NULL,
-  public_key TEXT NOT NULL,
-  algorithm TEXT NOT NULL CHECK (algorithm IN ('ES256', 'RS256')),
-  fingerprint TEXT NOT NULL,
-  is_active BOOLEAN DEFAULT true,
-  created_at TIMESTAMP DEFAULT NOW(),
-  last_used_at TIMESTAMP,
-  expires_at TIMESTAMP NOT NULL,
-  revoked_at TIMESTAMP,
-  revoked_reason TEXT
-);
-
-CREATE INDEX idx_user_public_keys_user_id ON user_public_keys(user_id);
-CREATE INDEX idx_user_public_keys_key_id ON user_public_keys(key_id);
-CREATE INDEX idx_user_public_keys_is_active ON user_public_keys(is_active);
+export default defineServerConfig()
+    .lifecycle(createAuthLifecycle({
+        deletion: {
+            gracePeriodDays: 30,               // default; 0 = immediate
+            purgeStrategy: 'anonymize',        // default; or 'hard-delete'
+            allowSelfImmediate: false,         // default; self-service immediate: true
+            sendNotifications: true,           // default
+            onBeforePurge: async (user) =>
+            {
+                // throw to skip this user for the current sweep (retried next run)
+                await appDataCleanup(user.id);
+            },
+        },
+    }))
+    .jobs(authJobRouter)   // registers the daily (04:00 UTC) purge sweep
+    .routes(appRouter)
+    .build();
 ```
 
-**Key Points:**
-- `keyId` is client-generated UUID v4
-- `fingerprint` is SHA-256(publicKey) for verification
-- `expiresAt` defaults to 90 days from creation
-- `isActive` determines if key can be used
-
----
-
-#### `verification_codes`
+**Purge strategies:**
+
+- `anonymize` (default) — scrubs PII, keeps the row: `email` → `deleted-{publicId}@deleted.invalid`,
+  `phone`/`username`/`passwordHash` → `null`, `status` → `'deleted'`, `deletedAt`/`deletedBy` set
+  (`softDelete()` on `users`). Social accounts and public keys are deleted (frees the provider
+  link and revokes access), the profile's PII columns are cleared, and any leftover verification
+  codes for the original email/phone are removed. The freed email/phone can be re-registered
+  immediately.
+- `hard-delete` — physically removes the `users` row; child rows (`user_profiles`,
+  `user_public_keys`, `user_social_accounts`, `user_permissions`) cascade-delete via their FK.
+  The `account_deletion_requests` audit row survives either strategy — its `userId` FK is
+  `set null` (not cascade), by design, so "who requested/purged what, when" outlives the user row.
+
+The final "your account has been deleted" notice is sent **after** the purge transaction commits
+(never before, and never on a purge that aborted or rolled back — see below), using the address
+captured before the destructive step ran. This holds for `hard-delete` too: the row is already
+gone by send time, but the address was captured beforehand, so the notice still goes out.
+
+**Concurrency.** The purge job re-verifies the user is still `pending_deletion` on the write
+primary immediately before any destructive DML, inside the same transaction as the DML itself —
+closing the window between a stale read (the sweep's own batch, or replica lag) and a concurrent
+`cancel`. The `account_deletion_requests` claim (`markCompleted`) is a conditional `UPDATE ...
+WHERE status = 'pending'`; if a concurrent cancel already moved the row off `pending`, the claim
+matches zero rows and the purge aborts with no destructive DML and no overwritten audit row.
+
+**Cron schedule caveat.** `deletion.purgeCron` (default `0 4 * * *`) is stored for reference, but
+the static `authJobRouter` export above always runs on the *default* cron — `job(...).cron(...)`
+is fixed at module-import time, which happens before `createAuthLifecycle()` runs in your
+`server.config.ts`. For a non-default schedule, build the router yourself, after the
+`createAuthLifecycle()` call, and register that instead:
+
+```typescript
+import { createAuthDeletionJobRouter } from '@spfn/auth/server';
+
+// ... after .lifecycle(createAuthLifecycle({ deletion: { purgeCron: '0 3 * * *' } }))
+.jobs(createAuthDeletionJobRouter({ purgeCron: '0 3 * * *' }))
+```
+
+Register **only one** of `authJobRouter` / `createAuthDeletionJobRouter(...)` — both build a job
+named `auth.deletion.purge`, so registering both (e.g. the static export *and* a custom-cron
+router) double-registers the same job name against pg-boss instead of overriding it.
+
+## Pitfalls & anti-patterns
+
+- **Wrong entry point.** `@spfn/auth/server` and `@spfn/auth/nextjs/*` are server-only (Node /
+  `server-only`). Importing them in a client component breaks the build. Entities, services, and
+  repositories are on `/server`, not on root `@spfn/auth`.
+- **No `app.bind(contract, ...)`.** That contract pattern is removed. Use the route DSL
+  (`route.get().handler()` + `defineRouter`). Any docs/snippets using `app.bind` are stale.
+- **Custom error classes must be registered.** Add them to an `ErrorRegistry` (mirror
+  `authErrorRegistry` in `src/errors/index.ts`) and pass it to your `createApi({ errorRegistry })`,
+  or the client receives a generic error instead of the typed one.
+- **Two env files, by audience.** `SPFN_AUTH_SESSION_SECRET` lives in `.env.local` (Next.js needs
+  it for cookie crypto); `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` and
+  `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` live in `.env.server`. Token encryption keys are backend-only;
+  putting them in `.env.local` unnecessarily gives the Next.js process token-decryption authority.
+- **`SPFN_AUTH_SESSION_SECRET` is validated.** Minimum 32 chars plus entropy/unique-char checks —
+  a short or low-entropy value fails startup, not just a warning.
+- **Forgetting the interceptor import.** Without `import '@spfn/auth/nextjs/api'` in the RPC proxy
+  route, the client sends no `Authorization` header and every protected call 401s. The
+  `authenticate` middleware error message points here.
+- **Custom OAuth callback without `Transactional()`.** A failure mid-callback leaves an orphan
+  user. Always wrap the callback route in `Transactional()` and call `oauthCallbackService`.
+- **`sideEffects: false` tree-shakes the google provider.** The built-in provider self-registers
+  via a module side-effect; an aggressive bundler config can drop it. Don't mark this package's
+  imports side-effect-free.
+- **Public routes need an explicit opt-out.** With global `authenticate`, any route without
+  `.skip(['auth'])` (or `optionalAuth`, which auto-skips) requires a valid token.
+- **`SOCIAL_PROVIDERS` is plain `enumText`.** Adding a provider value needs no DB migration, but
+  every `switch(provider)` over login/register events must handle the new value.
+- **Email/SMS is not here.** It moved to `@spfn/notification` (`import { sendEmail, sendSMS } from
+  '@spfn/notification/server'`). Wire verification-code / invitation emails through its events.
+- **`authJobRouter` isn't registered for you.** `createAuthLifecycle()`'s `afterInfrastructure`
+  hook runs *before* `@spfn/core` initializes pg-boss and registers jobs, so the lifecycle has no
+  opportunity to auto-register the account-deletion purge job. Call `.jobs(authJobRouter)`
+  yourself — see [Account Deletion & Recovery](#account-deletion--recovery).
+- **`USER_STATUSES` gained `pending_deletion` / `deleted`.** Any code with a `switch(user.status)`
+  or an exhaustive status union must handle both — `enumText` is plain `text` with no DB `CHECK`,
+  so nothing enforces this at the database layer.
+
+## Complete example
+
+```typescript
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { createAuthLifecycle } from '@spfn/auth/server';
+import { appRouter } from './router';
 
-OTP codes for email/SMS verification.
+export default defineServerConfig()
+    .port(8790)
+    .routes(appRouter)
+    .lifecycle(createAuthLifecycle({
+        roles: [{ name: 'editor', displayName: 'Editor', priority: 30 }],
+        permissions: [{ name: 'post:publish', displayName: 'Publish Posts', category: 'content' }],
+        rolePermissions: { editor: ['post:publish'] },
+    }))
+    .build();
 
-```sql
-CREATE TABLE verification_codes (
-  id BIGSERIAL PRIMARY KEY,
-  target TEXT NOT NULL,
-  target_type TEXT NOT NULL CHECK (target_type IN ('email', 'phone')),
-  code TEXT NOT NULL,
-  purpose TEXT NOT NULL CHECK (purpose IN ('registration', 'login', 'password_reset')),
-  expires_at TIMESTAMP NOT NULL,
-  used_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW()
-);
+// router.ts
+import { defineRouter } from '@spfn/core/route';
+import { authRouter, authenticate } from '@spfn/auth/server';
+import { getMe } from './routes/me';
 
-CREATE INDEX idx_verification_codes_target ON verification_codes(target);
-```
+export const appRouter = defineRouter({ getMe })
+    .packages([authRouter])
+    .use([authenticate]);
+export type AppRouter = typeof appRouter;
 
-**Key Points:**
-- 6-digit numeric code
-- Expires in 5-10 minutes (configurable)
-- Single-use (marked via `usedAt`)
-
----
-
-### RBAC Tables
-
-#### `roles`
-
-```sql
-CREATE TABLE roles (
-  id BIGSERIAL PRIMARY KEY,
-  name TEXT UNIQUE NOT NULL,
-  display_name TEXT NOT NULL,
-  description TEXT,
-  is_builtin BOOLEAN DEFAULT false,
-  is_system BOOLEAN DEFAULT false,
-  is_active BOOLEAN DEFAULT true,
-  priority INTEGER NOT NULL,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
-```
+// app/api/rpc/[routeName]/route.ts
+import '@spfn/auth/nextjs/api';
+import { createRpcProxy } from '@spfn/core/nextjs/server';
+import { authRouteMap } from '@spfn/auth';
+import { routeMap } from '@/generated/route-map';
+export const { GET, POST } = createRpcProxy({ routeMap: { ...routeMap, ...authRouteMap } });
 
-**Built-in Roles:**
-- `user` (priority 10) - Default role
-- `admin` (priority 80)
-- `superadmin` (priority 100)
-
----
-
-#### `permissions`
-
-```sql
-CREATE TABLE permissions (
-  id BIGSERIAL PRIMARY KEY,
-  name TEXT UNIQUE NOT NULL,
-  display_name TEXT NOT NULL,
-  description TEXT,
-  category TEXT,
-  is_builtin BOOLEAN DEFAULT false,
-  is_system BOOLEAN DEFAULT false,
-  is_active BOOLEAN DEFAULT true,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
+// any client component
+import { authApi } from '@spfn/auth';
+const session = await authApi.getAuthSession.call({});
 ```
 
-**Built-in Permissions:**
-- `auth:self:manage`
-- `user:read`, `user:write`, `user:delete`
-- `rbac:role:manage`, `rbac:permission:manage`
-
----
-
-#### `role_permissions`
-
-Many-to-many mapping between roles and permissions.
-
-```sql
-CREATE TABLE role_permissions (
-  id BIGSERIAL PRIMARY KEY,
-  role_id BIGINT REFERENCES roles(id) ON DELETE CASCADE,
-  permission_id BIGINT REFERENCES permissions(id) ON DELETE CASCADE,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-
-  UNIQUE(role_id, permission_id)
-);
-```
-
----
-
-#### `user_permissions`
-
-User-specific permission overrides.
-
-```sql
-CREATE TABLE user_permissions (
-  id BIGSERIAL PRIMARY KEY,
-  user_id BIGINT REFERENCES users(id) ON DELETE CASCADE,
-  permission_id BIGINT REFERENCES permissions(id) ON DELETE CASCADE,
-  granted BOOLEAN NOT NULL,
-  reason TEXT,
-  expires_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-
-  UNIQUE(user_id, permission_id)
-);
-```
-
-**Use Cases:**
-- `granted: true` - Grant permission temporarily
-- `granted: false` - Revoke permission (even if role has it)
-- `expiresAt` - Temporary access with expiration
-
----
-
-### Supporting Tables
-
-#### `invitations`
-
-User invitation system.
-
-```sql
-CREATE TABLE invitations (
-  id BIGSERIAL PRIMARY KEY,
-  email TEXT NOT NULL,
-  token TEXT UNIQUE NOT NULL,
-  role_id BIGINT REFERENCES roles(id),
-  invited_by BIGINT REFERENCES users(id),
-  status TEXT CHECK (status IN ('pending', 'accepted', 'cancelled', 'expired')),
-  expires_at TIMESTAMP NOT NULL,
-  accepted_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW()
-);
-```
-
----
-
-#### `user_profiles`
-
-Extended user profile information.
-
-```sql
-CREATE TABLE user_profiles (
-  id BIGSERIAL PRIMARY KEY,
-  user_id BIGINT REFERENCES users(id) ON DELETE CASCADE UNIQUE,
-  first_name TEXT,
-  last_name TEXT,
-  display_name TEXT,
-  avatar_url TEXT,
-  bio TEXT,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
-```
-
----
-
-#### `user_social_accounts`
-
-OAuth provider accounts (future feature).
-
-```sql
-CREATE TABLE user_social_accounts (
-  id BIGSERIAL PRIMARY KEY,
-  user_id BIGINT REFERENCES users(id) ON DELETE CASCADE,
-  provider TEXT NOT NULL,
-  provider_id TEXT NOT NULL,
-  access_token TEXT,
-  refresh_token TEXT,
-  expires_at TIMESTAMP,
-  created_at TIMESTAMP DEFAULT NOW(),
-
-  UNIQUE(provider, provider_id)
-);
-```
-
----
-
-## RBAC System
-
-### Initialization
-
-```typescript
-import { initializeAuth } from '@spfn/auth/server';
-
-// Minimal setup (built-in roles only)
-await initializeAuth();
-
-// With presets
-await initializeAuth({
-  usePresets: true,  // Adds moderator, editor, viewer roles
-});
-
-// Custom roles and permissions
-await initializeAuth({
-  roles: [
-    {
-      name: 'content-creator',
-      displayName: 'Content Creator',
-      priority: 20,
-    },
-  ],
-  permissions: [
-    {
-      name: 'post:create',
-      displayName: 'Create Posts',
-      category: 'content',
-    },
-  ],
-  rolePermissions: {
-    'content-creator': ['post:create'],
-  },
-});
-```
-
----
-
-### Built-in System
-
-**Roles:**
-- `superadmin` (priority 100) - Full access
-- `admin` (priority 80) - User management
-- `user` (priority 10) - Self management
-
-**Permissions:**
-- `auth:self:manage` - Change password, rotate keys
-- `user:read`, `user:write`, `user:delete`
-- `rbac:role:manage`, `rbac:permission:manage`
-
----
-
-### Middleware Usage
-
-```typescript
-import { authenticate, requirePermissions, requireRole } from '@spfn/auth/server';
-
-// Single permission
-app.bind(
-  deleteUserContract,
-  [authenticate, requirePermissions('user:delete')],
-  async (c) => {
-    // Only users with user:delete permission
-  }
-);
-
-// Multiple permissions (all required)
-app.bind(
-  publishPostContract,
-  [authenticate, requirePermissions('post:write', 'post:publish')],
-  async (c) => {
-    // Needs both permissions
-  }
-);
-
-// Role-based
-app.bind(
-  adminDashboardContract,
-  [authenticate, requireRole('admin', 'superadmin')],
-  async (c) => {
-    // Admin or superadmin only
-  }
-);
-```
-
----
-
-### Programmatic Checks
-
-```typescript
-import { hasPermission, hasRole, getUserPermissions } from '@spfn/auth/server';
-
-const canPublish = await hasPermission(userId, 'post:publish');
-const isAdmin = await hasRole(userId, 'admin');
-const permissions = await getUserPermissions(userId);
-
-if (canPublish)
-{
-  // Allow publish
-}
-```
-
----
-
-### Runtime Role Management
-
-```typescript
-import { createRole, addPermissionToRole } from '@spfn/auth/server';
-
-// Create role
-const role = await createRole({
-  name: 'moderator',
-  displayName: 'Moderator',
-  priority: 40,
-  permissionIds: [1n, 2n],
-});
-
-// Add permission
-await addPermissionToRole(role.id, 5n);
-
-// Delete (system roles protected)
-await deleteRole(role.id);
-```
-
----
-
-## Next.js Adapter
-
-### Session Management
-
-The Next.js adapter provides encrypted HttpOnly cookie-based sessions.
-
-**Configuration:**
-```bash
-# .env
-SPFN_AUTH_SESSION_SECRET=your-32-char-secret
-SPFN_AUTH_SESSION_TTL=7d  # Optional, default 7d
-```
-
-**Session Data:**
-```typescript
-interface SessionData {
-  userId: string;
-  privateKey: string;    // Encrypted in cookie
-  keyId: string;
-  algorithm: 'ES256' | 'RS256';
-}
-```
-
----
-
-### Server Component Guards
-
-```typescript
-// app/admin/page.tsx
-import { RequireAuth, RequireRole } from '@spfn/auth/nextjs/server';
-
-export default async function AdminPage()
-{
-  return (
-    <RequireAuth redirectTo="/login">
-      <RequireRole roles={['admin', 'superadmin']} redirectTo="/forbidden">
-        <div>Admin Dashboard</div>
-      </RequireRole>
-    </RequireAuth>
-  );
-}
-```
-
----
-
-### Interceptors (API Routes)
-
-**Setup:**
-```typescript
-// Simply import to auto-register
-import '@spfn/auth/nextjs/api';
-```
-
-**How It Works:**
-1. Reads `session` HttpOnly cookie
-2. Unseals session data
-3. Generates JWT signed with `privateKey`
-4. Injects `Authorization: Bearer <jwt>` header
-
-**Target Routes:**
-- `/_auth/login`, `/_auth/register` - Login/register interceptor
-- `/_auth/keys/rotate` - Key rotation interceptor
-- All other authenticated routes - General auth interceptor
-
----
-
-## Testing
-
-### Setup Test Environment
-
-```bash
-# Start test database
-pnpm docker:test:up
-
-# Generate migrations
-pnpm db:generate
-
-# Run migrations (via @spfn/core)
-cd ../../
-pnpm spfn db migrate
-```
-
----
-
-### Run Tests
-
-```bash
-# All tests
-pnpm test
-
-# With coverage
-pnpm test:coverage
-
-# Route tests only
-pnpm test:routes
-
-# Watch mode
-pnpm test --watch
-```
-
----
-
-### Test Structure
-
-```
-src/
-├── __tests__/
-│   └── setup.ts              # Global test setup
-└── server/
-    ├── routes/
-    │   └── auth/
-    │       └── __tests__/
-    │           ├── login.test.ts
-    │           ├── register.test.ts
-    │           └── ...
-    └── services/
-        └── __tests__/
-            ├── auth.service.test.ts
-            └── ...
-```
-
----
-
-### Writing Tests
-
-```typescript
-import { describe, it, expect, beforeEach } from 'vitest';
-import { loginService } from '@/server/services';
-
-describe('loginService', () =>
-{
-  beforeEach(async () =>
-  {
-    // Setup test data
-  });
-
-  it('should login with valid credentials', async () =>
-  {
-    const result = await loginService({
-      email: 'test@example.com',
-      password: 'password123',
-      publicKey: '...',
-      keyId: '...',
-      fingerprint: '...',
-      algorithm: 'ES256',
-    });
-
-    expect(result.userId).toBeDefined();
-  });
-});
-```
-
----
-
-### Test Database
-
-**docker-compose.test.yml:**
-```yaml
-services:
-  postgres-test:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: spfn_auth_test
-      POSTGRES_USER: spfn
-      POSTGRES_PASSWORD: spfn_dev_password
-    ports:
-      - "5433:5432"
-```
-
-**Test env variables:**
-```bash
-DATABASE_URL=postgresql://spfn:spfn_dev_password@localhost:5433/spfn_auth_test
-```
-
----
-
-## Development Workflow
-
-### Initial Setup
-
-```bash
-# Install dependencies
-pnpm install
-
-# Generate migrations
-pnpm db:generate
-
-# Build package
-pnpm build
-```
-
----
-
-### Development
-
-```bash
-# Watch mode (auto-rebuild on changes)
-pnpm dev
-
-# Type checking
-pnpm type-check
-
-# Run tests
-pnpm test
-```
-
----
-
-### Build Process
-
-The package uses `tsup` for building:
-
-**tsup.config.ts:**
-```typescript
-export default defineConfig({
-  entry: {
-    index: 'src/index.ts',
-    server: 'src/server.ts',
-    client: 'src/client.ts',
-    // ... more entry points
-  },
-  format: ['esm'],
-  dts: true,
-  clean: true,
-  sourcemap: true,
-});
-```
-
-**Build outputs:**
-- `dist/index.js` + `dist/index.d.ts`
-- `dist/server.js` + `dist/server.d.ts`
-- `dist/client.js` + `dist/client.d.ts`
-- `dist/config/`, `dist/errors/`, `dist/nextjs/`
-
----
-
-### Database Migrations
-
-```bash
-# Generate new migration (after entity changes)
-pnpm db:generate
-
-# Apply migrations (via SPFN CLI)
-cd ../../
-pnpm spfn db migrate
-
-# View database
-pnpm spfn db studio
-```
-
-**Migration files:** `migrations/*.sql`
-
----
-
-### SPFN Plugin Integration
-
-**package.json:**
-```json
-{
-  "spfn": {
-    "schemas": ["./dist/server/entities/*.js"],
-    "routes": {
-      "basePath": "/_auth",
-      "dir": "./dist/server/routes"
-    },
-    "migrations": {
-      "dir": "./migrations"
-    }
-  }
-}
-```
-
-**How it works:**
-1. SPFN CLI discovers packages with `spfn` field
-2. Auto-loads database schemas
-3. Auto-registers routes at `basePath`
-4. Includes migrations in `db migrate` command
-
----
-
-### Code Style
-
-Follow the project's code style (see `/Users/launchscreen/PROJECTS/SPFN/workspaces/.claude/rules.md`):
-
-- **Brace placement:** Next line (Allman-style)
-- **Indentation:** 4 spaces
-- **Semicolons:** Always
-- **Type assertions:** Use `as`, not `<>`
-
-**Example:**
-```typescript
-export async function myFunction(): Promise<void>
-{
-    if (condition)
-    {
-        await operation();
-    }
-    else
-    {
-        handleError();
-    }
-}
-```
-
----
-
-### Environment Variables
-
-**Server-side:**
-```bash
-# Required
-SPFN_AUTH_JWT_SECRET=your-secret-key
-DATABASE_URL=postgresql://...
-
-# Optional
-SPFN_AUTH_JWT_EXPIRES_IN=7d
-SPFN_AUTH_BCRYPT_SALT_ROUNDS=10
-SPFN_AUTH_VERIFICATION_TOKEN_SECRET=separate-secret
-```
-
-**Next.js adapter:**
-```bash
-# Required
-SPFN_AUTH_SESSION_SECRET=your-32-char-secret
-
-# Optional
-SPFN_AUTH_SESSION_TTL=7d
-SPFN_API_URL=http://localhost:8790
-```
-
----
-
-### Debugging
-
-**Enable logging:**
-```typescript
-import { serverLogger } from '@/server/logger';
-
-serverLogger.info('Debug message', { context });
-serverLogger.error('Error occurred', error);
-```
-
-**Inspect database:**
-```bash
-pnpm spfn db studio
-```
-
-**Check migrations:**
-```bash
-ls migrations/
-```
-
----
-
-## Known Issues
-
-### 1. Client Crypto Functions Missing
-
-**Issue:** README documents `generateKeyPair` and `generateClientToken` in `@spfn/auth/client`, but they only exist in `@spfn/auth/server`.
-
-**Workaround:** Use server-side crypto functions or implement client-side crypto separately.
-
-**Status:** Needs design decision - keep server-only or implement browser-compatible version.
-
----
-
-### 2. Next.js Proxy Route Not Implemented
-
-**Issue:** Documentation mentions `@spfn/auth/nextjs/proxy` for client-side API proxying, but it doesn't exist.
-
-**Status:** Feature planned but not implemented. Current alternative: use server-side `createAuthInterceptor`.
-
----
-
-### 3. `lib/api` Client Functions Removed
-
-**Issue:** Old `src/lib/api/` directory was deleted during refactoring.
-
-**Status:** Intentional removal. Use services or HTTP routes directly.
-
----
-
-### 4. Test Coverage Below Target
-
-**Current:** ~83%
-**Target:** 90%+
-
-**Areas needing tests:**
-- Invitation service edge cases
-- RBAC permission checks
-- Key rotation scenarios
-- Session expiry handling
-
----
-
-## Roadmap
-
-### Short-term (Alpha → Beta)
-
-- [ ] **Client-side crypto** - Browser-compatible key generation
-- [ ] **Next.js proxy route** - Implement or remove from docs
-- [x] **High-level authApi** - Simplified Next.js auth functions (implemented in `@spfn/auth`)
-- [ ] **Test coverage** - Reach 90%+ coverage
-- [x] **Documentation** - Sync docs with actual code
-
----
-
-### Mid-term (Beta → v1.0)
-
-- [ ] **React hooks** - useAuth, useSession, usePermissions
-- [ ] **UI components** - LoginForm, RegisterForm, AuthProvider
-- [ ] **OAuth integration** - Google, GitHub, etc.
-- [ ] **2FA support** - TOTP/authenticator apps
-- [ ] **Password reset flow** - Complete email-based reset
-- [ ] **Email change flow** - Verification for email updates
-- [ ] **Phone change flow** - SMS verification for phone updates
-
----
-
-### Long-term (Post v1.0)
-
-- [ ] **Admin UI** - User/role/permission management dashboard
-- [ ] **Audit logging** - Track auth events
-- [ ] **Rate limiting** - Built-in protection against brute force
-- [ ] **Multi-tenancy** - Organization/workspace support
-- [ ] **SSO integration** - SAML, OIDC
-- [ ] **Biometric auth** - WebAuthn/FIDO2 support
-
----
-
-## Contributing
-
-### Before Contributing
-
-1. Read this documentation thoroughly
-2. Check existing issues/PRs
-3. Understand the architecture
-4. Follow code style guidelines
-
----
-
-### Pull Request Process
-
-1. **Create feature branch**
-   ```bash
-   git checkout -b feature/my-feature
-   ```
-
-2. **Make changes**
-   - Follow code style
-   - Add tests
-   - Update docs if needed
-
-3. **Run checks**
-   ```bash
-   pnpm type-check
-   pnpm test
-   pnpm build
-   ```
-
-4. **Commit with conventional commits**
-   ```bash
-   git commit -m "feat(auth): add password strength validation"
-   ```
-
-5. **Push and create PR**
-   ```bash
-   git push origin feature/my-feature
-   ```
-
----
-
-### Commit Message Format
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-**Types:**
-- `feat` - New feature
-- `fix` - Bug fix
-- `refactor` - Code refactoring
-- `test` - Test changes
-- `docs` - Documentation
-- `chore` - Maintenance
-
-**Example:**
-```
-feat(rbac): add permission inheritance
-
-Implement hierarchical permission inheritance where child roles
-automatically inherit parent role permissions.
-
-Closes #123
-```
-
----
-
-## Release Process
-
-### Version Naming
-
-- `0.1.0-alpha.x` - Alpha releases (current)
-- `0.1.0-beta.x` - Beta releases
-- `1.0.0` - Stable release
-
----
-
-### Publishing
-
-```bash
-# Alpha release
-pnpm run publish:alpha
-
-# Beta release
-pnpm run publish:beta
-
-# Production release
-pnpm run publish:latest
-```
-
-**Pre-publish checklist:**
-- [ ] All tests pass
-- [ ] Type checking passes
-- [ ] Build succeeds
-- [ ] CHANGELOG updated
-- [ ] Version bumped
-- [ ] Docs updated
-
----
-
-## Support
-
-### Internal Team
-
-- **Issues:** GitHub Issues
-- **Discussions:** GitHub Discussions
-- **Slack:** #spfn-auth channel
-
----
-
-## License
-
-MIT License - See LICENSE file for details.
-
----
+## Related
 
-**Last Updated:** 2025-12-07
-**Document Version:** 2.2.0 (Technical Documentation)
-**Package Version:** 0.1.0-alpha.88
+- `@spfn/core` — route DSL (`route`, `defineRouter`), `createApi`, env (`@spfn/core/env`),
+  errors (`ErrorRegistry`), db (`Transactional`), events, jobs.
+- `@spfn/notification` — email/SMS/push (verification codes, invitation emails).
+- Full guide: `docs/guides/authentication.md`.