@cyanautomation/kaseki-agent 1.4.1

package/src/run-artifact-metadata-cache.ts

@@ -0,0 +1,184 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface RunArtifactFileSnapshot {
+  exists: boolean;
+  size: number;
+  mtimeMs?: number;
+}
+
+export type RunArtifactMetadata = Record<string, RunArtifactFileSnapshot>;
+
+interface CacheEntry {
+  timestamp: number;
+  files: Map<string, RunArtifactFileSnapshot>;
+}
+
+export interface RunArtifactMetadataCacheOptions {
+  ttlMs?: number;
+  maxEntries?: number;
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 250;
+
+/**
+ * Shared cache for terminal run artifact metadata.
+ *
+ * Entries are keyed by job id and result directory. Cached file snapshots are
+ * validated against current size/mtime before reuse, so terminal status and
+ * artifact routes can share availability metadata without diverging when an
+ * artifact is rewritten after finalization.
+ */
+export class RunArtifactMetadataCache {
+  private readonly ttlMs: number;
+  private readonly maxEntries: number;
+  private readonly cache = new Map<string, CacheEntry>();
+
+  constructor(options: RunArtifactMetadataCacheOptions = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+
+  get(jobId: string, resultDir: string, fileNames: readonly string[], cacheable: boolean): RunArtifactMetadata {
+    if (!cacheable) {
+      return this.readMetadata(resultDir, fileNames);
+    }
+
+    const key = this.cacheKey(jobId, resultDir);
+    const cached = this.cache.get(key);
+    if (cached && this.isUsable(cached, resultDir, fileNames)) {
+      cached.timestamp = Date.now();
+      return this.project(cached.files, fileNames);
+    }
+
+    const metadata = this.readMetadata(resultDir, fileNames);
+    this.set(key, metadata);
+    return metadata;
+  }
+
+  clear(jobId?: string, resultDir?: string): void {
+    if (!jobId && !resultDir) {
+      this.cache.clear();
+      return;
+    }
+
+    const normalizedResultDir = resultDir ? this.normalizeResultDir(resultDir) : undefined;
+    for (const key of Array.from(this.cache.keys())) {
+      const [entryJobId, entryResultDir] = this.parseKey(key);
+      if (jobId && entryJobId !== jobId) {
+        continue;
+      }
+      if (normalizedResultDir && entryResultDir !== normalizedResultDir) {
+        continue;
+      }
+      this.cache.delete(key);
+    }
+  }
+
+  getStats(): { entries: number } {
+    return { entries: this.cache.size };
+  }
+
+  private isUsable(entry: CacheEntry, resultDir: string, fileNames: readonly string[]): boolean {
+    if (Date.now() - entry.timestamp >= this.ttlMs) {
+      return false;
+    }
+
+    for (const fileName of fileNames) {
+      const cached = entry.files.get(fileName);
+      if (!cached) {
+        return false;
+      }
+      const current = this.readOne(resultDir, fileName);
+      if (!this.sameSnapshot(cached, current)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  private readMetadata(resultDir: string, fileNames: readonly string[]): RunArtifactMetadata {
+    const metadata: RunArtifactMetadata = {};
+    for (const fileName of fileNames) {
+      metadata[fileName] = this.readOne(resultDir, fileName);
+    }
+    return metadata;
+  }
+
+  private readOne(resultDir: string, fileName: string): RunArtifactFileSnapshot {
+    try {
+      const stat = fs.statSync(path.join(resultDir, fileName));
+      if (!stat.isFile()) {
+        return { exists: false, size: 0 };
+      }
+      return { exists: true, size: stat.size, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { exists: false, size: 0 };
+    }
+  }
+
+  private sameSnapshot(a: RunArtifactFileSnapshot, b: RunArtifactFileSnapshot): boolean {
+    if (a.exists !== b.exists || a.size !== b.size) {
+      return false;
+    }
+    if (!a.exists && !b.exists) {
+      return true;
+    }
+    return a.mtimeMs === b.mtimeMs;
+  }
+
+  private project(files: Map<string, RunArtifactFileSnapshot>, fileNames: readonly string[]): RunArtifactMetadata {
+    const metadata: RunArtifactMetadata = {};
+    for (const fileName of fileNames) {
+      metadata[fileName] = files.get(fileName) ?? { exists: false, size: 0 };
+    }
+    return metadata;
+  }
+
+  private set(key: string, metadata: RunArtifactMetadata): void {
+    if (!this.cache.has(key) && this.cache.size >= this.maxEntries) {
+      const oldest = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
+      if (oldest) {
+        this.cache.delete(oldest[0]);
+      }
+    }
+
+    this.cache.set(key, {
+      timestamp: Date.now(),
+      files: new Map(Object.entries(metadata)),
+    });
+  }
+
+  private cacheKey(jobId: string, resultDir: string): string {
+    return `${jobId}\0${this.normalizeResultDir(resultDir)}`;
+  }
+
+  private parseKey(key: string): [string, string] {
+    const separatorIndex = key.indexOf('\0');
+    if (separatorIndex === -1) {
+      return [key, ''];
+    }
+    return [key.slice(0, separatorIndex), key.slice(separatorIndex + 1)];
+  }
+
+  private normalizeResultDir(resultDir: string): string {
+    return path.resolve(resultDir);
+  }
+}
+
+export const runArtifactMetadataCache = new RunArtifactMetadataCache();
+
+export function getRunArtifactMetadata(
+  jobId: string,
+  resultDir: string,
+  fileNames: readonly string[],
+  cacheable: boolean
+): RunArtifactMetadata {
+  return runArtifactMetadataCache.get(jobId, resultDir, fileNames, cacheable);
+}
+
+export function clearRunArtifactMetadataCache(jobId?: string, resultDir?: string): void {
+  runArtifactMetadataCache.clear(jobId, resultDir);
+}

package/src/secret-value-cache.test.ts

@@ -0,0 +1,66 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { SecretValueCache } from './secret-value-cache';
+
+describe('SecretValueCache', () => {
+  let testDir: string;
+  let cache: SecretValueCache;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join('/tmp', 'secret-value-cache-test-'));
+    cache = new SecretValueCache();
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test('returns cached file values while mtime and size are unchanged', () => {
+    const secretFile = path.join(testDir, 'secret');
+    const fixedTime = new Date('2020-01-01T00:00:00.000Z');
+    fs.writeFileSync(secretFile, 'secret-one\n');
+    fs.utimesSync(secretFile, fixedTime, fixedTime);
+
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('secret-one');
+
+    fs.writeFileSync(secretFile, 'secret-two\n');
+    fs.utimesSync(secretFile, fixedTime, fixedTime);
+
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('secret-one');
+  });
+
+  test('rereads file values when file metadata changes', () => {
+    const secretFile = path.join(testDir, 'secret');
+    fs.writeFileSync(secretFile, 'old-secret\n');
+
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('old-secret');
+
+    fs.writeFileSync(secretFile, 'new-secret-value\n');
+
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('new-secret-value');
+  });
+
+  test('prefers inline values over file values', () => {
+    const secretFile = path.join(testDir, 'secret');
+    fs.writeFileSync(secretFile, 'file-secret\n');
+    fs.rmSync(secretFile);
+
+    expect(cache.readSecretValue(' inline-secret ', secretFile)).toBe('inline-secret');
+  });
+
+  test('clear drops cached values for tests', () => {
+    const secretFile = path.join(testDir, 'secret');
+    const fixedTime = new Date('2020-01-01T00:00:00.000Z');
+    fs.writeFileSync(secretFile, 'old-secret\n');
+    fs.utimesSync(secretFile, fixedTime, fixedTime);
+
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('old-secret');
+
+    fs.writeFileSync(secretFile, 'new-secret\n');
+    fs.utimesSync(secretFile, fixedTime, fixedTime);
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('old-secret');
+
+    cache.clear();
+    expect(cache.readSecretValue(undefined, secretFile)).toBe('new-secret');
+  });
+});

package/src/secret-value-cache.ts

@@ -0,0 +1,55 @@
+import * as fs from 'fs';
+
+type SecretCacheEntry = {
+  value: string;
+  mtimeMs: number;
+  size: number;
+};
+
+/**
+ * Small synchronous cache for secret files that are read repeatedly while the
+ * process stays alive. Entries are keyed by file path and invalidated whenever
+ * the file metadata changes.
+ */
+export class SecretValueCache {
+  private entries = new Map<string, SecretCacheEntry>();
+
+  readFile(filePath: string): string {
+    const stat = fs.statSync(filePath);
+    const cached = this.entries.get(filePath);
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+      return cached.value;
+    }
+
+    const value = fs.readFileSync(filePath, 'utf-8');
+    this.entries.set(filePath, {
+      value,
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+    });
+    return value;
+  }
+
+  readSecretValue(inlineValue?: string, filePath?: string): string | undefined {
+    const trimmedInline = inlineValue?.trim();
+    if (trimmedInline) {
+      return trimmedInline;
+    }
+    if (!filePath) {
+      return undefined;
+    }
+
+    try {
+      const value = this.readFile(filePath).replace(/^\uFEFF/, '').trim();
+      return value || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+export const secretValueCache = new SecretValueCache();

package/src/secrets/SecretsManager.ts

@@ -0,0 +1,343 @@
+/**
+ * Secrets Manager
+ *
+ * Secure credential storage with keyring integration
+ * - Primary: Linux keyring (pass)
+ * - Fallback: File-based storage (~/.kaseki/secrets/) with 0600 permissions
+ *
+ * Note: macOS Keychain and Windows Credential Manager support can be added
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { createLogger } from '../logger';
+
+const logger = createLogger('secrets');
+
+export interface SecretsStore {
+  store(key: string, value: string): Promise<void>;
+  retrieve(key: string): Promise<string | null>;
+  delete(key: string): Promise<void>;
+  list(): Promise<string[]>;
+}
+
+/**
+ * File-based secrets store (fallback, headless systems)
+ */
+export class FileSecretsStore implements SecretsStore {
+  private baseDir: string;
+
+  constructor(baseDir?: string) {
+    this.baseDir = baseDir || path.join(os.homedir(), '.kaseki', 'secrets');
+  }
+
+  async store(key: string, value: string): Promise<void> {
+    try {
+      await fs.mkdir(this.baseDir, { recursive: true, mode: 0o700 });
+      const filePath = path.join(this.baseDir, key);
+
+      // Write with restrictive permissions (0600 - owner read/write only)
+      await fs.writeFile(filePath, value, {
+        mode: 0o600,
+        flag: 'w',
+      });
+
+      logger.debug(`Secret stored: ${key} -> ${filePath}`);
+    } catch (error) {
+      throw new Error(`Failed to store secret: ${error}`);
+    }
+  }
+
+  async retrieve(key: string): Promise<string | null> {
+    try {
+      const filePath = path.join(this.baseDir, key);
+      const stat = await fs.stat(filePath);
+
+      // Security check: verify file permissions are restrictive
+      if ((stat.mode & 0o077) !== 0) {
+        logger.warn(`Secret file has overly permissive permissions: ${filePath}`);
+      }
+
+      const value = await fs.readFile(filePath, 'utf-8');
+      return value.trim();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null;
+      }
+      throw new Error(`Failed to retrieve secret: ${error}`);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      const filePath = path.join(this.baseDir, key);
+      await fs.unlink(filePath);
+      logger.debug(`Secret deleted: ${key}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw new Error(`Failed to delete secret: ${error}`);
+      }
+    }
+  }
+
+  async list(): Promise<string[]> {
+    try {
+      const files = await fs.readdir(this.baseDir);
+      return files;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  }
+}
+
+/**
+ * Linux pass (password-store) backed secrets
+ * Requires: pass package installed and initialized
+ */
+export class PassSecretsStore implements SecretsStore {
+  private prefix: string;
+
+  constructor(prefix: string = 'kaseki-agent') {
+    this.prefix = prefix;
+  }
+
+  private getPassKey(key: string): string {
+    return `${this.prefix}/${key}`;
+  }
+
+  private isPassAvailable(): boolean {
+    try {
+      execSync('command -v pass', { shell: '/bin/bash', stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private isPassInitialized(): boolean {
+    try {
+      execSync('pass ls > /dev/null 2>&1', { shell: '/bin/bash', stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async store(key: string, value: string): Promise<void> {
+    if (!this.isPassAvailable()) {
+      throw new Error('pass (password-store) not installed. Install with: sudo apt install pass');
+    }
+
+    if (!this.isPassInitialized()) {
+      throw new Error('pass (password-store) not initialized. Run: pass init');
+    }
+
+    try {
+      // Use echo + pass insert to avoid interactive prompt
+      const passKey = this.getPassKey(key);
+      execSync(`echo "${value.replace(/"/g, '\\"')}" | pass insert -f "${passKey}"`, {
+        shell: '/bin/bash',
+      });
+
+      logger.debug(`Secret stored in pass: ${passKey}`);
+    } catch (error) {
+      throw new Error(`Failed to store secret in pass: ${error}`);
+    }
+  }
+
+  async retrieve(key: string): Promise<string | null> {
+    if (!this.isPassAvailable()) {
+      logger.debug('pass not available, skipping keyring retrieval');
+      return null;
+    }
+
+    try {
+      const passKey = this.getPassKey(key);
+      const result = execSync(`pass show "${passKey}" 2>/dev/null || echo ""`, {
+        shell: '/bin/bash',
+        encoding: 'utf-8',
+      });
+
+      return result.trim() || null;
+    } catch (error) {
+      logger.debug(`Failed to retrieve secret from pass: ${error}`);
+      return null;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!this.isPassAvailable()) {
+      return;
+    }
+
+    try {
+      const passKey = this.getPassKey(key);
+      execSync(`pass rm -f "${passKey}"`, { shell: '/bin/bash' });
+      logger.debug(`Secret deleted from pass: ${passKey}`);
+    } catch (error) {
+      throw new Error(`Failed to delete secret from pass: ${error}`);
+    }
+  }
+
+  async list(): Promise<string[]> {
+    if (!this.isPassAvailable()) {
+      return [];
+    }
+
+    try {
+      const result = execSync(`pass ls 2>/dev/null | grep "^${this.prefix}/" || echo ""`, {
+        shell: '/bin/bash',
+        encoding: 'utf-8',
+      });
+
+      return result
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => line.replace(`${this.prefix}/`, ''));
+    } catch (error) {
+      logger.debug(`Failed to list secrets from pass: ${error}`);
+      return [];
+    }
+  }
+}
+
+/**
+ * Secrets Manager - Main interface
+ * Tries keyring first, falls back to file storage
+ */
+export class SecretsManager {
+  private fileStore: FileSecretsStore;
+  private passStore: PassSecretsStore;
+  private usePassIfAvailable: boolean;
+
+  constructor(usePassIfAvailable: boolean = true) {
+    this.fileStore = new FileSecretsStore();
+    this.passStore = new PassSecretsStore();
+    this.usePassIfAvailable = usePassIfAvailable;
+  }
+
+  /**
+   * Store a secret with automatic fallback
+   */
+  async store(key: string, value: string): Promise<void> {
+    if (this.usePassIfAvailable && this.isPassAvailable()) {
+      try {
+        await this.passStore.store(key, value);
+        return;
+      } catch (error) {
+        logger.warn(`Keyring storage failed, falling back to file storage: ${error}`);
+      }
+    }
+
+    await this.fileStore.store(key, value);
+  }
+
+  /**
+   * Retrieve a secret (tries keyring first, then file)
+   */
+  async retrieve(key: string): Promise<string | null> {
+    // Try file-based first (where users might have stored it)
+    const fileValue = await this.fileStore.retrieve(key);
+    if (fileValue) {
+      return fileValue;
+    }
+
+    // Try keyring if available
+    if (this.usePassIfAvailable && this.isPassAvailable()) {
+      const passValue = await this.passStore.retrieve(key);
+      if (passValue) {
+        return passValue;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Delete a secret from both stores
+   */
+  async delete(key: string): Promise<void> {
+    try {
+      await this.fileStore.delete(key);
+    } catch (error) {
+      logger.debug(`Failed to delete from file store: ${error}`);
+    }
+
+    if (this.usePassIfAvailable && this.isPassAvailable()) {
+      try {
+        await this.passStore.delete(key);
+      } catch (error) {
+        logger.debug(`Failed to delete from keyring: ${error}`);
+      }
+    }
+  }
+
+  /**
+   * List all stored secrets
+   */
+  async list(): Promise<Map<string, string>> {
+    const secrets = new Map<string, string>();
+
+    // List from file store
+    const fileKeys = await this.fileStore.list();
+    for (const key of fileKeys) {
+      const value = await this.fileStore.retrieve(key);
+      if (value) {
+        secrets.set(key, `file:${path.join(os.homedir(), '.kaseki', 'secrets', key)}`);
+      }
+    }
+
+    // List from keyring
+    if (this.usePassIfAvailable && this.isPassAvailable()) {
+      const passKeys = await this.passStore.list();
+      for (const key of passKeys) {
+        secrets.set(key, `keyring:${key}`);
+      }
+    }
+
+    return secrets;
+  }
+
+  /**
+   * Check if pass is available
+   */
+  private isPassAvailable(): boolean {
+    try {
+      execSync('command -v pass', { shell: '/bin/bash', stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Initialize/setup keyring (interactive)
+   */
+  async initializeKeyring(): Promise<void> {
+    if (!this.isPassAvailable()) {
+      throw new Error('pass (password-store) not installed');
+    }
+
+    try {
+      execSync('pass init 2>&1', { shell: '/bin/bash', stdio: 'inherit' });
+      logger.info('Keyring initialized successfully');
+    } catch (error) {
+      throw new Error(`Failed to initialize keyring: ${error}`);
+    }
+  }
+
+  /**
+   * Get recommended storage method for system
+   */
+  getRecommendedStore(): string {
+    if (this.isPassAvailable()) {
+      return 'keyring (pass)';
+    }
+    return 'file (~/.kaseki/secrets/)';
+  }
+}