gitspace 0.2.0-rc.1

package/src/core/__tests__/access.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Access List Tests
+ *
+ * Tests for access list file operations and entry validation.
+ * Covers edge cases discovered in production.
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { existsSync, unlinkSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  readAccessList,
+  writeAccessList,
+  addAccess,
+  removeAccess,
+  getAccessEntry,
+  parsePublicKey,
+} from "../access";
+import type { AccessEntry, PublicIdentity } from "../../types/identity";
+
+// Use a temp directory for tests to avoid affecting real config
+const TEST_DIR = join(tmpdir(), `spaces-test-${Date.now()}`);
+const TEST_ACCESS_PATH = join(TEST_DIR, ".access.json");
+
+// Mock getSpacesDir to use test directory
+let originalGetSpacesDir: () => string;
+
+beforeEach(() => {
+  // Create test directory
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  // Cleanup test directory
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+describe("readAccessList", () => {
+  test("returns empty array when file does not exist", () => {
+    // Note: This test uses the real getSpacesDir, so it may return
+    // actual entries if the file exists. For unit testing, we'd need
+    // to mock getSpacesDir or use dependency injection.
+    // This is more of an integration test pattern.
+  });
+
+  test("parses valid JSON access list", () => {
+    const entries: AccessEntry[] = [
+      {
+        identityId: "test123",
+        signingPublicKey: "signingKey123",
+        keyExchangePublicKey: "keyExchangeKey123",
+        label: "Test Device",
+        grantedAt: Date.now(),
+        accessType: "full",
+      },
+    ];
+    writeFileSync(TEST_ACCESS_PATH, JSON.stringify(entries), "utf-8");
+
+    // Would need to mock getAccessListPath to use TEST_ACCESS_PATH
+  });
+});
+
+describe("AccessEntry validation", () => {
+  /**
+   * These tests document the expected shape of access entries
+   * and what fields are required for proper protocol communication.
+   */
+
+  test("valid entry has all required fields", () => {
+    const validEntry: AccessEntry = {
+      identityId: "vyPe20Hv1pnlKo89",
+      signingPublicKey: "vyPe20Hv1pnlKo89BOvn5XuJzPXarq5/hjim96fZ/dM=",
+      keyExchangePublicKey: "/NOCKBrpy+5hST69/NF2rXutunFakeKey123456789=",
+      label: "Test Device",
+      grantedAt: Date.now(),
+      accessType: "full",
+    };
+
+    expect(validEntry.identityId).toBeTruthy();
+    expect(validEntry.signingPublicKey).toBeTruthy();
+    expect(validEntry.keyExchangePublicKey).toBeTruthy();
+    expect(validEntry.accessType).toBe("full");
+  });
+
+  test("entry with missing keyExchangePublicKey is invalid for relay sync", () => {
+    const invalidEntry = {
+      identityId: "vyPe20Hv1pnlKo89",
+      signingPublicKey: "vyPe20Hv1pnlKo89BOvn5XuJzPXarq5/hjim96fZ/dM=",
+      keyExchangePublicKey: "", // Empty - will fail protocol validation
+      label: "Test Device",
+      grantedAt: Date.now(),
+      accessType: "full" as const,
+    };
+
+    expect(invalidEntry.keyExchangePublicKey).toBeFalsy();
+  });
+
+  test("entry with missing accessType is invalid for relay sync", () => {
+    const legacyEntry = {
+      identityId: "vyPe20Hv1pnlKo89",
+      signingPublicKey: "vyPe20Hv1pnlKo89BOvn5XuJzPXarq5/hjim96fZ/dM=",
+      keyExchangePublicKey: "/NOCKBrpy+5hST69/NF2rXutunFakeKey123456789=",
+      label: "Legacy Device",
+      grantedAt: Date.now(),
+      // accessType is missing - legacy entry before schema update
+    };
+
+    expect((legacyEntry as any).accessType).toBeUndefined();
+  });
+
+  test("accessType must be 'full' or 'session-invite'", () => {
+    const validTypes = ["full", "session-invite"];
+    const invalidTypes = ["admin", "read-only", "", null, undefined];
+
+    for (const type of validTypes) {
+      expect(type === "full" || type === "session-invite").toBe(true);
+    }
+
+    for (const type of invalidTypes) {
+      expect(type === "full" || type === "session-invite").toBe(false);
+    }
+  });
+});
+
+describe("parsePublicKey", () => {
+  test("parses full format gssh-pub:SIGNING:KEYEXCHANGE", () => {
+    // Generate valid test keys (32 bytes each, base64 encoded)
+    const signingKey = Buffer.from(new Uint8Array(32).fill(1)).toString("base64");
+    const keyExchangeKey = Buffer.from(new Uint8Array(32).fill(2)).toString("base64");
+    const pubkeyString = `gssh-pub:${signingKey}:${keyExchangeKey}`;
+
+    const result = parsePublicKey(pubkeyString);
+
+    expect(result.signingPublicKey).toBe(signingKey);
+    expect(result.keyExchangePublicKey).toBe(keyExchangeKey);
+    expect(result.id).toBeTruthy(); // Derived from signing key
+  });
+
+  test("parses signing key only format", () => {
+    const signingKey = Buffer.from(new Uint8Array(32).fill(1)).toString("base64");
+
+    const result = parsePublicKey(signingKey);
+
+    expect(result.signingPublicKey).toBe(signingKey);
+    expect(result.keyExchangePublicKey).toBe(""); // Empty - needs to be provided separately
+    expect(result.id).toBeTruthy();
+  });
+
+  test("throws for invalid format", () => {
+    expect(() => parsePublicKey("gssh-pub:only-one-part")).toThrow();
+    expect(() => parsePublicKey("gssh-pub:a:b:c:d")).toThrow();
+  });
+
+  test("throws for invalid base64", () => {
+    expect(() => parsePublicKey("not-valid-base64!!!")).toThrow();
+  });
+
+  test("throws for wrong key length", () => {
+    const shortKey = Buffer.from(new Uint8Array(16)).toString("base64"); // 16 bytes, not 32
+    expect(() => parsePublicKey(shortKey)).toThrow();
+  });
+});
+
+describe("access entry validation helper", () => {
+  /**
+   * Helper function to validate an access entry has all required fields
+   * for relay protocol communication.
+   */
+  function isValidAccessEntry(entry: Partial<AccessEntry>): boolean {
+    if (!entry.identityId || entry.identityId.length === 0) return false;
+    if (!entry.signingPublicKey || entry.signingPublicKey.length === 0) return false;
+    if (!entry.keyExchangePublicKey || entry.keyExchangePublicKey.length === 0) return false;
+    if (entry.accessType !== "full" && entry.accessType !== "session-invite") return false;
+    return true;
+  }
+
+  test("validates complete entry", () => {
+    const entry: AccessEntry = {
+      identityId: "test123",
+      signingPublicKey: "signingKey",
+      keyExchangePublicKey: "keyExchangeKey",
+      label: "Test",
+      grantedAt: Date.now(),
+      accessType: "full",
+    };
+    expect(isValidAccessEntry(entry)).toBe(true);
+  });
+
+  test("rejects entry with empty identityId", () => {
+    const entry = {
+      identityId: "",
+      signingPublicKey: "signingKey",
+      keyExchangePublicKey: "keyExchangeKey",
+      accessType: "full" as const,
+    };
+    expect(isValidAccessEntry(entry)).toBe(false);
+  });
+
+  test("rejects entry with empty signingPublicKey", () => {
+    const entry = {
+      identityId: "test123",
+      signingPublicKey: "",
+      keyExchangePublicKey: "keyExchangeKey",
+      accessType: "full" as const,
+    };
+    expect(isValidAccessEntry(entry)).toBe(false);
+  });
+
+  test("rejects entry with empty keyExchangePublicKey", () => {
+    const entry = {
+      identityId: "test123",
+      signingPublicKey: "signingKey",
+      keyExchangePublicKey: "",
+      accessType: "full" as const,
+    };
+    expect(isValidAccessEntry(entry)).toBe(false);
+  });
+
+  test("rejects entry with undefined accessType", () => {
+    const entry = {
+      identityId: "test123",
+      signingPublicKey: "signingKey",
+      keyExchangePublicKey: "keyExchangeKey",
+    };
+    expect(isValidAccessEntry(entry)).toBe(false);
+  });
+
+  test("rejects entry with invalid accessType", () => {
+    const entry = {
+      identityId: "test123",
+      signingPublicKey: "signingKey",
+      keyExchangePublicKey: "keyExchangeKey",
+      accessType: "admin" as any,
+    };
+    expect(isValidAccessEntry(entry)).toBe(false);
+  });
+});

package/src/core/access.ts

@@ -0,0 +1,277 @@
+/**
+ * Access control list management
+ * Provides file-based storage and management of authorized identities
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { join, dirname } from 'path';
+import type { AccessEntry, AccessType, PublicIdentity } from '../types/identity.js';
+import { deriveIdentityId } from '../lib/tmux-lite/crypto/identity.js';
+import { getSpacesDir } from './config.js';
+import { SpacesError } from '../types/errors.js';
+
+/**
+ * Get the access list file path
+ */
+export function getAccessListPath(): string {
+  return join(getSpacesDir(), '.access.json');
+}
+
+/**
+ * Read the access list from disk
+ * @returns Array of access entries
+ */
+export function readAccessList(): AccessEntry[] {
+  const accessPath = getAccessListPath();
+
+  if (!existsSync(accessPath)) {
+    return [];
+  }
+
+  try {
+    const content = readFileSync(accessPath, 'utf-8');
+    return JSON.parse(content) as AccessEntry[];
+  } catch (error) {
+    throw new SpacesError(
+      `Failed to read access list: ${error instanceof Error ? error.message : String(error)}`,
+      'SYSTEM_ERROR',
+      2
+    );
+  }
+}
+
+/**
+ * Write the access list to disk
+ * @param entries - Array of access entries to write
+ */
+export function writeAccessList(entries: AccessEntry[]): void {
+  const accessPath = getAccessListPath();
+  const spacesDir = dirname(accessPath);
+
+  // Ensure spaces directory exists
+  if (!existsSync(spacesDir)) {
+    mkdirSync(spacesDir, { recursive: true });
+  }
+
+  try {
+    writeFileSync(accessPath, JSON.stringify(entries, null, 2), 'utf-8');
+    chmodSync(accessPath, 0o600);
+  } catch (error) {
+    throw new SpacesError(
+      `Failed to write access list: ${error instanceof Error ? error.message : String(error)}`,
+      'SYSTEM_ERROR',
+      2
+    );
+  }
+}
+
+/**
+ * Add a new access entry
+ * @param publicIdentity - Public identity to add
+ * @param label - Human-readable label
+ * @param accessType - Access type to grant (default: 'full')
+ * @param sessionId - For session-invite: the specific session ID
+ * @returns The created access entry
+ */
+export function addAccess(
+  publicIdentity: PublicIdentity,
+  label?: string,
+  accessType: AccessType = 'full',
+  sessionId?: string
+): AccessEntry {
+  const entries = readAccessList();
+
+  // Check if identity already exists
+  const existingIndex = entries.findIndex(
+    (e) => e.identityId === publicIdentity.id
+  );
+
+  const entry: AccessEntry = {
+    identityId: publicIdentity.id,
+    signingPublicKey: publicIdentity.signingPublicKey,
+    keyExchangePublicKey: publicIdentity.keyExchangePublicKey,
+    label: label || publicIdentity.label,
+    grantedAt: Date.now(),
+    accessType,
+    sessionId,
+  };
+
+  if (existingIndex >= 0) {
+    // Replace existing entry
+    entries[existingIndex] = entry;
+  } else {
+    // Add new entry
+    entries.push(entry);
+  }
+
+  writeAccessList(entries);
+  return entry;
+}
+
+/**
+ * Remove an access entry by identity ID or label
+ * @param identityIdOrLabel - Identity ID (full or prefix) or label (case-insensitive)
+ * @returns The removed entry, or null if not found
+ */
+export function removeAccess(identityIdOrLabel: string): AccessEntry | null {
+  const entries = readAccessList();
+  const searchTerm = identityIdOrLabel.toLowerCase();
+
+  // Try to find by identity ID prefix or exact label match
+  const index = entries.findIndex((e) => {
+    const matchesId = e.identityId.toLowerCase().startsWith(searchTerm);
+    const matchesLabel = e.label?.toLowerCase() === searchTerm;
+    return matchesId || matchesLabel;
+  });
+
+  if (index < 0) {
+    return null;
+  }
+
+  const removed = entries[index];
+  entries.splice(index, 1);
+  writeAccessList(entries);
+
+  return removed;
+}
+
+/**
+ * Get an access entry by identity ID or label
+ * @param identityIdOrLabel - Identity ID (full or prefix) or label (case-insensitive)
+ * @returns The access entry, or null if not found
+ */
+export function getAccessEntry(identityIdOrLabel: string): AccessEntry | null {
+  const entries = readAccessList();
+  const searchTerm = identityIdOrLabel.toLowerCase();
+
+  // Try to find by identity ID prefix or exact label match
+  return (
+    entries.find((e) => {
+      const matchesId = e.identityId.toLowerCase().startsWith(searchTerm);
+      const matchesLabel = e.label?.toLowerCase() === searchTerm;
+      return matchesId || matchesLabel;
+    }) || null
+  );
+}
+
+/**
+ * Parse a public key string
+ * Supports formats:
+ * - Full format: gssh-pub:SIGNING_KEY:KEYEXCHANGE_KEY
+ * - Just signing key: BASE64_SIGNING_KEY
+ *
+ * @param pubkeyString - Public key string to parse
+ * @returns Public identity
+ * @throws {SpacesError} If format is invalid
+ */
+export function parsePublicKey(pubkeyString: string): PublicIdentity {
+  const trimmed = pubkeyString.trim();
+
+  if (trimmed.startsWith('gssh-pub:')) {
+    // Full format: gssh-pub:SIGNING_KEY:KEYEXCHANGE_KEY
+    const parts = trimmed.split(':');
+    if (parts.length !== 3) {
+      throw new SpacesError(
+        'Invalid public key format. Expected: gssh-pub:SIGNING_KEY:KEYEXCHANGE_KEY',
+        'USER_ERROR',
+        1
+      );
+    }
+
+    const [, signingKey, keyExchangeKey] = parts;
+
+    // Validate base64
+    if (!isValidBase64(signingKey) || !isValidBase64(keyExchangeKey)) {
+      throw new SpacesError(
+        'Invalid base64 encoding in public key',
+        'USER_ERROR',
+        1
+      );
+    }
+
+    // Derive identity ID from signing key
+    try {
+      const signingPublicKey = Buffer.from(signingKey, 'base64');
+      if (signingPublicKey.length !== 32) {
+        throw new Error('Signing key must be 32 bytes');
+      }
+
+      const identityId = deriveIdentityId(new Uint8Array(signingPublicKey));
+
+      return {
+        id: identityId,
+        signingPublicKey: signingKey,
+        keyExchangePublicKey: keyExchangeKey,
+      };
+    } catch (error) {
+      throw new SpacesError(
+        `Failed to parse public key: ${error instanceof Error ? error.message : String(error)}`,
+        'USER_ERROR',
+        1
+      );
+    }
+  } else {
+    // Just signing key format: BASE64_SIGNING_KEY
+    if (!isValidBase64(trimmed)) {
+      throw new SpacesError(
+        'Invalid base64 encoding in public key',
+        'USER_ERROR',
+        1
+      );
+    }
+
+    try {
+      const signingPublicKey = Buffer.from(trimmed, 'base64');
+      if (signingPublicKey.length !== 32) {
+        throw new SpacesError(
+          'Signing key must be 32 bytes (expected ~43 characters in base64)',
+          'USER_ERROR',
+          1
+        );
+      }
+
+      const identityId = deriveIdentityId(new Uint8Array(signingPublicKey));
+
+      return {
+        id: identityId,
+        signingPublicKey: trimmed,
+        keyExchangePublicKey: '', // Will need to be provided separately
+      };
+    } catch (error) {
+      throw new SpacesError(
+        `Failed to parse signing key: ${error instanceof Error ? error.message : String(error)}`,
+        'USER_ERROR',
+        1
+      );
+    }
+  }
+}
+
+/**
+ * Check if a string is valid base64 or base64url
+ */
+function isValidBase64(str: string): boolean {
+  // Match standard base64 or base64url (with - and _ instead of + and /)
+  return /^[A-Za-z0-9+/\-_]*={0,2}$/.test(str) && str.length > 0;
+}
+
+/**
+ * Format an access entry's fingerprint for display
+ * Shows first 12 chars of identity ID
+ */
+export function formatFingerprint(identityId: string): string {
+  return identityId.slice(0, 12) + '...';
+}
+
+/**
+ * Format access type for display
+ */
+export function formatAccessType(accessType: AccessType, sessionId?: string): string {
+  if (accessType === 'full') {
+    return 'full access';
+  }
+  if (sessionId) {
+    return `session invite (${sessionId})`;
+  }
+  return 'session invite';
+}