@kuratchi/auth 0.0.1

package/src/core/guards.ts

@@ -0,0 +1,152 @@
+/**
+ * @kuratchi/auth — Guards API
+ *
+ * Route protection that runs before route handlers.
+ * Configure in kuratchi.config.ts, or call requireAuth() in server functions.
+ *
+ * @example
+ * ```ts
+ * // In kuratchi.config.ts:
+ * auth: {
+ *   guards: {
+ *     paths: ['/admin/*', '/dashboard/*'],
+ *     exclude: ['/admin/login'],
+ *     redirectTo: '/auth/login',
+ *   }
+ * }
+ *
+ * // Or call directly in a server function:
+ * import { requireAuth } from '@kuratchi/auth';
+ * const user = await requireAuth(); // throws redirect if not authenticated
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface GuardsConfig {
+  /** Paths to protect (glob patterns). If empty, protects all paths. */
+  paths?: string[];
+  /** Paths to exclude from protection (glob patterns) */
+  exclude?: string[];
+  /** Redirect URL if not authenticated (default: '/auth/login') */
+  redirectTo?: string;
+}
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _config: GuardsConfig | null = null;
+
+/**
+ * Configure route guards. Called automatically by the compiler from kuratchi.config.ts.
+ */
+export function configureGuards(config: GuardsConfig): void {
+  _config = config;
+}
+
+// ============================================================================
+// Framework context
+// ============================================================================
+
+function _getContext() {
+  const dezContext = (globalThis as any).__kuratchi_context__;
+  return {
+    request: dezContext?.request as Request | undefined,
+    locals: dezContext?.locals as Record<string, any> ?? {},
+  };
+}
+
+// ============================================================================
+// Pattern matching
+// ============================================================================
+
+function _matchPattern(pathname: string, pattern: string): boolean {
+  // /admin/* should match /admin, /admin/, /admin/roles, etc.
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2); // '/admin'
+    if (pathname === base || pathname.startsWith(base + '/')) return true;
+    return false;
+  }
+  const regexStr = pattern
+    .replace(/\*/g, '.*')
+    .replace(/\//g, '\\/');
+  return new RegExp(`^${regexStr}$`).test(pathname);
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Check if the current request should be guarded.
+ * Called by the compiler-generated worker entry before route handlers.
+ * Returns a redirect Response if not authenticated, or null to proceed.
+ */
+export function checkGuard(): Response | null {
+  if (!_config) return null;
+
+  const { request, locals } = _getContext();
+  if (!request) return null;
+
+  const url = new URL(request.url);
+  const pathname = url.pathname;
+
+  // Skip internal asset routes
+  if (pathname.startsWith('/_assets/')) return null;
+
+  // Check if path is protected
+  const paths = _config.paths || [];
+  const exclude = _config.exclude || [];
+
+  if (paths.length > 0) {
+    const included = paths.some(p => _matchPattern(pathname, p));
+    if (!included) return null;
+  }
+
+  if (exclude.length > 0) {
+    const excluded = exclude.some(p => _matchPattern(pathname, p));
+    if (excluded) return null;
+  }
+
+  // Check if authenticated (session cookie exists)
+  const sessionCookie = locals.auth?.sessionCookie;
+  if (sessionCookie) return null; // Has session cookie — allow through
+
+  // Not authenticated — redirect
+  const redirectTo = _config.redirectTo || '/auth/login';
+  return new Response(null, {
+    status: 302,
+    headers: { Location: redirectTo },
+  });
+}
+
+/**
+ * Callable guard for use in server functions.
+ * Returns the current user or redirects if not authenticated.
+ *
+ * @example
+ * ```ts
+ * const user = await requireAuth();
+ * // If we get here, user is authenticated
+ * ```
+ */
+export async function requireAuth(options?: {
+  redirectTo?: string;
+}): Promise<Record<string, any>> {
+  const { getCurrentUser } = await import('./credentials.js');
+  const user = await getCurrentUser();
+
+  if (!user) {
+    const { locals } = _getContext();
+    locals.__redirectTo = options?.redirectTo || _config?.redirectTo || '/auth/login';
+    throw new Error('Authentication required');
+  }
+
+  return user;
+}
+
+
+

package/src/core/oauth.ts

@@ -0,0 +1,348 @@
+/**
+ * @kuratchi/auth — OAuth API
+ *
+ * Ready-to-use server functions for OAuth flows.
+ * Configure providers once, then startOAuth/handleOAuthCallback just work.
+ *
+ * @example
+ * ```ts
+ * import { configureOAuth, startOAuth, handleOAuthCallback, getOAuthData } from '@kuratchi/auth';
+ *
+ * configureOAuth({
+ *   providers: {
+ *     github: {
+ *       clientId: env.GITHUB_CLIENT_ID,
+ *       clientSecret: env.GITHUB_CLIENT_SECRET,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+import {
+  signState,
+  verifyState,
+  hashToken,
+  buildSessionCookie,
+  generateSessionToken,
+} from '../utils/crypto.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OAuthProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+}
+
+export interface OAuthConfig {
+  providers: Record<string, OAuthProviderConfig>;
+  /** Redirect after successful OAuth login (default: '/admin') */
+  loginRedirect?: string;
+  /** Session duration in ms (default: 30 days) */
+  sessionDuration?: number;
+}
+
+interface ProviderEndpoints {
+  authorizeUrl: string;
+  tokenUrl: string;
+  profileUrl: string;
+  defaultScopes: string[];
+  parseProfile: (data: any) => { id: string; email: string; name: string | null; image: string | null };
+}
+
+// ============================================================================
+// Known providers
+// ============================================================================
+
+const PROVIDERS: Record<string, ProviderEndpoints> = {
+  github: {
+    authorizeUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    profileUrl: 'https://api.github.com/user',
+    defaultScopes: ['read:user', 'user:email'],
+    parseProfile: (data: any) => ({
+      id: String(data.id),
+      email: data.email?.toLowerCase() || `${data.login}@github.noemail`,
+      name: data.name || data.login || null,
+      image: data.avatar_url || null,
+    }),
+  },
+  google: {
+    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    profileUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    parseProfile: (data: any) => ({
+      id: String(data.id),
+      email: data.email?.toLowerCase() || '',
+      name: data.name || null,
+      image: data.picture || null,
+    }),
+  },
+};
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _config: OAuthConfig | null = null;
+
+/**
+ * Configure OAuth providers. Call once at module scope.
+ */
+export function configureOAuth(config: OAuthConfig): void {
+  _config = config;
+}
+
+/**
+ * Get configured OAuth provider info (for UI rendering).
+ */
+export function getOAuthProviders(): string[] {
+  if (!_config) return [];
+  return Object.keys(_config.providers).filter(p => {
+    const c = _config!.providers[p];
+    return !!c.clientId;
+  });
+}
+
+// ============================================================================
+// Framework context
+// ============================================================================
+
+function _getEnv(): Record<string, any> {
+  return (globalThis as any).__cloudflare_env__ ?? {};
+}
+
+function _getContext() {
+  const dezContext = (globalThis as any).__kuratchi_context__;
+  return {
+    request: dezContext?.request as Request | undefined,
+    locals: dezContext?.locals as Record<string, any> ?? {},
+  };
+}
+
+function _getDb(): any {
+  const env = _getEnv();
+  if (!env.DB) throw new Error('[kuratchi/auth] No DB binding found.');
+  return env.DB;
+}
+
+function _getSecret(): string {
+  const secret = _getEnv().AUTH_SECRET;
+  if (!secret) {
+    throw new Error(
+      '[kuratchi/auth] AUTH_SECRET is not set. Add it to .dev.vars (local) or Workers secrets (production). '
+      + 'Auth operations cannot proceed without a secret.'
+    );
+  }
+  return secret;
+}
+
+function _getCookieName(): string {
+  const { locals } = _getContext();
+  return locals.auth?.cookieName || 'kuratchi_session';
+}
+
+function _setRedirect(path: string) {
+  const { locals } = _getContext();
+  locals.__redirectTo = path;
+}
+
+function _pushSetCookie(header: string) {
+  const { locals } = _getContext();
+  if (!locals.__setCookieHeaders) locals.__setCookieHeaders = [];
+  locals.__setCookieHeaders.push(header);
+}
+
+function _buildSetCookieHeader(name: string, value: string, opts: {
+  expires?: Date; httpOnly?: boolean; secure?: boolean; sameSite?: string; path?: string;
+}): string {
+  const parts = [`${name}=${value}`];
+  parts.push(`Path=${opts.path || '/'}`);
+  if (opts.httpOnly !== false) parts.push('HttpOnly');
+  if (opts.secure !== false) parts.push('Secure');
+  parts.push(`SameSite=${opts.sameSite || 'Lax'}`);
+  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);
+  return parts.join('; ');
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Get OAuth data for the OAuth page (which providers are configured).
+ */
+export async function getOAuthData() {
+  const { request } = _getContext();
+  const url = new URL(request?.url || 'http://localhost');
+  const origin = `${url.protocol}//${url.host}`;
+
+  const providers = getOAuthProviders();
+
+  return {
+    providers,
+    hasGithub: providers.includes('github'),
+    hasGoogle: providers.includes('google'),
+    origin,
+  };
+}
+
+/**
+ * Start an OAuth flow for a given provider.
+ * Reads provider name from FormData or defaults to 'github'.
+ */
+export async function startOAuth(formData: FormData): Promise<void> {
+  const providerName = (formData.get('provider') as string) || 'github';
+  if (!_config) throw new Error('[kuratchi/auth] OAuth not configured. Call configureOAuth() first.');
+
+  const providerConfig = _config.providers[providerName];
+  if (!providerConfig?.clientId) throw new Error(`OAuth provider '${providerName}' not configured.`);
+
+  const endpoints = PROVIDERS[providerName];
+  if (!endpoints) throw new Error(`Unknown OAuth provider: ${providerName}`);
+
+  const { request } = _getContext();
+  const url = new URL(request?.url || 'http://localhost');
+  const origin = `${url.protocol}//${url.host}`;
+  const secret = _getSecret();
+
+  const state = await signState(secret, {
+    provider: providerName,
+    redirectTo: _config.loginRedirect || '/admin',
+    ts: Date.now(),
+    n: crypto.randomUUID(),
+  });
+
+  const authUrl = new URL(endpoints.authorizeUrl);
+  authUrl.searchParams.set('client_id', providerConfig.clientId);
+  authUrl.searchParams.set('redirect_uri', `${origin}/auth/oauth/${providerName}/callback`);
+  authUrl.searchParams.set('scope', (providerConfig.scopes || endpoints.defaultScopes).join(' '));
+  authUrl.searchParams.set('state', state);
+  if (providerName === 'google') {
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('access_type', 'offline');
+  }
+
+  _setRedirect(authUrl.toString());
+}
+
+/**
+ * Handle OAuth callback. Exchanges code for token, fetches profile,
+ * creates/links user, creates session, sets cookie.
+ */
+export async function handleOAuthCallback(): Promise<{ success?: boolean; error?: string; redirectTo?: string }> {
+  const { request } = _getContext();
+  const url = new URL(request?.url || 'http://localhost');
+  const origin = `${url.protocol}//${url.host}`;
+
+  const code = url.searchParams.get('code');
+  const stateParam = url.searchParams.get('state');
+  const secret = _getSecret();
+
+  if (!code || !stateParam) return { error: 'Missing code or state parameter' };
+  if (!_config) return { error: 'OAuth not configured' };
+
+  // Verify state
+  const payload = await verifyState(secret, stateParam);
+  if (!payload) return { error: 'Invalid or expired state' };
+
+  const stateData = payload as Record<string, any>;
+  if (stateData.ts && Date.now() - stateData.ts > 600000) return { error: 'State expired' };
+
+  const providerName = stateData.provider || 'github';
+  const providerConfig = _config.providers[providerName];
+  const endpoints = PROVIDERS[providerName];
+  if (!providerConfig || !endpoints) return { error: `Unknown provider: ${providerName}` };
+
+  // Exchange code for token
+  const tokenBody: Record<string, string> = {
+    code,
+    client_id: providerConfig.clientId,
+    client_secret: providerConfig.clientSecret,
+    redirect_uri: `${origin}/auth/oauth/${providerName}/callback`,
+  };
+  if (providerName === 'google') tokenBody.grant_type = 'authorization_code';
+
+  const tokenRes = await fetch(endpoints.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },
+    body: new URLSearchParams(tokenBody),
+  });
+
+  if (!tokenRes.ok) return { error: `Token exchange failed: ${await tokenRes.text()}` };
+
+  const tokenJson: any = await tokenRes.json();
+  const access_token = tokenJson.access_token;
+  if (!access_token) return { error: 'No access token received' };
+
+  // Fetch profile
+  const profileRes = await fetch(endpoints.profileUrl, {
+    headers: { 'Authorization': `Bearer ${access_token}`, 'Accept': 'application/json' },
+  });
+  if (!profileRes.ok) return { error: `Failed to fetch profile: ${await profileRes.text()}` };
+
+  const profileData: any = await profileRes.json();
+  const profile = endpoints.parseProfile(profileData);
+
+  const db = _getDb();
+
+  // Check if OAuth account already linked
+  const existingOAuth = await db.prepare(
+    'SELECT userId FROM oauthAccounts WHERE provider = ? AND providerAccountId = ?'
+  ).bind(providerName, profile.id).first();
+
+  let user: any;
+
+  if (existingOAuth?.userId) {
+    user = await db.prepare('SELECT * FROM users WHERE id = ?').bind(existingOAuth.userId).first();
+  } else {
+    // Check by email
+    user = await db.prepare('SELECT * FROM users WHERE email = ?').bind(profile.email).first();
+
+    if (!user) {
+      // Create new user
+      await db.prepare(
+        'INSERT INTO users (email, name, passwordHash, role, image, emailVerified) VALUES (?, ?, ?, ?, ?, ?)'
+      ).bind(profile.email, profile.name, null, 'user', profile.image, Date.now()).run();
+      user = await db.prepare('SELECT * FROM users WHERE email = ?').bind(profile.email).first();
+    }
+
+    // Link OAuth account
+    if (user) {
+      await db.prepare(
+        'INSERT INTO oauthAccounts (userId, provider, providerAccountId, accessToken, refreshToken, idToken) VALUES (?, ?, ?, ?, ?, ?)'
+      ).bind(user.id, providerName, profile.id, access_token, tokenJson.refresh_token || null, null).run();
+    }
+  }
+
+  if (!user) return { error: 'Failed to create or find user' };
+
+  // Create session
+  const sessionToken = generateSessionToken();
+  const sessionTokenHash = await hashToken(sessionToken);
+  const now = new Date();
+  const duration = _config.sessionDuration ?? 30 * 24 * 60 * 60 * 1000;
+  const expires = new Date(now.getTime() + duration);
+
+  await db.prepare(
+    'INSERT INTO sessions (sessionToken, userId, expires) VALUES (?, ?, ?)'
+  ).bind(sessionTokenHash, user.id, expires.getTime()).run();
+
+  const sessionCookie = await buildSessionCookie(secret, 'default', sessionTokenHash);
+  const cookieName = _getCookieName();
+  _pushSetCookie(_buildSetCookieHeader(cookieName, sessionCookie, {
+    expires, httpOnly: true, secure: true, sameSite: 'lax',
+  }));
+
+  const redirectTo = stateData.redirectTo || _config.loginRedirect || '/admin';
+  _setRedirect(redirectTo);
+
+  return { success: true, redirectTo };
+}
+
+
+

package/src/core/organization.ts

@@ -0,0 +1,171 @@
+/**
+ * @kuratchi/auth — Organization API
+ *
+ * Multi-tenant DO-backed database orchestrator.
+ * Manages the DO namespace binding and provides stub access.
+ *
+ * The DO exposes explicit RPC methods (createUser, getUserByEmail,
+ * createSession, getSession, deleteSession) that use the ORM
+ * internally. No proxy needed — credentials.ts calls them directly.
+ *
+ * Configuration lives in `auth.organizations` in kuratchi.config.ts:
+ * ```ts
+ * organizations: {
+ *   binding: 'ORG_DB',
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { getOrgClient, getOrgStubByName } from '@kuratchi/auth';
+ *
+ * // Get stub by DO name (from session cookie or admin lookup)
+ * const stub = getOrgStubByName(doName);
+ * const user = await stub.getUserByEmail('user@example.com');
+ *
+ * // Get stub by org ID (resolves via admin DB)
+ * const stub = await getOrgClient(organizationId);
+ * const sites = await stub.query({ table: 'sites', method: 'many', args: [{}] });
+ * ```
+ */
+
+import { kuratchiORM } from '@kuratchi/orm';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OrganizationConfig {
+  /** DO namespace binding name in env (e.g. 'ORG_DB') */
+  binding: string;
+}
+
+export interface OrgDatabaseInfo {
+  databaseName: string;
+  organizationId: string;
+}
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _config: OrganizationConfig | null = null;
+
+/**
+ * Configure organization multi-tenancy. Called by the compiler.
+ */
+export function configureOrganization(config: OrganizationConfig): void {
+  _config = config;
+}
+
+// ============================================================================
+// Framework context
+// ============================================================================
+
+function _getEnv(): Record<string, any> {
+  return (globalThis as any).__cloudflare_env__ ?? {};
+}
+
+function _getDoNamespace(): any {
+  if (!_config) return null;
+  const env = _getEnv();
+  return env[_config.binding] || null;
+}
+
+function _getAdminDb(): Record<string, any> {
+  return kuratchiORM(() => {
+    const env = _getEnv();
+    if (!env.DB) throw new Error('[kuratchi/auth] No DB binding found.');
+    return env.DB;
+  });
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Get a DO stub by its DO name (for direct RPC calls).
+ * The stub exposes the OrganizationDO's RPC methods:
+ *   stub.createUser(), stub.getUserByEmail(), stub.createSession(),
+ *   stub.getSession(), stub.deleteSession(), stub.query()
+ */
+export function getOrgStubByName(doName: string): any | null {
+  const doNamespace = _getDoNamespace();
+  if (!doNamespace) return null;
+  const doId = doNamespace.idFromName(doName);
+  return doNamespace.get(doId);
+}
+
+/**
+ * Resolve the DO name for an organization by its ID.
+ * Looks up the `organizations` table in the admin D1 via ORM.
+ */
+export async function resolveOrgDatabaseName(organizationId: string): Promise<string | null> {
+  try {
+    const adminDb = _getAdminDb();
+    const result = await adminDb.organizations.where({ id: organizationId }).first();
+    return result.data?.doName || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get a DO stub for an organization by its organization ID.
+ * Resolves the DO name from admin D1, then returns the stub.
+ */
+export async function getOrgClient(organizationId: string): Promise<any | null> {
+  const doName = await resolveOrgDatabaseName(organizationId);
+  if (!doName) {
+    console.warn(`[kuratchi/auth organization] No database found for org: ${organizationId}`);
+    return null;
+  }
+  return getOrgStubByName(doName);
+}
+
+/**
+ * Create a new organization database (DO provisioning).
+ * Returns the generated database name.
+ */
+export async function createOrgDatabase(params: {
+  organizationId: string;
+  organizationName: string;
+}): Promise<{ databaseName: string }> {
+  const doNamespace = _getDoNamespace();
+  if (!doNamespace) {
+    throw new Error('[kuratchi/auth organization] DO namespace not available');
+  }
+
+  const sanitizedName = params.organizationName
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .substring(0, 32);
+  const databaseName = `org-${sanitizedName}-${crypto.randomUUID().substring(0, 8)}`;
+
+  // Touch the DO to provision it (constructor runs initDO → creates tables)
+  const doId = doNamespace.idFromName(databaseName);
+  doNamespace.get(doId);
+
+  return { databaseName };
+}
+
+/**
+ * Get database info for an organization.
+ */
+export async function getOrgDatabaseInfo(organizationId: string): Promise<OrgDatabaseInfo | null> {
+  const databaseName = await resolveOrgDatabaseName(organizationId);
+  if (!databaseName) return null;
+  return { databaseName, organizationId };
+}
+
+/**
+ * Check if the organizations plugin is configured and DO namespace is available.
+ */
+export function isOrgAvailable(): boolean {
+  return !!_getDoNamespace();
+}
+
+
+