@logicseek/hello-cc 1.0.2 → 1.1.0-rc.1

package/lib/runtime/project-path.mjs

@@ -1,6 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import process from 'node:process';
 import { CliError } from '../shared/errors.mjs';
+import { projectStateDir, legacyProjectStateDir } from './paths.mjs';
+import { ensurePrivateProjectStateDir, inspectPrivateProjectAuthority } from './private-state.mjs';
+import { unsafeDirectoryAcl } from './project-trust.mjs';
 
 function pathIsWithin(parent, candidate) {
   const relative = path.relative(parent, candidate);
@@ -22,8 +26,85 @@ function canonicalProjectRoot(root) {
   }
 }
 
-function ensureStateDirectory(root, createStateDir) {
-  const stateDir = path.join(root, '.hello-cc');
+function privateDirectory(directory, description, { tighten = true } = {}) {
+  let stat;
+  try { stat = fs.lstatSync(directory); }
+  catch { throw projectPathForbidden(`Cannot inspect ${description}: ${directory}`); }
+  if (stat.isSymbolicLink() || !stat.isDirectory() ||
+      (typeof process.getuid === 'function' && stat.uid !== process.getuid())) {
+    throw projectPathForbidden(`${description} must be an owned real directory: ${directory}`);
+  }
+
+  let fd;
+  try {
+    fd = fs.openSync(directory, fs.constants.O_RDONLY |
+      (fs.constants.O_DIRECTORY || 0) | (fs.constants.O_NOFOLLOW || 0));
+    const opened = fs.fstatSync(fd);
+    if (!opened.isDirectory() || opened.dev !== stat.dev || opened.ino !== stat.ino ||
+        unsafeDirectoryAcl(directory, opened)) {
+      throw projectPathForbidden(`${description} changed during validation: ${directory}`);
+    }
+    if (process.platform !== 'win32' && (opened.mode & 0o777) !== 0o700) {
+      if (tighten) fs.fchmodSync(fd, 0o700);
+      else if ((opened.mode & 0o022) !== 0) {
+        throw projectPathForbidden(`${description} is writable by another user: ${directory}`);
+      }
+    }
+    const current = fs.lstatSync(directory);
+    if (current.isSymbolicLink() || current.dev !== stat.dev || current.ino !== stat.ino) {
+      throw projectPathForbidden(`${description} changed during validation: ${directory}`);
+    }
+    return fs.realpathSync(directory);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw projectPathForbidden(`Cannot secure ${description}: ${directory}`);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function ensureStateDirectory(root, createStateDir, secureExisting = createStateDir) {
+  const stateDir = projectStateDir(root);
+  if (stateDir !== legacyProjectStateDir(root)) {
+    const authority = inspectPrivateProjectAuthority(root);
+    let privateEntryExists = false;
+    try { fs.lstatSync(stateDir); privateEntryExists = true; }
+    catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw projectPathForbidden(`Cannot inspect private project state: ${stateDir}`);
+      }
+    }
+    // A crash can leave a pending marker with an empty directory or a valid
+    // manifest not yet promoted to fresh. Older private stores may have no
+    // sibling marker. Finish either binding before returning any existing
+    // state, including during a read-only request.
+    const finishBinding = privateEntryExists &&
+      (authority === null || authority === 'pending');
+    const existing = ensurePrivateProjectStateDir(root, { create: finishBinding });
+    if (existing) return { stateDir, exists: true };
+    if (authority === 'fresh' || authority === 'migrated') {
+      throw new CliError('STATE_AUTHORITY_MISSING',
+        `Previously established private project state is missing: ${stateDir}. Restore it from backup; ` +
+        'if the legacy source still exists, stop all old writers and run ' +
+        'hcc --root DIR migrate-state --offline --yes; otherwise run ' +
+        'hcc --root DIR uninstall --purge --yes to explicitly reset the missing state.');
+    }
+    const legacy = legacyProjectStateDir(root);
+    let legacyStat = null;
+    try { legacyStat = fs.lstatSync(legacy); }
+    catch (error) {
+      if (error?.code !== 'ENOENT') throw projectPathForbidden(`Cannot inspect legacy project state: ${legacy}`);
+    }
+    if (legacyStat && (legacyStat.isSymbolicLink() || !legacyStat.isDirectory())) {
+      throw projectPathForbidden(`Legacy project state is not a real directory: ${legacy}`);
+    }
+    if (legacyStat) {
+      throw new CliError('STATE_MIGRATION_REQUIRED',
+        `Legacy project state requires an offline migration before use: ${legacy}`);
+    }
+    const secured = createStateDir ? ensurePrivateProjectStateDir(root, { create: true }) : null;
+    return { stateDir, exists: Boolean(secured) };
+  }
   let stateStat;
   try {
     stateStat = fs.lstatSync(stateDir);
@@ -35,8 +116,9 @@ function ensureStateDirectory(root, createStateDir) {
     try {
       fs.mkdirSync(stateDir, { mode: 0o700 });
       stateStat = fs.lstatSync(stateDir);
-    } catch {
-      throw projectPathForbidden(`Cannot create project state directory: ${stateDir}`);
+    } catch (error) {
+      if (error?.code === 'EEXIST') stateStat = fs.lstatSync(stateDir);
+      else throw projectPathForbidden(`Cannot create project state directory: ${stateDir}`);
     }
   }
 
@@ -44,7 +126,7 @@ function ensureStateDirectory(root, createStateDir) {
     throw projectPathForbidden(`Project state directory must be a real directory: ${stateDir}`);
   }
   try {
-    const canonical = fs.realpathSync(stateDir);
+    const canonical = privateDirectory(stateDir, 'Project state directory', { tighten: secureExisting });
     if (canonical !== stateDir || !pathIsWithin(root, canonical)) {
       throw projectPathForbidden(`Project state directory escapes its project root: ${stateDir}`);
     }
@@ -55,13 +137,26 @@ function ensureStateDirectory(root, createStateDir) {
   }
 }
 
-function validateDatabaseParent(stateDir, db) {
+export function secureExistingProjectStateDirectory(root) {
+  const canonicalRoot = canonicalProjectRoot(root);
+  return ensureStateDirectory(canonicalRoot, false, true);
+}
+
+function validateDatabaseParent(stateDir, db, createParents = false) {
   const parent = path.dirname(db);
   const relative = path.relative(stateDir, parent);
   const segments = relative === '' ? [] : relative.split(path.sep);
   let current = stateDir;
   for (const segment of segments) {
     current = path.join(current, segment);
+    if (createParents) {
+      try { fs.mkdirSync(current, { mode: 0o700 }); }
+      catch (error) {
+        if (error?.code !== 'EEXIST') {
+          throw projectPathForbidden(`Cannot create database parent directory: ${current}`);
+        }
+      }
+    }
     let stat;
     try {
       stat = fs.lstatSync(current);
@@ -71,6 +166,9 @@ function validateDatabaseParent(stateDir, db) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
       throw projectPathForbidden(`Database parent must contain only real directories: ${current}`);
     }
+    if (privateDirectory(current, 'Database parent directory', { tighten: createParents }) !== current) {
+      throw projectPathForbidden(`Database parent directory changed: ${current}`);
+    }
   }
 
   try {
@@ -107,14 +205,18 @@ function validateDatabaseTarget(stateDir, db) {
   }
 }
 
-export function resolveProjectDatabase({ root, db, createStateDir = false }) {
+export function resolveProjectDatabase({ root, db, createStateDir = false, createDatabaseParents = false }) {
   const requestedRoot = path.resolve(String(root || ''));
   const canonicalRoot = canonicalProjectRoot(requestedRoot);
   const rawDb = path.resolve(String(db || path.join(requestedRoot, '.hello-cc', 'mesh.db')));
-  let requestedDb = pathIsWithin(requestedRoot, rawDb)
-    ? path.join(canonicalRoot, path.relative(requestedRoot, rawDb))
-    : rawDb;
-  const intendedStateDir = path.join(canonicalRoot, '.hello-cc');
+  const intendedStateDir = projectStateDir(canonicalRoot);
+  const requestedLegacyState = legacyProjectStateDir(requestedRoot);
+  const canonicalLegacyState = legacyProjectStateDir(canonicalRoot);
+  let requestedDb = pathIsWithin(requestedLegacyState, rawDb)
+    ? path.join(intendedStateDir, path.relative(requestedLegacyState, rawDb))
+    : pathIsWithin(canonicalLegacyState, rawDb)
+      ? path.join(intendedStateDir, path.relative(canonicalLegacyState, rawDb))
+      : rawDb;
   if (!pathIsWithin(intendedStateDir, requestedDb)) {
     try {
       const canonicalParent = fs.realpathSync(path.dirname(requestedDb));
@@ -130,10 +232,44 @@ export function resolveProjectDatabase({ root, db, createStateDir = false }) {
     return { root: canonicalRoot, stateDir: state.stateDir, db: requestedDb };
   }
 
-  validateDatabaseParent(state.stateDir, requestedDb);
+  validateDatabaseParent(state.stateDir, requestedDb, Boolean(createDatabaseParents));
   return {
     root: canonicalRoot,
     stateDir: state.stateDir,
     db: validateDatabaseTarget(state.stateDir, requestedDb)
   };
 }
+
+export function ensurePrivateProjectStateSubdirectory(root, directoryName, { create = true } = {}) {
+  if (!directoryName || directoryName !== path.basename(directoryName) ||
+      directoryName === '.' || directoryName === '..') {
+    throw projectPathForbidden(`Invalid buffer directory name: ${directoryName}`);
+  }
+  const canonicalRoot = canonicalProjectRoot(root);
+  const state = ensureStateDirectory(canonicalRoot, create, create);
+  if (!state.exists) return null;
+  const { stateDir } = state;
+  const directory = path.join(stateDir, directoryName);
+  if (create) {
+    try { fs.mkdirSync(directory, { mode: 0o700 }); }
+    catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw projectPathForbidden(`Cannot create buffer directory: ${directory}`);
+      }
+    }
+  } else {
+    try { fs.lstatSync(directory); }
+    catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw projectPathForbidden(`Cannot inspect buffer directory: ${directory}`);
+    }
+  }
+  if (privateDirectory(directory, 'Project state subdirectory', { tighten: create }) !== directory) {
+    throw projectPathForbidden(`Buffer directory escapes project state directory: ${directory}`);
+  }
+  return directory;
+}
+
+export function ensurePrivateProjectBufferDirectory(root, directoryName = 'bufs', options = {}) {
+  return ensurePrivateProjectStateSubdirectory(root, directoryName, options);
+}

package/lib/runtime/project-trust.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+// A private .hello-cc is only safe behind a pathname that another UID cannot
+// rename. The ownership of the leaf alone is not sufficient: a writable
+// non-sticky ancestor lets another UID replace its directory entry.
+const aclCache = new Map();
+
+export function unsafeDirectoryAcl(directory, stat = null) {
+  let identity = stat;
+  try { identity ||= fs.lstatSync(directory); }
+  catch { return true; }
+  const signature = `${identity.dev}:${identity.ino}:${identity.ctimeNs ?? identity.ctimeMs}`;
+  const cached = aclCache.get(directory);
+  if (cached?.signature === signature) return cached.unsafe;
+  const ls = fs.existsSync('/bin/ls') ? '/bin/ls'
+    : fs.existsSync('/usr/bin/ls') ? '/usr/bin/ls' : null;
+  if (!ls) return true;
+  const result = spawnSync(ls, process.platform === 'darwin'
+    ? ['-lde', directory] : ['-ld', directory], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000,
+    env: { ...process.env, LC_ALL: 'C' }
+  });
+  if (result.status !== 0) return true;
+  const [first, ...entries] = result.stdout.trim().split('\n');
+  const permissions = first?.trim().split(/\s+/, 1)[0];
+  if (!/^[-dlcbps][rwxStTs-]{9}[+@.]?$/.test(permissions)) return true;
+  // A deny-only macOS ACL cannot grant another UID the ability to rebind a
+  // directory entry. Unknown or allow ACL entries use the private fallback.
+  const aclEntries = entries.filter((entry) => entry.trim().length > 0);
+  const unsafe = process.platform === 'darwin'
+    ? (aclEntries.length > 0
+        ? aclEntries.some((entry) => !/^\s*\d+:\s+.+\sdeny\s+/.test(entry))
+        : permissions[10] === '+')
+    : permissions[10] === '+';
+  if (aclCache.size >= 1024) aclCache.clear();
+  aclCache.set(directory, { signature, unsafe });
+  return unsafe;
+}
+
+export function stableProjectStateRoot(root) {
+  if (typeof process.getuid !== 'function') return null;
+  const uid = process.getuid();
+  let canonical;
+  try { canonical = fs.realpathSync.native(path.resolve(root)); }
+  catch { return null; }
+  const parts = [];
+  for (let current = canonical;; current = path.dirname(current)) {
+    parts.push(current);
+    if (path.dirname(current) === current) break;
+  }
+  parts.reverse();
+  let parent = null;
+  for (const component of parts) {
+    let stat;
+    try { stat = fs.lstatSync(component); }
+    catch { return null; }
+    if (!stat.isDirectory() || stat.isSymbolicLink() ||
+        (stat.uid !== uid && stat.uid !== 0) || unsafeDirectoryAcl(component, stat)) return null;
+    if (parent) {
+      const parentMode = parent.mode & 0o7777;
+      if ((parentMode & 0o022) !== 0 &&
+          ((parentMode & 0o1000) === 0 || (stat.uid !== uid && stat.uid !== 0))) {
+        return null;
+      }
+    }
+    parent = stat;
+  }
+  // A cross-UID-writable root can have its .hello-cc entry replaced. Keep its
+  // state under the user's private state directory even when root is sticky.
+  if ((parent.mode & 0o022) !== 0) return null;
+  // A stable but read-only server directory (for example /etc) cannot host a
+  // new project-local state directory. It remains selectable via private state.
+  try { fs.accessSync(canonical, fs.constants.W_OK | fs.constants.X_OK); }
+  catch { return null; }
+  return canonical;
+}

package/lib/runtime/projects.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { projectDbPath, projectRegistryPath } from './paths.mjs';
+import { projectDbPath, projectRegistryPath, projectStateDir } from './paths.mjs';
 import { withFileLock } from '../shared/file-lock.mjs';
 import { writeJsonSafe } from '../shared/json-file.mjs';
 
@@ -101,9 +101,12 @@ function canonicalProjectDb(value, rawRoot, rootInfo, { strict = false } = {}) {
   const db = pathWithin(rawRoot, rawDb)
     ? path.resolve(rootInfo.root, relativeToRawRoot)
     : rawDb;
+  const privateState = projectStateDir(rootInfo.root);
+  const allowed = (candidate) => pathWithin(rootInfo.root, candidate) ||
+    (privateState !== path.join(rootInfo.root, '.hello-cc') && pathWithin(privateState, candidate));
 
   if (!rootInfo.exists) {
-    return pathWithin(rootInfo.root, db)
+    return allowed(db)
       ? db
       : reject(`project DB is outside the project root: ${rawDb}`);
   }
@@ -145,7 +148,7 @@ function canonicalProjectDb(value, rawRoot, rootInfo, { strict = false } = {}) {
     const canonicalDb = dbExists
       ? canonicalAncestor
       : path.resolve(canonicalAncestor, path.relative(ancestor, db));
-    if (!pathWithin(rootInfo.root, canonicalDb)) {
+    if (!allowed(canonicalDb)) {
       return reject(`project DB is outside the project root: ${rawDb}`);
     }
     return canonicalDb;