@kuratchi/auth 0.0.1

package/src/core/plugin.ts

@@ -0,0 +1,178 @@
+/**
+ * @kuratchi/auth — Core plugin system
+ * Enables modular, composable authentication middleware
+ */
+
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Base context available to all plugins
+ * Maps to KuratchiJS RouteContext — direct env access, no SvelteKit indirection
+ */
+export interface PluginContext {
+  /** The incoming Request (standard Web API) */
+  request: Request;
+  /** Cloudflare Worker env — D1, KV, R2, DO, etc. */
+  env: Record<string, any>;
+  /** Parsed URL */
+  url: URL;
+  /** Request-scoped state (shared across middleware/plugins) */
+  locals: Record<string, any>;
+  /** Auth-specific env values resolved from env bindings */
+  authEnv: AuthEnv;
+}
+
+/**
+ * Context available after session is resolved
+ */
+export interface SessionContext extends PluginContext {
+  session: any;
+  user: any;
+}
+
+/**
+ * Context available when handling response
+ */
+export interface ResponseContext extends SessionContext {
+  response: Response;
+}
+
+/**
+ * Auth environment — resolved from Cloudflare Worker env bindings
+ */
+export interface AuthEnv {
+  AUTH_SECRET: string;
+  ORIGIN?: string;
+  RESEND_API_KEY?: string;
+  EMAIL_FROM?: string;
+  GOOGLE_CLIENT_ID?: string;
+  GOOGLE_CLIENT_SECRET?: string;
+  GITHUB_CLIENT_ID?: string;
+  GITHUB_CLIENT_SECRET?: string;
+  TURNSTILE_SECRET?: string;
+  TURNSTILE_SITE_KEY?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Auth plugin interface
+ * Plugins can hook into different lifecycle stages
+ */
+export interface AuthPlugin {
+  /** Unique plugin name */
+  name: string;
+
+  /**
+   * Priority for execution order (lower runs first)
+   * Default: 100
+   * Recommended ranges:
+   * - 0-20: Infrastructure (rate limiting)
+   * - 20-40: Session management
+   * - 40-60: Storage bindings
+   * - 60-80: Auth flows (OAuth, credentials, magic links)
+   * - 80-100: Route guards
+   * - 100+: Custom/analytics
+   */
+  priority?: number;
+
+  /**
+   * Called early in request lifecycle
+   * Can short-circuit by returning a Response
+   * Use for: setup, route handling, redirects
+   */
+  onRequest?: (context: PluginContext) => MaybePromise<Response | void>;
+
+  /**
+   * Called after session is resolved
+   * Use for: session enrichment, user data loading
+   */
+  onSession?: (context: SessionContext) => MaybePromise<void>;
+
+  /**
+   * Called before response is sent
+   * Can modify or replace the response
+   * Use for: response headers, logging, analytics
+   */
+  onResponse?: (context: ResponseContext) => MaybePromise<Response | void>;
+}
+
+/**
+ * Plugin registry and execution engine
+ */
+export class PluginRegistry {
+  private plugins: AuthPlugin[] = [];
+
+  register(plugin: AuthPlugin): void {
+    if (this.plugins.some(p => p.name === plugin.name)) {
+      console.warn(`[kuratchi/auth] Plugin "${plugin.name}" already registered, skipping`);
+      return;
+    }
+
+    this.plugins.push(plugin);
+    this.plugins.sort((a, b) => (a.priority || 100) - (b.priority || 100));
+  }
+
+  registerMany(plugins: AuthPlugin[]): void {
+    plugins.forEach(p => this.register(p));
+  }
+
+  getPlugins(): AuthPlugin[] {
+    return [...this.plugins];
+  }
+
+  getPlugin(name: string): AuthPlugin | undefined {
+    return this.plugins.find(p => p.name === name);
+  }
+
+  async executeOnRequest(context: PluginContext): Promise<Response | void> {
+    for (const plugin of this.plugins) {
+      if (plugin.onRequest) {
+        const result = await plugin.onRequest(context);
+        if (result instanceof Response) {
+          return result;
+        }
+      }
+    }
+  }
+
+  async executeOnSession(context: SessionContext): Promise<void> {
+    for (const plugin of this.plugins) {
+      if (plugin.onSession) {
+        await plugin.onSession(context);
+      }
+    }
+  }
+
+  async executeOnResponse(context: ResponseContext): Promise<Response> {
+    let response = context.response;
+
+    for (const plugin of this.plugins) {
+      if (plugin.onResponse) {
+        const result = await plugin.onResponse({ ...context, response });
+        if (result instanceof Response) {
+          response = result;
+        }
+      }
+    }
+
+    return response;
+  }
+}
+
+/**
+ * Helper to create a simple plugin
+ */
+export function createPlugin(
+  name: string,
+  hooks: Partial<Pick<AuthPlugin, 'onRequest' | 'onSession' | 'onResponse'>>,
+  priority?: number
+): AuthPlugin {
+  return {
+    name,
+    priority,
+    ...hooks
+  };
+}
+
+
+

package/src/core/rate-limit.ts

@@ -0,0 +1,235 @@
+/**
+ * @kuratchi/auth — Rate Limiting API
+ *
+ * Config-driven request throttling. Runs in the worker entry before route handlers.
+ *
+ * @example
+ * ```ts
+ * // In kuratchi.config.ts:
+ * auth: {
+ *   rateLimit: {
+ *     routes: [
+ *       { path: '/auth/login', methods: ['POST'], maxRequests: 10, windowMs: 60000 },
+ *       { path: '/auth/signup', methods: ['POST'], maxRequests: 5, windowMs: 60000 },
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface RateLimitRouteConfig {
+  /** Unique identifier for the route (used in storage key) */
+  id?: string;
+  /** Path matcher — literal path or glob with * */
+  path: string;
+  /** HTTP methods to match (defaults to all) */
+  methods?: string[];
+  /** Maximum requests within the window */
+  maxRequests?: number;
+  /** Window duration in milliseconds */
+  windowMs?: number;
+  /** Custom error message */
+  message?: string;
+}
+
+export interface RateLimitConfig {
+  /** Default window in ms (default: 60000) */
+  defaultWindowMs?: number;
+  /** Default max requests (default: 10) */
+  defaultMaxRequests?: number;
+  /** KV binding name for cross-instance rate limiting (optional) */
+  kvBinding?: string;
+  /** Key prefix (default: 'ratelimit') */
+  keyPrefix?: string;
+  /** Route-specific rate limit configs */
+  routes?: RateLimitRouteConfig[];
+}
+
+interface RateLimitRecord {
+  count: number;
+  expiresAt: number;
+}
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _config: RateLimitConfig | null = null;
+
+// In-memory store (per-isolate, resets on cold start)
+const _store = new Map<string, RateLimitRecord>();
+
+/**
+ * Configure rate limiting. Called automatically by the compiler from kuratchi.config.ts.
+ */
+export function configureRateLimit(config: RateLimitConfig): void {
+  _config = config;
+}
+
+// ============================================================================
+// Framework context
+// ============================================================================
+
+function _getContext() {
+  const dezContext = (globalThis as any).__kuratchi_context__;
+  const env = (globalThis as any).__cloudflare_env__ ?? {};
+  return {
+    request: dezContext?.request as Request | undefined,
+    locals: dezContext?.locals as Record<string, any> ?? {},
+    env,
+  };
+}
+
+// ============================================================================
+// Pattern matching
+// ============================================================================
+
+function _matchPath(pathname: string, pattern: string): boolean {
+  const trimmed = pattern !== '/' && pattern.endsWith('/') ? pattern.slice(0, -1) : pattern;
+  const escaped = trimmed
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\\\*/g, '.*');
+  return new RegExp(`^${escaped}/?$`, 'i').test(pathname);
+}
+
+// ============================================================================
+// Store operations
+// ============================================================================
+
+async function _increment(key: string, windowMs: number, kvBinding?: any): Promise<RateLimitRecord> {
+  const now = Date.now();
+
+  // Try KV if available
+  if (kvBinding) {
+    try {
+      const prefix = _config?.keyPrefix || 'ratelimit';
+      const storageKey = `${prefix}:${key}`;
+      const existing = await kvBinding.get(storageKey, 'json') as RateLimitRecord | null;
+
+      if (!existing || existing.expiresAt <= now) {
+        const record = { count: 1, expiresAt: now + windowMs };
+        await kvBinding.put(storageKey, JSON.stringify(record), {
+          expirationTtl: Math.max(1, Math.ceil(windowMs / 1000)),
+        });
+        return record;
+      }
+
+      const updated = { count: existing.count + 1, expiresAt: existing.expiresAt };
+      const ttl = Math.max(1, Math.ceil((updated.expiresAt - now) / 1000));
+      await kvBinding.put(storageKey, JSON.stringify(updated), { expirationTtl: ttl });
+      return updated;
+    } catch {
+      // Fall through to memory store
+    }
+  }
+
+  // Memory store fallback
+  const existing = _store.get(key);
+  if (!existing || existing.expiresAt <= now) {
+    const record = { count: 1, expiresAt: now + windowMs };
+    _store.set(key, record);
+    return record;
+  }
+
+  const updated = { count: existing.count + 1, expiresAt: existing.expiresAt };
+  _store.set(key, updated);
+  return updated;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Check rate limits for the current request.
+ * Called by the compiler-generated worker entry before route handlers.
+ * Returns a 429 Response if rate limited, or null to proceed.
+ */
+export function checkRateLimit(): Promise<Response | null> {
+  return _checkRateLimitAsync();
+}
+
+async function _checkRateLimitAsync(): Promise<Response | null> {
+  if (!_config?.routes?.length) return null;
+
+  const { request, env } = _getContext();
+  if (!request) return null;
+
+  const url = new URL(request.url);
+  const method = request.method.toUpperCase();
+  const pathname = url.pathname;
+
+  // Find matching route config
+  const matched = _config.routes.find(route => {
+    if (!_matchPath(pathname, route.path)) return false;
+    if (route.methods?.length) {
+      return route.methods.map(m => m.toUpperCase()).includes(method);
+    }
+    return true;
+  });
+
+  if (!matched) return null;
+
+  // Resolve identifier (IP address)
+  const ip = request.headers.get('cf-connecting-ip')
+    || request.headers.get('x-forwarded-for')?.split(',')[0]?.trim()
+    || 'unknown';
+
+  const routeId = matched.id || matched.path;
+  const windowMs = matched.windowMs ?? _config.defaultWindowMs ?? 60_000;
+  const maxRequests = matched.maxRequests ?? _config.defaultMaxRequests ?? 10;
+
+  // Get KV binding if configured
+  const kvBinding = _config.kvBinding ? env[_config.kvBinding] : null;
+
+  const record = await _increment(`${routeId}:${ip}`, windowMs, kvBinding);
+
+  if (record.count > maxRequests) {
+    const retryAfter = Math.max(1, Math.ceil((record.expiresAt - Date.now()) / 1000));
+    return new Response(JSON.stringify({
+      error: 'too_many_requests',
+      message: matched.message || 'Too many requests. Please try again later.',
+    }), {
+      status: 429,
+      headers: {
+        'Content-Type': 'application/json',
+        'Retry-After': retryAfter.toString(),
+        'X-RateLimit-Limit': String(maxRequests),
+        'X-RateLimit-Remaining': '0',
+        'X-RateLimit-Reset': Math.ceil(record.expiresAt / 1000).toString(),
+      },
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Get rate limit info for a specific route (for use in server functions).
+ */
+export function getRateLimitInfo(routeId: string): { limit: number; remaining: number; reset: number } | null {
+  if (!_config?.routes) return null;
+  const route = _config.routes.find(r => (r.id || r.path) === routeId);
+  if (!route) return null;
+
+  const maxRequests = route.maxRequests ?? _config.defaultMaxRequests ?? 10;
+  const key = `${routeId}:unknown`;
+  const record = _store.get(key);
+
+  if (!record || record.expiresAt <= Date.now()) {
+    return { limit: maxRequests, remaining: maxRequests, reset: 0 };
+  }
+
+  return {
+    limit: maxRequests,
+    remaining: Math.max(0, maxRequests - record.count),
+    reset: Math.ceil(record.expiresAt / 1000),
+  };
+}
+
+
+

package/src/core/roles.ts

@@ -0,0 +1,219 @@
+/**
+ * @kuratchi/auth — Roles & Permissions API
+ *
+ * Ready-to-use server functions for RBAC.
+ * Define roles in config, then use hasRole/hasPermission anywhere.
+ *
+ * @example
+ * ```ts
+ * import { defineRoles, hasRole, hasPermission, assignRole, getRolesData } from '@kuratchi/auth';
+ *
+ * const Roles = defineRoles({
+ *   admin:  ['*'],
+ *   editor: ['todos.*', 'users.read'],
+ *   user:   ['todos.read', 'todos.create'],
+ * });
+ *
+ * // Check permissions:
+ * const user = await getCurrentUser();
+ * if (hasPermission(user, 'todos.delete')) { ... }
+ *
+ * // Assign role:
+ * await assignRole(formData); // reads userId + role from FormData
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type RoleDefinitions = Record<string, string[]>;
+
+export interface RolesConfig {
+  /** Default role for new users (default: 'user') */
+  defaultRole?: string;
+}
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _definitions: RoleDefinitions = {};
+let _allRoles: string[] = [];
+let _defaultRole: string = 'user';
+
+/**
+ * Define role → permission mappings. Returns a typed constant object
+ * mapping role names to themselves (for type-safe usage).
+ */
+export function defineRoles<T extends RoleDefinitions>(
+  definitions: T,
+  config?: RolesConfig,
+): { [K in keyof T]: K } {
+  _definitions = definitions;
+  _allRoles = Object.keys(definitions);
+  if (config?.defaultRole) _defaultRole = config.defaultRole;
+
+  const roles = {} as { [K in keyof T]: K };
+  for (const key of Object.keys(definitions) as (keyof T & string)[]) {
+    (roles as any)[key] = key;
+  }
+  return roles;
+}
+
+/**
+ * Get the registered role definitions.
+ */
+export function getRoleDefinitions(): RoleDefinitions {
+  return _definitions;
+}
+
+/**
+ * Get all defined role names.
+ */
+export function getAllRoles(): string[] {
+  return _allRoles;
+}
+
+/**
+ * Get the default role name.
+ */
+export function getDefaultRole(): string {
+  return _defaultRole;
+}
+
+// ============================================================================
+// Permission matching
+// ============================================================================
+
+function _matchesPermission(permission: string, pattern: string): boolean {
+  if (pattern === permission) return true;
+  if (pattern === '*') return true;
+  if (pattern.endsWith('.*')) {
+    const prefix = pattern.slice(0, -2);
+    return permission === prefix || permission.startsWith(prefix + '.');
+  }
+  return false;
+}
+
+/**
+ * Get all concrete permissions for a given role.
+ * Expands wildcards against all known permissions from all role definitions.
+ */
+export function getPermissionsForRole(role: string): string[] {
+  const patterns = _definitions[role] || [];
+  if (patterns.includes('*')) return _getAllPermissions();
+  return _getAllPermissions().filter(p =>
+    patterns.some(pattern => _matchesPermission(p, pattern))
+  );
+}
+
+/**
+ * Check if a user object has a specific permission based on their role.
+ */
+export function hasPermission(user: { role?: string } | null, permission: string): boolean {
+  if (!user) return false;
+  const role = user.role || _defaultRole;
+  const patterns = _definitions[role] || [];
+  return patterns.some(pattern => _matchesPermission(permission, pattern));
+}
+
+/**
+ * Check if a user object has a specific role.
+ */
+export function hasRole(user: { role?: string } | null, role: string): boolean {
+  if (!user) return false;
+  return (user.role || _defaultRole) === role;
+}
+
+// ============================================================================
+// Framework context + DB
+// ============================================================================
+
+function _getDb(): any {
+  const env = (globalThis as any).__cloudflare_env__ ?? {};
+  const binding = env.DB;
+  if (!binding) throw new Error('[kuratchi/auth] No DB binding found.');
+  return binding;
+}
+
+// ============================================================================
+// Server functions
+// ============================================================================
+
+/**
+ * Assign a role to a user. Reads userId and role from FormData.
+ * Callable by users who can manage users via `users.*` permission.
+ */
+export async function assignRole(formData: FormData): Promise<void> {
+  // Import getCurrentUser at call time to avoid circular deps
+  const { getCurrentUser } = await import('./credentials.js');
+  const currentUser = await getCurrentUser();
+  if (!currentUser || !hasPermission(currentUser, 'users.update')) {
+    throw new Error('Not authorized to assign roles');
+  }
+
+  const userId = formData.get('userId') as string;
+  const role = formData.get('role') as string;
+
+  if (!userId || !role) throw new Error('User ID and role are required');
+  if (!_allRoles.includes(role)) throw new Error(`Invalid role: ${role}`);
+
+  const db = _getDb();
+  await db.prepare('UPDATE users SET role = ? WHERE id = ?').bind(role, Number(userId)).run();
+}
+
+/**
+ * Get full roles data for the roles management page.
+ * Returns current user, their permissions, role definitions, and all users (if allowed).
+ */
+export async function getRolesData() {
+  const { getCurrentUser } = await import('./credentials.js');
+  const currentUser = await getCurrentUser();
+  if (!currentUser) {
+    return { isAuthenticated: false, user: null, roles: [], userRole: null, permissions: [], roleDefinitions: {}, allPermissions: [], allUsers: [] };
+  }
+
+  const userRole = currentUser.role || _defaultRole;
+  const permissions = getPermissionsForRole(userRole);
+
+  let allUsers: any[] = [];
+  if (hasPermission(currentUser, 'users.read')) {
+    const db = _getDb();
+    const result = await db.prepare('SELECT id, email, name, role, createdAt FROM users').all();
+    allUsers = (result?.results ?? []).map((u: any) => ({
+      ...u,
+      role: u.role || _defaultRole,
+    }));
+  }
+
+  return {
+    isAuthenticated: true,
+    user: currentUser,
+    userRole,
+    roles: _allRoles,
+    roleDefinitions: _definitions,
+    permissions,
+    allPermissions: _getAllPermissions(),
+    allUsers,
+  };
+}
+
+// ============================================================================
+// Internal: collect all concrete permissions from role definitions
+// ============================================================================
+
+function _getAllPermissions(): string[] {
+  const perms = new Set<string>();
+  for (const patterns of Object.values(_definitions)) {
+    for (const p of patterns) {
+      if (p !== '*' && !p.endsWith('.*')) {
+        perms.add(p);
+      }
+    }
+  }
+  return Array.from(perms);
+}
+
+
+