@wangyaoshen/remux 0.3.8-dev.a8ceb0c

package/src/adapters/registry.ts

@@ -0,0 +1,99 @@
+// E10-003: AdapterRegistry — manages adapter registration, queries, event dispatch
+
+import { SemanticAdapter, SemanticEvent, AdapterState } from "./types.js";
+
+export class AdapterRegistry {
+  private adapters: Map<string, SemanticAdapter> = new Map();
+  private eventSeq = 0;
+  private listeners: ((event: SemanticEvent) => void)[] = [];
+
+  register(adapter: SemanticAdapter): void {
+    // Stop existing adapter with same id to prevent resource leaks
+    const existing = this.adapters.get(adapter.id);
+    if (existing) existing.stop?.();
+    this.adapters.set(adapter.id, adapter);
+    adapter.start?.();
+  }
+
+  unregister(id: string): void {
+    const adapter = this.adapters.get(id);
+    adapter?.stop?.();
+    this.adapters.delete(id);
+  }
+
+  get(id: string): SemanticAdapter | undefined {
+    return this.adapters.get(id);
+  }
+
+  getAll(): SemanticAdapter[] {
+    return Array.from(this.adapters.values());
+  }
+
+  getAllStates(): AdapterState[] {
+    return this.getAll().map((a) => a.getCurrentState());
+  }
+
+  /** Subscribe to adapter events */
+  onEvent(listener: (event: SemanticEvent) => void): () => void {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+
+  /** Emit an event from an adapter */
+  emit(adapterId: string, type: string, data: Record<string, unknown>): void {
+    const event: SemanticEvent = {
+      type,
+      seq: ++this.eventSeq,
+      timestamp: new Date().toISOString(),
+      data,
+      adapterId,
+    };
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error(`[adapter-registry] listener error:`, err);
+      }
+    }
+  }
+
+  /** Stop all adapters and clear state (for clean shutdown). */
+  shutdown(): void {
+    for (const adapter of this.adapters.values()) {
+      try { adapter.stop?.(); } catch {}
+    }
+    this.adapters.clear();
+    this.listeners = [];
+  }
+
+  /** Forward terminal data to all passive adapters */
+  dispatchTerminalData(sessionName: string, data: string): void {
+    for (const adapter of this.adapters.values()) {
+      if (adapter.mode === "passive" && adapter.onTerminalData) {
+        try {
+          adapter.onTerminalData(sessionName, data);
+        } catch (err) {
+          console.error(`[adapter:${adapter.id}] onTerminalData error:`, err);
+        }
+      }
+    }
+  }
+
+  /** Forward event file data to all passive adapters */
+  dispatchEventFile(
+    path: string,
+    event: Record<string, unknown>,
+  ): void {
+    for (const adapter of this.adapters.values()) {
+      if (adapter.mode === "passive" && adapter.onEventFile) {
+        try {
+          adapter.onEventFile(path, event);
+        } catch (err) {
+          console.error(`[adapter:${adapter.id}] onEventFile error:`, err);
+        }
+      }
+    }
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,41 @@
+// E10-001: SemanticEvent and AdapterState types
+
+export interface SemanticEvent {
+  type: string;
+  seq: number;
+  timestamp: string;
+  data: Record<string, unknown>;
+  adapterId: string;
+}
+
+export interface AdapterState {
+  adapterId: string;
+  name: string;
+  mode: "none" | "passive" | "active";
+  capabilities: string[];
+  currentState: "idle" | "running" | "waiting_approval" | "error";
+  lastEvent?: SemanticEvent;
+}
+
+// E10-002: SemanticAdapter interface
+export interface SemanticAdapter {
+  id: string;
+  name: string;
+  mode: "none" | "passive" | "active";
+  capabilities: string[];
+
+  // Passive mode: infer state from terminal data or event files
+  onTerminalData?(sessionName: string, data: string): void;
+  onEventFile?(path: string, event: Record<string, unknown>): void;
+
+  // Active mode: can initiate operations
+  createRun?(params: Record<string, unknown>): Promise<void>;
+  steerRun?(runId: string, instruction: string): Promise<void>;
+
+  // State query
+  getCurrentState(): AdapterState;
+
+  // Lifecycle
+  start?(): void;
+  stop?(): void;
+}

package/src/auth.ts

@@ -0,0 +1,174 @@
+/**
+ * Authentication module for Remux.
+ * Handles token auth, password auth, session token management,
+ * and device registration/trust.
+ */
+
+import crypto from "crypto";
+import type http from "http";
+import {
+  computeFingerprint,
+  findDeviceById,
+  findDeviceByFingerprint,
+  createDevice,
+  hasAnyDevice,
+  touchDevice,
+  type Device,
+  type TrustLevel,
+} from "./store.js";
+
+// ── State ────────────────────────────────────────────────────────
+
+// Tokens generated from password login (with TTL expiry)
+const PASSWORD_TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const passwordTokens = new Map<string, number>(); // token → expiresAt
+
+/** Periodically clean expired password tokens (every 10 minutes). */
+setInterval(() => {
+  const now = Date.now();
+  for (const [token, expiresAt] of passwordTokens) {
+    if (now >= expiresAt) passwordTokens.delete(token);
+  }
+}, 10 * 60 * 1000).unref();
+
+/** Add a password token with TTL. */
+export function addPasswordToken(token: string): void {
+  passwordTokens.set(token, Date.now() + PASSWORD_TOKEN_TTL_MS);
+}
+
+// ── CLI password parsing ─────────────────────────────────────────
+
+/**
+ * Parse --password CLI flag from process.argv.
+ */
+export function parseCliPassword(argv: string[]): string | null {
+  const idx = argv.indexOf("--password");
+  return idx !== -1 && idx + 1 < argv.length ? argv[idx + 1] : null;
+}
+
+// ── Auth config ──────────────────────────────────────────────────
+
+/**
+ * Resolve authentication configuration.
+ * Priority: REMUX_TOKEN > REMUX_PASSWORD (+ --password CLI) > auto-generated token
+ */
+export function resolveAuth(argv: string[]): {
+  TOKEN: string | null;
+  PASSWORD: string | null;
+} {
+  const PASSWORD =
+    process.env.REMUX_PASSWORD || parseCliPassword(argv) || null;
+  const TOKEN =
+    process.env.REMUX_TOKEN ||
+    (PASSWORD ? null : crypto.randomBytes(16).toString("hex"));
+  return { TOKEN, PASSWORD };
+}
+
+// ── Token generation & validation ────────────────────────────────
+
+/**
+ * Generate a cryptographically random session token (hex).
+ */
+export function generateToken(): string {
+  return crypto.randomBytes(16).toString("hex");
+}
+
+/**
+ * Validate a token against the configured TOKEN, PASSWORD-generated tokens.
+ */
+export function validateToken(
+  token: string,
+  TOKEN: string | null,
+): boolean {
+  // Timing-safe comparison to prevent side-channel attacks
+  if (TOKEN && token.length === TOKEN.length) {
+    const equal = crypto.timingSafeEqual(Buffer.from(token), Buffer.from(TOKEN));
+    if (equal) return true;
+  }
+  const entry = passwordTokens.get(token);
+  if (entry && Date.now() < entry) return true;
+  return false;
+}
+
+// ── Device registration ─────────────────────────────────────────
+
+/**
+ * Register or retrieve a device.
+ * Uses client-provided deviceId (from localStorage) when available,
+ * falling back to header-based fingerprint for legacy clients.
+ * First device ever is auto-trusted (bootstrap trust).
+ */
+export function registerDevice(
+  req: http.IncomingMessage,
+  clientDeviceId?: string,
+): { device: Device; isNew: boolean } {
+  // Prefer client-provided persistent deviceId over header fingerprint
+  if (clientDeviceId) {
+    const existing = findDeviceById(clientDeviceId);
+    if (existing) {
+      touchDevice(existing.id);
+      return { device: existing, isNew: false };
+    }
+    // New device with client-provided ID — create with that ID as fingerprint
+    const isFirst = !hasAnyDevice();
+    const trust: TrustLevel = isFirst ? "trusted" : "untrusted";
+    const device = createDevice(clientDeviceId, trust, undefined, clientDeviceId);
+    return { device, isNew: true };
+  }
+
+  // Legacy fallback: header-based fingerprint
+  const ua = req.headers["user-agent"] || "";
+  const lang = req.headers["accept-language"] || "";
+  const fingerprint = computeFingerprint(ua, lang);
+
+  const existing = findDeviceByFingerprint(fingerprint);
+  if (existing) {
+    touchDevice(existing.id);
+    return { device: existing, isNew: false };
+  }
+
+  const isFirst = !hasAnyDevice();
+  const trust: TrustLevel = isFirst ? "trusted" : "untrusted";
+  const device = createDevice(fingerprint, trust);
+  return { device, isNew: true };
+}
+
+// ── Password page HTML ──────────────────────────────────────────
+
+export const PASSWORD_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Remux \u2014 Login</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #1e1e1e; color: #ccc; height: 100vh; display: flex;
+      align-items: center; justify-content: center; }
+    .login { background: #252526; border-radius: 8px; padding: 32px; width: 320px;
+      box-shadow: 0 4px 24px rgba(0,0,0,.4); }
+    .login h1 { font-size: 18px; color: #e5e5e5; margin-bottom: 20px; text-align: center; }
+    .login input { width: 100%; padding: 10px 12px; font-size: 14px; background: #1e1e1e;
+      border: 1px solid #3a3a3a; border-radius: 4px; color: #d4d4d4;
+      font-family: inherit; outline: none; margin-bottom: 12px; }
+    .login input:focus { border-color: #007acc; }
+    .login button { width: 100%; padding: 10px; font-size: 14px; background: #007acc;
+      border: none; border-radius: 4px; color: #fff; cursor: pointer;
+      font-family: inherit; font-weight: 500; }
+    .login button:hover { background: #0098ff; }
+    .login .error { color: #f14c4c; font-size: 12px; margin-bottom: 12px; display: none; text-align: center; }
+  </style>
+</head>
+<body>
+  <form class="login" method="POST" action="/auth">
+    <h1>Remux</h1>
+    <div class="error" id="error">Incorrect password</div>
+    <input type="password" name="password" placeholder="Password" autofocus required />
+    <button type="submit">Login</button>
+  </form>
+  <script>
+    if (location.search.includes('error=1')) document.getElementById('error').style.display = 'block';
+  </script>
+</body>
+</html>`;

package/src/e2ee.ts

@@ -0,0 +1,236 @@
+/**
+ * E2EE encryption layer for Remux WebSocket messages.
+ * Uses X25519 key exchange + HKDF-SHA256 key derivation + AES-256-GCM encryption.
+ *
+ * Design references:
+ * - Signal Protocol (X25519 + AES-GCM): https://signal.org/docs/specifications/x3dh/
+ * - Mosh: AES-128-OCB transport encryption with sequence numbers
+ * - Node.js crypto docs: https://nodejs.org/api/crypto.html
+ */
+
+import crypto from "crypto";
+
+// ── Constants ──────────────────────────────────────────────────────
+
+const HKDF_SALT = "remux-e2ee-v1";
+const HKDF_INFO = "aes-256-gcm";
+const AES_KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 12; // 96 bits for GCM
+const IV_PREFIX_LENGTH = 4; // fixed prefix bytes in IV
+const IV_COUNTER_LENGTH = 8; // counter bytes in IV
+const AUTH_TAG_LENGTH = 16; // 128 bits
+
+// ── Key pair generation ────────────────────────────────────────────
+
+/**
+ * Generate an X25519 key pair for ECDH key exchange.
+ * Returns raw 32-byte public and private key buffers.
+ */
+export function generateKeyPair(): { publicKey: Buffer; privateKey: Buffer } {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("x25519", {
+    publicKeyEncoding: { type: "spki", format: "der" },
+    privateKeyEncoding: { type: "pkcs8", format: "der" },
+  });
+
+  // X25519 DER-encoded SPKI public key: 12-byte header + 32-byte raw key
+  // X25519 DER-encoded PKCS8 private key: 16-byte header + 32-byte raw key
+  const rawPublic = publicKey.subarray(publicKey.length - 32);
+  const rawPrivate = privateKey.subarray(privateKey.length - 32);
+
+  return {
+    publicKey: Buffer.from(rawPublic),
+    privateKey: Buffer.from(rawPrivate),
+  };
+}
+
+// ── Shared secret derivation ───────────────────────────────────────
+
+/**
+ * Derive a shared AES-256-GCM key from our private key and the peer's public key.
+ * Uses X25519 ECDH followed by HKDF-SHA256 key derivation.
+ */
+export function deriveSharedSecret(
+  privateKey: Buffer,
+  peerPublicKey: Buffer,
+): Buffer {
+  // Reconstruct CryptoKey objects from raw buffers
+  const privKeyObj = crypto.createPrivateKey({
+    key: buildPkcs8(privateKey),
+    format: "der",
+    type: "pkcs8",
+  });
+
+  const pubKeyObj = crypto.createPublicKey({
+    key: buildSpki(peerPublicKey),
+    format: "der",
+    type: "spki",
+  });
+
+  // X25519 ECDH to get raw shared secret
+  const rawSecret = crypto.diffieHellman({
+    privateKey: privKeyObj,
+    publicKey: pubKeyObj,
+  });
+
+  // HKDF-SHA256 to derive the final 256-bit AES key
+  const salt = Buffer.from(HKDF_SALT, "utf8");
+  const info = Buffer.from(HKDF_INFO, "utf8");
+  const derived = crypto.hkdfSync("sha256", rawSecret, salt, info, AES_KEY_LENGTH);
+
+  return Buffer.from(derived);
+}
+
+/**
+ * Build a DER-encoded PKCS8 wrapper around a raw 32-byte X25519 private key.
+ */
+function buildPkcs8(rawKey: Buffer): Buffer {
+  // PKCS8 header for X25519: 302e020100300506032b656e042204 20
+  const header = Buffer.from(
+    "302e020100300506032b656e04220420",
+    "hex",
+  );
+  return Buffer.concat([header, rawKey]);
+}
+
+/**
+ * Build a DER-encoded SPKI wrapper around a raw 32-byte X25519 public key.
+ */
+function buildSpki(rawKey: Buffer): Buffer {
+  // SPKI header for X25519: 302a300506032b656e032100
+  const header = Buffer.from("302a300506032b656e032100", "hex");
+  return Buffer.concat([header, rawKey]);
+}
+
+// ── Encrypt / Decrypt ──────────────────────────────────────────────
+
+/**
+ * Encrypt a plaintext buffer using AES-256-GCM.
+ *
+ * IV construction: 4 bytes fixed random prefix + 8 bytes counter (big-endian).
+ * This ensures unique IVs per message while the counter provides ordering.
+ */
+export function encrypt(
+  key: Buffer,
+  plaintext: Buffer,
+  counter: bigint,
+): { ciphertext: Buffer; tag: Buffer; iv: Buffer } {
+  // Build IV: 4 bytes random prefix + 8 bytes counter (big-endian)
+  const iv = Buffer.alloc(IV_LENGTH);
+  crypto.randomFillSync(iv, 0, IV_PREFIX_LENGTH);
+  iv.writeBigUInt64BE(counter, IV_PREFIX_LENGTH);
+
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return { ciphertext: encrypted, tag, iv };
+}
+
+/**
+ * Decrypt a ciphertext buffer using AES-256-GCM.
+ * Verifies the auth tag; throws on tampered data.
+ */
+export function decrypt(
+  key: Buffer,
+  ciphertext: Buffer,
+  tag: Buffer,
+  iv: Buffer,
+): Buffer {
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+// ── E2EESession ────────────────────────────────────────────────────
+
+/**
+ * Manages an E2EE session for a single WebSocket connection.
+ * Handles key exchange, counter management, and anti-replay protection.
+ */
+export class E2EESession {
+  private sharedKey: Buffer | null = null;
+  private sendCounter: bigint = 0n;
+  private recvCounter: bigint = -1n; // last received counter; -1 means none yet
+  private localKeyPair: { publicKey: Buffer; privateKey: Buffer };
+
+  constructor() {
+    this.localKeyPair = generateKeyPair();
+  }
+
+  /** Get our public key as a base64-encoded string for transmission. */
+  getPublicKey(): string {
+    return this.localKeyPair.publicKey.toString("base64");
+  }
+
+  /**
+   * Complete the ECDH handshake with the peer's base64-encoded public key.
+   * After this, encrypt/decrypt operations become available.
+   */
+  completeHandshake(peerPublicKeyB64: string): void {
+    const peerPublicKey = Buffer.from(peerPublicKeyB64, "base64");
+    this.sharedKey = deriveSharedSecret(
+      this.localKeyPair.privateKey,
+      peerPublicKey,
+    );
+  }
+
+  /**
+   * Encrypt a plaintext string for sending.
+   * Returns a base64-encoded string containing: iv (12) + ciphertext (variable) + tag (16).
+   * Increments the send counter after each call.
+   */
+  encryptMessage(plaintext: string): string {
+    if (!this.sharedKey) {
+      throw new Error("E2EE handshake not completed");
+    }
+
+    const plaintextBuf = Buffer.from(plaintext, "utf8");
+    const { ciphertext, tag, iv } = encrypt(
+      this.sharedKey,
+      plaintextBuf,
+      this.sendCounter,
+    );
+    this.sendCounter++;
+
+    // Pack: iv (12) + ciphertext (N) + tag (16)
+    const packed = Buffer.concat([iv, ciphertext, tag]);
+    return packed.toString("base64");
+  }
+
+  /**
+   * Decrypt a base64-encoded encrypted message.
+   * Validates that the counter is monotonically increasing (anti-replay).
+   */
+  decryptMessage(encrypted: string): string {
+    if (!this.sharedKey) {
+      throw new Error("E2EE handshake not completed");
+    }
+
+    const packed = Buffer.from(encrypted, "base64");
+
+    // Unpack: iv (12) + ciphertext (N) + tag (16)
+    if (packed.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+      throw new Error("E2EE message too short");
+    }
+
+    const iv = packed.subarray(0, IV_LENGTH);
+    const ciphertext = packed.subarray(IV_LENGTH, packed.length - AUTH_TAG_LENGTH);
+    const tag = packed.subarray(packed.length - AUTH_TAG_LENGTH);
+
+    // Extract counter from IV for anti-replay check
+    const counter = iv.readBigUInt64BE(IV_PREFIX_LENGTH);
+    if (counter <= this.recvCounter) {
+      throw new Error("E2EE replay detected: counter not monotonically increasing");
+    }
+
+    const decrypted = decrypt(this.sharedKey, ciphertext, tag, iv);
+    this.recvCounter = counter;
+
+    return decrypted.toString("utf8");
+  }
+
+  /** Whether the handshake has been completed and encryption is available. */
+  isEstablished(): boolean {
+    return this.sharedKey !== null;
+  }
+}