hylekit 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,434 @@
+# HyleKit
+
+Distributed BetterAuth library for SvelteKit and Next.js with Google OAuth and Turso cloud database.
+
+> **Note:** HyleKit provides **only the authentication database**. You will need to provision your own separate database for storing application data.
+
+## Features
+
+- 🔐 **Google OAuth** - Simple Google login integration
+- 🌐 **Distributed Auth** - Each app runs auth locally, sharing a centralized Turso auth database
+- 📦 **Framework Adapters** - First-class support for SvelteKit and Next.js
+- 🗄️ **Turso/LibSQL** - Edge-friendly SQLite database for auth
+- 🔄 **Session Management** - Automatic session handling with cookies
+- 🚀 **BFF Pattern** - Built-in support for Backend-For-Frontend architecture with Express
+
+## Database Architecture
+
+HyleKit uses a **centralized authentication database** that all your applications connect to. This database stores:
+- User accounts
+- Sessions
+- OAuth tokens
+- Verification tokens
+
+**You must provision two databases:**
+
+| Database | Purpose | Provided by |
+|----------|---------|-------------|
+| **Hyle Auth Database** | Stores users, sessions, and auth data | HyleKit (shared Turso instance) |
+| **Your Application Database** | Stores your app's business data | You (separate database) |
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Your Application                                                │
+├──────────────────────────────┬──────────────────────────────────┤
+│  Hyle Auth Database          │  Your Application Database       │
+│  (Turso - provided by Hyle)  │  (Postgres, MySQL, SQLite, etc.) │
+│  ├── users                   │  ├── products                    │
+│  ├── sessions                │  ├── orders                      │
+│  ├── accounts                │  ├── posts                       │
+│  └── verification            │  └── ... your data               │
+└──────────────────────────────┴──────────────────────────────────┘
+```
+
+> **Important:** Your application database can use any database technology you prefer. HyleKit does not manage or interact with your application data—only authentication.
+
+## Installation
+
+```bash
+npm install hylekit
+```
+
+## Environment Variables
+
+```bash
+# Turso Database
+HYLE_DATABASE_URL=libsql://[db-name]-[org].turso.io
+HYLE_DATABASE_AUTH_TOKEN=your-turso-token
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# App URL
+PUBLIC_APP_URL=http://localhost:5173  # or your production URL
+```
+
+## Architecture
+
+HyleKit supports a BFF (Backend-For-Frontend) architecture:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Browser (Client FE)                                            │
+│  └── Uses: hyle.client (signIn, signOut, etc.)                  │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Next.js / SvelteKit Backend (BFF)                              │
+│  ├── Auth: hyle.server (getSession, handler, etc.)              │
+│  └── Calls Express via: hyle.bff (BffClient)                    │
+│      └── Attaches session as x-hyle-user/x-hyle-session headers │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Express Backend                                                │
+│  └── Uses: hyle.server.express.middleware()                     │
+│      └── Parses headers → req.authUser, req.authSession         │
+│      └── Optional: DB verification for service-to-service calls │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## SvelteKit Setup
+
+### 1. Create Auth Route Handler
+
+Create the auth API route to handle authentication requests:
+
+```typescript
+// src/routes/api/auth/[...auth]/+server.ts
+import hyle from "hylekit";
+
+export const { GET, POST } = hyle.server.sveltekit.handler;
+```
+
+### 2. Add Session Hook
+
+Add the handle hook to populate session data in `event.locals`:
+
+```typescript
+// src/hooks.server.ts
+import hyle from "hylekit";
+
+export const handle = hyle.server.sveltekit.createHandle();
+```
+
+### 3. Extend App.Locals Types
+
+Update your type definitions to include session data:
+
+```typescript
+// src/app.d.ts
+import type { SessionResult, UserInfo } from "hylekit";
+
+declare global {
+    namespace App {
+        interface Locals {
+            session: SessionResult;
+            user: UserInfo | null;
+        }
+    }
+}
+
+export {};
+```
+
+### 4. Use in Pages
+
+Access session data in your server load functions:
+
+```typescript
+// src/routes/+page.server.ts
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = async ({ locals }) => {
+    return {
+        user: locals.user,
+    };
+};
+```
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+    export let data;
+</script>
+
+{#if data.user}
+    <p>Welcome, {data.user.name}!</p>
+    <a href="/api/auth/sign-out">Sign out</a>
+{:else}
+    <a href="/api/auth/sign-in/google">Sign in with Google</a>
+{/if}
+```
+
+---
+
+## Next.js Setup (App Router)
+
+### 1. Create Auth Route Handler
+
+Create the auth API route to handle authentication requests:
+
+```typescript
+// app/api/auth/[...auth]/route.ts
+import hyle from "hylekit";
+
+export const { GET, POST } = hyle.server.nextjs.handler;
+```
+
+### 2. Use in Server Components
+
+Access session data directly in your server components:
+
+```typescript
+// app/page.tsx
+import hyle from "hylekit";
+
+export default async function Page() {
+    const session = await hyle.server.nextjs.getSession();
+    
+    if (!session) {
+        return (
+            <a href="/api/auth/sign-in/google">Sign in with Google</a>
+        );
+    }
+    
+    return (
+        <div>
+            <p>Welcome, {session.user.name}!</p>
+            <a href="/api/auth/sign-out">Sign out</a>
+        </div>
+    );
+}
+```
+
+### 3. Protected Routes
+
+Use the auth helpers to protect routes:
+
+```typescript
+// app/dashboard/page.tsx
+import hyle from "hylekit";
+import { redirect } from "next/navigation";
+
+export default async function DashboardPage() {
+    const isAuth = await hyle.server.nextjs.isAuthenticated();
+    
+    if (!isAuth) {
+        redirect("/api/auth/sign-in/google");
+    }
+    
+    const user = await hyle.server.nextjs.getUser();
+    
+    return <p>Dashboard for {user?.name}</p>;
+}
+```
+
+---
+
+## BFF Pattern with Express
+
+### 1. Setup Express Middleware
+
+Configure the Express middleware to parse authenticated requests:
+
+```typescript
+// express-app/src/app.ts
+import express from "express";
+import hyle from "hylekit";
+
+const app = express();
+
+// Option 1: Trust headers from BFF (internal calls only)
+app.use(hyle.server.express.middleware({
+    unauthenticatedRoutes: ["/health", "/public/*"],
+}));
+
+// Option 2: Verify sessions against DB (for service-to-service calls)
+app.use(hyle.server.express.middleware({
+    unauthenticatedRoutes: ["/health", "/public/*"],
+    verifySession: true,  // Checks session in Turso DB
+}));
+```
+
+### 2. Access Auth Context in Routes
+
+Use `req.authUser` and `req.authSession` in your route handlers:
+
+```typescript
+import type { AuthenticatedRequest } from "hylekit";
+
+app.get("/api/profile", (req: AuthenticatedRequest, res) => {
+    // authUser is always available on authenticated routes
+    res.json({
+        userId: req.authUser.id,
+        email: req.authUser.email,
+        name: req.authUser.name,
+    });
+});
+
+app.post("/api/settings", (req: AuthenticatedRequest, res) => {
+    // Access full session data
+    console.log("Session expires:", req.authSession.expiresAt);
+    
+    // Your business logic here
+    res.json({ success: true });
+});
+```
+
+### 3. Using Helper Functions
+
+```typescript
+import { isAuthenticated, getAuthContext } from "hylekit";
+
+// Type guard for optional auth routes
+app.get("/api/greeting", (req, res) => {
+    if (isAuthenticated(req)) {
+        res.json({ message: `Hello, ${req.authUser.name}!` });
+    } else {
+        res.json({ message: "Hello, guest!" });
+    }
+});
+
+// Get auth context with error handling
+app.post("/api/order", (req, res) => {
+    try {
+        const { user, session } = getAuthContext(req);
+        // Proceed with authenticated user
+    } catch (e) {
+        res.status(401).json({ error: "Not authenticated" });
+    }
+});
+```
+
+### 4. Call Express from Next.js/SvelteKit
+
+Use the BFF client to make authenticated calls from your frontend backend:
+
+```typescript
+// Next.js: app/api/data/route.ts
+import { createNextJsBff } from "hylekit";
+
+const bff = createNextJsBff(process.env.EXPRESS_API_URL!);
+
+export async function GET() {
+    // Session is automatically attached to the request
+    const data = await bff.get("/api/profile");
+    return Response.json(data);
+}
+```
+
+```typescript
+// SvelteKit: src/routes/api/data/+server.ts
+import { createSvelteKitBff } from "hylekit";
+import type { RequestHandler } from "./$types";
+
+const bff = createSvelteKitBff(process.env.EXPRESS_API_URL!);
+
+export const GET: RequestHandler = async (event) => {
+    // Use .with(event) to bind the request context
+    const data = await bff.with(event).get("/api/profile");
+    return new Response(JSON.stringify(data));
+};
+```
+
+### Middleware Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `unauthenticatedRoutes` | `string[]` | `[]` | Routes that skip authentication |
+| `verifySession` | `boolean` | `false` | Verify session against DB (for service-to-service) |
+| `required` | `boolean` | `true` | Return 401 for unauthenticated requests |
+
+### Route Pattern Examples
+
+```typescript
+unauthenticatedRoutes: [
+    "/health",           // Exact match
+    "/public/*",         // Matches /public/anything (single level)
+    "/api/webhooks/**",  // Matches /api/webhooks/a/b/c (deep)
+]
+```
+
+---
+
+## Database Schema
+
+HyleKit uses Drizzle ORM. You can import the schema definitions for use with Drizzle Kit or migration tools.
+
+```typescript
+// Import all schema definitions
+import hyle from "hylekit";
+
+const { user, session, account, verification } = hyle.schema;
+```
+
+---
+
+## API Reference
+
+The library exports a default `hyle` object containing:
+
+### `hyle.server`
+
+#### `hyle.server.sveltekit`
+- `handler`: `{ GET, POST }` route handlers.
+- `createHandle()`: Creates a SvelteKit handle hook.
+- `getSession(event)`: Get session from request event.
+- `isAuthenticated(event)`: Check if user is authenticated.
+- `makeAuthenticatedCall(fn)`: Wrapper to ensure authentication.
+
+#### `hyle.server.nextjs`
+- `handler`: `{ GET, POST }` route handlers.
+- `getSession()`: Get session from current request headers.
+- `isAuthenticated()`: Check if user is authenticated.
+- `getUser()`: Get current user object.
+- `makeAuthenticatedCall(fn)`: Wrapper to ensure authentication.
+
+#### `hyle.server.express`
+- `middleware(options)`: Express middleware for session verification.
+- `isAuthenticated(req)`: Type guard to check if request is authenticated.
+- `getAuthContext(req)`: Get `{ user, session }` from request (throws if not authenticated).
+
+### `hyle.client`
+
+#### `hyle.client.sveltekit`
+- `login`: Alias for `signIn`.
+- All `better-auth/svelte` client methods.
+
+#### `hyle.client.nextjs`
+- `login`: Alias for `signIn`.
+- All `better-auth/react` client methods.
+
+### `hyle.bff`
+
+#### `hyle.bff.createNextJsBff(config)`
+Creates a BFF client for Next.js that automatically attaches session headers.
+
+#### `hyle.bff.createSvelteKitBff(config)`
+Creates a BFF client for SvelteKit that automatically attaches session headers.
+
+### Types
+
+```typescript
+import type {
+    SessionResult,
+    SessionData,
+    UserInfo,
+    Session,
+    User,
+    BffClientConfig,
+    RequestOptions,
+    AuthenticatedRequest,
+    MiddlewareOptions,
+} from "hylekit";
+```
+
+## License
+
+ISC