@edge-base/server 0.1.1

package/src/lib/startup-config.ts

@@ -0,0 +1,99 @@
+import { materializeConfig, type EdgeBaseConfig } from '@edge-base/shared';
+
+function hasConfigContent(config: unknown): config is EdgeBaseConfig {
+  return Boolean(
+    config &&
+    typeof config === 'object' &&
+    !Array.isArray(config) &&
+    Object.keys(config as Record<string, unknown>).length > 0,
+  );
+}
+
+function shouldPreferTestConfig(
+  processEnv: Record<string, string | undefined> | undefined,
+): boolean {
+  if (!processEnv) {
+    return false;
+  }
+
+  if (processEnv.EDGEBASE_USE_TEST_CONFIG === '1' || processEnv.EDGEBASE_USE_TEST_CONFIG === 'true') {
+    return true;
+  }
+
+  if (processEnv.VITEST === '1' || processEnv.VITEST === 'true') {
+    return true;
+  }
+
+  if ((processEnv.VITEST_WORKER_ID ?? '').trim().length > 0) {
+    return true;
+  }
+
+  if ((processEnv.VITEST_POOL_ID ?? '').trim().length > 0) {
+    return true;
+  }
+
+  return processEnv.NODE_ENV === 'test';
+}
+
+async function loadMaterializedTestConfig(
+  loadTestConfig: () => Promise<unknown>,
+): Promise<EdgeBaseConfig | null> {
+  let resolvedConfig: unknown = null;
+  try {
+    const mod = await loadTestConfig();
+    resolvedConfig = (mod as { default?: unknown })?.default ?? mod;
+  } catch {
+    // Test-only config is optional in packaged/runtime environments.
+  }
+
+  if (!hasConfigContent(resolvedConfig)) {
+    return null;
+  }
+
+  return materializeConfig(resolvedConfig as EdgeBaseConfig);
+}
+
+export function parseProcessEnvConfig(
+  processEnv: Record<string, string | undefined> | undefined,
+): EdgeBaseConfig | null {
+  const rawConfig = processEnv?.EDGEBASE_CONFIG;
+  if (!rawConfig || rawConfig.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(rawConfig) as EdgeBaseConfig;
+    if (!hasConfigContent(parsed)) {
+      return null;
+    }
+
+    return materializeConfig(parsed);
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveStartupConfig(
+  generatedConfig: unknown,
+  loadTestConfig: () => Promise<unknown>,
+  processEnv: Record<string, string | undefined> | undefined,
+  options?: { preferTestConfig?: boolean },
+): Promise<EdgeBaseConfig | null> {
+  const processEnvConfig = parseProcessEnvConfig(processEnv);
+  if (processEnvConfig) {
+    return processEnvConfig;
+  }
+
+  if (options?.preferTestConfig || shouldPreferTestConfig(processEnv)) {
+    const preferredTestConfig = await loadMaterializedTestConfig(loadTestConfig);
+    if (preferredTestConfig) {
+      return preferredTestConfig;
+    }
+  }
+
+  if (hasConfigContent(generatedConfig)) {
+    return materializeConfig(generatedConfig as EdgeBaseConfig);
+  }
+
+  return loadMaterializedTestConfig(loadTestConfig);
+}

package/src/lib/totp.ts

@@ -0,0 +1,242 @@
+/**
+ * TOTP — RFC 6238 Time-Based One-Time Password implementation.
+ *
+ * Uses Web Crypto API (no Node.js dependencies) for Cloudflare Workers compatibility.
+ * Standard: 6-digit codes, 30-second step, SHA-1 HMAC.
+ */
+
+// ─── Constants ───
+
+const DIGITS = 6;
+const STEP = 30;  // seconds
+const WINDOW = 1; // accept ±1 step (covers clock skew)
+
+// ─── Secret Generation ───
+
+/** Generate a random TOTP secret (20 bytes = 160 bits, standard for SHA-1). */
+export function generateTOTPSecret(): string {
+  const bytes = new Uint8Array(20);
+  crypto.getRandomValues(bytes);
+  return base32Encode(bytes);
+}
+
+/** Generate an otpauth:// URI for QR code scanning. */
+export function generateTOTPUri(
+  secret: string,
+  email: string,
+  issuer: string,
+): string {
+  const encodedIssuer = encodeURIComponent(issuer);
+  const encodedEmail = encodeURIComponent(email);
+  return `otpauth://totp/${encodedIssuer}:${encodedEmail}?secret=${secret}&issuer=${encodedIssuer}&algorithm=SHA1&digits=${DIGITS}&period=${STEP}`;
+}
+
+// ─── TOTP Verification ───
+
+/**
+ * Verify a TOTP code against the secret.
+ * Accepts codes within ±window steps (default: ±1 = 90 second window).
+ */
+export async function verifyTOTP(
+  secret: string,
+  code: string,
+  window: number = WINDOW,
+): Promise<boolean> {
+  if (!code || code.length !== DIGITS) return false;
+
+  const now = Math.floor(Date.now() / 1000);
+  const counter = Math.floor(now / STEP);
+
+  for (let i = -window; i <= window; i++) {
+    const expected = await generateTOTPCode(secret, counter + i);
+    if (timingSafeEqual(code, expected)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Generate a TOTP code for a given counter value. */
+async function generateTOTPCode(secret: string, counter: number): Promise<string> {
+  const key = base32Decode(secret);
+  const counterBytes = new Uint8Array(8);
+  const view = new DataView(counterBytes.buffer);
+  view.setBigUint64(0, BigInt(counter));
+
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    key as unknown as BufferSource,
+    { name: 'HMAC', hash: 'SHA-1' },
+    false,
+    ['sign'],
+  );
+
+  const hmac = new Uint8Array(
+    await crypto.subtle.sign('HMAC', cryptoKey, counterBytes),
+  );
+
+  // Dynamic truncation (RFC 4226 §5.4)
+  const offset = hmac[hmac.length - 1] & 0x0f;
+  const binary =
+    ((hmac[offset] & 0x7f) << 24) |
+    ((hmac[offset + 1] & 0xff) << 16) |
+    ((hmac[offset + 2] & 0xff) << 8) |
+    (hmac[offset + 3] & 0xff);
+
+  const otp = binary % 10 ** DIGITS;
+  return otp.toString().padStart(DIGITS, '0');
+}
+
+// ─── Recovery Codes ───
+
+/**
+ * Generate recovery codes (8 codes, 8 characters each).
+ * Returns plaintext codes. Caller must hash them before storage.
+ */
+export function generateRecoveryCodes(count: number = 8): string[] {
+  const codes: string[] = [];
+  const charset = 'abcdefghjkmnpqrstuvwxyz23456789'; // no ambiguous chars (0/o, 1/l/i)
+  for (let i = 0; i < count; i++) {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    let code = '';
+    for (const b of bytes) {
+      code += charset[b % charset.length];
+    }
+    codes.push(code);
+  }
+  return codes;
+}
+
+// ─── Encryption (AES-GCM for secret storage) ───
+
+/**
+ * Encrypt the TOTP secret for storage using AES-256-GCM.
+ * @param plaintext The TOTP secret to encrypt
+ * @param keyMaterial The encryption key (e.g., JWT_USER_SECRET)
+ */
+export async function encryptSecret(plaintext: string, keyMaterial: string): Promise<string> {
+  const key = await deriveEncryptionKey(keyMaterial);
+  const iv = new Uint8Array(12);
+  crypto.getRandomValues(iv);
+  const encoded = new TextEncoder().encode(plaintext);
+
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded),
+  );
+
+  // Format: base64(iv + ciphertext)
+  const combined = new Uint8Array(iv.length + ciphertext.length);
+  combined.set(iv);
+  combined.set(ciphertext, iv.length);
+
+  return uint8ArrayToBase64(combined);
+}
+
+/**
+ * Decrypt a stored TOTP secret.
+ * @param encrypted Base64-encoded (iv + ciphertext)
+ * @param keyMaterial The encryption key (e.g., JWT_USER_SECRET)
+ */
+export async function decryptSecret(encrypted: string, keyMaterial: string): Promise<string> {
+  const key = await deriveEncryptionKey(keyMaterial);
+  const combined = base64ToUint8Array(encrypted);
+  const iv = combined.slice(0, 12);
+  const ciphertext = combined.slice(12);
+
+  const decrypted = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext,
+  );
+
+  return new TextDecoder().decode(decrypted);
+}
+
+async function deriveEncryptionKey(keyMaterial: string): Promise<CryptoKey> {
+  const raw = new TextEncoder().encode(keyMaterial);
+  const hash = await crypto.subtle.digest('SHA-256', raw);
+  return crypto.subtle.importKey(
+    'raw',
+    hash,
+    { name: 'AES-GCM' },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+// ─── Utilities ───
+
+/** Timing-safe string comparison to prevent timing attacks. */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+// ─── Base32 ───
+
+const BASE32_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function base32Encode(data: Uint8Array): string {
+  let result = '';
+  let bits = 0;
+  let buffer = 0;
+
+  for (const byte of data) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      result += BASE32_CHARS[(buffer >> bits) & 0x1f];
+    }
+  }
+
+  if (bits > 0) {
+    result += BASE32_CHARS[(buffer << (5 - bits)) & 0x1f];
+  }
+
+  return result;
+}
+
+function base32Decode(encoded: string): Uint8Array {
+  const cleaned = encoded.toUpperCase().replace(/[^A-Z2-7]/g, '');
+  const bytes: number[] = [];
+  let bits = 0;
+  let buffer = 0;
+
+  for (const char of cleaned) {
+    const val = BASE32_CHARS.indexOf(char);
+    if (val === -1) continue;
+    buffer = (buffer << 5) | val;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 0xff);
+    }
+  }
+
+  return new Uint8Array(bytes);
+}
+
+// ─── Base64 ───
+
+function uint8ArrayToBase64(data: Uint8Array): string {
+  let binary = '';
+  for (const byte of data) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function base64ToUint8Array(str: string): Uint8Array {
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/lib/uuid.ts

@@ -0,0 +1,87 @@
+/**
+ * UUID v7 Monotonic generation utility.
+ * Manual implementation using crypto.getRandomValues() — no external dependency.
+ * RFC 9562 compliant: 48-bit unix_ts_ms + 4-bit version(7) + 12-bit rand_a + 2-bit var(10) + 62-bit rand_b.
+ * Time-ordered for natural cursor pagination on PK.
+ */
+
+const HEX = '0123456789abcdef';
+let lastTimestamp = -1;
+let lastBytes: Uint8Array | null = null;
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = '';
+  for (let i = 0; i < bytes.length; i++) {
+    hex += HEX[bytes[i] >> 4] + HEX[bytes[i] & 0x0f];
+  }
+  return hex;
+}
+
+function writeTimestamp(bytes: Uint8Array, timestamp: number): void {
+  bytes[0] = (timestamp / 2 ** 40) & 0xff;
+  bytes[1] = (timestamp / 2 ** 32) & 0xff;
+  bytes[2] = (timestamp / 2 ** 24) & 0xff;
+  bytes[3] = (timestamp / 2 ** 16) & 0xff;
+  bytes[4] = (timestamp / 2 ** 8) & 0xff;
+  bytes[5] = timestamp & 0xff;
+}
+
+function createRandomUuidBytes(timestamp: number): Uint8Array {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  writeTimestamp(bytes, timestamp);
+
+  // version: 4 bits = 0111 (7)
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+
+  // variant: 2 bits = 10
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  return bytes;
+}
+
+function incrementMonotonicTail(bytes: Uint8Array): boolean {
+  for (let i = 15; i >= 6; i--) {
+    const mask = i === 6 ? 0x0f : i === 8 ? 0x3f : 0xff;
+    const fixedBits = i === 6 ? 0x70 : i === 8 ? 0x80 : 0x00;
+    const value = bytes[i] & mask;
+
+    if (value < mask) {
+      bytes[i] = fixedBits | (value + 1);
+      return true;
+    }
+
+    bytes[i] = fixedBits;
+  }
+
+  return false;
+}
+
+/**
+ * Generate a UUID v7 string.
+ * Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+ * where y is one of [8, 9, a, b]
+ */
+export function generateId(): string {
+  let timestamp = Date.now();
+  if (timestamp < lastTimestamp) {
+    timestamp = lastTimestamp;
+  }
+
+  let bytes: Uint8Array;
+  if (lastBytes !== null && timestamp === lastTimestamp) {
+    bytes = lastBytes.slice();
+    if (!incrementMonotonicTail(bytes)) {
+      timestamp = lastTimestamp + 1;
+      bytes = createRandomUuidBytes(timestamp);
+    }
+  } else {
+    bytes = createRandomUuidBytes(timestamp);
+  }
+
+  lastTimestamp = timestamp;
+  lastBytes = bytes;
+
+  const hex = bytesToHex(bytes);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/lib/validation.ts

@@ -0,0 +1,205 @@
+/**
+ * Field validation engine for table schemas.
+ * Validates request body against schema field definitions.
+ */
+import type { SchemaField } from '@edge-base/shared';
+import { buildEffectiveSchema } from './schema.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: Record<string, string>;
+}
+
+export const CUSTOM_RECORD_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+export const CUSTOM_RECORD_ID_MESSAGE =
+  'Record ID must use English letters, numbers, hyphen (-), or underscore (_).';
+
+export function validateCustomRecordId(value: unknown): string | null {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string') return 'Record ID must be a string.';
+  return CUSTOM_RECORD_ID_PATTERN.test(value) ? null : CUSTOM_RECORD_ID_MESSAGE;
+}
+
+export function summarizeValidationErrors(errors: Record<string, string>): string {
+  const entries = Object.entries(errors);
+  if (entries.length === 0) return 'Validation failed.';
+
+  const [field, message] = entries[0];
+  const label = field === 'id' ? 'record ID' : `'${field}'`;
+
+  if (entries.length === 1) {
+    return `Invalid ${label}. ${message}`;
+  }
+
+  return `Request body failed validation. First issue: invalid ${label}. ${message}`;
+}
+
+/**
+ * Validate a record against a table schema for insert operations.
+ * Checks required fields, types, constraints (min/max/pattern/enum).
+ * When schema is undefined (schemaless,), all fields are accepted.
+ */
+export function validateInsert(
+  data: Record<string, unknown>,
+  schema?: Record<string, SchemaField | false>,
+): ValidationResult {
+  // Schemaless: accept everything
+  if (!schema) return { valid: true, errors: {} };
+
+  const effective = buildEffectiveSchema(schema);
+  const errors: Record<string, string> = {};
+  const idError = validateCustomRecordId(data.id);
+  if (idError) {
+    errors.id = idError;
+  }
+
+  for (const [name, field] of Object.entries(effective)) {
+    // Skip auto-managed fields
+    if (name === 'id' || name === 'createdAt' || name === 'updatedAt') continue;
+
+    const value = data[name];
+
+    // Check required
+    if (field.required && (value === undefined || value === null)) {
+      if (field.default === undefined) {
+        errors[name] = 'Field is required.';
+        continue;
+      }
+    }
+
+    // Skip validation if value is absent (optional field)
+    if (value === undefined || value === null) continue;
+
+    // Validate type and constraints
+    const typeErr = validateType(value, field);
+    if (typeErr) {
+      errors[name] = typeErr;
+    }
+  }
+
+  // Unknown fields are silently ignored — the SQL layer filters them out
+  // (schema-defined: columns = Object.keys(record).filter(k => k in effective)).
+  // Rejecting unknown fields here would break SDK payloads that send extra metadata.
+
+  return { valid: Object.keys(errors).length === 0, errors };
+}
+
+/**
+ * Validate a record against a table schema for update operations.
+ * Partial validation — only checks provided fields.
+ * When schema is undefined (schemaless,), all fields are accepted.
+ */
+export function validateUpdate(
+  data: Record<string, unknown>,
+  schema?: Record<string, SchemaField | false>,
+): ValidationResult {
+  // Schemaless: accept everything
+  if (!schema) return { valid: true, errors: {} };
+
+  const effective = buildEffectiveSchema(schema);
+  const errors: Record<string, string> = {};
+
+  for (const [name, value] of Object.entries(data)) {
+    // Skip auto-managed fields
+    if (name === 'id' || name === 'createdAt' || name === 'updatedAt') continue;
+
+    const field = effective[name];
+    if (!field) continue;
+
+    if (isFieldOperator(value)) {
+      if (value.$op === 'deleteField' && field.required) {
+        errors[name] = 'Field is required and cannot be deleted.';
+      }
+      continue;
+    }
+
+    // Check required (can't set to null if required)
+    if (field.required && (value === null || value === undefined)) {
+      errors[name] = 'Field is required and cannot be null.';
+      continue;
+    }
+
+    if (value === null || value === undefined) continue;
+
+    const typeErr = validateType(value, field);
+    if (typeErr) {
+      errors[name] = typeErr;
+    }
+  }
+
+  return { valid: Object.keys(errors).length === 0, errors };
+}
+
+// ─── Type & Constraint Validation ───
+
+function validateType(value: unknown, field: SchemaField): string | null {
+  switch (field.type) {
+    case 'string':
+    case 'text':
+      if (typeof value !== 'string') return 'Must be a string.';
+      return validateStringConstraints(value, field);
+
+    case 'number':
+      if (typeof value !== 'number' || Number.isNaN(value)) return 'Must be a number.';
+      return validateNumberConstraints(value, field);
+
+    case 'boolean':
+      if (typeof value !== 'boolean') return 'Must be a boolean.';
+      return null;
+
+    case 'datetime':
+      if (typeof value !== 'string') return 'Must be a datetime string.';
+      if (Number.isNaN(Date.parse(value))) return 'Invalid datetime format.';
+      return null;
+
+    case 'json':
+      // JSON fields accept any serializable value
+      return null;
+
+    default:
+      return null;
+  }
+}
+
+function validateStringConstraints(value: string, field: SchemaField): string | null {
+  if (field.min !== undefined && value.length < field.min) {
+    return `Must be at least ${field.min} characters.`;
+  }
+  if (field.max !== undefined && value.length > field.max) {
+    return `Must be at most ${field.max} characters.`;
+  }
+  if (field.pattern !== undefined) {
+    const regex = new RegExp(field.pattern);
+    if (!regex.test(value)) return `Must match pattern: ${field.pattern}`;
+  }
+  if (field.enum !== undefined && !field.enum.includes(value)) {
+    return `Must be one of: ${field.enum.join(', ')}`;
+  }
+  return null;
+}
+
+function validateNumberConstraints(value: number, field: SchemaField): string | null {
+  if (field.min !== undefined && value < field.min) {
+    return `Must be at least ${field.min}.`;
+  }
+  if (field.max !== undefined && value > field.max) {
+    return `Must be at most ${field.max}.`;
+  }
+  return null;
+}
+
+// ─── Field Operator Detection ───
+
+export interface FieldOperator {
+  $op: 'increment' | 'deleteField';
+  value?: number;
+}
+
+export function isFieldOperator(value: unknown): value is FieldOperator {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$op' in value &&
+    typeof (value as FieldOperator).$op === 'string'
+  );
+}

package/src/lib/version.ts

@@ -0,0 +1,2 @@
+/** Single source of truth for server version. Keep in sync with package.json. */
+export const SERVER_VERSION = '0.1.0';

package/src/lib/websocket-pending.ts

@@ -0,0 +1,40 @@
+function parsePendingCount(value: string | null): number {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export async function getPendingWebSocketCount(
+  kv: KVNamespace,
+  key: string,
+): Promise<number> {
+  return parsePendingCount(await kv.get(key));
+}
+
+export async function acquirePendingWebSocketSlot(
+  kv: KVNamespace,
+  key: string,
+  maxPending: number,
+  ttlSeconds: number,
+): Promise<boolean> {
+  const current = parsePendingCount(await kv.get(key));
+  if (current >= maxPending) {
+    return false;
+  }
+
+  await kv.put(key, String(current + 1), { expirationTtl: ttlSeconds });
+  return true;
+}
+
+export async function releasePendingWebSocketSlot(
+  kv: KVNamespace,
+  key: string,
+  ttlSeconds: number,
+): Promise<void> {
+  const current = parsePendingCount(await kv.get(key));
+  if (current <= 1) {
+    await kv.delete(key);
+    return;
+  }
+
+  await kv.put(key, String(current - 1), { expirationTtl: ttlSeconds });
+}