@krutai/auth 0.2.3 → 0.4.1

package/AI_REFERENCE.md

@@ -3,203 +3,273 @@
 ## Package Overview
 
 - **Name**: `@krutai/auth`
-- **Version**: `0.1.9`
-- **Purpose**: Authentication package for KrutAI — wraps Better Auth with a `krutAuth` function and optional API key validation via `KrutAuth` class
+- **Version**: `0.4.0`
+- **Purpose**: Fetch-based authentication client for KrutAI — calls your server's `/lib-auth` routes (powered by better-auth + PostgreSQL on the server side)
 - **Entry**: `src/index.ts` → `dist/index.{js,mjs,d.ts}`
-- **Build**: `tsup` (CJS + ESM, all deps external)
+- **Build**: `tsup` (CJS + ESM, `krutai` external)
+
+## ⚠️ Critical Architecture Note for AI
+
+> All auth logic and database connectivity (PostgreSQL, etc.) lives on the server.
+> This package is a **pure HTTP client** that calls the server's `/lib-auth` routes.
+
+**Do NOT suggest any of the following for this package — they do not exist:**
+- `@krutai/auth/react`
+- `@krutai/auth/next-js`
+- `createAuthClient()`
+- `toNextJsHandler()`
+- `getBetterAuth()`
+- `betterAuthOptions` config key
+- `database` config key
+- Passing `new Database(...)` or `new Pool(...)` to `krutAuth()`
+
+**Do NOT suggest SQLite (`better-sqlite3`) usage.** The server side should use PostgreSQL.
 
 ## Dependency Architecture
 
 ```
-@krutai/auth@0.1.9
-├── dependency: krutai              ← API key validation (also peerDep)
-├── dependency: better-auth         ← auth engine (external in tsup)
-├── dependency: better-sqlite3      ← default SQLite adapter
-└── dependency: @types/better-sqlite3
+@krutai/auth@0.4.0
+└── dependency: krutai              ← API key validation (also peerDep)
+
+Your Server (separate codebase)
+├── better-auth                     ← Auth engine
+└── pg / postgres                   ← PostgreSQL adapter
 ```
 
-> **Important for AI**: Do NOT bundle `better-auth` or `krutai` inline (no `noExternal`). They are real dependencies and must stay external in tsup.
+## Full System Flow
+
+```mermaid
+sequenceDiagram
+    participant App as Consumer App (@krutai/auth)
+    participant Server as Your Server (/lib-auth)
+    participant BA as better-auth (server)
+    participant PG as PostgreSQL
+
+    App->>Server: POST /lib-auth/api/auth/sign-up/email<br/>Headers: Authorization: Bearer <apiKey>
+    Server->>Server: Validate API key
+    Server->>BA: Forward to better-auth handler
+    BA->>PG: INSERT user + session
+    PG-->>BA: OK
+    BA-->>Server: User + session
+    Server-->>App: JSON response { token, user }
+```
 
 ## File Structure
 
 ```
 packages/auth/
 ├── src/
-│   ├── index.ts     # Exports krutAuth function + KrutAuth class + validator re-exports
-│   ├── client.ts    # KrutAuth class (API-key-protected wrapper)
-│   ├── types.ts     # KrutAuthConfig, AuthSession, BetterAuthOptions
-│   ├── react.ts     # re-exports better-auth/react (createAuthClient, hooks)
-│   └── next-js.ts   # re-exports better-auth/next-js (toNextJsHandler)
-├── scripts/
-│   └── migrate.js   # postinstall: auto-migrates SQLite tables via better-auth
+│   ├── index.ts     # Exports krutAuth factory + KrutAuth class + types + validators
+│   ├── client.ts    # KrutAuth class (fetch-based auth client)
+│   └── types.ts     # KrutAuthConfig, auth params, auth response types
 ├── package.json
 ├── tsconfig.json
 └── tsup.config.ts
 ```
 
-## Sub-path Exports
-
-| Import | File | Purpose |
-|---|---|---|
-| `@krutai/auth` | `dist/index.js` | `krutAuth`, `KrutAuth`, validator re-exports |
-| `@krutai/auth/react` | `dist/react.js` | `createAuthClient`, hooks |
-| `@krutai/auth/next-js` | `dist/next-js.js` | `toNextJsHandler` |
-
 ## Main Exports
 
-### `krutAuth(options)` ← PRIMARY API
-
-Drop-in replacement for `betterAuth`. Users should always use this.
-
-**Always include `baseURL`** to avoid Better Auth base URL warnings:
+### `krutAuth(config)` ← FACTORY (recommended)
 
 ```typescript
 import { krutAuth } from "@krutai/auth";
-import Database from "better-sqlite3";
 
-export const auth = krutAuth({
-  database: new Database("./sqlite.db"),
-  emailAndPassword: { enabled: true },
-  baseURL: process.env.BETTER_AUTH_BASE_URL ?? "http://localhost:3000",
+const auth = krutAuth({
+  apiKey: process.env.KRUTAI_API_KEY!,  // or set KRUTAI_API_KEY env var
+  serverUrl: "https://krut.ai",          // your server URL
 });
-```
 
-### `KrutAuth` class ← API-KEY-PROTECTED WRAPPER
+await auth.initialize(); // validates API key against server
+```
 
-For when you need API key validation before initializing auth.
+### `KrutAuth` class ← CORE CLIENT
 
-```typescript
-import { KrutAuth } from "@krutai/auth";
+| Method | HTTP Call | Description |
+|---|---|---|
+| `initialize()` | validates API key | Must be called before other methods |
+| `signUpEmail(params)` | `POST /lib-auth/api/auth/sign-up/email` | Register a new user |
+| `signInEmail(params)` | `POST /lib-auth/api/auth/sign-in/email` | Authenticate a user |
+| `getSession(token)` | `GET /lib-auth/api/auth/get-session` | Retrieve session info |
+| `signOut(token)` | `POST /lib-auth/api/auth/sign-out` | Invalidate a session |
+| `request(method, path, body?)` | Any | Generic helper for custom endpoints |
+| `isInitialized()` | — | Returns `boolean` |
 
-const auth = new KrutAuth({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  betterAuthOptions: {
-    database: { provider: 'postgres', url: process.env.DATABASE_URL },
-    emailAndPassword: { enabled: true },
-  },
-});
+### Types
 
-await auth.initialize();
-const betterAuthInstance = auth.getBetterAuth();
+#### `KrutAuthConfig`
+```typescript
+interface KrutAuthConfig {
+  apiKey?: string;          // defaults to process.env.KRUTAI_API_KEY
+  serverUrl?: string;       // default: "http://localhost:8000"
+  authPrefix?: string;      // default: "/lib-auth"
+  validateOnInit?: boolean; // default: true
+}
 ```
 
-**Methods:**
-- `initialize(): Promise<void>` — validates API key + initializes Better Auth
-- `getBetterAuth(): Auth` — returns the Better Auth `Auth` instance
-- `isInitialized(): boolean`
-- `getApiKey(): string`
+#### `SignUpEmailParams` / `SignInEmailParams`
+```typescript
+interface SignUpEmailParams { email: string; password: string; name: string; }
+interface SignInEmailParams { email: string; password: string; }
+```
 
-### Types
+#### `AuthResponse`
+```typescript
+interface AuthResponse { token: string; user: AuthUser; [key: string]: unknown; }
+```
 
-#### `KrutAuthConfig`
+#### `AuthUser`
 ```typescript
-interface KrutAuthConfig {
-  apiKey: string;                              // REQUIRED
-  betterAuthOptions?: Partial<BetterAuthOptions>;
-  validateOnInit?: boolean;                    // default: true
-  validationEndpoint?: string;
+interface AuthUser {
+  id: string;
+  email: string;
+  name?: string;
+  emailVerified: boolean;
+  createdAt: string;
+  updatedAt: string;
+  [key: string]: unknown;
 }
 ```
 
-### Validator Re-exports (from `krutai`)
+#### `AuthSession`
+```typescript
+interface AuthSession { user: AuthUser; session: AuthSessionRecord; }
+interface AuthSessionRecord { id: string; userId: string; token: string; expiresAt: string; }
+```
 
-> **Note for AI assistants**: Only `validateApiKeyFormat`, `validateApiKeyWithService`, and `ApiKeyValidationError` are exported. `createApiKeyChecker` is **NOT exported**. Do not suggest it.
-> The API key validation is **format/length only** (not null, minimum length). There is no external API check call.
+### Validator Re-exports (from `krutai`)
 
 ```typescript
-// These are re-exported from krutai — NOT defined here
-export { validateApiKeyFormat, validateApiKeyWithService, ApiKeyValidationError } from 'krutai';
+export { validateApiKeyFormat, validateApiKey } from 'krutai';
 ```
 
 ## Usage Examples
 
-### Example 1: Standard Server Setup (recommended)
+### Example 1: Sign Up + Sign In
 ```typescript
 import { krutAuth } from "@krutai/auth";
-import Database from "better-sqlite3";
 
-export const auth = krutAuth({
-  database: new Database("./sqlite.db"),
-  emailAndPassword: { enabled: true },
-  baseURL: process.env.BETTER_AUTH_BASE_URL ?? "http://localhost:3000",
+const auth = krutAuth({
+  apiKey: process.env.KRUTAI_API_KEY!,
+  serverUrl: "https://krut.ai",
 });
-```
+await auth.initialize();
 
-### Example 2: Next.js Route Handler
-```typescript
-// app/api/auth/[...all]/route.ts
-import { auth } from "@/lib/auth";
-import { toNextJsHandler } from "@krutai/auth/next-js";
+// Sign up
+const { token, user } = await auth.signUpEmail({
+  email: "user@example.com",
+  password: "secret123",
+  name: "Alice",
+});
 
-export const { GET, POST } = toNextJsHandler(auth);
+// Sign in
+const result = await auth.signInEmail({
+  email: "user@example.com",
+  password: "secret123",
+});
+console.log("Token:", result.token);
 ```
 
-### Example 3: React Client
+### Example 2: Session Management
 ```typescript
-import { createAuthClient } from "@krutai/auth/react";
+// Get session
+const session = await auth.getSession(token);
+console.log("User:", session.user.email);
 
-export const authClient = createAuthClient({
-  baseURL: process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
-});
-export const { signIn, signUp, signOut, useSession } = authClient;
+// Sign out
+await auth.signOut(token);
 ```
 
-### Example 4: KrutAuth with API Key Validation
+### Example 3: Custom Endpoint
 ```typescript
-import { KrutAuth } from "@krutai/auth";
-
-const auth = new KrutAuth({
-  apiKey: process.env.KRUTAI_API_KEY!,
-  betterAuthOptions: { emailAndPassword: { enabled: true } },
+const data = await auth.request("POST", "/api/auth/some-custom-endpoint", {
+  someParam: "value",
 });
-await auth.initialize();
 ```
 
-### Example 5: Error Handling
+### Example 4: Error Handling
 ```typescript
-import { KrutAuth, ApiKeyValidationError } from "@krutai/auth";
+import { krutAuth, KrutAuthKeyValidationError } from "@krutai/auth";
 
 try {
-  const auth = new KrutAuth({ apiKey: "bad" });
+  const auth = krutAuth({ apiKey: "bad-key" });
   await auth.initialize();
 } catch (e) {
-  if (e instanceof ApiKeyValidationError) {
+  if (e instanceof KrutAuthKeyValidationError) {
     console.error("Invalid API key:", e.message);
   }
 }
 ```
 
-## Auto-Migration (postinstall)
+### Example 5: Skip validation in tests
+```typescript
+const auth = krutAuth({
+  apiKey: "test-key-minimum-10-chars",
+  serverUrl: "http://localhost:8000",
+  validateOnInit: false, // Skip server round-trip
+});
+// Ready to use immediately — no initialize() needed
+```
+
+## Server-side PostgreSQL Setup (NOT in this package)
+
+When a user asks about PostgreSQL + this auth package, the Postgres config goes on the **server**, not here:
+
+```typescript
+// server: lib/auth.ts
+import { betterAuth } from "better-auth";
+import { Pool } from "pg";
 
-`scripts/migrate.js` runs after `npm install` to create all required Better Auth SQLite tables automatically. This means users do NOT need to run any manual migration commands — sign-up and sign-in work out of the box.
+export const auth = betterAuth({
+  database: new Pool({ connectionString: process.env.DATABASE_URL }),
+  emailAndPassword: { enabled: true },
+  basePath: "/lib-auth",
+  baseURL: process.env.BETTER_AUTH_BASE_URL,
+  secret: process.env.BETTER_AUTH_SECRET,
+});
+```
 
-The script:
-1. Creates `sqlite.db` in the project root (if not present)
-2. Runs `better-auth migrate` to create all required tables
-3. Skips silently if the DB already exists and tables are up to date
+Required server env vars:
+- `DATABASE_URL` — PostgreSQL connection string (e.g. `postgresql://user:pass@host:5432/db`)
+- `BETTER_AUTH_BASE_URL` — Server base URL
+- `BETTER_AUTH_SECRET` — Session signing secret
+
+## Request Headers
+
+Every request from `KrutAuth` sends:
+```
+Content-Type: application/json
+Authorization: Bearer <apiKey>
+x-api-key: <apiKey>
+```
+
+`getSession` and `signOut` additionally send:
+```
+Cookie: better-auth.session_token=<sessionToken>
+```
 
-## tsup Configuration Notes
+## Known Limitations
 
-- `better-auth` → **external** (real dependency, NOT bundled)
-- `krutai` → **external** (peer dep, NOT bundled)
-- `better-sqlite3` → **external** (real dependency)
-- `react`, `react-dom`, `next` → external
+1. **`getSession`/`signOut` use cookie-based auth** — may not work in all server-to-server contexts if the server strips cookies
+2. **`AuthResponse` is missing `session`** — better-auth returns `{ token, user, session }` but the type only declares `{ token, user }`. Access `session` via the `[key: string]: unknown` index signature
+3. **`dist/index.d.ts` may be missing** — Run `npm run build` inside `packages/auth` if TypeScript types are not resolving
 
 ## Important Notes
 
-1. **Always set `baseURL`**: Pass `baseURL: process.env.BETTER_AUTH_BASE_URL` in `krutAuth()` options
-2. **Use `krutAuth` not `betterAuth`**: The public API is `krutAuth`. `betterAuth` is an internal implementation detail
-3. **Validator lives in `krutai`**: Never add a local `validator.ts` — import from `krutai`
-4. **No `noExternal` for `better-auth` or `krutai`**: They must stay external in tsup
-5. **`getBetterAuth()` returns `Auth`**: Uses the `Auth` type from `better-auth`, not `ReturnType<typeof betterAuth>`
+1. **No local database** — All auth logic runs on your server — this package is a pure HTTP client
+2. **No SQLite** — Do not use `better-sqlite3` with this package or its server. Use PostgreSQL
+3. **API key in headers** — Every request sends `Authorization: Bearer <key>` and `x-api-key` headers
+4. **Server prefix** — Auth routes are prefixed with `/lib-auth` by default (configurable via `authPrefix`)
+5. **Call `initialize()` first** — Must validate API key before calling auth methods (unless `validateOnInit: false`)
+6. **Same pattern as ai-provider** — Works identically to `KrutAIProvider` — construct, initialize, call methods
 
 ## Related Packages
 
-- `krutai` — Core utilities and API validation (peer dep)
-- `@krutai/rbac` — Role-Based Access Control
+- `krutai` — Core utilities and API key validation (peer dep)
+- `@krutai/ai-provider` — AI provider (same fetch-based pattern)
+- `@krutai/db-service` — DB config service client
 
 ## Links
 
-- Better Auth Docs: https://www.better-auth.com/docs
 - GitHub: https://github.com/AccountantAIOrg/krut_packages
 - npm: https://www.npmjs.com/package/@krutai/auth
+- Better Auth PostgreSQL docs: https://www.better-auth.com/docs/adapters/postgresql