cli4ai 1.2.0 → 1.2.2

package/dist/core/secrets.js

@@ -0,0 +1,384 @@
+/**
+ * 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 } 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';
+function getSecretsFilePath() {
+    const override = process.env[SECRETS_FILE_OVERRIDE_ENV];
+    return override ? resolve(override) : SECRETS_FILE;
+}
+function getSaltFilePath() {
+    const override = process.env[SALT_FILE_OVERRIDE_ENV];
+    return override ? resolve(override) : SALT_FILE;
+}
+function ensureSecretsDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function normalizeEnvVarSegment(value) {
+    return value
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function getScopedEnvVarName(packageName, key) {
+    return `C4AI_${normalizeEnvVarSegment(packageName)}__${normalizeEnvVarSegment(key)}`;
+}
+function makeScopedVaultKey(packageName, key) {
+    return `${packageName}:${key}`;
+}
+function getLegacyMachineKey() {
+    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() {
+    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() {
+    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() {
+    const parts = [
+        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) {
+    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) {
+    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, key) {
+    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) {
+    const key = getMachineKey({ createSalt: false });
+    return decryptWithKey(data, key);
+}
+function decryptLegacy(data) {
+    const key = getLegacyMachineKey();
+    return decryptWithKey(data, key);
+}
+/**
+ * Check and warn about insecure file permissions
+ */
+function checkFilePermissions(filePath, fileName) {
+    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() {
+    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);
+        const secrets = {};
+        const migrated = {};
+        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 = { ...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) {
+    const secretsFilePath = getSecretsFilePath();
+    ensureSecretsDir(secretsFilePath);
+    const encrypted = {};
+    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, packageName) {
+    // 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, value, packageName) {
+    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, packageName) {
+    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() {
+    const secrets = loadSecrets();
+    return Object.keys(secrets);
+}
+/**
+ * Check if a secret exists (in env or vault)
+ */
+export function hasSecret(key, packageName) {
+    return getSecretSource(key, packageName) !== 'missing';
+}
+/**
+ * Get secret source (for display)
+ */
+export function getSecretSource(key, packageName) {
+    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, packageName) {
+    const env = {};
+    for (const key of keys) {
+        const value = getSecret(key, packageName);
+        if (value) {
+            env[key] = value;
+        }
+    }
+    return env;
+}

package/dist/lib/cli.d.ts

@@ -0,0 +1,84 @@
+/**
+ * cli4ai - cli4ai.com
+ * Standardized CLI framework for AI agent tools
+ */
+import { Command } from 'commander';
+export declare const BRAND = "cli4ai - cli4ai.com";
+export declare const VERSION: any;
+export interface CLIError {
+    error: string;
+    message: string;
+    [key: string]: unknown;
+}
+export type CommandFn = (...args: unknown[]) => Promise<void> | void;
+export declare const ErrorCodes: {
+    readonly ENV_MISSING: "ENV_MISSING";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly API_ERROR: "API_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly MANIFEST_ERROR: "MANIFEST_ERROR";
+    readonly INSTALL_ERROR: "INSTALL_ERROR";
+    readonly NPM_ERROR: "NPM_ERROR";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * Require environment variables to be set. Exits with parseable error if missing.
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export declare function requireEnv(...variables: string[]): void;
+/**
+ * Get env var or exit with error
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export declare function env(name: string): string;
+/**
+ * Get env var or return default
+ */
+export declare function envOr(name: string, defaultValue: string): string;
+/**
+ * Output JSON data to stdout
+ */
+export declare function output(data: unknown): void;
+/**
+ * Output error and exit. Format is parseable JSON.
+ */
+export declare function outputError(code: string, message: string, details?: Record<string, unknown>, exitCodeOverride?: number): never;
+/**
+ * Log to stderr (for progress messages)
+ */
+export declare function log(message: string): void;
+/**
+ * Create a branded CLI program
+ */
+export declare function cli(name: string, version: string, description: string): Command;
+/**
+ * Wrap an async action with error handling
+ */
+export declare function withErrorHandling<T extends unknown[]>(fn: (...args: T) => Promise<void>): (...args: T) => Promise<void>;
+/**
+ * Parse a string as JSON, or return error
+ */
+export declare function parseJson<T>(str: string, context?: string): T;
+/**
+ * Sleep for ms milliseconds
+ */
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Format bytes to human readable
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format date to ISO string (date only)
+ */
+export declare function formatDate(date: Date | number | string): string;
+/**
+ * Format date to ISO string (datetime)
+ */
+export declare function formatDateTime(date: Date | number | string): string;

package/dist/lib/cli.js

@@ -0,0 +1,216 @@
+/**
+ * cli4ai - cli4ai.com
+ * Standardized CLI framework for AI agent tools
+ */
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, '..', '..', 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+export const BRAND = 'cli4ai - cli4ai.com';
+export const VERSION = pkg.version;
+// ═══════════════════════════════════════════════════════════════════════════
+// ERROR CODES
+// ═══════════════════════════════════════════════════════════════════════════
+export const ErrorCodes = {
+    ENV_MISSING: 'ENV_MISSING',
+    INVALID_INPUT: 'INVALID_INPUT',
+    NOT_FOUND: 'NOT_FOUND',
+    AUTH_FAILED: 'AUTH_FAILED',
+    API_ERROR: 'API_ERROR',
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    RATE_LIMITED: 'RATE_LIMITED',
+    TIMEOUT: 'TIMEOUT',
+    PARSE_ERROR: 'PARSE_ERROR',
+    MANIFEST_ERROR: 'MANIFEST_ERROR',
+    INSTALL_ERROR: 'INSTALL_ERROR',
+    NPM_ERROR: 'NPM_ERROR',
+};
+const EXIT_CODES = {
+    [ErrorCodes.NOT_FOUND]: 2,
+    [ErrorCodes.INVALID_INPUT]: 3,
+    [ErrorCodes.ENV_MISSING]: 4,
+    [ErrorCodes.MANIFEST_ERROR]: 4,
+    [ErrorCodes.INSTALL_ERROR]: 4,
+    [ErrorCodes.AUTH_FAILED]: 6,
+    [ErrorCodes.NETWORK_ERROR]: 7,
+    [ErrorCodes.RATE_LIMITED]: 8,
+    [ErrorCodes.TIMEOUT]: 9,
+    [ErrorCodes.PARSE_ERROR]: 10,
+    [ErrorCodes.NPM_ERROR]: 11,
+};
+function getExitCode(code) {
+    return EXIT_CODES[code] ?? 1;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ENV VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+// SECURITY NOTE: We intentionally do NOT auto-load .env files from the filesystem.
+// This prevents supply chain attacks where malicious .env files in parent directories
+// could inject credentials or override security settings.
+//
+// Use `cli4ai secrets set <key>` for secure credential storage, or set environment
+// variables explicitly in your shell/CI environment.
+/**
+ * Require environment variables to be set. Exits with parseable error if missing.
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export function requireEnv(...variables) {
+    const missing = variables.filter(v => !process.env[v]);
+    if (missing.length > 0) {
+        outputError('ENV_MISSING', `Missing required environment variables: ${missing.join(', ')}`, {
+            variables: missing,
+            hint: 'Use "cli4ai secrets set <key>" to store securely, or set in your shell environment'
+        });
+    }
+}
+/**
+ * Get env var or exit with error
+ *
+ * NOTE: Does not auto-load .env files. Use `cli4ai secrets` for secure credential storage.
+ */
+export function env(name) {
+    const value = process.env[name];
+    if (!value) {
+        outputError('ENV_MISSING', `Missing required environment variable: ${name}`, {
+            variables: [name],
+            hint: 'Use "cli4ai secrets set ' + name + '" to store securely, or set in your shell environment'
+        });
+    }
+    return value;
+}
+/**
+ * Get env var or return default
+ */
+export function envOr(name, defaultValue) {
+    return process.env[name] || defaultValue;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Output JSON data to stdout
+ */
+export function output(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/**
+ * Output error and exit. Format is parseable JSON.
+ */
+export function outputError(code, message, details, exitCodeOverride) {
+    console.error(JSON.stringify({
+        error: code,
+        message,
+        ...details
+    }));
+    process.exit(exitCodeOverride ?? getExitCode(code));
+}
+/**
+ * Log to stderr (for progress messages)
+ */
+export function log(message) {
+    console.error(message);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// CLI CREATION
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Create a branded CLI program
+ */
+export function cli(name, version, description) {
+    const program = new Command()
+        .name(name)
+        .version(version, '-v, --version', 'Show version')
+        .description(description)
+        .addHelpText('beforeAll', `\n${BRAND}\n`)
+        .configureOutput({
+        writeErr: (str) => {
+            // Don't double-output errors
+            if (!str.includes('"error"')) {
+                process.stderr.write(str);
+            }
+        }
+    })
+        .exitOverride((err) => {
+        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+            process.exit(0);
+        }
+        if (err.code === 'commander.missingArgument') {
+            outputError('INVALID_INPUT', err.message, { code: err.code });
+        }
+        if (err.code === 'commander.unknownCommand') {
+            outputError('INVALID_INPUT', err.message, { code: err.code });
+        }
+        if (err.code !== 'commander.help') {
+            process.exit(1);
+        }
+    });
+    program.addHelpCommand('help [command]', 'Show help for command');
+    return program;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ERROR HANDLING
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Wrap an async action with error handling
+ */
+export function withErrorHandling(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            outputError('API_ERROR', message);
+        }
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITY HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Parse a string as JSON, or return error
+ */
+export function parseJson(str, context) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        outputError('PARSE_ERROR', `Invalid JSON${context ? ` in ${context}` : ''}`, {
+            input: str.slice(0, 100)
+        });
+    }
+}
+/**
+ * Sleep for ms milliseconds
+ */
+export const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/**
+ * Format bytes to human readable
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+/**
+ * Format date to ISO string (date only)
+ */
+export function formatDate(date) {
+    const d = new Date(date);
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Format date to ISO string (datetime)
+ */
+export function formatDateTime(date) {
+    const d = new Date(date);
+    return d.toISOString().slice(0, 19).replace('T', ' ');
+}