tetherdb 0.1.0 → 0.1.1

package/dist/vite/index.js

@@ -0,0 +1,2013 @@
+// src/server/server.ts
+import * as http from "http";
+import { WebSocketServer } from "ws";
+
+// src/shared/path.ts
+function normalizeBasePath(path3) {
+  if (path3 === "" || path3 === "/") return "";
+  if (path3.endsWith("/")) path3 = path3.slice(0, path3.length - 1);
+  if (!path3.startsWith("/")) path3 = `/${path3}`;
+  return path3 === "/" ? "" : path3;
+}
+
+// src/server/crypto.ts
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+var DEFAULT_TOKEN_EXPIRES_IN = 7 * 24 * 60 * 60;
+async function hashPassword(password) {
+  const salt = crypto.randomBytes(16).toString("hex");
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(
+      password.normalize("NFKC"),
+      salt,
+      64,
+      SCRYPT_OPTIONS,
+      (err, derivedKey) => {
+        if (err) return reject(err);
+        resolve(`scrypt$${salt}$${derivedKey.toString("hex")}`);
+      }
+    );
+  });
+}
+async function verifyPasswordHash(password, storedHash) {
+  if (!storedHash || typeof storedHash !== "string") return false;
+  const parts = storedHash.split("$");
+  if (parts.length !== 3 || parts[0] !== "scrypt") return false;
+  const [, salt, expectedHex] = parts;
+  return new Promise((resolve) => {
+    crypto.scrypt(
+      password.normalize("NFKC"),
+      salt,
+      64,
+      SCRYPT_OPTIONS,
+      (err, derivedKey) => {
+        if (err) return resolve(false);
+        const expectedBuf = Buffer.from(expectedHex, "hex");
+        if (derivedKey.length !== expectedBuf.length) return resolve(false);
+        resolve(crypto.timingSafeEqual(derivedKey, expectedBuf));
+      }
+    );
+  });
+}
+async function verifyDummyPasswordHash(password) {
+  if (!dummyPasswordHashPromise) {
+    dummyPasswordHashPromise = hashPassword("TetherDB:dummy_seed_password");
+  }
+  const dummyHash = await dummyPasswordHashPromise;
+  return verifyPasswordHash(password, dummyHash);
+}
+function createSessionToken(userId, username, secret, expiresInSeconds = DEFAULT_TOKEN_EXPIRES_IN) {
+  const expiresAt = Math.floor(Date.now() / 1e3) + expiresInSeconds;
+  const payload = JSON.stringify({
+    userId,
+    username,
+    expiresAt
+  });
+  const payloadB64 = Buffer.from(payload, "utf-8").toString("base64url");
+  const signature = crypto.createHmac("sha256", secret).update(payloadB64).digest("base64url");
+  return `${payloadB64}.${signature}`;
+}
+function verifySessionToken(token, secret) {
+  if (!token || typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length !== 2) return null;
+  const [payloadB64, signature] = parts;
+  const expectedSig = crypto.createHmac("sha256", secret).update(payloadB64).digest("base64url");
+  if (signature.length !== expectedSig.length || !crypto.timingSafeEqual(
+    Buffer.from(signature, "utf-8"),
+    Buffer.from(expectedSig, "utf-8")
+  )) {
+    return null;
+  }
+  try {
+    const raw = Buffer.from(payloadB64, "base64url").toString("utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.userId !== "string" || !parsed.userId || typeof parsed.username !== "string" || !parsed.username || typeof parsed.expiresAt !== "number" || !Number.isFinite(parsed.expiresAt) || parsed.expiresAt < Math.floor(Date.now() / 1e3)) {
+      return null;
+    }
+    return {
+      userId: parsed.userId,
+      username: parsed.username,
+      expiresAt: parsed.expiresAt
+    };
+  } catch {
+    return null;
+  }
+}
+var SCRYPT_OPTIONS = {
+  N: process.env.NODE_ENV === "test" ? 512 : 16384,
+  r: 8,
+  p: 1,
+  maxmem: 32 * 1024 * 1024
+};
+var dummyPasswordHashPromise = null;
+
+// src/server/errors.ts
+var TetherServerError = class extends Error {
+  /** Error category code identifying the broad error type. */
+  code;
+  /**
+   * Initializes a new `TetherServerError`.
+   *
+   * @param code - The error category code.
+   * @param message - User-safe error description message.
+   */
+  constructor(code, message) {
+    super(message ?? getDefaultServerErrorMessage(code));
+    this.name = "TetherServerError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function getDefaultServerErrorMessage(code) {
+  switch (code) {
+    case 0 /* InvalidInput */:
+      return "Invalid request parameter";
+    case 1 /* NotFound */:
+      return "Requested resource not found";
+    case 2 /* AlreadyExists */:
+      return "Resource already exists";
+    case 3 /* Unauthorized */:
+      return "Authentication required";
+    case 4 /* AuthenticationFailed */:
+      return "Authentication failed";
+    case 5 /* LimitExceeded */:
+      return "Request or resource limit exceeded";
+    case 6 /* ConfigurationError */:
+      return "Server configuration error";
+    case 7 /* NotSupported */:
+      return "Operation not supported";
+    case 8 /* InternalError */:
+      return "Internal server error";
+  }
+}
+
+// src/server/lock.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+function isProcessAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    return code === "EPERM";
+  }
+}
+function readServerLock(baseDir) {
+  const lockPath = path2.join(baseDir, "server.lock");
+  try {
+    if (!fs2.existsSync(lockPath)) return null;
+    const content = fs2.readFileSync(lockPath, "utf-8");
+    const info = JSON.parse(content);
+    if (typeof info.pid === "number" && isProcessAlive(info.pid)) {
+      return info;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function acquireServerLock(baseDir, details) {
+  fs2.mkdirSync(baseDir, { recursive: true });
+  const lockPath = path2.join(baseDir, "server.lock");
+  const existing = readServerLock(baseDir);
+  if (existing && existing.pid !== process.pid) {
+    throw new TetherServerError(
+      2 /* AlreadyExists */,
+      "A TetherDB server is already running on this data directory"
+    );
+  }
+  if (fs2.existsSync(lockPath)) {
+    try {
+      fs2.unlinkSync(lockPath);
+    } catch {
+    }
+  }
+  const info = {
+    pid: process.pid,
+    port: details.port,
+    host: details.host,
+    backend: details.backend,
+    startedAt: Date.now()
+  };
+  fs2.writeFileSync(lockPath, JSON.stringify(info, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+  let isReleased = false;
+  const release = () => {
+    if (isReleased) return;
+    isReleased = true;
+    try {
+      if (fs2.existsSync(lockPath)) {
+        const current = JSON.parse(
+          fs2.readFileSync(lockPath, "utf-8")
+        );
+        if (current.pid === process.pid) {
+          fs2.unlinkSync(lockPath);
+        }
+      }
+    } catch {
+    }
+  };
+  return {
+    info,
+    lockPath,
+    release
+  };
+}
+
+// src/server/rate-limiter.ts
+var RateLimiter = class {
+  store = /* @__PURE__ */ new Map();
+  windowMs;
+  maxRequests;
+  maxFailures;
+  initialBackoffMs;
+  maxBackoffMs;
+  maxEntries;
+  /**
+   * Initializes a new RateLimiter instance.
+   *
+   * @param options - Configuration options for window size, request limits, and backoff.
+   */
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? 6e4;
+    this.maxRequests = options.maxRequests ?? 60;
+    this.maxFailures = options.maxFailures ?? 3;
+    this.initialBackoffMs = options.initialBackoffMs ?? 1e3;
+    this.maxBackoffMs = options.maxBackoffMs ?? 9e5;
+    this.maxEntries = options.maxEntries ?? 1e4;
+  }
+  /**
+   * Returns the current number of tracked keys in memory.
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Checks whether the given key is currently rate limited or blocked by backoff cooldown.
+   *
+   * @param key - Identifier (e.g. IP address or username).
+   * @param now - Current timestamp in milliseconds (defaults to Date.now()).
+   * @returns `true` if requests for this key are limited; `false` otherwise.
+   */
+  isLimited(key, now = Date.now()) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    if (entry.blockedUntil > now) {
+      return true;
+    }
+    if (entry.resetAt <= now) {
+      this.store.delete(key);
+      return false;
+    }
+    return entry.count >= this.maxRequests;
+  }
+  /**
+   * Consumes one attempt for the given key if not currently limited.
+   *
+   * @param key - Identifier.
+   * @param now - Current timestamp in milliseconds.
+   * @returns `true` if request was allowed and consumed; `false` if rate limited.
+   */
+  consume(key, now = Date.now()) {
+    if (this.isLimited(key, now)) {
+      return false;
+    }
+    const entry = this.store.get(key);
+    if (!entry || entry.resetAt <= now && entry.blockedUntil <= now) {
+      this.setEntry(
+        key,
+        {
+          count: 1,
+          resetAt: now + this.windowMs,
+          failures: 0,
+          blockedUntil: 0
+        },
+        now
+      );
+      return true;
+    }
+    entry.count++;
+    return true;
+  }
+  /**
+   * Records a failed attempt for the given key and applies progressive exponential backoff.
+   *
+   * @param key - Identifier.
+   * @param now - Current timestamp in milliseconds.
+   * @returns Cooldown duration in milliseconds if blocked, or 0 if under failure threshold.
+   */
+  recordFailure(key, now = Date.now()) {
+    let entry = this.store.get(key);
+    if (!entry || entry.resetAt <= now && entry.blockedUntil <= now) {
+      entry = {
+        count: 1,
+        resetAt: now + this.windowMs,
+        failures: 0,
+        blockedUntil: 0
+      };
+      this.setEntry(key, entry, now);
+    }
+    entry.failures++;
+    if (entry.failures >= this.maxFailures) {
+      const exponent = entry.failures - this.maxFailures;
+      const backoff = Math.min(
+        this.initialBackoffMs * 2 ** exponent,
+        this.maxBackoffMs
+      );
+      entry.blockedUntil = now + backoff;
+      return backoff;
+    }
+    return 0;
+  }
+  /**
+   * Resets all failure counters and request tracking for the given key.
+   *
+   * @param key - Identifier to reset.
+   */
+  reset(key) {
+    this.store.delete(key);
+  }
+  /**
+   * Clears all stored rate limit entries.
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Purges expired entries from the internal store.
+   *
+   * @param now - Current timestamp in milliseconds.
+   */
+  cleanup(now = Date.now()) {
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.resetAt <= now && entry.blockedUntil <= now) {
+        this.store.delete(key);
+      }
+    }
+  }
+  // -- Private Helpers --------------------------------------------------------
+  setEntry(key, entry, now) {
+    if (this.store.size >= this.maxEntries && !this.store.has(key)) {
+      this.cleanup(now);
+      if (this.store.size >= this.maxEntries) {
+        const oldestKey = this.store.keys().next().value;
+        if (oldestKey !== void 0) {
+          this.store.delete(oldestKey);
+        }
+      }
+    }
+    this.store.set(key, entry);
+  }
+};
+
+// src/shared/clock.ts
+function shouldOverwrite(incoming, existing) {
+  if (!existing) return true;
+  if (incoming.timestamp > existing.timestamp) {
+    return true;
+  }
+  if (incoming.timestamp < existing.timestamp) {
+    return false;
+  }
+  const incomingClient = incoming.clientId ?? "";
+  const existingClient = existing.clientId ?? "";
+  return incomingClient >= existingClient;
+}
+
+// src/shared/types.ts
+var PROTOCOL_VERSION = 1;
+
+// src/server/validate.ts
+var MIN_USERNAME_LENGTH = 4;
+var MAX_USERNAME_LENGTH = 128;
+var MIN_PASSWORD_LENGTH = 4;
+var MAX_PASSWORD_LENGTH = 512;
+var MAX_FUTURE_TIMESTAMP_DRIFT_MS = 5 * 60 * 1e3;
+function validateTimestamp(timestamp, maxFutureDriftMs = MAX_FUTURE_TIMESTAMP_DRIFT_MS) {
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp <= 0) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      "Invalid timestamp"
+    );
+  }
+  if (timestamp > Date.now() + maxFutureDriftMs) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      "Timestamp drift exceeds maximum allowable threshold"
+    );
+  }
+  return timestamp;
+}
+function validateUserId(userId) {
+  return validateFilesystemSafe(userId, "user ID");
+}
+function validateAppId(appId) {
+  return validateFilesystemSafe(appId, "application ID");
+}
+function validateTableName(tableName) {
+  return validateFilesystemSafe(tableName, "table name");
+}
+function validateRecordId(id) {
+  if (typeof id !== "string" || id.length === 0 || id.length > 512) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      "Invalid record ID"
+    );
+  }
+  return id;
+}
+function normalizeUsername(username) {
+  return typeof username === "string" ? username.trim().toLowerCase() : "";
+}
+function validateUsername(username) {
+  if (typeof username !== "string") {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      `Username must be between ${MIN_USERNAME_LENGTH} and ${MAX_USERNAME_LENGTH} characters`
+    );
+  }
+  const normalized = normalizeUsername(username);
+  if (normalized.length < MIN_USERNAME_LENGTH || normalized.length > MAX_USERNAME_LENGTH) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      `Username must be between ${MIN_USERNAME_LENGTH} and ${MAX_USERNAME_LENGTH} characters`
+    );
+  }
+  return normalized;
+}
+function normalizePassword(password) {
+  return typeof password === "string" ? password.trim() : "";
+}
+function validatePassword(password) {
+  if (typeof password !== "string") {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      "Password must be a valid non-empty string"
+    );
+  }
+  const normalized = normalizePassword(password);
+  if (normalized.length < MIN_PASSWORD_LENGTH || normalized.length > MAX_PASSWORD_LENGTH) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      `Password must be between ${MIN_PASSWORD_LENGTH} and ${MAX_PASSWORD_LENGTH} characters`
+    );
+  }
+  return normalized;
+}
+function validateIdentifier(id, name = "identifier") {
+  if (typeof id !== "string" || !/^[a-zA-Z0-9_-]{2,128}$/.test(id)) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      `Invalid ${name}`
+    );
+  }
+  return id;
+}
+function calculateByteSize(value) {
+  if (value === null || value === void 0) return 0;
+  if (typeof value === "string") return Buffer.byteLength(value, "utf-8");
+  if (typeof value === "number") return 8;
+  if (typeof value === "boolean") return 4;
+  try {
+    return Buffer.byteLength(JSON.stringify(value), "utf-8");
+  } catch {
+    return 0;
+  }
+}
+function validateFilesystemSafe(id, name) {
+  if (typeof id !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(id)) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      `Invalid ${name}`
+    );
+  }
+  return id;
+}
+
+// src/server/storage/base/app.ts
+var AppBaseStorage = class {
+  id;
+  constructor(id) {
+    this.id = id;
+  }
+};
+function applyChangeToRecord(change, existing, seq) {
+  const isDeleted = change.op === "delete" /* Delete */;
+  const nextVersion = (existing?.version ?? 0) + 1;
+  const updatedRecord = {
+    id: change.id,
+    version: nextVersion,
+    timestamp: change.timestamp,
+    clientId: change.clientId,
+    deleted: isDeleted,
+    data: isDeleted ? null : change.data ?? null
+  };
+  const appliedChange = {
+    seq,
+    table: change.table,
+    id: change.id,
+    op: change.op,
+    version: nextVersion,
+    timestamp: change.timestamp,
+    clientId: change.clientId,
+    data: isDeleted ? void 0 : change.data
+  };
+  return { updatedRecord, appliedChange };
+}
+
+// src/server/storage/base/storage.ts
+var BaseStorage = class {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /** Optional storage base directory if disk-backed. */
+  getBaseDir() {
+    return void 0;
+  }
+  async getUserByToken(token) {
+    const payload = verifySessionToken(token, this.secret);
+    if (!payload) return void 0;
+    return this.getUser(payload.userId);
+  }
+  async getStatus(appId) {
+    const users = await this.getUsers();
+    const allApps = await this.getApps();
+    const targetApps = filterTargetApps(allApps, appId);
+    const apps = await buildAppSummaries(targetApps);
+    const status = {
+      backend: this.backend,
+      usersCount: users.length,
+      appsCount: allApps.length,
+      apps
+    };
+    const baseDir = this.getBaseDir();
+    if (baseDir !== void 0) {
+      status.baseDir = baseDir;
+    }
+    return status;
+  }
+};
+function filterTargetApps(allApps, appId) {
+  const targetApps = appId ? allApps.filter((a) => a.id === validateAppId(appId)) : allApps;
+  if (appId && targetApps.length === 0) {
+    throw new TetherServerError(
+      1 /* NotFound */,
+      `Application "${appId}" not found`
+    );
+  }
+  return targetApps;
+}
+async function buildAppSummaries(apps) {
+  const appSummaries = [];
+  for (const app of apps) {
+    const tables = await app.getTables();
+    appSummaries.push({
+      id: app.id,
+      tables: tables.map((t) => t.name)
+    });
+  }
+  return appSummaries;
+}
+
+// src/server/storage/base/table.ts
+var TableBaseStorage = class {
+  name;
+  app;
+  constructor(name, app) {
+    this.name = name;
+    this.app = app;
+  }
+  /** Applies batch mutation changes to this table. */
+  async applyChanges(user, changes) {
+    return this.app.applyChanges(
+      user,
+      targetChangesForTable(this.name, this.app.id, changes)
+    );
+  }
+};
+function filterActiveRecords(tableName, records) {
+  const items = [];
+  for (const rec of records) {
+    if (!rec.deleted) {
+      items.push({
+        ...rec,
+        table: tableName
+      });
+    }
+  }
+  return items;
+}
+function targetChangesForTable(tableName, appId, changes) {
+  return changes.map((c) => ({
+    ...c,
+    table: tableName,
+    appId
+  }));
+}
+
+// src/server/storage/base/user.ts
+var UserBaseStorage = class {
+  id;
+  username;
+  createdAt;
+  constructor(id, username, createdAt) {
+    this.id = id;
+    this.username = username;
+    this.createdAt = createdAt;
+  }
+  /** Creates a signed session token for this user. */
+  async createToken(expiresInSeconds) {
+    return createSessionToken(
+      this.id,
+      this.username,
+      this.getSecret(),
+      expiresInSeconds
+    );
+  }
+  /** Verifies whether the session token is valid for this user. */
+  async verifyToken(token) {
+    const payload = verifySessionToken(token, this.getSecret());
+    return payload !== null && payload.userId === this.id;
+  }
+};
+async function verifyUserPassword(password, passwordHash) {
+  if (!passwordHash) return false;
+  const normalized = normalizePassword(password);
+  if (!normalized) return false;
+  return verifyPasswordHash(normalized, passwordHash);
+}
+async function hashUserPassword(newPassword) {
+  const valid = validatePassword(newPassword);
+  return hashPassword(valid);
+}
+
+// src/server/storage/memory/table.ts
+var TableMemoryStorage = class extends TableBaseStorage {
+  storage;
+  constructor(name, app, storage) {
+    super(name, app);
+    this.storage = storage;
+  }
+  async getRecord(user, id) {
+    const safeId = validateRecordId(id);
+    const userState = this.storage.getUserState(user.id, this.app.id);
+    const tableMap = userState.tables.get(this.name);
+    const record = tableMap?.get(safeId);
+    if (!record || record.deleted) {
+      return void 0;
+    }
+    return record;
+  }
+  async getAllRecords(user) {
+    const userState = this.storage.getUserState(user.id, this.app.id);
+    const tableMap = userState.tables.get(this.name);
+    return tableMap ? filterActiveRecords(this.name, tableMap.values()) : [];
+  }
+  async delete() {
+    return this.app.deleteTable(this.name);
+  }
+};
+
+// src/server/storage/memory/app.ts
+var AppMemoryStorage = class extends AppBaseStorage {
+  tables = /* @__PURE__ */ new Map();
+  storage;
+  constructor(id, storage) {
+    super(id);
+    this.storage = storage;
+  }
+  async createTable(name) {
+    const safeName = validateTableName(name);
+    if (this.tables.has(safeName)) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Table already exists in this application"
+      );
+    }
+    const table = new TableMemoryStorage(safeName, this, this.storage);
+    this.tables.set(safeName, table);
+    return table;
+  }
+  async getTable(name) {
+    const safeName = validateTableName(name);
+    return this.tables.get(safeName);
+  }
+  async getTables() {
+    return Array.from(this.tables.values());
+  }
+  async applyChanges(user, changes) {
+    const userState = this.storage.getUserState(user.id, this.id);
+    const maxRecords = this.storage.options.maxRecordsPerTable ?? 1e4;
+    const maxRecordSize = this.storage.options.maxRecordSizeBytes ?? 512 * 1024;
+    const maxChangelog = this.storage.options.maxChangelogEntries ?? 1e3;
+    for (const change of changes) {
+      const tableName = validateTableName(change.table);
+      validateRecordId(change.id);
+      validateTimestamp(change.timestamp);
+      if (!this.tables.has(tableName)) {
+        throw new TetherServerError(
+          1 /* NotFound */,
+          "Table not found"
+        );
+      }
+      const payloadBytes = calculateByteSize(change.data);
+      if (payloadBytes > maxRecordSize) {
+        throw new TetherServerError(
+          5 /* LimitExceeded */,
+          "Record payload exceeds maximum allowed size"
+        );
+      }
+    }
+    const stagedTables = /* @__PURE__ */ new Map();
+    const stagedApplied = [];
+    let stagedCurrentSeq = userState.currentSeq;
+    let stagedMinSeq = userState.minSeq;
+    for (const change of changes) {
+      const tableName = validateTableName(change.table);
+      const recordId = validateRecordId(change.id);
+      let tableMap = stagedTables.get(tableName);
+      if (!tableMap) {
+        const existingTableMap = userState.tables.get(tableName);
+        tableMap = new Map(existingTableMap);
+        stagedTables.set(tableName, tableMap);
+      }
+      if (change.op === "put" /* Put */ && !tableMap.has(recordId) && tableMap.size >= maxRecords) {
+        throw new TetherServerError(
+          5 /* LimitExceeded */,
+          "Table record limit reached"
+        );
+      }
+      const existing = tableMap.get(recordId);
+      const shouldApply = !existing || shouldOverwrite(change, existing);
+      if (shouldApply) {
+        stagedCurrentSeq++;
+        const assignedSeq = stagedCurrentSeq;
+        if (stagedMinSeq === 0) {
+          stagedMinSeq = 1;
+        }
+        const { updatedRecord, appliedChange } = applyChangeToRecord(
+          change,
+          existing,
+          assignedSeq
+        );
+        tableMap.set(recordId, updatedRecord);
+        stagedApplied.push(appliedChange);
+      }
+    }
+    for (const [tableName, stagedMap] of stagedTables.entries()) {
+      userState.tables.set(tableName, stagedMap);
+    }
+    userState.currentSeq = stagedCurrentSeq;
+    userState.minSeq = stagedMinSeq;
+    userState.changelog.push(...stagedApplied);
+    if (userState.changelog.length > maxChangelog) {
+      const pruneCount = userState.changelog.length - maxChangelog;
+      userState.changelog.splice(0, pruneCount);
+      if (userState.changelog.length > 0) {
+        userState.minSeq = userState.changelog[0].seq;
+      }
+    }
+    return { applied: stagedApplied, newSeq: userState.currentSeq };
+  }
+  async getChangesSince(user, fromSeq) {
+    const userState = this.storage.getUserState(user.id, this.id);
+    const currentSeq = userState.currentSeq;
+    const minSeq = userState.minSeq;
+    if (fromSeq < minSeq && minSeq > 0 || fromSeq > currentSeq) {
+      return { changes: [], currentSeq, requiresSnapshot: true };
+    }
+    const changes = userState.changelog.filter((c) => c.seq > fromSeq);
+    return { changes, currentSeq, requiresSnapshot: false };
+  }
+  async getCurrentSeq(user) {
+    const userState = this.storage.getUserState(user.id, this.id);
+    return userState.currentSeq;
+  }
+  async delete() {
+    return this.storage.deleteApp(this.id);
+  }
+  deleteTable(name) {
+    const safeName = validateTableName(name);
+    const deleted = this.tables.delete(safeName);
+    this.storage.deleteTableInUserStates(this.id, safeName);
+    return deleted;
+  }
+};
+
+// src/server/storage/memory/storage.ts
+import * as crypto2 from "crypto";
+
+// src/server/storage/memory/user.ts
+var UserMemoryStorage = class extends UserBaseStorage {
+  storage;
+  constructor(data, storage) {
+    super(data.id, data.username, data.createdAt);
+    this.storage = storage;
+  }
+  getSecret() {
+    return this.storage.secret;
+  }
+  getUserData() {
+    const data = this.storage.getUserData(this.id);
+    if (!data) {
+      throw new TetherServerError(
+        1 /* NotFound */,
+        "User not found"
+      );
+    }
+    return data;
+  }
+  async verifyPassword(password) {
+    const data = this.getUserData();
+    return verifyUserPassword(password, data.passwordHash);
+  }
+  async changePassword(newPassword) {
+    const data = this.getUserData();
+    data.passwordHash = await hashUserPassword(newPassword);
+  }
+  async delete() {
+    return this.storage.deleteUser(this.id);
+  }
+};
+
+// src/server/storage/memory/storage.ts
+var MemoryStorage = class extends BaseStorage {
+  backend = "memory";
+  apps = /* @__PURE__ */ new Map();
+  userStates = /* @__PURE__ */ new Map();
+  // key = `${appId}:${userId}`
+  users = /* @__PURE__ */ new Map();
+  // key = userId
+  usersByUsername = /* @__PURE__ */ new Map();
+  // username -> userId
+  secret;
+  options;
+  constructor(options = {}) {
+    super(options);
+    this.options = options;
+    this.secret = options.secret ?? crypto2.randomBytes(32).toString("hex");
+  }
+  getUserState(userId, appId) {
+    const safeAppId = validateAppId(appId);
+    const safeUserId = validateUserId(userId);
+    const key = `${safeAppId}:${safeUserId}`;
+    let state = this.userStates.get(key);
+    if (!state) {
+      state = {
+        currentSeq: 0,
+        minSeq: 0,
+        tables: /* @__PURE__ */ new Map(),
+        changelog: []
+      };
+      this.userStates.set(key, state);
+    }
+    return state;
+  }
+  deleteUserState(userId) {
+    const safeUserId = validateUserId(userId);
+    let deleted = false;
+    for (const key of Array.from(this.userStates.keys())) {
+      if (key.endsWith(`:${safeUserId}`)) {
+        this.userStates.delete(key);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+  deleteAppUserStates(appId) {
+    const safeAppId = validateAppId(appId);
+    for (const key of Array.from(this.userStates.keys())) {
+      if (key.startsWith(`${safeAppId}:`)) {
+        this.userStates.delete(key);
+      }
+    }
+  }
+  deleteTableInUserStates(appId, tableName) {
+    const safeAppId = validateAppId(appId);
+    for (const [key, state] of this.userStates.entries()) {
+      if (key.startsWith(`${safeAppId}:`)) {
+        state.tables.delete(tableName);
+      }
+    }
+  }
+  async createApp(id) {
+    const safeId = validateAppId(id);
+    if (this.apps.has(safeId)) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Application already exists"
+      );
+    }
+    const app = new AppMemoryStorage(safeId, this);
+    this.apps.set(safeId, app);
+    return app;
+  }
+  async getApp(id) {
+    const safeId = validateAppId(id);
+    return this.apps.get(safeId);
+  }
+  async getApps() {
+    return Array.from(this.apps.values());
+  }
+  async createUser(username, password) {
+    const safeUsername = validateUsername(username);
+    const validPassword = validatePassword(password);
+    if (this.usersByUsername.has(safeUsername)) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Username is already registered"
+      );
+    }
+    const userId = crypto2.randomUUID();
+    const passwordHash = await hashPassword(validPassword);
+    const userData = {
+      id: userId,
+      username: safeUsername,
+      passwordHash,
+      createdAt: Date.now()
+    };
+    this.users.set(userId, userData);
+    this.usersByUsername.set(safeUsername, userId);
+    return new UserMemoryStorage(userData, this);
+  }
+  getUserData(userId) {
+    return this.users.get(userId);
+  }
+  async getUser(id) {
+    const safeUserId = validateUserId(id);
+    const data = this.users.get(safeUserId);
+    if (data) {
+      return new UserMemoryStorage(data, this);
+    }
+    return void 0;
+  }
+  async getUserByUsername(username) {
+    const safeUsername = normalizeUsername(username);
+    if (!safeUsername) return void 0;
+    const userId = this.usersByUsername.get(safeUsername);
+    if (!userId) return void 0;
+    const data = this.users.get(userId);
+    if (data) {
+      return new UserMemoryStorage(data, this);
+    }
+    return void 0;
+  }
+  async getUsers() {
+    return Array.from(this.users.values()).map(
+      (data) => new UserMemoryStorage(data, this)
+    );
+  }
+  deleteUser(id) {
+    const safeUserId = validateUserId(id);
+    this.deleteUserState(safeUserId);
+    const data = this.users.get(safeUserId);
+    if (data) {
+      this.usersByUsername.delete(data.username);
+      this.users.delete(safeUserId);
+      return true;
+    }
+    return false;
+  }
+  deleteApp(id) {
+    const safeId = validateAppId(id);
+    this.deleteAppUserStates(safeId);
+    return this.apps.delete(safeId);
+  }
+  async checkpoint(appId) {
+    throw new TetherServerError(
+      7 /* NotSupported */,
+      `Checkpoint operation is not supported by memory storage${appId ? ` (app: ${appId})` : ""}`
+    );
+  }
+  async vacuum(appId) {
+    throw new TetherServerError(
+      7 /* NotSupported */,
+      `Vacuum operation is not supported by memory storage${appId ? ` (app: ${appId})` : ""}`
+    );
+  }
+  async prune(appId, keepCount) {
+    const keep = keepCount ?? this.options.maxChangelogEntries ?? 1e3;
+    const allApps = await this.getApps();
+    const targetApps = filterTargetApps(allApps, appId);
+    let totalPruned = 0;
+    for (const app of targetApps) {
+      for (const [key, state] of this.userStates.entries()) {
+        if (key.startsWith(`${app.id}:`)) {
+          if (state.changelog.length > keep) {
+            const pruneCount = state.changelog.length - keep;
+            state.changelog.splice(0, pruneCount);
+            if (state.changelog.length > 0) {
+              state.minSeq = state.changelog[0].seq;
+            }
+            totalPruned += pruneCount;
+          }
+        }
+      }
+    }
+    return {
+      action: "prune",
+      backend: "memory",
+      appId,
+      affectedCount: totalPruned,
+      message: `Prune completed successfully. Removed ${totalPruned} changelog record(s)`
+    };
+  }
+  async close() {
+    this.apps.clear();
+    this.userStates.clear();
+    this.users.clear();
+    this.usersByUsername.clear();
+  }
+};
+
+// src/server/sync.ts
+var Sync = class {
+  storage;
+  maxConcurrentConnectionsPerUser;
+  authTimeoutMs;
+  rateLimiter;
+  logger;
+  userClients = /* @__PURE__ */ new Map();
+  // key = `${appId}:${userId}`
+  webSocketToClient = /* @__PURE__ */ new Map();
+  pendingAuthTimers = /* @__PURE__ */ new Map();
+  webSocketToIp = /* @__PURE__ */ new Map();
+  /**
+   * Initializes a new Sync coordinator instance.
+   *
+   * @param storage - Pluggable backend storage engine.
+   * @param options - Configuration options for concurrency limits, auth timeout, and rate limiting.
+   */
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.maxConcurrentConnectionsPerUser = options.maxConcurrentConnectionsPerUser ?? 20;
+    this.authTimeoutMs = options.authTimeoutMs ?? 1e4;
+    this.rateLimiter = options.rateLimiter ?? null;
+    this.logger = options.logger ?? null;
+  }
+  /**
+   * Total number of currently active authenticated WebSocket client connections.
+   */
+  get connectedClientsCount() {
+    return this.webSocketToClient.size;
+  }
+  /**
+   * Handles an incoming WebSocket connection, binding message, error, and disconnection events.
+   *
+   * @param webSocket - Active WebSocket connection.
+   * @param clientIp - Remote client IP address.
+   */
+  handleConnection(webSocket, clientIp = "127.0.0.1") {
+    this.webSocketToIp.set(webSocket, clientIp);
+    if (this.rateLimiter && !this.rateLimiter.consume(clientIp)) {
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Too many connection attempts"
+      });
+      webSocket.close();
+      return;
+    }
+    if (this.authTimeoutMs > 0) {
+      const timer = setTimeout(() => {
+        if (!this.webSocketToClient.has(webSocket)) {
+          this.send(webSocket, {
+            type: "auth_error" /* AuthError */,
+            message: "Authentication timeout"
+          });
+          webSocket.close();
+        }
+      }, this.authTimeoutMs);
+      this.pendingAuthTimers.set(webSocket, timer);
+    }
+    let messageQueue = Promise.resolve();
+    webSocket.on("message", (data) => {
+      const client = this.webSocketToClient.get(webSocket);
+      const userContext = client ? ` (app: "${client.appId}", user: "${client.user.id}", client: "${client.clientId}")` : "";
+      messageQueue = messageQueue.then(async () => {
+        try {
+          const raw = typeof data === "string" ? data : data.toString();
+          const msg = JSON.parse(raw);
+          await this.handleMessage(webSocket, msg);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : "Unknown server error";
+          this.logger?.error(
+            `[TetherServer.Sync] Error processing WebSocket message${userContext}:`,
+            err
+          );
+          this.send(webSocket, {
+            type: "error" /* Error */,
+            message
+          });
+        }
+      }).catch((err) => {
+        this.logger?.error(
+          `[TetherServer.Sync] Unhandled error in message queue${userContext}:`,
+          err
+        );
+      });
+    });
+    webSocket.on("error", (err) => {
+      const client = this.webSocketToClient.get(webSocket);
+      const userContext = client ? ` (app: "${client.appId}", user: "${client.user.id}", client: "${client.clientId}")` : "";
+      this.logger?.error(
+        `[TetherServer.Sync] WebSocket connection error${userContext}:`,
+        err
+      );
+      this.cleanupConnection(webSocket);
+    });
+    webSocket.on("close", () => {
+      this.cleanupConnection(webSocket);
+    });
+  }
+  /**
+   * Routes and executes incoming client protocol messages.
+   *
+   * @param webSocket - The connection that sent the message.
+   * @param msg - Parsed client protocol message.
+   */
+  async handleMessage(webSocket, msg) {
+    if (!msg || typeof msg !== "object" || typeof msg.type !== "string") {
+      throw new TetherServerError(
+        0 /* InvalidInput */,
+        "Invalid message format"
+      );
+    }
+    switch (msg.type) {
+      case "auth" /* Auth */:
+        await this.handleAuthMessage(webSocket, msg);
+        break;
+      case "change_batch" /* ChangeBatch */:
+        await this.handleChangeBatchMessage(webSocket, msg);
+        break;
+      case "ping" /* Ping */:
+        this.handlePingMessage(webSocket);
+        break;
+      default:
+        throw new TetherServerError(
+          0 /* InvalidInput */,
+          "Unsupported message type"
+        );
+    }
+  }
+  // -- Private Message Handlers ---------------------------------------------
+  async handleAuthMessage(webSocket, msg) {
+    const ip = this.webSocketToIp.get(webSocket) ?? "127.0.0.1";
+    const authTimer = this.pendingAuthTimers.get(webSocket);
+    if (authTimer) {
+      clearTimeout(authTimer);
+      this.pendingAuthTimers.delete(webSocket);
+    }
+    if (msg.protocolVersion !== PROTOCOL_VERSION) {
+      this.rateLimiter?.recordFailure(ip);
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: `Unsupported protocol version: expected ${PROTOCOL_VERSION}, got ${msg.protocolVersion}`
+      });
+      webSocket.close();
+      return;
+    }
+    if (typeof msg.token !== "string" || !msg.token) {
+      this.rateLimiter?.recordFailure(ip);
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Missing or invalid authentication token"
+      });
+      webSocket.close();
+      return;
+    }
+    const user = await this.storage.getUserByToken(msg.token);
+    if (!user) {
+      this.rateLimiter?.recordFailure(ip);
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Invalid or expired authentication token"
+      });
+      webSocket.close();
+      return;
+    }
+    if (typeof msg.appId !== "string" || !msg.appId) {
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Missing required field: appId"
+      });
+      webSocket.close();
+      return;
+    }
+    const appId = validateAppId(msg.appId);
+    const app = await this.storage.getApp(appId);
+    if (!app) {
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Application not found"
+      });
+      webSocket.close();
+      return;
+    }
+    const channelKey = `${appId}:${user.id}`;
+    let set = this.userClients.get(channelKey);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.userClients.set(channelKey, set);
+    }
+    if (set.size >= this.maxConcurrentConnectionsPerUser) {
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Maximum concurrent connections exceeded for this user"
+      });
+      webSocket.close();
+      return;
+    }
+    this.rateLimiter?.reset(ip);
+    const clientId = validateIdentifier(
+      msg.clientId ?? "client_anon",
+      "clientId"
+    );
+    const existingClient = this.webSocketToClient.get(webSocket);
+    if (existingClient) {
+      const oldChannelKey = `${existingClient.appId}:${existingClient.user.id}`;
+      const oldSet = this.userClients.get(oldChannelKey);
+      if (oldSet) {
+        oldSet.delete(existingClient);
+        if (oldSet.size === 0) {
+          this.userClients.delete(oldChannelKey);
+        }
+      }
+      this.webSocketToClient.delete(webSocket);
+    }
+    const client = {
+      webSocket,
+      clientId,
+      user,
+      appId
+    };
+    this.webSocketToClient.set(webSocket, client);
+    set.add(client);
+    const currentSeq = await app.getCurrentSeq(user);
+    const refreshedToken = await user.createToken();
+    this.send(webSocket, {
+      type: "auth_success" /* AuthSuccess */,
+      protocolVersion: PROTOCOL_VERSION,
+      userId: user.id,
+      currentSeq,
+      token: refreshedToken
+    });
+    await this.performSync(client, msg.lastSyncSeq);
+  }
+  async handleChangeBatchMessage(webSocket, msg) {
+    const client = this.webSocketToClient.get(webSocket);
+    if (!client) {
+      this.send(webSocket, {
+        type: "auth_error" /* AuthError */,
+        message: "Not authenticated"
+      });
+      return;
+    }
+    if (!Array.isArray(msg.changes)) {
+      throw new TetherServerError(
+        0 /* InvalidInput */,
+        "Invalid change batch: changes must be an array"
+      );
+    }
+    const maxBatchSize = this.storage.options?.maxBatchSizeBytes ?? 5 * 1024 * 1024;
+    const batchBytes = calculateByteSize(msg.changes);
+    if (batchBytes > maxBatchSize) {
+      throw new TetherServerError(
+        5 /* LimitExceeded */,
+        "Change batch exceeds maximum allowed size"
+      );
+    }
+    const batchId = validateIdentifier(msg.batchId, "batchId");
+    const app = await this.storage.getApp(client.appId);
+    if (!app) {
+      throw new TetherServerError(
+        1 /* NotFound */,
+        "Application not found"
+      );
+    }
+    const { applied, newSeq } = await app.applyChanges(
+      client.user,
+      msg.changes
+    );
+    this.send(webSocket, {
+      type: "change_ack" /* ChangeAck */,
+      batchId,
+      appliedSeq: newSeq
+    });
+    if (applied.length > 0) {
+      this.broadcastToAppUser(client.appId, client.user.id, client.clientId, {
+        type: "broadcast_changes" /* BroadcastChanges */,
+        fromClientId: client.clientId,
+        changes: applied,
+        seq: newSeq
+      });
+    }
+  }
+  handlePingMessage(webSocket) {
+    this.send(webSocket, {
+      type: "pong" /* Pong */
+    });
+  }
+  // -- Private Helpers ------------------------------------------------------
+  cleanupConnection(webSocket) {
+    const authTimer = this.pendingAuthTimers.get(webSocket);
+    if (authTimer) {
+      clearTimeout(authTimer);
+      this.pendingAuthTimers.delete(webSocket);
+    }
+    this.webSocketToIp.delete(webSocket);
+    const client = this.webSocketToClient.get(webSocket);
+    if (!client) return;
+    this.webSocketToClient.delete(webSocket);
+    const channelKey = `${client.appId}:${client.user.id}`;
+    const set = this.userClients.get(channelKey);
+    if (set) {
+      set.delete(client);
+      if (set.size === 0) {
+        this.userClients.delete(channelKey);
+      }
+    }
+  }
+  send(webSocket, msg) {
+    if (webSocket.readyState === 1) {
+      webSocket.send(JSON.stringify(msg));
+    }
+  }
+  async performSync(client, lastSyncSeq) {
+    const app = await this.storage.getApp(client.appId);
+    if (!app) {
+      throw new TetherServerError(
+        1 /* NotFound */,
+        "Application not found"
+      );
+    }
+    const seq = lastSyncSeq ?? 0;
+    if (seq === 0) {
+      const snapshot = await this.getAppSnapshot(app, client.user);
+      const currentSeq = await app.getCurrentSeq(client.user);
+      this.send(client.webSocket, {
+        type: "sync_snapshot" /* SyncSnapshot */,
+        seq: currentSeq,
+        snapshot
+      });
+    } else {
+      const { changes, currentSeq, requiresSnapshot } = await app.getChangesSince(client.user, seq);
+      if (requiresSnapshot) {
+        const snapshot = await this.getAppSnapshot(app, client.user);
+        this.send(client.webSocket, {
+          type: "sync_snapshot" /* SyncSnapshot */,
+          seq: currentSeq,
+          snapshot
+        });
+      } else {
+        this.send(client.webSocket, {
+          type: "sync_diff" /* SyncDiff */,
+          fromSeq: seq,
+          toSeq: currentSeq,
+          changes
+        });
+      }
+    }
+  }
+  async getAppSnapshot(app, user) {
+    const tables = await app.getTables();
+    const snapshot = [];
+    for (const table of tables) {
+      const records = await table.getAllRecords(user);
+      snapshot.push(...records);
+    }
+    return snapshot;
+  }
+  broadcastToAppUser(appId, userId, excludeClientId, msg) {
+    const channelKey = `${appId}:${userId}`;
+    const clients = this.userClients.get(channelKey);
+    if (!clients) return;
+    for (const client of clients) {
+      if (client.clientId !== excludeClientId) {
+        this.send(client.webSocket, msg);
+      }
+    }
+  }
+};
+
+// src/server/server.ts
+var TetherServer = class {
+  /** Underlying storage engine for users, apps, and tables. */
+  storage;
+  /** Real-time synchronization connection and broadcast coordinator. */
+  sync;
+  /** Base path for HTTP REST endpoints. */
+  basePath;
+  /** Path for WebSocket upgrade requests. */
+  webSocketPath;
+  trustProxy;
+  allowRegistration;
+  corsConfig;
+  logger;
+  ipLoginLimiter;
+  userLoginLimiter;
+  ipRegisterLimiter;
+  _httpServer = null;
+  _webSocketServer = null;
+  lockHandle = null;
+  /**
+   * Initializes a new TetherServer instance.
+   *
+   * @param options - Configuration options for storage, endpoints, and rate limiting.
+   */
+  constructor(options = {}) {
+    this.storage = options.storage ?? new MemoryStorage();
+    this.basePath = normalizeBasePath(options.basePath ?? "");
+    this.webSocketPath = options.webSocketPath ?? `${this.basePath}/sync`;
+    this.allowRegistration = options.allowRegistration ?? true;
+    this.trustProxy = options.trustProxy ?? false;
+    this.corsConfig = options.cors === false ? null : typeof options.cors === "object" ? options.cors : {};
+    this.logger = options.logger === false ? null : options.logger ?? console;
+    const rateLimitConfig = options.rateLimiting ?? true;
+    if (rateLimitConfig === false) {
+      this.ipLoginLimiter = null;
+      this.userLoginLimiter = null;
+      this.ipRegisterLimiter = null;
+      this.sync = new Sync(this.storage, {
+        maxConcurrentConnectionsPerUser: 1e3,
+        authTimeoutMs: 0,
+        rateLimiter: null,
+        logger: this.logger
+      });
+    } else {
+      const opts = typeof rateLimitConfig === "object" ? rateLimitConfig : {};
+      const windowMs = opts.windowMs ?? 6e4;
+      const maxFailures = opts.maxFailures ?? 5;
+      const initialBackoffMs = opts.initialBackoffMs ?? 1e3;
+      const maxBackoffMs = opts.maxBackoffMs ?? 9e5;
+      this.ipLoginLimiter = new RateLimiter({
+        windowMs,
+        maxRequests: opts.ipLoginMaxRequests ?? 100,
+        maxFailures,
+        initialBackoffMs,
+        maxBackoffMs
+      });
+      this.userLoginLimiter = new RateLimiter({
+        windowMs,
+        maxRequests: opts.userLoginMaxRequests ?? 20,
+        maxFailures,
+        initialBackoffMs,
+        maxBackoffMs
+      });
+      this.ipRegisterLimiter = new RateLimiter({
+        windowMs,
+        maxRequests: opts.ipRegisterMaxRequests ?? 100
+      });
+      const syncLimiter = new RateLimiter({
+        windowMs,
+        maxRequests: opts.ipSyncMaxRequests ?? 100,
+        maxFailures,
+        initialBackoffMs,
+        maxBackoffMs
+      });
+      this.sync = new Sync(this.storage, {
+        maxConcurrentConnectionsPerUser: opts.maxConcurrentConnectionsPerUser ?? 20,
+        authTimeoutMs: opts.authTimeoutMs ?? 1e4,
+        rateLimiter: syncLimiter,
+        logger: this.logger
+      });
+    }
+  }
+  /**
+   * Active Node.js HTTP server instance, or `null` if not listening.
+   */
+  get httpServer() {
+    return this._httpServer;
+  }
+  /**
+   * Active WebSocketServer instance, or `null` if not listening.
+   */
+  get webSocketServer() {
+    return this._webSocketServer;
+  }
+  /**
+   * Declares an application and its tables.
+   * Registers the application and any declared tables if not already present.
+   *
+   * @param appId - Application identifier.
+   * @param tables - Array of table names.
+   */
+  async declareApp(appId, tables = []) {
+    let app = await this.storage.getApp(appId);
+    if (!app) {
+      app = await this.storage.createApp(appId);
+    }
+    for (const table of tables) {
+      const existing = await app.getTable(table);
+      if (!existing) {
+        await app.createTable(table);
+      }
+    }
+  }
+  /**
+   * Declares a user account with the specified username and password.
+   * Creates the user if not already registered, or updates the existing user's password.
+   *
+   * @param username - Username for the account.
+   * @param password - Plaintext password for the account.
+   * @returns UserStorage handle for the declared user.
+   */
+  async declareUser(username, password) {
+    const user = await this.storage.getUserByUsername(username);
+    if (user) {
+      await user.changePassword(password);
+      return user;
+    }
+    return this.storage.createUser(username, password);
+  }
+  /**
+   * Attaches WebSocket synchronization handling to an existing HTTP server.
+   *
+   * @param server - The HTTP server instance to attach to.
+   */
+  attach(server) {
+    if (!this._webSocketServer) {
+      this._webSocketServer = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: {
+          zlibDeflateOptions: {
+            level: 6,
+            memLevel: 8
+          },
+          threshold: 1024,
+          clientNoContextTakeover: true,
+          serverNoContextTakeover: true
+        }
+      });
+      this._webSocketServer.on("connection", (ws, req) => {
+        const ip = req ? this.getClientIp(req) : "127.0.0.1";
+        this.sync.handleConnection(ws, ip);
+      });
+    }
+    server.on("upgrade", (req, socket, head) => {
+      const url = new URL(
+        req.url ?? "",
+        `http://${req.headers.host ?? "localhost"}`
+      );
+      if (url.pathname === this.webSocketPath) {
+        this._webSocketServer?.handleUpgrade(req, socket, head, (ws) => {
+          this._webSocketServer?.emit("connection", ws, req);
+        });
+      }
+    });
+  }
+  /**
+   * Starts the HTTP and WebSocket server listening on the specified port and host.
+   *
+   * @param port - Port number to bind. Defaults to 8080.
+   * @param host - Host interface to bind. Defaults to '0.0.0.0'.
+   * @returns The active Node.js HTTP server instance.
+   */
+  async listen(port = 8080, host = "0.0.0.0") {
+    const storageBaseDir = this.storage.baseDir;
+    const isMemory = this.storage.inMemory ?? this.storage instanceof MemoryStorage;
+    if (storageBaseDir && !isMemory) {
+      const status = await this.storage.getStatus();
+      this.lockHandle = acquireServerLock(storageBaseDir, {
+        port,
+        host,
+        backend: status.backend
+      });
+    }
+    return new Promise((resolve, reject) => {
+      this._httpServer = http.createServer(async (req, res) => {
+        const handled = await this.handleHttpRequest(req, res);
+        if (!handled) {
+          this.sendJson(res, 404, { error: "Not found" });
+        }
+      });
+      this.attach(this._httpServer);
+      this._httpServer.listen(port, host, () => {
+        if (this._httpServer) {
+          const addr = this._httpServer.address();
+          const actualPort = typeof addr === "object" && addr ? addr.port : port;
+          if (this.lockHandle && storageBaseDir && this.lockHandle.info.port !== actualPort) {
+            this.lockHandle.release();
+            this.lockHandle = acquireServerLock(storageBaseDir, {
+              port: actualPort,
+              host,
+              backend: this.lockHandle.info.backend
+            });
+          }
+          resolve(this._httpServer);
+        }
+      });
+      this._httpServer.on("error", (err) => {
+        if (this.lockHandle) {
+          this.lockHandle.release();
+          this.lockHandle = null;
+        }
+        reject(err);
+      });
+    });
+  }
+  /**
+   * Closes active HTTP server and WebSocket server listeners.
+   */
+  async close() {
+    if (this.lockHandle) {
+      this.lockHandle.release();
+      this.lockHandle = null;
+    }
+    return new Promise((resolve, reject) => {
+      if (this._webSocketServer) {
+        for (const client of this._webSocketServer.clients) {
+          try {
+            client.terminate();
+          } catch {
+          }
+        }
+        this._webSocketServer.close();
+        this._webSocketServer = null;
+      }
+      if (this._httpServer) {
+        try {
+          this._httpServer.closeAllConnections?.();
+        } catch {
+        }
+        this._httpServer.close((err) => {
+          this._httpServer = null;
+          if (err) reject(err);
+          else resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+  /**
+   * Creates a Connect- and Express-compatible HTTP middleware handler.
+   *
+   * @returns Middleware function `(req, res, next) => void`.
+   */
+  createMiddleware() {
+    return (req, res, next) => {
+      this.handleHttpRequest(req, res).then(
+        (handled) => {
+          if (!handled) next();
+        },
+        (err) => {
+          next(err);
+        }
+      );
+    };
+  }
+  /**
+   * Handles incoming HTTP requests for authentication and discovery endpoints.
+   *
+   * @param req - Incoming HTTP request.
+   * @param res - Server HTTP response.
+   * @returns `true` if the request was handled by TetherDB; `false` if the path did not match.
+   */
+  async handleHttpRequest(req, res) {
+    const url = new URL(
+      req.url ?? "/",
+      `http://${req.headers.host ?? "localhost"}`
+    );
+    const method = req.method?.toUpperCase();
+    if (method === "OPTIONS") {
+      this.handleOptions(req, res);
+      return true;
+    }
+    try {
+      if (method === "GET" && url.pathname === `${this.basePath}/health`) {
+        this.handleHealth(req, res);
+        return true;
+      }
+      if (method === "GET" && url.pathname === `${this.basePath}/ready`) {
+        await this.handleReady(req, res);
+        return true;
+      }
+      if (method === "GET" && url.pathname === `${this.basePath}/metrics`) {
+        await this.handleMetrics(req, res);
+        return true;
+      }
+      if (this.allowRegistration && method === "POST" && url.pathname === `${this.basePath}/auth/register`) {
+        await this.handleRegister(req, res);
+        return true;
+      }
+      if (method === "POST" && url.pathname === `${this.basePath}/auth/login`) {
+        await this.handleLogin(req, res);
+        return true;
+      }
+      return false;
+    } catch (err) {
+      const status = getHttpStatusForError(err);
+      if (status >= 500) {
+        this.logger?.error("Error handling HTTP request:", err);
+      } else {
+        this.logger?.debug("Client error handling HTTP request:", err);
+      }
+      const msg = err instanceof Error ? err.message : "Internal server error";
+      this.sendJson(res, status, { error: msg }, req);
+      return true;
+    }
+  }
+  // -- Private Helpers ------------------------------------------------------
+  getCorsHeaders(req) {
+    if (!this.corsConfig) return {};
+    const headers = {
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": (this.corsConfig.allowedHeaders ?? ["Content-Type", "Authorization"]).join(", ")
+    };
+    if (this.corsConfig.exposedHeaders && this.corsConfig.exposedHeaders.length > 0) {
+      headers["Access-Control-Expose-Headers"] = this.corsConfig.exposedHeaders.join(", ");
+    }
+    if (this.corsConfig.maxAge !== void 0) {
+      headers["Access-Control-Max-Age"] = String(this.corsConfig.maxAge);
+    }
+    const reqOrigin = req?.headers.origin;
+    const origin = this.corsConfig.origin ?? "*";
+    if (origin === "*") {
+      if (this.corsConfig.credentials) {
+        if (reqOrigin) {
+          headers["Access-Control-Allow-Origin"] = reqOrigin;
+          headers.Vary = "Origin";
+        }
+      } else {
+        headers["Access-Control-Allow-Origin"] = "*";
+      }
+    } else if (typeof origin === "string") {
+      headers["Access-Control-Allow-Origin"] = origin;
+      headers.Vary = "Origin";
+    } else if (Array.isArray(origin)) {
+      if (reqOrigin && origin.includes(reqOrigin)) {
+        headers["Access-Control-Allow-Origin"] = reqOrigin;
+        headers.Vary = "Origin";
+      }
+    } else if (origin === true && reqOrigin) {
+      headers["Access-Control-Allow-Origin"] = reqOrigin;
+      headers.Vary = "Origin";
+    }
+    if (this.corsConfig.credentials) {
+      headers["Access-Control-Allow-Credentials"] = "true";
+    }
+    return headers;
+  }
+  sendJson(res, status, data, req) {
+    res.writeHead(status, {
+      "Content-Type": "application/json",
+      ...this.getCorsHeaders(req)
+    });
+    res.end(JSON.stringify(data));
+  }
+  async readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk;
+        if (body.length > 1024 * 1024) {
+          reject(
+            new TetherServerError(
+              5 /* LimitExceeded */,
+              "Payload exceeds maximum allowed size"
+            )
+          );
+        }
+      });
+      req.on("end", () => {
+        try {
+          resolve(body ? JSON.parse(body) : {});
+        } catch {
+          reject(
+            new TetherServerError(
+              0 /* InvalidInput */,
+              "Invalid JSON payload"
+            )
+          );
+        }
+      });
+      req.on("error", reject);
+    });
+  }
+  handleOptions(req, res) {
+    res.writeHead(204, this.getCorsHeaders(req));
+    res.end();
+  }
+  handleHealth(req, res) {
+    this.sendJson(
+      res,
+      200,
+      {
+        status: "ok",
+        uptime: process.uptime()
+      },
+      req
+    );
+  }
+  async handleReady(req, res) {
+    try {
+      await this.storage.getApps();
+      this.sendJson(res, 200, { status: "ready" }, req);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Storage unavailable";
+      this.logger?.error("Storage readiness error:", err);
+      this.sendJson(res, 503, { status: "unready", error: message }, req);
+    }
+  }
+  async handleMetrics(req, res) {
+    const apps = await this.storage.getApps();
+    this.sendJson(
+      res,
+      200,
+      {
+        uptime: process.uptime(),
+        connectedClients: this.sync.connectedClientsCount,
+        appsCount: apps.length,
+        memoryUsage: process.memoryUsage()
+      },
+      req
+    );
+  }
+  async handleRegister(req, res) {
+    const ip = this.getClientIp(req);
+    if (this.ipRegisterLimiter && !this.ipRegisterLimiter.consume(ip)) {
+      this.sendJson(res, 429, { error: "Too many registration requests" }, req);
+      return;
+    }
+    const credentials = await this.readCredentials(req, res);
+    if (!credentials) return;
+    try {
+      const user = await this.storage.createUser(
+        credentials.username,
+        credentials.password
+      );
+      const token = await user.createToken();
+      this.sendJson(
+        res,
+        201,
+        {
+          userId: user.id,
+          username: user.username,
+          token
+        },
+        req
+      );
+    } catch (err) {
+      const status = getHttpStatusForError(err);
+      if (status >= 500) {
+        this.logger?.error("Registration error:", err);
+      } else {
+        this.logger?.debug("Client registration error:", err);
+      }
+      const msg = err instanceof Error ? err.message : "Registration error";
+      this.sendJson(res, status, { error: msg }, req);
+    }
+  }
+  async handleLogin(req, res) {
+    const ip = this.getClientIp(req);
+    if (this.ipLoginLimiter && !this.ipLoginLimiter.consume(ip)) {
+      this.sendJson(res, 429, { error: "Too many login attempts" }, req);
+      return;
+    }
+    const credentials = await this.readCredentials(req, res);
+    if (!credentials) return;
+    const userKey = `${ip}:${credentials.username}`;
+    if (this.userLoginLimiter && !this.userLoginLimiter.consume(userKey)) {
+      this.sendJson(
+        res,
+        429,
+        { error: "Too many login attempts for this account" },
+        req
+      );
+      return;
+    }
+    const user = await this.storage.getUserByUsername(credentials.username);
+    const valid = user ? await user.verifyPassword(credentials.password) : await verifyDummyPasswordHash(credentials.password);
+    if (!user || !valid) {
+      this.ipLoginLimiter?.recordFailure(ip);
+      this.userLoginLimiter?.recordFailure(userKey);
+      this.sendJson(
+        res,
+        401,
+        {
+          error: "Invalid username or password"
+        },
+        req
+      );
+      return;
+    }
+    this.ipLoginLimiter?.reset(ip);
+    this.userLoginLimiter?.reset(userKey);
+    const token = await user.createToken();
+    this.sendJson(
+      res,
+      200,
+      {
+        userId: user.id,
+        username: user.username,
+        token
+      },
+      req
+    );
+  }
+  async readCredentials(req, res) {
+    const body = await this.readJsonBody(req);
+    const { username, password } = body;
+    const normUsername = normalizeUsername(username ?? "");
+    const normPassword = normalizePassword(password ?? "");
+    if (!normUsername || !normPassword) {
+      this.sendJson(
+        res,
+        400,
+        {
+          error: "Missing or invalid required field: username and password"
+        },
+        req
+      );
+      return null;
+    }
+    return { username: normUsername, password: normPassword };
+  }
+  getClientIp(req) {
+    if (this.trustProxy) {
+      const forwarded = req.headers["x-forwarded-for"];
+      if (typeof forwarded === "string") {
+        const first = forwarded.split(",")[0].trim();
+        if (first) return first;
+      }
+    }
+    return req.socket.remoteAddress ?? "127.0.0.1";
+  }
+};
+function getHttpStatusForError(err) {
+  if (err instanceof TetherServerError) {
+    switch (err.code) {
+      case 0 /* InvalidInput */:
+      case 6 /* ConfigurationError */:
+        return 400;
+      case 3 /* Unauthorized */:
+      case 4 /* AuthenticationFailed */:
+        return 401;
+      case 1 /* NotFound */:
+        return 404;
+      case 2 /* AlreadyExists */:
+        return 409;
+      case 5 /* LimitExceeded */:
+        return 413;
+      case 7 /* NotSupported */:
+        return 501;
+      case 8 /* InternalError */:
+        return 500;
+    }
+  }
+  return 500;
+}
+
+// src/vite/index.ts
+function tetherPlugin(options = {}) {
+  let tetherServer = null;
+  async function setupServer(server) {
+    tetherServer = new TetherServer({
+      storage: options.storage ?? new MemoryStorage(),
+      logger: options.logger ?? false,
+      ...options
+    });
+    if (options.apps) {
+      for (const app of options.apps) {
+        await tetherServer.declareApp(app.appId, app.tables ?? []);
+      }
+    }
+    if (options.users) {
+      for (const user of options.users) {
+        await tetherServer.declareUser(user.username, user.password);
+      }
+    }
+    if (server.httpServer) {
+      tetherServer.attach(
+        server.httpServer
+      );
+      server.httpServer.on("close", () => {
+        tetherServer?.close().catch(() => {
+        });
+      });
+    }
+    server.middlewares.use(tetherServer.createMiddleware());
+  }
+  return {
+    name: "vite-plugin-tetherdb",
+    configureServer: setupServer,
+    configurePreviewServer: setupServer,
+    async closeBundle() {
+      if (tetherServer) {
+        await tetherServer.close();
+        tetherServer = null;
+      }
+    }
+  };
+}
+export {
+  tetherPlugin
+};
+//# sourceMappingURL=index.js.map