@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/utils/secret-load-availability.js

@@ -0,0 +1,54 @@
+export class SecretLoadUnavailableError extends Error {
+    serverUnavailable = true;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SecretLoadUnavailableError";
+    }
+}
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EPIPE",
+    "UND_ERR_ABORTED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+export function isUnavailableSecretLoadHttpStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
+}
+export function isSecretLoadUnavailable(err) {
+    if (err instanceof SecretLoadUnavailableError)
+        return true;
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth < 4 && current && !seen.has(current); depth += 1) {
+        seen.add(current);
+        if (typeof current !== "object")
+            break;
+        const record = current;
+        if (typeof record.code === "string" &&
+            TRANSIENT_NETWORK_CODES.has(record.code)) {
+            return true;
+        }
+        if (record.name === "TimeoutError" || record.name === "AbortError") {
+            return true;
+        }
+        if (record instanceof TypeError &&
+            typeof record.message === "string" &&
+            /fetch failed|network error/i.test(record.message)) {
+            return true;
+        }
+        current = record.cause;
+    }
+    return false;
+}
+export const CACHED_SECRETS_SERVER_UNAVAILABLE_MESSAGE = "using cached secrets; server unavailable";
+//# sourceMappingURL=secret-load-availability.js.map

package/dist/utils/secrets-cache.d.ts

@@ -1,12 +1,16 @@
 export declare const DEFAULT_SECRETS_CACHE_TTL_MS: number;
-export declare function readCache(companyUid: string, name: string, expectedVersion?: number, maxAgeMs?: number): string | null;
+export declare function readCache(companyUid: string, name: string, principalUid: string, expectedVersion?: number, maxAgeMs?: number): string | null;
 /**
  * Returns whether an unexpired entry exists without decrypting its plaintext.
  * Callers use this only to decide whether to reauthorize a possible cache hit;
  * they must complete that authorization before calling {@link readCache}.
  */
-export declare function hasCacheEntry(companyUid: string, name: string): boolean;
-export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number, version?: number): void;
+export declare function hasCacheEntry(companyUid: string, name: string, principalUid: string): boolean;
+export declare function writeCache(companyUid: string, name: string, principalUid: string, value: string, ttlMs?: number, version?: number): void;
+/** Persist the last successfully resolved scope for a principal, encrypted and authenticated. */
+export declare function writeCachedScopeUid(scopeKey: string, principalUid: string, scopeUid: string): void;
+/** Return a still-valid scope UID only for the principal that wrote it. */
+export declare function readCachedScopeUid(scopeKey: string, principalUid: string): string | null;
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
  * secrets-cache directory on disk. Install-time MCP registration may use an

package/dist/utils/secrets-cache.js

@@ -6,9 +6,11 @@ const CACHE_DIR = path.join(os.homedir(), ".hq", "secrets-cache");
 const KEY_PATH = path.join(CACHE_DIR, ".key");
 const CACHE_FORMAT_MAGIC = Buffer.from("HQSC");
 const CACHE_FORMAT_MAGIC_BYTES = CACHE_FORMAT_MAGIC.length;
-const CACHE_VERSION_MARKER = Buffer.from("HQSCV2\0");
+const CACHE_VERSION_MARKER = Buffer.from("HQSCV3\0");
+const PREVIOUS_CACHE_VERSION_MARKER = Buffer.from("HQSCV2\0");
 const LEGACY_CACHE_VERSION_MARKER = Buffer.from("HQSCV1\0");
 const CACHE_VERSION_MARKER_BYTES = CACHE_VERSION_MARKER.length;
+const PRINCIPAL_DIGEST_BYTES = 32;
 const LEGACY_TIMESTAMP_BYTES = 8;
 const TIMESTAMP_BYTES = 8;
 const TTL_BYTES = 8;
@@ -16,7 +18,9 @@ const CACHE_VERSION_BYTES = 8;
 const ALGORITHM = "aes-256-gcm";
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
-export const DEFAULT_SECRETS_CACHE_TTL_MS = 5 * 60 * 1000;
+const SCOPE_CACHE_MAGIC = Buffer.from("HQSSV1\0");
+const SCOPE_KEY_DIR = "scopes";
+export const DEFAULT_SECRETS_CACHE_TTL_MS = 3 * 60 * 60 * 1000;
 function ensureCacheDir(companyUid) {
     const dir = path.join(CACHE_DIR, companyUid);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -58,7 +62,10 @@ function readCacheVersion(raw, offset) {
         return undefined;
     return isCacheVersion(value) ? value : null;
 }
-function cacheAad(header, companyUid, name) {
+function principalDigest(principalUid) {
+    return crypto.createHash("sha256").update(principalUid, "utf8").digest();
+}
+function cacheAad(header, companyUid, name, principalUid) {
     const company = Buffer.from(companyUid, "utf8");
     const secretName = Buffer.from(name, "utf8");
     const companyLength = Buffer.alloc(4);
@@ -72,6 +79,7 @@ function cacheAad(header, companyUid, name) {
         company,
         nameLength,
         secretName,
+        principalDigest(principalUid),
     ]);
 }
 function parseCacheHeader(raw) {
@@ -82,8 +90,9 @@ function parseCacheHeader(raw) {
         let ivStart = baseHeaderBytes;
         let version;
         let identityAuthenticated = false;
+        let encodedPrincipalDigest;
         if (raw.length >=
-            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + PRINCIPAL_DIGEST_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
             raw
                 .subarray(baseHeaderBytes, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES)
                 .equals(CACHE_VERSION_MARKER)) {
@@ -91,9 +100,22 @@ function parseCacheHeader(raw) {
             if (parsedVersion === null)
                 return null;
             version = parsedVersion;
-            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            const principalStart = baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            encodedPrincipalDigest = raw.subarray(principalStart, principalStart + PRINCIPAL_DIGEST_BYTES);
+            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + PRINCIPAL_DIGEST_BYTES;
             identityAuthenticated = true;
         }
+        else if (raw.length >=
+            baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length)
+                .equals(PREVIOUS_CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + PREVIOUS_CACHE_VERSION_MARKER.length);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += PREVIOUS_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES;
+        }
         else if (raw.length >=
             baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
             raw
@@ -114,6 +136,7 @@ function parseCacheHeader(raw) {
             ttlMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES)),
             version,
             identityAuthenticated,
+            principalDigest: encodedPrincipalDigest,
             ivStart,
             authTagStart,
             ciphertextStart,
@@ -136,8 +159,8 @@ function isExpired(header, maxAgeMs) {
     const ageMs = Date.now() - header.timestampMs;
     return !Number.isFinite(ttlMs) || ttlMs <= 0 || ageMs < 0 || ageMs > ttlMs;
 }
-export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
-    if (!validateInputs(companyUid, name))
+export function readCache(companyUid, name, principalUid, expectedVersion, maxAgeMs) {
+    if (!validateInputs(companyUid, name) || !principalUid)
         return null;
     const filePath = path.join(CACHE_DIR, companyUid, name);
     let raw;
@@ -159,6 +182,8 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
         catch { /* ok */ }
         return null;
     }
+    if (!header.principalDigest?.equals(principalDigest(principalUid)))
+        return null;
     const iv = raw.subarray(header.ivStart, header.authTagStart);
     const authTag = raw.subarray(header.authTagStart, header.ciphertextStart);
     const ciphertext = raw.subarray(header.ciphertextStart);
@@ -171,7 +196,7 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
     }
     try {
         const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name));
+        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name, principalUid));
         decipher.setAuthTag(authTag);
         const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
         return decrypted.toString("utf8");
@@ -189,8 +214,8 @@ export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
  * Callers use this only to decide whether to reauthorize a possible cache hit;
  * they must complete that authorization before calling {@link readCache}.
  */
-export function hasCacheEntry(companyUid, name) {
-    if (!validateInputs(companyUid, name))
+export function hasCacheEntry(companyUid, name, principalUid) {
+    if (!validateInputs(companyUid, name) || !principalUid)
         return false;
     const filePath = path.join(CACHE_DIR, companyUid, name);
     let raw;
@@ -203,18 +228,21 @@ export function hasCacheEntry(companyUid, name) {
     const header = parseCacheHeader(raw);
     if (!header)
         return false;
-    if (!header.identityAuthenticated || isExpired(header)) {
+    if (!header.identityAuthenticated ||
+        isExpired(header)) {
         try {
             fs.unlinkSync(filePath);
         }
         catch { /* ok */ }
         return false;
     }
+    if (!header.principalDigest?.equals(principalDigest(principalUid)))
+        return false;
     return true;
 }
-export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
+export function writeCache(companyUid, name, principalUid, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
     try {
-        if (!validateInputs(companyUid, name))
+        if (!validateInputs(companyUid, name) || !principalUid)
             return;
         if (ttlMs <= 0)
             return;
@@ -233,9 +261,10 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
             ttl,
             CACHE_VERSION_MARKER,
             versionBuffer,
+            principalDigest(principalUid),
         ]);
         const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-        cipher.setAAD(cacheAad(header, companyUid, name));
+        cipher.setAAD(cacheAad(header, companyUid, name, principalUid));
         const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
         const authTag = cipher.getAuthTag();
         const out = Buffer.concat([
@@ -254,6 +283,125 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
         // Cache write failure is non-fatal
     }
 }
+function scopeCachePath(scopeKey) {
+    const name = crypto.createHash("sha256").update(scopeKey, "utf8").digest("hex");
+    return path.join(CACHE_DIR, SCOPE_KEY_DIR, name);
+}
+function scopeCacheAad(header, scopeKey, principalUid) {
+    const key = Buffer.from(scopeKey, "utf8");
+    const keyLength = Buffer.alloc(4);
+    keyLength.writeUInt32BE(key.length);
+    return Buffer.concat([
+        Buffer.from("HQSC-SCOPE-AAD-V1\0"),
+        header,
+        keyLength,
+        key,
+        principalDigest(principalUid),
+    ]);
+}
+function logScopeCacheFailure(operation, err) {
+    const code = err && typeof err === "object" && "code" in err &&
+        typeof err.code === "string" &&
+        /^[A-Z0-9_]+$/.test(err.code)
+        ? err.code
+        : undefined;
+    console.warn(`Unable to ${operation} cached HQ scope UID`, code ? { code } : {});
+}
+function removeScopeCacheFile(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch (err) {
+        if (!(err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT")) {
+            logScopeCacheFailure("remove", err);
+        }
+    }
+}
+/** Persist the last successfully resolved scope for a principal, encrypted and authenticated. */
+export function writeCachedScopeUid(scopeKey, principalUid, scopeUid) {
+    try {
+        if (!scopeKey || !principalUid || !/^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(scopeUid))
+            return;
+        fs.mkdirSync(path.join(CACHE_DIR, SCOPE_KEY_DIR), { recursive: true, mode: 0o700 });
+        const key = getOrCreateKey();
+        const timestamp = Buffer.alloc(8);
+        timestamp.writeBigInt64BE(BigInt(Date.now()));
+        const ttl = Buffer.alloc(8);
+        ttl.writeBigInt64BE(BigInt(DEFAULT_SECRETS_CACHE_TTL_MS));
+        const header = Buffer.concat([SCOPE_CACHE_MAGIC, timestamp, ttl, principalDigest(principalUid)]);
+        const iv = crypto.randomBytes(IV_BYTES);
+        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+        cipher.setAAD(scopeCacheAad(header, scopeKey, principalUid));
+        const encrypted = Buffer.concat([cipher.update(scopeUid, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const output = Buffer.concat([header, iv, authTag, encrypted]);
+        const filePath = scopeCachePath(scopeKey);
+        const tmpPath = `${filePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, output, { mode: 0o600 });
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        // A scope-cache write failure must not change a successful online lookup.
+        logScopeCacheFailure("write", err);
+    }
+}
+/** Return a still-valid scope UID only for the principal that wrote it. */
+export function readCachedScopeUid(scopeKey, principalUid) {
+    if (!scopeKey || !principalUid)
+        return null;
+    const headerBytes = SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES + TTL_BYTES + PRINCIPAL_DIGEST_BYTES;
+    const filePath = scopeCachePath(scopeKey);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT") {
+            return null;
+        }
+        logScopeCacheFailure("read", err);
+        return null;
+    }
+    if (raw.length < headerBytes + IV_BYTES + AUTH_TAG_BYTES || !raw.subarray(0, SCOPE_CACHE_MAGIC.length).equals(SCOPE_CACHE_MAGIC)) {
+        console.warn("Ignoring malformed cached HQ scope UID entry");
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+    const encodedPrincipal = raw.subarray(SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES + TTL_BYTES, headerBytes);
+    const timestampMs = Number(raw.readBigInt64BE(SCOPE_CACHE_MAGIC.length));
+    const ttlMs = Number(raw.readBigInt64BE(SCOPE_CACHE_MAGIC.length + TIMESTAMP_BYTES));
+    const ageMs = Date.now() - timestampMs;
+    if (!encodedPrincipal.equals(principalDigest(principalUid)))
+        return null;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0 || ageMs < 0 || ageMs > ttlMs) {
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+    const ivStart = headerBytes;
+    const authTagStart = ivStart + IV_BYTES;
+    const ciphertextStart = authTagStart + AUTH_TAG_BYTES;
+    try {
+        const decipher = crypto.createDecipheriv(ALGORITHM, getOrCreateKey(), raw.subarray(ivStart, authTagStart));
+        decipher.setAAD(scopeCacheAad(raw.subarray(0, headerBytes), scopeKey, principalUid));
+        decipher.setAuthTag(raw.subarray(authTagStart, ciphertextStart));
+        const scopeUid = Buffer.concat([
+            decipher.update(raw.subarray(ciphertextStart)),
+            decipher.final(),
+        ]).toString("utf8");
+        return /^(?:cmp|prs)_[A-Za-z0-9_-]+$/.test(scopeUid) ? scopeUid : null;
+    }
+    catch (err) {
+        logScopeCacheFailure("decrypt", err);
+        removeScopeCacheFile(filePath);
+        return null;
+    }
+}
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
  * secrets-cache directory on disk. Install-time MCP registration may use an

package/dist/utils/self-update.d.ts

@@ -56,13 +56,15 @@
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
+import * as fs from "node:fs";
 import { type RunningInstall, type UpdateResult } from "./version-gate.js";
+import { type RestartDaemonResult } from "../lib/mesh/live/daemon/install.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
  */
 export declare const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
-export type SelfUpdateAction = 
+type SelfUpdateAction = 
 /** Opted out, guard set, lock held elsewhere, or latest unknown — nothing attempted. */
 "skipped"
 /** Already at (or ahead of) npm latest. */
@@ -82,6 +84,8 @@ export type SelfUpdateAction =
  | "update-ineffective"
 /** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
  | "reexec"
+/** Updated with no re-exec (the `hq daemon` updater restarts the daemon instead). */
+ | "updated"
 /**
  * Unattended caller: replacing the CLI in place is unsafe here, so nothing
  * was attempted and the command runs on the current version. An attended
@@ -133,6 +137,12 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
+    /** Permission preflight for an npm global prefix (tests inject a read-only result). */
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    /** Home directory used for the durable per-install permission notice marker. */
+    homeDir?: string;
+    /** Same-filesystem install rename, injectable for rollback tests. */
+    renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;
@@ -153,6 +163,21 @@ export interface SelfUpdateDeps {
      * underneath themselves: hooks, scripts, agents, cron, CI.
      */
     interactive?: boolean;
+    /** Best-effort daemon kick after the CLI install converges (tests). */
+    restartDaemon?: () => RestartDaemonResult | void;
+    /**
+     * Whether `cli.staged-self-update` is on: build the new version beside the
+     * running package and swap it in, instead of moving the running package
+     * aside for the whole install. Read only when an npm global install is due.
+     */
+    stagedSelfUpdate?: () => Promise<boolean>;
+    /**
+     * Runs installs through a copy of the installer's supervisor outside the
+     * package until disposed. Defaults to {@link detachUpdateSupervisor}.
+     */
+    detachSupervisor?: () => {
+        dispose(): void;
+    } | null;
 }
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and
@@ -168,4 +193,12 @@ export declare function autoUpdateAndReexec(argv: readonly string[], latest: str
  * are preserved.
  */
 export declare function selfUpdateAndReexec(argv: readonly string[], deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+/**
+ * `hq daemon` updater service: update to npm latest with nobody at a terminal
+ * and no re-exec. It runs as its own short-lived child of the daemon, so no
+ * user command is waiting on the package being replaced; after an "updated"
+ * outcome the daemon restarts itself onto the new version.
+ */
+export declare function daemonSelfUpdate(deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+export {};
 //# sourceMappingURL=self-update.d.ts.map