@indigoai-us/hq-cli 5.345.170 → 5.345.171

package/dist/utils/cognito-session.d.ts

@@ -19,11 +19,12 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 import { isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens, type CognitoTokenSource } from "./machine-principal-state.js";
 import { loadCachedTokens, personTokenCacheFile, readPersonTokenFile } from "./person-token-cache.js";
 export { loadCachedTokens, personTokenCacheFile, readPersonTokenFile };
 export { isExpiring, isMachineIdentity };
-/** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
-export type CognitoTokenSource = "person" | "machine";
+export { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens };
+export type { CognitoTokenSource };
 /** Actor kind derived from the active token / machine-creds signal. */
 export type CognitoActorKind = "human" | "agent" | "unknown";
 /**
@@ -97,13 +98,6 @@ export declare const DEFAULT_HQ_ROOT: string;
 export declare function machineTokenStateDir(home?: string, env?: NodeJS.ProcessEnv): string;
 /** Absolute path of the machine-token cache file (daemon state dir). */
 export declare function machineTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
-/**
- * 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 declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
 /** Default machine-creds path hq-cloud also checks when the env is unset. */
 export declare function defaultMachineCredsFile(home?: string): string;
 export type EnsureCognitoTokenOptions = {
@@ -127,33 +121,12 @@ export type EnsureCognitoTokenOptions = {
 export declare const HQ_NO_BROWSER_LOGIN_ENV = "HQ_NO_BROWSER_LOGIN";
 /** An explicit `interactive` option wins; otherwise interactive unless the env switch is "1". */
 export declare function resolveInteractiveLogin(options: Pick<EnsureCognitoTokenOptions, "interactive">, env?: NodeJS.ProcessEnv): boolean;
-/**
- * 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 declare function hasPersonCachedSession(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
  * cache, and the default machine-creds file is readable. Distinct from
  * explicit `HQ_MACHINE_CREDS_FILE` / `{ tokenSource: "machine" }` opt-in.
  */
 export declare function isDefaultMachineCredsFallback(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
-/**
- * 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 declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Which Cognito token source this process will use for doctor / status / whoami.
  * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file

package/dist/utils/cognito-session.js

@@ -26,6 +26,7 @@ import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
 import { isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { hasPersonCachedSession, isMachineCredsFileEnvSet, probeMachineIdentity, wantsMachineCognitoTokens, } from "./machine-principal-state.js";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
@@ -36,6 +37,7 @@ export { loadCachedTokens, personTokenCacheFile, readPersonTokenFile };
 // Re-export the cached-session primitives for callers that must deliberately
 // avoid the refresh/login behavior in the higher-level helpers below.
 export { isExpiring, isMachineIdentity };
+export { hasPersonCachedSession, isMachineCredsFileEnvSet, wantsMachineCognitoTokens };
 /**
  * Override for where machine-minted Cognito tokens are cached.
  * Default: the work-mesh daemon state dir (`~/.hq/work-mesh/daemon`), so a
@@ -253,16 +255,6 @@ export function machineTokenStateDir(home = os.homedir(), env = process.env) {
 export function machineTokenCacheFile(home = os.homedir(), env = process.env) {
     return path.join(machineTokenStateDir(home, env), "cognito-tokens.json");
 }
-/**
- * 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;
-}
 /** Default machine-creds path hq-cloud also checks when the env is unset. */
 export function defaultMachineCredsFile(home = os.homedir()) {
     return path.join(home, ".hq-agent", "machine-creds.json");
@@ -279,69 +271,6 @@ export function resolveInteractiveLogin(options, env = process.env) {
         return options.interactive;
     return env[HQ_NO_BROWSER_LOGIN_ENV]?.trim() !== "1";
 }
-/**
- * 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`.
- */
-function probeMachineIdentity(env) {
-    return withAlignedMachineCredsEnv(env, () => isMachineIdentity());
-}
 /**
  * Fresh-box / Outpost bootstrap: env unset, not forced to person, no person
  * cache, and the default machine-creds file is readable. Distinct from
@@ -361,33 +290,6 @@ export function isDefaultMachineCredsFallback(options = {}, env = process.env) {
 function logDefaultMachineCredsFallback() {
     console.error(chalk.dim("machine identity from default creds file"));
 }
-/**
- * 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);
-}
 /**
  * Which Cognito token source this process will use for doctor / status / whoami.
  * Matches {@link wantsMachineCognitoTokens}: env opt-in, or default-file

package/dist/utils/machine-principal-state.d.ts

@@ -0,0 +1,38 @@
+/** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
+export type CognitoTokenSource = "person" | "machine";
+/**
+ * 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 declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function hasPersonCachedSession(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether hq-cloud currently sees readable machine creds (env override or
+ * default `~/.hq-agent/machine-creds.json`), honoring a synthetic `env`.
+ */
+export declare function probeMachineIdentity(env: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function wantsMachineCognitoTokens(options?: {
+    tokenSource?: CognitoTokenSource;
+}, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=machine-principal-state.d.ts.map

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/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