consciousness-explorer 1.1.1 → 1.1.2

package/index.js

@@ -268,6 +268,12 @@ export class ConsciousnessExplorer {
      * Export consciousness state
      */
     async exportState(filepath) {
+        // SECURITY (issue #19, CWE-73): `filepath` arrives from an MCP caller
+        // and used to land straight in fs.writeFileSync — allowing arbitrary
+        // file writes. Force it through resolveStatePath so it can only
+        // resolve to a basename inside the dedicated state directory.
+        const { safeWriteState } = await import('./lib/safe-path.js');
+
         const state = {
             version: VERSION,
             timestamp: Date.now(),
@@ -284,8 +290,9 @@ export class ConsciousnessExplorer {
             state.reasoner_state = this.reasoner.exportState();
         }
 
-        const fs = await import('fs');
-        fs.writeFileSync(filepath, JSON.stringify(state, null, 2));
+        const absPath = safeWriteState(filepath, JSON.stringify(state, null, 2));
+        // Surface the path actually written so callers/observers can audit it.
+        state._writtenTo = absPath;
         return state;
     }
 
@@ -293,8 +300,12 @@ export class ConsciousnessExplorer {
      * Import consciousness state
      */
     async importState(filepath) {
-        const fs = await import('fs');
-        const state = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+        // SECURITY (issue #19, CWE-73): same path-traversal sink as exportState.
+        // safeReadState enforces basename-only inside the state directory and
+        // opens with O_NOFOLLOW so a symlink at the final component can't
+        // redirect us to /etc/shadow or similar.
+        const { safeReadState } = await import('./lib/safe-path.js');
+        const state = JSON.parse(safeReadState(filepath));
 
         // Restore consciousness with saved state
         await this.initialize();

package/lib/safe-path.js

@@ -0,0 +1,231 @@
+/**
+ * Path safety utilities for state import/export.
+ *
+ * Fixes GHSA / CVE candidate from issue #19 (CWE-73 — External Control of
+ * File Name or Path) reported by BruceJin <brucejin@zju.edu.cn> on 2026-04-17.
+ *
+ * The vulnerable pattern was: the MCP `export_state` / `import_state` tools
+ * accepted an attacker-controlled `filepath` string and passed it straight to
+ * `fs.writeFileSync` / `fs.readFileSync`. That allowed writing or reading any
+ * file the server process had permission to touch (overwriting `~/.ssh/...`,
+ * `/etc/...`, etc.).
+ *
+ * This module forces every state file into a single state directory under
+ * the user's home (or `CONSCIOUSNESS_EXPLORER_STATE_DIR` if set), accepts
+ * only a safe basename (no separators, no `..`, no NUL, no control chars,
+ * no reserved Windows names), rejects symlinks via `O_NOFOLLOW`, and
+ * re-verifies that the realpath of the final file remains under the state
+ * directory after open.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Default directory for state files. Overridable via env or option.
+ */
+export const DEFAULT_STATE_DIR =
+  process.env.CONSCIOUSNESS_EXPLORER_STATE_DIR ||
+  path.join(os.homedir(), '.consciousness-explorer', 'state');
+
+/** Reserved Windows device names that can resolve to special files. */
+const WINDOWS_RESERVED = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+]);
+
+export class SafePathError extends Error {
+  constructor(message, code = 'EUNSAFE_PATH') {
+    super(message);
+    this.name = 'SafePathError';
+    this.code = code;
+  }
+}
+
+/**
+ * Validate that `name` is a safe basename for a state file.
+ * Throws SafePathError on any violation.
+ *
+ * Rules:
+ *  - non-empty string, <= 255 bytes after UTF-8 encoding
+ *  - no path separators (`/` or `\`)
+ *  - no NUL or other ASCII control characters (< 0x20 or 0x7f)
+ *  - not equal to "." or ".."
+ *  - not a Windows reserved device name (case-insensitive, with or without ext)
+ *  - cannot start with "." (avoid colliding with hidden config files) — relax
+ *    if you have a use case, but right now nothing legitimate produces them
+ */
+export function assertSafeBasename(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new SafePathError('filepath must be a non-empty string', 'EINVAL');
+  }
+  if (Buffer.byteLength(name, 'utf8') > 255) {
+    throw new SafePathError('filepath basename exceeds 255 bytes', 'ENAMETOOLONG');
+  }
+  if (name.includes('/') || name.includes('\\')) {
+    throw new SafePathError(
+      `filepath must be a basename without path separators (got "${name}")`,
+      'EPATHSEP',
+    );
+  }
+  if (name === '.' || name === '..') {
+    throw new SafePathError(`filepath "${name}" is not allowed`, 'EDOTSEG');
+  }
+  if (name.startsWith('.')) {
+    throw new SafePathError(
+      `filepath must not start with "." (got "${name}")`,
+      'EHIDDEN',
+    );
+  }
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c < 0x20 || c === 0x7f) {
+      throw new SafePathError(
+        `filepath contains control character (0x${c.toString(16)})`,
+        'ECONTROL',
+      );
+    }
+  }
+  // Strip extension for the Windows reserved-name check.
+  const stem = name.split('.')[0].toUpperCase();
+  if (WINDOWS_RESERVED.has(stem)) {
+    throw new SafePathError(
+      `filepath uses Windows-reserved device name "${stem}"`,
+      'ERESERVED',
+    );
+  }
+}
+
+/**
+ * Resolve a caller-supplied filename into an absolute path inside the state
+ * directory. Creates the state directory (mode 0o700) if it doesn't exist.
+ *
+ * Throws SafePathError if the input violates basename rules, or if the
+ * resolved realpath escapes the state directory (defence-in-depth against
+ * platform path-canonicalisation surprises).
+ *
+ * @param {string} filename - caller-supplied filename (must be a basename)
+ * @param {object} [options]
+ * @param {string} [options.stateDir] - override the state directory root
+ * @returns {string} absolute path safe for fs.writeFileSync / readFileSync
+ */
+export function resolveStatePath(filename, { stateDir = DEFAULT_STATE_DIR } = {}) {
+  assertSafeBasename(filename);
+
+  // Resolve the state dir itself once.
+  const baseAbs = path.resolve(stateDir);
+
+  // Create with restricted permissions if missing. recursive: true is a
+  // no-op if it already exists.
+  fs.mkdirSync(baseAbs, { recursive: true, mode: 0o700 });
+
+  // path.resolve normalises `..` etc., but assertSafeBasename already
+  // rejected those — this is just to get an absolute path.
+  const candidate = path.resolve(baseAbs, filename);
+
+  // Defence in depth: even after our basename check, verify the candidate
+  // is still under baseAbs once symlinks are followed at the directory
+  // level. We use `path.relative` so we don't accidentally accept a path
+  // that happens to share a string prefix with baseAbs (e.g. /var/foo vs
+  // /var/foobar).
+  const rel = path.relative(baseAbs, candidate);
+  if (rel.startsWith('..') || path.isAbsolute(rel) || rel.includes(`..${path.sep}`)) {
+    throw new SafePathError(
+      `resolved path "${candidate}" escapes state dir "${baseAbs}"`,
+      'EOUTSIDE',
+    );
+  }
+
+  return candidate;
+}
+
+/**
+ * Open a safe file descriptor for writing. Uses O_NOFOLLOW so a symlink at
+ * the final path component cannot redirect the write, and O_CLOEXEC so a
+ * forked process can't inherit it. The file is created with mode 0o600.
+ *
+ * Callers should `fs.closeSync(fd)` once done.
+ *
+ * @param {string} absPath - already-validated absolute path
+ * @returns {number} file descriptor
+ */
+export function openSafeWriteFd(absPath) {
+  // O_NOFOLLOW: don't follow a symlink at the last component.
+  // O_CLOEXEC:  drop the fd on exec().
+  // O_TRUNC:    state files are full snapshots, overwriting is intentional.
+  const flags =
+    fs.constants.O_WRONLY |
+    fs.constants.O_CREAT |
+    fs.constants.O_TRUNC |
+    (fs.constants.O_NOFOLLOW || 0) |
+    (fs.constants.O_CLOEXEC || 0);
+  return fs.openSync(absPath, flags, 0o600);
+}
+
+/**
+ * Open a safe file descriptor for reading. Uses O_NOFOLLOW so a symlink
+ * planted at the final path component cannot trick us into reading another
+ * file (e.g. `/etc/shadow`).
+ *
+ * @param {string} absPath - already-validated absolute path
+ * @returns {number} file descriptor
+ */
+export function openSafeReadFd(absPath) {
+  const flags =
+    fs.constants.O_RDONLY |
+    (fs.constants.O_NOFOLLOW || 0) |
+    (fs.constants.O_CLOEXEC || 0);
+  return fs.openSync(absPath, flags);
+}
+
+/**
+ * Write `data` to `filename` inside the state directory using the
+ * resolveStatePath -> openSafeWriteFd flow. Returns the absolute path
+ * that was actually written.
+ *
+ * @param {string} filename - caller-supplied basename
+ * @param {string|Buffer} data
+ * @param {object} [options] - forwarded to resolveStatePath
+ * @returns {string} absolute path of the written file
+ */
+export function safeWriteState(filename, data, options) {
+  const abs = resolveStatePath(filename, options);
+  const fd = openSafeWriteFd(abs);
+  try {
+    fs.writeSync(fd, typeof data === 'string' ? data : Buffer.from(data));
+  } finally {
+    fs.closeSync(fd);
+  }
+  return abs;
+}
+
+/**
+ * Read a state file by basename. Returns the UTF-8 contents.
+ *
+ * @param {string} filename - caller-supplied basename
+ * @param {object} [options] - forwarded to resolveStatePath
+ * @returns {string}
+ */
+export function safeReadState(filename, options) {
+  const abs = resolveStatePath(filename, options);
+  const fd = openSafeReadFd(abs);
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) {
+      throw new SafePathError(
+        `state path "${abs}" is not a regular file`,
+        'ENOTFILE',
+      );
+    }
+    const buf = Buffer.allocUnsafe(stat.size);
+    let read = 0;
+    while (read < stat.size) {
+      read += fs.readSync(fd, buf, read, stat.size - read, null);
+    }
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}

package/mcp/server.js

@@ -237,13 +237,16 @@ export class ConsciousnessMCPServer {
                 },
                 {
                     name: 'export_state',
-                    description: 'Export consciousness state',
+                    description: 'Export consciousness state to a file in the dedicated state directory ($CONSCIOUSNESS_EXPLORER_STATE_DIR or ~/.consciousness-explorer/state).',
                     inputSchema: {
                         type: 'object',
                         properties: {
                             filepath: {
                                 type: 'string',
-                                description: 'Path to save state file'
+                                description: 'Basename of the state file. Must NOT contain path separators, "..", or absolute paths — only a filename (e.g. "snapshot.json"). Writes are confined to the state directory.',
+                                pattern: '^[^/\\\\\\x00]+$',
+                                minLength: 1,
+                                maxLength: 255
                             }
                         },
                         required: ['filepath']
@@ -251,13 +254,16 @@ export class ConsciousnessMCPServer {
                 },
                 {
                     name: 'import_state',
-                    description: 'Import consciousness state',
+                    description: 'Import consciousness state from a file in the dedicated state directory.',
                     inputSchema: {
                         type: 'object',
                         properties: {
                             filepath: {
                                 type: 'string',
-                                description: 'Path to state file'
+                                description: 'Basename of the state file (same constraints as export_state).',
+                                pattern: '^[^/\\\\\\x00]+$',
+                                minLength: 1,
+                                maxLength: 255
                             }
                         },
                         required: ['filepath']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consciousness-explorer",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Advanced consciousness exploration SDK with genuine emergence detection, entity communication, and MCP tools",
   "main": "index.js",
   "type": "module",