@kuratchi/auth 0.0.1

package/src/core/turnstile.ts

@@ -0,0 +1,275 @@
+/**
+ * @kuratchi/auth — Turnstile API
+ *
+ * Config-driven Cloudflare Turnstile bot protection.
+ * Runs in the worker entry before route handlers.
+ *
+ * @example
+ * ```ts
+ * // In kuratchi.config.ts:
+ * auth: {
+ *   turnstile: {
+ *     secretEnv: 'TURNSTILE_SECRET',
+ *     routes: [
+ *       { path: '/auth/login', methods: ['POST'] },
+ *       { path: '/auth/signup', methods: ['POST'] },
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+
+const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+
+const DEFAULT_FIELD_NAMES = ['cf-turnstile-response', 'turnstileToken', 'turnstile_token'];
+const DEFAULT_HEADER_NAMES = ['cf-turnstile-token', 'x-turnstile-token'];
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TurnstileRouteConfig {
+  /** Unique identifier (defaults to path) */
+  id?: string;
+  /** Path matcher — literal path or glob with * */
+  path: string;
+  /** HTTP methods to match (defaults to ['POST']) */
+  methods?: string[];
+  /** Custom field name to read the token from */
+  tokenField?: string;
+  /** Custom header name to read the token from */
+  tokenHeader?: string;
+  /** Override failure message */
+  message?: string;
+  /** Expected Turnstile action value(s) */
+  expectedAction?: string;
+}
+
+export interface TurnstileConfig {
+  /** Env var name for Turnstile secret (default: 'TURNSTILE_SECRET') */
+  secretEnv?: string;
+  /** Env var name for Turnstile site key (default: 'TURNSTILE_SITE_KEY') — exposed to client */
+  siteKeyEnv?: string;
+  /** Skip Turnstile verification in dev mode (default: true) */
+  skipInDev?: boolean;
+  /** Routes that require Turnstile verification */
+  routes?: TurnstileRouteConfig[];
+}
+
+// ============================================================================
+// Module state
+// ============================================================================
+
+let _config: TurnstileConfig | null = null;
+
+/**
+ * Configure Turnstile. Called automatically by the compiler from kuratchi.config.ts.
+ */
+export function configureTurnstile(config: TurnstileConfig): 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);
+}
+
+// ============================================================================
+// Token extraction
+// ============================================================================
+
+async function _extractToken(request: Request, route: TurnstileRouteConfig): Promise<string | null> {
+  // Check headers first
+  const headerNames = route.tokenHeader ? [route.tokenHeader] : DEFAULT_HEADER_NAMES;
+  for (const name of headerNames) {
+    const val = request.headers.get(name);
+    if (val) return val;
+  }
+
+  // Check body
+  const contentType = request.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    try {
+      const cloned = request.clone();
+      const json = await cloned.json() as Record<string, any>;
+      const fieldNames = route.tokenField ? [route.tokenField] : DEFAULT_FIELD_NAMES;
+      for (const name of fieldNames) {
+        if (json[name]) return String(json[name]);
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (contentType.includes('form')) {
+    try {
+      const cloned = request.clone();
+      const formData = await cloned.formData();
+      const fieldNames = route.tokenField ? [route.tokenField] : DEFAULT_FIELD_NAMES;
+      for (const name of fieldNames) {
+        const val = formData.get(name);
+        if (val) return String(val);
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Check Turnstile verification for the current request.
+ * Called by the compiler-generated worker entry before route handlers.
+ * Returns a 403 Response if verification fails, or null to proceed.
+ */
+export function checkTurnstile(): Promise<Response | null> {
+  return _checkTurnstileAsync();
+}
+
+async function _checkTurnstileAsync(): Promise<Response | null> {
+  if (!_config?.routes?.length) return null;
+
+  // Skip in dev mode (default: true)
+  if (_config.skipInDev !== false) {
+    const env = (globalThis as any).__cloudflare_env__ ?? {};
+    // Wrangler local dev sets no specific flag, but we can check if TURNSTILE_SECRET is missing
+    // or use the __DEV__ flag if the compiler sets it
+    if ((globalThis as any).__kuratchi_DEV__) 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
+  const matched = _config.routes.find(route => {
+    if (!_matchPath(pathname, route.path)) return false;
+    const methods = route.methods || ['POST'];
+    return methods.map(m => m.toUpperCase()).includes(method);
+  });
+
+  if (!matched) return null;
+
+  // Resolve secret from env
+  const secretKey = _config.secretEnv || 'TURNSTILE_SECRET';
+  const secret = env[secretKey];
+  if (!secret) return null; // No secret configured — skip
+
+  // Extract token
+  const token = await _extractToken(request, matched);
+  if (!token) {
+    return new Response(JSON.stringify({
+      error: 'turnstile_token_missing',
+      message: matched.message || 'Turnstile verification required.',
+    }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  // Verify with Cloudflare
+  const ip = request.headers.get('cf-connecting-ip')
+    || request.headers.get('x-forwarded-for')?.split(',')[0]?.trim()
+    || undefined;
+
+  const verifyBody: Record<string, string> = { secret, response: token };
+  if (ip) verifyBody.remoteip = ip;
+
+  const verifyRes = await fetch(TURNSTILE_VERIFY_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(verifyBody),
+  });
+
+  const result: any = await verifyRes.json();
+
+  if (!result.success) {
+    return new Response(JSON.stringify({
+      error: 'turnstile_verification_failed',
+      message: matched.message || 'Bot verification failed.',
+      details: result['error-codes'],
+    }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  // Check expected action
+  if (matched.expectedAction && result.action && result.action !== matched.expectedAction) {
+    return new Response(JSON.stringify({
+      error: 'turnstile_action_mismatch',
+      message: 'Turnstile action mismatch.',
+    }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Verify a Turnstile token manually (for use in server functions).
+ */
+export async function verifyTurnstile(token: string, options?: {
+  expectedAction?: string;
+}): Promise<{ success: boolean; error?: string }> {
+  const { env } = _getContext();
+  const secretKey = _config?.secretEnv || 'TURNSTILE_SECRET';
+  const secret = env[secretKey];
+
+  if (!secret) return { success: false, error: 'TURNSTILE_SECRET not configured' };
+
+  const { request } = _getContext();
+  const ip = request?.headers.get('cf-connecting-ip') || undefined;
+
+  const verifyBody: Record<string, string> = { secret, response: token };
+  if (ip) verifyBody.remoteip = ip;
+
+  const res = await fetch(TURNSTILE_VERIFY_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(verifyBody),
+  });
+
+  const result: any = await res.json();
+
+  if (!result.success) {
+    return { success: false, error: result['error-codes']?.join(', ') || 'Verification failed' };
+  }
+
+  if (options?.expectedAction && result.action !== options.expectedAction) {
+    return { success: false, error: 'Action mismatch' };
+  }
+
+  return { success: true };
+}
+
+
+

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @kuratchi/auth — Config-driven auth for KuratchiJS
+ *
+ * All auth features are configured in kuratchi.config.ts and auto-initialized
+ * by the compiler. Import callable functions directly:
+ *
+ * @example
+ * ```ts
+ * import { signUp, signIn, getCurrentUser, logActivity } from '@kuratchi/auth';
+ *
+ * const user = await getCurrentUser();
+ * await logActivity('user.login', { detail: 'Logged in' });
+ * ```
+ */
+
+// Core — low-level auth context (cookie/session access)
+export { getAuth } from './core/auth.js';
+export type { AuthContext, AuthSession, CookieOptions, GetAuthOptions } from './core/auth.js';
+
+// Credentials — signup, signin, signout, session lookup, password reset
+export { signUp, signIn, signOut, getCurrentUser, configureCredentials, requestPasswordReset, resetPassword } from './core/credentials.js';
+export type { CredentialsConfig } from './core/credentials.js';
+
+// Activity — structured audit logging
+export { logActivity, getActivity, defineActivities, getActivityDefinitions } from './core/activity.js';
+export type { LogActivityOptions, GetActivityOptions, ActivityConfig } from './core/activity.js';
+
+// Roles — RBAC with permission wildcards
+export { defineRoles, hasRole, hasPermission, getPermissionsForRole, assignRole, getRolesData, getRoleDefinitions, getAllRoles, getDefaultRole } from './core/roles.js';
+
+// OAuth — provider-based authentication
+export { configureOAuth, getOAuthData, startOAuth, handleOAuthCallback, getOAuthProviders } from './core/oauth.js';
+export type { OAuthConfig } from './core/oauth.js';
+
+// Guards — route protection (compiler interceptor)
+export { configureGuards, checkGuard, requireAuth as requireAuthGuard } from './core/guards.js';
+export type { GuardsConfig } from './core/guards.js';
+
+// Rate Limiting — per-route throttling (compiler interceptor)
+export { configureRateLimit, checkRateLimit, getRateLimitInfo } from './core/rate-limit.js';
+export type { RateLimitConfig, RateLimitRouteConfig as RateLimitRoute } from './core/rate-limit.js';
+
+// Turnstile — Cloudflare bot protection (compiler interceptor)
+export { configureTurnstile, checkTurnstile, verifyTurnstile } from './core/turnstile.js';
+export type { TurnstileConfig, TurnstileRouteConfig as TurnstileRoute } from './core/turnstile.js';
+
+// Organization — multi-tenant DO orchestration
+export { configureOrganization, getOrgClient, getOrgStubByName, createOrgDatabase, getOrgDatabaseInfo, resolveOrgDatabaseName, isOrgAvailable } from './core/organization.js';
+export type { OrganizationConfig } from './core/organization.js';
+
+// Activity action constants
+export { ActivityAction, getActivityActions, isValidAction } from './utils/activity-actions.js';
+
+// Crypto utilities
+export {
+  generateSessionToken,
+  hashPassword,
+  comparePassword,
+  hashToken,
+  buildSessionCookie,
+  parseSessionCookie,
+  signState,
+  verifyState,
+  toBase64Url,
+  fromBase64Url,
+} from './utils/crypto.js';
+
+
+

package/src/utils/activity-actions.ts

@@ -0,0 +1,50 @@
+/**
+ * Activity Action Constants
+ *
+ * Provides typed constants for activity actions loaded from the database.
+ * This is populated by the activityPlugin during initialization.
+ */
+
+// Cache for activity types
+let activityTypesCache: Record<string, string> = {};
+
+/**
+ * Activity Action Constants
+ * Provides autocomplete for activity actions
+ *
+ * Usage: ActivityAction.ORGANIZATION_CREATED
+ */
+export const ActivityAction = new Proxy({} as Record<string, string>, {
+	get(_target, prop: string) {
+		// Return cached value if available
+		if (prop in activityTypesCache) {
+			return activityTypesCache[prop];
+		}
+
+		// If not cached, convert constant name to action string
+		// ORGANIZATION_CREATED -> organization.created
+		return prop.toLowerCase().replace(/_/g, '.');
+	}
+});
+
+/**
+ * Internal: Update the activity types cache
+ * Called by activityPlugin during initialization
+ */
+export function _updateActivityTypesCache(types: Record<string, string>) {
+	activityTypesCache = types;
+}
+
+/**
+ * Get all available activity actions
+ */
+export function getActivityActions(): string[] {
+	return Object.values(activityTypesCache);
+}
+
+/**
+ * Check if an action is valid
+ */
+export function isValidAction(action: string): boolean {
+	return Object.values(activityTypesCache).includes(action);
+}

package/src/utils/crypto.ts

@@ -0,0 +1,207 @@
+/**
+ * @kuratchi/auth — Crypto utilities
+ * Pure WebCrypto API — works in Cloudflare Workers, Node 20+, Deno, Bun
+ */
+
+/**
+ * Generate a secure random session token using Web Crypto API
+ * @returns A base64url encoded random string
+ */
+export function generateSessionToken(): string {
+	const bytes = new Uint8Array(20);
+	crypto.getRandomValues(bytes);
+	return toBase64Url(bytes);
+}
+
+/**
+ * Hash a password with PBKDF2 + optional pepper
+ * Returns "saltHex:hashHex"
+ */
+export const hashPassword = async (password: string, providedSalt?: Uint8Array, pepper?: string): Promise<string> => {
+	const encoder = new TextEncoder();
+	const salt = providedSalt || crypto.getRandomValues(new Uint8Array(16));
+
+	const keyMaterial = await crypto.subtle.importKey(
+		'raw',
+		encoder.encode(pepper ? `${password}:${pepper}` : password),
+		{ name: 'PBKDF2' },
+		false,
+		['deriveBits', 'deriveKey']
+	);
+
+	const key = await crypto.subtle.deriveKey(
+		{
+			name: 'PBKDF2',
+			salt: salt.buffer as ArrayBuffer,
+			iterations: 100000,
+			hash: 'SHA-256',
+		},
+		keyMaterial,
+		{ name: 'AES-GCM', length: 256 },
+		true,
+		['encrypt', 'decrypt']
+	);
+
+	const exportedKey = await crypto.subtle.exportKey('raw', key);
+	const hashArray = Array.from(new Uint8Array(exportedKey));
+	const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+
+	const saltArray = Array.from(salt);
+	const saltHex = saltArray.map(b => b.toString(16).padStart(2, '0')).join('');
+
+	return `${saltHex}:${hashHex}`;
+};
+
+/**
+ * Compare a plaintext password against a stored hash
+ */
+export const comparePassword = async (password: string, hashedPassword: string, pepper?: string): Promise<boolean> => {
+	const [salt, hash] = hashedPassword.split(':');
+	const saltMatches = salt.match(/.{1,2}/g);
+	if (!saltMatches) return false;
+	const saltBuffer = new Uint8Array(saltMatches.map(byte => parseInt(byte, 16)));
+
+	const _hash = await hashPassword(password, saltBuffer, pepper);
+	const [, _hashHex] = _hash.split(':');
+
+	return _hashHex === hash;
+};
+
+/**
+ * SHA-256 hash a token string
+ */
+export const hashToken = async (token: string): Promise<string> => {
+	const encoder = new TextEncoder();
+	const data = encoder.encode(token);
+	const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+	const hashArray = Array.from(new Uint8Array(hashBuffer));
+	return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+};
+
+// ==============================
+// Base64url helpers
+// ==============================
+
+const _toBytes = (input: string | ArrayBuffer | Uint8Array) =>
+	typeof input === 'string' ? new TextEncoder().encode(input) : (input instanceof Uint8Array ? input : new Uint8Array(input));
+
+const _bytesToBase64 = (bytes: Uint8Array) => {
+	const B = (globalThis as any).Buffer;
+	if (B) return B.from(bytes).toString('base64');
+	let binary = '';
+	for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+};
+
+const _base64ToBytes = (b64: string) => {
+	const B = (globalThis as any).Buffer;
+	if (B) return new Uint8Array(B.from(b64, 'base64'));
+	const binary = atob(b64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+};
+
+export const toBase64Url = (buf: ArrayBuffer | Uint8Array | string) =>
+	_bytesToBase64(_toBytes(buf)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+
+export const fromBase64Url = (b64url: string): Uint8Array => {
+	const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(b64url.length / 4) * 4, '=');
+	return _base64ToBytes(b64);
+};
+
+export function b64urlDecodeToString(str: string): string {
+	const decoded = fromBase64Url(str);
+	return new TextDecoder().decode(decoded);
+}
+
+// ==============================
+// Session cookie encryption (AES-GCM)
+// ==============================
+
+const importAesGcmKey = async (secret: string): Promise<CryptoKey> => {
+	if (!secret) {
+		throw new Error('[kuratchi/auth] Cannot derive encryption key from empty secret. Set AUTH_SECRET.');
+	}
+	const enc = new TextEncoder();
+	const raw = await crypto.subtle.digest('SHA-256', enc.encode(secret));
+	return crypto.subtle.importKey('raw', raw, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+};
+
+/**
+ * Build an opaque encrypted session cookie from orgId and tokenHash
+ */
+export const buildSessionCookie = async (
+	secret: string,
+	orgId: string,
+	tokenHash: string
+): Promise<string> => {
+	const key = await importAesGcmKey(secret);
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const payload = JSON.stringify({ o: orgId, th: tokenHash });
+	const pt = new TextEncoder().encode(payload);
+	const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, pt);
+	const combined = new Uint8Array(iv.byteLength + (ct as ArrayBuffer).byteLength);
+	combined.set(iv, 0);
+	combined.set(new Uint8Array(ct), iv.byteLength);
+	return toBase64Url(combined);
+};
+
+/**
+ * Parse an opaque session cookie into { orgId, tokenHash }
+ */
+export const parseSessionCookie = async (
+	secret: string,
+	cookie: string
+): Promise<{ orgId: string; tokenHash: string } | null> => {
+	try {
+		if (!cookie) return null;
+		const data = fromBase64Url(cookie);
+		if (data.byteLength < 13) return null;
+		const iv = data.slice(0, 12);
+		const ct = data.slice(12);
+		const key = await importAesGcmKey(secret);
+		const pt = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
+		const json = new TextDecoder().decode(pt);
+		const parsed = JSON.parse(json);
+		if (!parsed?.o || !parsed?.th) return null;
+		return { orgId: parsed.o, tokenHash: parsed.th };
+	} catch {
+		return null;
+	}
+};
+
+// ==============================
+// HMAC state signing (for OAuth)
+// ==============================
+
+export const importHmacKey = async (secret: string): Promise<CryptoKey> =>
+	crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+
+export const signState = async (secret: string, payload: Record<string, any>): Promise<string> => {
+	const key = await importHmacKey(secret);
+	const json = JSON.stringify(payload);
+	const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(json));
+	return `${toBase64Url(json)}.${toBase64Url(new Uint8Array(sig))}`;
+};
+
+export const verifyState = async (secret: string, state: string): Promise<Record<string, any> | null> => {
+	try {
+		const [p, s] = state.split('.', 2);
+		if (!p || !s) return null;
+		const json = b64urlDecodeToString(p);
+		const key = await importHmacKey(secret);
+		const sigBytes = fromBase64Url(s);
+		const sigCopy = new Uint8Array(sigBytes.byteLength);
+		sigCopy.set(sigBytes);
+		const sigBuf: ArrayBuffer = sigCopy.buffer;
+		const valid = await crypto.subtle.verify('HMAC', key, sigBuf, new TextEncoder().encode(json));
+		if (!valid) return null;
+		return JSON.parse(json);
+	} catch {
+		return null;
+	}
+};
+
+
+