@geometra/mcp 1.64.0 → 1.65.1

package/dist/session-state.js

@@ -1,76 +1,248 @@
-import { mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { accessSync, chmodSync, closeSync, constants, lstatSync, mkdirSync, openSync, } from 'node:fs';
 import path from 'node:path';
-import { threadId } from 'node:worker_threads';
 import { ParallelMcpOrchestrator, SqliteParallelMcpStore, } from '@razroo/parallel-mcp';
+import { sanitizeRetainedCode, sanitizeRetainedError, sanitizeRetainedState, } from './state-privacy.js';
 const SESSION_NAMESPACE = 'geometra-mcp-session';
 const SESSION_TASK_KEY = 'session.live';
 const SESSION_LEASE_MS = 60_000;
 const SESSION_SWEEP_MS = 15_000;
 const SESSION_WORKER_PREFIX = `geometra-mcp:${process.pid}`;
-function resolveSessionStateFile() {
+const SECURE_DIRECTORY_MODE = 0o700;
+const SECURE_FILE_MODE = 0o600;
+class SessionStateConfigurationError extends Error {
+}
+let lifecycleRegistry = null;
+function configurationError(message) {
+    return new SessionStateConfigurationError(`Refusing GEOMETRA_MCP_STATE_FILE: ${message}`);
+}
+function lstatIfPresent(targetPath, description) {
+    try {
+        return lstatSync(targetPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw configurationError(`${description} could not be inspected securely`);
+    }
+}
+function assertCurrentProcessOwns(stats, description) {
+    if (typeof process.geteuid === 'function' && stats.uid !== process.geteuid()) {
+        throw configurationError(`${description} must be owned by the current user`);
+    }
+}
+function assertSecureStateDirectory(directory) {
+    const stats = lstatIfPresent(directory, 'parent directory');
+    if (!stats)
+        throw configurationError('parent directory does not exist');
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw configurationError('parent must be a real directory, not a symbolic link');
+    }
+    assertCurrentProcessOwns(stats, 'parent directory');
+    if ((stats.mode & 0o077) !== 0) {
+        throw configurationError('existing parent directory must not grant group or other access (mode 0700 or stricter)');
+    }
+    try {
+        accessSync(directory, constants.R_OK | constants.W_OK | constants.X_OK);
+    }
+    catch {
+        throw configurationError('parent directory must be readable, writable, and searchable by the current user');
+    }
+}
+function assertRegularOwnedArtifact(stats, description) {
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        throw configurationError(`${description} must be a regular file, not a symbolic link or special file`);
+    }
+    assertCurrentProcessOwns(stats, description);
+    if (stats.nlink !== 1) {
+        throw configurationError(`${description} must not have multiple hard links`);
+    }
+}
+function secureExistingArtifact(artifactPath, description) {
+    const stats = lstatIfPresent(artifactPath, description);
+    if (!stats)
+        return false;
+    assertRegularOwnedArtifact(stats, description);
+    try {
+        chmodSync(artifactPath, SECURE_FILE_MODE);
+    }
+    catch {
+        throw configurationError(`${description} permissions could not be restricted to mode 0600`);
+    }
+    const secured = lstatIfPresent(artifactPath, description);
+    if (!secured)
+        throw configurationError(`${description} disappeared while permissions were secured`);
+    assertRegularOwnedArtifact(secured, description);
+    if ((secured.mode & 0o077) !== 0) {
+        throw configurationError(`${description} permissions are not private`);
+    }
+    return true;
+}
+function sqliteSidecarPaths(filename) {
+    return [
+        [`${filename}-wal`, 'WAL file'],
+        [`${filename}-shm`, 'shared-memory file'],
+        [`${filename}-journal`, 'rollback journal'],
+    ];
+}
+function preparePersistentStateFile(filename) {
+    const directory = path.dirname(filename);
+    if (!lstatIfPresent(directory, 'parent directory')) {
+        try {
+            mkdirSync(directory, { recursive: true, mode: SECURE_DIRECTORY_MODE });
+        }
+        catch {
+            throw configurationError('parent directory could not be created securely');
+        }
+    }
+    assertSecureStateDirectory(directory);
+    for (const [sidecarPath, description] of sqliteSidecarPaths(filename)) {
+        secureExistingArtifact(sidecarPath, description);
+    }
+    if (!secureExistingArtifact(filename, 'database file')) {
+        let descriptor;
+        try {
+            const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+            descriptor = openSync(filename, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | noFollow, SECURE_FILE_MODE);
+        }
+        catch {
+            throw configurationError('database file could not be created exclusively and securely');
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+        secureExistingArtifact(filename, 'database file');
+    }
+}
+function securePersistentArtifacts(filename) {
+    assertSecureStateDirectory(path.dirname(filename));
+    if (!secureExistingArtifact(filename, 'database file')) {
+        throw configurationError('database file disappeared while storage was active');
+    }
+    for (const [sidecarPath, description] of sqliteSidecarPaths(filename)) {
+        secureExistingArtifact(sidecarPath, description);
+    }
+}
+function resolveSessionStateStorage() {
     const raw = process.env.GEOMETRA_MCP_STATE_FILE?.trim();
-    if (raw) {
-        mkdirSync(path.dirname(raw), { recursive: true });
-        return raw;
+    if (!raw || raw === ':memory:') {
+        return { filename: ':memory:', persistentPath: null };
     }
-    const dir = path.join(homedir(), '.geometra-mcp');
-    mkdirSync(dir, { recursive: true });
-    return path.join(dir, `parallel-mcp-${process.pid}-${threadId}.sqlite`);
+    if (raw.includes('\0'))
+        throw configurationError('path contains an invalid null byte');
+    const filename = path.resolve(raw);
+    preparePersistentStateFile(filename);
+    return { filename, persistentPath: filename };
 }
 function isSessionLifecycleDisabled() {
     const raw = process.env.GEOMETRA_MCP_DISABLE_SESSION_LIFECYCLE?.trim().toLowerCase();
     return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
 }
 function formatSessionLifecycleInitError(error) {
-    if (error instanceof Error) {
-        if (error.code === 'ERR_DLOPEN_FAILED' &&
-            error.message.includes('better_sqlite3.node')) {
-            return `${error.message}. Rebuild the native module with \`npm rebuild better-sqlite3\` in the MCP package directory, or reinstall dependencies for the current Node.js version.`;
-        }
+    if (error instanceof SessionStateConfigurationError)
         return error.message;
+    if (error instanceof Error &&
+        error.code === 'ERR_DLOPEN_FAILED' &&
+        error.message.includes('better_sqlite3.node')) {
+        return 'The SQLite native module is unavailable. Rebuild it with `npm rebuild better-sqlite3` in the MCP package directory, or reinstall dependencies for the current Node.js version.';
     }
-    return String(error);
+    return 'Secure session lifecycle storage could not be initialized';
 }
 function createSessionLifecycleRegistry() {
     if (isSessionLifecycleDisabled()) {
-        process.stderr.write('[geometra-mcp] durable session lifecycle disabled via GEOMETRA_MCP_DISABLE_SESSION_LIFECYCLE\n');
+        process.stderr.write('[geometra-mcp] session lifecycle disabled via GEOMETRA_MCP_DISABLE_SESSION_LIFECYCLE\n');
         return {
             available: false,
             orchestrator: null,
+            secureArtifacts: () => { },
             close: () => { },
         };
     }
+    const configuredStateFile = process.env.GEOMETRA_MCP_STATE_FILE?.trim();
+    const persistentStorageRequested = Boolean(configuredStateFile && configuredStateFile !== ':memory:');
+    let orchestrator = null;
     try {
-        const orchestrator = new ParallelMcpOrchestrator(new SqliteParallelMcpStore({ filename: resolveSessionStateFile() }), { defaultLeaseMs: SESSION_LEASE_MS });
-        const leaseSweep = setInterval(() => {
+        const storage = resolveSessionStateStorage();
+        orchestrator = new ParallelMcpOrchestrator(new SqliteParallelMcpStore({ filename: storage.filename }), { defaultLeaseMs: SESSION_LEASE_MS });
+        const secureArtifacts = storage.persistentPath
+            ? () => securePersistentArtifacts(storage.persistentPath)
+            : () => { };
+        secureArtifacts();
+        let closed = false;
+        let leaseSweep = null;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (leaseSweep)
+                clearInterval(leaseSweep);
+            try {
+                secureArtifacts();
+            }
+            finally {
+                orchestrator?.close();
+            }
+        };
+        leaseSweep = setInterval(() => {
+            if (closed)
+                return;
             try {
-                orchestrator.expireLeases();
+                orchestrator?.expireLeases();
+                secureArtifacts();
             }
             catch {
-                /* ignore background lease sweep failures */
+                process.stderr.write('[geometra-mcp] session lifecycle storage failed a background security check and was closed\n');
+                try {
+                    close();
+                }
+                catch {
+                    /* already failed closed */
+                }
             }
         }, SESSION_SWEEP_MS);
         leaseSweep.unref();
         return {
-            available: true,
-            orchestrator,
-            close: () => {
-                clearInterval(leaseSweep);
-                orchestrator.close();
+            get available() {
+                return !closed;
             },
+            orchestrator,
+            secureArtifacts,
+            close,
         };
     }
     catch (error) {
-        process.stderr.write(`[geometra-mcp] durable session lifecycle disabled: ${formatSessionLifecycleInitError(error)}\n`);
+        try {
+            orchestrator?.close();
+        }
+        catch {
+            /* initialization already failed */
+        }
+        const safeError = formatSessionLifecycleInitError(error);
+        if (persistentStorageRequested) {
+            // The caught cause can contain the configured path or native-module
+            // filesystem details; attaching it would defeat this privacy boundary.
+            // eslint-disable-next-line preserve-caught-error
+            throw new Error(safeError);
+        }
+        process.stderr.write(`[geometra-mcp] session lifecycle unavailable: ${safeError}\n`);
         return {
             available: false,
             orchestrator: null,
+            secureArtifacts: () => { },
             close: () => { },
         };
     }
 }
-const lifecycleRegistry = createSessionLifecycleRegistry();
+function getSessionLifecycleRegistry() {
+    if (!lifecycleRegistry)
+        lifecycleRegistry = createSessionLifecycleRegistry();
+    return lifecycleRegistry;
+}
+function currentSessionLifecycleRegistry() {
+    return lifecycleRegistry?.available && lifecycleRegistry.orchestrator
+        ? lifecycleRegistry
+        : null;
+}
 function extractPageUrl(target) {
     const cached = target.cachedA11y?.meta?.pageUrl;
     if (typeof cached === 'string' && cached.length > 0)
@@ -80,31 +252,18 @@ function extractPageUrl(target) {
         return semantic.pageUrl;
     return null;
 }
-function toJsonValue(value) {
-    if (value === null)
-        return null;
-    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-        return value;
-    }
-    if (value instanceof Date) {
-        return value.toISOString();
-    }
-    if (Array.isArray(value)) {
-        return value.map(item => toJsonValue(item));
-    }
-    if (typeof value === 'object') {
-        const object = {};
-        for (const [key, entry] of Object.entries(value)) {
-            if (entry === undefined)
-                continue;
-            object[key] = toJsonValue(entry);
-        }
-        return object;
+function toRetainedJsonValue(value) {
+    return sanitizeRetainedState(value);
+}
+function toRetainedJsonObject(value) {
+    const retained = sanitizeRetainedState(value);
+    if (retained && typeof retained === 'object' && !Array.isArray(retained)) {
+        return retained;
     }
-    return String(value);
+    return {};
 }
 function buildSessionContext(target, label, extra) {
-    return {
+    return toRetainedJsonObject({
         sessionId: target.id,
         label,
         transportUrl: target.url,
@@ -116,8 +275,8 @@ function buildSessionContext(target, label, extra) {
         hasLayout: target.layout !== null,
         hasTree: target.tree !== null,
         connectMode: target.connectTrace?.mode ?? null,
-        ...(extra ? { extra: toJsonValue(extra) } : {}),
-    };
+        ...(extra ? { extra } : {}),
+    });
 }
 function liveTaskIdFor(sessionId) {
     return `${sessionId}:live`;
@@ -128,8 +287,23 @@ function liveTaskKindFor(sessionId) {
 function workerIdFor(sessionId) {
     return `${SESSION_WORKER_PREFIX}:${sessionId}`;
 }
+function secureAfterWrite(registry) {
+    try {
+        registry.secureArtifacts();
+    }
+    catch {
+        try {
+            registry.close();
+        }
+        catch {
+            /* fail closed even if SQLite close also fails */
+        }
+        throw new Error('Session lifecycle storage failed a security check and was closed');
+    }
+}
 export function initializeSessionLifecycle(target, options) {
-    if (!lifecycleRegistry.available || !lifecycleRegistry.orchestrator) {
+    const registry = getSessionLifecycleRegistry();
+    if (!registry.available || !registry.orchestrator) {
         target.lifecycleFinalized = true;
         target.lifecycleTaskId = undefined;
         target.lifecycleTaskKind = undefined;
@@ -137,7 +311,7 @@ export function initializeSessionLifecycle(target, options) {
         target.lifecycleWorkerId = undefined;
         return;
     }
-    const orchestrator = lifecycleRegistry.orchestrator;
+    const orchestrator = registry.orchestrator;
     const sessionId = target.id;
     const taskId = liveTaskIdFor(sessionId);
     const taskKind = liveTaskKindFor(sessionId);
@@ -145,7 +319,7 @@ export function initializeSessionLifecycle(target, options) {
     orchestrator.createRun({
         id: sessionId,
         namespace: SESSION_NAMESPACE,
-        metadata: toJsonValue({
+        metadata: toRetainedJsonValue({
             transportMode: options?.transportMode ?? 'direct-ws',
             isolated: target.isolated === true,
         }),
@@ -158,7 +332,7 @@ export function initializeSessionLifecycle(target, options) {
         runId: sessionId,
         key: SESSION_TASK_KEY,
         kind: taskKind,
-        input: toJsonValue({
+        input: toRetainedJsonValue({
             transportUrl: target.url,
             requestedPageUrl: options?.pageUrl ?? null,
         }),
@@ -169,13 +343,14 @@ export function initializeSessionLifecycle(target, options) {
         leaseMs: SESSION_LEASE_MS,
     });
     if (!claimed || claimed.task.id !== taskId) {
-        throw new Error(`Failed to initialize durable session task for ${sessionId}`);
+        throw new Error('Failed to initialize session lifecycle task');
     }
     orchestrator.markTaskRunning({
         taskId,
         leaseId: claimed.lease.id,
         workerId,
     });
+    secureAfterWrite(registry);
     target.lifecycleTaskId = taskId;
     target.lifecycleTaskKind = taskKind;
     target.lifecycleLeaseId = claimed.lease.id;
@@ -183,73 +358,80 @@ export function initializeSessionLifecycle(target, options) {
     target.lifecycleFinalized = false;
 }
 export function heartbeatSessionLifecycle(target) {
-    if (!lifecycleRegistry.orchestrator)
+    const registry = currentSessionLifecycleRegistry();
+    if (!registry?.orchestrator)
         return;
-    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
-    orchestrator.heartbeatLease({
+    registry.orchestrator.heartbeatLease({
         taskId: target.lifecycleTaskId,
         leaseId: target.lifecycleLeaseId,
         workerId: target.lifecycleWorkerId,
         leaseMs: SESSION_LEASE_MS,
     });
+    secureAfterWrite(registry);
 }
 export function recordSessionSnapshot(target, label, extra) {
-    if (!lifecycleRegistry.orchestrator)
+    const registry = currentSessionLifecycleRegistry();
+    if (!registry?.orchestrator || !target.lifecycleTaskId)
         return;
-    const orchestrator = lifecycleRegistry.orchestrator;
-    if (!target.lifecycleTaskId)
-        return;
-    orchestrator.appendContextSnapshot({
+    const retainedLabel = sanitizeRetainedCode(label);
+    registry.orchestrator.appendContextSnapshot({
         runId: target.id,
         taskId: target.lifecycleTaskId,
         scope: 'run',
-        label,
-        payload: buildSessionContext(target, label, extra),
+        label: retainedLabel,
+        payload: buildSessionContext(target, retainedLabel, extra),
     });
+    secureAfterWrite(registry);
 }
 export function completeSessionLifecycle(target, reason, extra) {
-    if (!lifecycleRegistry.orchestrator)
+    const registry = currentSessionLifecycleRegistry();
+    if (!registry?.orchestrator)
         return;
-    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
-    orchestrator.completeTask({
+    const retainedReason = sanitizeRetainedCode(reason);
+    registry.orchestrator.completeTask({
         taskId: target.lifecycleTaskId,
         leaseId: target.lifecycleLeaseId,
         workerId: target.lifecycleWorkerId,
-        output: toJsonValue({
-            reason,
+        output: toRetainedJsonValue({
+            reason: retainedReason,
             ...(extra ? { extra } : {}),
         }),
         nextContext: buildSessionContext(target, 'session.completed', {
-            reason,
+            reason: retainedReason,
             ...(extra ? { ...extra } : {}),
         }),
         nextContextLabel: 'session.completed',
     });
+    secureAfterWrite(registry);
     target.lifecycleFinalized = true;
 }
 export function failSessionLifecycle(target, error, extra) {
-    if (!lifecycleRegistry.orchestrator)
+    const registry = currentSessionLifecycleRegistry();
+    if (!registry?.orchestrator)
         return;
-    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
+    const retainedError = sanitizeRetainedError(error);
     recordSessionSnapshot(target, 'session.failed', {
-        error,
+        error: retainedError,
         ...(extra ? { ...extra } : {}),
     });
-    orchestrator.failTask({
+    registry.orchestrator.failTask({
         taskId: target.lifecycleTaskId,
         leaseId: target.lifecycleLeaseId,
         workerId: target.lifecycleWorkerId,
-        error,
-        metadata: extra ? toJsonValue(extra) : undefined,
+        error: retainedError,
+        metadata: extra ? toRetainedJsonValue(extra) : undefined,
     });
+    secureAfterWrite(registry);
     target.lifecycleFinalized = true;
 }
 export function shutdownSessionLifecycleRegistry() {
-    lifecycleRegistry.close();
+    const registry = lifecycleRegistry;
+    lifecycleRegistry = null;
+    registry?.close();
 }