@tiflis-io/tiflis-code-tunnel 0.3.0

package/dist/main.js

@@ -0,0 +1,2264 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { nanoid } from "nanoid";
+
+// src/app.ts
+import Fastify from "fastify";
+function createApp(config2) {
+  const app = Fastify({
+    loggerInstance: config2.logger,
+    trustProxy: config2.env.TRUST_PROXY,
+    // Disable request logging since we use pino directly
+    disableRequestLogging: true
+  });
+  app.addHook("onRequest", async (request, _reply) => {
+    request.log.info(
+      {
+        method: request.method,
+        url: request.url,
+        // Include forwarded headers if behind proxy
+        ...config2.env.TRUST_PROXY && {
+          forwardedFor: request.headers["x-forwarded-for"],
+          forwardedProto: request.headers["x-forwarded-proto"]
+        }
+      },
+      "Incoming request"
+    );
+  });
+  app.addHook("onResponse", async (request, reply) => {
+    request.log.info(
+      {
+        method: request.method,
+        url: request.url,
+        statusCode: reply.statusCode,
+        responseTime: reply.elapsedTime
+      },
+      "Request completed"
+    );
+  });
+  app.setErrorHandler((error, request, reply) => {
+    request.log.error({ error }, "Request error");
+    const statusCode = error.statusCode ?? 500;
+    const code = error.code || "INTERNAL_ERROR";
+    void reply.status(statusCode).send({
+      error: error.message,
+      code
+    });
+  });
+  app.setNotFoundHandler((request, reply) => {
+    request.log.warn({ url: request.url }, "Route not found");
+    reply.status(404).send({
+      error: "Not Found",
+      code: "NOT_FOUND"
+    });
+  });
+  return app;
+}
+
+// src/config/env.ts
+import { z } from "zod";
+import { config } from "dotenv";
+config({ path: ".env.local" });
+config({ path: ".env" });
+var EnvSchema = z.object({
+  // Server
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+  PORT: z.coerce.number().default(3001),
+  HOST: z.string().default("0.0.0.0"),
+  LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error", "fatal"]).default("info"),
+  // Security
+  TUNNEL_REGISTRATION_API_KEY: z.string().min(32, "API key must be at least 32 characters"),
+  // Reverse Proxy Configuration
+  /**
+   * Whether the server is running behind a reverse proxy.
+   * When true, the server will trust X-Forwarded-* headers.
+   */
+  TRUST_PROXY: z.coerce.boolean().default(false),
+  /**
+   * Public base URL for the tunnel server (used to generate public_url in registration response).
+   * Example: "wss://tunnel.example.com" or "ws://localhost:3001"
+   * If not set, will be auto-generated based on HOST and PORT.
+   */
+  PUBLIC_BASE_URL: z.string().url().optional(),
+  /**
+   * Custom WebSocket path (defaults to /ws).
+   */
+  WS_PATH: z.string().default("/ws")
+});
+function loadEnv() {
+  const result = EnvSchema.safeParse(process.env);
+  if (!result.success) {
+    console.error("\u274C Invalid environment variables:");
+    console.error(result.error.format());
+    process.exit(1);
+  }
+  return result.data;
+}
+function generatePublicUrl(env) {
+  if (env.PUBLIC_BASE_URL) {
+    const baseUrl = env.PUBLIC_BASE_URL.replace(/\/$/, "");
+    return `${baseUrl}${env.WS_PATH}`;
+  }
+  const protocol = env.NODE_ENV === "production" ? "wss" : "ws";
+  const host = env.HOST === "0.0.0.0" ? "localhost" : env.HOST;
+  return `${protocol}://${host}:${env.PORT}${env.WS_PATH}`;
+}
+var envInstance = null;
+function getEnv() {
+  envInstance ??= loadEnv();
+  return envInstance;
+}
+
+// src/config/constants.ts
+var PROTOCOL_VERSION = {
+  major: 1,
+  minor: 0,
+  patch: 0
+};
+function getProtocolVersion() {
+  return `${PROTOCOL_VERSION.major}.${PROTOCOL_VERSION.minor}.${PROTOCOL_VERSION.patch}`;
+}
+var CONNECTION_TIMING = {
+  /** How often clients should send ping (15 seconds - keeps connection alive through proxies) */
+  PING_INTERVAL_MS: 15e3,
+  /** Max time to wait for ping before considering connection stale (45 seconds) */
+  PONG_TIMEOUT_MS: 45e3,
+  /** Interval for checking timed-out connections (10 seconds) */
+  TIMEOUT_CHECK_INTERVAL_MS: 1e4,
+  /** Minimum reconnect delay (1 second) */
+  RECONNECT_DELAY_MIN_MS: 1e3,
+  /** Maximum reconnect delay (30 seconds) */
+  RECONNECT_DELAY_MAX_MS: 3e4
+};
+var WEBSOCKET_CONFIG = {
+  /** Path for WebSocket endpoint */
+  PATH: "/ws"
+};
+
+// src/utils/version.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+function getTunnelVersion() {
+  try {
+    const packageJsonPath = join(process.cwd(), "package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    return packageJson.version;
+  } catch (error) {
+    console.error("Failed to read tunnel version from package.json:", error);
+    return "unknown";
+  }
+}
+
+// src/infrastructure/logging/pino-logger.ts
+import pino from "pino";
+function createLogger(config2) {
+  const options = {
+    name: config2.name,
+    level: config2.level,
+    formatters: {
+      level: (label) => ({ level: label })
+    },
+    // Redact sensitive data from logs
+    redact: {
+      paths: [
+        "api_key",
+        "auth_key",
+        "payload.api_key",
+        "payload.auth_key",
+        "*.api_key",
+        "*.auth_key"
+      ],
+      censor: "****"
+    }
+  };
+  if (config2.pretty) {
+    return pino({
+      ...options,
+      transport: {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+          translateTime: "SYS:standard",
+          ignore: "pid,hostname"
+        }
+      }
+    });
+  }
+  return pino(options);
+}
+
+// src/infrastructure/persistence/in-memory-registry.ts
+var InMemoryWorkstationRegistry = class {
+  workstations = /* @__PURE__ */ new Map();
+  register(workstation) {
+    this.workstations.set(workstation.tunnelId.value, workstation);
+  }
+  unregister(tunnelId) {
+    return this.workstations.delete(tunnelId.value);
+  }
+  get(tunnelId) {
+    return this.workstations.get(tunnelId.value);
+  }
+  has(tunnelId) {
+    return this.workstations.has(tunnelId.value);
+  }
+  getAll() {
+    return Array.from(this.workstations.values());
+  }
+  count() {
+    return this.workstations.size;
+  }
+  findTimedOut(timeoutMs) {
+    return this.getAll().filter((ws) => ws.hasTimedOut(timeoutMs));
+  }
+};
+var InMemoryClientRegistry = class {
+  clients = /* @__PURE__ */ new Map();
+  register(client) {
+    this.clients.set(client.deviceId, client);
+  }
+  unregister(deviceId) {
+    return this.clients.delete(deviceId);
+  }
+  get(deviceId) {
+    return this.clients.get(deviceId);
+  }
+  has(deviceId) {
+    return this.clients.has(deviceId);
+  }
+  getByTunnelId(tunnelId) {
+    return this.getAll().filter(
+      (client) => client.tunnelId.equals(tunnelId)
+    );
+  }
+  getAll() {
+    return Array.from(this.clients.values());
+  }
+  count() {
+    return this.clients.size;
+  }
+  findTimedOut(timeoutMs) {
+    return this.getAll().filter((client) => client.hasTimedOut(timeoutMs));
+  }
+};
+var InMemoryHttpClientRegistry = class {
+  clients = /* @__PURE__ */ new Map();
+  register(client) {
+    this.clients.set(client.deviceId, client);
+  }
+  unregister(deviceId) {
+    return this.clients.delete(deviceId);
+  }
+  get(deviceId) {
+    return this.clients.get(deviceId);
+  }
+  has(deviceId) {
+    return this.clients.has(deviceId);
+  }
+  getByTunnelId(tunnelId) {
+    return this.getAll().filter(
+      (client) => client.tunnelId.equals(tunnelId)
+    );
+  }
+  getAll() {
+    return Array.from(this.clients.values());
+  }
+  count() {
+    return this.clients.size;
+  }
+  findTimedOut(timeoutMs) {
+    return this.getAll().filter((client) => client.hasTimedOut(timeoutMs));
+  }
+};
+
+// src/infrastructure/http/health-route.ts
+function registerHealthRoute(app, config2, deps) {
+  const startTime = Date.now();
+  app.get("/health", async (_request, reply) => {
+    const workstationCount = deps.workstationRegistry.count();
+    const clientCount = deps.clientRegistry.count();
+    const response = {
+      status: "healthy",
+      version: config2.version,
+      uptime: Math.floor((Date.now() - startTime) / 1e3),
+      connections: {
+        workstations: workstationCount,
+        clients: clientCount
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return reply.status(200).send(response);
+  });
+  app.get("/healthz", async (_request, reply) => {
+    return reply.status(200).send({ status: "ok" });
+  });
+  app.get("/readyz", async (_request, reply) => {
+    return reply.status(200).send({ status: "ready" });
+  });
+}
+
+// src/domain/errors/domain-errors.ts
+var DomainError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message
+    };
+  }
+};
+var InvalidApiKeyError = class extends DomainError {
+  code = "INVALID_API_KEY";
+  statusCode = 401;
+  constructor() {
+    super("Invalid API key for workstation registration");
+  }
+};
+var InvalidAuthKeyError = class extends DomainError {
+  code = "INVALID_AUTH_KEY";
+  statusCode = 401;
+  constructor() {
+    super("Invalid authentication key");
+  }
+};
+var TunnelNotFoundError = class extends DomainError {
+  code = "TUNNEL_NOT_FOUND";
+  statusCode = 404;
+  constructor(tunnelId) {
+    super(`Tunnel not found: ${tunnelId}`);
+  }
+};
+var WorkstationOfflineError = class extends DomainError {
+  code = "WORKSTATION_OFFLINE";
+  statusCode = 503;
+  constructor(tunnelId) {
+    super(`Workstation is offline: ${tunnelId}`);
+  }
+};
+
+// src/infrastructure/http/watch-api-route.ts
+function registerWatchApiRoute(app, deps) {
+  const { httpClientOperations, logger } = deps;
+  const log = logger.child({ route: "watch-api" });
+  app.post("/api/v1/watch/connect", async (request, reply) => {
+    try {
+      const { tunnel_id, auth_key, device_id } = request.body;
+      if (!tunnel_id || !auth_key || !device_id) {
+        return await reply.status(400).send({
+          error: "missing_parameters",
+          message: "tunnel_id, auth_key, and device_id are required"
+        });
+      }
+      const result = httpClientOperations.connect({
+        tunnelId: tunnel_id,
+        authKey: auth_key,
+        deviceId: device_id
+      });
+      log.info({ deviceId: device_id, tunnelId: tunnel_id }, "Watch connected via HTTP");
+      return await reply.status(200).send({
+        success: true,
+        tunnel_id: result.tunnelId,
+        workstation_online: result.workstationOnline,
+        workstation_name: result.workstationName
+      });
+    } catch (error) {
+      return await handleError(error, reply, log);
+    }
+  });
+  app.post("/api/v1/watch/command", async (request, reply) => {
+    try {
+      const { device_id, message } = request.body;
+      if (!device_id) {
+        return await reply.status(400).send({
+          error: "missing_parameters",
+          message: "device_id and message are required"
+        });
+      }
+      const sent = httpClientOperations.sendCommand({
+        deviceId: device_id,
+        message
+      });
+      if (!sent) {
+        return await reply.status(503).send({
+          error: "send_failed",
+          message: "Failed to send command to workstation"
+        });
+      }
+      return await reply.status(200).send({
+        success: true
+      });
+    } catch (error) {
+      return await handleError(error, reply, log);
+    }
+  });
+  app.get("/api/v1/watch/messages", async (request, reply) => {
+    try {
+      const { device_id, since, ack } = request.query;
+      if (!device_id) {
+        return await reply.status(400).send({
+          error: "missing_parameters",
+          message: "device_id is required"
+        });
+      }
+      const sinceSequence = since ? parseInt(since, 10) : 0;
+      const ackSequence = ack ? parseInt(ack, 10) : void 0;
+      const result = httpClientOperations.pollMessages({
+        deviceId: device_id,
+        sinceSequence,
+        acknowledgeSequence: ackSequence
+      });
+      const messages = result.messages.map((msg) => ({
+        sequence: msg.sequence,
+        timestamp: msg.timestamp.toISOString(),
+        data: JSON.parse(msg.data)
+      }));
+      return await reply.status(200).send({
+        messages,
+        current_sequence: result.currentSequence,
+        workstation_online: result.workstationOnline
+      });
+    } catch (error) {
+      return await handleError(error, reply, log);
+    }
+  });
+  app.get("/api/v1/watch/state", async (request, reply) => {
+    try {
+      const { device_id } = request.query;
+      if (!device_id) {
+        return await reply.status(400).send({
+          error: "missing_parameters",
+          message: "device_id is required"
+        });
+      }
+      const result = httpClientOperations.getState({
+        deviceId: device_id
+      });
+      return await reply.status(200).send({
+        connected: result.connected,
+        workstation_online: result.workstationOnline,
+        workstation_name: result.workstationName,
+        queue_size: result.queueSize,
+        current_sequence: result.currentSequence
+      });
+    } catch (error) {
+      return await handleError(error, reply, log);
+    }
+  });
+  app.post("/api/v1/watch/disconnect", async (request, reply) => {
+    try {
+      const { device_id } = request.body;
+      if (!device_id) {
+        return await reply.status(400).send({
+          error: "missing_parameters",
+          message: "device_id is required"
+        });
+      }
+      const disconnected = httpClientOperations.disconnect(device_id);
+      log.info({ deviceId: device_id }, "Watch disconnected via HTTP");
+      return await reply.status(200).send({
+        success: disconnected
+      });
+    } catch (error) {
+      return await handleError(error, reply, log);
+    }
+  });
+}
+async function handleError(error, reply, log) {
+  if (error instanceof TunnelNotFoundError) {
+    return await reply.status(404).send({
+      error: "tunnel_not_found",
+      message: error.message
+    });
+  }
+  if (error instanceof InvalidAuthKeyError) {
+    return await reply.status(401).send({
+      error: "invalid_auth_key",
+      message: "Invalid authentication key"
+    });
+  }
+  if (error instanceof WorkstationOfflineError) {
+    return await reply.status(503).send({
+      error: "workstation_offline",
+      message: "Workstation is offline"
+    });
+  }
+  log.error({ error }, "Unexpected error in Watch API");
+  return await reply.status(500).send({
+    error: "internal_error",
+    message: "An unexpected error occurred"
+  });
+}
+
+// src/domain/value-objects/tunnel-id.ts
+var TunnelId = class _TunnelId {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  get value() {
+    return this._value;
+  }
+  static create(value) {
+    if (!value || value.trim().length === 0) {
+      throw new Error("TunnelId cannot be empty");
+    }
+    return new _TunnelId(value.trim());
+  }
+  static generate(generator) {
+    return new _TunnelId(generator());
+  }
+  equals(other) {
+    return this._value === other._value;
+  }
+  toString() {
+    return this._value;
+  }
+};
+
+// src/protocol/schemas.ts
+import { z as z2 } from "zod";
+var WorkstationRegisterPayloadSchema = z2.object({
+  api_key: z2.string().min(32, "API key must be at least 32 characters"),
+  name: z2.string().min(1, "Workstation name is required"),
+  auth_key: z2.string().min(16, "Auth key must be at least 16 characters"),
+  reconnect: z2.boolean().optional(),
+  previous_tunnel_id: z2.string().optional()
+});
+var WorkstationRegisterSchema = z2.object({
+  type: z2.literal("workstation.register"),
+  payload: WorkstationRegisterPayloadSchema
+});
+var ConnectPayloadSchema = z2.object({
+  tunnel_id: z2.string().min(1, "Tunnel ID is required"),
+  auth_key: z2.string().min(16, "Auth key must be at least 16 characters"),
+  device_id: z2.string().min(1, "Device ID is required"),
+  reconnect: z2.boolean().optional()
+});
+var ConnectSchema = z2.object({
+  type: z2.literal("connect"),
+  payload: ConnectPayloadSchema
+});
+var PingSchema = z2.object({
+  type: z2.literal("ping"),
+  timestamp: z2.number()
+});
+var PongSchema = z2.object({
+  type: z2.literal("pong"),
+  timestamp: z2.number()
+});
+var ForwardToDeviceSchema = z2.object({
+  type: z2.literal("forward.to_device"),
+  device_id: z2.string().min(1, "Device ID is required"),
+  payload: z2.string()
+});
+var BaseMessageSchema = z2.object({
+  type: z2.string()
+});
+var IncomingMessageSchema = z2.discriminatedUnion("type", [
+  WorkstationRegisterSchema,
+  ConnectSchema,
+  PingSchema
+]);
+function getMessageType(data) {
+  const result = BaseMessageSchema.safeParse(data);
+  if (result.success) {
+    return result.data.type;
+  }
+  return void 0;
+}
+
+// src/protocol/errors.ts
+function createErrorMessage(code, message, requestId, details) {
+  const result = {
+    type: "error",
+    payload: {
+      code,
+      message
+    }
+  };
+  if (requestId) {
+    result.id = requestId;
+  }
+  if (details !== void 0) {
+    result.payload.details = details;
+  }
+  return result;
+}
+var ProtocolErrors = {
+  invalidApiKey: (requestId) => createErrorMessage("INVALID_API_KEY", "Invalid API key for workstation registration", requestId),
+  invalidAuthKey: (requestId) => createErrorMessage("INVALID_AUTH_KEY", "Invalid authentication key", requestId),
+  tunnelNotFound: (tunnelId, requestId) => createErrorMessage("TUNNEL_NOT_FOUND", `Tunnel not found: ${tunnelId}`, requestId),
+  workstationOffline: (tunnelId, requestId) => createErrorMessage("WORKSTATION_OFFLINE", `Workstation is offline: ${tunnelId}`, requestId),
+  registrationFailed: (reason, requestId) => createErrorMessage("REGISTRATION_FAILED", `Workstation registration failed: ${reason}`, requestId),
+  invalidPayload: (message, requestId, details) => createErrorMessage("INVALID_PAYLOAD", message, requestId, details),
+  internalError: (message = "An internal error occurred", requestId) => createErrorMessage("INTERNAL_ERROR", message, requestId)
+};
+
+// src/infrastructure/websocket/connection-handler.ts
+var ConnectionHandler = class {
+  meta = /* @__PURE__ */ new WeakMap();
+  deps;
+  logger;
+  constructor(deps) {
+    this.deps = deps;
+    this.logger = deps.logger.child({ component: "ConnectionHandler" });
+  }
+  /**
+   * Sets up event handlers for a new WebSocket connection.
+   */
+  handleConnection(socket) {
+    this.meta.set(socket, { role: "unknown" });
+    socket.on("message", (data) => {
+      let message;
+      if (Array.isArray(data)) {
+        message = Buffer.concat(data).toString("utf8");
+      } else if (data instanceof ArrayBuffer) {
+        message = Buffer.from(new Uint8Array(data)).toString("utf8");
+      } else {
+        message = data.toString("utf8");
+      }
+      this.handleMessage(socket, message);
+    });
+    socket.on("close", () => {
+      this.handleClose(socket);
+    });
+    socket.on("error", (error) => {
+      this.logger.error({ error }, "WebSocket error");
+    });
+  }
+  /**
+   * Processes an incoming message from a WebSocket connection.
+   */
+  handleMessage(socket, data) {
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      this.sendError(socket, "INVALID_PAYLOAD", "Invalid JSON");
+      return;
+    }
+    const messageType = getMessageType(parsed);
+    if (!messageType) {
+      this.sendError(socket, "INVALID_PAYLOAD", "Missing message type");
+      return;
+    }
+    const meta = this.meta.get(socket);
+    if (!meta) {
+      this.logger.error("Connection metadata not found");
+      socket.close(1011, "Internal error");
+      return;
+    }
+    try {
+      switch (messageType) {
+        case "workstation.register":
+          this.handleWorkstationRegister(socket, parsed, meta);
+          break;
+        case "connect":
+          this.handleClientConnect(socket, parsed, meta);
+          break;
+        case "ping":
+          this.handlePing(socket, parsed, meta);
+          break;
+        case "forward.to_device":
+          this.handleForwardToDevice(socket, parsed, meta);
+          break;
+        default:
+          this.logger.info(
+            { messageType, role: meta.role, tunnelId: meta.tunnelId },
+            "Forwarding message based on role"
+          );
+          this.forwardMessage(socket, data, meta);
+          break;
+      }
+    } catch (error) {
+      this.handleError(socket, error);
+    }
+  }
+  /**
+   * Handles workstation registration request.
+   */
+  handleWorkstationRegister(socket, data, meta) {
+    const parseResult = WorkstationRegisterSchema.safeParse(data);
+    if (!parseResult.success) {
+      this.sendError(
+        socket,
+        "INVALID_PAYLOAD",
+        "Invalid registration payload",
+        void 0,
+        parseResult.error.flatten()
+      );
+      return;
+    }
+    const { payload } = parseResult.data;
+    const result = this.deps.registerWorkstation.execute(socket, {
+      apiKey: payload.api_key,
+      name: payload.name,
+      authKey: payload.auth_key,
+      reconnect: payload.reconnect,
+      previousTunnelId: payload.previous_tunnel_id
+    });
+    meta.role = "workstation";
+    meta.tunnelId = result.tunnelId;
+    if (result.restored) {
+      const onlineMessage = {
+        type: "connection.workstation_online",
+        payload: {
+          tunnel_id: result.tunnelId
+        }
+      };
+      this.deps.forwardMessage.broadcastToClients(
+        TunnelId.create(result.tunnelId),
+        onlineMessage
+      );
+    }
+    const response = {
+      type: "workstation.registered",
+      payload: {
+        tunnel_id: result.tunnelId,
+        public_url: result.publicUrl,
+        restored: result.restored || void 0
+      }
+    };
+    socket.send(JSON.stringify(response));
+    this.logger.info(
+      { tunnelId: result.tunnelId, restored: result.restored },
+      "Workstation registered"
+    );
+  }
+  /**
+   * Handles mobile client connection request.
+   */
+  handleClientConnect(socket, data, meta) {
+    const parseResult = ConnectSchema.safeParse(data);
+    if (!parseResult.success) {
+      this.sendError(
+        socket,
+        "INVALID_PAYLOAD",
+        "Invalid connection payload",
+        void 0,
+        parseResult.error.flatten()
+      );
+      return;
+    }
+    const { payload } = parseResult.data;
+    const result = this.deps.connectClient.execute(socket, {
+      tunnelId: payload.tunnel_id,
+      authKey: payload.auth_key,
+      deviceId: payload.device_id,
+      reconnect: payload.reconnect
+    });
+    meta.role = "client";
+    meta.tunnelId = result.tunnelId;
+    meta.deviceId = payload.device_id;
+    const response = {
+      type: "connected",
+      payload: {
+        tunnel_id: result.tunnelId,
+        tunnel_version: this.deps.tunnelVersion,
+        protocol_version: this.deps.protocolVersion,
+        restored: result.restored || void 0
+      }
+    };
+    socket.send(JSON.stringify(response));
+    this.logger.info(
+      {
+        tunnelId: result.tunnelId,
+        deviceId: payload.device_id,
+        restored: result.restored
+      },
+      "Client connected"
+    );
+  }
+  /**
+   * Handles ping message.
+   */
+  handlePing(socket, data, meta) {
+    const parseResult = PingSchema.safeParse(data);
+    if (!parseResult.success) {
+      return;
+    }
+    if (meta.role === "workstation" && meta.tunnelId) {
+      const workstation = this.deps.workstationRegistry.get(
+        TunnelId.create(meta.tunnelId)
+      );
+      workstation?.recordPing();
+    } else if (meta.role === "client" && meta.deviceId) {
+      const client = this.deps.clientRegistry.get(meta.deviceId);
+      client?.recordPing();
+    }
+    const pong = {
+      type: "pong",
+      timestamp: parseResult.data.timestamp
+    };
+    socket.send(JSON.stringify(pong));
+  }
+  /**
+   * Handles forward.to_device message from workstation.
+   * Sends the payload to a specific device by device_id.
+   */
+  handleForwardToDevice(socket, data, meta) {
+    if (meta.role !== "workstation" || !meta.tunnelId) {
+      this.sendError(
+        socket,
+        "INVALID_PAYLOAD",
+        "Only workstations can send forward.to_device"
+      );
+      return;
+    }
+    const parseResult = ForwardToDeviceSchema.safeParse(data);
+    if (!parseResult.success) {
+      this.sendError(
+        socket,
+        "INVALID_PAYLOAD",
+        "Invalid forward.to_device payload",
+        void 0,
+        parseResult.error.flatten()
+      );
+      return;
+    }
+    const { device_id, payload } = parseResult.data;
+    const tunnelId = TunnelId.create(meta.tunnelId);
+    this.deps.forwardMessage.forwardToDevice(tunnelId, device_id, payload);
+  }
+  /**
+   * Forwards a message based on the connection role.
+   */
+  forwardMessage(socket, data, meta) {
+    let msgType = "unknown";
+    try {
+      const parsed = JSON.parse(data);
+      msgType = parsed.type ?? "unknown";
+    } catch {
+    }
+    this.logger.info(
+      { messageType: msgType, role: meta.role, tunnelId: meta.tunnelId },
+      "forwardMessage called"
+    );
+    if (meta.role === "workstation" && meta.tunnelId) {
+      this.deps.forwardMessage.forwardToClients(
+        TunnelId.create(meta.tunnelId),
+        data
+      );
+    } else if (meta.role === "client" && meta.deviceId) {
+      try {
+        this.deps.forwardMessage.forwardToWorkstation(meta.deviceId, data);
+      } catch (error) {
+        this.handleError(socket, error);
+      }
+    } else {
+      this.sendError(socket, "INVALID_PAYLOAD", "Not authenticated");
+    }
+  }
+  /**
+   * Handles WebSocket connection close.
+   */
+  handleClose(socket) {
+    const meta = this.meta.get(socket);
+    if (!meta) return;
+    if (meta.role === "workstation" && meta.tunnelId) {
+      this.deps.handleDisconnection.handleWorkstationDisconnection(
+        TunnelId.create(meta.tunnelId)
+      );
+    } else if (meta.role === "client" && meta.deviceId) {
+      this.deps.handleDisconnection.handleClientDisconnection(meta.deviceId);
+    }
+    this.meta.delete(socket);
+  }
+  /**
+   * Handles errors and sends appropriate error responses.
+   */
+  handleError(socket, error) {
+    if (error instanceof DomainError) {
+      const errorMessage = ProtocolErrors.invalidPayload(error.message);
+      errorMessage.payload.code = error.code;
+      socket.send(JSON.stringify(errorMessage));
+    } else {
+      this.logger.error({ error }, "Unexpected error");
+      socket.send(JSON.stringify(ProtocolErrors.internalError()));
+    }
+  }
+  /**
+   * Sends an error message to the socket.
+   */
+  sendError(socket, code, message, requestId, details) {
+    const payload = {
+      code,
+      message
+    };
+    if (details !== void 0) {
+      payload.details = details;
+    }
+    const errorMessage = {
+      type: "error",
+      payload
+    };
+    if (requestId) {
+      errorMessage.id = requestId;
+    }
+    socket.send(JSON.stringify(errorMessage));
+  }
+};
+
+// src/infrastructure/websocket/websocket-server.ts
+import { WebSocketServer as WSServer } from "ws";
+var WebSocketServerWrapper = class {
+  wss = null;
+  heartbeatInterval = null;
+  config;
+  deps;
+  logger;
+  constructor(config2, deps) {
+    this.config = config2;
+    this.deps = deps;
+    this.logger = deps.logger.child({ component: "WebSocketServer" });
+  }
+  /**
+   * Attaches the WebSocket server to an HTTP server.
+   */
+  attach(httpServer) {
+    this.wss = new WSServer({
+      server: httpServer,
+      path: this.config.path,
+      maxPayload: 50 * 1024 * 1024
+      // 50MB - allow large messages for audio sync
+    });
+    this.wss.on("connection", (socket) => {
+      this.logger.debug("New WebSocket connection");
+      this.deps.connectionHandler.handleConnection(socket);
+    });
+    this.wss.on("error", (error) => {
+      this.logger.error({ error }, "WebSocket server error");
+    });
+    this.startHeartbeatCheck();
+    this.logger.info(
+      { path: this.config.path },
+      "WebSocket server attached"
+    );
+  }
+  /**
+   * Starts the periodic heartbeat/timeout check.
+   */
+  startHeartbeatCheck() {
+    this.heartbeatInterval = setInterval(() => {
+      this.deps.onTimeoutCheck?.();
+    }, this.config.heartbeatIntervalMs);
+  }
+  /**
+   * Broadcasts a message to all connected clients.
+   */
+  broadcast(message) {
+    if (!this.wss) return;
+    const data = typeof message === "string" ? message : JSON.stringify(message);
+    this.wss.clients.forEach((client) => {
+      if (client.readyState === 1) {
+        client.send(data);
+      }
+    });
+  }
+  /**
+   * Returns the number of connected clients.
+   */
+  get connectionCount() {
+    return this.wss?.clients.size ?? 0;
+  }
+  /**
+   * Closes the WebSocket server gracefully.
+   */
+  async close() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+    const wss = this.wss;
+    if (!wss) return;
+    wss.clients.forEach((client) => {
+      client.close(1001, "Server shutting down");
+    });
+    return new Promise((resolve, reject) => {
+      wss.close((err) => {
+        if (err) {
+          this.logger.error({ error: err }, "Error closing WebSocket server");
+          reject(err);
+        } else {
+          this.logger.info("WebSocket server closed");
+          resolve();
+        }
+      });
+    });
+  }
+};
+
+// src/domain/entities/workstation.ts
+var Workstation = class {
+  _tunnelId;
+  _name;
+  _authKey;
+  _socket;
+  _publicUrl;
+  _status;
+  _lastPingAt;
+  _connectedAt;
+  constructor(props) {
+    this._tunnelId = props.tunnelId;
+    this._name = props.name;
+    this._authKey = props.authKey;
+    this._socket = props.socket;
+    this._publicUrl = props.publicUrl;
+    this._status = "online";
+    this._lastPingAt = /* @__PURE__ */ new Date();
+    this._connectedAt = /* @__PURE__ */ new Date();
+  }
+  get tunnelId() {
+    return this._tunnelId;
+  }
+  get name() {
+    return this._name;
+  }
+  get authKey() {
+    return this._authKey;
+  }
+  get socket() {
+    return this._socket;
+  }
+  get publicUrl() {
+    return this._publicUrl;
+  }
+  get status() {
+    return this._status;
+  }
+  get lastPingAt() {
+    return this._lastPingAt;
+  }
+  get connectedAt() {
+    return this._connectedAt;
+  }
+  get isOnline() {
+    return this._status === "online";
+  }
+  /**
+   * Validates the provided auth key against this workstation's auth key.
+   */
+  validateAuthKey(authKey) {
+    return this._authKey.secureEquals(authKey);
+  }
+  /**
+   * Updates the last ping timestamp.
+   */
+  recordPing() {
+    this._lastPingAt = /* @__PURE__ */ new Date();
+    if (this._status === "offline") {
+      this._status = "online";
+    }
+  }
+  /**
+   * Marks the workstation as offline.
+   */
+  markOffline() {
+    this._status = "offline";
+  }
+  /**
+   * Marks the workstation as online.
+   */
+  markOnline() {
+    this._status = "online";
+    this._lastPingAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Updates the socket connection (for reconnection scenarios).
+   */
+  updateSocket(socket) {
+    this._socket = socket;
+    this.markOnline();
+  }
+  /**
+   * Sends a message to the workstation.
+   */
+  send(message) {
+    if (!this.isOnline || this._socket.readyState !== 1) {
+      return false;
+    }
+    this._socket.send(message);
+    return true;
+  }
+  /**
+   * Checks if the workstation has timed out (no ping received within timeout period).
+   */
+  hasTimedOut(timeoutMs) {
+    const elapsed = Date.now() - this._lastPingAt.getTime();
+    return elapsed > timeoutMs;
+  }
+};
+
+// src/domain/value-objects/auth-key.ts
+var MIN_AUTH_KEY_LENGTH = 16;
+var AuthKey = class _AuthKey {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  get value() {
+    return this._value;
+  }
+  static create(value) {
+    if (!value || value.trim().length < MIN_AUTH_KEY_LENGTH) {
+      throw new Error(`AuthKey must be at least ${MIN_AUTH_KEY_LENGTH} characters`);
+    }
+    return new _AuthKey(value.trim());
+  }
+  /**
+   * Creates an AuthKey without validation.
+   * Use for cases where the key was already validated (e.g., from storage).
+   */
+  static fromTrusted(value) {
+    return new _AuthKey(value);
+  }
+  equals(other) {
+    return this._value === other._value;
+  }
+  /**
+   * Performs a timing-safe comparison to prevent timing attacks.
+   */
+  secureEquals(other) {
+    const a = this._value;
+    const b = other._value;
+    if (a.length !== b.length) {
+      return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+  }
+  toString() {
+    return `${this._value.substring(0, 4)}****`;
+  }
+};
+
+// src/application/register-workstation.ts
+var RegisterWorkstationUseCase = class {
+  workstationRegistry;
+  generateTunnelId;
+  getPublicUrl;
+  expectedApiKey;
+  logger;
+  constructor(deps) {
+    this.workstationRegistry = deps.workstationRegistry;
+    this.generateTunnelId = deps.generateTunnelId;
+    this.getPublicUrl = deps.getPublicUrl;
+    this.expectedApiKey = deps.expectedApiKey;
+    this.logger = deps.logger.child({ useCase: "RegisterWorkstation" });
+  }
+  execute(socket, params) {
+    if (params.apiKey !== this.expectedApiKey) {
+      this.logger.warn("Invalid API key attempted");
+      throw new InvalidApiKeyError();
+    }
+    let tunnelId;
+    let restored = false;
+    if (params.reconnect && params.previousTunnelId) {
+      const requestedTunnelId = TunnelId.create(params.previousTunnelId);
+      const existing = this.workstationRegistry.get(requestedTunnelId);
+      if (existing) {
+        tunnelId = existing.tunnelId;
+        existing.updateSocket(socket);
+        restored = true;
+        this.logger.info(
+          { tunnelId: tunnelId.value, name: params.name },
+          "Workstation reconnected with restored tunnel ID"
+        );
+      } else {
+        if (this.workstationRegistry.has(requestedTunnelId)) {
+          tunnelId = TunnelId.generate(this.generateTunnelId);
+          this.logger.warn(
+            {
+              tunnelId: tunnelId.value,
+              previousTunnelId: params.previousTunnelId,
+              name: params.name
+            },
+            "Previous tunnel ID is in use, generated new tunnel ID"
+          );
+        } else {
+          tunnelId = requestedTunnelId;
+          this.logger.info(
+            {
+              tunnelId: tunnelId.value,
+              name: params.name
+            },
+            "Workstation reclaimed tunnel ID after tunnel server restart"
+          );
+        }
+      }
+    } else {
+      tunnelId = TunnelId.generate(this.generateTunnelId);
+    }
+    if (!restored) {
+      const workstation = new Workstation({
+        tunnelId,
+        name: params.name,
+        authKey: AuthKey.create(params.authKey),
+        socket,
+        publicUrl: this.getPublicUrl()
+      });
+      this.workstationRegistry.register(workstation);
+      this.logger.info(
+        { tunnelId: tunnelId.value, name: params.name },
+        "Workstation registered"
+      );
+    }
+    return {
+      tunnelId: tunnelId.value,
+      publicUrl: this.getPublicUrl(),
+      restored
+    };
+  }
+};
+
+// src/domain/entities/mobile-client.ts
+var MobileClient = class {
+  _deviceId;
+  _tunnelId;
+  _socket;
+  _status;
+  _lastPingAt;
+  _connectedAt;
+  constructor(props) {
+    this._deviceId = props.deviceId;
+    this._tunnelId = props.tunnelId;
+    this._socket = props.socket;
+    this._status = "connected";
+    this._lastPingAt = /* @__PURE__ */ new Date();
+    this._connectedAt = /* @__PURE__ */ new Date();
+  }
+  get deviceId() {
+    return this._deviceId;
+  }
+  get tunnelId() {
+    return this._tunnelId;
+  }
+  get socket() {
+    return this._socket;
+  }
+  get status() {
+    return this._status;
+  }
+  get lastPingAt() {
+    return this._lastPingAt;
+  }
+  get connectedAt() {
+    return this._connectedAt;
+  }
+  get isConnected() {
+    return this._status === "connected";
+  }
+  /**
+   * Updates the last ping timestamp.
+   */
+  recordPing() {
+    this._lastPingAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Marks the client as disconnected.
+   */
+  markDisconnected() {
+    this._status = "disconnected";
+  }
+  /**
+   * Updates the socket connection (for reconnection scenarios).
+   */
+  updateSocket(socket) {
+    this._socket = socket;
+    this._status = "connected";
+    this._lastPingAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Sends a message to the client.
+   */
+  send(message) {
+    if (!this.isConnected || this._socket.readyState !== 1) {
+      return false;
+    }
+    this._socket.send(message);
+    return true;
+  }
+  /**
+   * Checks if the client has timed out (no ping received within timeout period).
+   */
+  hasTimedOut(timeoutMs) {
+    const elapsed = Date.now() - this._lastPingAt.getTime();
+    return elapsed > timeoutMs;
+  }
+};
+
+// src/application/connect-client.ts
+var ConnectClientUseCase = class {
+  workstationRegistry;
+  clientRegistry;
+  logger;
+  constructor(deps) {
+    this.workstationRegistry = deps.workstationRegistry;
+    this.clientRegistry = deps.clientRegistry;
+    this.logger = deps.logger.child({ useCase: "ConnectClient" });
+  }
+  execute(socket, params) {
+    const tunnelId = TunnelId.create(params.tunnelId);
+    const workstation = this.workstationRegistry.get(tunnelId);
+    if (!workstation) {
+      this.logger.warn(
+        { tunnelId: params.tunnelId, deviceId: params.deviceId },
+        "Tunnel not found"
+      );
+      throw new TunnelNotFoundError(params.tunnelId);
+    }
+    if (!workstation.isOnline) {
+      this.logger.warn(
+        { tunnelId: params.tunnelId, deviceId: params.deviceId },
+        "Workstation is offline"
+      );
+      throw new WorkstationOfflineError(params.tunnelId);
+    }
+    const authKey = AuthKey.fromTrusted(params.authKey);
+    if (!workstation.validateAuthKey(authKey)) {
+      this.logger.warn(
+        { tunnelId: params.tunnelId, deviceId: params.deviceId },
+        "Invalid auth key"
+      );
+      throw new InvalidAuthKeyError();
+    }
+    let restored = false;
+    if (params.reconnect) {
+      const existingClient = this.clientRegistry.get(params.deviceId);
+      if (existingClient?.tunnelId.equals(tunnelId)) {
+        existingClient.updateSocket(socket);
+        restored = true;
+        this.logger.info(
+          { tunnelId: params.tunnelId, deviceId: params.deviceId },
+          "Client reconnected"
+        );
+      }
+    }
+    if (!restored) {
+      this.clientRegistry.unregister(params.deviceId);
+      const client = new MobileClient({
+        deviceId: params.deviceId,
+        tunnelId,
+        socket
+      });
+      this.clientRegistry.register(client);
+      this.logger.info(
+        { tunnelId: params.tunnelId, deviceId: params.deviceId },
+        "Client connected"
+      );
+    }
+    return {
+      tunnelId: tunnelId.value,
+      restored
+    };
+  }
+};
+
+// src/application/forward-message.ts
+var ForwardMessageUseCase = class {
+  workstationRegistry;
+  clientRegistry;
+  httpClientRegistry;
+  logger;
+  constructor(deps) {
+    this.workstationRegistry = deps.workstationRegistry;
+    this.clientRegistry = deps.clientRegistry;
+    this.httpClientRegistry = deps.httpClientRegistry;
+    this.logger = deps.logger.child({ useCase: "ForwardMessage" });
+  }
+  /**
+   * Forwards a message from a mobile client to the workstation.
+   * Injects device_id into the message so workstation can identify the sender.
+   */
+  forwardToWorkstation(deviceId, message) {
+    this.logger.info({ deviceId, messageLength: message.length }, "forwardToWorkstation called");
+    const client = this.clientRegistry.get(deviceId);
+    if (!client) {
+      this.logger.warn({ deviceId }, "Client not found for forwarding");
+      return false;
+    }
+    const workstation = this.workstationRegistry.get(client.tunnelId);
+    if (!workstation) {
+      this.logger.warn(
+        { tunnelId: client.tunnelId.value, deviceId },
+        "Workstation not found for forwarding"
+      );
+      throw new TunnelNotFoundError(client.tunnelId.value);
+    }
+    if (!workstation.isOnline) {
+      this.logger.warn(
+        { tunnelId: client.tunnelId.value, deviceId },
+        "Workstation offline, cannot forward"
+      );
+      throw new WorkstationOfflineError(client.tunnelId.value);
+    }
+    let enrichedMessage = message;
+    try {
+      const parsed = JSON.parse(message);
+      parsed.device_id = deviceId;
+      enrichedMessage = JSON.stringify(parsed);
+      this.logger.info({ deviceId, messageType: parsed.type, enrichedLength: enrichedMessage.length }, "Injected device_id into message");
+    } catch {
+      this.logger.warn({ deviceId, message: message.slice(0, 100) }, "Could not inject device_id, message is not JSON");
+    }
+    const sent = workstation.send(enrichedMessage);
+    if (!sent) {
+      this.logger.warn(
+        { tunnelId: client.tunnelId.value, deviceId },
+        "Failed to send message to workstation"
+      );
+    }
+    return sent;
+  }
+  /**
+   * Forwards a message from a workstation to all connected clients.
+   * Also queues the message for HTTP polling clients (watchOS).
+   */
+  forwardToClients(tunnelId, message) {
+    const clients = this.clientRegistry.getByTunnelId(tunnelId);
+    let sentCount = 0;
+    let messageType = "unknown";
+    try {
+      const parsed = JSON.parse(message);
+      messageType = parsed.type ?? "unknown";
+    } catch {
+    }
+    const clientsToRemove = [];
+    for (const client of clients) {
+      if (client.send(message)) {
+        sentCount++;
+      } else {
+        this.logger.warn(
+          {
+            tunnelId: tunnelId.value,
+            deviceId: client.deviceId,
+            clientStatus: client.status,
+            socketReadyState: client.socket.readyState,
+            isConnected: client.isConnected,
+            messageType
+          },
+          "forwardToClients - send failed, marking client for removal"
+        );
+        client.markDisconnected();
+        clientsToRemove.push(client.deviceId);
+      }
+    }
+    for (const deviceId of clientsToRemove) {
+      this.clientRegistry.unregister(deviceId);
+      this.logger.info({ deviceId, tunnelId: tunnelId.value }, "Removed zombie client from registry");
+    }
+    let httpQueuedCount = 0;
+    if (this.httpClientRegistry) {
+      const httpClients = this.httpClientRegistry.getByTunnelId(tunnelId);
+      for (const httpClient of httpClients) {
+        if (httpClient.isActive) {
+          httpClient.queueMessage(message);
+          httpQueuedCount++;
+        }
+      }
+    }
+    this.logger.info(
+      {
+        tunnelId: tunnelId.value,
+        wsClients: clients.length,
+        wsSent: sentCount,
+        httpClients: httpQueuedCount,
+        messageType
+      },
+      "forwardToClients"
+    );
+    return sentCount + httpQueuedCount;
+  }
+  /**
+   * Broadcasts a message to all clients connected to a specific tunnel.
+   * Used for system events like workstation_offline/online.
+   */
+  broadcastToClients(tunnelId, message) {
+    return this.forwardToClients(tunnelId, JSON.stringify(message));
+  }
+  /**
+   * Forwards a message to a specific device by device_id.
+   * Used for targeted delivery (e.g., session output to subscribed clients only).
+   */
+  forwardToDevice(tunnelId, deviceId, payload) {
+    const wsClient = this.clientRegistry.get(deviceId);
+    if (wsClient && wsClient.tunnelId.value === tunnelId.value) {
+      const sent = wsClient.send(payload);
+      if (sent) {
+        this.logger.debug({ tunnelId: tunnelId.value, deviceId }, "forwardToDevice via WebSocket");
+        return true;
+      } else {
+        this.logger.warn(
+          {
+            tunnelId: tunnelId.value,
+            deviceId,
+            clientStatus: wsClient.status,
+            socketReadyState: wsClient.socket.readyState,
+            isConnected: wsClient.isConnected
+          },
+          "forwardToDevice - WebSocket send failed, removing zombie client"
+        );
+        wsClient.markDisconnected();
+        this.clientRegistry.unregister(deviceId);
+      }
+    }
+    if (this.httpClientRegistry) {
+      const httpClient = this.httpClientRegistry.get(deviceId);
+      if (httpClient && httpClient.tunnelId.value === tunnelId.value && httpClient.isActive) {
+        httpClient.queueMessage(payload);
+        this.logger.debug({ tunnelId: tunnelId.value, deviceId }, "forwardToDevice via HTTP queue");
+        return true;
+      }
+    }
+    const allClients = this.clientRegistry.getByTunnelId(tunnelId);
+    this.logger.warn(
+      {
+        tunnelId: tunnelId.value,
+        deviceId,
+        registeredClients: allClients.map((c) => ({
+          deviceId: c.deviceId,
+          status: c.status,
+          socketState: c.socket.readyState
+        }))
+      },
+      "forwardToDevice - client not found or not deliverable"
+    );
+    return false;
+  }
+};
+
+// src/application/handle-disconnection.ts
+var HandleDisconnectionUseCase = class {
+  workstationRegistry;
+  clientRegistry;
+  httpClientRegistry;
+  forwardMessage;
+  logger;
+  constructor(deps) {
+    this.workstationRegistry = deps.workstationRegistry;
+    this.clientRegistry = deps.clientRegistry;
+    this.httpClientRegistry = deps.httpClientRegistry;
+    this.forwardMessage = deps.forwardMessage;
+    this.logger = deps.logger.child({ useCase: "HandleDisconnection" });
+  }
+  /**
+   * Handles workstation disconnection.
+   * Marks the workstation as offline and notifies all connected clients.
+   */
+  handleWorkstationDisconnection(tunnelId) {
+    const workstation = this.workstationRegistry.get(tunnelId);
+    if (!workstation) {
+      this.logger.warn(
+        { tunnelId: tunnelId.value },
+        "Attempted to handle disconnection for unknown workstation"
+      );
+      return;
+    }
+    workstation.markOffline();
+    const offlineMessage = {
+      type: "connection.workstation_offline",
+      payload: {
+        tunnel_id: tunnelId.value
+      }
+    };
+    const notifiedCount = this.forwardMessage.broadcastToClients(
+      tunnelId,
+      offlineMessage
+    );
+    this.logger.info(
+      { tunnelId: tunnelId.value, notifiedClients: notifiedCount },
+      "Workstation disconnected, clients notified"
+    );
+  }
+  /**
+   * Handles workstation removal.
+   * Called when the workstation connection is completely closed
+   * and we don't expect a reconnection.
+   */
+  handleWorkstationRemoval(tunnelId) {
+    this.handleWorkstationDisconnection(tunnelId);
+    const removed = this.workstationRegistry.unregister(tunnelId);
+    if (removed) {
+      this.logger.info(
+        { tunnelId: tunnelId.value },
+        "Workstation removed from registry"
+      );
+    }
+  }
+  /**
+   * Handles client disconnection.
+   * Removes the client from the registry and notifies the workstation.
+   */
+  handleClientDisconnection(deviceId) {
+    const client = this.clientRegistry.get(deviceId);
+    if (!client) {
+      this.logger.warn(
+        { deviceId },
+        "Attempted to handle disconnection for unknown client"
+      );
+      return;
+    }
+    const tunnelId = client.tunnelId;
+    client.markDisconnected();
+    this.clientRegistry.unregister(deviceId);
+    const workstation = this.workstationRegistry.get(tunnelId);
+    if (workstation?.isOnline) {
+      const disconnectMessage = {
+        type: "client.disconnected",
+        payload: {
+          device_id: deviceId,
+          tunnel_id: tunnelId.value
+        }
+      };
+      try {
+        workstation.send(JSON.stringify(disconnectMessage));
+        this.logger.debug(
+          { deviceId, tunnelId: tunnelId.value },
+          "Sent client.disconnected notification to workstation"
+        );
+      } catch (error) {
+        this.logger.warn(
+          { deviceId, tunnelId: tunnelId.value, error },
+          "Failed to send client.disconnected notification to workstation"
+        );
+      }
+    }
+    this.logger.info(
+      { deviceId, tunnelId: tunnelId.value },
+      "Client disconnected"
+    );
+  }
+  /**
+   * Handles timeout check for all connections.
+   * Returns the number of connections that were closed due to timeout.
+   */
+  handleTimeoutCheck(timeoutMs) {
+    let workstationsClosed = 0;
+    let clientsClosed = 0;
+    let httpClientsClosed = 0;
+    const timedOutWorkstations = this.workstationRegistry.findTimedOut(timeoutMs);
+    for (const workstation of timedOutWorkstations) {
+      try {
+        workstation.socket.close(1e3, "Connection timed out");
+      } catch {
+      }
+      this.handleWorkstationDisconnection(workstation.tunnelId);
+      workstationsClosed++;
+    }
+    const timedOutClients = this.clientRegistry.findTimedOut(timeoutMs);
+    for (const client of timedOutClients) {
+      this.handleClientDisconnection(client.deviceId);
+      try {
+        client.socket.close(1e3, "Connection timed out");
+      } catch {
+      }
+      clientsClosed++;
+    }
+    const httpTimeoutMs = timeoutMs * 4;
+    if (this.httpClientRegistry) {
+      const timedOutHttpClients = this.httpClientRegistry.findTimedOut(httpTimeoutMs);
+      for (const httpClient of timedOutHttpClients) {
+        httpClient.markInactive();
+        this.httpClientRegistry.unregister(httpClient.deviceId);
+        httpClientsClosed++;
+        this.logger.info(
+          { deviceId: httpClient.deviceId },
+          "HTTP client timed out and removed"
+        );
+      }
+    }
+    if (workstationsClosed > 0 || clientsClosed > 0 || httpClientsClosed > 0) {
+      this.logger.info(
+        { workstationsClosed, clientsClosed, httpClientsClosed },
+        "Timeout check completed"
+      );
+    }
+    return { workstations: workstationsClosed, clients: clientsClosed, httpClients: httpClientsClosed };
+  }
+};
+
+// src/domain/entities/http-client.ts
+var HttpClient = class _HttpClient {
+  _deviceId;
+  _tunnelId;
+  _status;
+  _lastPollAt;
+  _connectedAt;
+  _messageQueue;
+  _sequence;
+  // Maximum messages to keep in queue (prevent memory bloat)
+  static MAX_QUEUE_SIZE = 100;
+  // Message TTL in milliseconds (5 minutes)
+  static MESSAGE_TTL_MS = 5 * 60 * 1e3;
+  constructor(props) {
+    this._deviceId = props.deviceId;
+    this._tunnelId = props.tunnelId;
+    this._status = "active";
+    this._lastPollAt = /* @__PURE__ */ new Date();
+    this._connectedAt = /* @__PURE__ */ new Date();
+    this._messageQueue = [];
+    this._sequence = 0;
+  }
+  get deviceId() {
+    return this._deviceId;
+  }
+  get tunnelId() {
+    return this._tunnelId;
+  }
+  get status() {
+    return this._status;
+  }
+  get lastPollAt() {
+    return this._lastPollAt;
+  }
+  get connectedAt() {
+    return this._connectedAt;
+  }
+  get isActive() {
+    return this._status === "active";
+  }
+  get queueSize() {
+    return this._messageQueue.length;
+  }
+  get currentSequence() {
+    return this._sequence;
+  }
+  /**
+   * Records a poll request, updating last poll timestamp.
+   */
+  recordPoll() {
+    this._lastPollAt = /* @__PURE__ */ new Date();
+    this._status = "active";
+  }
+  /**
+   * Marks the client as inactive.
+   */
+  markInactive() {
+    this._status = "inactive";
+  }
+  /**
+   * Queues a message for delivery to this client.
+   */
+  queueMessage(message) {
+    this._sequence++;
+    const queuedMessage = {
+      sequence: this._sequence,
+      timestamp: /* @__PURE__ */ new Date(),
+      data: message
+    };
+    this._messageQueue.push(queuedMessage);
+    if (this._messageQueue.length > _HttpClient.MAX_QUEUE_SIZE) {
+      this._messageQueue = this._messageQueue.slice(-_HttpClient.MAX_QUEUE_SIZE);
+    }
+    return this._sequence;
+  }
+  /**
+   * Gets messages since a given sequence number.
+   * Also cleans up expired messages.
+   */
+  getMessagesSince(sinceSequence) {
+    const now = Date.now();
+    this._messageQueue = this._messageQueue.filter(
+      (msg) => now - msg.timestamp.getTime() < _HttpClient.MESSAGE_TTL_MS
+    );
+    return this._messageQueue.filter((msg) => msg.sequence > sinceSequence);
+  }
+  /**
+   * Clears messages up to a given sequence (acknowledged by client).
+   */
+  acknowledgeMessages(upToSequence) {
+    this._messageQueue = this._messageQueue.filter(
+      (msg) => msg.sequence > upToSequence
+    );
+  }
+  /**
+   * Checks if the client has timed out (no poll received within timeout period).
+   */
+  hasTimedOut(timeoutMs) {
+    const elapsed = Date.now() - this._lastPollAt.getTime();
+    return elapsed > timeoutMs;
+  }
+};
+
+// src/application/http-client-operations.ts
+var HttpClientOperationsUseCase = class {
+  workstationRegistry;
+  httpClientRegistry;
+  logger;
+  constructor(deps) {
+    this.workstationRegistry = deps.workstationRegistry;
+    this.httpClientRegistry = deps.httpClientRegistry;
+    this.logger = deps.logger.child({ useCase: "HttpClientOperations" });
+  }
+  /**
+   * Connects an HTTP polling client (watchOS).
+   * Validates auth key and registers the client.
+   */
+  connect(input) {
+    const { tunnelId: tunnelIdStr, authKey: authKeyStr, deviceId } = input;
+    this.logger.info({ tunnelId: tunnelIdStr, deviceId }, "HTTP client connect request");
+    const tunnelId = TunnelId.create(tunnelIdStr);
+    const authKey = AuthKey.create(authKeyStr);
+    const workstation = this.workstationRegistry.get(tunnelId);
+    if (!workstation) {
+      this.logger.warn({ tunnelId: tunnelIdStr, deviceId }, "Tunnel not found for HTTP client");
+      throw new TunnelNotFoundError(tunnelIdStr);
+    }
+    if (!workstation.validateAuthKey(authKey)) {
+      this.logger.warn({ tunnelId: tunnelIdStr, deviceId }, "Invalid auth key for HTTP client");
+      throw new InvalidAuthKeyError();
+    }
+    let client = this.httpClientRegistry.get(deviceId);
+    if (client) {
+      client.recordPoll();
+      this.logger.info({ deviceId, tunnelId: tunnelIdStr }, "HTTP client reconnected");
+    } else {
+      client = new HttpClient({
+        deviceId,
+        tunnelId
+      });
+      this.httpClientRegistry.register(client);
+      this.logger.info({ deviceId, tunnelId: tunnelIdStr }, "HTTP client registered");
+    }
+    return {
+      success: true,
+      tunnelId: tunnelIdStr,
+      workstationOnline: workstation.isOnline,
+      workstationName: workstation.name
+    };
+  }
+  /**
+   * Sends a command from HTTP client to workstation.
+   */
+  sendCommand(input) {
+    const { deviceId, message } = input;
+    this.logger.info({ deviceId, messageType: message.type }, "HTTP client sending command");
+    const client = this.httpClientRegistry.get(deviceId);
+    if (!client) {
+      this.logger.warn({ deviceId }, "HTTP client not found for command");
+      return false;
+    }
+    client.recordPoll();
+    const workstation = this.workstationRegistry.get(client.tunnelId);
+    if (!workstation) {
+      this.logger.warn({ deviceId, tunnelId: client.tunnelId.value }, "Workstation not found");
+      throw new TunnelNotFoundError(client.tunnelId.value);
+    }
+    if (!workstation.isOnline) {
+      this.logger.warn({ deviceId, tunnelId: client.tunnelId.value }, "Workstation offline");
+      throw new WorkstationOfflineError(client.tunnelId.value);
+    }
+    const enrichedMessage = {
+      ...message,
+      device_id: deviceId
+    };
+    const sent = workstation.send(JSON.stringify(enrichedMessage));
+    if (!sent) {
+      this.logger.warn({ deviceId }, "Failed to send command to workstation");
+    }
+    return sent;
+  }
+  /**
+   * Polls for messages for an HTTP client.
+   */
+  pollMessages(input) {
+    const { deviceId, sinceSequence, acknowledgeSequence } = input;
+    const client = this.httpClientRegistry.get(deviceId);
+    if (!client) {
+      this.logger.warn({ deviceId }, "HTTP client not found for poll");
+      return {
+        messages: [],
+        currentSequence: 0,
+        workstationOnline: false
+      };
+    }
+    client.recordPoll();
+    if (acknowledgeSequence !== void 0 && acknowledgeSequence > 0) {
+      client.acknowledgeMessages(acknowledgeSequence);
+    }
+    const messages = client.getMessagesSince(sinceSequence);
+    const workstation = this.workstationRegistry.get(client.tunnelId);
+    const workstationOnline = workstation?.isOnline ?? false;
+    this.logger.debug(
+      { deviceId, sinceSequence, messageCount: messages.length, currentSequence: client.currentSequence },
+      "HTTP client poll"
+    );
+    return {
+      messages,
+      currentSequence: client.currentSequence,
+      workstationOnline
+    };
+  }
+  /**
+   * Gets current state for an HTTP client.
+   */
+  getState(input) {
+    const { deviceId } = input;
+    const client = this.httpClientRegistry.get(deviceId);
+    if (!client) {
+      return {
+        connected: false,
+        workstationOnline: false,
+        queueSize: 0,
+        currentSequence: 0
+      };
+    }
+    client.recordPoll();
+    const workstation = this.workstationRegistry.get(client.tunnelId);
+    return {
+      connected: true,
+      workstationOnline: workstation?.isOnline ?? false,
+      workstationName: workstation?.name,
+      queueSize: client.queueSize,
+      currentSequence: client.currentSequence
+    };
+  }
+  /**
+   * Disconnects an HTTP client.
+   */
+  disconnect(deviceId) {
+    const client = this.httpClientRegistry.get(deviceId);
+    if (!client) {
+      return false;
+    }
+    client.markInactive();
+    this.httpClientRegistry.unregister(deviceId);
+    this.logger.info({ deviceId }, "HTTP client disconnected");
+    return true;
+  }
+  /**
+   * Queues a message for all HTTP clients connected to a tunnel.
+   * Called when workstation sends a message.
+   */
+  queueMessageForTunnel(tunnelId, message) {
+    const clients = this.httpClientRegistry.getByTunnelId(tunnelId);
+    let queuedCount = 0;
+    for (const client of clients) {
+      if (client.isActive) {
+        client.queueMessage(message);
+        queuedCount++;
+      }
+    }
+    if (queuedCount > 0) {
+      this.logger.debug(
+        { tunnelId: tunnelId.value, queuedCount, totalClients: clients.length },
+        "Message queued for HTTP clients"
+      );
+    }
+    return queuedCount;
+  }
+  /**
+   * Cleans up timed-out HTTP clients.
+   */
+  cleanupTimedOut(timeoutMs) {
+    const timedOut = this.httpClientRegistry.findTimedOut(timeoutMs);
+    let cleanedCount = 0;
+    for (const client of timedOut) {
+      client.markInactive();
+      this.httpClientRegistry.unregister(client.deviceId);
+      cleanedCount++;
+      this.logger.info({ deviceId: client.deviceId }, "HTTP client timed out and removed");
+    }
+    return cleanedCount;
+  }
+};
+
+// src/main.ts
+function printBanner(tunnelVersion) {
+  const dim = "\x1B[2m";
+  const blue = "\x1B[38;5;69m";
+  const purple = "\x1B[38;5;135m";
+  const white = "\x1B[97m";
+  const reset = "\x1B[0m";
+  const banner = `
+                        ${white}-#####${reset}
+                        ${white}#     #${reset}
+${blue}       -####.${reset}           ${white}#     #${reset}              ${purple}-###+.${reset}
+${blue}     .##    .${reset}        ${white}.. #     #....${reset}          ${purple}-   ##-${reset}
+${blue}    -##    #.${reset}       ${white}#####     #####+${reset}         ${purple}--    #+.${reset}
+${blue}   +#    ##-.${reset}       ${white}#              #${reset}         ${purple}.##    ##.${reset}
+${blue}   #    ##.${reset}         ${white}#              #${reset}          ${purple}.+##   +.${reset}
+${blue}   #   ##${reset}           ${white}#####     #####+${reset}            ${purple}.#   #-${reset}
+${blue}   #   +-${reset}               ${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   +-${reset}               ${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   +-${reset}       ${blue}---.${reset}    ${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   +-${reset}       ${blue}+ ###.${reset}  ${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   +-${reset}       ${blue}+    ##-${reset}${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   +-${reset}       ${blue}-##    #${reset}${white}#     #${reset}                  ${purple}#   #-${reset}
+${blue}   #   ##.${reset}      ${blue}.###    ${reset}${white}#     #.${reset}               ${purple}.+#   #.${reset}
+${blue}   #    ##+${reset}     ${blue}+    ###${reset}${white}#     #####+${reset}          ${purple}.##    #.${reset}
+${blue}   -##    ##.${reset}   ${blue}+  ##+. ${reset}${white}#          #${reset}         ${purple}-#     #+.${reset}
+${blue}    .##     .${reset}   ${blue}-##+.${reset}   ${white}+##        #${reset}         ${purple}-    ##-${reset}
+${blue}     .-##  #.${reset}            ${white}-#########+${reset}         ${purple}-+ -#+.${reset}
+
+       ${white}T I F L I S   C O D E${reset}  ${dim}\xB7${reset}  Tunnel Server
+       ${dim}Secure WebSocket Relay for Remote Agents${reset}
+
+       ${dim}v${tunnelVersion}  \xB7  \xA9 2025 Roman Barinov  \xB7  FSL-1.1-NC${reset}
+       ${dim}https://github.com/tiflis-io/tiflis-code${reset}
+`;
+  process.stdout.write(banner);
+}
+async function bootstrap() {
+  const tunnelVersion = getTunnelVersion();
+  const protocolVersion = getProtocolVersion();
+  printBanner(tunnelVersion);
+  const env = getEnv();
+  const logger = createLogger({
+    name: "tiflis-tunnel",
+    level: env.LOG_LEVEL,
+    pretty: env.NODE_ENV === "development"
+  });
+  logger.info(
+    {
+      version: tunnelVersion,
+      nodeEnv: env.NODE_ENV,
+      port: env.PORT,
+      trustProxy: env.TRUST_PROXY,
+      publicBaseUrl: env.PUBLIC_BASE_URL ?? "auto"
+    },
+    "Starting tunnel server"
+  );
+  const workstationRegistry = new InMemoryWorkstationRegistry();
+  const clientRegistry = new InMemoryClientRegistry();
+  const httpClientRegistry = new InMemoryHttpClientRegistry();
+  const registerWorkstation = new RegisterWorkstationUseCase({
+    workstationRegistry,
+    generateTunnelId: () => nanoid(12),
+    getPublicUrl: () => generatePublicUrl(env),
+    expectedApiKey: env.TUNNEL_REGISTRATION_API_KEY,
+    logger
+  });
+  const connectClient = new ConnectClientUseCase({
+    workstationRegistry,
+    clientRegistry,
+    logger
+  });
+  const forwardMessage = new ForwardMessageUseCase({
+    workstationRegistry,
+    clientRegistry,
+    httpClientRegistry,
+    logger
+  });
+  const httpClientOperations = new HttpClientOperationsUseCase({
+    workstationRegistry,
+    httpClientRegistry,
+    logger
+  });
+  const handleDisconnection = new HandleDisconnectionUseCase({
+    workstationRegistry,
+    clientRegistry,
+    httpClientRegistry,
+    forwardMessage,
+    logger
+  });
+  const connectionHandler = new ConnectionHandler({
+    workstationRegistry,
+    clientRegistry,
+    registerWorkstation,
+    connectClient,
+    forwardMessage,
+    handleDisconnection,
+    tunnelVersion,
+    protocolVersion,
+    logger
+  });
+  const app = createApp({ env, logger });
+  registerHealthRoute(
+    app,
+    { version: tunnelVersion },
+    { workstationRegistry, clientRegistry }
+  );
+  registerWatchApiRoute(app, {
+    httpClientOperations,
+    logger
+  });
+  const wsServer = new WebSocketServerWrapper(
+    {
+      path: env.WS_PATH || WEBSOCKET_CONFIG.PATH,
+      heartbeatIntervalMs: CONNECTION_TIMING.TIMEOUT_CHECK_INTERVAL_MS,
+      connectionTimeoutMs: CONNECTION_TIMING.PONG_TIMEOUT_MS
+    },
+    {
+      connectionHandler,
+      onTimeoutCheck: () => {
+        handleDisconnection.handleTimeoutCheck(
+          CONNECTION_TIMING.PONG_TIMEOUT_MS
+        );
+      },
+      logger
+    }
+  );
+  try {
+    await app.listen({ port: env.PORT, host: env.HOST });
+    wsServer.attach(app.server);
+    logger.info(
+      {
+        address: `http://${env.HOST}:${env.PORT}`,
+        wsPath: env.WS_PATH || WEBSOCKET_CONFIG.PATH
+      },
+      "\u{1F680} Tunnel server is running"
+    );
+  } catch (error) {
+    logger.fatal({ error }, "Failed to start server");
+    process.exit(1);
+  }
+  const shutdown = async (signal) => {
+    logger.info({ signal }, "Shutdown signal received");
+    try {
+      await wsServer.close();
+      await app.close();
+      logger.info("Shutdown complete");
+      process.exit(0);
+    } catch (error) {
+      logger.error({ error }, "Error during shutdown");
+      process.exit(1);
+    }
+  };
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("unhandledRejection", (reason, promise) => {
+    logger.error({ reason, promise }, "Unhandled rejection");
+  });
+  process.on("uncaughtException", (error) => {
+    logger.fatal({ error }, "Uncaught exception");
+    process.exit(1);
+  });
+}
+bootstrap().catch((error) => {
+  console.error("Failed to bootstrap:", error);
+  process.exit(1);
+});
+/**
+ * @file app.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file env.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file constants.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file version.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file pino-logger.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file in-memory-registry.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file health-route.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file domain-errors.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file watch-api-route.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file tunnel-id.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file schemas.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file errors.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file connection-handler.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file websocket-server.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file index.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file workstation.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file auth-key.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file register-workstation.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file mobile-client.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file connect-client.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file forward-message.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file handle-disconnection.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file http-client.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file http-client-operations.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */
+/**
+ * @file main.ts
+ * @copyright 2025 Roman Barinov <rbarinov@gmail.com>
+ * @license FSL-1.1-NC
+ */