gitspace 0.2.0-rc.1

package/src/relay/__tests__/helpers/auth.ts

@@ -0,0 +1,354 @@
+/**
+ * Test authentication helpers for relay tests
+ *
+ * Provides utilities for Ed25519 challenge-response authentication
+ * used by the relay server.
+ */
+
+import { ed25519 } from "@noble/curves/ed25519.js";
+import type { Server } from "bun";
+import type { Identity } from "../../../types/identity.js";
+import type { RelayIdentity } from "../../identity.js";
+import type { WebSocketData } from "../../types.js";
+import { generateRelayIdentity } from "../../identity.js";
+import { createRelayServer } from "../../server.js";
+import { signMessage, type SignatureBlock } from "../../signing.js";
+import { toPublicIdentity } from "../../../lib/tmux-lite/crypto/__tests__/helpers/test-identities.js";
+
+// ============================================================================
+// Challenge-Response Authentication
+// ============================================================================
+
+/**
+ * Sign a challenge nonce for machine authentication
+ *
+ * The relay sends a random nonce in the relay_identity message.
+ * The machine must sign this nonce with its Ed25519 private key.
+ *
+ * @param nonce - The challenge nonce bytes (from relay_identity.challenge, base64 decoded)
+ * @param signingSecretKey - The machine's Ed25519 secret key (64 bytes: private + public)
+ * @returns Base64-encoded signature
+ */
+export function signChallenge(
+  nonce: Uint8Array,
+  signingSecretKey: Uint8Array
+): string {
+  // Ed25519 secretKey is 64 bytes (32 private + 32 public), use first 32 for signing
+  // Note: noble ed25519.sign expects 32-byte private key
+  const privateKey = signingSecretKey.slice(0, 32);
+  const signature = ed25519.sign(nonce, privateKey);
+  return Buffer.from(signature).toString("base64");
+}
+
+/**
+ * Get base64-encoded signing key from identity
+ *
+ * Used to build the preAuthorizedMachines set for createRelayServer.
+ *
+ * @param identity - Machine identity
+ * @returns Base64-encoded signing public key
+ */
+export function getSigningKeyBase64(identity: Identity): string {
+  return Buffer.from(identity.signing.publicKey).toString("base64");
+}
+
+export function signClientMessage<T extends object>(
+  message: T,
+  identity: Identity
+): T & { signature: SignatureBlock } {
+  const privateKey = identity.signing.secretKey.slice(0, 32);
+  return signMessage(message, privateKey, identity.signing.publicKey);
+}
+
+// ============================================================================
+// Machine Connection with Authentication
+// ============================================================================
+
+/**
+ * Connect a machine to the relay and complete challenge-response authentication
+ *
+ * This handles the full authentication flow:
+ * 1. Connect to /ws?role=machine
+ * 2. Receive relay_identity with challenge nonce
+ * 3. Sign nonce with machine's private key
+ * 4. Send register_machine with challengeResponse
+ * 5. Wait for "registered" confirmation
+ *
+ * @param relayUrl - WebSocket URL (e.g., "ws://localhost:3099/ws")
+ * @param identity - Machine identity
+ * @param options - Optional configuration
+ * @returns Connected and authenticated WebSocket
+ */
+export async function connectMachineWithAuth(
+  relayUrl: string,
+  identity: Identity,
+  options?: {
+    label?: string;
+    timeoutMs?: number;
+  }
+): Promise<WebSocket> {
+  const { label = identity.label, timeoutMs = 5000 } = options ?? {};
+
+  // Connect without token (new auth flow)
+  const url = new URL(relayUrl);
+  url.searchParams.set("role", "machine");
+
+  const ws = new WebSocket(url.toString());
+  ws.binaryType = "arraybuffer";
+
+  // Wait for connection
+  await new Promise<void>((resolve, reject) => {
+    ws.onopen = () => resolve();
+    ws.onerror = () => reject(new Error("Machine WebSocket connection failed"));
+    setTimeout(() => reject(new Error("Connection timeout")), timeoutMs);
+  });
+
+  // Wait for relay_identity with challenge
+  const challenge = await new Promise<Uint8Array>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error("Challenge timeout")), timeoutMs);
+    ws.onmessage = (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.type === "relay_identity" && msg.challenge) {
+          clearTimeout(timeout);
+          resolve(Buffer.from(msg.challenge, "base64"));
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    };
+  });
+
+  // Sign challenge and send register_machine
+  const signature = signChallenge(challenge, identity.signing.secretKey);
+  const publicIdentity = toPublicIdentity(identity);
+
+  ws.send(JSON.stringify({
+    type: "register_machine",
+    machineId: identity.id,
+    signingKey: publicIdentity.signingPublicKey,
+    keyExchangeKey: publicIdentity.keyExchangePublicKey,
+    challengeResponse: signature,
+    label,
+  }));
+
+  // Wait for registration confirmation
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error("Registration timeout")), timeoutMs);
+    ws.onmessage = (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.type === "registered") {
+          clearTimeout(timeout);
+          resolve();
+        } else if (msg.type === "error") {
+          clearTimeout(timeout);
+          reject(new Error(msg.message || "Registration failed"));
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    };
+  });
+
+  return ws;
+}
+
+/**
+ * Connect a machine and wait for the first relay_identity message
+ * without completing authentication.
+ *
+ * Useful for tests that need to inspect the challenge or test failure cases.
+ *
+ * @param relayUrl - WebSocket URL
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns WebSocket and challenge details
+ */
+export async function connectMachineAndGetChallenge(
+  relayUrl: string,
+  timeoutMs = 5000
+): Promise<{
+  ws: WebSocket;
+  challenge: Uint8Array;
+  relayPublicKey: string;
+  relayFingerprint: string;
+}> {
+  const url = new URL(relayUrl);
+  url.searchParams.set("role", "machine");
+
+  const ws = new WebSocket(url.toString());
+  ws.binaryType = "arraybuffer";
+
+  await new Promise<void>((resolve, reject) => {
+    ws.onopen = () => resolve();
+    ws.onerror = () => reject(new Error("Connection failed"));
+    setTimeout(() => reject(new Error("Connection timeout")), timeoutMs);
+  });
+
+  const relayIdentity = await new Promise<{
+    challenge: Uint8Array;
+    publicKey: string;
+    fingerprint: string;
+  }>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error("Challenge timeout")), timeoutMs);
+    ws.onmessage = (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.type === "relay_identity") {
+          clearTimeout(timeout);
+          resolve({
+            challenge: Buffer.from(msg.challenge, "base64"),
+            publicKey: msg.publicKey,
+            fingerprint: msg.fingerprint,
+          });
+        }
+      } catch {
+        // Ignore
+      }
+    };
+  });
+
+  return {
+    ws,
+    challenge: relayIdentity.challenge,
+    relayPublicKey: relayIdentity.publicKey,
+    relayFingerprint: relayIdentity.fingerprint,
+  };
+}
+
+// ============================================================================
+// Client Connection (no auth needed at relay level)
+// ============================================================================
+
+/**
+ * Connect a client to the relay
+ *
+ * Clients no longer need tokens - auth happens via X3DH handshake with machine.
+ *
+ * @param relayUrl - WebSocket URL
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Connected WebSocket
+ */
+export async function connectClient(
+  relayUrl: string,
+  timeoutMs = 5000
+): Promise<WebSocket> {
+  const url = new URL(relayUrl);
+  url.searchParams.set("role", "client");
+
+  const ws = new WebSocket(url.toString());
+  ws.binaryType = "arraybuffer";
+
+  await new Promise<void>((resolve, reject) => {
+    ws.onopen = () => resolve();
+    ws.onerror = () => reject(new Error("Client WebSocket connection failed"));
+    setTimeout(() => reject(new Error("Connection timeout")), timeoutMs);
+  });
+
+  return ws;
+}
+
+// ============================================================================
+// Test Server Creation
+// ============================================================================
+
+/**
+ * Create a test relay server with pre-authorized machines
+ *
+ * @param port - Port to listen on
+ * @param preAuthorizedMachines - Machine identities to pre-authorize
+ * @param options - Additional server options
+ * @returns Relay server instance
+ */
+export function createTestRelayServer(
+  port: number,
+  preAuthorizedMachines: Identity[],
+  options?: {
+    hostname?: string;
+    label?: string;
+  }
+): { server: Server<WebSocketData>; relayIdentity: RelayIdentity } {
+  const { hostname = "localhost", label = "test-relay" } = options ?? {};
+
+  const relayIdentity = generateRelayIdentity(label);
+
+  const preAuthSet = new Set(
+    preAuthorizedMachines.map((id) => getSigningKeyBase64(id))
+  );
+
+  const server = createRelayServer({
+    port,
+    hostname,
+    identity: relayIdentity,
+    preAuthorizedMachines: preAuthSet,
+  });
+
+  return { server, relayIdentity };
+}
+
+// ============================================================================
+// Message Helpers
+// ============================================================================
+
+/**
+ * Wait for a specific message type on a WebSocket
+ *
+ * @param ws - WebSocket to listen on
+ * @param messageType - Message type to wait for
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Parsed message
+ */
+export async function waitForMessage<T = unknown>(
+  ws: WebSocket,
+  messageType: string,
+  timeoutMs = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error(`Timeout waiting for ${messageType}`));
+    }, timeoutMs);
+
+    const handler = (event: MessageEvent) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.type === messageType) {
+          clearTimeout(timeout);
+          ws.removeEventListener("message", handler);
+          resolve(msg as T);
+        } else if (msg.type === "error") {
+          clearTimeout(timeout);
+          ws.removeEventListener("message", handler);
+          reject(new Error(msg.message || `Error while waiting for ${messageType}`));
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    };
+
+    ws.addEventListener("message", handler);
+  });
+}
+
+/**
+ * Send a message and wait for response
+ *
+ * @param ws - WebSocket to use
+ * @param message - Message to send
+ * @param expectedResponseType - Expected response type
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Response message
+ */
+export async function sendAndWait<T = unknown>(
+  ws: WebSocket,
+  message: object,
+  expectedResponseType: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const responsePromise = waitForMessage<T>(ws, expectedResponseType, timeoutMs);
+  ws.send(JSON.stringify(message));
+  return responsePromise;
+}

package/src/relay/__tests__/helpers/ports.ts

@@ -0,0 +1,51 @@
+import { randomBytes } from "crypto";
+import { createRelayServer } from "../../server";
+
+type RelayServerConfig = Parameters<typeof createRelayServer>[0];
+
+const DEFAULT_PORT_RANGE: [number, number] = [20000, 60000];
+const DEFAULT_MAX_ATTEMPTS = 25;
+
+function pickRandomPort([min, max]: [number, number]): number {
+  const range = max - min + 1;
+  const randomValue = randomBytes(4).readUInt32BE(0);
+  return min + (randomValue % range);
+}
+
+function isPortInUseError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /EADDRINUSE/i.test(message) || /port .* in use/i.test(message);
+}
+
+export function startRelayServer(
+  config: Omit<RelayServerConfig, "port"> & {
+    port?: number;
+    portRange?: [number, number];
+    maxAttempts?: number;
+  }
+) {
+  const {
+    port,
+    portRange = DEFAULT_PORT_RANGE,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    ...rest
+  } = config;
+
+  if (typeof port === "number") {
+    return createRelayServer({ ...rest, port });
+  }
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const candidate = pickRandomPort(portRange);
+    try {
+      return createRelayServer({ ...rest, port: candidate });
+    } catch (error) {
+      if (isPortInUseError(error)) {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error("Failed to allocate relay port for tests");
+}

package/src/relay/__tests__/protocol-validation.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Protocol Validation Tests
+ *
+ * Tests message parsing and validation for the relay protocol.
+ * Focuses on edge cases and error conditions discovered in production.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  parseMessage,
+  isValidIdentifier,
+  isValidBase64,
+} from "../protocol";
+
+describe("parseMessage", () => {
+  describe("authorize_client validation", () => {
+    const validAuthorizeClient = {
+      type: "authorize_client",
+      machineId: "R0lENwJ57_naVQ3h",
+      clientIdentityId: "vyPe20Hv1pnlKo89",
+      signingKey: "vyPe20Hv1pnlKo89BOvn5XuJzPXarq5/hjim96fZ/dM=",
+      keyExchangeKey: "/NOCKBrpy+5hST69/NF2rXutunFakeKey123456789=",
+      accessType: "full",
+    };
+
+    test("parses valid authorize_client message", () => {
+      const result = parseMessage(JSON.stringify(validAuthorizeClient));
+      expect(result).not.toBeNull();
+      expect(result?.type).toBe("authorize_client");
+    });
+
+    test("rejects message with undefined accessType", () => {
+      const msg = { ...validAuthorizeClient };
+      delete (msg as any).accessType;
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("rejects message with null accessType", () => {
+      const msg = { ...validAuthorizeClient, accessType: null };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("rejects message with invalid accessType string", () => {
+      const msg = { ...validAuthorizeClient, accessType: "admin" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("accepts accessType 'full'", () => {
+      const msg = { ...validAuthorizeClient, accessType: "full" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("accepts accessType 'session-invite'", () => {
+      const msg = { ...validAuthorizeClient, accessType: "session-invite" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("rejects message with empty signingKey", () => {
+      const msg = { ...validAuthorizeClient, signingKey: "" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("rejects message with empty keyExchangeKey", () => {
+      const msg = { ...validAuthorizeClient, keyExchangeKey: "" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("rejects message with empty clientIdentityId", () => {
+      const msg = { ...validAuthorizeClient, clientIdentityId: "" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("rejects message with empty machineId", () => {
+      const msg = { ...validAuthorizeClient, machineId: "" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("accepts message with valid sessionId", () => {
+      const msg = { ...validAuthorizeClient, sessionId: "session-123" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("rejects message with invalid sessionId characters", () => {
+      const msg = { ...validAuthorizeClient, sessionId: "session with spaces" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+
+    test("accepts message without sessionId (undefined)", () => {
+      const msg = { ...validAuthorizeClient };
+      delete (msg as any).sessionId;
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+  });
+
+  describe("register_machine validation", () => {
+    const validRegisterMachine = {
+      type: "register_machine",
+      machineId: "R0lENwJ57_naVQ3h",
+      signingKey: "vyPe20Hv1pnlKo89BOvn5XuJzPXarq5/hjim96fZ/dM=",
+      keyExchangeKey: "/NOCKBrpy+5hST69/NF2rXutunFakeKey123456789=",
+    };
+
+    test("parses valid register_machine message", () => {
+      const result = parseMessage(JSON.stringify(validRegisterMachine));
+      expect(result).not.toBeNull();
+      expect(result?.type).toBe("register_machine");
+    });
+
+    test("accepts message with optional label", () => {
+      const msg = { ...validRegisterMachine, label: "My Machine" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("accepts message with optional challengeResponse", () => {
+      const msg = { ...validRegisterMachine, challengeResponse: "base64signature==" };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("rejects message with missing machineId", () => {
+      const msg = { ...validRegisterMachine };
+      delete (msg as any).machineId;
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("data message validation", () => {
+    test("parses machine data message with connectionId", () => {
+      const msg = {
+        type: "data",
+        connectionId: "abc123def456",
+        data: "SGVsbG8gV29ybGQ=", // base64 "Hello World"
+      };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+      expect(result?.type).toBe("data");
+    });
+
+    test("parses client data message without connectionId", () => {
+      const msg = {
+        type: "data",
+        data: "SGVsbG8gV29ybGQ=",
+      };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).not.toBeNull();
+    });
+
+    test("rejects data message with empty data", () => {
+      const msg = {
+        type: "data",
+        data: "",
+      };
+      const result = parseMessage(JSON.stringify(msg));
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("error handling", () => {
+    test("returns null for invalid JSON", () => {
+      const result = parseMessage("not valid json");
+      expect(result).toBeNull();
+    });
+
+    test("returns null for empty string", () => {
+      const result = parseMessage("");
+      expect(result).toBeNull();
+    });
+
+    test("returns null for message without type", () => {
+      const result = parseMessage(JSON.stringify({ foo: "bar" }));
+      expect(result).toBeNull();
+    });
+
+    test("returns null for unknown message type", () => {
+      const result = parseMessage(JSON.stringify({ type: "unknown_type" }));
+      expect(result).toBeNull();
+    });
+
+    test("returns null for message exceeding size limit", () => {
+      const hugeData = "x".repeat(2 * 1024 * 1024); // 2MB
+      const result = parseMessage(hugeData);
+      expect(result).toBeNull();
+    });
+  });
+});
+
+describe("isValidIdentifier", () => {
+  test("accepts alphanumeric identifiers", () => {
+    expect(isValidIdentifier("abc123")).toBe(true);
+    expect(isValidIdentifier("ABC123")).toBe(true);
+  });
+
+  test("accepts identifiers with allowed special chars", () => {
+    expect(isValidIdentifier("machine-1")).toBe(true);
+    expect(isValidIdentifier("machine_1")).toBe(true);
+    expect(isValidIdentifier("machine.local")).toBe(true);
+    expect(isValidIdentifier("client:xyz")).toBe(true);
+    expect(isValidIdentifier("key+value")).toBe(true);
+    expect(isValidIdentifier("base64/chars")).toBe(true);
+    expect(isValidIdentifier("equals=sign")).toBe(true);
+  });
+
+  test("rejects empty string", () => {
+    expect(isValidIdentifier("")).toBe(false);
+  });
+
+  test("rejects identifiers with spaces", () => {
+    expect(isValidIdentifier("has space")).toBe(false);
+  });
+
+  test("rejects identifiers with control characters", () => {
+    expect(isValidIdentifier("has\nnewline")).toBe(false);
+    expect(isValidIdentifier("has\ttab")).toBe(false);
+  });
+
+  test("rejects very long identifiers", () => {
+    const longId = "x".repeat(500);
+    expect(isValidIdentifier(longId)).toBe(false);
+  });
+
+  test("rejects non-string values", () => {
+    expect(isValidIdentifier(123 as any)).toBe(false);
+    expect(isValidIdentifier(null as any)).toBe(false);
+    expect(isValidIdentifier(undefined as any)).toBe(false);
+  });
+});
+
+describe("isValidBase64", () => {
+  test("accepts valid base64 strings", () => {
+    expect(isValidBase64("SGVsbG8gV29ybGQ=")).toBe(true);
+    expect(isValidBase64("YWJjMTIz")).toBe(true);
+  });
+
+  test("accepts base64url strings", () => {
+    expect(isValidBase64("abc-def_ghi")).toBe(true);
+  });
+
+  test("rejects empty string", () => {
+    expect(isValidBase64("")).toBe(false);
+  });
+
+  test("rejects strings with invalid characters", () => {
+    expect(isValidBase64("has space")).toBe(false);
+    expect(isValidBase64("has\nnewline")).toBe(false);
+  });
+
+  test("rejects very long strings", () => {
+    const longData = "x".repeat(2 * 1024 * 1024);
+    expect(isValidBase64(longData)).toBe(false);
+  });
+});