codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14

package/src/alpha6/store-sidecars.ts

@@ -0,0 +1,335 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { SidecarEventRecord } from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+
+const HASH_64_PATTERN = /^[a-f0-9]{64}$/;
+const SIDECAR_NAME_PATTERN = /^[a-z][a-z0-9-]*\.jsonl$/;
+
+type CanonicalJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | CanonicalJsonValue[]
+  | { [key: string]: CanonicalJsonValue };
+
+export interface PreparedSidecarAppend<T extends SidecarEventRecord> {
+  event: T;
+  content: string;
+  contentHash: string;
+}
+
+export interface SidecarEventValidationContext {
+  file: string;
+  line: number;
+  eventId: string;
+}
+
+export interface SidecarReadOptions<T extends SidecarEventRecord> {
+  validateEvent?: SidecarEventValidator<T>;
+  trustedRoot?: string;
+}
+
+export type SidecarAppendInput<T extends SidecarEventRecord> = Omit<T, 'previousEventHash' | 'eventHash'> & {
+  previousEventHash?: string | null;
+  eventHash?: string;
+};
+
+export type SidecarEventValidator<T extends SidecarEventRecord> = (
+  event: T,
+  context: SidecarEventValidationContext,
+) => void;
+
+export function sha256Hex(content: string | Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function canonicalJsonStringify(value: unknown): string {
+  return JSON.stringify(canonicalizeJson(value));
+}
+
+export function assertHash64(value: string, label: string): void {
+  if (!HASH_64_PATTERN.test(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a sha256 hex digest.`, { value });
+  }
+}
+
+export function assertSafeSidecarName(name: string): void {
+  if (!name.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Sidecar name is required.');
+  }
+  if (path.isAbsolute(name) || name.includes('/') || name.includes('\\') || !SIDECAR_NAME_PATTERN.test(name)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Invalid sidecar path: ${name}`, {
+      expectedPattern: SIDECAR_NAME_PATTERN.source,
+    });
+  }
+}
+
+export function resolveSidecarPath(entityRoot: string, sidecarName: string, trustedRoot?: string): string {
+  assertSafeSidecarName(sidecarName);
+  assertNoSymlinkPathComponents(entityRoot, {
+    label: 'Sidecar entity root',
+    requireLeaf: true,
+    ...(trustedRoot ? { trustedRoot } : {}),
+  });
+  return path.join(entityRoot, sidecarName);
+}
+
+export function computeSidecarEventHash<T extends SidecarEventRecord>(event: Omit<T, 'eventHash'> | T): string {
+  const { eventHash: _eventHash, ...payload } = event as Record<string, unknown>;
+  return sha256Hex(canonicalJsonStringify(payload));
+}
+
+export function renderSidecarEvent<T extends SidecarEventRecord>(event: T): string {
+  return `${canonicalJsonStringify(event)}\n`;
+}
+
+export function renderSidecarEvents<T extends SidecarEventRecord>(events: readonly T[]): string {
+  return events.map((event) => renderSidecarEvent(event)).join('');
+}
+
+export function readSidecarEvents<T extends SidecarEventRecord>(file: string, options: SidecarReadOptions<T> = {}): T[] {
+  assertNoSymlinkPathComponents(file, {
+    label: 'Sidecar path',
+    ...(options.trustedRoot ? { trustedRoot: options.trustedRoot } : {}),
+  });
+  if (!existsSync(file)) return [];
+  const content = readFileSync(file, 'utf8');
+  if (content.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar log must not be empty: ${file}`);
+  }
+  const rawLines = content.split('\n');
+  if (rawLines.at(-1) === '') rawLines.pop();
+  if (rawLines.some((line) => line.length === 0)) {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar log contains a blank line: ${file}`);
+  }
+  const events: T[] = [];
+  const eventIds = new Set<string>();
+  let previousEventHash: string | null = null;
+  for (const [index, rawLine] of rawLines.entries()) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(rawLine);
+    } catch (error) {
+      throw new WorkflowError('STATE_CORRUPT', `Invalid sidecar JSONL: ${file}`, {
+        line: index + 1,
+        cause: error instanceof Error ? error.message : String(error),
+      });
+    }
+    const event = parsed as T;
+    validateSidecarEventShape(event, file, index + 1);
+    runSidecarEventValidator(event, options.validateEvent, {
+      file,
+      line: index + 1,
+      eventId: event.eventId,
+    });
+    if (eventIds.has(event.eventId)) {
+      throw new WorkflowError('STATE_CORRUPT', `Duplicate sidecar event id in ${file}`, {
+        eventId: event.eventId,
+        line: index + 1,
+      });
+    }
+    eventIds.add(event.eventId);
+    if (event.previousEventHash !== previousEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Broken sidecar event chain in ${file}`, {
+        line: index + 1,
+        expectedPreviousEventHash: previousEventHash,
+        actualPreviousEventHash: event.previousEventHash,
+      });
+    }
+    const expectedEventHash = computeSidecarEventHash(event);
+    if (event.eventHash !== expectedEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', `Sidecar event hash mismatch in ${file}`, {
+        line: index + 1,
+        eventId: event.eventId,
+        expectedEventHash,
+        actualEventHash: event.eventHash,
+      });
+    }
+    previousEventHash = event.eventHash;
+    events.push(event);
+  }
+  return events;
+}
+
+export function prepareSidecarAppend<T extends SidecarEventRecord>(
+  existingEvents: readonly T[],
+  input: SidecarAppendInput<T>,
+  options: SidecarReadOptions<T> = {},
+): PreparedSidecarAppend<T> {
+  const { previousEventHash: providedPreviousEventHash, eventHash: providedEventHash, ...payload } = input;
+  const nextPreviousEventHash = existingEvents.length > 0 ? existingEvents[existingEvents.length - 1]!.eventHash : null;
+  if (providedPreviousEventHash !== undefined && providedPreviousEventHash !== nextPreviousEventHash) {
+    throw new WorkflowError('STATE_CONFLICT', 'Sidecar append previousEventHash does not match the current chain.', {
+      expectedPreviousEventHash: nextPreviousEventHash,
+      actualPreviousEventHash: providedPreviousEventHash,
+    });
+  }
+  const event = {
+    ...payload,
+    previousEventHash: nextPreviousEventHash,
+  } as Omit<T, 'eventHash'>;
+  validateSidecarEventShape({ ...event, eventHash: computeSidecarEventHash(event) } as T, '<pending-sidecar>', 1);
+  const duplicate = existingEvents.find((candidate) => candidate.eventId === event.eventId);
+  if (duplicate) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Sidecar event id already exists: ${event.eventId}`);
+  }
+  const computedEventHash = computeSidecarEventHash(event);
+  if (providedEventHash !== undefined && providedEventHash !== computedEventHash) {
+    throw new WorkflowError('STATE_CONFLICT', 'Sidecar append eventHash does not match the canonical payload.', {
+      expectedEventHash: computedEventHash,
+      actualEventHash: providedEventHash,
+    });
+  }
+  const appendedEvent = { ...event, eventHash: computedEventHash } as T;
+  runSidecarEventValidator(appendedEvent, options.validateEvent, {
+    file: '<pending-sidecar>',
+    line: existingEvents.length + 1,
+    eventId: appendedEvent.eventId,
+  });
+  const content = renderSidecarEvents([...existingEvents, appendedEvent]);
+  return {
+    event: appendedEvent,
+    content,
+    contentHash: sha256Hex(content),
+  };
+}
+
+function canonicalizeJson(value: unknown): CanonicalJsonValue {
+  if (value === null) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Canonical JSON cannot represent non-finite numbers.');
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeJson(item));
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .filter((key) => record[key] !== undefined)
+        .map((key) => [key, canonicalizeJson(record[key])]),
+    );
+  }
+  throw new WorkflowError('INVALID_ARGUMENT', `Canonical JSON does not support value type: ${typeof value}`);
+}
+
+function validateSidecarEventShape(event: SidecarEventRecord, file: string, line: number): void {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar event must be an object: ${file}`, { line });
+  }
+  if (typeof event.eventId !== 'string' || !event.eventId.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar event is missing eventId: ${file}`, { line });
+  }
+  if (event.previousEventHash !== null) {
+    if (typeof event.previousEventHash !== 'string') {
+      throw new WorkflowError('STATE_CORRUPT', `Sidecar event previousEventHash must be null or string: ${file}`, {
+        line,
+        eventId: event.eventId,
+      });
+    }
+    assertHash64(event.previousEventHash, `Sidecar event previousEventHash at ${file}:${line}`);
+  }
+  if (typeof event.recordedAt !== 'string' || !event.recordedAt.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar event is missing recordedAt: ${file}`, {
+      line,
+      eventId: event.eventId,
+    });
+  }
+  if (typeof event.eventHash !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar event is missing eventHash: ${file}`, {
+      line,
+      eventId: event.eventId,
+    });
+  }
+  assertHash64(event.eventHash, `Sidecar event eventHash at ${file}:${line}`);
+}
+
+export function assertNoSymlinkPathComponents(
+  candidatePath: string,
+  options: { label?: string; requireLeaf?: boolean; trustedRoot?: string } = {},
+): void {
+  const label = options.label ?? 'Path';
+  const resolved = path.resolve(candidatePath);
+  if (options.trustedRoot) {
+    const resolvedTrustedRoot = path.resolve(options.trustedRoot);
+    if (resolved !== resolvedTrustedRoot && !resolved.startsWith(`${resolvedTrustedRoot}${path.sep}`)) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${label} is outside of the trusted root: ${candidatePath}`, {
+        trustedRoot: resolvedTrustedRoot,
+      });
+    }
+    if (!existsSync(resolvedTrustedRoot)) {
+      throw new WorkflowError('STATE_CORRUPT', `${label} trusted root does not exist: ${candidatePath}`, {
+        trustedRoot: resolvedTrustedRoot,
+      });
+    }
+    let current = resolvedTrustedRoot;
+    const relativeSegments = path.relative(resolvedTrustedRoot, resolved).split(path.sep).filter(Boolean);
+    for (const [index, segment] of relativeSegments.entries()) {
+      current = path.join(current, segment);
+      if (!existsSync(current)) {
+        if (index === relativeSegments.length - 1 && options.requireLeaf !== true) return;
+        return;
+      }
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must not traverse a symlink: ${candidatePath}`, {
+          symlinkPath: current,
+        });
+      }
+    }
+    return;
+  }
+  const root = path.parse(resolved).root;
+  let current = root;
+  const segments = resolved.slice(root.length).split(path.sep).filter(Boolean);
+  if (!existsSync(root)) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} root does not exist: ${candidatePath}`);
+  }
+  if (lstatSync(root).isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} root must not be a symlink: ${candidatePath}`);
+  }
+  for (const [index, segment] of segments.entries()) {
+    current = path.join(current, segment);
+    if (!existsSync(current)) {
+      if (index === segments.length - 1 && options.requireLeaf !== true) return;
+      return;
+    }
+    if (lstatSync(current).isSymbolicLink()) {
+      throw new WorkflowError('STATE_CORRUPT', `${label} must not traverse a symlink: ${candidatePath}`, {
+        symlinkPath: current,
+      });
+    }
+  }
+}
+
+function runSidecarEventValidator<T extends SidecarEventRecord>(
+  event: T,
+  validateEvent: SidecarEventValidator<T> | undefined,
+  context: SidecarEventValidationContext,
+): void {
+  if (!validateEvent) return;
+  try {
+    validateEvent(event, context);
+  } catch (error) {
+    if (error instanceof WorkflowError && error.code === 'STATE_CORRUPT') {
+      throw new WorkflowError(error.code, error.message, {
+        ...error.details,
+        file: context.file,
+        line: context.line,
+        eventId: context.eventId,
+      });
+    }
+    throw new WorkflowError('STATE_CORRUPT', `Sidecar event validation failed: ${context.file}`, {
+      line: context.line,
+      eventId: context.eventId,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+}