cli4ai 0.8.0

package/src/core/routines.ts

@@ -0,0 +1,111 @@
+/**
+ * Routine discovery and resolution.
+ *
+ * Routines live in:
+ * - local:  <project>/.cli4ai/routines
+ * - global: ~/.cli4ai/routines
+ *
+ * Resolution order:
+ * - local before global (unless globalOnly)
+ * - within a scope: .routine.json before .routine.sh
+ */
+
+import { existsSync, readdirSync, statSync } from 'fs';
+import { resolve } from 'path';
+import { ensureCli4aiHome, ensureLocalDir, ROUTINES_DIR, LOCAL_ROUTINES_DIR } from './config.js';
+
+export type RoutineKind = 'json' | 'bash';
+export type RoutineScope = 'local' | 'global';
+
+export interface RoutineInfo {
+  name: string;
+  kind: RoutineKind;
+  scope: RoutineScope;
+  path: string;
+}
+
+export interface ResolveRoutineOptions {
+  globalOnly?: boolean;
+}
+
+const ROUTINE_FILES = [
+  { kind: 'json' as const, suffix: '.routine.json' },
+  { kind: 'bash' as const, suffix: '.routine.sh' }
+] as const;
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export function validateRoutineName(name: string): void {
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid routine name: ${name}`);
+  }
+}
+
+function listRoutinesInDir(dir: string, scope: RoutineScope): RoutineInfo[] {
+  if (!existsSync(dir)) return [];
+
+  const results: RoutineInfo[] = [];
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+
+    for (const def of ROUTINE_FILES) {
+      if (!entry.name.endsWith(def.suffix)) continue;
+
+      const name = entry.name.slice(0, -def.suffix.length);
+      if (!NAME_PATTERN.test(name)) continue;
+
+      const fullPath = resolve(dir, entry.name);
+
+      // Best-effort: ensure it's a regular file
+      try {
+        if (!statSync(fullPath).isFile()) continue;
+      } catch {
+        continue;
+      }
+
+      results.push({
+        name,
+        kind: def.kind,
+        scope,
+        path: fullPath
+      });
+    }
+  }
+
+  return results;
+}
+
+export function getLocalRoutines(projectDir: string): RoutineInfo[] {
+  ensureLocalDir(projectDir);
+  const dir = resolve(projectDir, LOCAL_ROUTINES_DIR);
+  return listRoutinesInDir(dir, 'local');
+}
+
+export function getGlobalRoutines(): RoutineInfo[] {
+  ensureCli4aiHome();
+  return listRoutinesInDir(ROUTINES_DIR, 'global');
+}
+
+export function resolveRoutine(name: string, projectDir: string, options: ResolveRoutineOptions = {}): RoutineInfo | null {
+  validateRoutineName(name);
+
+  const candidates: Array<{ scope: RoutineScope; baseDir: string }> = options.globalOnly
+    ? [{ scope: 'global', baseDir: ROUTINES_DIR }]
+    : [
+        { scope: 'local', baseDir: resolve(projectDir, LOCAL_ROUTINES_DIR) },
+        { scope: 'global', baseDir: ROUTINES_DIR }
+      ];
+
+  for (const { scope, baseDir } of candidates) {
+    for (const def of ROUTINE_FILES) {
+      const routinePath = resolve(baseDir, `${name}${def.suffix}`);
+      if (existsSync(routinePath)) {
+        return { name, kind: def.kind, scope, path: routinePath };
+      }
+    }
+  }
+
+  return null;
+}
+

package/src/core/secrets.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Tests for secrets.ts
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir, hostname, userInfo } from 'os';
+import { createCipheriv, createHash, randomBytes } from 'crypto';
+import { getSecret, listSecretKeys } from './secrets.js';
+
+const ALGORITHM = 'aes-256-gcm';
+
+function legacyEncrypt(value: string): string {
+  const machineId = `${hostname()}-${userInfo().username}-cli4ai-secrets`;
+  const key = createHash('sha256').update(machineId).digest();
+  const iv = randomBytes(16);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  let encrypted = cipher.update(value, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+
+  const authTag = cipher.getAuthTag();
+
+  return JSON.stringify({
+    iv: iv.toString('hex'),
+    encrypted,
+    authTag: authTag.toString('hex')
+  });
+}
+
+describe('secrets', () => {
+  let tempDir: string;
+  let secretsFile: string;
+  let saltFile: string;
+  let originalSecretsFileEnv: string | undefined;
+  let originalSaltFileEnv: string | undefined;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli4ai-secrets-test-'));
+    secretsFile = join(tempDir, 'secrets.json');
+    saltFile = join(tempDir, 'secrets.salt');
+
+    originalSecretsFileEnv = process.env.C4AI_SECRETS_FILE;
+    originalSaltFileEnv = process.env.C4AI_SECRETS_SALT_FILE;
+
+    process.env.C4AI_SECRETS_FILE = secretsFile;
+    process.env.C4AI_SECRETS_SALT_FILE = saltFile;
+  });
+
+  afterEach(() => {
+    if (originalSecretsFileEnv !== undefined) process.env.C4AI_SECRETS_FILE = originalSecretsFileEnv;
+    else delete process.env.C4AI_SECRETS_FILE;
+
+    if (originalSaltFileEnv !== undefined) process.env.C4AI_SECRETS_SALT_FILE = originalSaltFileEnv;
+    else delete process.env.C4AI_SECRETS_SALT_FILE;
+
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('decrypts legacy secrets and migrates to salted format', () => {
+    writeFileSync(
+      secretsFile,
+      JSON.stringify({ SLACK_BOT_TOKEN: legacyEncrypt('xoxb-test') }, null, 2),
+      { mode: 0o600 }
+    );
+
+    expect(getSecret('SLACK_BOT_TOKEN')).toBe('xoxb-test');
+    expect(listSecretKeys()).toEqual(['SLACK_BOT_TOKEN']);
+
+    // Migration should create a salt file for the new scheme.
+    expect(existsSync(saltFile)).toBe(true);
+    expect(readFileSync(saltFile).length).toBe(32);
+
+    // Subsequent reads should still work.
+    expect(getSecret('SLACK_BOT_TOKEN')).toBe('xoxb-test');
+  });
+});
+

package/src/core/secrets.ts

@@ -0,0 +1,430 @@
+/**
+ * Secrets management for cli4ai
+ *
+ * Priority order:
+ * 1. Scoped environment variables (C4AI_<PKG>__<KEY>)
+ * 2. Environment variables (for CI/CD)
+ * 3. Scoped local secrets vault (<pkg>:<key>)
+ * 4. Global local secrets vault (~/.cli4ai/secrets.json)
+ *
+ * Secrets are stored encrypted using a machine-specific key with random entropy.
+ *
+ * SECURITY: The encryption key is derived from:
+ * - Machine hostname
+ * - Username
+ * - A random 32-byte salt stored in ~/.cli4ai/secrets.salt
+ *
+ * This ensures that even if an attacker knows the hostname and username,
+ * they cannot reconstruct the key without access to the salt file.
+ */
+
+import { readFileSync, writeFileSync, existsSync, chmodSync, statSync, mkdirSync } from 'fs';
+import { createCipheriv, createDecipheriv, randomBytes, createHash, pbkdf2Sync } from 'crypto';
+import { hostname, userInfo, platform } from 'os';
+import { dirname, resolve } from 'path';
+import { CLI4AI_HOME, ensureCli4aiHome } from './config.js';
+
+const SECRETS_FILE = resolve(CLI4AI_HOME, 'secrets.json');
+const SALT_FILE = resolve(CLI4AI_HOME, 'secrets.salt');
+const ALGORITHM = 'aes-256-gcm';
+const PBKDF2_ITERATIONS = 100000; // Strong iteration count for key derivation
+
+const SECRETS_FILE_OVERRIDE_ENV = 'C4AI_SECRETS_FILE';
+const SALT_FILE_OVERRIDE_ENV = 'C4AI_SECRETS_SALT_FILE';
+
+export type SecretSource = 'env_scoped' | 'env' | 'vault_scoped' | 'vault' | 'missing';
+
+function getSecretsFilePath(): string {
+  const override = process.env[SECRETS_FILE_OVERRIDE_ENV];
+  return override ? resolve(override) : SECRETS_FILE;
+}
+
+function getSaltFilePath(): string {
+  const override = process.env[SALT_FILE_OVERRIDE_ENV];
+  return override ? resolve(override) : SALT_FILE;
+}
+
+function ensureSecretsDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function normalizeEnvVarSegment(value: string): string {
+  return value
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function getScopedEnvVarName(packageName: string, key: string): string {
+  return `C4AI_${normalizeEnvVarSegment(packageName)}__${normalizeEnvVarSegment(key)}`;
+}
+
+function makeScopedVaultKey(packageName: string, key: string): string {
+  return `${packageName}:${key}`;
+}
+
+function getLegacyMachineKey(): Buffer {
+  const machineId = `${hostname()}-${userInfo().username}-cli4ai-secrets`;
+  return createHash('sha256').update(machineId).digest();
+}
+
+/**
+ * Get or create the random salt for key derivation.
+ * The salt is stored in a separate file with restricted permissions.
+ */
+function getSaltIfExists(): Buffer | null {
+  const saltFilePath = getSaltFilePath();
+
+  if (existsSync(saltFilePath)) {
+    // SECURITY: Verify file permissions on Unix-like systems
+    if (platform() !== 'win32') {
+      try {
+        const stats = statSync(saltFilePath);
+        const mode = stats.mode & 0o777;
+        if (mode !== 0o600) {
+          console.error(`Warning: Salt file has insecure permissions (${mode.toString(8)}). Should be 600.`);
+          // Attempt to fix permissions
+          chmodSync(saltFilePath, 0o600);
+        }
+      } catch {
+        // Ignore permission check errors
+      }
+    }
+
+    try {
+      const salt = readFileSync(saltFilePath);
+      if (salt.length === 32) {
+        return salt;
+      }
+      // Invalid salt file, regenerate
+      console.error('Warning: Invalid salt file, regenerating...');
+    } catch {
+      // Failed to read, regenerate
+    }
+  }
+
+  return null;
+}
+
+function getOrCreateSalt(): Buffer {
+  const saltFilePath = getSaltFilePath();
+  ensureSecretsDir(saltFilePath);
+
+  const salt = getSaltIfExists();
+  if (salt) return salt;
+
+  // Generate new random salt
+  const newSalt = randomBytes(32);
+  writeFileSync(saltFilePath, newSalt, { mode: 0o600 });
+  return newSalt;
+}
+
+/**
+ * Try to get additional machine-specific entropy.
+ * This is best-effort and won't fail if sources are unavailable.
+ */
+function getMachineEntropy(): string {
+  const parts: string[] = [
+    hostname(),
+    userInfo().username,
+  ];
+
+  // Try to get machine-id on Linux
+  if (platform() === 'linux') {
+    try {
+      const machineId = readFileSync('/etc/machine-id', 'utf-8').trim();
+      parts.push(machineId);
+    } catch {
+      // Not available
+    }
+  }
+
+  // Try to get hardware UUID on macOS
+  if (platform() === 'darwin') {
+    try {
+      // This is a backup - the salt file is the primary entropy source
+      const { execSync } = require('child_process');
+      const uuid = execSync('ioreg -rd1 -c IOPlatformExpertDevice | grep IOPlatformUUID', {
+        encoding: 'utf-8',
+        timeout: 1000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      const match = uuid.match(/"([^"]+)"$/);
+      if (match) {
+        parts.push(match[1]);
+      }
+    } catch {
+      // Not available
+    }
+  }
+
+  return parts.join('-');
+}
+
+/**
+ * Generate a machine-specific encryption key with strong entropy.
+ *
+ * Uses PBKDF2 with:
+ * - Machine-specific data (hostname, username, hardware IDs when available)
+ * - A random 32-byte salt stored on disk
+ * - 100,000 iterations for key stretching
+ */
+function getMachineKey(options: { createSalt: boolean }): Buffer {
+  const salt = options.createSalt ? getOrCreateSalt() : getSaltIfExists();
+  if (!salt) {
+    throw new Error('Secrets salt file is missing');
+  }
+  const machineData = getMachineEntropy();
+
+  // Use PBKDF2 for proper key derivation with the random salt
+  return pbkdf2Sync(machineData, salt, PBKDF2_ITERATIONS, 32, 'sha512');
+}
+
+/**
+ * Encrypt a string value
+ */
+function encrypt(text: string): string {
+  const key = getMachineKey({ createSalt: true });
+  const iv = randomBytes(16);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  let encrypted = cipher.update(text, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+
+  const authTag = cipher.getAuthTag();
+
+  return JSON.stringify({
+    iv: iv.toString('hex'),
+    encrypted,
+    authTag: authTag.toString('hex')
+  });
+}
+
+function decryptWithKey(data: string, key: Buffer): string {
+  const { iv, encrypted, authTag } = JSON.parse(data);
+
+  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(iv, 'hex'));
+  decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+
+  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+
+  return decrypted;
+}
+
+/**
+ * Decrypt a string value
+ */
+function decrypt(data: string): string {
+  const key = getMachineKey({ createSalt: false });
+  return decryptWithKey(data, key);
+}
+
+function decryptLegacy(data: string): string {
+  const key = getLegacyMachineKey();
+  return decryptWithKey(data, key);
+}
+
+/**
+ * Check and warn about insecure file permissions
+ */
+function checkFilePermissions(filePath: string, fileName: string): void {
+  if (platform() === 'win32') return;
+
+  try {
+    const stats = statSync(filePath);
+    const mode = stats.mode & 0o777;
+    // Warn if file is readable by group or others
+    if (mode & 0o077) {
+      console.error(`Warning: ${fileName} has insecure permissions (${mode.toString(8)}). Should be 600.`);
+      // Attempt to fix permissions
+      try {
+        chmodSync(filePath, 0o600);
+        console.error(`  Fixed permissions to 600.`);
+      } catch {
+        console.error(`  Could not fix permissions. Please run: chmod 600 ${filePath}`);
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Load all secrets from vault
+ */
+function loadSecrets(): Record<string, string> {
+  const secretsFilePath = getSecretsFilePath();
+  ensureSecretsDir(secretsFilePath);
+
+  if (!existsSync(secretsFilePath)) {
+    return {};
+  }
+
+  // SECURITY: Check file permissions
+  checkFilePermissions(secretsFilePath, 'secrets.json');
+
+  try {
+    const content = readFileSync(secretsFilePath, 'utf-8');
+    const encrypted = JSON.parse(content) as Record<string, unknown>;
+    const secrets: Record<string, string> = {};
+    const migrated: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(encrypted)) {
+      if (typeof value !== 'string') continue;
+      try {
+        secrets[key] = decrypt(value);
+      } catch {
+        // Back-compat: attempt legacy decrypt (pre-salt secrets).
+        try {
+          const legacy = decryptLegacy(value);
+          secrets[key] = legacy;
+          migrated[key] = legacy;
+        } catch {
+          // Skip corrupted/unreadable entries
+        }
+      }
+    }
+
+    // If we successfully decrypted legacy secrets, rewrite those entries using the current scheme.
+    if (Object.keys(migrated).length > 0) {
+      try {
+        const updated: Record<string, unknown> = { ...encrypted };
+        for (const [k, v] of Object.entries(migrated)) {
+          updated[k] = encrypt(v);
+        }
+        writeFileSync(secretsFilePath, JSON.stringify(updated, null, 2), { mode: 0o600 });
+      } catch {
+        // Best-effort migration only. If we can't write (e.g. restricted FS), still return decrypted secrets.
+      }
+    }
+
+    return secrets;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save all secrets to vault
+ */
+function saveSecrets(secrets: Record<string, string>): void {
+  const secretsFilePath = getSecretsFilePath();
+  ensureSecretsDir(secretsFilePath);
+
+  const encrypted: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(secrets)) {
+    encrypted[key] = encrypt(value);
+  }
+
+  writeFileSync(secretsFilePath, JSON.stringify(encrypted, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Get a secret value (env var takes precedence)
+ */
+export function getSecret(key: string, packageName?: string): string | undefined {
+  // Environment variables take precedence (for CI/CD)
+  if (packageName) {
+    const scopedEnvKey = getScopedEnvVarName(packageName, key);
+    if (process.env[scopedEnvKey]) {
+      return process.env[scopedEnvKey];
+    }
+  }
+
+  if (process.env[key]) {
+    return process.env[key];
+  }
+
+  // Check vault
+  const secrets = loadSecrets();
+  if (packageName) {
+    const scopedVaultKey = makeScopedVaultKey(packageName, key);
+    if (secrets[scopedVaultKey]) {
+      return secrets[scopedVaultKey];
+    }
+  }
+
+  return secrets[key];
+}
+
+/**
+ * Set a secret in the vault
+ */
+export function setSecret(key: string, value: string, packageName?: string): void {
+  const secrets = loadSecrets();
+  const vaultKey = packageName ? makeScopedVaultKey(packageName, key) : key;
+  secrets[vaultKey] = value;
+  saveSecrets(secrets);
+}
+
+/**
+ * Delete a secret from the vault
+ */
+export function deleteSecret(key: string, packageName?: string): boolean {
+  const secrets = loadSecrets();
+  const vaultKey = packageName ? makeScopedVaultKey(packageName, key) : key;
+  if (vaultKey in secrets) {
+    delete secrets[vaultKey];
+    saveSecrets(secrets);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * List all secret keys (not values)
+ */
+export function listSecretKeys(): string[] {
+  const secrets = loadSecrets();
+  return Object.keys(secrets);
+}
+
+/**
+ * Check if a secret exists (in env or vault)
+ */
+export function hasSecret(key: string, packageName?: string): boolean {
+  return getSecretSource(key, packageName) !== 'missing';
+}
+
+/**
+ * Get secret source (for display)
+ */
+export function getSecretSource(key: string, packageName?: string): SecretSource {
+  if (packageName) {
+    const scopedEnvKey = getScopedEnvVarName(packageName, key);
+    if (process.env[scopedEnvKey]) return 'env_scoped';
+  }
+  if (process.env[key]) return 'env';
+
+  const secrets = loadSecrets();
+
+  if (packageName) {
+    const scopedVaultKey = makeScopedVaultKey(packageName, key);
+    if (secrets[scopedVaultKey]) return 'vault_scoped';
+  }
+  if (secrets[key]) return 'vault';
+
+  return 'missing';
+}
+
+/**
+ * Export secrets as environment variables (for subprocess)
+ */
+export function getSecretsAsEnv(keys: string[], packageName?: string): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of keys) {
+    const value = getSecret(key, packageName);
+    if (value) {
+      env[key] = value;
+    }
+  }
+
+  return env;
+}