@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/utils/machine-principal-state.js

@@ -0,0 +1,110 @@
+/**
+ * Local-state checks that decide machine vs person Cognito tokens. Reads env
+ * and files only; no network code, so fast native entries can import it
+ * (e.g. via src/lib/caller-principal.ts) without pulling cognito-session.ts.
+ */
+import * as os from "node:os";
+import * as fs from "node:fs";
+import { accessTokenFingerprint, isMachineIdentity } from "@indigoai-us/hq-cloud";
+import { personTokenCacheFile, readPersonTokenFile } from "./person-token-cache.js";
+/**
+ * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
+ * Explicit env remains the primary opt-in for daemon units. Fresh agent boxes
+ * without the env still mint via {@link wantsMachineCognitoTokens}'s
+ * default-file fallback when no usable person session exists.
+ */
+export function isMachineCredsFileEnvSet(env = process.env) {
+    const raw = env.HQ_MACHINE_CREDS_FILE;
+    return typeof raw === "string" && raw.trim().length > 0;
+}
+/**
+ * Align `process.env.HQ_MACHINE_CREDS_FILE` with a (possibly synthetic) `env`
+ * for the duration of `fn`, so hq-cloud's `isMachineIdentity()` sees the same
+ * value doctor / tests intended.
+ */
+function withAlignedMachineCredsEnv(env, fn) {
+    const prevCreds = process.env.HQ_MACHINE_CREDS_FILE;
+    const nextCreds = env.HQ_MACHINE_CREDS_FILE;
+    if (nextCreds !== prevCreds) {
+        if (nextCreds === undefined || String(nextCreds).trim() === "") {
+            delete process.env.HQ_MACHINE_CREDS_FILE;
+        }
+        else {
+            process.env.HQ_MACHINE_CREDS_FILE = nextCreds;
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (nextCreds !== prevCreds) {
+            if (prevCreds === undefined)
+                delete process.env.HQ_MACHINE_CREDS_FILE;
+            else
+                process.env.HQ_MACHINE_CREDS_FILE = prevCreds;
+        }
+    }
+}
+/**
+ * True when a usable person Cognito cache file exists under the effective
+ * `HQ_STATE_DIR` (or `~/.hq`). Presence alone keeps human commands on the
+ * person path even when the default machine-creds file is also on disk
+ * (no-flip guarantee).
+ */
+export function hasPersonCachedSession(env = process.env) {
+    try {
+        const file = personTokenCacheFile(os.homedir(), env);
+        const raw = readPersonTokenFile(os.homedir(), env);
+        if (!raw ||
+            typeof raw.accessToken !== "string" ||
+            raw.accessToken.length === 0 ||
+            typeof raw.idToken !== "string" ||
+            raw.idToken.length === 0) {
+            return false;
+        }
+        // Definitive refresh rejection writes `${file}.invalid.<fingerprint>`;
+        // treat that as no usable person session so status/whoami report machine.
+        const marker = `${file}.invalid.${accessTokenFingerprint(raw.accessToken)}`;
+        if (fs.existsSync(marker))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether hq-cloud currently sees readable machine creds (env override or
+ * default `~/.hq-agent/machine-creds.json`), honoring a synthetic `env`.
+ */
+export function probeMachineIdentity(env) {
+    return withAlignedMachineCredsEnv(env, () => isMachineIdentity());
+}
+/**
+ * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
+ *
+ * Machine path when:
+ *   - explicit `{ tokenSource: "machine" }` and creds are readable, or
+ *   - `HQ_MACHINE_CREDS_FILE` is set and readable, or
+ *   - fresh-box fallback: env unset, no person cache, default
+ *     `~/.hq-agent/machine-creds.json` readable.
+ *
+ * Explicit `{ tokenSource: "person" }` never uses machine creds. A present
+ * person cache keeps the person path even when the default creds file exists
+ * (do not flip a human's commands onto machine tokens).
+ */
+export function wantsMachineCognitoTokens(options = {}, env = process.env) {
+    if (options.tokenSource === "person")
+        return false;
+    if (options.tokenSource === "machine") {
+        return probeMachineIdentity(env);
+    }
+    if (isMachineCredsFileEnvSet(env)) {
+        return probeMachineIdentity(env);
+    }
+    // Fresh-box fallback — default creds file only when no person session.
+    if (hasPersonCachedSession(env))
+        return false;
+    return probeMachineIdentity(env);
+}
+//# sourceMappingURL=machine-principal-state.js.map

package/dist/utils/remote-list-not-converging.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plain-language rendering for hq-cloud's `RemoteListNotConvergingError`
+ * (code `REMOTE_LIST_NOT_CONVERGING`, hq-cloud >= 6.18.102). hq-cloud throws
+ * it when a company's vault file listing keeps stopping early (a repeated
+ * cursor, or a truncated page with no cursor) after its retries run out.
+ *
+ * Duck-typed on `code` so hq-cli stays compatible while hq-cloud and the CLI
+ * are released independently.
+ */
+export declare const REMOTE_LIST_NOT_CONVERGING_CODE = "REMOTE_LIST_NOT_CONVERGING";
+export declare const REMOTE_LIST_NOT_CONVERGING_HINT: string;
+export declare function isRemoteListNotConvergingError(err: unknown): boolean;
+/**
+ * Returns the user-facing message for a non-converging remote listing, with
+ * the original engine detail on a second line for bug reports, or null when
+ * `err` is some other failure.
+ */
+export declare function formatRemoteListNotConverging(err: unknown): string | null;
+/** Remote-list hint when it applies, else the raw error text. */
+export declare function describeSyncError(err: unknown): string;
+//# sourceMappingURL=remote-list-not-converging.d.ts.map

package/dist/utils/remote-list-not-converging.js

@@ -0,0 +1,40 @@
+/**
+ * Plain-language rendering for hq-cloud's `RemoteListNotConvergingError`
+ * (code `REMOTE_LIST_NOT_CONVERGING`, hq-cloud >= 6.18.102). hq-cloud throws
+ * it when a company's vault file listing keeps stopping early (a repeated
+ * cursor, or a truncated page with no cursor) after its retries run out.
+ *
+ * Duck-typed on `code` so hq-cli stays compatible while hq-cloud and the CLI
+ * are released independently.
+ */
+export const REMOTE_LIST_NOT_CONVERGING_CODE = "REMOTE_LIST_NOT_CONVERGING";
+export const REMOTE_LIST_NOT_CONVERGING_HINT = "HQ could not finish listing this company's files. Try hq sync now again in a minute; " +
+    "if it keeps happening, run hq feedback bug.";
+export function isRemoteListNotConvergingError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === REMOTE_LIST_NOT_CONVERGING_CODE);
+}
+/**
+ * Returns the user-facing message for a non-converging remote listing, with
+ * the original engine detail on a second line for bug reports, or null when
+ * `err` is some other failure.
+ */
+export function formatRemoteListNotConverging(err) {
+    if (!isRemoteListNotConvergingError(err))
+        return null;
+    const detail = err instanceof Error
+        ? err.message
+        : typeof err.message === "string"
+            ? err.message
+            : "";
+    return detail.length > 0
+        ? `${REMOTE_LIST_NOT_CONVERGING_HINT}\nDetail: ${detail}`
+        : REMOTE_LIST_NOT_CONVERGING_HINT;
+}
+/** Remote-list hint when it applies, else the raw error text. */
+export function describeSyncError(err) {
+    return (formatRemoteListNotConverging(err) ??
+        (err instanceof Error ? err.message : String(err)));
+}
+//# sourceMappingURL=remote-list-not-converging.js.map

package/dist/utils/safe-link.js

@@ -284,6 +284,9 @@ export function removeLinkOnly(linkPath) {
     if (!st.isSymbolicLink()) {
         throw new Error(`Refusing to remove ${linkPath}: it is not a link.`);
     }
+    // Re-check immediately before each removal call, so an entry swapped for a
+    // real file or folder after the first check is refused, not removed.
+    assertStillLink(linkPath);
     try {
         fs.unlinkSync(linkPath);
     }
@@ -293,8 +296,14 @@ export function removeLinkOnly(linkPath) {
         // unlink(). A non-recursive rmdir removes only the junction entry.
         if (code !== 'EPERM' && code !== 'EISDIR')
             throw err;
+        assertStillLink(linkPath);
         fs.rmdirSync(linkPath);
     }
     return true;
 }
+function assertStillLink(linkPath) {
+    if (!fs.lstatSync(linkPath).isSymbolicLink()) {
+        throw new Error(`Refusing to remove ${linkPath}: it is no longer a link.`);
+    }
+}
 //# sourceMappingURL=safe-link.js.map

package/dist/utils/script-bound-exec.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Bind a script-locked secret release to the process that is actually run
+ * (feedback_0e6abcb8).
+ *
+ * `--script <path>` sends the script's path and hash to the vault, which
+ * releases a script-locked secret when that pair is approved. Before this
+ * module the command after `--` was never compared with that script, so any
+ * command that named an approved script received the secret.
+ *
+ * When any requested secret is script-locked (or its lock state is unknown),
+ * the command after `--` must be one of:
+ *   1. the approved script itself: `-- ./approved.sh [args...]` (realpath
+ *      match). Its `#!` line is parsed and the interpreter it names goes
+ *      through the same allowlist; `#!/usr/bin/env X` resolves X against a
+ *      fixed system PATH, never the caller's PATH;
+ *   2. an allowlisted interpreter followed directly by the script:
+ *      `-- bash approved.sh [args...]`, also resolved against the fixed PATH.
+ * Anything else (wrappers such as env, xargs, sudo, a shell `-c` string, an
+ * interpreter option before the script) is refused and nothing is injected.
+ *
+ * Allowlisted interpreters: sh, dash, ksh, bash (run with --noprofile
+ * --norc), zsh (run with -f), python3/python (run with -I -S), node. Ruby and
+ * perl are not allowlisted. The interpreter's realpath and every parent
+ * directory must be owned by root and not group- or world-writable, so
+ * Homebrew or other user-writable installs are refused.
+ *
+ * At spawn time the script bytes are read once, hashed, compared with the hash
+ * sent to the vault, written to a fresh 0700 private directory, re-hashed, and
+ * that copy is passed to the interpreter. The original path is exposed to the
+ * script as HQ_APPROVED_SCRIPT and its directory as HQ_APPROVED_SCRIPT_DIR.
+ * `$0` / `__file__` / `__dirname` name the copy, so a script that loads
+ * neighbour files relative to itself must use HQ_APPROVED_SCRIPT_DIR. The
+ * working directory is left as the caller's.
+ *
+ * The child environment gets a fixed system PATH and loses the variables that
+ * make an interpreter, the loader or the macOS xcrun shims run other code.
+ * The same names are refused when they arrive in the injected secrets or in
+ * an env-schema / env-local value, because those are merged last.
+ *
+ * The child environment is built from an allowlist (see scriptBoundChildEnv),
+ * not inherited from the caller.
+ *
+ * What the binding does and does not protect: it controls which entrypoint
+ * receives the secret. It does not isolate what that entrypoint runs. A
+ * same-user caller can still influence tools the script calls through files
+ * in HOME (for example ~/.gitconfig and fsmonitor hooks, ~/.curlrc,
+ * ~/.ssh/config, ~/.netrc) or through anything else the user can write. Real
+ * isolation needs the vault-side sandbox release (`hq secrets sandbox`).
+ *
+ * Remaining limits, documented on purpose:
+ *   - Only the script file is hashed. Files it sources, requires or imports
+ *     (neighbour files, modules) are not covered by the approval.
+ *   - A process running as the same user can still race the private copy
+ *     between its re-hash and the interpreter opening it. The window is short
+ *     and the path is random, but same-user code is not a boundary this
+ *     client-side check can enforce.
+ *   - The check runs in the CLI. A modified CLI, or a direct call to the vault
+ *     API with a self-asserted hash, is outside what it can stop.
+ */
+export declare class ScriptBindingError extends Error {
+    constructor(message: string);
+}
+/** Root-owned search path used for interpreters and for the child. */
+export declare const FIXED_SYSTEM_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+export interface ScriptBoundCommand {
+    scriptRealPath: string;
+    interpreterPath: string;
+    interpreterArgs: string[];
+    scriptArgs: string[];
+    /** sha256 of the script when the command was resolved. */
+    sha256: string;
+}
+export interface PreparedBoundSpawn {
+    file: string;
+    args: string[];
+    copyPath: string;
+    cleanup: () => void;
+}
+/** True for a variable a bound script's environment must not take from the caller. */
+export declare function isDeniedEnvName(name: string): boolean;
+/**
+ * Schema / local env literal names a bound `hq run --script` launch accepts
+ * (fifth review). Literals are caller-written, so instead of denying
+ * tool-config names one by one, only these app-level switches are allowed.
+ * Everything else must come from the vault through hq().
+ */
+export declare const SAFE_LITERAL_NAMES: Set<string>;
+/** Refuse schema literals that are not on SAFE_LITERAL_NAMES (or are denied). */
+export declare function assertLiteralNamesAllowed(names: Iterable<string>): void;
+/**
+ * Design (feedback_0e6abcb8, fourth review): an injected name is accepted in a
+ * bound launch only when it is not on the loader/interpreter denylist, not
+ * one of the inherited allowlist names (HOME, USER, LANG, LC_*, TZ, TMPDIR,
+ * ...), and not on the explicit dangerous list above. Ordinary application
+ * names (FAKE_API_KEY, DATABASE_URL, NODE_ENV) pass.
+ */
+export declare function isDeniedInjectedName(name: string): boolean;
+/** Refuse a bound launch whose injected values use a denied name. */
+export declare function assertInjectedNamesAllowed(names: Iterable<string>): void;
+export declare function privateCopyRoot(): string;
+/**
+ * True when realPath and every parent directory are owned by root and not
+ * group- or world-writable.
+ */
+export declare function isRootOwnedChain(realPath: string): boolean;
+/**
+ * Resolve the command after `--` against the approved script. Throws
+ * ScriptBindingError when the command is not exactly the script invocation.
+ */
+export declare function resolveScriptBoundCommand(scriptPath: string, childArgs: string[]): Promise<ScriptBoundCommand>;
+/** Compare the script on disk with the hash sent to the vault. */
+export declare function assertScriptUnchanged(bound: ScriptBoundCommand, attestedSha256: string | undefined): Promise<void>;
+/**
+ * Read the script once, check its hash, copy those bytes into a fresh 0700
+ * directory, re-hash the copy, and return the spawn target that runs the copy.
+ */
+export declare function prepareBoundSpawn(bound: ScriptBoundCommand, attestedSha256: string | undefined): PreparedBoundSpawn;
+/**
+ * Remove the private copy when the parent gets SIGINT, SIGTERM or SIGHUP, or
+ * exits, then re-raise the signal so the default termination still happens.
+ * SIGKILL cannot be handled; a copy left by it stays in the 0700 temp
+ * directory until the OS cleans the temp dir.
+ */
+export declare function cleanupOnParentSignals(cleanup: () => void, proc?: Pick<NodeJS.Process, "once" | "removeListener" | "kill" | "pid">): () => void;
+/**
+ * Child environment for a bound script, built from an allowlist: HOME, USER,
+ * LOGNAME, LANG, LC_*, TERM, TZ and TMPDIR from the caller, a fixed PATH, and
+ * the HQ_APPROVED_* variables. Injected secrets and schema values are added by
+ * the caller after a denylist check.
+ */
+export declare function scriptBoundChildEnv(env: NodeJS.ProcessEnv, scriptRealPath?: string): NodeJS.ProcessEnv;
+/**
+ * Whether the release must be bound to the script. Only rows the vault marked
+ * `scriptLock.mode: "off"` are exempt; enforced or unknown fails closed.
+ */
+export declare function requiresScriptBinding(keys: string[], lockModes: Map<string, string | undefined>): boolean;
+export interface ScriptBindingPlan {
+    bound?: ScriptBoundCommand;
+    error?: ScriptBindingError;
+}
+/**
+ * Resolve the binding before any fetch. A refusal is held, not thrown, so a
+ * caller whose secrets turn out not to be script-locked keeps working.
+ */
+export declare function planScriptBinding(scriptPath: string | undefined, childArgs: string[]): Promise<ScriptBindingPlan | undefined>;
+export interface ChildLaunch {
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cleanup: () => void;
+}
+/**
+ * Pick what to spawn once the vault has answered. Unlocked secrets keep the
+ * caller's command unchanged; enforced or unknown lock state requires the
+ * bound script and throws ScriptBindingError otherwise.
+ */
+export declare function selectChildLaunch(plan: ScriptBindingPlan | undefined, keys: string[], lockModes: Map<string, string | undefined>, attestedSha256: string | undefined, childArgs: string[], env: NodeJS.ProcessEnv, injected: Record<string, string>): ChildLaunch;
+//# sourceMappingURL=script-bound-exec.d.ts.map