teleportation-cli 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# Teleportation
+
+**Remote approval system for Claude Code**
+
+Approve AI coding changes from your phone—work continues while you're away.
+
+## Overview
+
+Teleportation enables developers to approve Claude Code actions remotely from any device. The system intercepts Claude Code's tool requests via hooks, routes them to a relay API, and displays them in a mobile-friendly UI for instant approval.
+
+## Installation
+
+### Method 1: Quick Install (curl)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dundas/teleportation-private/main/scripts/install.sh | bash
+```
+
+### Method 2: From Source (Recommended)
+
+**Requirements:** Bun >=1.3.0
+
+```bash
+# Install Bun if you haven't already
+curl -fsSL https://bun.sh/install | bash
+
+# Clone and install
+git clone https://github.com/dundas/teleportation-private.git
+cd teleportation-private
+bun install
+bun link  # Makes 'teleportation' command available globally
+```
+
+### Method 3: GitHub Releases
+
+Download the latest release from [GitHub Releases](https://github.com/dundas/teleportation-private/releases/latest) and extract to `~/.teleportation/`.
+
+## Requirements
+
+- **Bun >=1.3.0** (JavaScript runtime)
+- **Claude Code CLI** installed
+
+### Installing Bun
+
+```bash
+# macOS, Linux, WSL
+curl -fsSL https://bun.sh/install | bash
+
+# Windows (PowerShell)
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+## Migrating from Node.js Version
+
+If you're upgrading from a previous Node.js version (v0.x):
+
+```bash
+# 1. Uninstall old version (if installed globally)
+npm uninstall -g @teleportation/cli
+
+# 2. Install Bun
+curl -fsSL https://bun.sh/install | bash
+
+# 3. Remove old dependencies
+cd /path/to/teleportation
+rm -rf node_modules package-lock.json
+
+# 4. Install with Bun
+bun install
+
+# 5. Verify installation
+./teleportation-cli.cjs --version
+```
+
+**Note:** Your hooks and credentials will be preserved during the upgrade.
+
+## Quick Start
+
+```bash
+# 1. Enable hooks
+teleportation on
+
+# 2. Authenticate with your account
+teleportation login
+
+# 3. Check status
+teleportation status
+
+# 4. Start Claude Code - approvals will be routed to your phone!
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+teleportation on          # Enable remote approval hooks
+teleportation off         # Disable hooks (local mode)
+teleportation status      # Show current configuration
+teleportation login       # Authenticate with relay server
+teleportation logout      # Clear credentials
+teleportation help        # Show all commands
+```
+
+### Session Management
+
+```bash
+teleportation session list       # List active sessions
+teleportation session info       # Show current session details
+teleportation session pause      # Pause current session
+teleportation session resume     # Resume paused session
+```
+
+### Worktree Commands (Multi-session)
+
+```bash
+teleportation worktree create <name>   # Create isolated worktree
+teleportation worktree list            # List all worktrees
+teleportation worktree use <name>      # Switch to worktree
+teleportation worktree merge <name>    # Merge worktree changes
+```
+
+### Snapshot Commands
+
+```bash
+teleportation snapshot create <name>   # Create code snapshot
+teleportation snapshot list            # List snapshots
+teleportation snapshot restore <name>  # Restore to snapshot
+teleportation snapshot diff <name>     # Compare with snapshot
+```
+
+## How It Works
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Claude Code   │────▶│   Relay API     │────▶│   Mobile UI     │
+│   (Your Mac)    │     │   (Cloud)       │     │   (Your Phone)  │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                       │                       │
+        │ 1. Tool request       │ 2. Push to queue     │
+        │    intercepted        │                       │
+        │                       │ 3. Display for       │
+        │                       │    approval          │
+        │                       │                       │
+        │ 5. Continue or        │ 4. User approves/    │
+        │    block action       │◀───denies            │
+        │                       │                       │
+```
+
+1. **Intercept**: Claude Code hooks capture tool requests
+2. **Route**: Requests are sent to the relay API
+3. **Display**: Mobile UI shows pending approvals
+4. **Decide**: You approve or deny from your phone
+5. **Execute**: Claude Code continues or blocks the action
+
+## Project Structure
+
+```
+teleportation/
+├── lib/
+│   ├── auth/              # Credential encryption & management
+│   ├── cli/               # CLI command implementations
+│   ├── config/            # Configuration management
+│   ├── install/           # Installation logic
+│   └── session/           # Session metadata extraction
+├── relay/                 # Relay API server
+├── mobile-ui/             # Mobile-friendly web UI
+├── .claude/
+│   └── hooks/             # Claude Code hooks
+├── scripts/
+│   └── install.sh         # Installation script
+├── teleportation-cli.cjs  # Main CLI tool
+└── tests/                 # Test suites
+```
+
+## Configuration
+
+Configuration is stored in `~/.teleportation/`:
+
+```
+~/.teleportation/
+├── config.json           # User preferences
+├── credentials.enc       # Encrypted credentials
+└── bin/
+    └── teleportation     # CLI symlink
+```
+
+Environment variables:
+- `TELEPORTATION_RELAY_URL` - Custom relay server URL
+- `TELEPORTATION_API_KEY` - API key for authentication
+
+## Self-Hosting
+
+Want to run your own relay server?
+
+```bash
+cd relay
+cp .env.example .env
+# Edit .env with your configuration
+bun install
+bun start
+```
+
+See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for full deployment instructions.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run relay server locally
+bun run dev:relay
+
+# Run mobile UI locally
+bun run dev:mobile
+
+# Run everything
+bun run dev:all
+```
+
+## Security
+
+- **End-to-end encryption**: Credentials encrypted with AES-256
+- **OAuth authentication**: Secure login via Google/GitHub
+- **Multi-tenant isolation**: Your data is isolated from other users
+- **Privacy-preserving**: Session existence not revealed to unauthorized users
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## Support
+
+- [GitHub Issues](https://github.com/dundas/teleportation-private/issues)
+- [Documentation](https://github.com/dundas/teleportation-private/wiki)

package/lib/auth/api-key.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * API Key authentication utilities
+ * Validates API keys and tests them against the relay API
+ */
+
+import { retryFetch } from '../utils/retry.js';
+
+/**
+ * Validate API key format
+ * Basic validation - checks for reasonable length and format
+ */
+export function validateApiKeyFormat(apiKey) {
+  if (!apiKey || typeof apiKey !== 'string') {
+    return { valid: false, error: 'API key must be a non-empty string' };
+  }
+
+  if (apiKey.length < 10) {
+    return { valid: false, error: 'API key is too short (minimum 10 characters)' };
+  }
+
+  if (apiKey.length > 256) {
+    return { valid: false, error: 'API key is too long (maximum 256 characters)' };
+  }
+
+  // Basic format check - should contain alphanumeric and some special chars
+  if (!/^[a-zA-Z0-9\-_\.]+$/.test(apiKey)) {
+    return { valid: false, error: 'API key contains invalid characters' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Test API key against relay API with retry logic
+ */
+export async function testApiKey(apiKey, relayApiUrl, retryOptions = {}) {
+  if (!relayApiUrl) {
+    return { valid: false, error: 'Relay API URL is required' };
+  }
+
+  try {
+    const response = await retryFetch(
+      `${relayApiUrl}/api/version`,
+      {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json'
+        }
+      },
+      {
+        maxRetries: 2,
+        initialDelay: 1000,
+        timeout: 10000,
+        shouldRetry: (error) => {
+          // Don't retry on 401 (authentication failures)
+          if (error.status === 401) {
+            return false;
+          }
+          // Retry on network errors and 5xx server errors
+          return true;
+        },
+        ...retryOptions
+      }
+    );
+
+    if (response.ok) {
+      const data = await response.json();
+      return { valid: true, data };
+    } else if (response.status === 401) {
+      return { valid: false, error: 'Invalid API key - authentication failed. Please check your API key and try again.' };
+    } else if (response.status >= 500) {
+      return { valid: false, error: `Relay API server error (${response.status}). The server may be temporarily unavailable. Please try again later.` };
+    } else {
+      return { valid: false, error: `API returned unexpected status ${response.status}. Please check your relay API configuration.` };
+    }
+  } catch (error) {
+    if (error.name === 'AbortError' || error.message?.includes('timeout')) {
+      return { valid: false, error: `Connection timeout: Could not reach relay API at ${relayApiUrl}. Please check your network connection and try again.` };
+    }
+    if (error.code === 'ENOTFOUND') {
+      return { valid: false, error: `Cannot resolve relay API hostname. Please verify the URL is correct: ${relayApiUrl}` };
+    }
+    if (error.code === 'ECONNREFUSED') {
+      return { valid: false, error: `Connection refused: Relay API is not running at ${relayApiUrl}. Start it with 'teleportation start' or check your configuration.` };
+    }
+    return { valid: false, error: `Failed to test API key: ${error.message}. Please check your network connection and relay API status.` };
+  }
+}
+
+/**
+ * Validate and test API key
+ */
+export async function validateApiKey(apiKey, relayApiUrl) {
+  // First validate format
+  const formatCheck = validateApiKeyFormat(apiKey);
+  if (!formatCheck.valid) {
+    return formatCheck;
+  }
+
+  // Then test against API if URL provided
+  if (relayApiUrl) {
+    return await testApiKey(apiKey, relayApiUrl);
+  }
+
+  // Format is valid but can't test without URL
+  return { valid: true, warning: 'API key format is valid but not tested (no relay URL)' };
+}
+

package/lib/auth/credentials.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * Credential encryption and storage management
+ * Uses AES-256 encryption with system keychain for key management
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from 'crypto';
+import { promisify } from 'util';
+import { readFile, writeFile, unlink, stat, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+const scryptAsync = promisify(scrypt);
+const KEY_LENGTH = 32; // 256 bits for AES-256
+const IV_LENGTH = 16; // 128 bits for AES IV
+const SALT_LENGTH = 32;
+const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.teleportation', 'credentials');
+const DEFAULT_KEY_PATH = join(homedir(), '.teleportation', '.key');
+
+/**
+ * Get encryption key from system keychain or fallback to file-based key
+ */
+async function getEncryptionKey(keyPath = DEFAULT_KEY_PATH) {
+  // Try to use system keychain first (platform-specific)
+  // For macOS: use security command
+  // For Linux: use secret-tool or fallback to file
+  // For Windows: use Credential Manager or fallback to file
+  
+  const platform = process.platform;
+  
+  if (platform === 'darwin') {
+    // macOS - try to use keychain
+    try {
+      const { execSync } = await import('child_process');
+      try {
+        const key = execSync(
+          'security find-generic-password -a teleportation -s encryption-key -w 2>/dev/null',
+          { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+        ).trim();
+        if (key && key.length >= 32) {
+          return Buffer.from(key.slice(0, 64), 'hex'); // Use first 32 bytes
+        }
+      } catch (e) {
+        // Keychain entry doesn't exist, fall through to file-based
+      }
+    } catch (e) {
+      // security command not available, fall through
+    }
+  }
+  
+  // Fallback: use file-based key with scrypt derivation
+  try {
+    const keyData = await readFile(keyPath, 'utf8');
+    const parsed = JSON.parse(keyData);
+    
+    // If we have a stored derived key, use it directly
+    if (parsed.derivedKey) {
+      return Buffer.from(parsed.derivedKey, 'hex');
+    }
+    
+    // Legacy format: derive from salt and master key
+    if (parsed.salt && parsed.masterKey) {
+      const key = await scryptAsync(Buffer.from(parsed.masterKey, 'hex'), Buffer.from(parsed.salt, 'hex'), KEY_LENGTH);
+      // Update to new format
+      await writeFile(
+        keyPath,
+        JSON.stringify({
+          derivedKey: Buffer.from(key).toString('hex')
+        }),
+        { mode: 0o600 }
+      );
+      return Buffer.from(key);
+    }
+    
+    throw new Error('Invalid key file format');
+  } catch (e) {
+    if (e.code === 'ENOENT' || e.message === 'Invalid key file format') {
+      // Key file doesn't exist or is invalid, create a new one
+      const masterKey = randomBytes(KEY_LENGTH);
+      const salt = randomBytes(SALT_LENGTH);
+      const derivedKey = await scryptAsync(masterKey, salt, KEY_LENGTH);
+      
+      // Ensure directory exists
+      await mkdir(dirname(keyPath), { recursive: true });
+      
+      // Save derived key directly (32 bytes for AES-256)
+      await writeFile(
+        keyPath,
+        JSON.stringify({
+          derivedKey: Buffer.from(derivedKey).toString('hex')
+        }),
+        { mode: 0o600 } // Owner read/write only
+      );
+      
+      return Buffer.from(derivedKey);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Encrypt data using AES-256-GCM
+ */
+function encrypt(data, key) {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  
+  let encrypted = cipher.update(JSON.stringify(data), 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  
+  const authTag = cipher.getAuthTag();
+  
+  return {
+    data: encrypted,
+    iv: iv.toString('hex'),
+    authTag: authTag.toString('hex')
+  };
+}
+
+/**
+ * Decrypt data using AES-256-GCM
+ */
+function decrypt(encryptedData, key) {
+  const { data, iv, authTag } = encryptedData;
+  
+  if (!data || !iv || !authTag) {
+    throw new Error('Invalid encrypted data structure');
+  }
+  
+  const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'hex'));
+  decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+  
+  let decrypted = decipher.update(data, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  
+  return JSON.parse(decrypted);
+}
+
+/**
+ * CredentialManager - handles encryption, storage, and retrieval of credentials
+ */
+export class CredentialManager {
+  constructor(credentialsPath = DEFAULT_CREDENTIALS_PATH, keyPath = DEFAULT_KEY_PATH) {
+    this.credentialsPath = credentialsPath;
+    this.keyPath = keyPath;
+  }
+
+  /**
+   * Save credentials to encrypted file
+   */
+  async save(credentials) {
+    if (!credentials || typeof credentials !== 'object') {
+      throw new Error('Credentials must be a non-null object');
+    }
+
+    // Ensure directory exists
+    await mkdir(dirname(this.credentialsPath), { recursive: true });
+
+    // Get encryption key
+    const key = await getEncryptionKey(this.keyPath);
+
+    // Encrypt credentials
+    const encrypted = encrypt(credentials, key);
+
+    // Add metadata
+    const fileData = {
+      version: '1.0',
+      createdAt: Date.now(),
+      ...encrypted
+    };
+
+    // Write encrypted file with 600 permissions
+    await writeFile(
+      this.credentialsPath,
+      JSON.stringify(fileData, null, 2),
+      { mode: 0o600 }
+    );
+  }
+
+  /**
+   * Load and decrypt credentials from file
+   */
+  async load() {
+    try {
+      const fileContent = await readFile(this.credentialsPath, 'utf8');
+      const fileData = JSON.parse(fileContent);
+
+      if (!fileData.data || !fileData.iv || !fileData.authTag) {
+        throw new Error('Invalid credential file format');
+      }
+
+      // Get encryption key
+      const key = await getEncryptionKey(this.keyPath);
+
+      // Decrypt credentials
+      const credentials = decrypt(
+        {
+          data: fileData.data,
+          iv: fileData.iv,
+          authTag: fileData.authTag
+        },
+        key
+      );
+
+      return credentials;
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        // File doesn't exist, return null
+        return null;
+      }
+      if (e.message === 'Invalid credential file format') {
+        throw new Error('Credential file is corrupted or invalid. Please re-authenticate by running: teleportation login\n\nThe existing credential file will be replaced.');
+      }
+      if (e.message.includes('decrypt') || e.message.includes('Unsupported state') || e.message.includes('bad decrypt')) {
+        throw new Error('Failed to decrypt credentials. This usually means:\n  - The encryption key is missing or has been changed\n  - The credential file was corrupted\n\nPlease re-authenticate by running: teleportation login');
+      }
+      if (e.message.includes('Invalid key file format')) {
+        throw new Error('Encryption key file is corrupted. Please re-authenticate by running: teleportation login\n\nThis will regenerate the encryption key.');
+      }
+      // Re-throw other errors with helpful message
+      throw new Error(`Failed to load credentials: ${e.message}\n\nIf this problem persists, try running: teleportation logout && teleportation login`);
+    }
+  }
+
+  /**
+   * Check if credentials are expired
+   */
+  async isExpired() {
+    const credentials = await this.load();
+    if (!credentials || !credentials.expiresAt) {
+      return false; // No expiry set, consider valid
+    }
+
+    return Date.now() >= credentials.expiresAt;
+  }
+
+  /**
+   * Check if credentials need rotation (within 7 days of expiry or expired)
+   */
+  async needsRotation(warningDays = 7) {
+    const credentials = await this.load();
+    if (!credentials || !credentials.expiresAt) {
+      return false; // No expiry set, consider valid
+    }
+
+    const now = Date.now();
+    const expiresAt = credentials.expiresAt;
+    const warningThreshold = expiresAt - (warningDays * 24 * 60 * 60 * 1000);
+
+    return now >= warningThreshold;
+  }
+
+  /**
+   * Get days until expiry (negative if expired)
+   */
+  async daysUntilExpiry() {
+    const credentials = await this.load();
+    if (!credentials || !credentials.expiresAt) {
+      return null; // No expiry set
+    }
+
+    const now = Date.now();
+    const expiresAt = credentials.expiresAt;
+    const diffMs = expiresAt - now;
+    return Math.floor(diffMs / (24 * 60 * 60 * 1000));
+  }
+
+  /**
+   * Update credentials (for token refresh or re-authentication)
+   */
+  async update(updates) {
+    const current = await this.load();
+    if (!current) {
+      throw new Error('No existing credentials to update');
+    }
+
+    const updated = {
+      ...current,
+      ...updates,
+      updatedAt: Date.now()
+    };
+
+    await this.save(updated);
+    return updated;
+  }
+
+  /**
+   * Refresh access token if refresh token is available
+   * This is a placeholder - actual implementation depends on OAuth provider
+   */
+  async refreshToken() {
+    const credentials = await this.load();
+    if (!credentials || !credentials.refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    // TODO: Implement actual token refresh with OAuth provider
+    // For now, this is a placeholder that would be implemented in oauth-client.js
+    throw new Error('Token refresh not yet implemented. Please run "teleportation login" to re-authenticate.');
+  }
+
+  /**
+   * Delete credentials file
+   */
+  async delete() {
+    try {
+      await unlink(this.credentialsPath);
+    } catch (e) {
+      if (e.code !== 'ENOENT') {
+        throw e;
+      }
+      // File doesn't exist, that's fine
+    }
+  }
+
+  /**
+   * Verify file permissions are correct (600)
+   */
+  async verifyPermissions() {
+    try {
+      const stats = await stat(this.credentialsPath);
+      const mode = stats.mode & parseInt('777', 8);
+      return mode === parseInt('600', 8);
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /**
+   * Check if credentials exist
+   */
+  async exists() {
+    try {
+      await stat(this.credentialsPath);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+