latchkey 0.1.0

package/src/config.ts

@@ -0,0 +1,115 @@
+/**
+ * Configuration management for Latchkey.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isKeychainAvailable } from './keychain.js';
+
+export class InsecureFilePermissionsError extends Error {
+  constructor(filePath: string, permissions: number) {
+    const permissionsOctal = permissions.toString(8).padStart(3, '0');
+    super(
+      `File ${filePath} has insecure permissions (${permissionsOctal}). Run: chmod 600 ${filePath}`
+    );
+    this.name = 'InsecureFilePermissionsError';
+  }
+}
+
+const LATCHKEY_STORE_ENV_VAR = 'LATCHKEY_STORE';
+const LATCHKEY_BROWSER_STATE_ENV_VAR = 'LATCHKEY_BROWSER_STATE';
+const LATCHKEY_CURL_PATH_ENV_VAR = 'LATCHKEY_CURL_PATH';
+const LATCHKEY_ENCRYPTION_KEY_ENV_VAR = 'LATCHKEY_ENCRYPTION_KEY';
+const LATCHKEY_KEYRING_SERVICE_NAME_ENV_VAR = 'LATCHKEY_KEYRING_SERVICE_NAME';
+const LATCHKEY_KEYRING_ACCOUNT_NAME_ENV_VAR = 'LATCHKEY_KEYRING_ACCOUNT_NAME';
+
+export const DEFAULT_KEYRING_SERVICE_NAME = 'latchkey';
+export const DEFAULT_KEYRING_ACCOUNT_NAME = 'encryption-key';
+
+function getDefaultCredentialStorePath(encryptionEnabled: boolean): string {
+  const filename = encryptionEnabled ? 'credentials.json.enc' : 'credentials.json';
+  return join(homedir(), '.latchkey', filename);
+}
+
+function getDefaultBrowserStatePath(encryptionEnabled: boolean): string {
+  const filename = encryptionEnabled ? 'browser_state.json.enc' : 'browser_state.json';
+  return join(homedir(), '.latchkey', filename);
+}
+
+function resolvePathWithTildeExpansion(path: string): string {
+  if (path.startsWith('~')) {
+    return resolve(homedir(), path.slice(2));
+  }
+  return resolve(path);
+}
+
+/**
+ * Configuration for Latchkey, sourced from environment variables with sensible defaults.
+ */
+export class Config {
+  readonly credentialStorePath: string;
+  readonly browserStatePath: string;
+  readonly curlCommand: string;
+  /**
+   * Encryption key override from environment variable.
+   * If set, this key will be used instead of the system keychain.
+   * The key should be a base64-encoded 256-bit (32-byte) value.
+   */
+  readonly encryptionKeyOverride: string | null;
+  readonly serviceName: string;
+  readonly accountName: string;
+
+  constructor(getEnv: (name: string) => string | undefined = (name) => process.env[name]) {
+    this.curlCommand = getEnv(LATCHKEY_CURL_PATH_ENV_VAR) ?? 'curl';
+    this.encryptionKeyOverride = getEnv(LATCHKEY_ENCRYPTION_KEY_ENV_VAR) ?? null;
+    this.serviceName =
+      getEnv(LATCHKEY_KEYRING_SERVICE_NAME_ENV_VAR) ?? DEFAULT_KEYRING_SERVICE_NAME;
+    this.accountName =
+      getEnv(LATCHKEY_KEYRING_ACCOUNT_NAME_ENV_VAR) ?? DEFAULT_KEYRING_ACCOUNT_NAME;
+
+    // Determine if encryption will be enabled (either via key override or keychain)
+    const encryptionEnabled =
+      this.encryptionKeyOverride !== null ||
+      isKeychainAvailable(this.serviceName, this.accountName);
+
+    const credentialStoreEnv = getEnv(LATCHKEY_STORE_ENV_VAR);
+    this.credentialStorePath = credentialStoreEnv
+      ? resolvePathWithTildeExpansion(credentialStoreEnv)
+      : getDefaultCredentialStorePath(encryptionEnabled);
+
+    const browserStateEnv = getEnv(LATCHKEY_BROWSER_STATE_ENV_VAR);
+    this.browserStatePath = browserStateEnv
+      ? resolvePathWithTildeExpansion(browserStateEnv)
+      : getDefaultBrowserStatePath(encryptionEnabled);
+  }
+
+  /**
+   * Check that sensitive files have secure permissions.
+   * Throws InsecureFilePermissionsError if any file is readable by group or others.
+   */
+  checkSensitiveFilePermissions(): void {
+    const filesToCheck = [this.credentialStorePath, this.browserStatePath];
+
+    for (const filePath of filesToCheck) {
+      if (!existsSync(filePath)) {
+        continue;
+      }
+
+      const stats = statSync(filePath);
+      if (stats.isDirectory()) {
+        continue;
+      }
+
+      const permissions = stats.mode & 0o777;
+      if ((permissions & 0o077) !== 0) {
+        throw new InsecureFilePermissionsError(filePath, permissions);
+      }
+    }
+  }
+}
+
+/**
+ * Global configuration singleton, initialized from process.env at import time.
+ */
+export const CONFIG = new Config();

package/src/curl.ts

@@ -0,0 +1,78 @@
+/**
+ * Curl subprocess utilities.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'node:child_process';
+import { CONFIG } from './config.js';
+
+export interface CurlResult {
+  readonly returncode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * Type for the subprocess runner function (no output capture, for interactive use).
+ */
+export type SubprocessRunner = (args: readonly string[]) => CurlResult;
+
+/**
+ * Type for the capturing subprocess runner function (captures output).
+ */
+export type CapturingSubprocessRunner = (args: readonly string[], timeout: number) => CurlResult;
+
+function defaultSubprocessRunner(args: readonly string[]): CurlResult {
+  const result: SpawnSyncReturns<Buffer> = spawnSync(CONFIG.curlCommand, args as string[], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+  });
+  return {
+    returncode: result.status ?? 1,
+    stdout: '',
+    stderr: '',
+  };
+}
+
+function defaultCapturingSubprocessRunner(args: readonly string[], timeout: number): CurlResult {
+  const result: SpawnSyncReturns<string> = spawnSync(CONFIG.curlCommand, args as string[], {
+    encoding: 'utf-8',
+    timeout: timeout * 1000,
+  });
+  return {
+    returncode: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+let subprocessRunner: SubprocessRunner = defaultSubprocessRunner;
+let capturingSubprocessRunner: CapturingSubprocessRunner = defaultCapturingSubprocessRunner;
+
+export function setSubprocessRunner(runner: SubprocessRunner): void {
+  subprocessRunner = runner;
+}
+
+export function resetSubprocessRunner(): void {
+  subprocessRunner = defaultSubprocessRunner;
+}
+
+export function setCapturingSubprocessRunner(runner: CapturingSubprocessRunner): void {
+  capturingSubprocessRunner = runner;
+}
+
+export function resetCapturingSubprocessRunner(): void {
+  capturingSubprocessRunner = defaultCapturingSubprocessRunner;
+}
+
+/**
+ * Run curl without capturing output (for interactive CLI use).
+ */
+export function run(args: readonly string[]): CurlResult {
+  return subprocessRunner(args);
+}
+
+/**
+ * Run curl with output capture (for credential checking).
+ */
+export function runCaptured(args: readonly string[], timeout = 10): CurlResult {
+  return capturingSubprocessRunner(args, timeout);
+}

package/src/encryptedStorage.ts

@@ -0,0 +1,161 @@
+/**
+ * Encrypted file storage with automatic key management.
+ * Encryption keys are retrieved from:
+ * 1. Provided encryptionKeyOverride option
+ * 2. System keychain
+ * 3. Generated and stored in keychain (first run)
+ *
+ * Falls back to unencrypted storage with chmod 600 if keychain is unavailable.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DEFAULT_KEYRING_SERVICE_NAME, DEFAULT_KEYRING_ACCOUNT_NAME } from './config.js';
+import { encrypt, decrypt, generateKey, DecryptionError } from './encryption.js';
+import {
+  isKeychainAvailable,
+  retrieveFromKeychain,
+  storeInKeychain,
+  KeychainNotAvailableError,
+} from './keychain.js';
+
+const ENCRYPTED_FILE_PREFIX = 'LATCHKEY_ENCRYPTED:';
+
+export class EncryptedStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EncryptedStorageError';
+  }
+}
+
+export class PathIsDirectoryError extends Error {
+  constructor(filePath: string) {
+    super(`Path is a directory, not a file: ${filePath}`);
+    this.name = 'PathIsDirectoryError';
+  }
+}
+
+export interface EncryptedStorageOptions {
+  encryptionKeyOverride?: string | null;
+  serviceName?: string;
+  accountName?: string;
+}
+
+/**
+ * Manages encrypted file storage with automatic key handling.
+ */
+export class EncryptedStorage {
+  private readonly key: string | null;
+
+  constructor(options: EncryptedStorageOptions = {}) {
+    this.key = EncryptedStorage.initializeKey(options);
+  }
+
+  private static initializeKey(options: EncryptedStorageOptions): string | null {
+    // If key was provided via override, use it
+    if (options.encryptionKeyOverride !== undefined && options.encryptionKeyOverride !== null) {
+      return options.encryptionKeyOverride;
+    }
+
+    const serviceName = options.serviceName ?? DEFAULT_KEYRING_SERVICE_NAME;
+    const accountName = options.accountName ?? DEFAULT_KEYRING_ACCOUNT_NAME;
+
+    // Check if keychain is available
+    if (!isKeychainAvailable(serviceName, accountName)) {
+      return null;
+    }
+
+    // Try to retrieve from keychain
+    try {
+      const keychainKey = retrieveFromKeychain(serviceName, accountName);
+      if (keychainKey) {
+        return keychainKey;
+      }
+
+      // Generate new key and store in keychain
+      const newKey = generateKey();
+      storeInKeychain(serviceName, accountName, newKey);
+      return newKey;
+    } catch (error) {
+      if (error instanceof KeychainNotAvailableError) {
+        // Fall back to unencrypted storage
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  private isEncryptionEnabled(): boolean {
+    return this.key !== null;
+  }
+
+  /**
+   * Read and decrypt a file.
+   */
+  readFile(filePath: string): string | null {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+
+    const stats = statSync(filePath);
+    if (stats.isDirectory()) {
+      throw new PathIsDirectoryError(filePath);
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+
+    // Check if the file is encrypted
+    if (content.startsWith(ENCRYPTED_FILE_PREFIX)) {
+      if (this.key === null) {
+        throw new EncryptedStorageError(
+          'File is encrypted but a key is not available. ' +
+            'Set LATCHKEY_ENCRYPTION_KEY or ensure system keychain is accessible.'
+        );
+      }
+
+      const encryptedData = content.slice(ENCRYPTED_FILE_PREFIX.length);
+      try {
+        return decrypt(encryptedData, this.key);
+      } catch (error) {
+        if (error instanceof DecryptionError) {
+          throw new EncryptedStorageError(
+            `Failed to decrypt file: ${error.message}. ` + 'The encryption key may have changed.'
+          );
+        }
+        throw error;
+      }
+    }
+
+    // File is not encrypted (fallback mode when keychain unavailable)
+    return content;
+  }
+
+  /**
+   * Encrypt and write data to a file.
+   * Creates parent directories. New files are created with chmod 600.
+   */
+  writeFile(filePath: string, content: string): void {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+
+    if (existsSync(filePath)) {
+      const stats = statSync(filePath);
+      if (stats.isDirectory()) {
+        throw new PathIsDirectoryError(filePath);
+      }
+    }
+
+    let dataToWrite: string;
+    if (this.key !== null) {
+      const encryptedData = encrypt(content, this.key);
+      dataToWrite = ENCRYPTED_FILE_PREFIX + encryptedData;
+    } else {
+      // Fallback to unencrypted storage
+      dataToWrite = content;
+    }
+
+    writeFileSync(filePath, dataToWrite, { encoding: 'utf-8', mode: 0o600 });
+  }
+}

package/src/encryption.ts

@@ -0,0 +1,106 @@
+/**
+ * Encryption utilities for secure credential storage.
+ * Uses AES-256-GCM for authenticated encryption.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 12; // 96 bits for GCM
+const AUTH_TAG_LENGTH = 16; // 128 bits
+
+export class EncryptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EncryptionError';
+  }
+}
+
+export class DecryptionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DecryptionError';
+  }
+}
+
+/**
+ * Encrypt data using AES-256-GCM.
+ * The key should be a base64-encoded 256-bit key.
+ * Returns a base64-encoded string containing: iv + authTag + ciphertext
+ */
+export function encrypt(plaintext: string, keyBase64: string): string {
+  try {
+    const key = Buffer.from(keyBase64, 'base64');
+    if (key.length !== KEY_LENGTH) {
+      throw new EncryptionError(
+        `Invalid key length: expected ${String(KEY_LENGTH)} bytes, got ${String(key.length)}`
+      );
+    }
+
+    const iv = randomBytes(IV_LENGTH);
+
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    // Combine: iv (12) + authTag (16) + ciphertext
+    const combined = Buffer.concat([iv, authTag, ciphertext]);
+    return combined.toString('base64');
+  } catch (error) {
+    if (error instanceof EncryptionError) {
+      throw error;
+    }
+    throw new EncryptionError(
+      `Failed to encrypt data: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Decrypt data that was encrypted with the encrypt function.
+ * The key should be a base64-encoded 256-bit key.
+ * Input should be a base64-encoded string containing: iv + authTag + ciphertext
+ */
+export function decrypt(encryptedData: string, keyBase64: string): string {
+  try {
+    const key = Buffer.from(keyBase64, 'base64');
+    if (key.length !== KEY_LENGTH) {
+      throw new DecryptionError(
+        `Invalid key length: expected ${String(KEY_LENGTH)} bytes, got ${String(key.length)}`
+      );
+    }
+
+    const combined = Buffer.from(encryptedData, 'base64');
+
+    // Minimum length is iv + authTag (ciphertext can be empty for empty string)
+    if (combined.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+      throw new DecryptionError('Invalid encrypted data: too short');
+    }
+
+    const iv = combined.subarray(0, IV_LENGTH);
+    const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = combined.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    decipher.setAuthTag(authTag);
+
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString('utf8');
+  } catch (error) {
+    if (error instanceof DecryptionError) {
+      throw error;
+    }
+    throw new DecryptionError(
+      `Failed to decrypt data: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Generate a cryptographically secure random 256-bit key.
+ * Returns the key as a base64-encoded string.
+ */
+export function generateKey(): string {
+  return randomBytes(KEY_LENGTH).toString('base64');
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Latchkey - A CLI tool that injects API credentials into curl requests.
+ */
+
+// Core types and utilities
+export {
+  ApiCredentials,
+  ApiCredentialStatus,
+  AuthorizationBearer,
+  AuthorizationBare,
+  SlackApiCredentials,
+  deserializeCredentials,
+  serializeCredentials,
+} from './apiCredentials.js';
+
+export { ApiCredentialStore, ApiCredentialStoreError } from './apiCredentialStore.js';
+
+export { Config, CONFIG, InsecureFilePermissionsError } from './config.js';
+
+export { encrypt, decrypt, generateKey, EncryptionError, DecryptionError } from './encryption.js';
+
+export { EncryptedStorage, EncryptedStorageError } from './encryptedStorage.js';
+
+export {
+  storeInKeychain,
+  retrieveFromKeychain,
+  deleteFromKeychain,
+  isKeychainAvailable,
+  KeychainError,
+  KeychainNotAvailableError,
+} from './keychain.js';
+
+export {
+  run as runCurl,
+  runCaptured as runCurlCaptured,
+  setSubprocessRunner,
+  resetSubprocessRunner,
+  setCapturingSubprocessRunner,
+  resetCapturingSubprocessRunner,
+} from './curl.js';
+
+export { typeLikeHuman } from './playwrightUtils.js';
+
+// Services
+export {
+  Service,
+  ServiceSession,
+  SimpleServiceSession,
+  BrowserFollowupServiceSession,
+  LoginCancelledError,
+  LoginFailedError,
+  Slack,
+  SLACK,
+  Discord,
+  DISCORD,
+  Github,
+  GITHUB,
+  Dropbox,
+  DROPBOX,
+  Linear,
+  LINEAR,
+} from './services/index.js';
+
+// Registry
+export { Registry, REGISTRY } from './registry.js';

package/src/keychain.ts

@@ -0,0 +1,105 @@
+/**
+ * System keychain integration for secure password storage.
+ * Uses @napi-rs/keyring for cross-platform support (macOS Keychain, Windows Credential Manager,
+ * Linux Secret Service via keyutils/kernel keyring).
+ */
+
+import { Entry } from '@napi-rs/keyring';
+
+export class KeychainError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeychainError';
+  }
+}
+
+export class KeychainNotAvailableError extends KeychainError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KeychainNotAvailableError';
+  }
+}
+
+/**
+ * Get a keyring entry.
+ */
+function getEntry(serviceName: string, accountName: string): Entry {
+  return new Entry(serviceName, accountName);
+}
+
+/**
+ * Store a password in the system keychain.
+ * Throws KeychainNotAvailableError if the keychain is not accessible.
+ */
+export function storeInKeychain(serviceName: string, accountName: string, password: string): void {
+  try {
+    const entry = getEntry(serviceName, accountName);
+    entry.setPassword(password);
+  } catch (error) {
+    throw new KeychainNotAvailableError(
+      `Failed to store password in keychain: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Retrieve a password from the system keychain.
+ * Returns null if the password is not found.
+ * Throws KeychainNotAvailableError if the keychain is not accessible.
+ */
+export function retrieveFromKeychain(serviceName: string, accountName: string): string | null {
+  try {
+    const entry = getEntry(serviceName, accountName);
+    const password = entry.getPassword();
+    return password ?? null;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    // Check if it's a "not found" error
+    if (
+      errorMessage.includes('not found') ||
+      errorMessage.includes('No password') ||
+      errorMessage.includes('ItemNotFound')
+    ) {
+      return null;
+    }
+    throw new KeychainNotAvailableError(
+      `Failed to retrieve password from keychain: ${errorMessage}`
+    );
+  }
+}
+
+/**
+ * Delete a password from the system keychain.
+ * Returns true if deleted, false if not found.
+ * Throws KeychainNotAvailableError if the keychain is not accessible.
+ */
+export function deleteFromKeychain(serviceName: string, accountName: string): boolean {
+  try {
+    const entry = getEntry(serviceName, accountName);
+    entry.deletePassword();
+    return true;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (
+      errorMessage.includes('not found') ||
+      errorMessage.includes('No password') ||
+      errorMessage.includes('ItemNotFound')
+    ) {
+      return false;
+    }
+    throw new KeychainNotAvailableError(`Failed to delete password from keychain: ${errorMessage}`);
+  }
+}
+
+/**
+ * Check if the system keychain is available.
+ */
+export function isKeychainAvailable(serviceName: string, accountName: string): boolean {
+  try {
+    // Try to create an entry - this should work on all supported platforms
+    getEntry(serviceName, accountName);
+    return true;
+  } catch {
+    return false;
+  }
+}