@flowcodex/core 0.3.0

package/src/session/audit-log.ts

@@ -0,0 +1,201 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import type { AuditEntry, AuditLog, VerifyResult } from './types.js';
+
+const GENESIS_PREV = '0'.repeat(64);
+const DEFAULT_FSYNC_EVERY = 100;
+
+export interface AuditLogOptions {
+  dir: string;
+  fsyncEvery?: number | undefined;
+}
+
+export class DefaultAuditLog implements AuditLog {
+  private readonly dir: string;
+  private readonly fsyncEvery: number;
+  private readonly tailHash = new Map<string, string>();
+  private readonly tailIndex = new Map<string, number>();
+  private readonly unSyncedWrites = new Map<string, number>();
+
+  constructor(opts: AuditLogOptions) {
+    this.dir = opts.dir;
+    this.fsyncEvery = opts.fsyncEvery ?? DEFAULT_FSYNC_EVERY;
+  }
+
+  private filePath(sessionId: string): string {
+    return path.join(this.dir, `${sessionId}.audit.jsonl`);
+  }
+
+  async record(input: {
+    sessionId: string;
+    toolName: string;
+    toolUseId: string;
+    input: unknown;
+    output: unknown;
+    isError: boolean;
+  }): Promise<AuditEntry> {
+    const fp = this.filePath(input.sessionId);
+    await fsp.mkdir(path.dirname(fp), { recursive: true }).catch(() => {});
+
+    let prevHash = this.tailHash.get(input.sessionId);
+    let index = this.tailIndex.get(input.sessionId) ?? 0;
+
+    if (prevHash === undefined || index === 0) {
+      const entries = await this.readAll(input.sessionId);
+      const last = entries.at(-1);
+      prevHash = last?.hash ?? GENESIS_PREV;
+      index = last ? last.index + 1 : 0;
+    }
+
+    const id = randomUUID();
+    const ts = new Date().toISOString();
+
+    const content = {
+      id,
+      ts,
+      prevHash,
+      toolName: input.toolName,
+      toolUseId: input.toolUseId,
+      input: input.input,
+      output: input.output,
+      isError: input.isError,
+      index,
+    };
+    const hash = createHash('sha256').update(stableStringify(content), 'utf8').digest('hex');
+
+    const entry: AuditEntry = {
+      ...content,
+      hash,
+    };
+
+    const line = JSON.stringify(entry) + '\n';
+    await fsp.appendFile(fp, line, 'utf8');
+
+    this.tailHash.set(input.sessionId, hash);
+    this.tailIndex.set(input.sessionId, index + 1);
+
+    const count = (this.unSyncedWrites.get(input.sessionId) ?? 0) + 1;
+    this.unSyncedWrites.set(input.sessionId, count);
+    if (this.fsyncEvery !== Number.POSITIVE_INFINITY && count % this.fsyncEvery === 0) {
+      await this.sync(fp);
+    }
+
+    return entry;
+  }
+
+  async verify(sessionId: string): Promise<VerifyResult> {
+    let entries: AuditEntry[];
+    try {
+      entries = await this.readAll(sessionId);
+    } catch {
+      return { ok: true, entries: 0 };
+    }
+
+    if (entries.length === 0) return { ok: true, entries: 0 };
+
+    if (entries[0]?.prevHash !== GENESIS_PREV) {
+      return {
+        ok: false,
+        brokenAt: 0,
+        reason: 'first entry prevHash is not genesis (all-zeros)',
+      };
+    }
+
+    let prevHash = GENESIS_PREV;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      if (!e) continue;
+      if (e.prevHash !== prevHash) {
+        return {
+          ok: false,
+          brokenAt: i,
+          reason: `prevHash mismatch at entry ${i}`,
+        };
+      }
+      const content = {
+        id: e.id,
+        ts: e.ts,
+        prevHash: e.prevHash,
+        toolName: e.toolName,
+        toolUseId: e.toolUseId,
+        input: e.input,
+        output: e.output,
+        isError: e.isError,
+        index: e.index,
+      };
+      const expectedHash = createHash('sha256')
+        .update(stableStringify(content), 'utf8')
+        .digest('hex');
+      if (expectedHash !== e.hash) {
+        return {
+          ok: false,
+          brokenAt: i,
+          reason: `hash mismatch at entry ${i} (content was modified)`,
+        };
+      }
+      prevHash = e.hash;
+    }
+
+    return { ok: true, entries: entries.length };
+  }
+
+  async load(sessionId: string): Promise<AuditEntry[]> {
+    return this.readAll(sessionId);
+  }
+
+  async flush(sessionId: string): Promise<void> {
+    await this.sync(this.filePath(sessionId));
+  }
+
+  private async readAll(sessionId: string): Promise<AuditEntry[]> {
+    const fp = this.filePath(sessionId);
+    let raw: string;
+    try {
+      raw = await fsp.readFile(fp, 'utf8');
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw err;
+    }
+    const out: AuditEntry[] = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line) as AuditEntry);
+      } catch {
+        // skip corrupt lines
+      }
+    }
+    return out;
+  }
+
+  private async sync(fp: string): Promise<void> {
+    try {
+      const fh = await fsp.open(fp, 'r+');
+      try {
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      // best-effort
+    }
+  }
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = sortKeys(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}

package/src/session/auth-service.ts

@@ -0,0 +1,178 @@
+import { promises as fsp } from 'node:fs';
+import { DefaultSecretVault, restrictFilePermissions } from './secret-vault.js';
+import type { SecretVault } from './types.js';
+import { atomicWrite } from '../utils/fs.js';
+
+export interface ApiKeyEntry {
+  label: string;
+  key: string;
+  createdAt: string;
+}
+
+export interface AuthEntry {
+  providerId: string;
+  keys: ApiKeyEntry[];
+  activeLabel: string;
+}
+
+export interface AuthProviderStatus {
+  providerId: string;
+  keyCount: number;
+  activeLabel: string | undefined;
+  lastUsed: string | undefined;
+  envVarDetected: boolean;
+}
+
+export interface AuthService {
+  load(): Promise<void>;
+  get(providerId: string): ApiKeyEntry | undefined;
+  all(): Record<string, ApiKeyEntry[]>;
+  set(providerId: string, key: string, label?: string): Promise<void>;
+  remove(providerId: string, label?: string): Promise<void>;
+  list(): Promise<AuthEntry[]>;
+  status(providerId: string): Promise<AuthProviderStatus>;
+  setActive(providerId: string, label: string): Promise<void>;
+}
+
+interface AuthFile {
+  version: number;
+  providers: Record<
+    string,
+    {
+      activeLabel: string;
+      keys: ApiKeyEntry[];
+    }
+  >;
+}
+
+export interface AuthServiceOptions {
+  authFile: string;
+  keyFile: string;
+}
+
+const AUTH_FILE_VERSION = 1;
+
+export class DefaultAuthService implements AuthService {
+  private vault: SecretVault;
+  private authFile: string;
+  private data: AuthFile = { version: AUTH_FILE_VERSION, providers: {} };
+
+  constructor(opts: AuthServiceOptions) {
+    this.authFile = opts.authFile;
+    this.vault = new DefaultSecretVault({ keyFile: opts.keyFile });
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await fsp.readFile(this.authFile, 'utf-8');
+      const decrypted = this.vault.decrypt(raw);
+      const parsed = JSON.parse(decrypted) as AuthFile;
+      if (parsed && typeof parsed === 'object' && parsed.providers) {
+        this.data = parsed;
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        this.data = { version: AUTH_FILE_VERSION, providers: {} };
+        return;
+      }
+      this.data = { version: AUTH_FILE_VERSION, providers: {} };
+    }
+  }
+
+  get(providerId: string): ApiKeyEntry | undefined {
+    const provider = this.data.providers[providerId];
+    if (!provider) return undefined;
+    return provider.keys.find((k) => k.label === provider.activeLabel) ?? provider.keys[0];
+  }
+
+  all(): Record<string, ApiKeyEntry[]> {
+    const result: Record<string, ApiKeyEntry[]> = {};
+    for (const [id, provider] of Object.entries(this.data.providers)) {
+      result[id] = provider.keys;
+    }
+    return result;
+  }
+
+  async set(providerId: string, key: string, label?: string): Promise<void> {
+    const existing = this.data.providers[providerId];
+    const provider = existing ?? { activeLabel: '', keys: [] as ApiKeyEntry[] };
+    if (!existing) {
+      this.data.providers[providerId] = provider;
+    }
+    const finalLabel =
+      label ?? (provider.keys.length === 0 ? 'default' : `key-${provider.keys.length + 1}`);
+    provider.keys = provider.keys.filter((k) => k.label !== finalLabel);
+    provider.keys.push({
+      label: finalLabel,
+      key,
+      createdAt: new Date().toISOString(),
+    });
+    if (!provider.activeLabel || provider.keys.length === 1) {
+      provider.activeLabel = finalLabel;
+    }
+    await this.save();
+  }
+
+  async remove(providerId: string, label?: string): Promise<void> {
+    const provider = this.data.providers[providerId];
+    if (!provider) return;
+    if (label === undefined) {
+      delete this.data.providers[providerId];
+    } else {
+      provider.keys = provider.keys.filter((k) => k.label !== label);
+      if (provider.activeLabel === label) {
+        provider.activeLabel = provider.keys[0]?.label ?? '';
+      }
+      if (provider.keys.length === 0) {
+        delete this.data.providers[providerId];
+      }
+    }
+    await this.save();
+  }
+
+  async list(): Promise<AuthEntry[]> {
+    const entries: AuthEntry[] = [];
+    for (const [id, provider] of Object.entries(this.data.providers)) {
+      entries.push({
+        providerId: id,
+        keys: provider.keys,
+        activeLabel: provider.activeLabel,
+      });
+    }
+    return entries;
+  }
+
+  async status(providerId: string): Promise<AuthProviderStatus> {
+    const provider = this.data.providers[providerId];
+    const envVar =
+      providerId === 'anthropic' ? 'ANTHROPIC_API_KEY' : `${providerId.toUpperCase()}_API_KEY`;
+    const lastUsed = provider?.keys.length ? provider.keys[provider.keys.length - 1]?.createdAt : undefined;
+    return {
+      providerId,
+      keyCount: provider?.keys.length ?? 0,
+      activeLabel: provider?.activeLabel || undefined,
+      lastUsed,
+      envVarDetected: process.env[envVar] !== undefined,
+    };
+  }
+
+  async setActive(providerId: string, label: string): Promise<void> {
+    const provider = this.data.providers[providerId];
+    if (!provider) {
+      throw new Error(`No keys for provider "${providerId}"`);
+    }
+    const exists = provider.keys.some((k) => k.label === label);
+    if (!exists) {
+      throw new Error(`No key with label "${label}" for provider "${providerId}"`);
+    }
+    provider.activeLabel = label;
+    await this.save();
+  }
+
+  private async save(): Promise<void> {
+    const json = JSON.stringify(this.data, null, 2);
+    const encrypted = this.vault.encrypt(json);
+    await atomicWrite(this.authFile, encrypted);
+    await restrictFilePermissions(this.authFile);
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,26 @@
+export type { SessionEvent, SessionSummary, AuditEntry, VerifyResult, SessionStore, SecretVault, AuditLog } from './types.js';
+export { DefaultSecretVault, ENCRYPTED_PREFIX, restrictFilePermissions, isSecretField } from './secret-vault.js';
+export type { SecretVaultOptions } from './secret-vault.js';
+export {
+  DefaultSessionStore,
+  generateSessionId,
+  projectHash,
+  flowcodexHome,
+  sessionsDir,
+  recordsDir,
+  reconstructMessages,
+  keyFilePath,
+  configFilePath,
+  authFilePath,
+} from './session-store.js';
+export type { SessionStoreOptions } from './session-store.js';
+export { DefaultAuditLog, stableStringify } from './audit-log.js';
+export type { AuditLogOptions } from './audit-log.js';
+export type {
+  ApiKeyEntry,
+  AuthEntry,
+  AuthProviderStatus,
+  AuthService,
+  AuthServiceOptions,
+} from './auth-service.js';
+export { DefaultAuthService } from './auth-service.js';

package/src/session/secret-vault.ts

@@ -0,0 +1,183 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import type { SecretVault } from './types.js';
+import { ConfigError, ERROR_CODES } from '../types/errors.js';
+
+export const ENCRYPTED_PREFIX = 'enc:v1:';
+
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const ALGO = 'aes-256-gcm';
+const KEY_FILE_MODE = 0o600;
+
+export interface SecretVaultOptions {
+  keyFile: string;
+}
+
+export class DefaultSecretVault implements SecretVault {
+  private readonly keyFile: string;
+  private key?: Buffer | undefined;
+
+  constructor(opts: SecretVaultOptions) {
+    this.keyFile = opts.keyFile;
+  }
+
+  isEncrypted(value: string): boolean {
+    return typeof value === 'string' && value.startsWith(ENCRYPTED_PREFIX);
+  }
+
+  encrypt(plaintext: string): string {
+    if (this.isEncrypted(plaintext)) return plaintext;
+    const key = this.loadOrCreateKey();
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGO, key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${ENCRYPTED_PREFIX}${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+  }
+
+  decrypt(value: string): string {
+    if (!this.isEncrypted(value)) return value;
+    const rest = value.slice(ENCRYPTED_PREFIX.length);
+    const parts = rest.split(':');
+    if (parts.length !== 3) {
+      throw new ConfigError({
+        message: 'SecretVault: malformed encrypted value',
+        code: ERROR_CODES.CONFIG_PARSE_FAILED,
+        context: { field: 'encrypted_value' },
+      });
+    }
+    const [ivB64, tagB64, ctB64] = parts as [string, string, string];
+    const iv = Buffer.from(ivB64, 'base64');
+    const tag = Buffer.from(tagB64, 'base64');
+    const ct = Buffer.from(ctB64, 'base64');
+    if (iv.length !== IV_BYTES) {
+      throw new ConfigError({
+        message: `SecretVault: bad IV length (${iv.length}, expected ${IV_BYTES})`,
+        code: ERROR_CODES.CONFIG_PARSE_FAILED,
+        context: { expected: IV_BYTES, actual: iv.length },
+      });
+    }
+    if (tag.length !== TAG_BYTES) {
+      throw new ConfigError({
+        message: `SecretVault: bad tag length (${tag.length}, expected ${TAG_BYTES})`,
+        code: ERROR_CODES.CONFIG_PARSE_FAILED,
+        context: { expected: TAG_BYTES, actual: tag.length },
+      });
+    }
+    const key = this.loadOrCreateKey();
+    const decipher = createDecipheriv(ALGO, key, iv);
+    decipher.setAuthTag(tag);
+    const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return pt.toString('utf8');
+  }
+
+  private loadOrCreateKey(): Buffer {
+    if (this.key) return this.key;
+    try {
+      const buf = fs.readFileSync(this.keyFile);
+      if (buf.length !== KEY_BYTES) {
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it to regenerate.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length },
+        });
+      }
+      this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
+      return this.key;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+    fs.mkdirSync(path.dirname(this.keyFile), { recursive: true });
+    const newKey = randomBytes(KEY_BYTES);
+    try {
+      fs.writeFileSync(this.keyFile, newKey, { mode: KEY_FILE_MODE, flag: 'wx' });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      const buf = fs.readFileSync(this.keyFile);
+      if (buf.length !== KEY_BYTES) {
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it to regenerate.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length },
+        });
+      }
+      this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
+      return this.key;
+    }
+    this.key = newKey;
+    return newKey;
+  }
+}
+
+function checkKeyFilePermissions(keyFile: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    const stat = fs.statSync(keyFile);
+    const actualMode = stat.mode & 0o777;
+    if (actualMode !== KEY_FILE_MODE) {
+      process.stderr.write(
+        JSON.stringify({
+          level: 'warn',
+          event: 'vault.key_file_wrong_permissions',
+          message: `Key file ${keyFile} has mode ${actualMode.toString(8)} — expected ${KEY_FILE_MODE.toString(8)}`,
+          timestamp: new Date().toISOString(),
+        }) + '\n',
+      );
+    }
+  } catch {
+    // stat failed, not critical
+  }
+}
+
+export async function restrictFilePermissions(
+  filePath: string,
+  opts?: { warn?: ((msg: string) => void) | undefined },
+): Promise<void> {
+  const warn = opts?.warn ?? ((msg: string) => process.stderr.write(msg + '\n'));
+  if (process.platform === 'win32') {
+    try {
+      const { execFile } = await import('node:child_process');
+      const { promisify } = await import('node:util');
+      const execFileAsync = promisify(execFile);
+      const user = windowsAccountName();
+      if (!user) {
+        warn(`[secret-vault] Could not determine Windows user for ${filePath}; skipping icacls.`);
+        return;
+      }
+      await execFileAsync('icacls', [filePath, '/inheritance:r', '/grant:r', `${user}:(F)`]);
+    } catch {
+      warn(`[secret-vault] Could not restrict permissions on ${filePath}.`);
+    }
+  } else {
+    try {
+      await fsp.chmod(filePath, 0o600);
+    } catch {
+      // best-effort
+    }
+  }
+}
+
+function windowsAccountName(): string | undefined {
+  const username = process.env.USERNAME || process.env.USER;
+  if (!username || username.includes('\0')) return undefined;
+  const domain = process.env.USERDOMAIN;
+  if (domain && !domain.includes('\0')) return `${domain}\\${username}`;
+  return username;
+}
+
+const SECRET_KEY_PATTERN =
+  /(?:apikey|api_key|authtoken|auth_token|bearer|secret|password|passwd|pwd|refreshtoken|refresh_token|sessionkey|session_key|access[_-]?token|private[_-]?key)/i;
+
+const NON_SECRET_OVERRIDES = new Set(['publickey', 'public_key']);
+
+export function isSecretField(name: string): boolean {
+  const lc = name.toLowerCase();
+  if (NON_SECRET_OVERRIDES.has(lc)) return false;
+  return SECRET_KEY_PATTERN.test(lc);
+}