clearauth 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,235 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2025-12-12
+
+### 🎉 Major Refactor - Arctic Migration
+
+This release completely replaces Better Auth with a lightweight Arctic-based implementation, reducing bundle size from ~150KB to ~15KB while maintaining full feature parity.
+
+### Added
+
+- **Arctic OAuth 2.0** - Lightweight OAuth library for GitHub and Google (~10KB)
+- **Argon2id password hashing** - Secure, OWASP-recommended password hashing via @node-rs/argon2
+- **Oslo token generation** - Cryptographically secure token generation with base64url encoding
+- **Custom session management** - Database-backed sessions with configurable expiration
+- **Email/password authentication** - Built-in signup, login, email verification, password reset
+- **React hooks** - Custom `AuthProvider` and `useAuth` hook
+- **Session presets** - Three predefined session configs (default, short, long)
+- **CORS support** - Configurable CORS for browser clients
+- **Password validation** - Configurable minimum length and validation rules
+- **Email enumeration prevention** - Constant-time responses for password reset
+- **Comprehensive test coverage** - 67+ tests for security, validation, token generation
+
+### Changed
+
+- **BREAKING**: Replaced `better-auth` with `arctic`, `@node-rs/argon2`, `oslo`
+- **BREAKING**: `createClearAuth()` now returns `ClearAuthConfig` instead of Better Auth instance
+- **BREAKING**: Use `handleClearAuthRequest(request, config)` instead of `auth.handler`
+- **BREAKING**: React imports changed from `better-auth/react` to `clearauth/react`
+- **BREAKING**: Session config uses new format with `cookie` object:
+  ```ts
+  // Old (Better Auth)
+  session: { updateAge: 86400 }
+
+  // New (Arctic)
+  session: {
+    expiresIn: 604800,  // 7 days in seconds
+    cookie: {
+      name: 'session',
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: true,
+      path: '/'
+    }
+  }
+  ```
+- **BREAKING**: `baseUrl` parameter now required in `createClearAuth()`
+- Reduced bundle size from ~150KB to ~15KB (90% reduction)
+- Improved TypeScript types with full Kysely integration
+- Enhanced security with Argon2id and PKCE for OAuth
+
+### Removed
+
+- **BREAKING**: Removed `better-auth` dependency
+- **BREAKING**: Removed all Better Auth plugins and middleware
+- **BREAKING**: Removed `auth.handler` - use `handleClearAuthRequest()` instead
+- **BREAKING**: Removed automatic `process.env` reading (explicit config only)
+
+### Migration Guide
+
+**Install new dependencies:**
+```bash
+npm uninstall better-auth
+npm install arctic @node-rs/argon2 oslo
+```
+
+**Update server code:**
+```ts
+// Before (Better Auth)
+import { createClearAuth } from "clearauth"
+
+const auth = createClearAuth({
+  emailAndPassword: { enabled: true }
+})
+
+export const handler = auth.handler
+
+// After (Arctic)
+import { createClearAuth, handleClearAuthRequest } from "clearauth"
+
+const config = createClearAuth({
+  secret: process.env.AUTH_SECRET!,
+  baseUrl: process.env.BASE_URL!,
+  database: {
+    appId: process.env.MECH_APP_ID!,
+    apiKey: process.env.MECH_API_KEY!,
+  },
+})
+
+export async function handler(request: Request) {
+  return handleClearAuthRequest(request, config)
+}
+```
+
+**Update React code:**
+```ts
+// Before
+import { useSession, signIn } from "better-auth/react"
+
+// After
+import { useAuth } from "clearauth/react"
+
+function Component() {
+  const { user, signIn } = useAuth()
+  // ...
+}
+```
+
+**Update session config:**
+```ts
+// Before
+import { createClearAuth } from "clearauth"
+
+const auth = createClearAuth({
+  session: {
+    updateAge: 86400 // 1 day
+  }
+})
+
+// After
+import { createClearAuth, defaultSessionConfig } from "clearauth"
+
+const config = createClearAuth({
+  // ...
+  session: defaultSessionConfig, // or shortSessionConfig, longSessionConfig
+})
+```
+
+### Security Improvements
+
+- Argon2id password hashing (memory-hard, side-channel resistant)
+- PKCE for OAuth (prevents authorization code interception)
+- Email enumeration prevention (constant-time responses)
+- Base64url token encoding (URL-safe, no padding)
+- Improved CSRF protection with state validation
+
+## [0.2.0] - 2025-12-11
+
+### Added
+
+- **Cloudflare Workers compatibility**: Library now works in any JavaScript runtime (Cloudflare Workers, Deno, Bun, etc.)
+- **Cloudflare Pages support**: Full documentation including routing workarounds for Pages Functions
+- Explicit configuration API - all parameters must be passed directly to `createClearAuth()`
+- `isProduction` parameter for runtime environment detection
+- Comprehensive deployment guide comparing Next.js/Vercel, Cloudflare Workers, and Cloudflare Pages
+- Updated integration examples for Next.js (with `toNextJsHandler`), Vite, Cloudflare Workers, and Cloudflare Pages
+- Platform comparison table showing routing differences and best use cases
+
+### Installation
+
+> **Note:** Install with:
+> ```bash
+> npm install clearauth
+> ```
+
+### Changed
+
+- **BREAKING**: `secret` parameter is now **required** (was optional, no longer falls back to env vars)
+- **BREAKING**: `database` configuration is now **required** (no longer reads from env vars)
+- **BREAKING**: `createClearAuth()` no longer reads `process.env` automatically
+- **BREAKING**: `MechSqlClient` constructor now requires config object (no env var fallback)
+- **BREAKING**: `createMechKysely()` now requires config parameter (no env var fallback)
+- `createCookieConfig()` now accepts `isProduction` parameter instead of reading `process.env.NODE_ENV`
+- Updated all documentation to reflect explicit configuration requirements
+
+### Removed
+
+- **BREAKING**: Removed all `process.env` access from library code
+- **BREAKING**: Removed automatic environment variable detection
+- **BREAKING**: Removed env var fallback behavior in all constructors and factory functions
+
+### Migration Guide
+
+**Before (0.1.0):**
+```ts
+// Library automatically read from process.env
+const auth = createClearAuth({
+  emailAndPassword: { enabled: true }
+})
+```
+
+**After (0.2.0):**
+```ts
+// Explicit configuration required
+const auth = createClearAuth({
+  secret: process.env.BETTER_AUTH_SECRET!,
+  database: {
+    appId: process.env.MECH_APP_ID!,
+    apiKey: process.env.MECH_API_KEY!,
+  },
+  isProduction: process.env.NODE_ENV === "production",
+  emailAndPassword: { enabled: true }
+})
+```
+
+### Documentation
+
+- Added comprehensive [Deployment Guide](./DEPLOYMENT_GUIDE.md)
+- Added Cloudflare Workers and Pages examples
+- Updated README with runtime compatibility matrix
+- Added platform-specific routing documentation
+
+## [0.1.0] - 2025-11-26
+
+### Added
+
+- Initial release
+- Better Auth integration with Mech Storage PostgreSQL backend
+- HTTP-based database access via Mech Storage API
+- Kysely query builder with custom Mech dialect
+- React client (`useSession`, `signIn`, `signUp`, `signOut`)
+- Email/password authentication
+- Social login support (GitHub, Google via Better Auth)
+- Next.js App Router support
+- TypeScript support
+- Automatic environment variable configuration
+
+### Features
+
+- ✅ Better Auth out of the box
+- ✅ Mech Storage PostgreSQL as database backend
+- ✅ Works in Node.js and Cloudflare Workers (with manual config)
+- ✅ React hooks included
+- ✅ TypeScript-first
+
+### Documentation
+
+- README with quick start guide
+- Integration examples
+- API reference
+- Contributing guidelines

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dundas
+
+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

@@ -0,0 +1,417 @@
+# ClearAuth
+
+A lightweight authentication library built with **Arctic** (OAuth 2.0), pluggable password hashing, and **Mech Storage** as the database backend. Designed for teams who need production-ready auth with minimal bundle size (~15KB vs 150KB).
+
+## Features
+
+- **Arctic OAuth 2.0** - Lightweight OAuth with GitHub, Google support (~10KB)
+- **Pluggable password hashing** - Argon2id (Node) and PBKDF2 (Edge)
+- **Email/password authentication** - Built-in email verification and password reset
+- **Session management** - Secure, database-backed sessions with configurable expiration
+- **Mech Storage PostgreSQL** as the database (HTTP-based, no direct DB connection needed)
+- **Cloudflare Workers compatible** - Use `clearauth/edge` for OAuth + email/password without native dependencies
+- **React hooks** included (`useAuth`, `AuthProvider`)
+- **TypeScript-first** - Full type safety with Kysely query builder
+- **Minimal bundle size** - ~15KB (vs 150KB for Better Auth)
+
+## Installation
+
+> **Note:** Install from npm as `clearauth`.
+
+```bash
+npm install clearauth
+```
+
+Or using a specific version/tag:
+```bash
+npm install clearauth
+```
+
+Or add to `package.json`:
+```json
+{
+  "dependencies": {
+    "clearauth": "^0.3.0",
+    "arctic": "^2.0.0"
+  }
+}
+```
+
+## Entrypoints
+
+- **`clearauth`**
+  - **Environment:** universal
+  - **Default password hasher:** PBKDF2 (WebCrypto)
+- **`clearauth/node`**
+  - **Environment:** Node.js
+  - **Default password hasher:** Argon2id
+  - **API:** `createClearAuthNode(...)`
+- **`clearauth/edge`**
+  - **Environment:** Cloudflare Workers / edge runtimes
+  - **Default password hasher:** PBKDF2 (no native dependencies)
+  - **API:** `createClearAuth(...)`
+- **`clearauth/argon2`**
+  - **Environment:** Node.js
+  - **Export:** `createArgon2idPasswordHasher(...)` (use to explicitly override)
+
+## Migration Notes
+
+- **Password hashing default:** `createClearAuth(...)` defaults to PBKDF2 for portability (works in edge runtimes). If you want Argon2id by default in Node.js, use `createClearAuthNode(...)` from `clearauth/node`.
+- **Cookie-based sessions:** `/auth/register` and `/auth/login` set the session cookie on success. `/auth/logout` supports cookie-based logout. If your client previously stored `sessionId` outside cookies, update it to rely on cookies (recommended) or continue sending an explicit `sessionId` in the logout request body.
+
+## Quick Start
+
+### Server Setup
+
+Create `lib/auth.ts`:
+
+```ts
+import { createClearAuthNode } from "clearauth/node"
+
+export const authConfig = createClearAuthNode({
+  secret: process.env.AUTH_SECRET!,
+  baseUrl: process.env.BASE_URL || "http://localhost:3000",
+  database: {
+    appId: process.env.MECH_APP_ID!,
+    apiKey: process.env.MECH_API_KEY!,
+  },
+  oauth: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: `${process.env.BASE_URL}/api/auth/callback/github`,
+    },
+  },
+})
+```
+
+### Next.js App Router
+
+Create `app/api/auth/[...path]/route.ts`:
+
+```ts
+import { handleClearAuthRequest } from "clearauth"
+import { authConfig } from "@/lib/auth"
+
+export async function GET(request: Request) {
+  return handleClearAuthRequest(request, authConfig)
+}
+
+export async function POST(request: Request) {
+  return handleClearAuthRequest(request, authConfig)
+}
+```
+
+### Cloudflare Workers
+
+Create `src/auth.ts`:
+
+```ts
+import { createClearAuth, handleClearAuthEdgeRequest } from "clearauth/edge"
+
+export function createAuth(env: Env) {
+  return createClearAuth({
+    secret: env.AUTH_SECRET,
+    baseUrl: "https://your-worker.workers.dev",
+    database: {
+      appId: env.MECH_APP_ID,
+      apiKey: env.MECH_API_KEY,
+    },
+    isProduction: true,
+  })
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+
+    if (url.pathname.startsWith("/auth")) {
+      const config = createAuth(env)
+      return handleClearAuthEdgeRequest(request, config)
+    }
+
+    return new Response("Hello World")
+  }
+}
+```
+
+### React Client
+
+Wrap your app with `AuthProvider`:
+
+```tsx
+// app/providers.tsx
+"use client"
+
+import { AuthProvider } from "clearauth/react"
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <AuthProvider baseUrl="/api/auth">
+      {children}
+    </AuthProvider>
+  )
+}
+```
+
+Use in components:
+
+```tsx
+"use client"
+
+import { useAuth } from "clearauth/react"
+
+export function LoginButton() {
+  const { user, loading, signIn, signOut } = useAuth()
+
+  if (loading) return <p>Loading...</p>
+
+  if (user) {
+    return (
+      <div>
+        <p>Welcome, {user.email}!</p>
+        <button onClick={signOut}>Sign Out</button>
+      </div>
+    )
+  }
+
+  return (
+    <button onClick={() => signIn("user@example.com", "password")}>
+      Sign In
+    </button>
+  )
+}
+```
+
+## Configuration
+
+### Required Configuration
+
+All configuration must be passed explicitly to `createClearAuth()`:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `secret` | `string` | Yes | Secret for signing tokens (minimum 32 characters recommended) |
+| `baseUrl` | `string` | Yes | Your application's base URL (e.g., `https://example.com`) |
+| `database.appId` | `string` | Yes | Your Mech app UUID |
+| `database.apiKey` | `string` | Yes | Your Mech API key |
+| `isProduction` | `boolean` | No | Set to `true` in production (enables secure cookies) |
+
+### Optional Configuration
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `oauth` | `OAuthProvidersConfig` | OAuth provider configuration (GitHub, Google) |
+| `session` | `SessionConfig` | Session configuration (expiration, cookie settings) |
+| `password` | `PasswordConfig` | Password validation rules (minLength) |
+| `cors` | `CorsConfig` | CORS configuration for browser clients |
+
+### Session Presets
+
+Three session configurations are available:
+
+```ts
+import {
+  defaultSessionConfig,  // 7 days, sameSite: lax
+  shortSessionConfig,    // 1 hour, sameSite: strict
+  longSessionConfig      // 30 days, sameSite: lax
+} from "clearauth"
+
+const config = createClearAuth({
+  // ...
+  session: shortSessionConfig, // Use preset
+})
+```
+
+### Environment Variables (Recommended Pattern)
+
+**Node.js / Next.js (.env.local):**
+```bash
+AUTH_SECRET=your-secret-key-at-least-32-chars
+BASE_URL=http://localhost:3000
+MECH_APP_ID=550e8400-e29b-41d4-a716-446655440000
+MECH_API_KEY=your-mech-api-key
+
+# OAuth (optional)
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+```
+
+**Cloudflare Workers (wrangler.toml):**
+```toml
+[vars]
+BASE_URL = "https://your-worker.workers.dev"
+
+# Use `wrangler secret put` for sensitive values:
+# wrangler secret put AUTH_SECRET
+# wrangler secret put MECH_API_KEY
+# wrangler secret put GITHUB_CLIENT_SECRET
+```
+
+## API Reference
+
+### `createClearAuth(options)`
+
+Creates an authentication configuration object.
+
+```ts
+import { createClearAuth } from "clearauth"
+
+const config = createClearAuth({
+  secret: process.env.AUTH_SECRET!,
+  baseUrl: "https://example.com",
+  database: {
+    appId: process.env.MECH_APP_ID!,
+    apiKey: process.env.MECH_API_KEY!,
+  },
+  oauth: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: "https://example.com/auth/callback/github",
+    },
+  },
+  session: defaultSessionConfig,
+  password: { minLength: 12 },
+})
+```
+
+**Returns:** `ClearAuthConfig` - Configuration object to pass to `handleClearAuthRequest()`
+
+### `handleClearAuthRequest(request, config)`
+
+Universal request handler for all authentication routes.
+
+```ts
+import { handleClearAuthRequest } from "clearauth"
+
+const response = await handleClearAuthRequest(request, authConfig)
+```
+
+**Parameters:**
+- `request: Request` - Web standard Request object
+- `config: ClearAuthConfig` - Configuration from `createClearAuth()`
+
+**Returns:** `Promise<Response>` - Web standard Response object
+
+### React Hooks
+
+#### `<AuthProvider>`
+
+Wraps your app to provide authentication context.
+
+```tsx
+import { AuthProvider } from "clearauth/react"
+
+<AuthProvider baseUrl="/api/auth">
+  {children}
+</AuthProvider>
+```
+
+#### `useAuth()`
+
+Access authentication state and actions.
+
+```tsx
+import { useAuth } from "clearauth/react"
+
+const {
+  user,              // Current user or null
+  loading,           // Loading state
+  error,             // Error message or null
+  signIn,            // (email, password) => Promise<void>
+  signUp,            // (email, password, name?) => Promise<void>
+  signOut,           // () => Promise<void>
+  loginWithGithub,   // () => Promise<void>
+  loginWithGoogle,   // () => Promise<void>
+  refresh,           // () => Promise<void>
+} = useAuth()
+```
+
+## Authentication Routes
+
+All routes are handled by `handleClearAuthRequest()`:
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/auth/register` | POST | Email/password registration |
+| `/auth/login` | POST | Email/password login |
+| `/auth/logout` | POST | Sign out current user |
+| `/auth/session` | GET | Get current session |
+| `/auth/verify-email` | POST | Verify email with token |
+| `/auth/resend-verification` | POST | Resend verification email |
+| `/auth/request-reset` | POST | Request password reset |
+| `/auth/reset-password` | POST | Reset password with token |
+| `/auth/oauth/github` | GET | Initiate GitHub OAuth flow |
+| `/auth/callback/github` | GET | GitHub OAuth callback |
+| `/auth/oauth/google` | GET | Initiate Google OAuth flow |
+| `/auth/callback/google` | GET | Google OAuth callback |
+
+## How It Works
+
+1. **Arctic** handles OAuth 2.0 flows (GitHub, Google) with PKCE and state validation
+2. **Argon2id** hashes passwords securely (memory-hard, side-channel resistant)
+3. **Oslo** generates cryptographically secure tokens (base64url encoded)
+4. **Kysely** provides type-safe SQL queries to Mech Storage
+5. **Mech Storage** stores users, sessions, and OAuth accounts via HTTP API
+
+This architecture means:
+- No heavyweight auth frameworks required
+- Works in any JavaScript runtime (Node.js, Cloudflare Workers, Deno, Bun)
+- No direct database connections needed
+- Minimal bundle size (~15KB vs 150KB)
+- Full TypeScript type safety
+
+## Security Features
+
+- ✅ **Argon2id password hashing** - OWASP recommended, memory-hard algorithm
+- ✅ **Email enumeration prevention** - Constant-time responses for password reset
+- ✅ **CSRF protection** - State parameter validation in OAuth flows
+- ✅ **PKCE for OAuth** - Prevents authorization code interception
+- ✅ **Secure session cookies** - httpOnly, sameSite, secure flags
+- ✅ **Token expiration** - Configurable session and token TTLs
+- ✅ **Timing attack resistance** - Constant-time comparisons
+
+## Cloudflare Compatibility
+
+Compatible with Cloudflare Workers and Pages when using an HTTP-based database backend. Note that email/password uses `@node-rs/argon2` (native) and may require a Node runtime.
+
+- ✅ **No `process.env` usage** - All configuration is explicit
+- ✅ **Works with Workers `env` bindings** - Pass secrets from environment
+- ✅ **HTTP-based database** - No TCP connections required
+- ✅ **Edge-friendly** - No Node.js-specific APIs
+- ✅ **Web Standards** - Uses Request/Response objects
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun run test
+
+# Run tests in watch mode
+bun run test:watch
+
+# Build
+bun run build
+
+# Output appears in dist/
+```
+
+## Migration from Better Auth
+
+If migrating from Better Auth:
+
+1. Replace `better-auth` dependency with `arctic`, `@node-rs/argon2`, `oslo`
+2. Update `createClearAuth()` - returns `ClearAuthConfig` instead of auth instance
+3. Use `handleClearAuthRequest()` instead of `auth.handler`
+4. Update React imports from `better-auth/react` to `clearauth/react`
+5. Update session config - uses new format with `cookie` object
+
+See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for detailed migration steps.
+
+## License
+
+MIT

package/dist/auth/handler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Email/Password Authentication HTTP Handler
+ *
+ * Handles HTTP requests for email/password authentication:
+ * - POST /auth/register - User registration
+ * - POST /auth/verify-email - Email verification
+ * - POST /auth/login - User login
+ * - POST /auth/logout - Session deletion
+ * - POST /auth/request-reset - Request password reset
+ * - POST /auth/reset-password - Reset password with token
+ */
+import type { ClearAuthConfig } from '../types.js';
+/**
+ * Main authentication request handler
+ *
+ * Routes incoming requests to the appropriate handler based on the URL path.
+ *
+ * Supported routes:
+ * - GET  /auth/session - Get current user session
+ * - POST /auth/register - Register new user
+ * - POST /auth/verify-email - Verify email with token
+ * - POST /auth/resend-verification - Resend verification email
+ * - POST /auth/login - Login with email/password
+ * - POST /auth/logout - Logout user
+ * - POST /auth/request-reset - Request password reset
+ * - POST /auth/reset-password - Reset password with token
+ *
+ * @param request - HTTP request
+ * @param config - Clear Auth configuration
+ * @returns HTTP response
+ *
+ * @example
+ * ```ts
+ * const response = await handleAuthRequest(request, config)
+ * return response
+ * ```
+ */
+export declare function handleAuthRequest(request: Request, config: ClearAuthConfig): Promise<Response>;