@edge-base/server 0.1.1

package/src/lib/op-parser.ts

@@ -0,0 +1,99 @@
+/**
+ * $op field operator parser for PATCH update requests.
+ * Converts field operators to SQL SET clause fragments.
+ *
+ * Supported operators:
+ * - increment(n): field = COALESCE(field, 0) + n
+ * - deleteField(): field = NULL
+ */
+import type { FieldOperator } from './validation.js';
+import { EdgeBaseError } from '@edge-base/shared';
+
+interface SetClause {
+  /** SQL fragment for SET clause, e.g. "viewCount" = COALESCE("viewCount", 0) + ? */
+  sql: string;
+  /** Parameters for the SQL fragment */
+  params: unknown[];
+  /** Next placeholder index after consuming this clause's params */
+  nextParamIndex: number;
+}
+
+export interface ParseUpdateBodyOptions {
+  dialect?: 'sqlite' | 'postgres';
+  startIndex?: number;
+}
+
+/**
+ * Parse update body into SQL SET clause parts.
+ * Handles both regular values and $op field operators.
+ * Returns { setClauses, params } ready for UPDATE statement.
+ */
+export function parseUpdateBody(
+  data: Record<string, unknown>,
+  excludeFields: string[] = ['id'],
+  options: ParseUpdateBodyOptions = {},
+): { setClauses: string[]; params: unknown[]; nextParamIndex: number } {
+  const setClauses: string[] = [];
+  const params: unknown[] = [];
+  const dialect = options.dialect ?? 'sqlite';
+  let paramIndex = options.startIndex ?? 1;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (excludeFields.includes(key)) continue;
+
+    if (isOpObject(value)) {
+      const clause = buildOpClause(key, value as FieldOperator, dialect, paramIndex);
+      setClauses.push(clause.sql);
+      params.push(...clause.params);
+      paramIndex = clause.nextParamIndex;
+    } else {
+      setClauses.push(`${esc(key)} = ${placeholderFor(dialect, paramIndex)}`);
+      params.push(value);
+      paramIndex++;
+    }
+  }
+
+  return { setClauses, params, nextParamIndex: paramIndex };
+}
+
+function buildOpClause(
+  field: string,
+  op: FieldOperator,
+  dialect: 'sqlite' | 'postgres',
+  paramIndex: number,
+): SetClause {
+  switch (op.$op) {
+    case 'increment':
+      return {
+        sql: `${esc(field)} = COALESCE(${esc(field)}, 0) + ${placeholderFor(dialect, paramIndex)}`,
+        params: [op.value ?? 0],
+        nextParamIndex: paramIndex + 1,
+      };
+
+    case 'deleteField':
+      return {
+        sql: `${esc(field)} = NULL`,
+        params: [],
+        nextParamIndex: paramIndex,
+      };
+
+    default:
+      throw new EdgeBaseError(400, `Unknown field operator '${(op as FieldOperator).$op}'. Supported operators: increment, deleteField.`);
+  }
+}
+
+function placeholderFor(dialect: 'sqlite' | 'postgres', paramIndex: number): string {
+  return dialect === 'postgres' ? `$${paramIndex}` : '?';
+}
+
+function isOpObject(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$op' in value
+  );
+}
+
+function esc(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}

package/src/lib/openapi.ts

@@ -0,0 +1,146 @@
+type OpenApiSecurityRequirement = Record<string, string[]>;
+type OpenApiOperation = Record<string, unknown> & {
+  security?: OpenApiSecurityRequirement[];
+};
+type OpenApiPathItem = Record<string, OpenApiOperation | unknown>;
+export type OpenApiSpec = {
+  servers?: Array<{ url: string; description?: string }>;
+  components?: object & {
+    securitySchemes?: Record<string, Record<string, unknown>>;
+  };
+  paths?: Record<string, OpenApiPathItem>;
+};
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
+
+const ADMIN_PUBLIC_PATHS = new Set([
+  '/admin/api/setup',
+  '/admin/api/setup/status',
+  '/admin/api/auth/login',
+  '/admin/api/auth/refresh',
+]);
+
+const USER_BEARER_PATHS = new Set([
+  '/api/auth/link/phone',
+  '/api/auth/verify-link-phone',
+  '/api/auth/mfa/totp/enroll',
+  '/api/auth/mfa/totp/verify',
+  '/api/auth/mfa/totp',
+  '/api/auth/mfa/factors',
+  '/api/auth/change-password',
+  '/api/auth/change-email',
+  '/api/auth/passkeys/register-options',
+  '/api/auth/passkeys/register',
+  '/api/auth/passkeys',
+  '/api/auth/passkeys/{credentialId}',
+  '/api/auth/me',
+  '/api/auth/profile',
+  '/api/auth/sessions',
+  '/api/auth/sessions/{id}',
+  '/api/auth/identities',
+  '/api/auth/identities/{identityId}',
+  '/api/auth/link/email',
+  '/api/auth/oauth/link/{provider}',
+  '/api/push/register',
+  '/api/push/unregister',
+  '/api/push/topic/subscribe',
+  '/api/push/topic/unsubscribe',
+]);
+
+const USER_BEARER_PREFIXES = [
+  '/api/room/media/realtime/',
+];
+
+const SERVICE_KEY_ONLY_PATHS = new Set([
+  '/api/db/broadcast',
+  '/api/sql',
+  '/api/push/send',
+  '/api/push/send-many',
+  '/api/push/send-to-token',
+  '/api/push/send-to-topic',
+  '/api/push/broadcast',
+  '/api/push/logs',
+  '/api/push/tokens',
+  '/api/analytics/query',
+  '/api/analytics/events',
+]);
+
+const SERVICE_KEY_ONLY_PREFIXES = [
+  '/admin/api/internal/',
+  '/admin/api/backup/',
+  '/api/auth/admin/',
+  '/api/kv/',
+  '/api/d1/',
+  '/api/vectorize/',
+];
+
+function isOperation(value: unknown): value is OpenApiOperation {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasPrefix(path: string, prefixes: string[]): boolean {
+  return prefixes.some((prefix) => path.startsWith(prefix));
+}
+
+function getSecurityForPath(path: string): OpenApiSecurityRequirement[] | undefined {
+  if (ADMIN_PUBLIC_PATHS.has(path)) return undefined;
+
+  if (SERVICE_KEY_ONLY_PATHS.has(path) || hasPrefix(path, SERVICE_KEY_ONLY_PREFIXES)) {
+    return [{ serviceKeyAuth: [] }];
+  }
+
+  if (path.startsWith('/admin/api/')) {
+    return [{ adminBearerAuth: [] }, { serviceKeyAuth: [] }];
+  }
+
+  if (USER_BEARER_PATHS.has(path) || hasPrefix(path, USER_BEARER_PREFIXES)) {
+    return [{ userBearerAuth: [] }];
+  }
+
+  return undefined;
+}
+
+export function normalizeOpenApiDocument(spec: OpenApiSpec, origin?: string): OpenApiSpec {
+  if (origin) {
+    spec.servers = [
+      {
+        url: origin,
+        description: 'Current EdgeBase instance',
+      },
+    ];
+  }
+
+  const components = (spec.components ??= {});
+  const securitySchemes = (components.securitySchemes ??= {});
+
+  securitySchemes.adminBearerAuth ??= {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+    description: 'Admin JWT used by the Admin Dashboard.',
+  };
+  securitySchemes.userBearerAuth ??= {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+    description: 'User access token for authenticated client endpoints.',
+  };
+  securitySchemes.serviceKeyAuth ??= {
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-EdgeBase-Service-Key',
+    description: 'Scoped service key for internal or server-side operations.',
+  };
+
+  for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+    const security = getSecurityForPath(path);
+    if (!security) continue;
+
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!HTTP_METHODS.has(method) || !isOperation(operation) || operation.security) continue;
+      operation.security = security;
+    }
+  }
+
+  return spec;
+}

package/src/lib/pagination.ts

@@ -0,0 +1,19 @@
+/**
+ * Pagination parameter validation.
+ *
+ * Clamps limit to 1..100 (default 20) and offset to ≥0 (default 0).
+ * Handles NaN, negative, and absurdly large values safely.
+ */
+
+export function parsePagination(
+  limitParam: string | undefined,
+  offsetParam: string | undefined,
+): { limit: number; offset: number } {
+  const rawLimit = parseInt(limitParam || '20', 10);
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, 100) : 20;
+
+  const rawOffset = parseInt(offsetParam || '0', 10);
+  const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? rawOffset : 0;
+
+  return { limit, offset };
+}

package/src/lib/password-policy.ts

@@ -0,0 +1,102 @@
+/**
+ * Password Policy — validates passwords against configurable rules + HIBP k-anonymity check.
+ *
+ * HIBP: Uses k-anonymity (first 5 chars of SHA-1 hash) to check if password has been leaked.
+ * Fail-open: If the HIBP API is unavailable, the password is accepted (no false negatives).
+ */
+import type { PasswordPolicyConfig } from '@edge-base/shared';
+
+export interface PasswordValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a password against the configured policy.
+ * Returns { valid: true } if all checks pass, or { valid: false, errors: [...] } with all failures.
+ */
+export async function validatePassword(
+  password: string,
+  policy?: PasswordPolicyConfig,
+): Promise<PasswordValidationResult> {
+  const errors: string[] = [];
+
+  // Default minLength is 8 regardless of policy config
+  const minLength = policy?.minLength ?? 8;
+
+  if (password.length < minLength) {
+    errors.push(`Password must be at least ${minLength} characters.`);
+  }
+
+  if (policy?.requireUppercase && !/[A-Z]/.test(password)) {
+    errors.push('Password must contain at least one uppercase letter.');
+  }
+
+  if (policy?.requireLowercase && !/[a-z]/.test(password)) {
+    errors.push('Password must contain at least one lowercase letter.');
+  }
+
+  if (policy?.requireNumber && !/\d/.test(password)) {
+    errors.push('Password must contain at least one digit.');
+  }
+
+  if (policy?.requireSpecial && !/[^A-Za-z0-9]/.test(password)) {
+    errors.push('Password must contain at least one special character.');
+  }
+
+  // HIBP check (k-anonymity, fail-open)
+  if (policy?.checkLeaked && errors.length === 0) {
+    const leaked = await checkHIBP(password);
+    if (leaked) {
+      errors.push('This password has been found in a data breach. Please choose a different password.');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Check if a password has been leaked using HIBP's k-anonymity API.
+ * Returns true if the password is found in the breach database.
+ * Fail-open: returns false on any error (network, timeout, etc.).
+ */
+async function checkHIBP(password: string): Promise<boolean> {
+  try {
+    // SHA-1 hash the password
+    const encoder = new TextEncoder();
+    const data = encoder.encode(password);
+    const hashBuffer = await crypto.subtle.digest('SHA-1', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('').toUpperCase();
+
+    const prefix = hashHex.substring(0, 5);
+    const suffix = hashHex.substring(5);
+
+    // Fetch range from HIBP API (k-anonymity: only send first 5 chars)
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000); // 3s timeout
+
+    const resp = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
+      signal: controller.signal,
+      headers: { 'User-Agent': 'EdgeBase-PasswordPolicy' },
+    });
+    clearTimeout(timeout);
+
+    if (!resp.ok) return false; // fail-open
+
+    const text = await resp.text();
+    // Each line is "SUFFIX:COUNT"
+    const lines = text.split('\n');
+    for (const line of lines) {
+      const [lineSuffix] = line.trim().split(':');
+      if (lineSuffix === suffix) {
+        return true; // password found in breach
+      }
+    }
+
+    return false;
+  } catch {
+    // Fail-open: network error, timeout, etc.
+    return false;
+  }
+}

package/src/lib/password.ts

@@ -0,0 +1,145 @@
+/**
+ * Password hashing — PBKDF2-SHA256 via Web Crypto API
+ *
+ * Workers-compatible (no native modules needed).
+ * Format: `pbkdf2:sha256:100000:{salt_base64}:{hash_base64}`
+ *
+ * Also supports verifying imported password hashes:
+ *   - bcrypt ($2a$, $2b$, $2y$) via bcryptjs (pure JS, Workers-compatible)
+ *   - Lazy re-hashing: needsRehash() returns true for non-PBKDF2 formats
+ */
+import bcrypt from 'bcryptjs';
+
+// ─── Constants ───
+
+const ALGORITHM = 'PBKDF2';
+const HASH_ALGO = 'SHA-256';
+// Cloudflare Workers' WebCrypto PBKDF2 currently rejects iteration counts above 100000.
+const ITERATIONS = 100_000;
+const SALT_LENGTH = 16;          // 128-bit salt
+const KEY_LENGTH = 32;           // 256-bit derived key
+
+// ─── Helpers ───
+
+function toBase64(buffer: ArrayBuffer): string {
+  return btoa(String.fromCharCode(...new Uint8Array(buffer)));
+}
+
+function fromBase64(base64: string): Uint8Array {
+  return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
+
+// ─── Public API ───
+
+/**
+ * Hash a password using PBKDF2-SHA256.
+ * Returns a self-describing string: `pbkdf2:sha256:{iterations}:{salt_b64}:{hash_b64}`
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(password),
+    ALGORITHM,
+    false,
+    ['deriveBits'],
+  );
+
+  const hash = await crypto.subtle.deriveBits(
+    {
+      name: ALGORITHM,
+      salt,
+      iterations: ITERATIONS,
+      hash: HASH_ALGO,
+    },
+    keyMaterial,
+    KEY_LENGTH * 8,  // bits
+  );
+
+  return `pbkdf2:sha256:${ITERATIONS}:${toBase64(salt.buffer)}:${toBase64(hash)}`;
+}
+
+/**
+ * Verify a password against a stored hash.
+ * Supports:
+ *   - pbkdf2:sha256:{iterations}:{salt_b64}:{hash_b64} (native format)
+ *   - $2a$... / $2b$... / $2y$... (bcrypt, imported hashes)
+ */
+export async function verifyPassword(
+  password: string,
+  storedHash: string,
+): Promise<boolean> {
+  // Native PBKDF2 format
+  if (storedHash.startsWith('pbkdf2:')) {
+    return verifyPBKDF2(password, storedHash);
+  }
+
+  // bcrypt format ($2a$, $2b$, $2y$)
+  if (storedHash.startsWith('$2a$') || storedHash.startsWith('$2b$') || storedHash.startsWith('$2y$')) {
+    return bcrypt.compareSync(password, storedHash);
+  }
+
+  // Unknown format — reject
+  return false;
+}
+
+/**
+ * Check if a stored hash needs to be re-hashed to the native format.
+ * Returns true for non-PBKDF2 formats (bcrypt, etc.).
+ */
+export function needsRehash(storedHash: string): boolean {
+  return !storedHash.startsWith('pbkdf2:');
+}
+
+/**
+ * Check if a string is a recognized password hash format.
+ * Used during import to distinguish pre-hashed passwords from plaintext.
+ */
+export function isPasswordHash(value: string): boolean {
+  if (value.startsWith('pbkdf2:sha256:')) return true;
+  if (value.startsWith('$2a$') || value.startsWith('$2b$') || value.startsWith('$2y$')) return true;
+  return false;
+}
+
+// ─── PBKDF2 Verification (internal) ───
+
+async function verifyPBKDF2(password: string, storedHash: string): Promise<boolean> {
+  const parts = storedHash.split(':');
+  if (parts.length !== 5 || parts[0] !== 'pbkdf2' || parts[1] !== 'sha256') {
+    return false;
+  }
+
+  const iterations = parseInt(parts[2], 10);
+  const salt = fromBase64(parts[3]);
+  const expectedHash = fromBase64(parts[4]);
+
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(password),
+    ALGORITHM,
+    false,
+    ['deriveBits'],
+  );
+
+  const derivedBits = await crypto.subtle.deriveBits(
+    {
+      name: ALGORITHM,
+      salt: salt as unknown as BufferSource,
+      iterations,
+      hash: HASH_ALGO,
+    },
+    keyMaterial,
+    KEY_LENGTH * 8,
+  );
+
+  // Constant-time comparison to prevent timing attacks
+  const derived = new Uint8Array(derivedBits);
+  if (derived.length !== expectedHash.length) return false;
+
+  let diff = 0;
+  for (let i = 0; i < derived.length; i++) {
+    diff |= derived[i] ^ expectedHash[i];
+  }
+  return diff === 0;
+}