@indigoai-us/hq-cli 5.107.0 → 5.107.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.107.1] — 2026-09-03
+
 ## [5.107.0] — 2026-09-03
 
 ### Added

package/dist/commands/secrets.d.ts

@@ -28,6 +28,7 @@ export interface SecretMetadata {
 export interface SecretLoadSuccessRow extends SecretMetadata {
     name: string;
     value?: string;
+    version?: number;
 }
 export interface SecretLoadResponse {
     secrets: SecretLoadSuccessRow[];

package/dist/commands/secrets.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 import { writeSync } from "node:fs";
 import * as nodePath from "node:path";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { DEFAULT_SECRETS_CACHE_TTL_MS, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
+import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
@@ -545,7 +545,12 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
     }
     const resolved = new Map();
     const requested = [...new Set(keys)];
+    const cachedCandidates = new Set(requested.filter((name) => hasCacheEntry(companyUid, name)));
     try {
+        // The batch endpoint is the only non-capturing authorization path that also
+        // evaluates the supplied usage metadata. It covers warm and cold names in
+        // bounded requests, then a warm name may use its locally authenticated
+        // plaintext only when the returned version and current policy TTL agree.
         for (let i = 0; i < requested.length; i += MAX_BATCH_NAMES) {
             const chunk = requested.slice(i, i + MAX_BATCH_NAMES);
             const chunkNames = new Set(chunk);
@@ -572,6 +577,9 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     typeof body.code === "string") {
                     throw new Error(message);
                 }
+                if (res.status === 403) {
+                    throw new Error(`Failed to fetch secret '${chunk[0]}': No read permission`);
+                }
                 throw new Error(`Failed to batch-load secrets: ${message}`);
             }
             const data = (await res.json());
@@ -601,8 +609,26 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     continue;
                 }
                 const cacheTtlMs = normalizeCacheTtlMs(s);
+                const cached = cachedCandidates.has(s.name) &&
+                    cacheTtlMs > 0 &&
+                    typeof s.version === "number" &&
+                    Number.isSafeInteger(s.version) &&
+                    s.version > 0
+                    ? readCache(companyUid, s.name, s.version, cacheTtlMs)
+                    : null;
+                if (cached !== null) {
+                    resolved.set(s.name, cached);
+                    continue;
+                }
                 if (cacheTtlMs > 0) {
-                    writeCache(companyUid, s.name, s.value, cacheTtlMs);
+                    if (typeof s.version === "number" &&
+                        Number.isSafeInteger(s.version) &&
+                        s.version > 0) {
+                        writeCache(companyUid, s.name, s.value, cacheTtlMs, s.version);
+                    }
+                    else {
+                        writeCache(companyUid, s.name, s.value, cacheTtlMs);
+                    }
                 }
                 else {
                     removeCacheEntry(companyUid, s.name);

package/dist/run/hq-plugin.js

@@ -181,7 +181,7 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
             state.loadedSecretsByName.set(s.name, s.value);
             const cacheTtlMs = normalizeCacheTtlMs(s);
             if (cacheTtlMs > 0) {
-                writeCache(uid, s.name, s.value, cacheTtlMs);
+                writeCache(uid, s.name, s.value, cacheTtlMs, s.version);
             }
             else {
                 removeCacheEntry(uid, s.name);

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

@@ -1,6 +1,12 @@
 export declare const DEFAULT_SECRETS_CACHE_TTL_MS: number;
-export declare function readCache(companyUid: string, name: string): string | null;
-export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number): void;
+export declare function readCache(companyUid: string, name: 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;
 /**
  * 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,13 @@ 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 LEGACY_CACHE_VERSION_MARKER = Buffer.from("HQSCV1\0");
+const CACHE_VERSION_MARKER_BYTES = CACHE_VERSION_MARKER.length;
 const LEGACY_TIMESTAMP_BYTES = 8;
 const TIMESTAMP_BYTES = 8;
 const TTL_BYTES = 8;
+const CACHE_VERSION_BYTES = 8;
 const ALGORITHM = "aes-256-gcm";
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
@@ -45,7 +49,94 @@ function getOrCreateKey() {
     fs.renameSync(tmpPath, KEY_PATH);
     return fs.readFileSync(KEY_PATH);
 }
-export function readCache(companyUid, name) {
+function isCacheVersion(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function readCacheVersion(raw, offset) {
+    const value = Number(raw.readBigInt64BE(offset));
+    if (value === 0)
+        return undefined;
+    return isCacheVersion(value) ? value : null;
+}
+function cacheAad(header, companyUid, name) {
+    const company = Buffer.from(companyUid, "utf8");
+    const secretName = Buffer.from(name, "utf8");
+    const companyLength = Buffer.alloc(4);
+    const nameLength = Buffer.alloc(4);
+    companyLength.writeUInt32BE(company.length);
+    nameLength.writeUInt32BE(secretName.length);
+    return Buffer.concat([
+        Buffer.from("HQSC-AAD-V2\0"),
+        header,
+        companyLength,
+        company,
+        nameLength,
+        secretName,
+    ]);
+}
+function parseCacheHeader(raw) {
+    if (raw.subarray(0, CACHE_FORMAT_MAGIC_BYTES).equals(CACHE_FORMAT_MAGIC)) {
+        const baseHeaderBytes = CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES;
+        if (raw.length < baseHeaderBytes + IV_BYTES + AUTH_TAG_BYTES)
+            return null;
+        let ivStart = baseHeaderBytes;
+        let version;
+        let identityAuthenticated = false;
+        if (raw.length >=
+            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES)
+                .equals(CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            identityAuthenticated = true;
+        }
+        else if (raw.length >=
+            baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length)
+                .equals(LEGACY_CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES;
+        }
+        const authTagStart = ivStart + IV_BYTES;
+        const ciphertextStart = authTagStart + AUTH_TAG_BYTES;
+        if (raw.length < ciphertextStart)
+            return null;
+        return {
+            timestampMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES)),
+            ttlMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES)),
+            version,
+            identityAuthenticated,
+            ivStart,
+            authTagStart,
+            ciphertextStart,
+        };
+    }
+    const headerLen = LEGACY_TIMESTAMP_BYTES + IV_BYTES + AUTH_TAG_BYTES;
+    if (raw.length < headerLen)
+        return null;
+    return {
+        timestampMs: Number(raw.readBigInt64BE(0)),
+        ttlMs: DEFAULT_SECRETS_CACHE_TTL_MS,
+        identityAuthenticated: false,
+        ivStart: LEGACY_TIMESTAMP_BYTES,
+        authTagStart: LEGACY_TIMESTAMP_BYTES + IV_BYTES,
+        ciphertextStart: headerLen,
+    };
+}
+function isExpired(header, maxAgeMs) {
+    const ttlMs = maxAgeMs === undefined ? header.ttlMs : Math.min(header.ttlMs, 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))
         return null;
     const filePath = path.join(CACHE_DIR, companyUid, name);
@@ -56,40 +147,21 @@ export function readCache(companyUid, name) {
     catch {
         return null;
     }
-    let timestampMs;
-    let ttlMs;
-    let ivStart;
-    let authTagStart;
-    let ciphertextStart;
-    if (raw.length >=
-        CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
-        raw.subarray(0, CACHE_FORMAT_MAGIC_BYTES).equals(CACHE_FORMAT_MAGIC)) {
-        timestampMs = Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES));
-        ttlMs = Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES));
-        ivStart = CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES;
-        authTagStart = ivStart + IV_BYTES;
-        ciphertextStart = authTagStart + AUTH_TAG_BYTES;
-    }
-    else {
-        const headerLen = LEGACY_TIMESTAMP_BYTES + IV_BYTES + AUTH_TAG_BYTES;
-        if (raw.length < headerLen)
-            return null;
-        timestampMs = Number(raw.readBigInt64BE(0));
-        ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS;
-        ivStart = LEGACY_TIMESTAMP_BYTES;
-        authTagStart = ivStart + IV_BYTES;
-        ciphertextStart = authTagStart + AUTH_TAG_BYTES;
-    }
-    if (ttlMs <= 0 || Date.now() - timestampMs > ttlMs) {
+    const header = parseCacheHeader(raw);
+    if (!header)
+        return null;
+    if (!header.identityAuthenticated ||
+        isExpired(header, maxAgeMs) ||
+        (expectedVersion !== undefined && header.version !== expectedVersion)) {
         try {
             fs.unlinkSync(filePath);
         }
         catch { /* ok */ }
         return null;
     }
-    const iv = raw.subarray(ivStart, authTagStart);
-    const authTag = raw.subarray(authTagStart, ciphertextStart);
-    const ciphertext = raw.subarray(ciphertextStart);
+    const iv = raw.subarray(header.ivStart, header.authTagStart);
+    const authTag = raw.subarray(header.authTagStart, header.ciphertextStart);
+    const ciphertext = raw.subarray(header.ciphertextStart);
     let key;
     try {
         key = getOrCreateKey();
@@ -99,6 +171,7 @@ export function readCache(companyUid, name) {
     }
     try {
         const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name));
         decipher.setAuthTag(authTag);
         const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
         return decrypted.toString("utf8");
@@ -111,7 +184,35 @@ export function readCache(companyUid, name) {
         return null;
     }
 }
-export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS) {
+/**
+ * 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 function hasCacheEntry(companyUid, name) {
+    if (!validateInputs(companyUid, name))
+        return false;
+    const filePath = path.join(CACHE_DIR, companyUid, name);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch {
+        return false;
+    }
+    const header = parseCacheHeader(raw);
+    if (!header)
+        return false;
+    if (!header.identityAuthenticated || isExpired(header)) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch { /* ok */ }
+        return false;
+    }
+    return true;
+}
+export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
     try {
         if (!validateInputs(companyUid, name))
             return;
@@ -120,14 +221,29 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
         ensureCacheDir(companyUid);
         const key = getOrCreateKey();
         const iv = crypto.randomBytes(IV_BYTES);
-        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-        const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
-        const authTag = cipher.getAuthTag();
         const timestamp = Buffer.alloc(8);
         timestamp.writeBigInt64BE(BigInt(Date.now()));
         const ttl = Buffer.alloc(8);
         ttl.writeBigInt64BE(BigInt(ttlMs));
-        const out = Buffer.concat([CACHE_FORMAT_MAGIC, timestamp, ttl, iv, authTag, encrypted]);
+        const versionBuffer = Buffer.alloc(CACHE_VERSION_BYTES);
+        versionBuffer.writeBigInt64BE(BigInt(isCacheVersion(version) ? version : 0));
+        const header = Buffer.concat([
+            CACHE_FORMAT_MAGIC,
+            timestamp,
+            ttl,
+            CACHE_VERSION_MARKER,
+            versionBuffer,
+        ]);
+        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+        cipher.setAAD(cacheAad(header, companyUid, name));
+        const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const out = Buffer.concat([
+            header,
+            iv,
+            authTag,
+            encrypted,
+        ]);
         const filePath = path.join(CACHE_DIR, companyUid, name);
         fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
         const tmpPath = `${filePath}.tmp.${process.pid}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.107.0",
+  "version": "5.107.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {