steroids-api 0.2.7

package/src/utils/sqlite.ts

@@ -0,0 +1,36 @@
+import Database from 'better-sqlite3';
+
+export type SqliteOpenOptions = {
+  timeoutMs?: number;
+};
+
+/**
+ * Open a connection suitable for reading a WAL-enabled database that may be
+ * concurrently written by another process.
+ *
+ * IMPORTANT:
+ * - In WAL mode, SQLite readers participate in coordination via the `-shm` file.
+ * - Opening the main database as SQLITE_OPEN_READONLY can break that coordination
+ *   and lead to transient IO errors (e.g. SHORT_READ) if the writer checkpoints/truncates.
+ *
+ * So we open read-write, then enforce read-only at the SQL layer via `PRAGMA query_only=ON`.
+ */
+export function openSqliteForRead(dbPath: string, opts: SqliteOpenOptions = {}): Database.Database {
+  const timeoutMs = opts.timeoutMs ?? 5000;
+
+  const db = new Database(dbPath, {
+    // Must exist; callers use existence checks only for UX, not correctness.
+    fileMustExist: true,
+    timeout: timeoutMs,
+  });
+
+  // Ensure the connection will wait for locks instead of failing immediately.
+  // (The `timeout` option also sets this, but being explicit makes intent clear.)
+  db.pragma(`busy_timeout = ${timeoutMs}`);
+
+  // Enforce read-only at the SQL layer while still allowing WAL shared-memory coordination.
+  db.pragma('query_only = ON');
+
+  return db;
+}
+

package/src/utils/storage-cache.ts

@@ -0,0 +1,107 @@
+/**
+ * In-memory cache for project storage computations.
+ * Keyed by project path with configurable TTL.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import {
+  getStorageBreakdown,
+  formatBytes,
+  type StorageBreakdown,
+} from '../../../dist/cleanup/directory-size.js';
+import { getRegisteredProject } from '../../../dist/runners/projects.js';
+
+interface CacheEntry<T> {
+  data: T;
+  expiresAt: number;
+}
+
+const detailCache = new Map<string, CacheEntry<StorageBreakdown>>();
+const listCache = new Map<string, CacheEntry<ListStorageInfo>>();
+
+const DETAIL_TTL_MS = 60_000;    // 60 seconds
+const LIST_TTL_MS = 300_000;     // 5 minutes
+
+export interface ListStorageInfo {
+  storage_bytes: number;
+  storage_human: string;
+  storage_warning: 'orange' | 'red' | null;
+}
+
+/**
+ * Validate that a query path is a registered project.
+ * Uses fs.promises.realpath() to resolve symlinks, then checks the global DB.
+ */
+export async function validateProjectPath(
+  path: string | undefined,
+): Promise<{ valid: true; realPath: string } | { valid: false; error: string; status: number }> {
+  if (!path || typeof path !== 'string' || path.trim().length === 0) {
+    return { valid: false, error: 'Query parameter "path" is required', status: 400 };
+  }
+  let realPath: string;
+  try {
+    realPath = await fs.realpath(path);
+  } catch {
+    return { valid: false, error: 'Path does not exist or is inaccessible', status: 404 };
+  }
+  const project = getRegisteredProject(realPath);
+  if (!project) {
+    return { valid: false, error: 'Path is not a registered project', status: 403 };
+  }
+  return { valid: true, realPath };
+}
+
+/**
+ * Get detailed storage breakdown with 60s cache.
+ */
+export async function getCachedStorageBreakdown(
+  projectPath: string, 
+  retentionDays: number = 7,
+  backupRetentionDays: number = 30
+): Promise<StorageBreakdown> {
+  const entry = detailCache.get(projectPath);
+  if (entry && Date.now() < entry.expiresAt) return entry.data;
+
+  const steroidsDir = join(projectPath, '.steroids');
+  const data = await getStorageBreakdown(steroidsDir, retentionDays, backupRetentionDays);
+  detailCache.set(projectPath, { data, expiresAt: Date.now() + DETAIL_TTL_MS });
+  return data;
+}
+
+/**
+ * Get lightweight storage info for project list with 5-minute cache.
+ * Returns null if not yet computed (triggers background computation).
+ */
+export function getCachedListStorage(projectPath: string): ListStorageInfo | null {
+  const entry = listCache.get(projectPath);
+  if (entry && Date.now() < entry.expiresAt) return entry.data;
+
+  // Trigger background computation (don't block the list response)
+  computeListStorageInBackground(projectPath);
+  return entry?.data ?? null;  // Return stale data if available, null otherwise
+}
+
+function computeListStorageInBackground(projectPath: string): void {
+  const steroidsDir = join(projectPath, '.steroids');
+  getStorageBreakdown(steroidsDir)
+    .then((breakdown) => {
+      listCache.set(projectPath, {
+        data: {
+          storage_bytes: breakdown.total_bytes,
+          storage_human: breakdown.total_human,
+          storage_warning: breakdown.threshold_warning,
+        },
+        expiresAt: Date.now() + LIST_TTL_MS,
+      });
+    })
+    .catch(() => { /* tolerate background failures */ });
+}
+
+/**
+ * Bust all caches for a given project path.
+ * Called after POST /clear-logs to ensure fresh data.
+ */
+export function bustStorageCache(projectPath: string): void {
+  detailCache.delete(projectPath);
+  listCache.delete(projectPath);
+}

package/src/utils/validation.ts

@@ -0,0 +1,61 @@
+/**
+ * Path validation utilities for API security
+ */
+
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Validate that a path is safe and points to a valid Steroids project
+ *
+ * @param path - Path to validate
+ * @returns True if path is valid and safe
+ */
+export function isValidProjectPath(path: string): boolean {
+  try {
+    const realPath = realpathSync(path);
+
+    // Must contain .steroids directory with database
+    const steroidsDb = join(realPath, '.steroids', 'steroids.db');
+    if (!existsSync(steroidsDb)) {
+      return false;
+    }
+
+    // Must not be system directories
+    const forbidden = ['/etc', '/var', '/usr', '/bin', '/sbin'];
+    if (
+      forbidden.some((f) => realPath.startsWith(f)) || 
+      (realPath.startsWith('/System') && !realPath.startsWith('/System/Volumes/Data'))
+    ) {
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate request body for path-based operations
+ *
+ * @param body - Request body
+ * @returns Validation result with error message if invalid
+ */
+export function validatePathRequest(body: unknown): { valid: boolean; error?: string; path?: string } {
+  if (!body || typeof body !== 'object') {
+    return { valid: false, error: 'Request body must be an object' };
+  }
+
+  const { path } = body as { path?: unknown };
+
+  if (!path || typeof path !== 'string') {
+    return { valid: false, error: 'Request body must contain a "path" string field' };
+  }
+
+  if (path.trim().length === 0) {
+    return { valid: false, error: 'Path cannot be empty' };
+  }
+
+  return { valid: true, path };
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}