@roj-ai/sdk 0.1.35 → 0.2.1

package/src/core/file-store/file-store.ts

@@ -5,6 +5,11 @@
  * validation, agent-visible path mapping). Replaces the separate path-resolver
  * functions for FileStore consumers.
  *
+ * Every operation resolves the path lexically and then checks that its real
+ * target is still inside the area the store may touch — session and workspace
+ * together, or whatever root a `scoped()` sub-store was carved out of. Links
+ * are not banned: one whose target lands back inside stays usable.
+ *
  * Three scopes:
  * - 'full': accepts agent-visible paths (/home/user/session/... or real paths)
  * - 'session': paths relative to sessionDir
@@ -12,8 +17,9 @@
  */
 
 import { dirname, join, normalize, resolve } from 'node:path'
+import { containmentOf } from '~/core/file-store/containment.js'
 import type { FileEntry, FileStore } from '~/core/file-store/types.js'
-import type { FileSystem } from '~/platform/fs.js'
+import type { FileSystem, WalkEntry } from '~/platform/fs.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { Result } from '~/lib/utils/result.js'
 
@@ -23,6 +29,19 @@ const VIRTUAL_WORKSPACE = '/home/user/workspace'
 
 type FileStoreScope = 'full' | 'session' | 'workspace'
 
+/** A lexically resolved path plus the roots its real target must stay inside. */
+interface ResolvedPath {
+	absolute: string
+	roots: readonly string[]
+}
+
+/**
+ * What the operation does with the final link, which decides what an
+ * unresolvable one means: `follow` leaves it to the operation, `create` refuses
+ * it because writing would create the target, `entry` checks the parent instead.
+ */
+type ContainmentMode = 'follow' | 'create' | 'entry'
+
 export class SessionFileStore implements FileStore {
 	constructor(
 		private readonly sessionDir: string,
@@ -30,25 +49,31 @@ export class SessionFileStore implements FileStore {
 		private readonly sandboxed: boolean,
 		private readonly fs: FileSystem,
 		private readonly scope: FileStoreScope = 'full',
+		/** Set by `scoped()` so a sub-store cannot escape the roots it was carved out of. */
+		private readonly containmentRoots?: readonly string[],
 	) {}
 
 	/** Create a session-scoped FileStore (relative paths → sessionDir) */
 	get session(): SessionFileStore {
-		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'session')
+		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'session', this.containmentRoots)
 	}
 
 	/** Create a workspace-scoped FileStore (relative paths → workspaceDir), or undefined if no workspace */
 	get workspace(): SessionFileStore | undefined {
 		if (!this.workspaceDir) return undefined
-		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'workspace')
+		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'workspace', this.containmentRoots)
 	}
 
 	async write(path: string, content: string | Buffer): Promise<Result<{ path: string }, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'create')
 		if (!resolved.ok) return resolved
 
-		await this.fs.mkdir(dirname(resolved.value), { recursive: true })
-		await this.fs.writeFile(resolved.value, content)
+		try {
+			await this.fs.mkdir(dirname(resolved.value), { recursive: true })
+			await this.fs.writeFile(resolved.value, content)
+		} catch {
+			return Err(`Failed to write: ${path}`)
+		}
 
 		return Ok({ path: this.toAgentPath(resolved.value) })
 	}
@@ -56,7 +81,7 @@ export class SessionFileStore implements FileStore {
 	async read(path: string): Promise<Result<string, string>>
 	async read(path: string, opts: { type: 'buffer' }): Promise<Result<Buffer, string>>
 	async read(path: string, opts?: { type: 'buffer' }): Promise<Result<string | Buffer, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		try {
@@ -70,21 +95,22 @@ export class SessionFileStore implements FileStore {
 	}
 
 	async exists(path: string): Promise<Result<boolean, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		return Ok(await this.fs.exists(resolved.value))
 	}
 
 	async stat(path: string): Promise<Result<FileEntry, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		try {
+			// `stat` follows links on purpose — a link to a file inside the root is a file here.
 			const s = await this.fs.stat(resolved.value)
 			return Ok({
 				size: s.size,
-				type: s.isFile() ? 'file' : s.isDirectory() ? 'directory' : s.isSymbolicLink() ? 'symlink' : 'other',
+				type: s.isFile() ? 'file' : s.isDirectory() ? 'directory' : 'other',
 				name: resolved.value.split('/').pop() || '',
 			})
 		} catch {
@@ -96,15 +122,24 @@ export class SessionFileStore implements FileStore {
 		path: string,
 		options?: { maxDepth?: number; gitIgnore?: boolean },
 	): Promise<Result<FileEntry[], string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		const maxDepth = options?.maxDepth ?? 1
 		if (maxDepth < 1) return Ok([])
 
 		try {
+			// A readdir plus a stat per file is one question asked in pieces. Where
+			// the platform takes it whole, ask it whole.
+			if (this.fs.walk) {
+				const base = resolved.value
+				const found = await this.fs.walk(base, { depth: maxDepth })
+				return Ok(found.map((entry) => toFileEntry(entry, base)))
+			}
+
 			const entries: FileEntry[] = []
-			await this.walkInto(resolved.value, '', maxDepth, entries)
+			const readAll = (): Promise<void> => this.walkInto(resolved.value, '', maxDepth, entries)
+			await (this.fs.scopeReads ? this.fs.scopeReads(readAll) : readAll())
 			return Ok(entries)
 		} catch {
 			return Err(`Directory not found: ${path}`)
@@ -142,7 +177,7 @@ export class SessionFileStore implements FileStore {
 	}
 
 	async remove(path: string): Promise<Result<void, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'entry')
 		if (!resolved.ok) return resolved
 
 		try {
@@ -166,24 +201,60 @@ export class SessionFileStore implements FileStore {
 		}
 	}
 
+	/** Lexical resolution only — despite the name it never follows a symlink. See FileStore.realPath. */
 	realPath(path: string): Result<string, string> {
-		return this.resolvePath(path)
+		const resolved = this.resolveScoped(path)
+		return resolved.ok ? Ok(resolved.value.absolute) : resolved
 	}
 
+	/** See FileStore.containedPath. */
+	containedPath(path: string): Promise<Result<string, string>> {
+		return this.resolveContained(path, 'create')
+	}
+
+	/** Throws on a path it cannot resolve — never hand it unvalidated request data; use `realPath` there. */
 	scoped(basePath: string): SessionFileStore {
 		// Resolve basePath relative to current scope
-		const resolved = this.resolvePath(basePath)
+		const resolved = this.resolveScoped(basePath)
 		if (!resolved.ok) {
 			throw new Error(`Cannot scope to invalid path: ${basePath}`)
 		}
-		return new SessionFileStore(resolved.value, undefined, false, this.fs, 'session')
+		return new SessionFileStore(resolved.value.absolute, undefined, false, this.fs, 'session', resolved.value.roots)
 	}
 
 	// ============================================================================
 	// Path resolution
 	// ============================================================================
 
-	private resolvePath(path: string): Result<string, string> {
+	/**
+	 * Lexical resolution, plus a check that the real target has not left the roots.
+	 * `mode` says what the operation does with the final link — see ContainmentMode.
+	 */
+	private async resolveContained(path: string, mode: ContainmentMode): Promise<Result<string, string>> {
+		const resolved = this.resolveScoped(path)
+		if (!resolved.ok) return resolved
+
+		const { absolute, roots } = resolved.value
+		const subject = mode === 'entry' ? dirname(absolute) : absolute
+		switch (await containmentOf(this.fs, roots, subject)) {
+			case 'outside':
+				return Err(`Path '${path}' resolves outside allowed directories`)
+			case 'unresolvable':
+				return mode === 'create' ? Err(`Path '${path}' cannot be resolved`) : Ok(absolute)
+			case 'inside':
+				return Ok(absolute)
+		}
+	}
+
+	/** The area this store may touch — both roots where a workspace is configured. */
+	private allowedRoots(): readonly string[] {
+		if (this.containmentRoots) return this.containmentRoots
+		const roots = [resolve(this.sessionDir)]
+		if (this.workspaceDir) roots.push(resolve(this.workspaceDir))
+		return roots
+	}
+
+	private resolveScoped(path: string): Result<ResolvedPath, string> {
 		switch (this.scope) {
 			case 'full':
 				return this.resolveAgentPath(path)
@@ -196,7 +267,7 @@ export class SessionFileStore implements FileStore {
 	}
 
 	/** Resolve a relative path within a root directory */
-	private resolveRelativePath(path: string, rootDir: string): Result<string, string> {
+	private resolveRelativePath(path: string, rootDir: string): Result<ResolvedPath, string> {
 		const normalized = normalize(path)
 		if (normalized.startsWith('..') || normalized.startsWith('/')) {
 			return Err(`Path traversal not allowed: ${path}`)
@@ -205,18 +276,18 @@ export class SessionFileStore implements FileStore {
 		if (!absolute.startsWith(rootDir)) {
 			return Err(`Path traversal not allowed: ${path}`)
 		}
-		return Ok(absolute)
+		return Ok({ absolute, roots: this.allowedRoots() })
 	}
 
 	/** Resolve an agent-visible path to real filesystem path (handles sandboxed virtual paths) */
-	private resolveAgentPath(agentPath: string): Result<string, string> {
+	private resolveAgentPath(agentPath: string): Result<ResolvedPath, string> {
 		if (this.sandboxed) {
 			return this.resolveSandboxedPath(agentPath)
 		}
 		return this.resolveNonSandboxedPath(agentPath)
 	}
 
-	private resolveSandboxedPath(agentPath: string): Result<string, string> {
+	private resolveSandboxedPath(agentPath: string): Result<ResolvedPath, string> {
 		if (agentPath.startsWith(VIRTUAL_SESSION + '/') || agentPath === VIRTUAL_SESSION) {
 			const relative = agentPath.slice(VIRTUAL_SESSION.length)
 			const absolutePath = resolve(this.sessionDir, relative.slice(1) || '.')
@@ -239,7 +310,7 @@ export class SessionFileStore implements FileStore {
 		return Err(`Path must start with ${validPrefixes}. Got: '${agentPath}'`)
 	}
 
-	private resolveNonSandboxedPath(agentPath: string): Result<string, string> {
+	private resolveNonSandboxedPath(agentPath: string): Result<ResolvedPath, string> {
 		const absolutePath = resolve(agentPath)
 		const normalizedSession = resolve(this.sessionDir)
 		const normalizedWorkspace = this.workspaceDir ? resolve(this.workspaceDir) : null
@@ -252,10 +323,10 @@ export class SessionFileStore implements FileStore {
 			return Err(`Path '${agentPath}' is outside allowed directories`)
 		}
 
-		return Ok(absolutePath)
+		return Ok({ absolute: absolutePath, roots: this.allowedRoots() })
 	}
 
-	private validateWithinRoot(absolutePath: string, rootDir: string, originalPath: string): Result<string, string> {
+	private validateWithinRoot(absolutePath: string, rootDir: string, originalPath: string): Result<ResolvedPath, string> {
 		const normalizedRoot = resolve(rootDir)
 		const isWithin = absolutePath === normalizedRoot || absolutePath.startsWith(normalizedRoot + '/')
 
@@ -263,7 +334,7 @@ export class SessionFileStore implements FileStore {
 			return Err(`Path '${originalPath}' resolves outside allowed directories`)
 		}
 
-		return Ok(absolutePath)
+		return Ok({ absolute: absolutePath, roots: this.allowedRoots() })
 	}
 
 	// ============================================================================
@@ -293,3 +364,13 @@ export class SessionFileStore implements FileStore {
 		return realPath
 	}
 }
+
+/** A walked entry as the store reports it: name relative to the listed directory. */
+function toFileEntry(entry: WalkEntry, baseDir: string): FileEntry {
+	const prefixLength = baseDir.endsWith('/') ? baseDir.length : baseDir.length + 1
+	return {
+		name: entry.path.slice(prefixLength),
+		type: entry.type,
+		size: entry.type === 'file' ? entry.size : undefined,
+	}
+}

package/src/core/file-store/types.ts

@@ -39,9 +39,22 @@ export interface FileStore {
 	/** Remove a file. */
 	remove(path: string): Promise<Result<void, string>>
 
-	/** Resolve an agent-visible path to real filesystem path. */
+	/**
+	 * Resolve an agent-visible path to a real filesystem path, lexically.
+	 *
+	 * Does not follow symlinks, so it cannot decide containment on its own. Use
+	 * it only where the path is never handed to the filesystem — everything that
+	 * goes on to read, write or spawn wants `containedPath` instead.
+	 */
 	realPath(path: string): Result<string, string>
 
+	/**
+	 * Resolve to a real filesystem path, refusing one whose real target leaves
+	 * the store's roots. What a caller that reaches the filesystem itself, rather
+	 * than through this store, should ask for.
+	 */
+	containedPath(path: string): Promise<Result<string, string>>
+
 	/** Get the agent-visible root paths (virtual when sandboxed, real otherwise) */
 	getRoots(): { session: string; workspace?: string }
 

package/src/core/image/image-processor.ts

@@ -80,7 +80,9 @@ export class DefaultImageProcessor implements ImageProcessor {
 			return { type: 'text', text: `[Image unavailable: ${path} - unsupported format]` }
 		}
 
-		const resolved = fileStore.realPath(path)
+		// Not `realPath`: the URL comes back from conversation history, and what it
+		// names may have become a link out of the store since it was first read.
+		const resolved = await fileStore.containedPath(path)
 		if (!resolved.ok) {
 			return { type: 'text', text: `[Image unavailable: ${path} - ${resolved.error}]` }
 		}

package/src/core/image/types.ts

@@ -5,6 +5,8 @@ export interface ImageResizeOptions {
 	maxFileSizeBytes?: number
 	/** Override the resizer's default max dimension (long side, px). */
 	maxDimension?: number
+	/** Cancels external image-processing commands. */
+	signal?: AbortSignal
 }
 
 export interface ImageResizer {

package/src/core/image/vips-resizer.ts

@@ -25,31 +25,59 @@ export class VipsImageResizer implements ImageResizer {
 
 	async resize(filePath: string, mimeType: string, options?: ImageResizeOptions): Promise<ImageResizeResult> {
 		const effectiveMaxDimension = options?.maxDimension ?? this.maxDimension
+		const signal = options?.signal
+		let ownedTempFile: string | undefined
 		try {
+			signal?.throwIfAborted()
 			// Step 1: Dimension resize if needed
-			const result = await this.dimensionResize(filePath, mimeType, effectiveMaxDimension)
+			const result = await this.dimensionResize(filePath, mimeType, effectiveMaxDimension, signal)
+			ownedTempFile = result.tempFile
+			signal?.throwIfAborted()
 
 			// Step 2: If no size constraint, done
-			if (!options?.maxFileSizeBytes) return result
+			if (!options?.maxFileSizeBytes) {
+				signal?.throwIfAborted()
+				return result
+			}
 
 			// Step 3: Check if result fits
 			const fileSize = (await this.fs.stat(result.path)).size
-			if (fileSize <= options.maxFileSizeBytes) return result
+			signal?.throwIfAborted()
+			if (fileSize <= options.maxFileSizeBytes) {
+				signal?.throwIfAborted()
+				return result
+			}
 
 			// Step 4: Compress to fit — clean up dimension resize temp first
 			if (result.tempFile) {
 				await this.fs.unlink(result.tempFile).catch(() => {})
+				ownedTempFile = undefined
 			}
 
-			return await this.compressToFit(filePath, options.maxFileSizeBytes, effectiveMaxDimension)
+			signal?.throwIfAborted()
+			const compressed = await this.compressToFit(filePath, options.maxFileSizeBytes, effectiveMaxDimension, signal)
+			ownedTempFile = compressed.tempFile
+			signal?.throwIfAborted()
+			return compressed
 		} catch (e) {
+			if (ownedTempFile) {
+				await this.fs.unlink(ownedTempFile).catch(() => {})
+			}
+			if (signal?.aborted) signal.throwIfAborted()
 			console.warn('[image-resize] failed, using original image:', e instanceof Error ? e.message : e)
 			return { path: filePath, mimeType }
 		}
 	}
 
-	private async getImageDimensions(filePath: string): Promise<{ width: number; height: number } | null> {
-		const { stdout } = await this.process.execFile('vipsheader', ['-f', 'width', '-f', 'height', filePath], { timeout: 30_000 })
+	private async getImageDimensions(
+		filePath: string,
+		signal?: AbortSignal,
+	): Promise<{ width: number; height: number } | null> {
+		const { stdout } = await this.process.execFile('vipsheader', ['-f', 'width', '-f', 'height', filePath], {
+			timeout: 30_000,
+			signal,
+		})
+		signal?.throwIfAborted()
 		const lines = stdout.trim().split('\n')
 		if (lines.length < 2) return null
 		const width = parseInt(lines[0], 10)
@@ -58,12 +86,19 @@ export class VipsImageResizer implements ImageResizer {
 		return { width, height }
 	}
 
-	private async dimensionResize(filePath: string, mimeType: string, maxDimension: number): Promise<ImageResizeResult> {
-		const dims = await this.getImageDimensions(filePath)
+	private async dimensionResize(
+		filePath: string,
+		mimeType: string,
+		maxDimension: number,
+		signal?: AbortSignal,
+	): Promise<ImageResizeResult> {
+		const dims = await this.getImageDimensions(filePath, signal)
+		signal?.throwIfAborted()
 		const needsResize = dims !== null && (dims.width > maxDimension || dims.height > maxDimension)
 
 		// JPEGs within dimension limits pass through unchanged
 		if (mimeType === 'image/jpeg' && !needsResize) {
+			signal?.throwIfAborted()
 			return { path: filePath, mimeType }
 		}
 
@@ -71,17 +106,27 @@ export class VipsImageResizer implements ImageResizer {
 		const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
 		const outputPath = join(this.tmpDir, `roj-resize-${id}.jpg`)
 
-		await this.process.execFile('vipsthumbnail', [
-			filePath,
-			'--size',
-			`${maxDimension}x${maxDimension}`,
-			'-o',
-			outputPath,
-		], { timeout: 30_000 })
+		try {
+			await this.process.execFile(
+				'vipsthumbnail',
+				[filePath, '--size', `${maxDimension}x${maxDimension}`, '-o', outputPath],
+				{ timeout: 30_000, signal },
+			)
+			signal?.throwIfAborted()
+		} catch (error) {
+			await this.fs.unlink(outputPath).catch(() => {})
+			throw error
+		}
+		signal?.throwIfAborted()
 		return { path: outputPath, mimeType: 'image/jpeg', tempFile: outputPath }
 	}
 
-	private async compressToFit(filePath: string, maxFileSizeBytes: number, maxDimension: number): Promise<ImageResizeResult> {
+	private async compressToFit(
+		filePath: string,
+		maxFileSizeBytes: number,
+		maxDimension: number,
+		signal?: AbortSignal,
+	): Promise<ImageResizeResult> {
 		const halfDim = Math.floor(maxDimension / 2)
 		const attempts = [
 			{ dimension: maxDimension, quality: 85 },
@@ -95,31 +140,51 @@ export class VipsImageResizer implements ImageResizer {
 
 		let lastResult: ImageResizeResult | undefined
 
-		for (const { dimension, quality } of attempts) {
-			const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
-			const outputPath = join(this.tmpDir, `roj-compress-${id}.jpg`)
-
-			await this.process.execFile('vipsthumbnail', [
-				filePath,
-				'--size',
-				`${dimension}x${dimension}`,
-				'-o',
-				`${outputPath}[Q=${quality}]`,
-			], { timeout: 30_000 })
+		try {
+			for (const { dimension, quality } of attempts) {
+				signal?.throwIfAborted()
+				const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+				const outputPath = join(this.tmpDir, `roj-compress-${id}.jpg`)
+
+				try {
+					await this.process.execFile(
+						'vipsthumbnail',
+						[filePath, '--size', `${dimension}x${dimension}`, '-o', `${outputPath}[Q=${quality}]`],
+						{ timeout: 30_000, signal },
+					)
+					signal?.throwIfAborted()
+
+					const outputSize = (await this.fs.stat(outputPath)).size
+					signal?.throwIfAborted()
+					if (lastResult?.tempFile) {
+						await this.fs.unlink(lastResult.tempFile).catch(() => {})
+					}
+					signal?.throwIfAborted()
+
+					lastResult = {
+						path: outputPath,
+						mimeType: 'image/jpeg',
+						tempFile: outputPath,
+					}
+					if (outputSize <= maxFileSizeBytes) {
+						signal?.throwIfAborted()
+						return lastResult
+					}
+				} catch (error) {
+					await this.fs.unlink(outputPath).catch(() => {})
+					throw error
+				}
+			}
 
-			// Clean up previous attempt
+			// Return best effort (most compressed) — caller decides what to do
+			if (!lastResult) throw new Error('Image compression produced no result')
+			signal?.throwIfAborted()
+			return lastResult
+		} catch (error) {
 			if (lastResult?.tempFile) {
 				await this.fs.unlink(lastResult.tempFile).catch(() => {})
 			}
-
-			lastResult = { path: outputPath, mimeType: 'image/jpeg', tempFile: outputPath }
-
-			if ((await this.fs.stat(outputPath)).size <= maxFileSizeBytes) {
-				return lastResult
-			}
+			throw error
 		}
-
-		// Return best effort (most compressed) — caller decides what to do
-		return lastResult!
 	}
 }