@pi-chamber/web 0.1.8

package/server/lib/server/tunnel-auth.js

@@ -0,0 +1,586 @@
+import crypto from 'crypto';
+
+const BOOTSTRAP_TOKEN_COOKIE_SAFE_BYTES = 32;
+const TUNNEL_SESSION_COOKIE_NAME = 'oc_tunnel_session';
+
+const CONNECT_RATE_LIMIT_WINDOW_MS = 5 * 60 * 1000;
+const CONNECT_RATE_LIMIT_LOCK_MS = 10 * 60 * 1000;
+const CONNECT_RATE_LIMIT_MAX_ATTEMPTS = 20;
+const CONNECT_RATE_LIMIT_NO_IP_MAX_ATTEMPTS = 5;
+
+const parseCookies = (cookieHeader) => {
+  if (!cookieHeader || typeof cookieHeader !== 'string') {
+    return {};
+  }
+
+  return cookieHeader.split(';').reduce((acc, segment) => {
+    const [name, ...rest] = segment.split('=');
+    if (!name) {
+      return acc;
+    }
+    const key = name.trim();
+    if (!key) {
+      return acc;
+    }
+    const value = rest.join('=').trim();
+    acc[key] = decodeURIComponent(value || '');
+    return acc;
+  }, {});
+};
+
+const isSecureRequest = (req) => {
+  if (req.secure) {
+    return true;
+  }
+  const forwardedProto = req.headers['x-forwarded-proto'];
+  if (typeof forwardedProto === 'string') {
+    const firstProto = forwardedProto.split(',')[0]?.trim().toLowerCase();
+    return firstProto === 'https';
+  }
+  return false;
+};
+
+const buildCookie = ({ name, value, maxAge, secure }) => {
+  const attributes = [
+    `${name}=${value}`,
+    'Path=/',
+    'HttpOnly',
+    'SameSite=Lax',
+  ];
+
+  if (typeof maxAge === 'number') {
+    attributes.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);
+  }
+
+  const expires = maxAge === 0
+    ? 'Thu, 01 Jan 1970 00:00:00 GMT'
+    : new Date(Date.now() + maxAge * 1000).toUTCString();
+
+  attributes.push(`Expires=${expires}`);
+
+  if (secure) {
+    attributes.push('Secure');
+  }
+
+  return attributes.join('; ');
+};
+
+const nowTs = () => Date.now();
+
+const hashToken = (token) => crypto.createHash('sha256').update(token).digest('hex');
+
+const normalizeHost = (candidate) => {
+  if (typeof candidate !== 'string') {
+    return null;
+  }
+  const trimmed = candidate.trim().toLowerCase();
+  if (!trimmed) {
+    return null;
+  }
+  return trimmed.replace(/:\d+$/, '');
+};
+
+const normalizeIpCandidate = (candidate) => {
+  if (typeof candidate !== 'string') {
+    return null;
+  }
+
+  const trimmed = candidate.trim().toLowerCase();
+  if (!trimmed) {
+    return null;
+  }
+
+  const withoutBrackets = trimmed.startsWith('[') && trimmed.endsWith(']')
+    ? trimmed.slice(1, -1)
+    : trimmed;
+
+  const withoutZone = withoutBrackets.split('%')[0];
+  if (!withoutZone) {
+    return null;
+  }
+
+  if (withoutZone.startsWith('::ffff:')) {
+    const mappedIpv4 = withoutZone.slice('::ffff:'.length);
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(mappedIpv4)) {
+      return mappedIpv4;
+    }
+  }
+
+  return withoutZone;
+};
+
+const getSocketRemoteIp = (req) => {
+  const remoteAddress = req?.socket?.remoteAddress || req?.connection?.remoteAddress;
+  return normalizeIpCandidate(remoteAddress);
+};
+
+const isPrivateOrLoopbackIpv4 = (candidate) => {
+  const octets = candidate.split('.').map((part) => Number(part));
+  if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+
+  const [first, second] = octets;
+  if (first === 127) {
+    return true;
+  }
+  if (first === 10) {
+    return true;
+  }
+  if (first === 172 && second >= 16 && second <= 31) {
+    return true;
+  }
+  if (first === 192 && second === 168) {
+    return true;
+  }
+  if (first === 169 && second === 254) {
+    return true;
+  }
+  return false;
+};
+
+const isPrivateOrLoopbackIpv6 = (candidate) => {
+  if (candidate === '::1') {
+    return true;
+  }
+
+  if (candidate.startsWith('fc') || candidate.startsWith('fd')) {
+    return true;
+  }
+
+  return candidate.startsWith('fe8')
+    || candidate.startsWith('fe9')
+    || candidate.startsWith('fea')
+    || candidate.startsWith('feb');
+};
+
+const isPrivateOrLoopbackIp = (candidate) => {
+  const normalized = normalizeIpCandidate(candidate);
+  if (!normalized) {
+    return false;
+  }
+
+  if (normalized.includes(':')) {
+    return isPrivateOrLoopbackIpv6(normalized);
+  }
+
+  return isPrivateOrLoopbackIpv4(normalized);
+};
+
+const isLocalHost = (host, req) => {
+  if (!host) {
+    return false;
+  }
+
+  const isLocalHostname = host === 'localhost'
+    || host === 'host.docker.internal'
+    || isPrivateOrLoopbackIp(host);
+  return isLocalHostname && isPrivateOrLoopbackIp(getSocketRemoteIp(req));
+};
+
+const getClientIp = (req) => {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (typeof forwarded === 'string') {
+    const ip = forwarded.split(',')[0].trim();
+    if (ip.startsWith('::ffff:')) {
+      return ip.substring(7);
+    }
+    return ip;
+  }
+
+  const ip = req.ip || req.connection?.remoteAddress;
+  if (ip) {
+    if (ip.startsWith('::ffff:')) {
+      return ip.substring(7);
+    }
+    return ip;
+  }
+  return null;
+};
+
+const getRateLimitKey = (req) => {
+  const ip = getClientIp(req);
+  if (ip) {
+    return ip;
+  }
+  return 'connect-rate-limit:no-ip';
+};
+
+const rateLimitMaxForKey = (key) => {
+  if (key === 'connect-rate-limit:no-ip') {
+    return CONNECT_RATE_LIMIT_NO_IP_MAX_ATTEMPTS;
+  }
+  return CONNECT_RATE_LIMIT_MAX_ATTEMPTS;
+};
+
+export const createTunnelAuth = () => {
+  let activeTunnelId = null;
+  let activeTunnelHost = null;
+  let activeTunnelMode = null;
+  let activeTunnelPublicUrl = null;
+  let bootstrapRecord = null;
+
+  const tunnelSessions = new Map();
+  const connectRateLimiter = new Map();
+
+  const clearTunnelSessionCookie = (req, res) => {
+    const secure = isSecureRequest(req);
+    const header = buildCookie({
+      name: TUNNEL_SESSION_COOKIE_NAME,
+      value: '',
+      maxAge: 0,
+      secure,
+    });
+    res.setHeader('Set-Cookie', header);
+  };
+
+  const setTunnelSessionCookie = (req, res, sessionId, ttlMs) => {
+    const secure = isSecureRequest(req);
+    const maxAge = Math.max(0, Math.floor(ttlMs / 1000));
+    const header = buildCookie({
+      name: TUNNEL_SESSION_COOKIE_NAME,
+      value: encodeURIComponent(sessionId),
+      maxAge,
+      secure,
+    });
+    res.setHeader('Set-Cookie', header);
+  };
+
+  const classifyRequestScope = (req) => {
+    const hostHeader = normalizeHost(typeof req.headers.host === 'string' ? req.headers.host : '');
+    const reqHost = normalizeHost(typeof req.hostname === 'string' ? req.hostname : '') || hostHeader;
+
+    if (activeTunnelHost && reqHost === activeTunnelHost) {
+      return 'tunnel';
+    }
+
+    if (isLocalHost(reqHost, req)) {
+      return 'local';
+    }
+
+    if (!activeTunnelId) {
+      return 'local';
+    }
+
+    return 'unknown-public';
+  };
+
+  const revokeBootstrapToken = () => {
+    if (!bootstrapRecord) {
+      return 0;
+    }
+    if (bootstrapRecord.revokedAt) {
+      return 0;
+    }
+    if (!bootstrapRecord.revokedAt) {
+      bootstrapRecord.revokedAt = nowTs();
+    }
+    return 1;
+  };
+
+  const invalidateTunnelSessions = (tunnelId, reason = 'tunnel-stopped') => {
+    const revokedAt = nowTs();
+    let count = 0;
+    for (const record of tunnelSessions.values()) {
+      if (record.tunnelId === tunnelId && !record.revokedAt) {
+        record.revokedAt = revokedAt;
+        record.revokedReason = reason;
+        count += 1;
+      }
+    }
+    return count;
+  };
+
+  const revokeTunnelArtifacts = (tunnelId) => {
+    const revokedBootstrapCount = bootstrapRecord && bootstrapRecord.tunnelId === tunnelId
+      ? revokeBootstrapToken()
+      : 0;
+    const invalidatedSessionCount = invalidateTunnelSessions(tunnelId, 'tunnel-revoked');
+    return { revokedBootstrapCount, invalidatedSessionCount };
+  };
+
+  const setActiveTunnel = ({ tunnelId, publicUrl, mode = null }) => {
+    activeTunnelId = tunnelId;
+    activeTunnelMode = mode;
+    activeTunnelPublicUrl = publicUrl || null;
+    try {
+      activeTunnelHost = normalizeHost(new URL(publicUrl).host);
+    } catch {
+      activeTunnelHost = null;
+    }
+  };
+
+  const clearActiveTunnel = () => {
+    if (activeTunnelId) {
+      revokeTunnelArtifacts(activeTunnelId);
+    }
+    activeTunnelId = null;
+    activeTunnelHost = null;
+    activeTunnelMode = null;
+    activeTunnelPublicUrl = null;
+    bootstrapRecord = null;
+  };
+
+  const isBootstrapRecordUsable = (record) => {
+    if (!record || record.revokedAt || record.usedAt) {
+      return false;
+    }
+    if (typeof record.expiresAt === 'number' && nowTs() >= record.expiresAt) {
+      return false;
+    }
+    return true;
+  };
+
+  const issueBootstrapToken = ({ ttlMs }) => {
+    if (!activeTunnelId) {
+      throw new Error('Tunnel is not active');
+    }
+
+    revokeBootstrapToken();
+
+    const token = crypto.randomBytes(BOOTSTRAP_TOKEN_COOKIE_SAFE_BYTES).toString('base64url');
+    const issuedAt = nowTs();
+    const expiresAt = Number.isFinite(ttlMs) && ttlMs > 0 ? issuedAt + ttlMs : null;
+
+    bootstrapRecord = {
+      id: crypto.randomUUID(),
+      tunnelId: activeTunnelId,
+      tokenHash: hashToken(token),
+      issuedAt,
+      expiresAt,
+      usedAt: null,
+      revokedAt: null,
+    };
+
+    return {
+      token,
+      expiresAt,
+    };
+  };
+
+  const getBootstrapStatus = () => {
+    if (!isBootstrapRecordUsable(bootstrapRecord)) {
+      return {
+        hasBootstrapToken: false,
+        bootstrapExpiresAt: null,
+      };
+    }
+
+    return {
+      hasBootstrapToken: true,
+      bootstrapExpiresAt: bootstrapRecord.expiresAt,
+    };
+  };
+
+  const checkConnectRateLimit = (req) => {
+    const key = getRateLimitKey(req);
+    const now = nowTs();
+    const maxAttempts = rateLimitMaxForKey(key);
+    const record = connectRateLimiter.get(key);
+
+    if (record?.lockedUntil && now < record.lockedUntil) {
+      return {
+        allowed: false,
+        retryAfter: Math.ceil((record.lockedUntil - now) / 1000),
+      };
+    }
+
+    if (!record || now - record.lastAttempt > CONNECT_RATE_LIMIT_WINDOW_MS) {
+      return { allowed: true, retryAfter: 0 };
+    }
+
+    if (record.count >= maxAttempts) {
+      const lockedUntil = now + CONNECT_RATE_LIMIT_LOCK_MS;
+      connectRateLimiter.set(key, {
+        count: record.count + 1,
+        lastAttempt: now,
+        lockedUntil,
+      });
+      return {
+        allowed: false,
+        retryAfter: Math.ceil(CONNECT_RATE_LIMIT_LOCK_MS / 1000),
+      };
+    }
+
+    return { allowed: true, retryAfter: 0 };
+  };
+
+  const recordConnectFailedAttempt = (req) => {
+    const key = getRateLimitKey(req);
+    const now = nowTs();
+    const record = connectRateLimiter.get(key);
+
+    if (!record || now - record.lastAttempt > CONNECT_RATE_LIMIT_WINDOW_MS) {
+      connectRateLimiter.set(key, { count: 1, lastAttempt: now, lockedUntil: null });
+      return;
+    }
+
+    connectRateLimiter.set(key, {
+      count: record.count + 1,
+      lastAttempt: now,
+      lockedUntil: record.lockedUntil || null,
+    });
+  };
+
+  const clearConnectRateLimit = (req) => {
+    const key = getRateLimitKey(req);
+    connectRateLimiter.delete(key);
+  };
+
+  const getTunnelSessionFromRequest = (req) => {
+    const cookies = parseCookies(req.headers.cookie);
+    const token = cookies[TUNNEL_SESSION_COOKIE_NAME];
+    if (!token) {
+      return null;
+    }
+    const session = tunnelSessions.get(token);
+    if (!session) {
+      return null;
+    }
+    if (session.revokedAt) {
+      return null;
+    }
+    if (session.expiresAt <= nowTs()) {
+      if (!session.expiredAt) {
+        session.expiredAt = nowTs();
+      }
+      return null;
+    }
+    if (session.tunnelId !== activeTunnelId) {
+      return null;
+    }
+    session.lastSeenAt = nowTs();
+    return session;
+  };
+
+  const requireTunnelSession = (req, res, next) => {
+    const session = getTunnelSessionFromRequest(req);
+    if (session) {
+      return next();
+    }
+
+    clearTunnelSessionCookie(req, res);
+    res.status(401).json({
+      error: 'Tunnel authentication required',
+      locked: true,
+      tunnelLocked: true,
+    });
+  };
+
+  const exchangeBootstrapToken = ({ req, res, token, sessionTtlMs }) => {
+    const rateLimit = checkConnectRateLimit(req);
+    if (!rateLimit.allowed) {
+      return {
+        ok: false,
+        reason: 'rate-limited',
+        retryAfter: rateLimit.retryAfter,
+      };
+    }
+
+    if (!activeTunnelId || !bootstrapRecord) {
+      recordConnectFailedAttempt(req);
+      return { ok: false, reason: 'inactive' };
+    }
+
+    if (!token || typeof token !== 'string') {
+      recordConnectFailedAttempt(req);
+      return { ok: false, reason: 'missing-token' };
+    }
+
+    if (!isBootstrapRecordUsable(bootstrapRecord)) {
+      recordConnectFailedAttempt(req);
+      return { ok: false, reason: 'expired' };
+    }
+
+    if (bootstrapRecord.tunnelId !== activeTunnelId) {
+      recordConnectFailedAttempt(req);
+      return { ok: false, reason: 'tunnel-mismatch' };
+    }
+
+    const incomingHash = hashToken(token);
+    const expected = bootstrapRecord.tokenHash;
+    const validHash = incomingHash.length === expected.length
+      && crypto.timingSafeEqual(Buffer.from(incomingHash), Buffer.from(expected));
+
+    if (!validHash) {
+      recordConnectFailedAttempt(req);
+      return { ok: false, reason: 'invalid-token' };
+    }
+
+    bootstrapRecord.usedAt = nowTs();
+    clearConnectRateLimit(req);
+
+    const sessionId = crypto.randomBytes(32).toString('base64url');
+    const createdAt = nowTs();
+    const expiresAt = createdAt + sessionTtlMs;
+
+    tunnelSessions.set(sessionId, {
+      sessionId,
+      tunnelId: activeTunnelId,
+      mode: activeTunnelMode,
+      publicUrl: activeTunnelPublicUrl,
+      createdAt,
+      lastSeenAt: createdAt,
+      expiresAt,
+      revokedAt: null,
+      revokedReason: null,
+      expiredAt: null,
+    });
+
+    setTunnelSessionCookie(req, res, sessionId, sessionTtlMs);
+
+    return {
+      ok: true,
+      sessionExpiresAt: expiresAt,
+    };
+  };
+
+  const listTunnelSessions = () => {
+    const now = nowTs();
+
+    const sessions = [];
+    for (const record of tunnelSessions.values()) {
+      const isExpired = record.expiresAt <= now;
+      if (isExpired && !record.expiredAt) {
+        record.expiredAt = now;
+      }
+
+      const active = !record.revokedAt && !isExpired && record.tunnelId === activeTunnelId;
+      const status = active ? 'active' : 'inactive';
+      const inactiveReason = record.revokedAt ? (record.revokedReason || 'revoked') : (isExpired ? 'expired' : 'inactive');
+
+      sessions.push({
+        sessionId: record.sessionId,
+        tunnelId: record.tunnelId,
+        mode: record.mode,
+        publicUrl: record.publicUrl,
+        createdAt: record.createdAt,
+        lastSeenAt: record.lastSeenAt,
+        expiresAt: record.expiresAt,
+        revokedAt: record.revokedAt,
+        status,
+        inactiveReason: status === 'inactive' ? inactiveReason : null,
+      });
+    }
+
+    sessions.sort((a, b) => b.createdAt - a.createdAt);
+    return sessions;
+  };
+
+  return {
+    classifyRequestScope,
+    setActiveTunnel,
+    clearActiveTunnel,
+    revokeTunnelArtifacts,
+    issueBootstrapToken,
+    getBootstrapStatus,
+    requireTunnelSession,
+    getTunnelSessionFromRequest,
+    exchangeBootstrapToken,
+    listTunnelSessions,
+    clearTunnelSessionCookie,
+    getActiveTunnelId: () => activeTunnelId,
+    getActiveTunnelHost: () => activeTunnelHost,
+    getActiveTunnelMode: () => activeTunnelMode,
+  };
+};

package/server/lib/terminal/DOCUMENTATION.md

@@ -0,0 +1,48 @@
+# Terminal Subsystem
+
+## Ownership
+
+`runtime.js` owns terminal identity, PTY processes, status, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shells.js` discovers executable shell families and resolves the persisted shell ID without accepting command strings or arguments. Clients own tab arrangement and choose stable terminal IDs. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
+
+## Protocol
+
+`/api/terminal/ws` is the only terminal data transport. It uses v3 binary JSON control frames and is opened through `openRuntimeWebSocket`, preserving direct, Electron proxy, URL-token authentication, and private-relay routing.
+
+- `attach` registers a connection for one terminal. One socket may attach to many terminals.
+- Every attach and reconnect begins with an authoritative `snapshot` containing bounded history and the current sequence.
+- A current socket that closes or errors before its initial `open` invalidates its URL-scoped auth token before retrying, so retries mint a fresh token instead of backing off against a rejected upgrade. Hidden or offline clients wait 60 seconds and wake promptly on visibility/online recovery.
+- `output`, `exit`, and `restarted` carry monotonically increasing per-terminal sequences. Output carries raw live bytes plus replay-safe bytes with terminal query exchanges removed.
+- Attach registers before capturing the snapshot, buffers concurrent events, drops events represented by the snapshot sequence, then enters live delivery.
+- `write` always includes the terminal ID; sockets never have mutable single-terminal binding state.
+- `detach` removes only that attachment.
+- Creation carries the active UI appearance. The PTY sets `COLORFGBG` and answers OSC 10, OSC 11, Mode 2031, and primary-device-attribute queries immediately, including queries emitted before a WebSocket attachment exists. The DA1 fallback prevents Fish from waiting ten seconds for a renderer that cannot observe or answer its startup query. Subscribed TUIs receive a Mode 2031 notification when the appearance changes.
+
+HTTP remains the authenticated command plane for create, resize, appearance updates, restart, close, and force-kill. There is no SSE output or HTTP input compatibility path.
+
+## PTY Lifecycle
+
+- IDs are client-provided or generated with `randomUUID()`.
+- Concurrent creates for one ID are single-flight only when working directory and shell preference match. Existing IDs cannot be reused for another working directory.
+- Dimensions are bounded to 1-1000 columns and 1-500 rows; input is capped at 64 KiB.
+- A client may create before its renderer has mounted. It derives an initial size from the container and font metrics (falling back to 80x24 when unavailable), then sends a resize once Ghostty reports its final dimensions. This allows shell startup and renderer initialization to overlap.
+- PTY children explicitly clear `NODE_CHANNEL_FD`; daemon IPC descriptors are host-private and invalid after PTY descriptor cleanup.
+- PTY children also strip AppImage `ARGV0` (and other host-private shell vars such as `ELECTRON_RUN_AS_NODE`, `BASH_ENV`, `ENV`, `BASH_XTRACEFD`). An exported `ARGV0` makes zsh rewrite argv[0] for every external command, which breaks Python venv detection and other argv[0]/$0 consumers while leaving `/proc/self/exe` correct. On Linux, PTY spawn is wrapped with `env -u ARGV0` because `bun-pty` merges the native OS environ and would otherwise reintroduce `ARGV0` after a JS-only delete.
+- `GET /api/terminal/shells` reports shell IDs available on the active server using the same augmented PATH provided to spawned PTYs, plus whether each executable has a supported login-mode argument. `auto` preserves environment/platform fallback order; an explicit unavailable shell fails creation instead of silently running a different shell. Login mode is opt-in and uses only built-in arguments for known shells. Preference changes affect new sessions and explicit restarts, not running PTYs.
+- PTY data and exit callbacks enter one FIFO queue. Stale callbacks from replaced processes are ignored.
+- Scrollback is retained on the server and capped at 512 KiB with UTF-8-safe trimming. Device-status, device-attribute, cursor-position reply, and color-query exchanges are removed from replay history with incomplete control sequences carried across PTY chunks; live output remains byte-for-byte unchanged.
+- Exited sessions remain attachable until explicit close or idle cleanup.
+- Restarts are serialized per terminal. Each restart spawns and wires the replacement before terminating the old process, retaining the terminal ID.
+- Close uses SIGTERM with bounded SIGKILL escalation. Force-kill, idle cleanup, and runtime shutdown terminate process groups immediately where supported. Removal explicitly sends a fatal scoped closure and evicts client projections even when a PTY backend fails to emit `onExit`; attached terminals are not considered idle.
+
+## Security And Relay
+
+The WebSocket path must remain in both `isUrlAuthWebSocketPath` and relay `ALLOWED_WS_PATHS`. The client must use `getRuntimeUrlResolver().websocket()` and `openRuntimeWebSocket`; direct local URLs or raw browser WebSockets break relay and URL-token authentication.
+
+## Verification
+
+Run:
+
+```sh
+bun test packages/web/server/lib/terminal/runtime.test.js packages/web/server/lib/terminal/terminal-ws-protocol.test.js
+bun test packages/web/server/lib/ui-auth/ui-auth.test.js packages/web/server/lib/relay/cross-compat.test.js
+```