gyoshu 0.1.0

package/src/lib/artifact-security.ts

@@ -0,0 +1,159 @@
+/**
+ * Artifact Security Module
+ * 
+ * Provides TOCTOU-resistant file operations with symlink protection.
+ * 
+ * Security features:
+ * - O_NOFOLLOW: Prevents following symlinks on POSIX systems
+ * - Path validation: Rejects absolute paths, path traversal (../), symlinks
+ * - TOCTOU mitigation: Validates paths at open time, not just pre-check
+ * - Safe mkdir: Checks each path component with lstat before creation
+ */
+
+import * as fs from 'fs/promises';
+import { constants } from 'fs';
+import * as path from 'path';
+
+/**
+ * Validates that an artifact path is safe and within the artifact root.
+ * 
+ * @param artifactPath - Relative path to the artifact
+ * @param artifactRoot - Root directory for artifacts
+ * @returns Resolved absolute path if valid
+ * @throws Error if path is absolute, contains traversal, or escapes root
+ */
+export function validateArtifactPath(artifactPath: string, artifactRoot: string): string {
+  // Reject absolute paths
+  if (path.isAbsolute(artifactPath)) {
+    throw new Error(`Absolute paths not allowed: ${artifactPath}`);
+  }
+  
+  // Normalize and resolve
+  const normalized = path.normalize(artifactPath);
+  
+  // Reject path traversal - check segments, not string includes
+  const segments = normalized.split(path.sep);
+  if (segments.includes('..')) {
+    throw new Error(`Path traversal detected: ${artifactPath}`);
+  }
+  
+  const resolved = path.resolve(artifactRoot, normalized);
+  
+  // Must be under artifact root
+  if (!resolved.startsWith(path.resolve(artifactRoot) + path.sep)) {
+    throw new Error(`Path escaped artifact root: ${artifactPath}`);
+  }
+  
+  return resolved;
+}
+
+/**
+ * Creates a directory path safely without following symlinks.
+ * 
+ * Walks through each path component, checking with lstat to ensure
+ * no symlinks exist in the path that could lead to directory escape.
+ * 
+ * @param dirPath - Target directory path to create
+ * @param root - Root directory that must contain the path
+ * @throws Error if symlink or non-directory found in path
+ */
+export async function mkdirSafe(dirPath: string, root: string): Promise<void> {
+  const relative = path.relative(root, dirPath);
+  const parts = relative.split(path.sep).filter(Boolean);
+  let current = root;
+  
+  for (const part of parts) {
+    current = path.join(current, part);
+    
+    try {
+      const stat = await fs.lstat(current);  // lstat doesn't follow symlinks
+      if (stat.isSymbolicLink()) {
+        throw new Error(`Symlink in path: ${current}`);
+      }
+      if (!stat.isDirectory()) {
+        throw new Error(`Not a directory: ${current}`);
+      }
+    } catch (e: unknown) {
+      const error = e as NodeJS.ErrnoException;
+      if (error.code === 'ENOENT') {
+        await fs.mkdir(current);
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+/**
+ * Opens a file without following symlinks (POSIX O_NOFOLLOW).
+ * 
+ * Uses O_NOFOLLOW flag to prevent symlink following on POSIX systems.
+ * For write operations, also uses O_EXCL to ensure exclusive creation.
+ * 
+ * @param filePath - Path to the file to open
+ * @param flags - Open mode: 'r' for read, 'w' or 'wx' for exclusive write
+ * @returns FileHandle if successful
+ * @throws Error if path is a symlink or not a regular file
+ */
+export async function openNoFollow(filePath: string, flags: string): Promise<fs.FileHandle> {
+  // POSIX: O_NOFOLLOW prevents following symlinks
+  const numericFlags = flags.includes('w') 
+    ? constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW
+    : constants.O_RDONLY | constants.O_NOFOLLOW;
+  
+  const fd = await fs.open(filePath, numericFlags);
+  
+  // Verify it's a regular file
+  const stat = await fd.stat();
+  if (!stat.isFile()) {
+    await fd.close();
+    throw new Error(`Not a regular file: ${filePath}`);
+  }
+  
+  return fd;
+}
+
+/**
+ * Safely writes an artifact with full TOCTOU protection.
+ * 
+ * Combines all security measures:
+ * 1. Validates the path doesn't escape artifact root
+ * 2. Creates parent directories safely (no symlink following)
+ * 3. Opens file exclusively with O_NOFOLLOW
+ * 4. Re-validates via realpath after open (TOCTOU mitigation)
+ * 5. Writes data and syncs to disk
+ * 
+ * @param artifactRoot - Root directory for artifacts
+ * @param relativePath - Relative path within artifact root
+ * @param data - Data to write
+ * @returns Absolute path where file was written
+ * @throws Error if any security check fails
+ */
+export async function safeWriteArtifact(
+  artifactRoot: string,
+  relativePath: string,
+  data: Buffer
+): Promise<string> {
+  const targetPath = validateArtifactPath(relativePath, artifactRoot);
+  
+  // Create directories safely
+  await mkdirSafe(path.dirname(targetPath), artifactRoot);
+  
+  // Open without following symlinks, create exclusively
+  const fd = await openNoFollow(targetPath, 'wx');
+  
+  try {
+    // Re-validate via realpath after file is created
+    const realPath = await fs.realpath(targetPath);
+    if (!realPath.startsWith(path.resolve(artifactRoot) + path.sep)) {
+      throw new Error('TOCTOU attack detected: file escaped artifact root');
+    }
+    
+    await fd.write(data);
+    await fd.sync();
+  } finally {
+    await fd.close();
+  }
+  
+  return targetPath;
+}

package/src/lib/atomic-write.ts

@@ -0,0 +1,107 @@
+/**
+ * Atomic, durable file writes. Guarantees: same-dir temp (same filesystem),
+ * fsync before rename, directory fsync (best-effort), Windows PowerShell fallback.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+export async function durableAtomicWrite(targetPath: string, data: string): Promise<void> {
+  const dir = path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  const tempPath = path.join(dir, `.${base}.tmp.${crypto.randomUUID()}`);
+  
+  let success = false;
+  
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    
+    const fd = await fs.open(tempPath, 'w');
+    try {
+      await fd.write(data);
+      await fd.sync();
+    } finally {
+      await fd.close();
+    }
+    
+    if (targetPath.endsWith('.json')) {
+      JSON.parse(data);
+    }
+    
+    if (process.platform === 'win32') {
+      await atomicReplaceWindows(tempPath, targetPath);
+    } else {
+      await fs.rename(tempPath, targetPath);
+    }
+    
+    success = true;
+    
+    // Directory fsync - best-effort, some platforms don't support it
+    try {
+      const dirFd = await fs.open(dir, 'r');
+      try {
+        await dirFd.sync();
+      } finally {
+        await dirFd.close();
+      }
+    } catch (e) {
+      console.warn(`[atomic-write] Directory fsync failed for ${dir}: ${(e as Error).message}`);
+    }
+  } finally {
+    if (!success) {
+      await fs.unlink(tempPath).catch(() => {});
+    }
+  }
+}
+
+export async function atomicReplaceWindows(tempPath: string, targetPath: string): Promise<void> {
+  if (process.platform !== 'win32') {
+    await fs.rename(tempPath, targetPath);
+    return;
+  }
+  
+  try {
+    const escapedTemp = tempPath.replace(/'/g, "''");
+    const escapedTarget = targetPath.replace(/'/g, "''");
+    
+    await execAsync(
+      `Move-Item -Force -Path '${escapedTemp}' -Destination '${escapedTarget}'`,
+      { shell: 'powershell.exe' }
+    );
+  } catch (psError) {
+    try {
+      await fs.rename(tempPath, targetPath);
+    } catch (renameError) {
+      throw new Error(
+        `Windows atomic replace failed. ` +
+        `PowerShell: ${(psError as Error).message}. ` +
+        `Rename fallback: ${(renameError as Error).message}`
+      );
+    }
+  }
+}
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readFile<T = string>(
+  filePath: string, 
+  parseJson: boolean = false
+): Promise<T> {
+  const content = await fs.readFile(filePath, 'utf-8');
+  if (parseJson) {
+    return JSON.parse(content) as T;
+  }
+  return content as T;
+}

package/src/lib/cell-identity.ts

@@ -0,0 +1,176 @@
+/**
+ * Cell Identity Management for Jupyter Notebooks
+ *
+ * Provides deterministic cell ID generation and migration for nbformat 4.5 compatibility.
+ * Legacy notebooks (pre-4.5) lack cell IDs; this module backfills them deterministically
+ * to ensure reproducible cell identification across sessions.
+ *
+ * @module cell-identity
+ */
+
+import * as crypto from 'crypto';
+
+/**
+ * Represents a single cell in a Jupyter notebook.
+ * Supports code, markdown, and raw cell types as per nbformat spec.
+ */
+export interface NotebookCell {
+  /** Type of the cell */
+  cell_type: 'code' | 'markdown' | 'raw';
+
+  /** Cell ID (optional in nbformat < 4.5, required in 4.5+) */
+  id?: string;
+
+  /** Cell source content - can be string or array of strings (one per line) */
+  source: string | string[];
+
+  /** Cell metadata */
+  metadata?: Record<string, unknown>;
+
+  /** Execution count for code cells (null if not executed) */
+  execution_count?: number | null;
+
+  /** Cell outputs for code cells */
+  outputs?: unknown[];
+}
+
+/**
+ * Represents a complete Jupyter notebook structure.
+ */
+export interface Notebook {
+  /** Array of cells in the notebook */
+  cells: NotebookCell[];
+
+  /** Notebook-level metadata */
+  metadata: Record<string, unknown>;
+
+  /** Major format version (typically 4) */
+  nbformat: number;
+
+  /** Minor format version (4.5 required for cell IDs) */
+  nbformat_minor: number;
+}
+
+/**
+ * Result of notebook cell ID migration.
+ */
+export interface MigrationResult {
+  /** Number of cells that were assigned new IDs */
+  migrated: number;
+}
+
+/**
+ * Computes a canonical content hash for a notebook cell.
+ *
+ * The hash is computed from the normalized source content:
+ * 1. Join array sources into a single string
+ * 2. Trim trailing whitespace
+ * 3. Normalize line endings to LF (Unix-style)
+ * 4. Compute SHA-256 hash
+ *
+ * This ensures identical content produces identical hashes regardless of
+ * how the source was stored (string vs array) or the original line endings.
+ *
+ * @param cell - The notebook cell to hash
+ * @returns A prefixed hash string in format "sha256:{hex}"
+ *
+ * @example
+ * ```typescript
+ * const hash = canonicalCellHash({
+ *   cell_type: 'code',
+ *   source: 'print("hello")\n'
+ * });
+ * // Returns: "sha256:abc123..."
+ * ```
+ */
+export function canonicalCellHash(cell: NotebookCell): string {
+  const source = Array.isArray(cell.source) ? cell.source.join('') : cell.source;
+  const normalized = source.trimEnd().replace(/\r\n/g, '\n');
+  const hash = crypto.createHash('sha256').update(normalized, 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Ensures a cell has an ID, generating one deterministically if missing.
+ *
+ * For cells without an existing ID, a deterministic ID is generated based on:
+ * - The notebook file path (for uniqueness across notebooks)
+ * - The cell index (for uniqueness within the notebook)
+ * - The cell content hash (for detecting content changes)
+ *
+ * This combination ensures:
+ * - Same notebook + same position + same content = same ID
+ * - Different notebooks or positions get different IDs
+ * - Content changes result in different IDs (intentional for change detection)
+ *
+ * Generated IDs use format: "gyoshu-{8-char-hex}"
+ *
+ * @param cell - The notebook cell (modified in place if ID is added)
+ * @param index - Zero-based index of the cell in the notebook
+ * @param notebookPath - Path to the notebook file (used for uniqueness)
+ * @returns The cell's ID (existing or newly generated)
+ *
+ * @example
+ * ```typescript
+ * const cell = { cell_type: 'code', source: 'x = 1' };
+ * const id = ensureCellId(cell, 0, '/path/to/notebook.ipynb');
+ * // cell.id is now set, and id contains the same value
+ * ```
+ */
+export function ensureCellId(cell: NotebookCell, index: number, notebookPath: string): string {
+  if (cell.id) {
+    return cell.id;
+  }
+
+  const contentHash = canonicalCellHash(cell);
+  const combined = `${notebookPath}:${index}:${contentHash}`;
+  const hash = crypto.createHash('sha256').update(combined).digest('hex').slice(0, 8);
+
+  const newId = `gyoshu-${hash}`;
+  cell.id = newId;
+  return newId;
+}
+
+/**
+ * Migrates all cells in a notebook to have IDs, updating format version if needed.
+ *
+ * This function:
+ * 1. Iterates through all cells in the notebook
+ * 2. Assigns deterministic IDs to cells that lack them
+ * 3. Updates the notebook format to nbformat 4.5 if any cells were migrated
+ *
+ * The notebook object is modified in place.
+ *
+ * @param notebook - The notebook to migrate (modified in place)
+ * @param notebookPath - Path to the notebook file (used for ID generation)
+ * @returns Object containing the count of migrated cells
+ *
+ * @example
+ * ```typescript
+ * const notebook = JSON.parse(fs.readFileSync('notebook.ipynb', 'utf8'));
+ * const result = migrateNotebookCellIds(notebook, 'notebook.ipynb');
+ * console.log(`Migrated ${result.migrated} cells`);
+ *
+ * if (result.migrated > 0) {
+ *   fs.writeFileSync('notebook.ipynb', JSON.stringify(notebook, null, 2));
+ * }
+ * ```
+ */
+export function migrateNotebookCellIds(notebook: Notebook, notebookPath: string): MigrationResult {
+  let migrated = 0;
+
+  for (let i = 0; i < notebook.cells.length; i++) {
+    const cell = notebook.cells[i];
+    if (!cell.id) {
+      ensureCellId(cell, i, notebookPath);
+      migrated++;
+    }
+  }
+
+  if (migrated > 0) {
+    notebook.nbformat = 4;
+    notebook.nbformat_minor = 5;
+  }
+
+  return { migrated };
+}