agent-vault-cli 0.1.0

package/src/core/audit.ts

@@ -0,0 +1,59 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const AUDIT_DIR = join(homedir(), '.agent-vault');
+const AUDIT_FILE = join(AUDIT_DIR, 'audit.log');
+
+export type AuditEvent =
+  | 'credential_stored'
+  | 'credential_retrieved'
+  | 'credential_deleted'
+  | 'login_filled'
+  | 'config_changed'
+  | 'rate_limit_exceeded';
+
+interface AuditEntry {
+  timestamp: string;
+  event: AuditEvent;
+  origin?: string;
+  details?: string;
+  success: boolean;
+}
+
+async function ensureAuditDir(): Promise<void> {
+  await mkdir(AUDIT_DIR, { recursive: true, mode: 0o700 });
+}
+
+/**
+ * Log an audit event to the audit log file.
+ * Never includes sensitive data like passwords or usernames.
+ */
+export async function logAuditEvent(
+  event: AuditEvent,
+  options: { origin?: string; details?: string; success?: boolean } = {}
+): Promise<void> {
+  try {
+    await ensureAuditDir();
+
+    const entry: AuditEntry = {
+      timestamp: new Date().toISOString(),
+      event,
+      origin: options.origin,
+      details: options.details,
+      success: options.success ?? true,
+    };
+
+    const line = JSON.stringify(entry) + '\n';
+    await appendFile(AUDIT_FILE, line, { mode: 0o600 });
+  } catch {
+    // Silently fail - audit logging should never break the main flow
+  }
+}
+
+/**
+ * Get the audit log file path (for admin/debug purposes)
+ */
+export function getAuditLogPath(): string {
+  return AUDIT_FILE;
+}

package/src/core/browser.ts

@@ -0,0 +1,131 @@
+import { chromium } from 'playwright';
+import type { BrowserConnection } from '../types/index.js';
+import { getConfigValue } from './config.js';
+
+const CDP_TIMEOUT_MS = 10000;
+
+// Default allowed CDP hosts for security
+const DEFAULT_CDP_ALLOWLIST = ['127.0.0.1', 'localhost', '::1'];
+
+/**
+ * Parse CDP allowlist from config
+ */
+async function getCdpAllowlist(): Promise<string[]> {
+  const configValue = await getConfigValue('cdpAllowlist');
+  if (configValue) {
+    return configValue.split(',').map((h) => h.trim().toLowerCase());
+  }
+  return DEFAULT_CDP_ALLOWLIST;
+}
+
+/**
+ * Check if a CDP endpoint host is in the allowlist
+ */
+async function isAllowedCdpHost(hostname: string): Promise<boolean> {
+  const allowlist = await getCdpAllowlist();
+  return allowlist.includes(hostname.toLowerCase());
+}
+
+export async function validateCDPEndpoint(endpoint: string): Promise<void> {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw new Error('Invalid CDP endpoint format');
+  }
+
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    throw new Error('CDP endpoint must use WebSocket protocol');
+  }
+
+  if (!url.hostname) {
+    throw new Error('CDP endpoint must have a valid hostname');
+  }
+
+  // Check against allowlist
+  const isAllowed = await isAllowedCdpHost(url.hostname);
+  if (!isAllowed) {
+    throw new Error(
+      'CDP endpoint host is not in the allowlist. ' +
+        'Add it with: vault config set cdpAllowlist "host1,host2"'
+    );
+  }
+}
+
+export async function connectToBrowser(cdpEndpoint: string): Promise<BrowserConnection> {
+  await validateCDPEndpoint(cdpEndpoint);
+
+  let browser;
+  try {
+    browser = await Promise.race([
+      chromium.connectOverCDP(cdpEndpoint),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('CDP connection timeout')), CDP_TIMEOUT_MS)
+      ),
+    ]);
+  } catch (error) {
+    // Sanitize connection errors - don't expose internal details
+    if (error instanceof Error) {
+      if (error.message.includes('timeout')) {
+        throw new Error('CDP connection timeout - ensure browser is running with remote debugging');
+      }
+      if (error.message.includes('ECONNREFUSED')) {
+        throw new Error('Cannot connect to CDP endpoint - ensure browser is running');
+      }
+    }
+    throw new Error('Failed to connect to browser');
+  }
+
+  const contexts = browser.contexts();
+
+  if (contexts.length === 0) {
+    await browser.close();
+    throw new Error('No browser context available');
+  }
+
+  const pages = contexts[0].pages();
+
+  if (pages.length === 0) {
+    await browser.close();
+    throw new Error('No browser page available');
+  }
+
+  return { browser, page: pages[0] };
+}
+
+export async function fillField(
+  page: BrowserConnection['page'],
+  selector: string,
+  value: string
+): Promise<void> {
+  try {
+    await page.fill(selector, value);
+  } catch {
+    // Sanitize selector errors - don't expose selector in error message
+    throw new Error('Failed to fill form field - selector may be invalid');
+  }
+}
+
+export async function clickElement(
+  page: BrowserConnection['page'],
+  selector: string
+): Promise<void> {
+  try {
+    await page.click(selector);
+  } catch {
+    // Sanitize selector errors
+    throw new Error('Failed to click element - selector may be invalid');
+  }
+}
+
+export async function validateSelector(
+  page: BrowserConnection['page'],
+  selector: string
+): Promise<boolean> {
+  try {
+    const element = await page.$(selector);
+    return element !== null;
+  } catch {
+    return false;
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,91 @@
+import { readFile, writeFile, mkdir, chmod, access, constants } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { lock, unlock } from 'proper-lockfile';
+import type { VaultConfig, ConfigKey } from '../types/index.js';
+import { logAuditEvent } from './audit.js';
+
+const CONFIG_DIR = join(homedir(), '.agent-vault');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+// Secure file permissions: owner read/write only
+const SECURE_DIR_MODE = 0o700;
+const SECURE_FILE_MODE = 0o600;
+
+async function ensureConfigDir(): Promise<void> {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: SECURE_DIR_MODE });
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadConfig(): Promise<VaultConfig> {
+  try {
+    const data = await readFile(CONFIG_FILE, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+export async function saveConfig(config: VaultConfig): Promise<void> {
+  await ensureConfigDir();
+
+  const exists = await fileExists(CONFIG_FILE);
+
+  // Create empty file if it doesn't exist (for locking)
+  if (!exists) {
+    await writeFile(CONFIG_FILE, '{}', { mode: SECURE_FILE_MODE });
+  }
+
+  // Use file locking to prevent race conditions
+  let release: (() => Promise<void>) | null = null;
+  try {
+    release = await lock(CONFIG_FILE, { retries: 3 });
+    await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: SECURE_FILE_MODE });
+    // Ensure permissions are set correctly
+    await chmod(CONFIG_FILE, SECURE_FILE_MODE);
+  } finally {
+    if (release) {
+      await release();
+    }
+  }
+}
+
+export async function getConfigValue(key: ConfigKey): Promise<string | undefined> {
+  const config = await loadConfig();
+  return config[key];
+}
+
+export async function setConfigValue(key: ConfigKey, value: string): Promise<void> {
+  const config = await loadConfig();
+  config[key] = value;
+  await saveConfig(config);
+  await logAuditEvent('config_changed', { details: `Key: ${key}` });
+}
+
+export async function unsetConfigValue(key: ConfigKey): Promise<boolean> {
+  const config = await loadConfig();
+  if (key in config) {
+    delete config[key];
+    await saveConfig(config);
+    await logAuditEvent('config_changed', { details: `Key removed: ${key}` });
+    return true;
+  }
+  return false;
+}
+
+export function isValidConfigKey(key: string): key is ConfigKey {
+  const validKeys: ConfigKey[] = ['defaultUsername', 'allowHttp', 'cdpAllowlist'];
+  return validKeys.includes(key as ConfigKey);
+}
+
+export function getValidConfigKeys(): ConfigKey[] {
+  return ['defaultUsername', 'allowHttp', 'cdpAllowlist'];
+}

package/src/core/crypto.ts

@@ -0,0 +1,106 @@
+import { randomInt } from 'node:crypto';
+import { customAlphabet } from 'nanoid';
+
+const PASSWORD_LENGTH = 24;
+const MIN_PASSWORD_LENGTH = 12;
+const PASSWORD_CHARSET =
+  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*';
+
+const CHAR_CLASSES = {
+  lowercase: 'abcdefghijklmnopqrstuvwxyz',
+  uppercase: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  digits: '0123456789',
+  special: '!@#$%^&*',
+} as const;
+
+/**
+ * Cryptographically secure random character selection
+ */
+function secureRandomChar(charset: string): string {
+  return charset[randomInt(charset.length)];
+}
+
+/**
+ * Cryptographically secure Fisher-Yates shuffle
+ */
+function secureShuffleArray<T>(array: T[]): T[] {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = randomInt(i + 1);
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Check if password meets complexity requirements
+ */
+function meetsComplexityRequirements(password: string): boolean {
+  return (
+    /[a-z]/.test(password) &&
+    /[A-Z]/.test(password) &&
+    /[0-9]/.test(password) &&
+    /[!@#$%^&*]/.test(password)
+  );
+}
+
+/**
+ * Generate a cryptographically secure password using Node.js crypto.randomInt
+ * Guarantees at least one character from each class (lowercase, uppercase, digit, special)
+ *
+ * @param length - Password length (minimum 12, default 24)
+ * @throws Error if length is less than minimum
+ */
+export function generatePassword(length: number = PASSWORD_LENGTH): string {
+  if (length < MIN_PASSWORD_LENGTH) {
+    throw new Error(`Password length must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+
+  // Start with one guaranteed character from each class
+  const chars = [
+    secureRandomChar(CHAR_CLASSES.lowercase),
+    secureRandomChar(CHAR_CLASSES.uppercase),
+    secureRandomChar(CHAR_CLASSES.digits),
+    secureRandomChar(CHAR_CLASSES.special),
+  ];
+
+  // Fill remaining length with random characters from full charset
+  while (chars.length < length) {
+    chars.push(secureRandomChar(PASSWORD_CHARSET));
+  }
+
+  // Cryptographically secure shuffle to randomize position of guaranteed chars
+  return secureShuffleArray(chars).join('');
+}
+
+/**
+ * Alternative password generator using nanoid's customAlphabet
+ * Regenerates until complexity requirements are met
+ *
+ * @param length - Password length (minimum 12, default 24)
+ * @throws Error if length is less than minimum
+ */
+export function generatePasswordNanoid(length: number = PASSWORD_LENGTH): string {
+  if (length < MIN_PASSWORD_LENGTH) {
+    throw new Error(`Password length must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+
+  const generate = customAlphabet(PASSWORD_CHARSET, length);
+
+  // Generate until we meet complexity requirements
+  // With 24 chars from a 70-char alphabet including all classes,
+  // probability of missing a class is extremely low (~0.01%)
+  let password: string;
+  let attempts = 0;
+  const maxAttempts = 100;
+
+  do {
+    password = generate();
+    attempts++;
+    if (attempts >= maxAttempts) {
+      throw new Error('Failed to generate compliant password after maximum attempts');
+    }
+  } while (!meetsComplexityRequirements(password));
+
+  return password;
+}

package/src/core/fields.ts

@@ -0,0 +1,59 @@
+import type { Page } from 'playwright';
+
+const USERNAME_SELECTORS = [
+  'input[type="email"]',
+  'input[name="email"]',
+  'input[autocomplete="username"]',
+  'input[autocomplete="email"]',
+  'input[name="username"]',
+  'input[id="username"]',
+  'input[id="email"]',
+];
+
+const PASSWORD_SELECTORS = [
+  'input[type="password"]',
+  'input[autocomplete="current-password"]',
+  'input[autocomplete="new-password"]',
+];
+
+const SUBMIT_SELECTORS = [
+  'button[type="submit"]',
+  'input[type="submit"]',
+  'button:has-text("Log in")',
+  'button:has-text("Sign in")',
+  'button:has-text("Login")',
+];
+
+export async function detectUsernameField(page: Page): Promise<string | null> {
+  for (const selector of USERNAME_SELECTORS) {
+    const element = await page.$(selector);
+    if (element && await element.isVisible()) {
+      return selector;
+    }
+  }
+  return null;
+}
+
+export async function detectPasswordField(page: Page): Promise<string | null> {
+  for (const selector of PASSWORD_SELECTORS) {
+    const element = await page.$(selector);
+    if (element && await element.isVisible()) {
+      return selector;
+    }
+  }
+  return null;
+}
+
+export async function detectSubmitButton(page: Page): Promise<string | null> {
+  for (const selector of SUBMIT_SELECTORS) {
+    try {
+      const element = await page.$(selector);
+      if (element && await element.isVisible()) {
+        return selector;
+      }
+    } catch {
+      // Some selectors might not be valid, continue
+    }
+  }
+  return null;
+}

package/src/core/keychain.ts

@@ -0,0 +1,110 @@
+import keytar from 'keytar';
+import { z } from 'zod';
+import type { RPConfig } from '../types/index.js';
+import { logAuditEvent } from './audit.js';
+import { checkRateLimit } from './ratelimit.js';
+
+const SERVICE_NAME = 'agent-vault';
+
+// Zod schema for strict validation of stored credentials
+const SelectorsSchema = z.object({
+  username: z.string().min(1),
+  password: z.string().min(1),
+  submit: z.string().optional(),
+});
+
+const CredentialsSchema = z.object({
+  username: z.string(),
+  password: z.string(),
+});
+
+const RPConfigSchema = z.object({
+  origin: z.string().url(),
+  selectors: SelectorsSchema,
+  credentials: CredentialsSchema,
+});
+
+/**
+ * Validate RPConfig data against schema
+ */
+function validateRPConfig(data: unknown): RPConfig | null {
+  const result = RPConfigSchema.safeParse(data);
+  if (!result.success) {
+    return null;
+  }
+  return result.data;
+}
+
+export async function storeRP(config: RPConfig): Promise<void> {
+  // Rate limit credential storage
+  await checkRateLimit('store_credentials');
+
+  // Validate config before storing
+  const validated = validateRPConfig(config);
+  if (!validated) {
+    throw new Error('Invalid credential configuration');
+  }
+
+  await keytar.setPassword(SERVICE_NAME, config.origin, JSON.stringify(validated));
+  await logAuditEvent('credential_stored', { origin: config.origin });
+}
+
+export async function getRP(origin: string): Promise<RPConfig | null> {
+  try {
+    // Rate limit credential retrieval
+    await checkRateLimit('get_credentials');
+
+    const data = await keytar.getPassword(SERVICE_NAME, origin);
+    if (!data) {
+      await logAuditEvent('credential_retrieved', { origin, success: false });
+      return null;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      // Corrupted JSON data
+      await logAuditEvent('credential_retrieved', {
+        origin,
+        details: 'Corrupted data',
+        success: false,
+      });
+      return null;
+    }
+
+    // Validate with zod schema
+    const validated = validateRPConfig(parsed);
+    if (!validated) {
+      await logAuditEvent('credential_retrieved', {
+        origin,
+        details: 'Schema validation failed',
+        success: false,
+      });
+      return null;
+    }
+
+    await logAuditEvent('credential_retrieved', { origin, success: true });
+    return validated;
+  } catch (error) {
+    // Don't expose internal errors - use generic message
+    if (error instanceof Error && error.message.includes('Rate limit')) {
+      throw error; // Re-throw rate limit errors
+    }
+    await logAuditEvent('credential_retrieved', {
+      origin,
+      details: 'Internal error',
+      success: false,
+    });
+    return null;
+  }
+}
+
+export async function deleteRP(origin: string): Promise<boolean> {
+  // Rate limit credential deletion
+  await checkRateLimit('delete_credentials');
+
+  const result = await keytar.deletePassword(SERVICE_NAME, origin);
+  await logAuditEvent('credential_deleted', { origin, success: result });
+  return result;
+}

package/src/core/origin.ts

@@ -0,0 +1,90 @@
+import { getConfigValue } from './config.js';
+
+export function extractOrigin(url: string): string {
+  const parsed = new URL(url);
+  return parsed.origin;
+}
+
+/**
+ * Check if origin uses HTTPS (secure)
+ */
+export function isSecureProtocol(origin: string): boolean {
+  try {
+    const url = new URL(origin);
+    return url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if origin uses HTTP (insecure)
+ */
+export function isHttpProtocol(origin: string): boolean {
+  try {
+    const url = new URL(origin);
+    return url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+export function isValidOrigin(origin: string): boolean {
+  try {
+    const url = new URL(origin);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+export interface OriginValidationOptions {
+  allowHttp?: boolean;
+}
+
+/**
+ * Validate an origin with security checks.
+ * By default, requires HTTPS to prevent credentials from being sent in plaintext.
+ */
+export async function validateOriginSecurity(
+  origin: string,
+  options: OriginValidationOptions = {}
+): Promise<void> {
+  // Check config for allowHttp setting
+  const configAllowHttp = await getConfigValue('allowHttp');
+  const allowHttp = options.allowHttp ?? configAllowHttp === 'true';
+
+  // Check HTTPS requirement
+  if (!allowHttp && isHttpProtocol(origin)) {
+    throw new Error(
+      'HTTP origins are not allowed by default. Credentials would be sent in plaintext. ' +
+        'Use --allow-http flag or set config allowHttp=true to override.'
+    );
+  }
+
+  // Validate basic origin format
+  if (!isValidOrigin(origin)) {
+    throw new Error('Invalid origin format');
+  }
+}
+
+export function extractAndValidateOrigin(url: string): string {
+  const origin = extractOrigin(url);
+  if (!isValidOrigin(origin)) {
+    throw new Error('Invalid page origin');
+  }
+  return origin;
+}
+
+/**
+ * Extract and validate origin with full security checks.
+ * Use this for operations that store or retrieve credentials.
+ */
+export async function extractAndValidateOriginSecure(
+  url: string,
+  options: OriginValidationOptions = {}
+): Promise<string> {
+  const origin = extractOrigin(url);
+  await validateOriginSecurity(origin, options);
+  return origin;
+}