@logicseek/hello-cc 1.0.5 → 1.1.0-rc.3

package/lib/runtime/project-path.mjs

@@ -2,12 +2,31 @@ 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);
   return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
 
+function canonicalCandidateFromExistingParent(candidate) {
+  let parent = path.dirname(candidate);
+  const missing = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(parent), ...missing.reverse(), path.basename(candidate));
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return null;
+      const next = path.dirname(parent);
+      if (next === parent) return null;
+      missing.push(path.basename(parent));
+      parent = next;
+    }
+  }
+}
+
 function projectPathForbidden(message) {
   return new CliError('PROJECT_PATH_FORBIDDEN', message);
 }
@@ -23,7 +42,7 @@ function canonicalProjectRoot(root) {
   }
 }
 
-function privateDirectory(directory, description) {
+function privateDirectory(directory, description, { tighten = true } = {}) {
   let stat;
   try { stat = fs.lstatSync(directory); }
   catch { throw projectPathForbidden(`Cannot inspect ${description}: ${directory}`); }
@@ -37,11 +56,15 @@ function privateDirectory(directory, description) {
     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) {
+    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) {
-      fs.fchmodSync(fd, 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) {
@@ -57,7 +80,47 @@ function privateDirectory(directory, description) {
 }
 
 function ensureStateDirectory(root, createStateDir, secureExisting = createStateDir) {
-  const stateDir = path.join(root, '.hello-cc');
+  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);
@@ -79,9 +142,7 @@ function ensureStateDirectory(root, createStateDir, secureExisting = createState
     throw projectPathForbidden(`Project state directory must be a real directory: ${stateDir}`);
   }
   try {
-    const canonical = secureExisting
-      ? privateDirectory(stateDir, 'Project state directory')
-      : 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}`);
     }
@@ -121,7 +182,7 @@ function validateDatabaseParent(stateDir, db, createParents = false) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
       throw projectPathForbidden(`Database parent must contain only real directories: ${current}`);
     }
-    if (createParents && privateDirectory(current, 'Database parent directory') !== current) {
+    if (privateDirectory(current, 'Database parent directory', { tighten: createParents }) !== current) {
       throw projectPathForbidden(`Database parent directory changed: ${current}`);
     }
   }
@@ -164,16 +225,23 @@ export function resolveProjectDatabase({ root, db, createStateDir = false, creat
   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));
-      const canonicalCandidate = path.join(canonicalParent, path.basename(requestedDb));
-      if (pathIsWithin(intendedStateDir, canonicalCandidate)) requestedDb = canonicalCandidate;
-    } catch {}
+    // An explicit --db may be spelled through an alias of an ancestor such as
+    // macOS /var -> /private/var, and its nested DB parents may not exist yet.
+    // Canonicalize the nearest existing parent before containment checking;
+    // validateDatabaseParent still rejects any newly created symlink segment.
+    const canonicalCandidate = canonicalCandidateFromExistingParent(requestedDb);
+    if (canonicalCandidate && pathIsWithin(intendedStateDir, canonicalCandidate)) {
+      requestedDb = canonicalCandidate;
+    }
   }
   if (!pathIsWithin(intendedStateDir, requestedDb)) {
     throw projectPathForbidden(`Database path must live under ${intendedStateDir}`);
@@ -191,13 +259,13 @@ export function resolveProjectDatabase({ root, db, createStateDir = false, creat
   };
 }
 
-export function ensurePrivateProjectBufferDirectory(root, directoryName = 'bufs', { create = true } = {}) {
+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, true);
+  const state = ensureStateDirectory(canonicalRoot, create, create);
   if (!state.exists) return null;
   const { stateDir } = state;
   const directory = path.join(stateDir, directoryName);
@@ -215,8 +283,12 @@ export function ensurePrivateProjectBufferDirectory(root, directoryName = 'bufs'
       throw projectPathForbidden(`Cannot inspect buffer directory: ${directory}`);
     }
   }
-  if (privateDirectory(directory, '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,8 +1,9 @@
 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';
+import { assertSelectedCwdSnapshot } from '../process/selected-cwd-identity.mjs';
 
 const ROOT_EXISTS = Symbol('projectRootExists');
 const ROOT_WAS_CANONICAL = Symbol('projectRootWasCanonical');
@@ -101,9 +102,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 +149,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;
@@ -302,6 +306,7 @@ function updateProjectRegistry(candidate, lockOptions = {}) {
 }
 
 export function registerProject(ctx, lockOptions = {}) {
+  if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
   const candidate = projectRecord(ctx);
   if (!candidate) throw new TypeError('project root is required');
   // xx-01: the throttle check lives inside the lock (canonical-domain safe, see
@@ -311,6 +316,7 @@ export function registerProject(ctx, lockOptions = {}) {
 }
 
 export function registerProjectActivity(ctx) {
+  if (ctx.initialRootIdentity) assertSelectedCwdSnapshot(ctx.initialRootIdentity);
   try {
     const wallTimestamp = Date.now();
     const candidate = projectRecord(ctx, () => Math.floor(wallTimestamp / 1000));