@openfairygui/backend 0.3.0 → 0.3.1

package/src/node.ts

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import {
 	BackendRuntime,
 	type BackendFileStat,
@@ -9,13 +11,183 @@ import {
 	type BackendSessionLock,
 } from './runtime.js';
 
+const PROCESS_START_TIME = Math.trunc(Date.now() - process.uptime() * 1000);
+
+interface NodeLockMetadata {
+	schemaVersion: 1;
+	pid: number;
+	processStartTime: number;
+	hostname: string;
+	token: string;
+}
+
+function parseLockMetadata(content: string): NodeLockMetadata | null {
+	try {
+		const value = JSON.parse(content) as Partial<NodeLockMetadata>;
+		if (
+			value.schemaVersion !== 1
+			|| !Number.isSafeInteger(value.pid)
+			|| !Number.isFinite(value.processStartTime)
+			|| typeof value.hostname !== 'string'
+			|| typeof value.token !== 'string'
+		) return null;
+		return value as NodeLockMetadata;
+	} catch {
+		return null;
+	}
+}
+
+function isProcessAlive(metadata: NodeLockMetadata): boolean {
+	if (metadata.hostname !== os.hostname()) return true;
+	if (metadata.pid === process.pid) return Math.abs(metadata.processStartTime - PROCESS_START_TIME) < 1000;
+	try {
+		process.kill(metadata.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+	}
+}
+
+async function recoverStaleLock(filePath: string): Promise<boolean> {
+	let before: string;
+	try {
+		before = await fs.readFile(filePath, 'utf-8');
+	} catch {
+		return false;
+	}
+	const metadata = parseLockMetadata(before);
+	if (!metadata || isProcessAlive(metadata)) return false;
+	const current = parseLockMetadata(await fs.readFile(filePath, 'utf-8').catch(() => ''));
+	if (!current || current.token !== metadata.token) return false;
+	await fs.unlink(filePath);
+	return true;
+}
+
+async function resolvePathThroughExistingAncestor(filePath: string): Promise<string> {
+	const missing: string[] = [];
+	let candidate = path.resolve(filePath);
+	for (;;) {
+		try {
+			const resolved = await fs.realpath(candidate);
+			return path.join(resolved, ...missing);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error;
+			const parent = path.dirname(candidate);
+			if (parent === candidate) return path.resolve(filePath);
+			missing.unshift(path.basename(candidate));
+			candidate = parent;
+		}
+	}
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+	return fs.stat(filePath).then(
+		() => true,
+		(error: NodeJS.ErrnoException) => {
+			if (error.code === 'ENOENT') return false;
+			throw error;
+		},
+	);
+}
+
+async function assertNoSymlinks(dirPath: string): Promise<void> {
+	for (const entry of await fs.readdir(dirPath, { withFileTypes: true })) {
+		const entryPath = path.join(dirPath, entry.name);
+		if (entry.isSymbolicLink()) throw new Error(`Symbolic links are not supported in project directories: ${entryPath}`);
+		if (entry.isDirectory()) await assertNoSymlinks(entryPath);
+	}
+}
+
+function createStagedNodeFileSystem(projectRoot: string, stagingRoot: string): BackendFileSystem {
+	const { runProjectWriteTransaction: _, ...base } = createNodeBackendFileSystem();
+	const translate = (filePath: string): string => {
+		const relative = path.relative(projectRoot, path.resolve(filePath));
+		if (relative.startsWith('..') || path.isAbsolute(relative)) {
+			const error = new Error(`Project path escapes the staged root: ${filePath}`) as Error & { code: string };
+			error.code = 'EACCES';
+			throw error;
+		}
+		return path.join(stagingRoot, relative);
+	};
+	return {
+		...base,
+		stat: (filePath) => fs.stat(translate(filePath)),
+		async readdir(dirPath) {
+			const entries = await fs.readdir(translate(dirPath), { withFileTypes: true });
+			const symlink = entries.find((entry) => entry.isSymbolicLink());
+			if (symlink) throw new Error(`Symbolic links are not supported in project directories: ${path.join(dirPath, symlink.name)}`);
+			return entries.map((entry) => entry.name);
+		},
+		readFile: (filePath) => fs.readFile(translate(filePath), 'utf-8'),
+		async readFileRaw(filePath) {
+			const buffer = await fs.readFile(translate(filePath));
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		writeFile: (filePath, content) => fs.writeFile(translate(filePath), content, 'utf-8'),
+		writeFileRaw: (filePath, data) => fs.writeFile(translate(filePath), data),
+		async mkdir(dirPath, options) {
+			await fs.mkdir(translate(dirPath), { recursive: options?.recursive ?? false });
+		},
+		resolvePath: (filePath) => resolvePathThroughExistingAncestor(translate(filePath)),
+		unlink: (filePath) => fs.unlink(translate(filePath)),
+		rmdir: (dirPath) => fs.rmdir(translate(dirPath)),
+	};
+}
+
+async function runNodeProjectWriteTransaction(
+	projectRoot: string,
+	write: (stagedFileSystem: BackendFileSystem) => Promise<void>,
+): Promise<void> {
+	const root = path.resolve(projectRoot);
+	const parent = path.dirname(root);
+	const name = path.basename(root);
+	const staging = path.join(parent, `.${name}.save-${randomUUID()}`);
+	const backup = path.join(parent, `.${name}.save-backup-${randomUUID()}`);
+	const existed = await pathExists(root);
+	if (existed) {
+		await assertNoSymlinks(root);
+		await fs.cp(root, staging, { recursive: true, errorOnExist: true, force: false });
+	} else {
+		await fs.mkdir(staging, { recursive: true });
+	}
+	try {
+		await write(createStagedNodeFileSystem(root, staging));
+	} catch (error) {
+		await fs.rm(staging, { recursive: true, force: true });
+		throw error;
+	}
+	if (!existed) {
+		await fs.rename(staging, root);
+		return;
+	}
+
+	// ponytail: two-step rename preserves rollback; use directory exchange if zero reader gap becomes required.
+	await fs.rename(root, backup);
+	try {
+		await fs.rename(staging, root);
+	} catch (error) {
+		await fs.rename(backup, root);
+		await fs.rm(staging, { recursive: true, force: true });
+		throw error;
+	}
+	await fs.rm(backup, { recursive: true, force: true }).catch(() => undefined);
+}
+
 export function createNodeBackendFileSystem(): BackendFileSystem {
 	return {
 		stat(filePath: string): Promise<BackendFileStat> {
 			return fs.stat(filePath);
 		},
-		readdir(dirPath: string): Promise<string[]> {
-			return fs.readdir(dirPath);
+		async readdir(dirPath: string): Promise<string[]> {
+			const entries = await fs.readdir(dirPath, { withFileTypes: true });
+			const symlink = entries.find((entry) => entry.isSymbolicLink());
+			if (symlink) {
+				const error = new Error(`Symbolic links are not supported in project directories: ${path.join(dirPath, symlink.name)}`) as Error & { code: string };
+				error.code = 'ELOOP';
+				throw error;
+			}
+			return entries.map((entry) => entry.name);
 		},
 		readFile(filePath: string): Promise<string> {
 			return fs.readFile(filePath, 'utf-8');
@@ -34,16 +206,32 @@ export function createNodeBackendFileSystem(): BackendFileSystem {
 			await fs.mkdir(dirPath, { recursive: options?.recursive ?? false });
 		},
 		async resolvePath(filePath: string): Promise<string> {
-			try {
-				return await fs.realpath(filePath);
-			} catch {
-				return path.resolve(filePath);
-			}
+			return resolvePathThroughExistingAncestor(filePath);
+		},
+		validateProjectRoot: assertNoSymlinks,
+		getSessionLockPath(canonicalProjectPath: string): string {
+			return path.join(path.dirname(canonicalProjectPath), `.${path.basename(canonicalProjectPath)}.openfairygui.backend.lock`);
 		},
+		runProjectWriteTransaction: runNodeProjectWriteTransaction,
 		async acquireSessionLock(filePath: string): Promise<BackendSessionLock> {
-			const handle = await fs.open(filePath, 'wx');
+			let handle: Awaited<ReturnType<typeof fs.open>>;
+			try {
+				handle = await fs.open(filePath, 'wx');
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== 'EEXIST' || !(await recoverStaleLock(filePath))) throw error;
+				handle = await fs.open(filePath, 'wx');
+			}
+			const owner = {
+				schemaVersion: 1 as const,
+				pid: process.pid,
+				processStartTime: PROCESS_START_TIME,
+				hostname: os.hostname(),
+				token: randomUUID(),
+				createdAt: new Date().toISOString(),
+			};
 			let closed = false;
 			let released = false;
+			let metadataWritten = false;
 			const closeHandle = async (): Promise<void> => {
 				if (closed) return;
 				await handle.close();
@@ -51,15 +239,28 @@ export function createNodeBackendFileSystem(): BackendFileSystem {
 			};
 			return {
 				async writeMetadata(content: string): Promise<void> {
-					await handle.writeFile(content, 'utf-8');
+					let supplied: Record<string, unknown> = {};
+					try {
+						const parsed = JSON.parse(content) as unknown;
+						if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) supplied = parsed as Record<string, unknown>;
+					} catch {
+						// Host metadata is optional; ownership metadata remains authoritative.
+					}
+					await handle.writeFile(JSON.stringify({ ...supplied, ...owner }, null, 2), 'utf-8');
+					metadataWritten = true;
 					await closeHandle();
 				},
 				async release(): Promise<void> {
 					if (released) return;
 					await closeHandle();
-					await fs.unlink(filePath).catch((error: NodeJS.ErrnoException) => {
-						if (error.code !== 'ENOENT') throw error;
-					});
+					const current = metadataWritten
+						? parseLockMetadata(await fs.readFile(filePath, 'utf-8').catch(() => ''))
+						: null;
+					if (!metadataWritten || current?.token === owner.token) {
+						await fs.unlink(filePath).catch((error: NodeJS.ErrnoException) => {
+							if (error.code !== 'ENOENT') throw error;
+						});
+					}
 					released = true;
 				},
 			};
@@ -86,8 +287,6 @@ export function createNodeBackendHostAdapter(): BackendHostAdapter {
 	return {
 		lockMetadata(input) {
 			return {
-				pid: process.pid,
-				createdAt: new Date().toISOString(),
 				canonicalPathKey: input.canonicalPathKey,
 			};
 		},

package/src/path-policy.ts

@@ -41,6 +41,24 @@ export function createRuntimePathPolicy(): BackendCapabilities['runtime']['pathP
 	};
 }
 
+export async function assertProjectPathContained(
+	fileSystem: BackendFileSystem,
+	projectRoot: string,
+	targetPath: string,
+): Promise<void> {
+	const [resolvedRoot, resolvedTarget] = await Promise.all([
+		fileSystem.resolvePath(projectRoot),
+		fileSystem.resolvePath(targetPath),
+	]);
+	const root = normalizeComparablePath(resolvedRoot);
+	const target = normalizeComparablePath(resolvedTarget);
+	if (root === '.' && !target.startsWith('/') && !/^[a-z]:\//i.test(target)) return;
+	if (target === root || target.startsWith(`${root}/`)) return;
+	const error = new Error(`Project path escapes the opened root: ${targetPath}`) as Error & { code: string };
+	error.code = 'EACCES';
+	throw error;
+}
+
 export async function resolveFairyPath(fileSystem: BackendFileSystem, input: string): Promise<string> {
 	const resolvedInput = fileSystem.resolve(input);
 	const stat = await fileSystem.stat(resolvedInput);

package/src/runtime/capabilities.ts

@@ -38,7 +38,7 @@ const ARTIFACT_BRIDGE_CAPABILITY = {
 	reason: 'publish/restore require explicit Node-hosted filesystem and artifact execution.',
 } as const satisfies BackendArtifactBridgeCapability;
 
-export function createCapabilities(): BackendCapabilities {
+export function createCapabilities(atomicSave = false): BackendCapabilities {
 	return {
 		contractVersion: BACKEND_CONTRACT_VERSION,
 		capabilitySchemaVersion: BACKEND_CAPABILITY_SCHEMA_VERSION,
@@ -102,7 +102,7 @@ export function createCapabilities(): BackendCapabilities {
 			sessionRuntime: true,
 			advisoryLocking: true,
 			coordinatedSave: true,
-			atomicSave: false,
+			atomicSave,
 			staleRevisionProtection: true,
 			pathPolicy: createRuntimePathPolicy(),
 			events: {

package/src/runtime/contracts.ts

@@ -36,6 +36,15 @@ export interface BackendFileSystem {
 	writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
 	mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void>;
 	resolvePath(filePath: string): Promise<string>;
+	/** Optional host validation before a project is read. Node rejects links anywhere in the project tree. */
+	validateProjectRoot?(projectRoot: string): Promise<void>;
+	/** Optional host-specific lock location. Node keeps it beside the project so directory swaps do not move it. */
+	getSessionLockPath?(canonicalProjectPath: string): string;
+	/** Runs project writes against a staged copy and commits them as one directory swap. */
+	runProjectWriteTransaction?(
+		projectRoot: string,
+		write: (stagedFileSystem: BackendFileSystem) => Promise<void>,
+	): Promise<void>;
 	acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
 	unlink(filePath: string): Promise<void>;
 	rmdir(dirPath: string): Promise<void>;
@@ -144,7 +153,7 @@ export interface BackendCapabilities {
 		sessionRuntime: true;
 		advisoryLocking: true;
 		coordinatedSave: true;
-		atomicSave: false;
+		atomicSave: boolean;
 		staleRevisionProtection: true;
 		pathPolicy: {
 			canonicalization: 'realpath+normalized-casefold';
@@ -276,6 +285,12 @@ export interface AdvisoryLockConflictError {
 	lockFilePath: string;
 }
 
+export interface SessionIdConflictError {
+	code: 'session_id_conflict';
+	message: string;
+	sessionId: string;
+}
+
 export interface SavePartialFailureError {
 	code: 'save_partial_failure';
 	message: string;
@@ -285,7 +300,7 @@ export interface SavePartialFailureError {
 	lastSavedRevision: number;
 	committedPaths: string[];
 	failedPaths: string[];
-	diskMayBePartiallyUpdated: true;
+	diskMayBePartiallyUpdated: boolean;
 }
 
 export interface UamFidelityUnsupportedError {
@@ -315,7 +330,7 @@ export interface MaterializeWriteFailedError {
 	failedPaths: string[];
 	skippedPaths: string[];
 	diagnostics: BackendDiagnostic[];
-	diskMayBePartiallyUpdated: true;
+	diskMayBePartiallyUpdated: boolean;
 }
 
 export type BackendEventKind =
@@ -494,6 +509,7 @@ export interface RefreshCacheInput {
 
 export type BackendError =
 	| SessionNotFoundError
+	| SessionIdConflictError
 	| SessionStaleWriteError
 	| InProcessLockConflictError
 	| AdvisoryLockConflictError
@@ -508,8 +524,22 @@ export type BackendError =
 	| BackendJobCancelledError
 	| CacheRefreshFailedError
 	| BackendCapabilityUnavailableError
+	| ProjectRootNotAllowedError
+	| ProjectOpenFailedError
 	| ApplyUamTransactionAppError;
 
+export interface ProjectRootNotAllowedError {
+	code: 'project_root_not_allowed';
+	message: string;
+	projectPath: string;
+}
+
+export interface ProjectOpenFailedError {
+	code: 'project_open_failed';
+	message: string;
+	projectPath: string;
+}
+
 export interface ApplySessionTransactionInput {
 	sessionId: string;
 	expectedRevision: number;
@@ -563,4 +593,6 @@ export interface MaterializeSessionInput {
 export interface BackendRuntimeOptions {
 	fileSystem?: BackendFileSystem;
 	host?: BackendHostAdapter;
+	/** Canonical filesystem roots available to file-backed sessions. Omit for unrestricted library use. */
+	allowedProjectRoots?: readonly string[];
 }

package/src/runtime.ts

@@ -3,7 +3,7 @@ import type { ProjectValidationReport } from '@openfairygui/core';
 import type { PathPolicyViolationError } from './path-policy.js';
 import { AuthoringService } from './services/authoring-service.js';
 import { CacheService } from './services/cache-service.js';
-import type { BackendContext, BackendSessionState } from './services/context.js';
+import { type BackendContext, type BackendSessionState, failure } from './services/context.js';
 import { EventService } from './services/event-service.js';
 import { JobService } from './services/job-service.js';
 import { ReadService } from './services/read-service.js';
@@ -42,9 +42,12 @@ import type {
 	MaterializeValidationFailedError,
 	MaterializeWriteFailedError,
 	OpenProjectSessionInput,
+	ProjectOpenFailedError,
+	ProjectRootNotAllowedError,
 	RefreshCacheInput,
 	SavePartialFailureError,
 	SaveSessionInput,
+	SessionIdConflictError,
 	SessionNotFoundError,
 	SessionStaleWriteError,
 	UamFidelityUnsupportedError,
@@ -71,10 +74,11 @@ export class BackendRuntime {
 
 	public constructor(options: BackendRuntimeOptions = {}) {
 		this.fileSystem = options.fileSystem;
-		this.capabilities = createCapabilities();
+		this.capabilities = createCapabilities(Boolean(options.fileSystem?.runProjectWriteTransaction));
 		this.context = {
 			fileSystem: this.fileSystem,
 			host: options.host,
+			allowedProjectRoots: options.allowedProjectRoots,
 			capabilities: this.capabilities,
 			sessions: this.sessions,
 			sessionsByPath: this.sessionsByPath,
@@ -103,13 +107,28 @@ export class BackendRuntime {
 	}): Promise<
 		BackendResult<
 			BackendSessionSnapshot,
-			InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError
+			InProcessLockConflictError
+			| AdvisoryLockConflictError
+			| BackendCapabilityUnavailableError
+			| ProjectRootNotAllowedError
+			| ProjectOpenFailedError
 		>
 	> {
-		return this.runtimeService.openSession(input);
-	}
-
-	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
+		const startedAt = Date.now();
+		try {
+			return await this.runtimeService.openSession(input);
+		} catch {
+			return failure('runtime', startedAt, {
+				code: 'project_open_failed',
+				message: 'Unable to open project.',
+				projectPath: input.projectPath,
+			});
+		}
+	}
+
+	public openProjectSession(
+		input: OpenProjectSessionInput,
+	): BackendResult<BackendSessionSnapshot, InProcessLockConflictError | SessionIdConflictError> {
 		return this.runtimeService.openProjectSession(input);
 	}
 
@@ -180,7 +199,7 @@ export class BackendRuntime {
 	public async closeSession(input: {
 		sessionId: string;
 	}): Promise<BackendResult<{ sessionId: string; closed: true }, SessionNotFoundError>> {
-		return this.runtimeService.closeSession(input);
+		return this.authoringService.runSessionExclusive(input.sessionId, () => this.runtimeService.closeSession(input));
 	}
 
 	public getEvents(

package/src/services/authoring-service.ts

@@ -178,7 +178,7 @@ export class AuthoringService {
 		private readonly eventService: EventService,
 	) {}
 
-	private async runSessionExclusive<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+	public async runSessionExclusive<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
 		const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
 		let release = (): void => undefined;
 		const current = new Promise<void>((resolve) => {
@@ -465,7 +465,7 @@ export class AuthoringService {
 					lastSavedRevision: session.lastSavedRevision,
 					committedPaths,
 					failedPaths,
-					diskMayBePartiallyUpdated: true,
+					diskMayBePartiallyUpdated: !fileSystem.runProjectWriteTransaction,
 				},
 				toSessionSnapshot(session, this.context.capabilities),
 				{
@@ -744,7 +744,7 @@ export class AuthoringService {
 					failedPaths,
 					skippedPaths,
 					diagnostics: diagnosticsFromError,
-					diskMayBePartiallyUpdated: true,
+					diskMayBePartiallyUpdated: !fileSystem.runProjectWriteTransaction,
 				},
 				toSessionSnapshot(session, this.context.capabilities),
 				{

package/src/services/context.ts

@@ -48,6 +48,7 @@ export interface BackendSessionState {
 export interface BackendContext {
 	fileSystem?: BackendFileSystem;
 	host?: BackendHostAdapter;
+	allowedProjectRoots?: readonly string[];
 	capabilities: BackendCapabilities;
 	sessions: Map<string, BackendSessionState>;
 	sessionsByPath: Map<string, string>;

package/src/services/runtime-service.ts

@@ -5,7 +5,7 @@ import {
 	normalizeUamProject,
 	type UamProject,
 } from '@openfairygui/core/uam';
-import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
+import { assertProjectPathContained, normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
 import type {
 	AdvisoryLockConflictError,
 	BackendCapabilityUnavailableError,
@@ -14,6 +14,8 @@ import type {
 	BackendSessionSnapshot,
 	InProcessLockConflictError,
 	OpenProjectSessionInput,
+	ProjectRootNotAllowedError,
+	SessionIdConflictError,
 	SessionNotFoundError,
 } from '../runtime.js';
 import type { CacheService } from './cache-service.js';
@@ -23,7 +25,7 @@ import type { JobService } from './job-service.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
 function randomId(): string {
-	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+	return crypto.randomUUID();
 }
 
 function createCapabilityUnavailableError(
@@ -42,29 +44,36 @@ function createCapabilityUnavailableError(
 	};
 }
 
-function createProjectReaderFileSystem(fileSystem: NonNullable<BackendContext['fileSystem']>): FileSystem {
+function createProjectReaderFileSystem(
+	fileSystem: NonNullable<BackendContext['fileSystem']>,
+	projectRoot: string,
+): FileSystem {
+	const contained = async <T>(filePath: string, operation: () => Promise<T>): Promise<T> => {
+		await assertProjectPathContained(fileSystem, projectRoot, filePath);
+		return operation();
+	};
 	return {
 		readFile(filePath: string): Promise<string> {
-			return fileSystem.readFile(filePath);
+			return contained(filePath, () => fileSystem.readFile(filePath));
 		},
 		readFileRaw(filePath: string): Promise<Uint8Array> {
-			return fileSystem.readFileRaw(filePath);
+			return contained(filePath, () => fileSystem.readFileRaw(filePath));
 		},
 		writeFile(filePath: string, content: string): Promise<void> {
-			return fileSystem.writeFile(filePath, content);
+			return contained(filePath, () => fileSystem.writeFile(filePath, content));
 		},
 		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
-			return fileSystem.writeFileRaw(filePath, data);
+			return contained(filePath, () => fileSystem.writeFileRaw(filePath, data));
 		},
 		async mkdir(dirPath: string): Promise<void> {
-			await fileSystem.mkdir(dirPath, { recursive: true });
+			await contained(dirPath, () => fileSystem.mkdir(dirPath, { recursive: true }));
 		},
 		readdir(dirPath: string): Promise<string[]> {
-			return fileSystem.readdir(dirPath);
+			return contained(dirPath, () => fileSystem.readdir(dirPath));
 		},
 		async exists(filePath: string): Promise<boolean> {
 			try {
-				await fileSystem.stat(filePath);
+				await contained(filePath, () => fileSystem.stat(filePath));
 				return true;
 			} catch {
 				return false;
@@ -180,7 +189,7 @@ export class RuntimeService {
 	}): Promise<
 		BackendResult<
 			BackendSessionSnapshot,
-			InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError
+			InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError | ProjectRootNotAllowedError
 		>
 	> {
 		const startedAt = Date.now();
@@ -188,10 +197,31 @@ export class RuntimeService {
 			return failure('runtime', startedAt, createCapabilityUnavailableError('fileSystem'));
 		}
 		const fileSystem = this.context.fileSystem;
+		if (this.context.allowedProjectRoots?.length) {
+			let allowed = false;
+			for (const root of this.context.allowedProjectRoots) {
+				try {
+					await assertProjectPathContained(fileSystem, root, input.projectPath);
+					allowed = true;
+					break;
+				} catch (error) {
+					if ((error as { code?: unknown }).code !== 'EACCES') throw error;
+				}
+			}
+			if (!allowed) {
+				return failure('runtime', startedAt, {
+					code: 'project_root_not_allowed',
+					message: 'Project path is outside the configured allowed roots.',
+					projectPath: input.projectPath,
+				});
+			}
+		}
 		const resolved = await resolveCanonicalProjectRoot(fileSystem, input.projectPath);
 		const { fairyPath, canonicalProjectPath, canonicalPathKey } = resolved;
+		await fileSystem.validateProjectRoot?.(canonicalProjectPath);
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
-		const lockFilePath = fileSystem.join(canonicalProjectPath, '.openfairygui.backend.lock');
+		const lockFilePath = fileSystem.getSessionLockPath?.(canonicalProjectPath)
+			?? fileSystem.join(canonicalProjectPath, '.openfairygui.backend.lock');
 
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -219,7 +249,7 @@ export class RuntimeService {
 					},
 				),
 			);
-			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem));
+			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem, canonicalProjectPath));
 			const read = await reader.readDetailed(fairyPath, { hydrateResourceBytes: true });
 			if (!read.document) throw new Error(read.diagnostics[0]?.message ?? `Unable to read project: ${fairyPath}`);
 			const document = read.document;
@@ -276,9 +306,18 @@ export class RuntimeService {
 		}
 	}
 
-	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
+	public openProjectSession(
+		input: OpenProjectSessionInput,
+	): BackendResult<BackendSessionSnapshot, InProcessLockConflictError | SessionIdConflictError> {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
+		if (this.context.sessions.has(sessionId)) {
+			return failure('runtime', startedAt, {
+				code: 'session_id_conflict',
+				message: `Session id is already in use: ${sessionId}`,
+				sessionId,
+			});
+		}
 		const storage = input.storage;
 		const memoryProjectPath = `memory://${sessionId}`;
 		const canonicalProjectPath =