tetherdb 0.1.0

package/dist/cli/index.cjs

@@ -0,0 +1,3999 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli/index.ts
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/cli/cli.ts
+var path8 = __toESM(require("path"), 1);
+var import_node_url = require("url");
+
+// src/shared/types.ts
+var PROTOCOL_VERSION = 1;
+
+// 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/server.ts
+var http = __toESM(require("http"), 1);
+var import_ws = require("ws");
+
+// src/shared/path.ts
+function normalizeBasePath(path9) {
+  if (path9 === "" || path9 === "/") return "";
+  if (path9.endsWith("/")) path9 = path9.slice(0, path9.length - 1);
+  if (!path9.startsWith("/")) path9 = `/${path9}`;
+  return path9 === "/" ? "" : path9;
+}
+
+// src/server/crypto.ts
+var crypto = __toESM(require("crypto"), 1);
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+var DEFAULT_TOKEN_EXPIRES_IN = 7 * 24 * 60 * 60;
+function getOrCreateKeyfileSecret(baseDir) {
+  const secretPath = path.join(baseDir, ".secret");
+  try {
+    if (fs.existsSync(secretPath)) {
+      const existing = fs.readFileSync(secretPath, "utf-8").trim();
+      if (existing.length >= 32) {
+        return existing;
+      }
+    }
+  } catch {
+  }
+  const generated = crypto.randomBytes(32).toString("hex");
+  try {
+    fs.mkdirSync(baseDir, { recursive: true });
+    fs.writeFileSync(secretPath, generated, {
+      encoding: "utf-8",
+      mode: 384
+    });
+  } catch {
+  }
+  return generated;
+}
+async function hashPassword(password) {
+  const salt = crypto.randomBytes(16).toString("hex");
+  return new Promise((resolve6, reject) => {
+    crypto.scrypt(
+      password.normalize("NFKC"),
+      salt,
+      64,
+      SCRYPT_OPTIONS,
+      (err, derivedKey) => {
+        if (err) return reject(err);
+        resolve6(`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((resolve6) => {
+    crypto.scrypt(
+      password.normalize("NFKC"),
+      salt,
+      64,
+      SCRYPT_OPTIONS,
+      (err, derivedKey) => {
+        if (err) return resolve6(false);
+        const expectedBuf = Buffer.from(expectedHex, "hex");
+        if (derivedKey.length !== expectedBuf.length) return resolve6(false);
+        resolve6(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/lock.ts
+var fs2 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
+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/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 getUserBucket(userId) {
+  const safeId = validateUserId(userId);
+  const clean = safeId.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+  return clean.length >= 2 ? clean.slice(0, 2) : clean.padStart(2, "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
+var crypto2 = __toESM(require("crypto"), 1);
+
+// 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
+async function startServer(options = {}) {
+  const port = options.port ?? (process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 8080);
+  const host = options.host ?? "0.0.0.0";
+  const server = new TetherServer(options);
+  const httpServer = await server.listen(port, host);
+  const addr = httpServer.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : port;
+  return {
+    server,
+    httpServer,
+    port: boundPort,
+    host,
+    close: async () => {
+      await server.close();
+    }
+  };
+}
+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 import_ws.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);
+        });
+      } else {
+        socket.destroy();
+      }
+    });
+  }
+  /**
+   * 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((resolve6, 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
+            });
+          }
+          resolve6(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((resolve6, 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 resolve6();
+        });
+      } else {
+        resolve6();
+      }
+    });
+  }
+  /**
+   * 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((resolve6, 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 {
+          resolve6(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/server/storage/file/storage.ts
+var crypto3 = __toESM(require("crypto"), 1);
+var fs4 = __toESM(require("fs/promises"), 1);
+var path4 = __toESM(require("path"), 1);
+
+// src/server/storage/file/app.ts
+var fs3 = __toESM(require("fs/promises"), 1);
+var path3 = __toESM(require("path"), 1);
+
+// src/server/storage/file/table.ts
+var TableFileStorage = class extends TableBaseStorage {
+  async getRecord(user, id) {
+    const safeUserId = validateUserId(user.id);
+    const safeId = validateRecordId(id);
+    const map = await this.app.readTableRecords(safeUserId, this.name);
+    const record = map.get(safeId);
+    if (!record || record.deleted) {
+      return void 0;
+    }
+    return record;
+  }
+  async getAllRecords(user) {
+    const safeUserId = validateUserId(user.id);
+    const map = await this.app.readTableRecords(safeUserId, this.name);
+    return filterActiveRecords(this.name, map.values());
+  }
+  async delete() {
+    return this.app.deleteTable(this.name);
+  }
+};
+
+// src/server/storage/file/app.ts
+var AppFileStorage = class extends AppBaseStorage {
+  storage;
+  constructor(id, storage) {
+    super(id);
+    this.storage = storage;
+  }
+  get appDir() {
+    return path3.join(this.storage.baseDir, this.id);
+  }
+  get manifestFile() {
+    return path3.join(this.appDir, "manifest.json");
+  }
+  getUserDir(userId) {
+    const safeUserId = validateUserId(userId);
+    const bucket = getUserBucket(safeUserId);
+    return path3.join(this.appDir, "users", bucket, safeUserId);
+  }
+  getUserMetaFile(userId) {
+    return path3.join(this.getUserDir(userId), "meta.json");
+  }
+  getUserSyncFile(userId) {
+    return path3.join(this.getUserDir(userId), "sync.jsonl");
+  }
+  getUserTablesDir(userId) {
+    return path3.join(this.getUserDir(userId), "tables");
+  }
+  getUserTableFile(userId, tableName) {
+    return path3.join(this.getUserTablesDir(userId), `${tableName}.json`);
+  }
+  async readManifest() {
+    try {
+      const content = await fs3.readFile(this.manifestFile, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return {
+        id: this.id,
+        tables: [],
+        createdAt: Date.now(),
+        version: 1
+      };
+    }
+  }
+  async writeManifest(manifest) {
+    await writeFileAtomic(this.manifestFile, JSON.stringify(manifest, null, 2));
+  }
+  async readUserMeta(userId) {
+    try {
+      const content = await fs3.readFile(this.getUserMetaFile(userId), "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return { currentSeq: 0, minSeq: 0 };
+    }
+  }
+  async writeUserMeta(userId, meta) {
+    await writeFileAtomic(
+      this.getUserMetaFile(userId),
+      JSON.stringify(meta, null, 2)
+    );
+  }
+  async readUserSync(userId) {
+    try {
+      const content = await fs3.readFile(this.getUserSyncFile(userId), "utf-8");
+      const lines = content.split("\n");
+      const changes = [];
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed) {
+          changes.push(JSON.parse(trimmed));
+        }
+      }
+      return changes;
+    } catch {
+      return [];
+    }
+  }
+  async appendUserSync(userId, changes) {
+    if (changes.length === 0) return;
+    await fs3.mkdir(this.getUserDir(userId), { recursive: true });
+    const content = `${changes.map((c) => JSON.stringify(c)).join("\n")}
+`;
+    await fs3.appendFile(this.getUserSyncFile(userId), content, "utf-8");
+  }
+  async rewriteUserSync(userId, changes) {
+    const content = changes.length > 0 ? `${changes.map((c) => JSON.stringify(c)).join("\n")}
+` : "";
+    await writeFileAtomic(this.getUserSyncFile(userId), content);
+  }
+  async readTableRecords(userId, tableName) {
+    try {
+      const content = await fs3.readFile(
+        this.getUserTableFile(userId, tableName),
+        "utf-8"
+      );
+      const list = JSON.parse(content);
+      const map = /* @__PURE__ */ new Map();
+      for (const rec of list) {
+        map.set(rec.id, rec);
+      }
+      return map;
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  async writeTableRecords(userId, tableName, records) {
+    await writeFileAtomic(
+      this.getUserTableFile(userId, tableName),
+      JSON.stringify(Array.from(records.values()), null, 2)
+    );
+  }
+  async createTable(name) {
+    assertNoActiveServerLock(this.storage.baseDir);
+    const safeName = validateTableName(name);
+    const manifest = await this.readManifest();
+    if (manifest.tables.includes(safeName)) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Table already exists in this application"
+      );
+    }
+    manifest.tables.push(safeName);
+    manifest.tables.sort();
+    await this.writeManifest(manifest);
+    return new TableFileStorage(safeName, this);
+  }
+  async getTable(name) {
+    const safeName = validateTableName(name);
+    const manifest = await this.readManifest();
+    if (manifest.tables.includes(safeName)) {
+      return new TableFileStorage(safeName, this);
+    }
+    return void 0;
+  }
+  async getTables() {
+    const manifest = await this.readManifest();
+    return manifest.tables.map((name) => new TableFileStorage(name, this));
+  }
+  async applyChanges(user, changes) {
+    assertNoActiveServerLock(this.storage.baseDir);
+    return this.storage.withUserLock(user.id, this.id, async () => {
+      const manifest = await this.readManifest();
+      const registeredTables = new Set(manifest.tables);
+      const safeUserId = validateUserId(user.id);
+      const applied = [];
+      const maxRecords = this.storage.options.maxRecordsPerTable ?? 1e4;
+      const maxRecordSize = this.storage.options.maxRecordSizeBytes ?? 512 * 1024;
+      const maxChangelog = this.storage.options.maxChangelogEntries ?? 1e3;
+      const meta = await this.readUserMeta(safeUserId);
+      const syncChanges = await this.readUserSync(safeUserId);
+      const modifiedTables = /* @__PURE__ */ new Map();
+      for (const change of changes) {
+        const tableName = validateTableName(change.table);
+        const recordId = validateRecordId(change.id);
+        validateTimestamp(change.timestamp);
+        if (!registeredTables.has(tableName)) {
+          throw new TetherServerError(
+            1 /* NotFound */,
+            "Table not found"
+          );
+        }
+        let tableRecords = modifiedTables.get(tableName);
+        if (!tableRecords) {
+          tableRecords = await this.readTableRecords(safeUserId, tableName);
+          modifiedTables.set(tableName, tableRecords);
+        }
+        if (change.op === "put" /* Put */ && !tableRecords.has(recordId) && tableRecords.size >= maxRecords) {
+          throw new TetherServerError(
+            5 /* LimitExceeded */,
+            "Table record limit reached"
+          );
+        }
+        const payloadBytes = calculateByteSize(change.data);
+        if (payloadBytes > maxRecordSize) {
+          throw new TetherServerError(
+            5 /* LimitExceeded */,
+            "Record payload exceeds maximum allowed size"
+          );
+        }
+        const existing = tableRecords.get(recordId);
+        const shouldApply = !existing || shouldOverwrite(change, existing);
+        if (shouldApply) {
+          meta.currentSeq++;
+          const assignedSeq = meta.currentSeq;
+          if (meta.minSeq === 0) {
+            meta.minSeq = 1;
+          }
+          const { updatedRecord, appliedChange } = applyChangeToRecord(
+            change,
+            existing,
+            assignedSeq
+          );
+          tableRecords.set(recordId, updatedRecord);
+          applied.push(appliedChange);
+          syncChanges.push(appliedChange);
+        }
+      }
+      if (applied.length > 0) {
+        for (const [tableName, records] of modifiedTables.entries()) {
+          await this.writeTableRecords(safeUserId, tableName, records);
+        }
+        if (syncChanges.length > maxChangelog) {
+          const pruneCount = syncChanges.length - maxChangelog;
+          syncChanges.splice(0, pruneCount);
+          if (syncChanges.length > 0) {
+            meta.minSeq = syncChanges[0].seq;
+          }
+          await this.rewriteUserSync(safeUserId, syncChanges);
+        } else {
+          await this.appendUserSync(
+            safeUserId,
+            applied
+          );
+        }
+        await this.writeUserMeta(safeUserId, meta);
+      }
+      return { applied, newSeq: meta.currentSeq };
+    });
+  }
+  async getChangesSince(user, fromSeq) {
+    const safeUserId = validateUserId(user.id);
+    const meta = await this.readUserMeta(safeUserId);
+    const currentSeq = meta.currentSeq;
+    const minSeq = meta.minSeq;
+    if (fromSeq < minSeq && minSeq > 0 || fromSeq > currentSeq) {
+      return { changes: [], currentSeq, requiresSnapshot: true };
+    }
+    const syncChanges = await this.readUserSync(safeUserId);
+    const changes = syncChanges.filter((c) => c.seq > fromSeq);
+    return { changes, currentSeq, requiresSnapshot: false };
+  }
+  async getCurrentSeq(user) {
+    const safeUserId = validateUserId(user.id);
+    const meta = await this.readUserMeta(safeUserId);
+    return meta.currentSeq;
+  }
+  async delete() {
+    return this.storage.deleteApp(this.id);
+  }
+  async deleteTable(name) {
+    assertNoActiveServerLock(this.storage.baseDir);
+    const safeName = validateTableName(name);
+    const manifest = await this.readManifest();
+    const idx = manifest.tables.indexOf(safeName);
+    if (idx === -1) return false;
+    manifest.tables.splice(idx, 1);
+    await this.writeManifest(manifest);
+    const usersRoot = path3.join(this.appDir, "users");
+    try {
+      const buckets = await fs3.readdir(usersRoot, { withFileTypes: true });
+      for (const bucket of buckets) {
+        if (bucket.isDirectory()) {
+          const bucketDir = path3.join(usersRoot, bucket.name);
+          const users = await fs3.readdir(bucketDir, { withFileTypes: true });
+          for (const user of users) {
+            if (user.isDirectory()) {
+              const tableFile = path3.join(
+                bucketDir,
+                user.name,
+                "tables",
+                `${safeName}.json`
+              );
+              try {
+                await fs3.rm(tableFile, { force: true });
+              } catch {
+              }
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    return true;
+  }
+};
+
+// src/server/storage/file/user.ts
+var UserFileStorage = class extends UserBaseStorage {
+  storage;
+  constructor(data, storage) {
+    super(data.id, data.username, data.createdAt);
+    this.storage = storage;
+  }
+  getSecret() {
+    return this.storage.secret;
+  }
+  async verifyPassword(password) {
+    const user = await this.storage.findUserDataById(this.id);
+    return verifyUserPassword(password, user?.passwordHash);
+  }
+  async changePassword(newPassword) {
+    const newHash = await hashUserPassword(newPassword);
+    await this.storage.updateUserData(this.id, { passwordHash: newHash });
+  }
+  async delete() {
+    return this.storage.deleteUser(this.id);
+  }
+};
+
+// src/server/storage/file/storage.ts
+var FileStorage = class extends BaseStorage {
+  backend = "file";
+  baseDir;
+  options;
+  secret;
+  userLocks = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    super(options);
+    this.options = options;
+    this.baseDir = path4.resolve(options.baseDir ?? ".data");
+    this.secret = options.secret ?? getOrCreateKeyfileSecret(this.baseDir);
+  }
+  getBaseDir() {
+    return this.baseDir;
+  }
+  get usersFile() {
+    return path4.join(this.baseDir, "users.json");
+  }
+  get appsFile() {
+    return path4.join(this.baseDir, "apps.json");
+  }
+  async withLock(key, fn) {
+    const prevLock = this.userLocks.get(key) ?? Promise.resolve();
+    let releaseLock;
+    const currentLock = new Promise((resolve6) => {
+      releaseLock = resolve6;
+    });
+    this.userLocks.set(
+      key,
+      prevLock.then(() => currentLock)
+    );
+    try {
+      await prevLock;
+      return await fn();
+    } finally {
+      releaseLock();
+      if (this.userLocks.get(key) === currentLock) {
+        this.userLocks.delete(key);
+      }
+    }
+  }
+  async withUserLock(userId, appId, fn) {
+    return this.withLock(`${appId}:${userId}`, fn);
+  }
+  async readUsersFile() {
+    try {
+      const content = await fs4.readFile(this.usersFile, "utf-8");
+      const list = JSON.parse(content);
+      const map = /* @__PURE__ */ new Map();
+      for (const u of list) {
+        map.set(u.id, u);
+      }
+      return map;
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  async writeUsersFile(users) {
+    await writeFileAtomic(
+      this.usersFile,
+      JSON.stringify(Array.from(users.values()), null, 2)
+    );
+  }
+  async readAppsFile() {
+    try {
+      const content = await fs4.readFile(this.appsFile, "utf-8");
+      const list = JSON.parse(content);
+      const map = /* @__PURE__ */ new Map();
+      for (const a of list) {
+        map.set(a.id, a);
+      }
+      return map;
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  async writeAppsFile(apps) {
+    await writeFileAtomic(
+      this.appsFile,
+      JSON.stringify(Array.from(apps.values()), null, 2)
+    );
+  }
+  async findUserDataById(id) {
+    const users = await this.readUsersFile();
+    return users.get(id);
+  }
+  async updateUserData(id, update) {
+    assertNoActiveServerLock(this.baseDir);
+    return this.withLock("__users__", async () => {
+      const users = await this.readUsersFile();
+      const existing = users.get(id);
+      if (!existing) {
+        throw new TetherServerError(
+          1 /* NotFound */,
+          "User not found"
+        );
+      }
+      users.set(id, { ...existing, ...update });
+      await this.writeUsersFile(users);
+    });
+  }
+  async createApp(id) {
+    assertNoActiveServerLock(this.baseDir);
+    const safeId = validateAppId(id);
+    return this.withLock("__apps__", async () => {
+      const apps = await this.readAppsFile();
+      if (apps.has(safeId)) {
+        throw new TetherServerError(
+          2 /* AlreadyExists */,
+          "Application already exists"
+        );
+      }
+      const appDir = path4.join(this.baseDir, safeId);
+      await fs4.mkdir(appDir, { recursive: true });
+      const now = Date.now();
+      apps.set(safeId, { id: safeId, createdAt: now });
+      await this.writeAppsFile(apps);
+      const manifestFile = path4.join(appDir, "manifest.json");
+      await writeFileAtomic(
+        manifestFile,
+        JSON.stringify(
+          {
+            id: safeId,
+            tables: [],
+            createdAt: now,
+            version: 1
+          },
+          null,
+          2
+        )
+      );
+      return new AppFileStorage(safeId, this);
+    });
+  }
+  async getApp(id) {
+    const safeId = validateAppId(id);
+    const apps = await this.readAppsFile();
+    if (apps.has(safeId)) {
+      return new AppFileStorage(safeId, this);
+    }
+    const manifestFile = path4.join(this.baseDir, safeId, "manifest.json");
+    try {
+      await fs4.stat(manifestFile);
+      apps.set(safeId, { id: safeId, createdAt: Date.now() });
+      await this.writeAppsFile(apps);
+      return new AppFileStorage(safeId, this);
+    } catch {
+      return void 0;
+    }
+  }
+  async getApps() {
+    const apps = await this.readAppsFile();
+    return Array.from(apps.values()).sort((a, b) => a.id.localeCompare(b.id)).map((a) => new AppFileStorage(a.id, this));
+  }
+  async createUser(username, password) {
+    assertNoActiveServerLock(this.baseDir);
+    const safeUsername = validateUsername(username);
+    const validPassword = validatePassword(password);
+    const passwordHash = await hashPassword(validPassword);
+    return this.withLock("__users__", async () => {
+      const users = await this.readUsersFile();
+      for (const u of users.values()) {
+        if (u.username.toLowerCase() === safeUsername.toLowerCase()) {
+          throw new TetherServerError(
+            2 /* AlreadyExists */,
+            "Username is already registered"
+          );
+        }
+      }
+      const userId = crypto3.randomUUID();
+      const userData = {
+        id: userId,
+        username: safeUsername,
+        passwordHash,
+        createdAt: Date.now()
+      };
+      users.set(userId, userData);
+      await this.writeUsersFile(users);
+      return new UserFileStorage(userData, this);
+    });
+  }
+  async getUser(id) {
+    const safeUserId = validateUserId(id);
+    const data = await this.findUserDataById(safeUserId);
+    if (data) {
+      return new UserFileStorage(data, this);
+    }
+    return void 0;
+  }
+  async getUserByUsername(username) {
+    const safeUsername = normalizeUsername(username);
+    if (!safeUsername) return void 0;
+    const users = await this.readUsersFile();
+    for (const u of users.values()) {
+      if (u.username.toLowerCase() === safeUsername) {
+        return new UserFileStorage(u, this);
+      }
+    }
+    return void 0;
+  }
+  async getUsers() {
+    const users = await this.readUsersFile();
+    return Array.from(users.values()).map(
+      (data) => new UserFileStorage(data, this)
+    );
+  }
+  async deleteUser(id) {
+    assertNoActiveServerLock(this.baseDir);
+    const safeUserId = validateUserId(id);
+    return this.withLock("__users__", async () => {
+      let deleted = false;
+      const apps = await this.getApps();
+      const bucket = getUserBucket(safeUserId);
+      for (const app of apps) {
+        const userDir = path4.join(
+          this.baseDir,
+          app.id,
+          "users",
+          bucket,
+          safeUserId
+        );
+        try {
+          await fs4.rm(userDir, { recursive: true, force: true });
+          deleted = true;
+        } catch {
+        }
+      }
+      const users = await this.readUsersFile();
+      if (users.has(safeUserId)) {
+        users.delete(safeUserId);
+        await this.writeUsersFile(users);
+        deleted = true;
+      }
+      return deleted;
+    });
+  }
+  async deleteApp(id) {
+    assertNoActiveServerLock(this.baseDir);
+    const safeId = validateAppId(id);
+    return this.withLock("__apps__", async () => {
+      const apps = await this.readAppsFile();
+      let deleted = false;
+      if (apps.has(safeId)) {
+        apps.delete(safeId);
+        await this.writeAppsFile(apps);
+        deleted = true;
+      }
+      const appDir = path4.join(this.baseDir, safeId);
+      try {
+        await fs4.rm(appDir, { recursive: true, force: true });
+        deleted = true;
+      } catch {
+      }
+      return deleted;
+    });
+  }
+  async checkpoint(appId) {
+    throw new TetherServerError(
+      7 /* NotSupported */,
+      `Checkpoint operation is not supported by file storage${appId ? ` (app: ${appId})` : ""}`
+    );
+  }
+  async vacuum(appId) {
+    throw new TetherServerError(
+      7 /* NotSupported */,
+      `Vacuum operation is not supported by file 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);
+    const users = await this.getUsers();
+    let totalPruned = 0;
+    for (const app of targetApps) {
+      for (const user of users) {
+        await this.withUserLock(user.id, app.id, async () => {
+          const userDir = path4.join(
+            this.baseDir,
+            app.id,
+            "users",
+            getUserBucket(user.id),
+            user.id
+          );
+          const syncFile = path4.join(userDir, "sync.jsonl");
+          const metaFile = path4.join(userDir, "meta.json");
+          try {
+            const content = await fs4.readFile(syncFile, "utf-8");
+            const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+            if (lines.length > keep) {
+              const pruneCount = lines.length - keep;
+              const keptLines = lines.slice(pruneCount);
+              const firstKept = JSON.parse(keptLines[0]);
+              await writeFileAtomic(syncFile, `${keptLines.join("\n")}
+`);
+              try {
+                const metaContent = await fs4.readFile(metaFile, "utf-8");
+                const meta = JSON.parse(metaContent);
+                meta.minSeq = firstKept.seq;
+                await writeFileAtomic(metaFile, JSON.stringify(meta, null, 2));
+              } catch {
+              }
+              totalPruned += pruneCount;
+            }
+          } catch {
+          }
+        });
+      }
+    }
+    return {
+      action: "prune",
+      backend: "file",
+      appId,
+      affectedCount: totalPruned,
+      message: `Prune completed successfully. Removed ${totalPruned} changelog record(s)`
+    };
+  }
+  async close() {
+    this.userLocks.clear();
+  }
+};
+function assertNoActiveServerLock(baseDir) {
+  const lock = readServerLock(baseDir);
+  if (lock && lock.pid !== process.pid) {
+    throw new TetherServerError(
+      7 /* NotSupported */,
+      `Cannot modify file storage directly while server is running (PID ${lock.pid})`
+    );
+  }
+}
+async function writeFileAtomic(filePath, content) {
+  const dir = path4.dirname(filePath);
+  await fs4.mkdir(dir, { recursive: true });
+  const tmpPath = `${filePath}.${crypto3.randomBytes(6).toString("hex")}.tmp`;
+  await fs4.writeFile(tmpPath, content, "utf-8");
+  await fs4.rename(tmpPath, filePath);
+}
+
+// src/server/storage/sqlite/storage.ts
+var crypto4 = __toESM(require("crypto"), 1);
+var fs5 = __toESM(require("fs"), 1);
+var import_node_module = require("module");
+var path5 = __toESM(require("path"), 1);
+
+// src/server/storage/sqlite/table.ts
+var TableSqliteStorage = class extends TableBaseStorage {
+  async delete() {
+    return this.app.deleteTable(this.name);
+  }
+  parseData(raw) {
+    if (raw === null || raw === void 0) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  async getRecord(user, id) {
+    const safeUserId = validateUserId(user.id);
+    const safeId = validateRecordId(id);
+    const handle = this.app.getUserDb(safeUserId);
+    const row = handle.stmtGetRecord.get(this.name, safeId);
+    if (!row) return void 0;
+    return {
+      id: row.id,
+      version: row.version,
+      timestamp: row.timestamp,
+      clientId: row.client_id ?? "",
+      deleted: Boolean(row.deleted),
+      data: this.parseData(row.data)
+    };
+  }
+  async getAllRecords(user) {
+    const safeUserId = validateUserId(user.id);
+    const handle = this.app.getUserDb(safeUserId);
+    const rows = handle.stmtGetSnapshotByTable.all(
+      this.name
+    );
+    return rows.map((row) => ({
+      table: row.table_name,
+      id: row.id,
+      version: row.version,
+      timestamp: row.timestamp,
+      clientId: row.client_id ?? "",
+      data: this.parseData(row.data)
+    }));
+  }
+};
+
+// src/server/storage/sqlite/app.ts
+var AppSqliteStorage = class extends AppBaseStorage {
+  storage;
+  constructor(id, storage) {
+    super(id);
+    this.storage = storage;
+  }
+  getUserDb(userId) {
+    return this.storage.getUserAppDb(this.id, userId);
+  }
+  parseData(raw) {
+    if (raw === null || raw === void 0) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  serializeData(data) {
+    if (data === null || data === void 0) return null;
+    if (typeof data === "string") return data;
+    return JSON.stringify(data);
+  }
+  async createTable(name) {
+    const safeName = validateTableName(name);
+    const appsDb = this.storage.getAppsDb();
+    const existing = appsDb.stmtFindTable.get(this.id, safeName);
+    if (existing) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Table already exists in this application"
+      );
+    }
+    appsDb.stmtInsertTable.run(this.id, safeName, Date.now());
+    return new TableSqliteStorage(safeName, this);
+  }
+  async getTable(name) {
+    const safeName = validateTableName(name);
+    const appsDb = this.storage.getAppsDb();
+    const row = appsDb.stmtFindTable.get(this.id, safeName);
+    if (row) {
+      return new TableSqliteStorage(safeName, this);
+    }
+    return void 0;
+  }
+  async getTables() {
+    const appsDb = this.storage.getAppsDb();
+    const rows = appsDb.stmtListTables.all(this.id);
+    return rows.map((r) => new TableSqliteStorage(r.name, this));
+  }
+  async applyChanges(user, changes) {
+    const safeUserId = validateUserId(user.id);
+    const appsDb = this.storage.getAppsDb();
+    const handle = this.getUserDb(safeUserId);
+    const applied = [];
+    const maxRecords = this.storage.options.maxRecordsPerTable ?? 1e4;
+    const maxRecordSize = this.storage.options.maxRecordSizeBytes ?? 512 * 1024;
+    const maxChangelog = this.storage.options.maxChangelogEntries ?? 1e3;
+    handle.db.exec("BEGIN IMMEDIATE TRANSACTION");
+    try {
+      const metaRow = handle.stmtGetMeta.get();
+      let currentSeq = metaRow?.current_seq ?? 0;
+      let minSeq = metaRow?.min_seq ?? 0;
+      const checkedTables = /* @__PURE__ */ new Set();
+      for (const change of changes) {
+        const tableName = validateTableName(change.table);
+        const recordId = validateRecordId(change.id);
+        validateTimestamp(change.timestamp);
+        if (!checkedTables.has(tableName)) {
+          const tableExists = appsDb.stmtFindTable.get(this.id, tableName);
+          if (!tableExists) {
+            throw new TetherServerError(
+              1 /* NotFound */,
+              "Table not found"
+            );
+          }
+          checkedTables.add(tableName);
+        }
+        const existingRecord = handle.stmtGetRecordForUpdate.get(
+          tableName,
+          recordId
+        );
+        if (change.op === "put" /* Put */ && !existingRecord) {
+          const countRow = handle.stmtCountTableRecords.get(tableName);
+          const tableCount = countRow?.count ?? 0;
+          if (tableCount >= maxRecords) {
+            throw new TetherServerError(
+              5 /* LimitExceeded */,
+              "Table record limit reached"
+            );
+          }
+        }
+        const payloadBytes = calculateByteSize(change.data);
+        if (payloadBytes > maxRecordSize) {
+          throw new TetherServerError(
+            5 /* LimitExceeded */,
+            "Record payload exceeds maximum allowed size"
+          );
+        }
+        const shouldApply = !existingRecord || shouldOverwrite(
+          {
+            timestamp: change.timestamp,
+            clientId: change.clientId,
+            version: change.version
+          },
+          {
+            timestamp: existingRecord.timestamp,
+            clientId: existingRecord.client_id ?? "",
+            version: existingRecord.version
+          }
+        );
+        if (shouldApply) {
+          currentSeq++;
+          const assignedSeq = currentSeq;
+          if (minSeq === 0) {
+            minSeq = 1;
+          }
+          const isDeleted = change.op === "delete" /* Delete */;
+          const nextVersion = (existingRecord?.version ?? 0) + 1;
+          const serializedData = isDeleted ? null : this.serializeData(change.data);
+          if (existingRecord) {
+            handle.stmtUpdateRecord.run(
+              nextVersion,
+              change.timestamp,
+              change.clientId ?? "",
+              isDeleted ? 1 : 0,
+              serializedData,
+              tableName,
+              recordId
+            );
+          } else {
+            handle.stmtInsertRecord.run(
+              tableName,
+              recordId,
+              nextVersion,
+              change.timestamp,
+              change.clientId ?? "",
+              isDeleted ? 1 : 0,
+              serializedData
+            );
+          }
+          handle.stmtInsertChangelog.run(
+            assignedSeq,
+            tableName,
+            recordId,
+            change.op,
+            nextVersion,
+            change.timestamp,
+            change.clientId ?? "",
+            isDeleted ? 1 : 0,
+            serializedData
+          );
+          applied.push({
+            seq: assignedSeq,
+            table: tableName,
+            id: recordId,
+            op: change.op,
+            version: nextVersion,
+            timestamp: change.timestamp,
+            clientId: change.clientId,
+            data: isDeleted ? void 0 : change.data
+          });
+        }
+      }
+      if (currentSeq - minSeq + 1 > maxChangelog) {
+        const newMinSeq = currentSeq - maxChangelog + 1;
+        handle.stmtPruneChangelog.run(newMinSeq);
+        minSeq = newMinSeq;
+      }
+      if (applied.length > 0) {
+        handle.stmtSetMeta.run(currentSeq, minSeq);
+      }
+      handle.db.exec("COMMIT");
+      return { applied, newSeq: currentSeq };
+    } catch (err) {
+      handle.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  async getChangesSince(user, fromSeq) {
+    const safeUserId = validateUserId(user.id);
+    const handle = this.getUserDb(safeUserId);
+    const metaRow = handle.stmtGetMeta.get();
+    const currentSeq = metaRow?.current_seq ?? 0;
+    const minSeq = metaRow?.min_seq ?? 0;
+    if (fromSeq < minSeq && minSeq > 0 || fromSeq > currentSeq) {
+      return { changes: [], currentSeq, requiresSnapshot: true };
+    }
+    const rows = handle.stmtGetChangelogSince.all(
+      fromSeq
+    );
+    const changes = rows.map((row) => ({
+      seq: row.seq,
+      table: row.table_name,
+      id: row.id,
+      op: row.op === "delete" /* Delete */ ? "delete" /* Delete */ : "put" /* Put */,
+      version: row.version,
+      timestamp: row.timestamp,
+      clientId: row.client_id ?? "",
+      data: row.op === "delete" /* Delete */ ? void 0 : this.parseData(row.data)
+    }));
+    return { changes, currentSeq, requiresSnapshot: false };
+  }
+  async getCurrentSeq(user) {
+    const safeUserId = validateUserId(user.id);
+    const handle = this.getUserDb(safeUserId);
+    const metaRow = handle.stmtGetMeta.get();
+    return metaRow?.current_seq ?? 0;
+  }
+  async delete() {
+    return this.storage.deleteApp(this.id);
+  }
+  deleteTable(name) {
+    return this.storage.deleteTable(this.id, name);
+  }
+};
+
+// src/server/storage/sqlite/user.ts
+var UserSqliteStorage = class extends UserBaseStorage {
+  storage;
+  constructor(data, storage) {
+    super(data.id, data.username, data.createdAt);
+    this.storage = storage;
+  }
+  getSecret() {
+    return this.storage.secret;
+  }
+  async verifyPassword(password) {
+    const user = this.storage.findUserDataById(this.id);
+    return verifyUserPassword(password, user?.passwordHash);
+  }
+  async changePassword(newPassword) {
+    const newHash = await hashUserPassword(newPassword);
+    this.storage.updateUserData(this.id, newHash);
+  }
+  async delete() {
+    return this.storage.deleteUser(this.id);
+  }
+};
+
+// src/server/storage/sqlite/storage.ts
+var SqliteStorage = class extends BaseStorage {
+  backend = "sqlite";
+  baseDir;
+  inMemory;
+  maxOpenDatabases;
+  options;
+  secret;
+  usersHandle = null;
+  appsHandle = null;
+  userAppDbs = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    super(options);
+    this.options = options;
+    this.inMemory = Boolean(
+      options.inMemory || options.baseDir === ":memory:" || !options.baseDir && options.inMemory
+    );
+    this.maxOpenDatabases = options.maxOpenDatabases ?? 100;
+    this.baseDir = path5.resolve(options.baseDir ?? ".data");
+    this.secret = options.secret ?? (this.inMemory ? crypto4.randomBytes(32).toString("hex") : getOrCreateKeyfileSecret(this.baseDir));
+    if (!this.inMemory) {
+      try {
+        fs5.mkdirSync(this.baseDir, { recursive: true });
+      } catch {
+      }
+    }
+  }
+  getBaseDir() {
+    return this.inMemory ? ":memory:" : this.baseDir;
+  }
+  getUsersDb() {
+    if (this.usersHandle) return this.usersHandle;
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const { DatabaseSync } = require2("node:sqlite");
+    const dbPath = this.inMemory ? ":memory:" : path5.join(this.baseDir, "users.sqlite");
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 5000;");
+    db.exec("PRAGMA foreign_keys = ON;");
+    if (!this.inMemory) {
+      db.exec("PRAGMA journal_mode = WAL;");
+      db.exec("PRAGMA synchronous = NORMAL;");
+    }
+    initUsersSchema(db);
+    this.usersHandle = {
+      db,
+      stmtFindById: db.prepare(
+        "SELECT id, username, password_hash, created_at FROM users WHERE id = ?"
+      ),
+      stmtFindByUsername: db.prepare(
+        "SELECT id, username, password_hash, created_at FROM users WHERE username = ?"
+      ),
+      stmtInsertUser: db.prepare(
+        "INSERT INTO users (id, username, password_hash, created_at) VALUES (?, ?, ?, ?)"
+      ),
+      stmtUpdatePassword: db.prepare(
+        "UPDATE users SET password_hash = ? WHERE id = ?"
+      ),
+      stmtDeleteUser: db.prepare("DELETE FROM users WHERE id = ?"),
+      stmtListUsers: db.prepare(
+        "SELECT id, username, password_hash, created_at FROM users ORDER BY created_at ASC"
+      )
+    };
+    return this.usersHandle;
+  }
+  getAppsDb() {
+    if (this.appsHandle) return this.appsHandle;
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const { DatabaseSync } = require2("node:sqlite");
+    const dbPath = this.inMemory ? ":memory:" : path5.join(this.baseDir, "apps.sqlite");
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 5000;");
+    db.exec("PRAGMA foreign_keys = ON;");
+    if (!this.inMemory) {
+      db.exec("PRAGMA journal_mode = WAL;");
+      db.exec("PRAGMA synchronous = NORMAL;");
+    }
+    initAppsSchema(db);
+    this.appsHandle = {
+      db,
+      stmtFindApp: db.prepare("SELECT id, created_at FROM apps WHERE id = ?"),
+      stmtInsertApp: db.prepare(
+        "INSERT INTO apps (id, created_at) VALUES (?, ?)"
+      ),
+      stmtListApps: db.prepare("SELECT id FROM apps ORDER BY id ASC"),
+      stmtDeleteApp: db.prepare("DELETE FROM apps WHERE id = ?"),
+      stmtFindTable: db.prepare(
+        "SELECT name, created_at FROM tables WHERE app_id = ? AND name = ?"
+      ),
+      stmtInsertTable: db.prepare(
+        "INSERT INTO tables (app_id, name, created_at) VALUES (?, ?, ?)"
+      ),
+      stmtListTables: db.prepare(
+        "SELECT name FROM tables WHERE app_id = ? ORDER BY name ASC"
+      ),
+      stmtDeleteTable: db.prepare(
+        "DELETE FROM tables WHERE app_id = ? AND name = ?"
+      ),
+      stmtDeleteAppTables: db.prepare("DELETE FROM tables WHERE app_id = ?")
+    };
+    return this.appsHandle;
+  }
+  getUserAppDb(appId, userId) {
+    const safeAppId = validateAppId(appId);
+    const safeUserId = validateUserId(userId);
+    const cacheKey = `${safeAppId}:${safeUserId}`;
+    let handle = this.userAppDbs.get(cacheKey);
+    if (handle) {
+      this.userAppDbs.delete(cacheKey);
+      this.userAppDbs.set(cacheKey, handle);
+      return handle;
+    }
+    if (!this.inMemory && this.userAppDbs.size >= this.maxOpenDatabases) {
+      const oldestKey = this.userAppDbs.keys().next().value;
+      if (oldestKey) {
+        const oldestHandle = this.userAppDbs.get(oldestKey);
+        try {
+          oldestHandle?.db.close();
+        } catch {
+        }
+        this.userAppDbs.delete(oldestKey);
+      }
+    }
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const { DatabaseSync } = require2("node:sqlite");
+    let dbPath;
+    if (this.inMemory) {
+      dbPath = ":memory:";
+    } else {
+      const bucket = getUserBucket(safeUserId);
+      const userDir = path5.join(this.baseDir, safeAppId, bucket);
+      try {
+        fs5.mkdirSync(userDir, { recursive: true });
+      } catch {
+      }
+      dbPath = path5.join(userDir, `${safeUserId}.sqlite`);
+    }
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 5000;");
+    db.exec("PRAGMA foreign_keys = ON;");
+    if (!this.inMemory) {
+      db.exec("PRAGMA journal_mode = WAL;");
+      db.exec("PRAGMA synchronous = NORMAL;");
+    }
+    initUserAppSchema(db);
+    handle = {
+      db,
+      stmtGetRecord: db.prepare(
+        "SELECT table_name, id, version, timestamp, client_id, deleted, data FROM records WHERE table_name = ? AND id = ? AND deleted = 0"
+      ),
+      stmtGetRecordForUpdate: db.prepare(
+        "SELECT table_name, id, version, timestamp, client_id, deleted, data FROM records WHERE table_name = ? AND id = ?"
+      ),
+      stmtGetSnapshot: db.prepare(
+        "SELECT table_name, id, version, timestamp, client_id, deleted, data FROM records WHERE deleted = 0"
+      ),
+      stmtGetSnapshotByTable: db.prepare(
+        "SELECT table_name, id, version, timestamp, client_id, deleted, data FROM records WHERE table_name = ? AND deleted = 0"
+      ),
+      stmtInsertRecord: db.prepare(
+        "INSERT INTO records (table_name, id, version, timestamp, client_id, deleted, data) VALUES (?, ?, ?, ?, ?, ?, ?)"
+      ),
+      stmtUpdateRecord: db.prepare(
+        "UPDATE records SET version = ?, timestamp = ?, client_id = ?, deleted = ?, data = ? WHERE table_name = ? AND id = ?"
+      ),
+      stmtGetMeta: db.prepare(
+        "SELECT current_seq, min_seq FROM user_meta LIMIT 1"
+      ),
+      stmtSetMeta: db.prepare(
+        "INSERT OR REPLACE INTO user_meta (rowid, current_seq, min_seq) VALUES (1, ?, ?)"
+      ),
+      stmtInsertChangelog: db.prepare(
+        "INSERT INTO changelog (seq, table_name, id, op, version, timestamp, client_id, deleted, data) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      ),
+      stmtGetChangelogSince: db.prepare(
+        "SELECT seq, table_name, id, op, version, timestamp, client_id, deleted, data FROM changelog WHERE seq > ? ORDER BY seq ASC"
+      ),
+      stmtPruneChangelog: db.prepare("DELETE FROM changelog WHERE seq < ?"),
+      stmtCountTableRecords: db.prepare(
+        "SELECT COUNT(*) as count FROM records WHERE table_name = ? AND deleted = 0"
+      ),
+      stmtDeleteTableRecords: db.prepare(
+        "DELETE FROM records WHERE table_name = ?"
+      ),
+      stmtDeleteTableChangelog: db.prepare(
+        "DELETE FROM changelog WHERE table_name = ?"
+      )
+    };
+    this.userAppDbs.set(cacheKey, handle);
+    return handle;
+  }
+  findUserDataById(id) {
+    const usersDb = this.getUsersDb();
+    const row = usersDb.stmtFindById.get(id);
+    if (!row) return void 0;
+    return {
+      id: row.id,
+      username: row.username,
+      passwordHash: row.password_hash,
+      createdAt: row.created_at
+    };
+  }
+  updateUserData(id, passwordHash) {
+    const usersDb = this.getUsersDb();
+    usersDb.stmtUpdatePassword.run(passwordHash, id);
+  }
+  async createApp(id) {
+    const safeId = validateAppId(id);
+    const appsDb = this.getAppsDb();
+    const existing = appsDb.stmtFindApp.get(safeId);
+    if (existing) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Application already exists"
+      );
+    }
+    appsDb.stmtInsertApp.run(safeId, Date.now());
+    if (!this.inMemory) {
+      const appDir = path5.join(this.baseDir, safeId);
+      try {
+        fs5.mkdirSync(appDir, { recursive: true });
+      } catch {
+      }
+    }
+    return new AppSqliteStorage(safeId, this);
+  }
+  async getApp(id) {
+    const safeId = validateAppId(id);
+    const appsDb = this.getAppsDb();
+    const existing = appsDb.stmtFindApp.get(safeId);
+    if (existing) {
+      return new AppSqliteStorage(safeId, this);
+    }
+    return void 0;
+  }
+  async getApps() {
+    const appsDb = this.getAppsDb();
+    const rows = appsDb.stmtListApps.all();
+    return rows.map((r) => new AppSqliteStorage(r.id, this));
+  }
+  async createUser(username, password) {
+    const safeUsername = validateUsername(username);
+    const validPassword = validatePassword(password);
+    const usersDb = this.getUsersDb();
+    const existing = usersDb.stmtFindByUsername.get(safeUsername);
+    if (existing) {
+      throw new TetherServerError(
+        2 /* AlreadyExists */,
+        "Username is already registered"
+      );
+    }
+    const userId = crypto4.randomUUID();
+    const passwordHash = await hashPassword(validPassword);
+    const createdAt = Date.now();
+    usersDb.stmtInsertUser.run(userId, safeUsername, passwordHash, createdAt);
+    const userData = {
+      id: userId,
+      username: safeUsername,
+      passwordHash,
+      createdAt
+    };
+    return new UserSqliteStorage(userData, this);
+  }
+  async getUser(id) {
+    const safeUserId = validateUserId(id);
+    const data = this.findUserDataById(safeUserId);
+    if (data) {
+      return new UserSqliteStorage(data, this);
+    }
+    return void 0;
+  }
+  async getUserByUsername(username) {
+    const safeUsername = normalizeUsername(username);
+    if (!safeUsername) return void 0;
+    const usersDb = this.getUsersDb();
+    const row = usersDb.stmtFindByUsername.get(safeUsername);
+    if (!row) return void 0;
+    const data = {
+      id: row.id,
+      username: row.username,
+      passwordHash: row.password_hash,
+      createdAt: row.created_at
+    };
+    return new UserSqliteStorage(data, this);
+  }
+  async getUsers() {
+    const usersDb = this.getUsersDb();
+    const rows = usersDb.stmtListUsers.all();
+    return rows.map(
+      (r) => new UserSqliteStorage(
+        {
+          id: r.id,
+          username: r.username,
+          passwordHash: r.password_hash,
+          createdAt: r.created_at
+        },
+        this
+      )
+    );
+  }
+  deleteUser(id) {
+    const safeUserId = validateUserId(id);
+    let deleted = false;
+    for (const [key, handle] of Array.from(this.userAppDbs.entries())) {
+      if (key.endsWith(`:${safeUserId}`)) {
+        try {
+          handle.db.close();
+        } catch {
+        }
+        this.userAppDbs.delete(key);
+      }
+    }
+    if (!this.inMemory) {
+      const bucket = getUserBucket(safeUserId);
+      const apps = this.getAppsDb().stmtListApps.all();
+      for (const app of apps) {
+        const userDbFile = path5.join(
+          this.baseDir,
+          app.id,
+          bucket,
+          `${safeUserId}.sqlite`
+        );
+        const walFile = `${userDbFile}-wal`;
+        const shmFile = `${userDbFile}-shm`;
+        try {
+          fs5.unlinkSync(userDbFile);
+          deleted = true;
+        } catch {
+        }
+        try {
+          fs5.unlinkSync(walFile);
+        } catch {
+        }
+        try {
+          fs5.unlinkSync(shmFile);
+        } catch {
+        }
+      }
+    }
+    const usersDb = this.getUsersDb();
+    const res = usersDb.stmtDeleteUser.run(safeUserId);
+    if (res.changes > 0) deleted = true;
+    return deleted;
+  }
+  deleteApp(id) {
+    const safeId = validateAppId(id);
+    let deleted = false;
+    for (const [key, handle] of Array.from(this.userAppDbs.entries())) {
+      if (key.startsWith(`${safeId}:`)) {
+        try {
+          handle.db.close();
+        } catch {
+        }
+        this.userAppDbs.delete(key);
+      }
+    }
+    const appsDb = this.getAppsDb();
+    appsDb.stmtDeleteAppTables.run(safeId);
+    const res = appsDb.stmtDeleteApp.run(safeId);
+    if (res.changes > 0) deleted = true;
+    if (!this.inMemory) {
+      const appDir = path5.join(this.baseDir, safeId);
+      try {
+        fs5.rmSync(appDir, { recursive: true, force: true });
+        deleted = true;
+      } catch {
+      }
+    }
+    return deleted;
+  }
+  deleteTable(appId, tableName) {
+    const safeAppId = validateAppId(appId);
+    const appsDb = this.getAppsDb();
+    const res = appsDb.stmtDeleteTable.run(safeAppId, tableName);
+    if (res.changes === 0) return false;
+    for (const [key, handle] of this.userAppDbs.entries()) {
+      if (key.startsWith(`${safeAppId}:`)) {
+        try {
+          handle.stmtDeleteTableRecords.run(tableName);
+          handle.stmtDeleteTableChangelog.run(tableName);
+        } catch {
+        }
+      }
+    }
+    return true;
+  }
+  async checkpoint(appId) {
+    const allApps = await this.getApps();
+    const targetApps = filterTargetApps(allApps, appId);
+    const users = await this.getUsers();
+    const count = this.executeOnAllDbs(
+      "PRAGMA wal_checkpoint(TRUNCATE);",
+      targetApps,
+      users
+    );
+    return {
+      action: "checkpoint",
+      backend: "sqlite",
+      appId,
+      affectedCount: count,
+      message: `Checkpoint completed successfully across ${count} database(s)`
+    };
+  }
+  async vacuum(appId) {
+    const allApps = await this.getApps();
+    const targetApps = filterTargetApps(allApps, appId);
+    const users = await this.getUsers();
+    const count = this.executeOnAllDbs("VACUUM;", targetApps, users);
+    return {
+      action: "vacuum",
+      backend: "sqlite",
+      appId,
+      affectedCount: count,
+      message: `Vacuum completed successfully across ${count} database(s)`
+    };
+  }
+  executeOnAllDbs(sql, targetApps, users) {
+    let count = 0;
+    this.getUsersDb().db.exec(sql);
+    count++;
+    this.getAppsDb().db.exec(sql);
+    count++;
+    for (const app of targetApps) {
+      for (const user of users) {
+        if (!this.inMemory) {
+          const bucket = getUserBucket(user.id);
+          const dbPath = path5.join(
+            this.baseDir,
+            app.id,
+            bucket,
+            `${user.id}.sqlite`
+          );
+          if (!fs5.existsSync(dbPath)) continue;
+        }
+        const handle = this.getUserAppDb(app.id, user.id);
+        handle.db.exec(sql);
+        count++;
+      }
+    }
+    return count;
+  }
+  async prune(appId, keepCount) {
+    const keep = keepCount ?? this.options.maxChangelogEntries ?? 1e3;
+    const allApps = await this.getApps();
+    const targetApps = filterTargetApps(allApps, appId);
+    const users = await this.getUsers();
+    let totalPruned = 0;
+    for (const app of targetApps) {
+      for (const user of users) {
+        if (!this.inMemory) {
+          const bucket = getUserBucket(user.id);
+          const dbPath = path5.join(
+            this.baseDir,
+            app.id,
+            bucket,
+            `${user.id}.sqlite`
+          );
+          if (!fs5.existsSync(dbPath)) continue;
+        }
+        const handle = this.getUserAppDb(app.id, user.id);
+        const metaRow = handle.stmtGetMeta.get();
+        if (!metaRow || metaRow.current_seq === 0) continue;
+        const currentSeq = metaRow.current_seq;
+        const newMinSeq = Math.max(1, currentSeq - keep + 1);
+        if (newMinSeq > metaRow.min_seq) {
+          const res = handle.stmtPruneChangelog.run(newMinSeq);
+          totalPruned += res.changes;
+          handle.stmtSetMeta.run(currentSeq, newMinSeq);
+        }
+      }
+    }
+    return {
+      action: "prune",
+      backend: "sqlite",
+      appId,
+      affectedCount: totalPruned,
+      message: `Prune completed successfully. Removed ${totalPruned} changelog record(s)`
+    };
+  }
+  async close() {
+    if (this.usersHandle) {
+      try {
+        this.usersHandle.db.close();
+      } catch {
+      }
+      this.usersHandle = null;
+    }
+    if (this.appsHandle) {
+      try {
+        this.appsHandle.db.close();
+      } catch {
+      }
+      this.appsHandle = null;
+    }
+    for (const handle of this.userAppDbs.values()) {
+      try {
+        handle.db.close();
+      } catch {
+      }
+    }
+    this.userAppDbs.clear();
+  }
+};
+var USERS_DB_SCHEMA_VERSION = 1;
+var APPS_DB_SCHEMA_VERSION = 1;
+var USER_APP_DB_SCHEMA_VERSION = 1;
+function getSchemaVersion(db) {
+  const row = db.prepare("PRAGMA user_version;").get();
+  return row?.user_version ?? 0;
+}
+function setSchemaVersion(db, version) {
+  db.exec(`PRAGMA user_version = ${version};`);
+}
+function initUsersSchema(db) {
+  const currentVersion = getSchemaVersion(db);
+  if (currentVersion < 1) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS users (
+        id TEXT PRIMARY KEY,
+        username TEXT UNIQUE NOT NULL,
+        password_hash TEXT,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_users_username ON users (username);
+    `);
+    setSchemaVersion(db, USERS_DB_SCHEMA_VERSION);
+  }
+}
+function initAppsSchema(db) {
+  const currentVersion = getSchemaVersion(db);
+  if (currentVersion < 1) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS apps (
+        id TEXT PRIMARY KEY,
+        created_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS tables (
+        app_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (app_id, name)
+      );
+      CREATE INDEX IF NOT EXISTS idx_tables_app ON tables (app_id);
+    `);
+    setSchemaVersion(db, APPS_DB_SCHEMA_VERSION);
+  }
+}
+function initUserAppSchema(db) {
+  const currentVersion = getSchemaVersion(db);
+  if (currentVersion < 1) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS records (
+        table_name TEXT NOT NULL,
+        id TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        timestamp INTEGER NOT NULL,
+        client_id TEXT NOT NULL,
+        deleted INTEGER NOT NULL,
+        data TEXT,
+        PRIMARY KEY (table_name, id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_records_lookup
+        ON records (table_name, deleted);
+
+      CREATE TABLE IF NOT EXISTS changelog (
+        seq INTEGER PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        id TEXT NOT NULL,
+        op TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        timestamp INTEGER NOT NULL,
+        client_id TEXT NOT NULL,
+        deleted INTEGER NOT NULL,
+        data TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_changelog_sync
+        ON changelog (seq);
+
+      CREATE TABLE IF NOT EXISTS user_meta (
+        current_seq INTEGER NOT NULL,
+        min_seq INTEGER NOT NULL
+      );
+    `);
+    setSchemaVersion(db, USER_APP_DB_SCHEMA_VERSION);
+  }
+}
+
+// src/cli/args.ts
+function parseCliArgs(args) {
+  const positionalArgs = [];
+  let port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 8080;
+  let host = process.env.HOST ?? "0.0.0.0";
+  let backend = "memory";
+  let dir = ".data";
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--port=")) port = Number.parseInt(arg.slice(7), 10);
+    else if (arg === "-p") port = Number.parseInt(args[++i] ?? "", 10);
+    else if (arg.startsWith("--host=")) host = arg.slice(7);
+    else if (arg === "-H") host = args[++i] ?? host;
+    else if (arg === "--memory") backend = "memory";
+    else if (arg === "--file" || arg.startsWith("--file=")) {
+      backend = "file";
+      if (arg.startsWith("--file=")) dir = arg.slice(7);
+    } else if (arg === "--sqlite" || arg.startsWith("--sqlite=")) {
+      backend = "sqlite";
+      if (arg.startsWith("--sqlite=")) dir = arg.slice(9);
+    } else if (arg.startsWith("-")) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        `Unknown or invalid option: "${arg}"`
+      );
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+  return {
+    command: positionalArgs[0] ?? "serve",
+    positionalArgs,
+    port,
+    host,
+    backend,
+    dir
+  };
+}
+
+// src/cli/backend.ts
+var path6 = __toESM(require("path"), 1);
+function createBackend(backend = "memory", baseDir = ".data", options) {
+  const resolvedDir = path6.resolve(baseDir);
+  switch (backend) {
+    case "memory":
+      return new MemoryStorage(options);
+    case "sqlite":
+      return new SqliteStorage({ baseDir: resolvedDir, ...options });
+    case "file":
+      return new FileStorage({ baseDir: resolvedDir, ...options });
+    default:
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        `Unknown backend type: "${backend}". Expected 'memory', 'file', or 'sqlite'`
+      );
+  }
+}
+
+// src/cli/commands/apps.ts
+async function handleAppsCommand(storage, [, action = "list", appId]) {
+  if (action === "list") {
+    const apps = await storage.getApps();
+    if (!apps.length) return console.log("No applications found.");
+    console.log(`Applications (${apps.length}):`);
+    for (const app of apps) {
+      const tables = await app.getTables();
+      const tableList = tables.length > 0 ? tables.map((t) => t.name).join(", ") : "no tables";
+      console.log(`  \u2022 ${app.id} (tables: ${tableList})`);
+    }
+  } else if (action === "add") {
+    if (!appId) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing application ID"
+      );
+    }
+    if (await storage.getApp(appId)) {
+      return console.log(`Application already exists: ${appId}`);
+    }
+    await storage.createApp(appId);
+    console.log(`Created application: ${appId}`);
+  } else if (action === "rm") {
+    if (!appId) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing application ID"
+      );
+    }
+    const app = await storage.getApp(appId);
+    if (!app) return console.log(`Application not found: ${appId}`);
+    await app.delete();
+    console.log(`Deleted application: ${appId}`);
+  } else {
+    throw new TetherServerError(
+      6 /* ConfigurationError */,
+      `Unknown apps action: "${action}"`
+    );
+  }
+}
+
+// src/cli/commands/help.ts
+function printHelp() {
+  console.log(`
+TetherDB CLI
+
+Usage:
+  npx tetherdb [command] [options]
+  tetherdb [command] [options]
+
+Commands:
+  serve (default)                         Start HTTP and WebSocket synchronization server
+  status [appid]                          Display storage and database statistics
+  maintenance checkpoint [appid]          Truncate WAL files for SQLite databases
+  maintenance vacuum [appid]              Reclaim disk space and defragment database files
+  maintenance prune [appid] [keepCount]   Prune changelogs older than retention threshold
+  apps [list]                             List all applications
+  apps add <appid>                        Register a new application
+  apps rm <appid>                         Delete an application and its data
+  tables [list] <appid>                   List tables for an application
+  tables add <appid> <table1> [table2...] Add one or more tables to an application
+  tables rm <appid> <table1> [table2...]  Remove table(s) from an application
+  users [list]                            List all registered user accounts
+  users add <username> <password>         Register a new user account
+  users rm <userid>                       Delete a user account and associated data
+
+Server Options (for 'serve'):
+  --port=<number>, -p <number>            Port number to bind (default: 8080 or PORT env)
+  --host=<string>, -H <string>            Host address to bind (default: 0.0.0.0 or HOST env)
+
+Backend Options (for all commands):
+  --memory                                Run in-memory without disk persistence (default)
+  --file[=<dir>]                          Use filesystem directory for auth and data (default: .data)
+  --sqlite[=<dir>]                        Use SQLite databases for auth and data (default: .data)
+  --help, -h                              Show this help message
+`);
+}
+
+// src/cli/commands/maintenance.ts
+async function handleMaintenanceCommand(storage, positionalArgs) {
+  const action = positionalArgs[1];
+  const appId = positionalArgs[2];
+  if (!action) {
+    throw new TetherServerError(
+      0 /* InvalidInput */,
+      'Missing maintenance action. Expected "checkpoint", "vacuum", or "prune"'
+    );
+  }
+  switch (action) {
+    case "checkpoint": {
+      const result = await storage.checkpoint(appId);
+      console.log(result.message);
+      break;
+    }
+    case "vacuum": {
+      const result = await storage.vacuum(appId);
+      console.log(result.message);
+      break;
+    }
+    case "prune": {
+      const keepStr = positionalArgs[3];
+      const keepCount = keepStr ? Number.parseInt(keepStr, 10) : void 0;
+      const result = await storage.prune(appId, keepCount);
+      console.log(result.message);
+      break;
+    }
+    default:
+      throw new TetherServerError(
+        0 /* InvalidInput */,
+        `Unknown maintenance action: "${action}". Expected "checkpoint", "vacuum", or "prune"`
+      );
+  }
+}
+
+// src/cli/commands/serve.ts
+var path7 = __toESM(require("path"), 1);
+async function handleServeCommand(storage, backend, dir, port, host) {
+  const running = await startServer({ port, host, storage });
+  const hostLabel = running.host === "0.0.0.0" ? "localhost" : running.host;
+  const storageInfo = backend === "memory" ? "in-memory (ephemeral)" : `${backend} (${path7.resolve(dir)})`;
+  console.log(
+    `TetherDB server listening at: http://${hostLabel}:${running.port}${running.server.basePath}`
+  );
+  console.log(
+    `WebSocket sync endpoint: ws://${hostLabel}:${running.port}${running.server.webSocketPath}`
+  );
+  console.log(`Storage backend: ${storageInfo}`);
+  const shutdown = async () => {
+    console.log("Stopping TetherDB server...");
+    try {
+      await running.close();
+      await storage.close?.();
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  return running;
+}
+
+// src/cli/commands/status.ts
+async function handleStatusCommand(storage, positionalArgs) {
+  const appId = positionalArgs[1];
+  const status = await storage.getStatus(appId);
+  console.log("TetherDB Storage Status:");
+  console.log(`  Backend:     ${status.backend}`);
+  if (status.baseDir) {
+    console.log(`  Directory:   ${status.baseDir}`);
+  }
+  if (status.baseDir && status.backend !== "memory") {
+    const lock = readServerLock(status.baseDir);
+    if (lock) {
+      console.log(
+        `  Server:      Running (PID: ${lock.pid}, Port: ${lock.port}, Host: ${lock.host})`
+      );
+    } else {
+      console.log("  Server:      Stopped");
+    }
+  }
+  console.log(`  Users:       ${status.usersCount}`);
+  console.log(`  Total Apps:  ${status.appsCount}`);
+  if (status.apps && status.apps.length > 0) {
+    console.log("\nApplications:");
+    for (const app of status.apps) {
+      console.log(`  - App: ${app.id}`);
+      console.log(
+        `    Tables (${app.tables.length}): ${app.tables.length > 0 ? app.tables.join(", ") : "(none)"}`
+      );
+    }
+  } else if (appId) {
+    console.log(`
+No tables found for application "${appId}".`);
+  }
+}
+
+// src/cli/commands/tables.ts
+async function handleTablesCommand(storage, args) {
+  const action = args[1] ?? "list";
+  if (action === "add" || action === "rm") {
+    const appId = args[2];
+    if (!appId) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing application ID"
+      );
+    }
+    const tableNames = args.slice(3);
+    if (!tableNames.length) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing table name"
+      );
+    }
+    const app = await storage.getApp(appId);
+    if (!app) {
+      throw new TetherServerError(
+        1 /* NotFound */,
+        `Application "${appId}" not found`
+      );
+    }
+    for (const tableName of tableNames) {
+      if (action === "add") {
+        if (await app.getTable(tableName)) {
+          console.log(
+            `Table "${tableName}" already exists in application "${appId}"`
+          );
+        } else {
+          await app.createTable(tableName);
+          console.log(`Added table "${tableName}" to application "${appId}"`);
+        }
+      } else {
+        const table = await app.getTable(tableName);
+        if (!table) {
+          console.log(
+            `Table "${tableName}" not found in application "${appId}"`
+          );
+        } else {
+          await table.delete();
+          console.log(
+            `Removed table "${tableName}" from application "${appId}"`
+          );
+        }
+      }
+    }
+  } else {
+    const appId = action === "list" ? args[2] : action;
+    if (!appId) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing application ID"
+      );
+    }
+    const app = await storage.getApp(appId);
+    if (!app) {
+      throw new TetherServerError(
+        1 /* NotFound */,
+        `Application "${appId}" not found`
+      );
+    }
+    const tables = await app.getTables();
+    if (!tables.length) {
+      console.log(`No tables found for application "${appId}".`);
+    } else {
+      console.log(`Tables for application "${appId}" (${tables.length}):`);
+      for (const t of tables) console.log(`  \u2022 ${t.name}`);
+    }
+  }
+}
+
+// src/cli/commands/users.ts
+async function handleUsersCommand(storage, [, action = "list", arg1, arg2]) {
+  if (action === "list") {
+    const users = await storage.getUsers();
+    if (!users.length) return console.log("No registered users found.");
+    console.log(`Registered users (${users.length}):`);
+    for (const u of users) {
+      console.log(
+        `  \u2022 [${u.id}] ${u.username} (created: ${new Date(u.createdAt).toISOString()})`
+      );
+    }
+  } else if (action === "add") {
+    if (!arg1) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing username"
+      );
+    }
+    if (!arg2) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing password"
+      );
+    }
+    const user = await storage.createUser(arg1, arg2);
+    console.log(`Created user: [${user.id}] ${user.username}`);
+  } else if (action === "rm") {
+    if (!arg1) {
+      throw new TetherServerError(
+        6 /* ConfigurationError */,
+        "Missing user ID"
+      );
+    }
+    const user = await storage.getUser(arg1);
+    if (!user) return console.log(`User not found: ${arg1}`);
+    await user.delete();
+    console.log(`Deleted user: ${arg1}`);
+  } else {
+    throw new TetherServerError(
+      6 /* ConfigurationError */,
+      `Unknown users action: "${action}"`
+    );
+  }
+}
+
+// src/cli/cli.ts
+async function runCli(args = process.argv.slice(2)) {
+  if (isHelpRequested(args)) {
+    printHelp();
+    return;
+  }
+  let storage;
+  try {
+    const { command, positionalArgs, port, host, backend, dir } = parseCliArgs(args);
+    storage = createBackend(backend, dir);
+    switch (command) {
+      case "serve":
+        await handleServeCommand(storage, backend, dir, port, host);
+        break;
+      case "status":
+        await handleStatusCommand(storage, positionalArgs);
+        break;
+      case "maintenance":
+        await handleMaintenanceCommand(storage, positionalArgs);
+        break;
+      case "apps":
+        await handleAppsCommand(storage, positionalArgs);
+        break;
+      case "tables":
+        await handleTablesCommand(storage, positionalArgs);
+        break;
+      case "users":
+        await handleUsersCommand(storage, positionalArgs);
+        break;
+      default:
+        throw new TetherServerError(
+          6 /* ConfigurationError */,
+          `Unknown command: "${command}"`
+        );
+    }
+    await storage.close?.();
+  } catch (err) {
+    console.error("Command failed:", err.message);
+    await storage?.close?.();
+    process.exit(1);
+  }
+}
+if (process.argv[1] && (0, import_node_url.fileURLToPath)(importMetaUrl) === path8.resolve(process.argv[1])) {
+  runCli().catch((err) => {
+    console.error("Failed to start TetherDB CLI:", err);
+    process.exit(1);
+  });
+}
+function isHelpRequested(args) {
+  return args.some(
+    (arg) => arg === "help" || arg === "--help" || arg === "-h" || arg === "-?" || arg === "/?" || arg === "-help"
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});
+//# sourceMappingURL=index.cjs.map