gitspace 0.2.0-rc.1

package/src/lib/tmux-lite/crypto/access-control.ts

@@ -0,0 +1,320 @@
+/**
+ * Access control list management for managing authorized identities
+ *
+ * This module provides an in-memory access control list that can be serialized
+ * to JSON for persistence. It manages which public keys are allowed to connect.
+ *
+ * Access types:
+ * - 'full': Complete machine access (browse, create sessions, etc.)
+ * - 'session-invite': View-only access to a specific session
+ *
+ * @module access-control
+ */
+
+import type {
+  AccessEntry,
+  AccessType,
+  PublicIdentity,
+} from "../../../types/identity.js";
+import { verify, deriveIdentityId } from "./identity.js";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default access type for new entries via `gssh access add` */
+export const DEFAULT_ACCESS_TYPE: AccessType = 'full';
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if an access entry is expired
+ *
+ * @param entry - Access entry to check
+ * @returns True if the entry has an expiry time and it has passed
+ */
+export function isAccessExpired(entry: AccessEntry): boolean {
+  if (!entry.expiresAt) {
+    return false;
+  }
+  return Date.now() >= entry.expiresAt;
+}
+
+// ============================================================================
+// AccessControlList Class
+// ============================================================================
+
+/**
+ * Manages the access control list for authorized identities
+ *
+ * This class maintains an in-memory map of identity IDs to access entries,
+ * providing methods to add, remove, and check access. It also supports
+ * signature verification to authenticate incoming connections.
+ *
+ * @example
+ * ```typescript
+ * const acl = new AccessControlList();
+ *
+ * // Add a new identity with full access
+ * const entry = acl.addEntry(publicIdentity);
+ *
+ * // Add a session invite (view-only)
+ * const invite = acl.addEntry(publicIdentity, 'session-invite', 'session-123');
+ *
+ * // Check access
+ * if (acl.hasAccess(identityId)) {
+ *   console.log('Access granted');
+ * }
+ *
+ * // Verify signature and check access
+ * const entry = acl.verifyAndCheckAccess(message, signature, publicKey);
+ * if (entry) {
+ *   console.log('Authenticated with access type:', entry.accessType);
+ * }
+ * ```
+ */
+export class AccessControlList {
+  private entries: Map<string, AccessEntry> = new Map();
+
+  /**
+   * Add an identity to the access list
+   *
+   * Creates a new access entry with the given access type.
+   * If the identity already exists, it will be replaced.
+   *
+   * @param publicIdentity - Public identity information to add
+   * @param accessType - Access type to grant (default: 'full')
+   * @param sessionId - For session-invite: the specific session ID
+   * @returns The created access entry
+   */
+  addEntry(
+    publicIdentity: PublicIdentity,
+    accessType: AccessType = DEFAULT_ACCESS_TYPE,
+    sessionId?: string
+  ): AccessEntry {
+    const entry: AccessEntry = {
+      identityId: publicIdentity.id,
+      signingPublicKey: publicIdentity.signingPublicKey,
+      keyExchangePublicKey: publicIdentity.keyExchangePublicKey,
+      label: publicIdentity.label,
+      grantedAt: Date.now(),
+      accessType,
+      sessionId,
+    };
+
+    this.entries.set(publicIdentity.id, entry);
+    return entry;
+  }
+
+  /**
+   * Remove an identity from the access list
+   *
+   * @param identityId - Identity ID to remove
+   * @returns True if the entry was removed, false if it didn't exist
+   */
+  removeEntry(identityId: string): boolean {
+    return this.entries.delete(identityId);
+  }
+
+  /**
+   * Check if an identity has access
+   *
+   * Checks if the identity exists in the access list and is not expired.
+   *
+   * @param identityId - Identity ID to check
+   * @returns True if the identity has access and is not expired
+   */
+  hasAccess(identityId: string): boolean {
+    const entry = this.entries.get(identityId);
+    if (!entry) {
+      return false;
+    }
+    return !isAccessExpired(entry);
+  }
+
+  /**
+   * Check if an identity has full access
+   *
+   * @param identityId - Identity ID to check
+   * @returns True if the identity has full access and is not expired
+   */
+  hasFullAccess(identityId: string): boolean {
+    const entry = this.entries.get(identityId);
+    if (!entry || isAccessExpired(entry)) {
+      return false;
+    }
+    return entry.accessType === 'full';
+  }
+
+  /**
+   * Check if an identity has access to a specific session
+   *
+   * @param identityId - Identity ID to check
+   * @param sessionId - Session ID to check access for
+   * @returns True if the identity has access (full or session-invite for this session)
+   */
+  hasSessionAccess(identityId: string, sessionId: string): boolean {
+    const entry = this.entries.get(identityId);
+    if (!entry || isAccessExpired(entry)) {
+      return false;
+    }
+    // Full access can access any session
+    if (entry.accessType === 'full') {
+      return true;
+    }
+    // Session invite can only access the specific session
+    return entry.accessType === 'session-invite' && entry.sessionId === sessionId;
+  }
+
+  /**
+   * Get access entry by identity ID
+   *
+   * @param identityId - Identity ID to look up
+   * @returns Access entry if found and not expired, undefined otherwise
+   */
+  getEntry(identityId: string): AccessEntry | undefined {
+    const entry = this.entries.get(identityId);
+    if (!entry || isAccessExpired(entry)) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  /**
+   * Get all entries
+   *
+   * Returns all access entries, including expired ones. Use isAccessExpired()
+   * to filter out expired entries if needed.
+   *
+   * @returns Array of all access entries
+   */
+  getAllEntries(): AccessEntry[] {
+    return Array.from(this.entries.values());
+  }
+
+  /**
+   * Update access type for an identity
+   *
+   * @param identityId - Identity ID to update
+   * @param accessType - New access type
+   * @param sessionId - For session-invite: the specific session ID
+   * @returns True if the entry was updated, false if it doesn't exist
+   */
+  updateAccessType(
+    identityId: string,
+    accessType: AccessType,
+    sessionId?: string
+  ): boolean {
+    const entry = this.entries.get(identityId);
+    if (!entry) {
+      return false;
+    }
+
+    entry.accessType = accessType;
+    entry.sessionId = sessionId;
+
+    this.entries.set(identityId, entry);
+    return true;
+  }
+
+  /**
+   * Update label for an identity
+   *
+   * @param identityId - Identity ID to update
+   * @param label - New label
+   * @returns True if the entry was updated, false if it doesn't exist
+   */
+  updateLabel(identityId: string, label: string): boolean {
+    const entry = this.entries.get(identityId);
+    if (!entry) {
+      return false;
+    }
+
+    entry.label = label;
+    this.entries.set(identityId, entry);
+    return true;
+  }
+
+  /**
+   * Verify a signed message and check access
+   *
+   * This method:
+   * 1. Derives the identity ID from the signing public key
+   * 2. Verifies the signature is valid
+   * 3. Checks if the identity has access
+   * 4. Returns the access entry if all checks pass
+   *
+   * @param message - Message that was signed
+   * @param signature - Signature to verify (64 bytes)
+   * @param signingPublicKey - Ed25519 public key (32 bytes)
+   * @returns AccessEntry if signature is valid and identity has access, null otherwise
+   */
+  verifyAndCheckAccess(
+    message: Uint8Array,
+    signature: Uint8Array,
+    signingPublicKey: Uint8Array
+  ): AccessEntry | null {
+    // Verify signature
+    if (!verify(message, signature, signingPublicKey)) {
+      return null;
+    }
+
+    // Derive identity ID from public key
+    const identityId = deriveIdentityId(signingPublicKey);
+
+    // Check access
+    const entry = this.getEntry(identityId);
+    if (!entry) {
+      return null;
+    }
+
+    return entry;
+  }
+
+  /**
+   * Export access list for storage
+   *
+   * Returns all entries (including expired ones) as a JSON-serializable array.
+   * This can be used to persist the access list to disk.
+   *
+   * @returns Array of access entries
+   */
+  export(): AccessEntry[] {
+    return this.getAllEntries();
+  }
+
+  /**
+   * Import access list from storage
+   *
+   * Replaces the current access list with the provided entries.
+   * This will clear any existing entries.
+   *
+   * @param entries - Array of access entries to import
+   */
+  import(entries: AccessEntry[]): void {
+    this.entries.clear();
+    for (const entry of entries) {
+      this.entries.set(entry.identityId, entry);
+    }
+  }
+
+  /**
+   * Clear all entries
+   *
+   * Removes all access entries from the list.
+   */
+  clear(): void {
+    this.entries.clear();
+  }
+
+  /**
+   * Get count of entries
+   *
+   * @returns Number of entries in the access list (including expired ones)
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+}

package/src/lib/tmux-lite/crypto/frames.test.ts

@@ -0,0 +1,262 @@
+import { describe, expect, test } from "bun:test";
+import {
+  encodeFrame,
+  decodeFrame,
+  peekStreamId,
+  createFrame,
+  openFrame,
+  MASTER_STREAM_ID,
+  STREAM_ID_LENGTH,
+  MIN_FRAME_LENGTH,
+  type EncryptedFrame,
+} from "./frames";
+import { NONCE_LENGTH, AUTH_TAG_LENGTH, generateNonce } from "./secretbox";
+import { randomBytes } from "node:crypto";
+
+const testKey = randomBytes(32);
+
+describe("constants", () => {
+  test("MASTER_STREAM_ID is 0", () => {
+    expect(MASTER_STREAM_ID).toBe(0);
+  });
+
+  test("STREAM_ID_LENGTH is 4", () => {
+    expect(STREAM_ID_LENGTH).toBe(4);
+  });
+
+  test("MIN_FRAME_LENGTH is correct", () => {
+    expect(MIN_FRAME_LENGTH).toBe(STREAM_ID_LENGTH + NONCE_LENGTH + AUTH_TAG_LENGTH);
+  });
+});
+
+describe("encodeFrame/decodeFrame", () => {
+  test("encodes and decodes frame", () => {
+    const frame: EncryptedFrame = {
+      streamId: 42,
+      nonce: generateNonce(),
+      ciphertext: Buffer.from("encrypted-data-here"),
+    };
+
+    const encoded = encodeFrame(frame);
+    const decoded = decodeFrame(encoded);
+
+    expect(decoded).not.toBeNull();
+    expect(decoded!.streamId).toBe(42);
+    expect(decoded!.nonce.equals(frame.nonce)).toBe(true);
+    expect(decoded!.ciphertext.equals(frame.ciphertext)).toBe(true);
+  });
+
+  test("encodes streamId as big-endian uint32", () => {
+    const frame: EncryptedFrame = {
+      streamId: 0x12345678,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32),
+    };
+
+    const encoded = encodeFrame(frame);
+
+    expect(encoded[0]).toBe(0x12);
+    expect(encoded[1]).toBe(0x34);
+    expect(encoded[2]).toBe(0x56);
+    expect(encoded[3]).toBe(0x78);
+  });
+
+  test("encodes master stream (0)", () => {
+    const frame: EncryptedFrame = {
+      streamId: MASTER_STREAM_ID,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32), // Must be >= AUTH_TAG_LENGTH
+    };
+
+    const encoded = encodeFrame(frame);
+    const decoded = decodeFrame(encoded);
+
+    expect(decoded!.streamId).toBe(MASTER_STREAM_ID);
+  });
+
+  test("encodes large streamId", () => {
+    const frame: EncryptedFrame = {
+      streamId: 0xffffffff,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32), // Must be >= AUTH_TAG_LENGTH
+    };
+
+    const encoded = encodeFrame(frame);
+    const decoded = decodeFrame(encoded);
+
+    expect(decoded!.streamId).toBe(0xffffffff);
+  });
+
+  test("decodeFrame returns null for too-short buffer", () => {
+    const tooShort = Buffer.alloc(MIN_FRAME_LENGTH - 1);
+    const decoded = decodeFrame(tooShort);
+    expect(decoded).toBeNull();
+  });
+
+  test("decodeFrame accepts Uint8Array", () => {
+    const frame: EncryptedFrame = {
+      streamId: 1,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32), // Must be >= AUTH_TAG_LENGTH
+    };
+
+    const encoded = new Uint8Array(encodeFrame(frame));
+    const decoded = decodeFrame(encoded);
+
+    expect(decoded).not.toBeNull();
+    expect(decoded!.streamId).toBe(1);
+  });
+
+  test("handles empty ciphertext", () => {
+    const frame: EncryptedFrame = {
+      streamId: 1,
+      nonce: generateNonce(),
+      ciphertext: Buffer.alloc(AUTH_TAG_LENGTH), // Just auth tag, no payload
+    };
+
+    const encoded = encodeFrame(frame);
+    const decoded = decodeFrame(encoded);
+
+    expect(decoded).not.toBeNull();
+    expect(decoded!.ciphertext.length).toBe(AUTH_TAG_LENGTH);
+  });
+});
+
+describe("peekStreamId", () => {
+  test("extracts streamId without full decode", () => {
+    const frame: EncryptedFrame = {
+      streamId: 123,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32),
+    };
+
+    const encoded = encodeFrame(frame);
+    const streamId = peekStreamId(encoded);
+
+    expect(streamId).toBe(123);
+  });
+
+  test("returns null for too-short buffer", () => {
+    const tooShort = Buffer.alloc(STREAM_ID_LENGTH - 1);
+    const streamId = peekStreamId(tooShort);
+    expect(streamId).toBeNull();
+  });
+
+  test("works with exactly STREAM_ID_LENGTH bytes", () => {
+    const buf = Buffer.alloc(STREAM_ID_LENGTH);
+    buf.writeUInt32BE(999, 0);
+
+    const streamId = peekStreamId(buf);
+    expect(streamId).toBe(999);
+  });
+
+  test("accepts Uint8Array", () => {
+    const frame: EncryptedFrame = {
+      streamId: 456,
+      nonce: generateNonce(),
+      ciphertext: randomBytes(32),
+    };
+
+    const encoded = new Uint8Array(encodeFrame(frame));
+    const streamId = peekStreamId(encoded);
+
+    expect(streamId).toBe(456);
+  });
+});
+
+describe("createFrame/openFrame", () => {
+  test("creates and opens frame", () => {
+    const plaintext = Buffer.from("Hello, World!");
+    const frame = createFrame(MASTER_STREAM_ID, plaintext, testKey);
+
+    const result = openFrame(frame, testKey);
+
+    expect(result).not.toBeNull();
+    expect(result!.streamId).toBe(MASTER_STREAM_ID);
+    expect(result!.data.equals(plaintext)).toBe(true);
+  });
+
+  test("creates frame with custom streamId", () => {
+    const plaintext = Buffer.from("Session data");
+    const streamId = 42;
+    const frame = createFrame(streamId, plaintext, testKey);
+
+    const result = openFrame(frame, testKey);
+
+    expect(result).not.toBeNull();
+    expect(result!.streamId).toBe(streamId);
+    expect(result!.data.equals(plaintext)).toBe(true);
+  });
+
+  test("openFrame fails with wrong key", () => {
+    const plaintext = Buffer.from("Secret message");
+    const frame = createFrame(MASTER_STREAM_ID, plaintext, testKey);
+
+    const wrongKey = randomBytes(32);
+    const result = openFrame(frame, wrongKey);
+
+    expect(result).toBeNull();
+  });
+
+  test("openFrame fails with tampered frame", () => {
+    const plaintext = Buffer.from("Secret message");
+    const frame = createFrame(MASTER_STREAM_ID, plaintext, testKey);
+
+    // Tamper with encrypted data
+    frame[STREAM_ID_LENGTH + NONCE_LENGTH + 5] ^= 0xff;
+    const result = openFrame(frame, testKey);
+
+    expect(result).toBeNull();
+  });
+
+  test("openFrame returns null for too-short frame", () => {
+    const tooShort = Buffer.alloc(MIN_FRAME_LENGTH - 1);
+    const result = openFrame(tooShort, testKey);
+    expect(result).toBeNull();
+  });
+
+  test("handles empty plaintext", () => {
+    const plaintext = Buffer.from("");
+    const frame = createFrame(MASTER_STREAM_ID, plaintext, testKey);
+
+    const result = openFrame(frame, testKey);
+
+    expect(result).not.toBeNull();
+    expect(result!.data.length).toBe(0);
+  });
+
+  test("handles large plaintext", () => {
+    const plaintext = randomBytes(64 * 1024); // 64KB
+    const frame = createFrame(MASTER_STREAM_ID, plaintext, testKey);
+
+    const result = openFrame(frame, testKey);
+
+    expect(result).not.toBeNull();
+    expect(result!.data.equals(plaintext)).toBe(true);
+  });
+
+  test("accepts Uint8Array inputs", () => {
+    const plaintext = new Uint8Array([1, 2, 3, 4, 5]);
+    const key = new Uint8Array(testKey);
+    const frame = createFrame(1, plaintext, key);
+
+    const result = openFrame(frame, key);
+
+    expect(result).not.toBeNull();
+    expect(Buffer.from(result!.data).equals(Buffer.from(plaintext))).toBe(true);
+  });
+
+  test("streamId can be peeked before decryption", () => {
+    const plaintext = Buffer.from("Secret");
+    const streamId = 789;
+    const frame = createFrame(streamId, plaintext, testKey);
+
+    // Can peek without decrypting
+    const peeked = peekStreamId(frame);
+    expect(peeked).toBe(streamId);
+
+    // Can still decrypt after peeking
+    const result = openFrame(frame, testKey);
+    expect(result).not.toBeNull();
+  });
+});

package/src/lib/tmux-lite/crypto/frames.ts

@@ -0,0 +1,141 @@
+/**
+ * Encrypted frame encoding for E2E communication
+ *
+ * Frame format:
+ * ┌────────────┬────────────┬──────────────────────────────────────────────┐
+ * │  streamId  │   nonce    │   encrypted payload + authTag (16 bytes)     │
+ * │  4 bytes   │  12 bytes  │              variable length                 │
+ * └────────────┴────────────┴──────────────────────────────────────────────┘
+ *
+ * Stream IDs:
+ * - 0: Master stream (full machine access)
+ * - 1+: Session share streams (per-terminal access)
+ */
+
+import { NONCE_LENGTH, AUTH_TAG_LENGTH, encrypt, decrypt } from "./secretbox";
+
+/** Stream ID for master access (full machine) */
+export const MASTER_STREAM_ID = 0;
+
+/** Length of stream ID field in bytes */
+export const STREAM_ID_LENGTH = 4;
+
+/** Minimum frame length (streamId + nonce + authTag, no payload) */
+export const MIN_FRAME_LENGTH = STREAM_ID_LENGTH + NONCE_LENGTH + AUTH_TAG_LENGTH;
+
+/**
+ * Encrypted frame structure
+ */
+export interface EncryptedFrame {
+  /** Stream ID (0 = master, 1+ = session shares) */
+  streamId: number;
+  /** Nonce used for encryption (12 bytes) */
+  nonce: Buffer;
+  /** Encrypted payload with auth tag appended */
+  ciphertext: Buffer;
+}
+
+/**
+ * Encode an encrypted frame to a buffer
+ *
+ * @param frame - The encrypted frame to encode
+ * @returns Buffer ready to send over the wire
+ */
+export function encodeFrame(frame: EncryptedFrame): Buffer {
+  const buf = Buffer.alloc(
+    STREAM_ID_LENGTH + NONCE_LENGTH + frame.ciphertext.length
+  );
+
+  // Write stream ID (big-endian)
+  buf.writeUInt32BE(frame.streamId, 0);
+
+  // Copy nonce
+  frame.nonce.copy(buf, STREAM_ID_LENGTH);
+
+  // Copy ciphertext
+  frame.ciphertext.copy(buf, STREAM_ID_LENGTH + NONCE_LENGTH);
+
+  return buf;
+}
+
+/**
+ * Decode an encrypted frame from a buffer
+ *
+ * @param data - Raw buffer from the wire
+ * @returns Decoded frame, or null if too short
+ */
+export function decodeFrame(data: Buffer | Uint8Array): EncryptedFrame | null {
+  if (data.length < MIN_FRAME_LENGTH) {
+    return null;
+  }
+
+  const buf = Buffer.from(data);
+
+  const streamId = buf.readUInt32BE(0);
+  const nonce = buf.slice(STREAM_ID_LENGTH, STREAM_ID_LENGTH + NONCE_LENGTH);
+  const ciphertext = buf.slice(STREAM_ID_LENGTH + NONCE_LENGTH);
+
+  return { streamId, nonce, ciphertext };
+}
+
+/**
+ * Peek at the stream ID without decoding the full frame
+ *
+ * Useful for routing frames to the right decryption key.
+ *
+ * @param data - Raw buffer from the wire
+ * @returns Stream ID, or null if buffer too short
+ */
+export function peekStreamId(data: Buffer | Uint8Array): number | null {
+  if (data.length < STREAM_ID_LENGTH) {
+    return null;
+  }
+
+  return Buffer.from(data).readUInt32BE(0);
+}
+
+/**
+ * Create an encrypted frame from plaintext data
+ *
+ * @param streamId - Stream ID (0 = master, 1+ = session)
+ * @param data - Plaintext data to encrypt
+ * @param key - Encryption key (from deriveKey)
+ * @returns Encoded frame buffer ready to send
+ */
+export function createFrame(
+  streamId: number,
+  data: Uint8Array | Buffer,
+  key: Uint8Array | Buffer
+): Buffer {
+  const { nonce, ciphertext } = encrypt(data, key);
+
+  return encodeFrame({
+    streamId,
+    nonce,
+    ciphertext,
+  });
+}
+
+/**
+ * Decrypt a frame and return the plaintext
+ *
+ * @param frame - Encoded frame buffer from the wire
+ * @param key - Decryption key (from deriveKey)
+ * @returns Decrypted plaintext, or null if decryption failed
+ */
+export function openFrame(
+  frame: Buffer | Uint8Array,
+  key: Uint8Array | Buffer
+): { streamId: number; data: Buffer } | null {
+  const decoded = decodeFrame(frame);
+  if (!decoded) {
+    return null;
+  }
+
+  const data = decrypt(decoded.ciphertext, decoded.nonce, key);
+  if (!data) {
+    return null;
+  }
+
+  return { streamId: decoded.streamId, data };
+}