gitspace 0.2.0-rc.1

package/src/types/bundle.ts

@@ -0,0 +1,112 @@
+/**
+ * Type definitions for Spaces bundle configuration
+ */
+
+/**
+ * Onboarding step types
+ */
+export type OnboardingStepType = 'info' | 'confirm' | 'secret' | 'input';
+
+/**
+ * Base interface for all onboarding steps
+ */
+interface BaseOnboardingStep {
+  /** Unique identifier for the step */
+  id: string;
+  /** Step type */
+  type: OnboardingStepType;
+  /** Display title for the step */
+  title: string;
+  /** Description/instructions for the user */
+  description: string;
+  /** Whether this step is required (default: true) */
+  required?: boolean;
+}
+
+/**
+ * Info step - Display information, user just acknowledges
+ */
+export interface InfoStep extends BaseOnboardingStep {
+  type: 'info';
+}
+
+/**
+ * Confirm step - Verify something is installed or done
+ */
+export interface ConfirmStep extends BaseOnboardingStep {
+  type: 'confirm';
+  /** Command to check if installed (optional) */
+  checkCommand?: string;
+  /** URL for installation instructions (optional) */
+  installUrl?: string;
+  /** Confirmation prompt text (default: "Continue?") */
+  confirmPrompt?: string;
+}
+
+/**
+ * Secret step - Collect sensitive value (masked input)
+ */
+export interface SecretStep extends BaseOnboardingStep {
+  type: 'secret';
+  /** Key to store the value under in project config */
+  configKey: string;
+  /** Validation regex pattern (optional) */
+  validationPattern?: string;
+  /** Validation error message (optional) */
+  validationMessage?: string;
+}
+
+/**
+ * Input step - Collect non-secret value
+ */
+export interface InputStep extends BaseOnboardingStep {
+  type: 'input';
+  /** Key to store the value under in project config */
+  configKey: string;
+  /** Default value (optional) */
+  defaultValue?: string;
+  /** Validation regex pattern (optional) */
+  validationPattern?: string;
+  /** Validation error message (optional) */
+  validationMessage?: string;
+}
+
+export type OnboardingStep = InfoStep | ConfirmStep | SecretStep | InputStep;
+
+/**
+ * Bundle manifest schema (bundle.json)
+ */
+export interface SpacesBundle {
+  /** Bundle schema version */
+  version: '1.0';
+  /** Bundle name (for display) */
+  name: string;
+  /** Bundle description (optional) */
+  description?: string;
+  /** Onboarding steps to run before project setup */
+  onboarding?: OnboardingStep[];
+}
+
+/**
+ * Result of running onboarding steps
+ */
+export interface OnboardingResult {
+  /** Values to store in project config */
+  configValues: Record<string, string>;
+  /** Whether onboarding completed successfully */
+  completed: boolean;
+  /** Step ID where user cancelled (if applicable) */
+  cancelledAt?: string;
+}
+
+/**
+ * Loaded bundle with source information
+ */
+export interface LoadedBundle {
+  /** The bundle manifest */
+  bundle: SpacesBundle;
+  /** Path to the bundle directory (for script copying) */
+  bundleDir: string;
+  /** Source description for logging */
+  source: string;
+}

package/src/types/config.ts

@@ -0,0 +1,89 @@
+/**
+ * Type definitions for GitSpace CLI configuration
+ */
+
+/**
+ * Global configuration stored in ~/gitspace/.config.json
+ */
+export interface GlobalConfig {
+  /** Name of the currently active project */
+  currentProject: string | null;
+  /** Path to the projects directory (default: ~/gitspace) */
+  projectsDir: string;
+  /** Default base branch for new projects (default: "main") */
+  defaultBaseBranch: string;
+  /** Number of days before a workspace is considered stale (default: 30) */
+  staleDays: number;
+}
+
+/**
+ * Information about an applied bundle
+ */
+export interface AppliedBundle {
+  /** Bundle name */
+  name: string;
+  /** Bundle version */
+  version: string;
+  /** Source of the bundle (path or URL) */
+  source: string;
+  /** ISO timestamp when bundle was applied */
+  appliedAt: string;
+}
+
+/**
+ * Project-specific configuration stored in ~/gitspace/{PROJECT_NAME}/.config.json
+ */
+export interface ProjectConfig {
+  /** Project name */
+  name: string;
+  /** GitHub repository in owner/repo format */
+  repository: string;
+  /** Base branch for creating worktrees */
+  baseBranch: string;
+  /** Optional Linear API key for issue integration */
+  linearApiKey?: string;
+  /** Optional Linear team key for filtering issues (e.g., "ENG") */
+  linearTeamKey?: string;
+  /** ISO timestamp when project was created */
+  createdAt: string;
+  /** ISO timestamp when project was last accessed */
+  lastAccessed: string;
+  /** Custom values collected during bundle onboarding (from input steps) */
+  bundleValues?: Record<string, string>;
+  /** Keys of secrets stored in OS keychain via Bun.secrets (from secret steps) */
+  bundleSecretKeys?: string[];
+  /** Information about the bundle that was applied */
+  appliedBundle?: AppliedBundle;
+}
+
+/**
+ * Default global configuration values
+ */
+export const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
+  currentProject: null,
+  projectsDir: '', // Will be set to ~/gitspace at runtime
+  defaultBaseBranch: 'main',
+  staleDays: 30,
+};
+
+/**
+ * Create default project configuration
+ */
+export function createDefaultProjectConfig(
+  name: string,
+  repository: string,
+  baseBranch: string,
+  linearApiKey?: string,
+  linearTeamKey?: string
+): ProjectConfig {
+  const now = new Date().toISOString();
+  return {
+    name,
+    repository,
+    baseBranch,
+    linearApiKey,
+    linearTeamKey,
+    createdAt: now,
+    lastAccessed: now,
+  };
+}

package/src/types/errors.ts

@@ -0,0 +1,206 @@
+/**
+ * Custom error types for GitSpace CLI
+ */
+
+export type ErrorCode = 'USER_ERROR' | 'SYSTEM_ERROR' | 'SERVICE_ERROR';
+
+/**
+ * Base error class for GitSpace CLI
+ */
+export class SpacesError extends Error {
+  public readonly code: ErrorCode;
+  public readonly exitCode: number;
+
+  constructor(message: string, code: ErrorCode = 'USER_ERROR', exitCode?: number) {
+    super(message);
+    this.name = 'SpacesError';
+    this.code = code;
+
+    // Set exit code based on error type if not provided
+    if (exitCode !== undefined) {
+      this.exitCode = exitCode;
+    } else {
+      switch (code) {
+        case 'USER_ERROR':
+          this.exitCode = 1;
+          break;
+        case 'SYSTEM_ERROR':
+          this.exitCode = 2;
+          break;
+        case 'SERVICE_ERROR':
+          this.exitCode = 3;
+          break;
+      }
+    }
+
+    // Maintains proper stack trace for where error was thrown
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Error thrown when a dependency is missing
+ */
+export class DependencyError extends SpacesError {
+  constructor(message: string) {
+    super(message, 'SYSTEM_ERROR', 2);
+    this.name = 'DependencyError';
+  }
+}
+
+/**
+ * Error thrown when GitHub CLI is not authenticated
+ */
+export class GitHubAuthError extends SpacesError {
+  constructor() {
+    super(
+      '✗ Error: GitHub CLI is not authenticated\n\nPlease run: gh auth login\n\nThen try again.',
+      'SYSTEM_ERROR',
+      2
+    );
+    this.name = 'GitHubAuthError';
+  }
+}
+
+/**
+ * Error thrown when a project already exists
+ */
+export class ProjectExistsError extends SpacesError {
+  constructor(projectName: string, projectPath: string) {
+    super(
+      `✗ Error: Project "${projectName}" already exists\n\nThe directory ${projectPath} already contains a project.\n\nTo use this project:\n  gssh switch project ${projectName}\n\nTo remove and recreate:\n  gssh remove project ${projectName}\n  gssh add project`,
+      'USER_ERROR',
+      1
+    );
+    this.name = 'ProjectExistsError';
+  }
+}
+
+/**
+ * Error thrown when a workspace already exists
+ */
+export class WorkspaceExistsError extends SpacesError {
+  constructor(workspaceName: string) {
+    super(
+      `✗ Error: Workspace "${workspaceName}" already exists\n\nTo switch to this workspace:\n  gssh switch ${workspaceName}`,
+      'USER_ERROR',
+      1
+    );
+    this.name = 'WorkspaceExistsError';
+  }
+}
+
+/**
+ * Error thrown when no project is selected
+ */
+export class NoProjectError extends SpacesError {
+  constructor() {
+    super(
+      '✗ Error: No project selected\n\nPlease add a project first:\n  gssh add project\n\nOr switch to an existing project:\n  gssh switch project',
+      'USER_ERROR',
+      1
+    );
+    this.name = 'NoProjectError';
+  }
+}
+
+// ============================================================================
+// Identity & Access Control Errors
+// ============================================================================
+
+/**
+ * Error thrown when identity is not initialized
+ */
+export class NoIdentityError extends SpacesError {
+  constructor() {
+    super(
+      '✗ Error: No identity found\n\nInitialize your identity first:\n  gssh identity init',
+      'USER_ERROR',
+      1
+    );
+    this.name = 'NoIdentityError';
+  }
+}
+
+/**
+ * Error thrown when password is incorrect for keypair decryption
+ */
+export class InvalidPasswordError extends SpacesError {
+  constructor() {
+    super(
+      '✗ Error: Invalid password\n\nThe password you entered is incorrect.',
+      'USER_ERROR',
+      1
+    );
+    this.name = 'InvalidPasswordError';
+  }
+}
+
+/**
+ * Error thrown when client is not in access list
+ */
+export class AccessDeniedError extends SpacesError {
+  constructor(identityId?: string) {
+    const msg = identityId
+      ? `✗ Error: Access denied for identity ${identityId}\n\nThis identity is not in the access list.`
+      : '✗ Error: Access denied\n\nYou are not authorized to connect to this machine.';
+    super(msg, 'USER_ERROR', 1);
+    this.name = 'AccessDeniedError';
+  }
+}
+
+/**
+ * Error thrown when invite token is invalid or expired
+ */
+export class InvalidInviteError extends SpacesError {
+  constructor(reason: string = 'Invalid or expired invite') {
+    super(
+      `✗ Error: ${reason}\n\nThe invite link may have expired or been revoked.`,
+      'USER_ERROR',
+      1
+    );
+    this.name = 'InvalidInviteError';
+  }
+}
+
+/**
+ * Error thrown when handshake protocol fails
+ */
+export class HandshakeFailedError extends SpacesError {
+  constructor(reason: string = 'Handshake failed') {
+    super(
+      `✗ Error: ${reason}\n\nCould not establish secure connection.`,
+      'SERVICE_ERROR',
+      3
+    );
+    this.name = 'HandshakeFailedError';
+  }
+}
+
+/**
+ * Error thrown when identity already exists
+ */
+export class IdentityExistsError extends SpacesError {
+  constructor() {
+    super(
+      '✗ Error: Identity already exists\n\nTo overwrite, use:\n  gssh identity init --force',
+      'USER_ERROR',
+      1
+    );
+    this.name = 'IdentityExistsError';
+  }
+}
+
+/**
+ * Error thrown when public key format is invalid
+ */
+export class InvalidPublicKeyError extends SpacesError {
+  constructor(reason: string = 'Invalid public key format') {
+    super(
+      `✗ Error: ${reason}\n\nPublic keys should be base64-encoded Ed25519 or X25519 keys.`,
+      'USER_ERROR',
+      1
+    );
+    this.name = 'InvalidPublicKeyError';
+  }
+}

package/src/types/identity.ts

@@ -0,0 +1,284 @@
+/**
+ * Type definitions for identity and access control
+ */
+
+// ============================================================================
+// Keypair Types
+// ============================================================================
+
+/** Ed25519 signing keypair */
+export interface SigningKeypair {
+  /** 32-byte public key */
+  publicKey: Uint8Array;
+  /** 64-byte secret key (includes public key suffix per Ed25519 convention) */
+  secretKey: Uint8Array;
+}
+
+/** X25519 key exchange keypair */
+export interface KeyExchangeKeypair {
+  /** 32-byte public key */
+  publicKey: Uint8Array;
+  /** 32-byte private key */
+  privateKey: Uint8Array;
+}
+
+// ============================================================================
+// Identity Types
+// ============================================================================
+
+/** Complete identity (signing + key exchange) */
+export interface Identity {
+  /** Unique identifier derived from signing public key (first 16 chars of base64url) */
+  id: string;
+  /** Ed25519 keypair for signing */
+  signing: SigningKeypair;
+  /** X25519 keypair for key exchange */
+  keyExchange: KeyExchangeKeypair;
+  /** Human-readable label */
+  label?: string;
+  /** Creation timestamp (Unix ms) */
+  createdAt: number;
+}
+
+/** Serializable identity for JSON storage (base64 encoded keys) */
+export interface StoredIdentity {
+  id: string;
+  signingPublicKey: string;
+  /** Encrypted with password-derived key */
+  signingSecretKey: string;
+  keyExchangePublicKey: string;
+  /** Encrypted with password-derived key */
+  keyExchangePrivateKey: string;
+  label?: string;
+  createdAt: number;
+}
+
+/** Public identity info (safe to share) */
+export interface PublicIdentity {
+  id: string;
+  signingPublicKey: string;
+  keyExchangePublicKey: string;
+  label?: string;
+}
+
+// ============================================================================
+// Access Control Types
+// ============================================================================
+
+/**
+ * Access type for a client
+ * - 'full': Complete machine access (browse, create sessions, etc.)
+ * - 'session-invite': View-only access to a specific session
+ */
+export type AccessType = 'full' | 'session-invite';
+
+/**
+ * @deprecated Use AccessType instead. Kept for backwards compatibility during migration.
+ */
+export interface AccessPermissions {
+  /** Can read terminal output */
+  read: boolean;
+  /** Can send terminal input */
+  write: boolean;
+  /** Can manage sessions (create/kill) */
+  manage: boolean;
+}
+
+/** Helper to convert AccessType to legacy AccessPermissions */
+export function accessTypeToPermissions(accessType: AccessType): AccessPermissions {
+  if (accessType === 'full') {
+    return { read: true, write: true, manage: true };
+  }
+  // session-invite is read-only
+  return { read: true, write: false, manage: false };
+}
+
+/** Helper to convert legacy AccessPermissions to AccessType */
+export function permissionsToAccessType(permissions: AccessPermissions): AccessType {
+  if (permissions.write || permissions.manage) {
+    return 'full';
+  }
+  return 'session-invite';
+}
+
+/** Access list entry for authorized public keys */
+export interface AccessEntry {
+  /** Identity ID (derived from signing public key) */
+  identityId: string;
+  /** Public signing key (base64) */
+  signingPublicKey: string;
+  /** Public key exchange key (base64) */
+  keyExchangePublicKey: string;
+  /** Human-readable label */
+  label?: string;
+  /** When access was granted (Unix ms) */
+  grantedAt: number;
+  /** Access type granted */
+  accessType: AccessType;
+  /** Optional expiry time (Unix ms) */
+  expiresAt?: number;
+  /** For session-invite: the specific session ID this grants access to */
+  sessionId?: string;
+}
+
+// ============================================================================
+// Invite Token Types
+// ============================================================================
+
+/** Signed invite token for sharing access */
+export interface InviteToken {
+  /** Token version */
+  version: 1;
+  /** Machine's identity ID */
+  machineId: string;
+  /** Machine's public signing key (base64) */
+  machineSigningKey: string;
+  /** Machine's public key exchange key (base64) */
+  machineKeyExchangeKey: string;
+  /** Relay URL to connect */
+  relayUrl: string;
+  /** Access type being granted */
+  accessType: AccessType;
+  /** For session-invite: the specific session ID */
+  sessionId?: string;
+  /** Expiry timestamp (Unix ms) */
+  expiresAt: number;
+  /** Single use? */
+  singleUse: boolean;
+  /** Signature over token data (base64) */
+  signature: string;
+}
+
+/** Options for creating an invite token */
+export interface CreateInviteOptions {
+  /** Access type to grant (default: 'session-invite') */
+  accessType?: AccessType;
+  /** For session-invite: the specific session ID */
+  sessionId?: string;
+  /** Validity duration in milliseconds */
+  validityMs?: number;
+  /** Whether invite can only be used once */
+  singleUse?: boolean;
+}
+
+// ============================================================================
+// Session Key Types
+// ============================================================================
+
+/** Derived session keys from handshake */
+export interface SessionKeys {
+  /** Key for encrypting data we send (32 bytes) */
+  sendKey: Uint8Array;
+  /** Key for decrypting data we receive (32 bytes) */
+  receiveKey: Uint8Array;
+  /** Session ID (for key rotation tracking) */
+  sessionId: string;
+}
+
+// ============================================================================
+// Handshake Message Types
+// ============================================================================
+
+/** X3DH handshake initiation message from client */
+export interface X3DHInitMessage {
+  /** Protocol version */
+  version: 1;
+  /** Client's ephemeral X25519 public key (base64) */
+  ephemeralKey: string;
+  /** Timestamp for replay protection (Unix ms) */
+  timestamp: number;
+  /** Client nonce (base64, 32 bytes random) */
+  clientNonce: string;
+  /** Optional: Machine ID hint for routing */
+  machineIdHint?: string;
+}
+
+/** X3DH response message from machine */
+export interface X3DHResponseMessage {
+  /** Protocol version */
+  version: 1;
+  /** Machine's identity public key - Ed25519 (base64) */
+  identityKey: string;
+  /** Machine's key exchange public key - X25519 (base64) */
+  keyExchangeKey: string;
+  /** Machine's ephemeral X25519 public key (base64) */
+  ephemeralKey: string;
+  /** Machine's signed pre-key - X25519 (base64) */
+  signedPreKey: string;
+  /** Signature over signedPreKey using identity key (base64) */
+  preKeySignature: string;
+  /** Server nonce (base64, 32 bytes random) */
+  serverNonce: string;
+  /** Timestamp (Unix ms) */
+  timestamp: number;
+}
+
+/** Client authentication message */
+export interface X3DHAuthMessage {
+  /** Protocol version */
+  version: 1;
+  /** Client's identity public key - Ed25519 (base64) */
+  identityKey: string;
+  /** Client's key exchange public key - X25519 (base64) */
+  keyExchangeKey: string;
+  /** HMAC proof binding client identity to session (base64) */
+  identityProof: string;
+  /**
+   * Ed25519 signature over handshake transcript proving key ownership (base64).
+   * Signs: clientEphemeral || serverEphemeral || clientNonce || serverNonce
+   * This proves the client possesses the private key for identityKey.
+   */
+  identitySignature: string;
+  /** Authorization type and data */
+  authorization:
+    | { type: "access_list" }
+    | { type: "invite"; inviteToken: string };
+}
+
+/** Server authentication/result message */
+export interface X3DHResultMessage {
+  /** Protocol version */
+  version: 1;
+  /** Machine's identity public key (base64) */
+  identityKey: string;
+  /** HMAC proof binding machine identity to session (base64) */
+  identityProof: string;
+  /** Authorization result */
+  result:
+    | { type: "accepted"; accessType: AccessType; sessionId?: string }
+    | { type: "rejected"; reason: string };
+}
+
+/** Handshake state phases */
+export type HandshakePhase =
+  | "idle"
+  | "awaiting_server_hello"
+  | "awaiting_client_auth"
+  | "awaiting_server_auth"
+  | "established"
+  | "failed";
+
+/** Handshake result on success */
+export interface X3DHHandshakeResult {
+  sessionKeys: SessionKeys;
+  peerIdentityId: string;
+  accessType: AccessType;
+  /** For session-invite: the specific session ID access was granted to */
+  sessionId?: string;
+}
+
+// ============================================================================
+// Machine Identity Types
+// ============================================================================
+
+/** Machine identity configuration stored locally */
+export interface MachineIdentity {
+  /** Unique machine ID (same as identity.id) */
+  machineId: string;
+  /** Human-readable machine name */
+  machineName: string;
+  /** Relay server URL this machine uses */
+  relayUrl: string;
+  /** ISO timestamp when registered */
+  registeredAt: string;
+}