@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/work-context/state.js

@@ -3,9 +3,10 @@
  * Written only by hq mesh context. Owner 0600. Metadata-only — never prompts/tokens.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
-import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
-import { NotTrackingError } from "./errors.js";
+import { atomicWriteJson, ensureOwnerDir, resolveRealTarget } from "./atomic.js";
+import { NotTrackingError, UnsafeConfigPathError } from "./errors.js";
 import { isSafeWorkContextSegment, workContextSessionPath, workContextSessionsDir, } from "./paths.js";
 /** Allowlisted keys that may appear in the durable state projection. */
 export const SESSION_STATE_ALLOWLIST = new Set([
@@ -30,6 +31,113 @@ export const SESSION_STATE_ALLOWLIST = new Set([
     "companyConfidence",
     "updatedAt",
 ]);
+const SESSION_STATE_LOCK_TIMEOUT_MS = 5_000;
+const SESSION_STATE_LOCK_RETRY_MS = 10;
+function waitForSessionStateLock(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function asPersistenceFailure(err) {
+    if (err instanceof NotTrackingError || err instanceof UnsafeConfigPathError)
+        throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new NotTrackingError(`Failed to persist session state: ${message}`, "NOT_TRACKING");
+}
+function reclaimStaleSessionStateLock(lockPath) {
+    const claim = `${lockPath}.reclaim.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+    try {
+        fs.renameSync(lockPath, claim);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    try {
+        return true;
+    }
+    finally {
+        try {
+            fs.unlinkSync(claim);
+        }
+        catch { /* private claim cannot block writers */ }
+    }
+}
+/**
+ * Serialize a session-state read/modify/write with every state writer. Atomic
+ * rename protects readers from torn files, but only this shared lock protects
+ * a writer that has to verify the current binding before changing it.
+ */
+export function withSessionStateLock(sessionId, root, fn) {
+    if (!isSafeWorkContextSegment(sessionId)) {
+        throw new NotTrackingError(`Unsafe session id for state file: ${sessionId}`, "NOT_TRACKING");
+    }
+    try {
+        ensureOwnerDir(workContextSessionsDir(root));
+    }
+    catch (err) {
+        asPersistenceFailure(err);
+    }
+    const statePath = resolveRealTarget(workContextSessionPath(sessionId, root));
+    const lockPath = `${statePath}.lock`;
+    const token = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+    const deadline = Date.now() + SESSION_STATE_LOCK_TIMEOUT_MS;
+    let fd;
+    while (fd === undefined) {
+        try {
+            fd = fs.openSync(lockPath, "wx", 0o600);
+            fs.writeSync(fd, JSON.stringify({ pid: process.pid, token }));
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                asPersistenceFailure(err);
+            let ownerPid = 0;
+            try {
+                const raw = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+                ownerPid = typeof raw.pid === "number" && Number.isInteger(raw.pid) ? raw.pid : 0;
+            }
+            catch {
+                // A malformed lock cannot safely protect the state.
+            }
+            let ownerAlive = false;
+            if (ownerPid > 0) {
+                try {
+                    process.kill(ownerPid, 0);
+                    ownerAlive = true;
+                }
+                catch {
+                    // Dead owners do not retain the lock.
+                }
+            }
+            if (!ownerAlive) {
+                try {
+                    reclaimStaleSessionStateLock(lockPath);
+                }
+                catch (err) {
+                    asPersistenceFailure(err);
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new NotTrackingError(`Timed out waiting for session state lock: ${path.basename(statePath)}`, "NOT_TRACKING");
+            }
+            waitForSessionStateLock(SESSION_STATE_LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.closeSync(fd);
+        try {
+            const current = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+            if (current.token === token)
+                fs.unlinkSync(lockPath);
+        }
+        catch {
+            // A stale-lock reclaimer or replacement owner has already retired it.
+        }
+    }
+}
 export function readSessionState(sessionId, root) {
     if (!isSafeWorkContextSegment(sessionId))
         return null;
@@ -50,6 +158,9 @@ export function writeSessionState(state, root) {
     if (!isSafeWorkContextSegment(state.sessionId)) {
         throw new NotTrackingError(`Unsafe session id for state file: ${state.sessionId}`, "NOT_TRACKING");
     }
+    return withSessionStateLock(state.sessionId, root, () => writeSessionStateUnlocked(state, root));
+}
+function writeSessionStateUnlocked(state, root) {
     const projected = projectSessionState(state);
     try {
         ensureOwnerDir(workContextSessionsDir(root));
@@ -61,6 +172,20 @@ export function writeSessionState(state, root) {
         throw new NotTrackingError(`Failed to persist session state: ${err instanceof Error ? err.message : String(err)}`, "NOT_TRACKING");
     }
 }
+/**
+ * Commit a state change only after inspecting the latest value under the same
+ * lock used by ordinary session writers. Returning null declines the write.
+ */
+export function updateSessionState(sessionId, root, update) {
+    return withSessionStateLock(sessionId, root, () => {
+        const current = readSessionState(sessionId, root);
+        const next = update(current);
+        if (!next)
+            return null;
+        writeSessionStateUnlocked(next, root);
+        return next;
+    });
+}
 /** Strip any non-allowlisted fields before durable write. */
 export function projectSessionState(state) {
     const out = {
@@ -118,7 +243,10 @@ export function mergeLocalSessionFields(next, prior, options = {}) {
     // projected locally; losing it causes held events and repeat registrations.
     // A caller that carries either company field is intentionally changing the
     // binding and remains authoritative.
-    if (!out.companyUid && !out.companySlug && (prior.companyUid || prior.companySlug)) {
+    if (options.preserveCompanyBinding !== false &&
+        !out.companyUid &&
+        !out.companySlug &&
+        (prior.companyUid || prior.companySlug)) {
         out.companyUid = prior.companyUid;
         out.companySlug = prior.companySlug;
         out.contextStatus = prior.contextStatus;

package/dist/lib/work-context/windows-acl.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Windows DACL check for the work-context config (US-018).
+ *
+ * NTFS has no POSIX mode bits: Node reports `mode` 0666 for every regular
+ * file on win32, so the POSIX `mode & 0o022` test in config.ts can never pass
+ * there. Instead of skipping the check on Windows, this module reads the real
+ * DACL and refuses the config when any principal other than the current user,
+ * SYSTEM, Administrators, or the owner is granted write/modify/full access.
+ *
+ * How the DACL is read (no native dependency):
+ *   `icacls <path> /save <tmpfile>` writes the DACL as an SDDL string
+ *   (`D:AI(A;ID;FA;;;SY)(A;ID;FA;;;BA)(A;ID;FA;;;S-1-5-21-...)`). SDDL carries
+ *   SIDs or well-known SID abbreviations, never display names, so the check is
+ *   independent of the OS language (VORDEFINIERT\Administratoren is still BA /
+ *   S-1-5-32-544). The current user's SID comes from `whoami /user`. Display
+ *   names are only resolved (via PowerShell) for the error message.
+ *
+ * Trust is decided by SID: S-1-5-18 (SYSTEM), S-1-5-32-544 (Administrators),
+ * S-1-3-0 (CREATOR OWNER), S-1-3-4 (OWNER RIGHTS), the current user's SID and
+ * the owner's SID when known.
+ *
+ * Reduced-guarantee path (explicit, documented): the check does NOT throw and
+ * instead emits one stderr diagnostic that the config is unprotected on this
+ * platform when, and only when, the DACL cannot be evaluated:
+ *   - icacls is missing, fails, or its output has no SDDL line (unreadable);
+ *   - an ACE grants write to a principal whose SID we cannot resolve (an SDDL
+ *     abbreviation this module does not know), or carries a rights token we
+ *     cannot decode, or the current user's SID is unknown and the grant is to
+ *     a non-well-known SID (unresolvable).
+ * A DACL that parses and grants write to a resolved SID outside the trusted
+ * set always throws UnsafeConfigPathError. Nothing else falls back.
+ */
+export interface SddlAce {
+    /** ACE type token, e.g. `A` (allow) or `D` (deny). */
+    type: string;
+    /** ACE flag string, e.g. `OICIID`. */
+    flags: string;
+    /** Rights field as written, e.g. `FA`, `0x1200a9`, `CCDCLCSWRPWPRC`. */
+    rights: string;
+    /** Account field as written: full SID or two-letter abbreviation. */
+    account: string;
+}
+export type AclReadResult = {
+    readable: true;
+    sddl: string;
+} | {
+    readable: false;
+    reason: string;
+};
+export interface WindowsAclCheckOptions {
+    /** Current user SID (defaults to `whoami /user`). `null` = unknown. */
+    currentUserSid?: string | null;
+    /** Owner SID when known (icacls /save does not include the owner). */
+    ownerSid?: string | null;
+    /** DACL reader; injectable for tests. Defaults to `icacls <path> /save`. */
+    readAcl?: (targetPath: string) => AclReadResult;
+    /** SID → display name for error messages; injectable for tests. */
+    resolveSidName?: (sid: string) => string | null;
+    /** Diagnostic sink for the reduced-guarantee path (defaults to stderr). */
+    diagnostic?: (line: string) => void;
+}
+export type AclVerdict = {
+    kind: "safe";
+} | {
+    kind: "unsafe";
+    sid: string;
+    rights: string;
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+export declare const SID_SYSTEM = "S-1-5-18";
+export declare const SID_ADMINISTRATORS = "S-1-5-32-544";
+export declare const SID_CREATOR_OWNER = "S-1-3-0";
+export declare const SID_OWNER_RIGHTS = "S-1-3-4";
+/** Resolve an SDDL account field to a SID, or null when unknown. */
+export declare function sddlAccountToSid(account: string): string | null;
+/** Any of these bits lets the holder change the file or replace it. */
+export declare const WRITE_MASK: number;
+/** Decode an SDDL rights field to an access mask, or null when undecodable. */
+export declare function sddlRightsToMask(rights: string): number | null;
+/**
+ * Parse the DACL portion of an SDDL string into ACEs. Accepts a full security
+ * descriptor string (`O:...G:...D:...S:...`) or just the `D:` section.
+ * Returns null when no DACL section is present or an ACE is malformed.
+ */
+export declare function parseSddlDacl(sddl: string): SddlAce[] | null;
+/**
+ * Parse the file `icacls <path> /save <file>` writes: UTF-16LE (optional BOM),
+ * CRLF, alternating `<name>` / `<sddl>` lines. Returns the SDDL of the first
+ * entry (the target itself), or an unreadable result.
+ */
+export declare function parseIcaclsSaveOutput(raw: string | Buffer): AclReadResult;
+/**
+ * Absolute path of a System32 tool. PATH lookup is not safe here: Git Bash and
+ * MSYS environments put a coreutils `whoami` ahead of Windows' `whoami.exe`,
+ * which does not understand `/user` and would make the current user SID look
+ * unknown on every run.
+ */
+export declare function system32Tool(exe: string): string;
+export declare function readAclWithIcaclsSave(targetPath: string): AclReadResult;
+/** Current user's SID via `whoami /user /fo csv /nh`; null when unavailable. */
+export declare function readCurrentUserSid(): string | null;
+/** Best-effort SID → account name (only used to build error messages). */
+export declare function resolveSidNameWithPowerShell(sid: string): string | null;
+/**
+ * Evaluate parsed ACEs against the trusted SID set.
+ * - `unsafe`: an allow ACE grants a write bit to a resolved, untrusted SID.
+ * - `unresolvable`: a write-granting ACE whose SID or rights cannot be decoded,
+ *   or whose SID is a per-machine/domain SID while the current user is unknown.
+ * - `safe`: everything else (deny ACEs and read-only grants are ignored).
+ */
+export declare function evaluateDacl(aces: SddlAce[], opts: Pick<WindowsAclCheckOptions, "currentUserSid" | "ownerSid">): AclVerdict;
+/**
+ * Assert the Windows DACL of `targetPath` grants write only to trusted
+ * principals. Throws UnsafeConfigPathError naming the offending principal.
+ * Unreadable or unresolvable DACL → reduced-guarantee diagnostic (once per
+ * path), no throw. See the module header for the exact conditions.
+ */
+export declare function assertWindowsOwnerOnlyAcl(targetPath: string, kind: "file" | "directory", opts?: WindowsAclCheckOptions): void;
+/** Test hook: forget which paths already emitted the reduced-guarantee line. */
+export declare function resetWindowsAclDiagnostics(): void;
+//# sourceMappingURL=windows-acl.d.ts.map