gitspace 0.2.0-rc.1

package/src/serve/pty-session.ts

@@ -0,0 +1,236 @@
+// @ts-nocheck - Uses Bun-specific APIs (Bun.Terminal)
+/**
+ * PTY session wrapper for remote terminal access
+ *
+ * Wraps Bun.Terminal to provide:
+ * - Encrypted frame I/O using session keys
+ * - Resize handling with SIGWINCH
+ * - Clean lifecycle management
+ */
+
+import { createFrame, openFrame } from "../lib/tmux-lite/crypto/frames.js";
+import { decodeControl, type SessionCtrl } from "../lib/tmux-lite/protocol.js";
+import type { SessionKeys } from "../types/identity.js";
+import { STREAM_ID } from "./types.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** PTY session options */
+export interface PTYSessionOptions {
+  /** Shell to spawn (default: $SHELL or /bin/bash) */
+  shell?: string;
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Initial terminal columns */
+  cols?: number;
+  /** Initial terminal rows */
+  rows?: number;
+  /** Session encryption keys */
+  sessionKeys: SessionKeys;
+  /** Callback for encrypted output data */
+  onData: (encrypted: Buffer) => void;
+  /** Callback when PTY exits */
+  onClose: (exitCode: number) => void;
+}
+
+// ============================================================================
+// PTYSession Class
+// ============================================================================
+
+/**
+ * Manages a PTY session with encrypted I/O
+ *
+ * @example
+ * ```typescript
+ * const pty = new PTYSession({
+ *   sessionKeys,
+ *   onData: (encrypted) => relay.send(connectionId, encrypted),
+ *   onClose: (code) => console.log(`Exit: ${code}`),
+ * });
+ *
+ * // Write encrypted input from client
+ * pty.write(encryptedFrame);
+ *
+ * // Handle resize
+ * pty.resize(120, 40);
+ *
+ * // Clean up
+ * pty.close();
+ * ```
+ */
+export class PTYSession {
+  private terminal: ReturnType<typeof Bun.Terminal> | null = null;
+  private proc: ReturnType<typeof Bun.spawn> | null = null;
+  private sendKey: Uint8Array;
+  private receiveKey: Uint8Array;
+  private onData: (encrypted: Buffer) => void;
+  private onClose: (exitCode: number) => void;
+  private closed = false;
+
+  constructor(options: PTYSessionOptions) {
+    this.sendKey = options.sessionKeys.sendKey;
+    this.receiveKey = options.sessionKeys.receiveKey;
+    this.onData = options.onData;
+    this.onClose = options.onClose;
+
+    const shell = options.shell ?? process.env.SHELL ?? "/bin/bash";
+    const cwd = options.cwd ?? process.env.HOME ?? "/";
+    const cols = options.cols ?? 80;
+    const rows = options.rows ?? 24;
+
+    // Build environment
+    const env: Record<string, string> = {
+      ...process.env as Record<string, string>,
+      ...options.env,
+      TERM: "xterm-256color",
+      SPACES_REMOTE: "true",
+    };
+
+    // Create PTY terminal
+    this.terminal = new Bun.Terminal({
+      cols,
+      rows,
+      data: (_term: unknown, data: Uint8Array) => {
+        if (this.closed) return;
+
+        // Encrypt and send output
+        const frame = createFrame(STREAM_ID.DATA, data, this.sendKey);
+        this.onData(frame);
+      },
+    });
+
+    // Spawn shell process
+    this.proc = Bun.spawn([shell], {
+      terminal: this.terminal,
+      cwd,
+      env,
+    });
+
+    // Handle process exit
+    this.proc.exited.then((code) => {
+      if (!this.closed) {
+        this.closed = true;
+        this.onClose(code);
+      }
+    });
+  }
+
+  /**
+   * Get the process ID
+   */
+  get pid(): number | undefined {
+    return this.proc?.pid;
+  }
+
+  /**
+   * Check if session is closed
+   */
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /**
+   * Write encrypted input data to PTY
+   *
+   * Decrypts the frame and writes plaintext to stdin.
+   *
+   * @param encryptedFrame - Encrypted frame from client
+   * @returns True if write succeeded, false on decryption failure
+   */
+  write(encryptedFrame: Buffer | Uint8Array): boolean {
+    if (this.closed || !this.terminal) return false;
+
+    const result = openFrame(Buffer.from(encryptedFrame), this.receiveKey);
+    if (!result) {
+      console.warn("[pty-session] Failed to decrypt input frame");
+      return false;
+    }
+
+    // Check stream ID
+    if (result.streamId === STREAM_ID.CONTROL) {
+      // Handle control message
+      this.handleControlMessage(result.data);
+      return true;
+    }
+
+    // Write data to PTY stdin
+    this.terminal.write(result.data);
+    return true;
+  }
+
+  /**
+   * Handle control messages (resize, etc.)
+   * Uses tmux-lite SessionCtrl format for consistency
+   */
+  private handleControlMessage(data: Buffer): void {
+    try {
+      const msg = decodeControl(data) as SessionCtrl;
+
+      switch (msg.type) {
+        case "resize":
+          this.resize(msg.cols, msg.rows);
+          break;
+        case "detach":
+          // Detach is handled at a higher level, ignore here
+          break;
+        case "attach-init":
+          // attach-init doesn't apply to PTYSession (already started)
+          break;
+        default:
+          console.warn("[pty-session] Unknown control message:", msg);
+      }
+    } catch (e) {
+      console.warn("[pty-session] Invalid control message:", e);
+    }
+  }
+
+  /**
+   * Resize the PTY
+   *
+   * @param cols - Number of columns
+   * @param rows - Number of rows
+   */
+  resize(cols: number, rows: number): void {
+    if (this.closed || !this.terminal || !this.proc) return;
+
+    try {
+      this.terminal.resize(cols, rows);
+      // Send SIGWINCH to process group so child processes get it
+      try {
+        process.kill(-this.proc.pid, "SIGWINCH");
+      } catch {
+        // Fallback to direct signal if process group fails
+        try {
+          process.kill(this.proc.pid, "SIGWINCH");
+        } catch {
+          // Process may have exited
+        }
+      }
+    } catch (e) {
+      console.warn("[pty-session] Resize failed:", e);
+    }
+  }
+
+  /**
+   * Close the PTY session
+   *
+   * Kills the process and cleans up resources.
+   */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+
+    try {
+      this.proc?.kill();
+    } catch {
+      // Already exited
+    }
+
+    this.terminal = null;
+    this.proc = null;
+  }
+}

package/src/serve/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Types for the gssh serve command
+ *
+ * Defines configuration, session state, and events for the machine-side daemon.
+ */
+
+import type { PTYSession } from "./pty-session.js";
+import type { Identity, SessionKeys, AccessType } from "../types/identity.js";
+import type { AccessControlList } from "../lib/tmux-lite/crypto/access-control.js";
+import { FrameType } from "../lib/tmux-lite/protocol.js";
+
+// ============================================================================
+// Permission Helpers
+// ============================================================================
+
+/**
+ * Check if an access type grants write permission (terminal input)
+ *
+ * Only 'full' access allows writing to the terminal.
+ * 'session-invite' is read-only.
+ */
+export function canWrite(accessType: AccessType | undefined): boolean {
+  return accessType === 'full';
+}
+
+/**
+ * Check if an access type grants management permission
+ *
+ * Management includes: create/kill sessions, delete workspaces, etc.
+ * Only 'full' access allows management operations.
+ */
+export function canManage(accessType: AccessType | undefined): boolean {
+  return accessType === 'full';
+}
+
+/**
+ * Check if a client can attach to a specific session
+ *
+ * - 'full' access can attach to any session
+ * - 'session-invite' can only attach to the specific session they were invited to
+ */
+export function canAttachSession(
+  accessType: AccessType | undefined,
+  grantedSessionId: string | undefined,
+  targetSessionId: string
+): boolean {
+  if (accessType === 'full') return true;
+  if (accessType === 'session-invite') {
+    return grantedSessionId === targetSessionId;
+  }
+  return false;
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/** Configuration for the serve command */
+export interface ServeOptions {
+  /** Relay WebSocket URL */
+  relay: string;
+  /** Machine identity for authentication */
+  identity: Identity;
+  /** Access control list for authorized clients */
+  accessList: AccessControlList;
+  /** Shell to spawn (default: $SHELL or /bin/bash) */
+  shell?: string;
+  /** Extra environment variables for PTY sessions */
+  env?: Record<string, string>;
+  /** Handshake timeout in milliseconds (default: 30000) */
+  handshakeTimeoutMs?: number;
+}
+
+// ============================================================================
+// Session Types
+// ============================================================================
+
+/** State of a client session */
+export type ClientSessionState = "handshaking" | "browsing" | "attached" | "closed";
+
+/** Client session data */
+export interface ClientSession {
+  /** Unique connection ID from relay */
+  connectionId: string;
+  /** Current session state */
+  state: ClientSessionState;
+  /** When handshake started (Unix ms) */
+  handshakeStartedAt: number;
+  /** PTY session (created after attach_session) - legacy, use tmuxSocket instead */
+  ptySession?: PTYSession;
+  /** tmux-lite session socket connection */
+  tmuxSocket?: Awaited<ReturnType<typeof Bun.connect>>;
+  /** Buffered writer for tmux-lite socket (Bun sockets can partially write under backpressure) */
+  tmuxSocketWriter?: {
+    write(data: Buffer | Uint8Array | ArrayBuffer): void;
+    flush(): void;
+    clear(): void;
+  };
+  /** Path to tmux-lite session socket */
+  sessionSocketPath?: string;
+  /** Session encryption keys */
+  sessionKeys?: SessionKeys;
+  /** Granted access type */
+  accessType?: AccessType;
+  /** Session ID for session-invite access */
+  sessionId?: string;
+  /** Peer's identity ID */
+  peerIdentityId?: string;
+  /** Attached tmux-lite session ID (when state === "attached") */
+  attachedSessionId?: string;
+  /** True if waiting for initial resize before sending attach-init */
+  waitingForResize?: boolean;
+  /** Buffer for incomplete frames from tmux-lite socket */
+  frameBuffer?: Buffer;
+}
+
+// ============================================================================
+// Stream IDs (for encrypted relay framing)
+// ============================================================================
+//
+// Stream IDs align with FrameType from tmux-lite protocol:
+// - DATA (0) = FrameType.PTY: raw terminal bytes
+// - CONTROL (1) = FrameType.CONTROL: JSON control messages (resize, detach, etc.)
+//
+// See src/lib/tmux-lite/protocol.ts for SessionCtrl/SessionEvent types.
+
+/** Stream IDs for frame routing - aligned with FrameType */
+export const STREAM_ID = {
+  /** Terminal data stream (same as FrameType.PTY) */
+  DATA: FrameType.PTY,
+  /** Control messages (same as FrameType.CONTROL) */
+  CONTROL: FrameType.CONTROL,
+} as const;
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+/** Events emitted by the serve daemon */
+export type ServeEvent =
+  | { type: "client_connected"; connectionId: string }
+  | { type: "client_authenticated"; connectionId: string; identityId: string; accessType: AccessType; sessionId?: string }
+  | { type: "client_disconnected"; connectionId: string; reason: string }
+  | { type: "relay_connected" }
+  | { type: "relay_disconnected"; code: number; reason: string }
+  | { type: "relay_reconnecting"; attempt: number }
+  | { type: "error"; connectionId?: string; error: Error };
+
+/** Event handler for serve events */
+export type ServeEventHandler = (event: ServeEvent) => void;
+
+// ============================================================================
+// Relay Protocol Types
+// ============================================================================
+
+/** Envelope for messages from relay (includes routing info) */
+export interface RelayEnvelope {
+  /** Connection ID for routing */
+  connectionId: string;
+  /** Raw message data */
+  data: Uint8Array;
+}
+
+/** Handshake message envelope */
+export interface HandshakeMessageEnvelope {
+  type: "handshake";
+  phase: "client_hello" | "server_hello" | "client_auth" | "server_auth";
+  data: unknown;
+}