@indigoai-us/hq-cli 5.345.154 → 5.345.155

package/dist/lib/lanes/registry-flag.js

@@ -1,5 +1,7 @@
 import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
-import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensureCognitoIdToken, loadCachedTokens, refreshActivePersonTokens, wantsMachineCognitoTokens, } from "../../utils/cognito-session.js";
 import { FLAG_REGISTRY_DEFAULT_ENDPOINT, resolveFlagRegistryEndpoint, } from "../flag-registry-endpoint.js";
 export const LANES_FLAG_API_DEFAULT_ENDPOINT = FLAG_REGISTRY_DEFAULT_ENDPOINT;
 export const LANES_FLAG_READ_TIMEOUT_MS = 5_000;
@@ -15,15 +17,118 @@ class MissingFlagTokenError extends Error {
         this.name = "MissingFlagTokenError";
     }
 }
+export const LANES_FLAG_RETRY_BACKOFF_MS = 250;
+export const LANES_FLAG_CACHE_FILE = "lanes-flag-cache.json";
+const FLAG_CACHE_MAX_ENTRIES = 256;
+/**
+ * Oldest last-known-good entry a failed read may serve. Every successful
+ * snapshot read restamps resolvedAt, so this bounds how long a value can
+ * outlive its last confirmation by the registry.
+ */
+export const LANES_FLAG_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * HQ state dir from the caller's env (`HQ_STATE_DIR`, else `<home>/.hq`).
+ * Returns null when the env names neither, so a hermetic env never touches
+ * the real home directory.
+ */
+function flagCacheDir(options) {
+    if (options.cacheDir !== undefined)
+        return options.cacheDir;
+    const env = options.env ?? process.env;
+    const stateDir = env.HQ_STATE_DIR?.trim();
+    if (stateDir)
+        return stateDir;
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim();
+    return home ? path.join(home, ".hq") : null;
+}
+function readFlagCacheFile(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, LANES_FLAG_CACHE_FILE), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const entries = parsed.entries;
+        if (!entries || typeof entries !== "object" || Array.isArray(entries))
+            return {};
+        return entries;
+    }
+    catch {
+        return {};
+    }
+}
+function readCachedFlagValue(dir, key, now = Date.now()) {
+    const entry = readFlagCacheFile(dir)[key];
+    if (!entry || typeof entry.value !== "boolean" || typeof entry.resolvedAt !== "string")
+        return null;
+    const resolvedAt = Date.parse(entry.resolvedAt);
+    if (!Number.isFinite(resolvedAt))
+        return null;
+    const age = now - resolvedAt;
+    // A future timestamp (clock skew or a hand-edited file) is not trusted either.
+    if (age < 0 || age > LANES_FLAG_CACHE_MAX_AGE_MS)
+        return null;
+    return entry.value;
+}
+function writeCachedFlagValue(dir, key, value) {
+    let tmp;
+    try {
+        const entries = readFlagCacheFile(dir);
+        // Always restamp resolvedAt, even for an unchanged value: the max-age check
+        // measures time since the registry last confirmed it. Delete first so the
+        // key moves to the end and eviction drops the least recently confirmed.
+        delete entries[key];
+        entries[key] = { value, resolvedAt: new Date().toISOString() };
+        const keys = Object.keys(entries);
+        for (const stale of keys.slice(0, Math.max(0, keys.length - FLAG_CACHE_MAX_ENTRIES)))
+            delete entries[stale];
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const target = path.join(dir, LANES_FLAG_CACHE_FILE);
+        tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify({ version: 1, entries })}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, target);
+    }
+    catch {
+        if (tmp) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                // Nothing to clean up.
+            }
+        }
+        // The cache is best-effort; a read must never fail because it cannot be saved.
+    }
+}
+const TOKENISH_PATTERNS = [
+    /bearer\s+\S+/gi,
+    /eyJ[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g,
+    /\b(?:hq|sk|pk|ghp|gho|xox[a-z])[_-][A-Za-z0-9_-]{8,}/gi,
+    /[A-Za-z0-9+/_-]{32,}={0,2}/g,
+];
+/** Error message safe for stderr: token-like substrings removed, length bounded. */
+export function sanitizeFlagErrorMessage(error) {
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    let message = raw;
+    for (const pattern of TOKENISH_PATTERNS)
+        message = message.replace(pattern, "[redacted]");
+    return message.length > 200 ? `${message.slice(0, 200)}...` : message;
+}
 function errorClass(error) {
     return error instanceof Error ? error.name : "UnknownError";
 }
-function reportReadFailure(flagKey, error, fallback) {
+function reportReadFailure(flagKey, error, fallback, diagnostics) {
     const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
     process.stderr.write(`${JSON.stringify({
         event: `lanes.${suffix}.flag_read_failed`,
         flag: flagKey,
         error: errorClass(error),
+        error_message: sanitizeFlagErrorMessage(error),
+        ...(diagnostics?.status !== undefined ? { status: diagnostics.status } : {}),
+        ...(diagnostics ? {
+            duration_ms: diagnostics.durationMs,
+            attempts: diagnostics.attempts,
+            token_refreshed: diagnostics.tokenRefreshed,
+            cache_used: diagnostics.cacheUsed,
+        } : {}),
         fallback,
     })}\n`);
 }
@@ -47,8 +152,11 @@ function cacheKey(flagKey, company, endpoint) {
 }
 /**
  * Read a lanes flag once for each company identity in this CLI process. The
- * cache contains only an in-flight or settled decision result; it is never
- * written to disk. A local override is checked on every call and wins first.
+ * in-process cache holds the in-flight or settled result. The last registry
+ * snapshot value per flag and company is also kept in the HQ state dir and
+ * used when a later read fails transiently (timeout, network error, 5xx) and
+ * the value was confirmed within LANES_FLAG_CACHE_MAX_AGE_MS. A local override
+ * is checked on every call and wins first.
  */
 export async function readLanesRegistryFlag(flagKey, options = {}) {
     const result = await readLanesRegistryFlagResult(flagKey, options);
@@ -72,7 +180,7 @@ async function readRegistryFlagOutcome(flagKey, options, failOpen) {
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);
     const key = cacheKey(flagKey, options.company, endpoint);
     const cached = registryReads.get(key);
-    const pending = cached ?? readRegistryValue(flagKey, endpoint, options);
+    const pending = cached ?? readRegistryValue(flagKey, endpoint, key, options);
     if (!cached)
         registryReads.set(key, pending);
     const outcome = await pending;
@@ -108,42 +216,89 @@ export async function readLanesRegistryFlagFailOff(flagKey, options = {}, reader
 export function _resetThrownFlagReadWarningsForTests() {
     reportedThrownFlagReads.clear();
 }
-async function readRegistryValue(flagKey, endpoint, options) {
+function isTimeoutError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.name === "AbortError" || error.name === "TimeoutError" ||
+        error.message.startsWith("hq-flags: request timed out");
+}
+function classifyAttempt(attempt) {
+    if (!attempt.failure)
+        return "none";
+    const status = attempt.status;
+    if (status !== undefined && status >= 400) {
+        if (status === 401)
+            return "unauthorized";
+        if (status >= 500)
+            return "transient";
+        return "permanent";
+    }
+    if (attempt.networkError || isTimeoutError(attempt.failure.error))
+        return "transient";
+    return "permanent";
+}
+async function defaultRefreshToken() {
+    if (wantsMachineCognitoTokens()) {
+        return ensureCognitoIdToken({ interactive: false });
+    }
+    const cached = loadCachedTokens();
+    if (!cached)
+        throw new MissingFlagTokenError();
+    const refreshed = await refreshActivePersonTokens(cached);
+    return refreshed.idToken;
+}
+function defaultAcquireToken() {
+    return async () => {
+        try {
+            return await ensureCognitoIdToken({ interactive: false });
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.startsWith("No valid HQ session")) {
+                throw new MissingFlagTokenError();
+            }
+            throw error;
+        }
+    };
+}
+function requireToken(token) {
+    if (typeof token !== "string" || token.trim().length === 0) {
+        throw new MissingFlagTokenError();
+    }
+    return token;
+}
+async function readRegistryAttempt(flagKey, endpoint, options, acquireToken) {
     const company = options.company;
     const companyUid = company?.uid?.trim();
     const companySlug = company?.slug?.trim();
+    const baseFetch = options.fetch ?? globalThis.fetch;
     let client;
-    let resolution;
-    let failure;
+    const attempt = { networkError: false };
     const rememberFailure = (error) => {
-        failure ??= { error };
+        attempt.failure ??= { error };
     };
     try {
-        const acquireToken = options.getToken ?? (async () => {
-            try {
-                return await ensureCognitoIdToken({ interactive: false });
-            }
-            catch (error) {
-                if (error instanceof Error &&
-                    error.message.startsWith("No valid HQ session")) {
-                    throw new MissingFlagTokenError();
-                }
-                throw error;
-            }
-        });
-        const getToken = async () => {
-            const token = await acquireToken();
-            if (typeof token !== "string" || token.trim().length === 0) {
-                throw new MissingFlagTokenError();
-            }
-            return token;
-        };
         client = (options.createClient ?? createFlagClient)({
             endpoint,
-            getToken,
+            getToken: async () => requireToken(await acquireToken()),
             env: {},
             refreshIntervalMs: 0,
             requestTimeoutMs: LANES_FLAG_READ_TIMEOUT_MS,
+            ...(baseFetch
+                ? {
+                    fetch: async (input, init) => {
+                        try {
+                            const res = await baseFetch(input, init);
+                            attempt.status = res.status;
+                            return res;
+                        }
+                        catch (error) {
+                            attempt.networkError = true;
+                            throw error;
+                        }
+                    },
+                }
+                : {}),
             ...(companyUid ? { companyUid } : {}),
             ...(companySlug ? { companyIdentifiers: [companySlug] } : {}),
             onError: rememberFailure,
@@ -155,7 +310,7 @@ async function readRegistryValue(flagKey, endpoint, options) {
             rememberFailure(error);
         }
         try {
-            resolution = client.explain(flagKey, { fallback: options.defaultValue ?? false });
+            attempt.resolution = client.explain(flagKey, { fallback: options.defaultValue ?? false });
         }
         catch (error) {
             rememberFailure(error);
@@ -172,12 +327,77 @@ async function readRegistryValue(flagKey, endpoint, options) {
             rememberFailure(error);
         }
     }
-    if (resolution?.source === "snapshot" || resolution?.source === "local-override") {
-        return { result: { state: "resolved", value: resolution.value }, ...(failure ? { failure } : {}) };
+    return attempt;
+}
+function isSnapshotResolution(resolution) {
+    return resolution?.source === "snapshot" || resolution?.source === "local-override";
+}
+async function readRegistryValue(flagKey, endpoint, key, options) {
+    const startedAt = Date.now();
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let acquireToken = options.getToken ?? defaultAcquireToken();
+    let attempt = await readRegistryAttempt(flagKey, endpoint, options, acquireToken);
+    let attempts = 1;
+    let tokenRefreshed = false;
+    if (!isSnapshotResolution(attempt.resolution)) {
+        const kind = classifyAttempt(attempt);
+        if (kind === "transient") {
+            await sleep(options.retryBackoffMs ?? LANES_FLAG_RETRY_BACKOFF_MS);
+            attempt = await readRegistryAttempt(flagKey, endpoint, options, acquireToken);
+            attempts += 1;
+        }
+        else if (kind === "unauthorized") {
+            const refresh = options.refreshToken ?? (options.getToken ? options.getToken : defaultRefreshToken);
+            let refreshedToken;
+            try {
+                refreshedToken = requireToken(await refresh());
+                tokenRefreshed = true;
+            }
+            catch {
+                // Keep the original 401 as the reported failure.
+            }
+            if (refreshedToken !== undefined) {
+                const token = refreshedToken;
+                acquireToken = () => token;
+                attempt = await readRegistryAttempt(flagKey, endpoint, options, acquireToken);
+                attempts += 1;
+            }
+        }
+    }
+    const durationMs = Date.now() - startedAt;
+    const diagnostics = {
+        ...(attempt.status !== undefined ? { status: attempt.status } : {}),
+        durationMs,
+        attempts,
+        tokenRefreshed,
+        cacheUsed: false,
+    };
+    const cacheDir = flagCacheDir(options);
+    if (isSnapshotResolution(attempt.resolution)) {
+        const value = attempt.resolution.value;
+        if (attempt.resolution.source === "snapshot" && cacheDir)
+            writeCachedFlagValue(cacheDir, key, value);
+        return {
+            result: { state: "resolved", value },
+            ...(attempt.failure ? { failure: { ...attempt.failure, diagnostics } } : {}),
+        };
+    }
+    if (attempt.failure) {
+        // Only a transient failure (timeout, network error, 5xx) may serve the
+        // last-known-good value. A 401 that survived the refresh, a 403 or other
+        // 4xx, and a missing token mean the registry (or the session) refused the
+        // read, so it fails closed to the caller's default instead.
+        const transient = classifyAttempt(attempt) === "transient";
+        const cachedValue = transient && cacheDir ? readCachedFlagValue(cacheDir, key) : null;
+        if (cachedValue !== null) {
+            return {
+                result: { state: "resolved", value: cachedValue },
+                failure: { ...attempt.failure, diagnostics: { ...diagnostics, cacheUsed: true } },
+            };
+        }
+        return { result: { state: "unknown" }, failure: { ...attempt.failure, diagnostics } };
     }
-    if (failure)
-        return { result: { state: "unknown" }, failure };
-    return { result: { state: "resolved", value: resolution?.value ?? false } };
+    return { result: { state: "resolved", value: attempt.resolution?.value ?? false } };
 }
 function reportRegistryFailure(flagKey, key, outcome, options, failOpen) {
     if (!outcome.failure)
@@ -194,7 +414,7 @@ function reportRegistryFailure(flagKey, key, outcome, options, failOpen) {
         reportFailure(outcome.failure.error);
         return;
     }
-    reportReadFailure(flagKey, outcome.failure.error, fallback);
+    reportReadFailure(flagKey, outcome.failure.error, fallback, outcome.failure.diagnostics);
 }
 export function _resetLanesRegistryFlagCacheForTests() {
     registryReads.clear();

package/dist/lib/personal-secrets-audit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Personal vault use from a company-locked session.
+ *
+ * Owner decision dq_20261020234444_f1b1ea4185: a session locked to one company
+ * may read the caller's own personal-vault secrets through `hq secrets exec
+ * --personal`, read-only, and every use is audit-logged. All other personal
+ * vault operations stay refused in such a session.
+ */
+/** True for a person (prs_) or agent-self (agt_) vault uid used as a scope. */
+export declare function isEntityScopeRef(ref: string): boolean;
+/** Relative to the HQ root. One JSON object per line. */
+export declare const PERSONAL_SECRETS_AUDIT_RELATIVE_PATH: string;
+export declare const PERSONAL_SCOPE_READ_ONLY_MESSAGE = "Personal scope in a company-locked session is read-only: only `hq secrets exec --personal --only <NAMES> -- <command>` is allowed.";
+export interface PersonalSecretsAuditEntry {
+    ts: string;
+    session_id: string;
+    locked_company: string;
+    command: "secrets exec";
+    scope: "personal";
+    secret_names: string[];
+}
+export declare function personalSecretsAuditPath(root: string): string;
+/**
+ * Append one audit line before any value is read. Throws when the line cannot
+ * be written, so the caller fails closed instead of reading unlogged.
+ * Records secret names only, never values.
+ */
+export declare function appendPersonalSecretsAudit(root: string, entry: Omit<PersonalSecretsAuditEntry, "ts" | "command" | "scope"> & {
+    ts?: string;
+}): PersonalSecretsAuditEntry;
+//# sourceMappingURL=personal-secrets-audit.d.ts.map

package/dist/lib/personal-secrets-audit.js

@@ -0,0 +1,45 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Personal vault use from a company-locked session.
+ *
+ * Owner decision dq_20261020234444_f1b1ea4185: a session locked to one company
+ * may read the caller's own personal-vault secrets through `hq secrets exec
+ * --personal`, read-only, and every use is audit-logged. All other personal
+ * vault operations stay refused in such a session.
+ */
+/** True for a person (prs_) or agent-self (agt_) vault uid used as a scope. */
+export function isEntityScopeRef(ref) {
+    return /^(prs|agt)_/.test(ref.trim());
+}
+/** Relative to the HQ root. One JSON object per line. */
+export const PERSONAL_SECRETS_AUDIT_RELATIVE_PATH = path.join("workspace", "audit", "personal-secrets-use.jsonl");
+export const PERSONAL_SCOPE_READ_ONLY_MESSAGE = "Personal scope in a company-locked session is read-only: only `hq secrets exec --personal --only <NAMES> -- <command>` is allowed.";
+export function personalSecretsAuditPath(root) {
+    return path.join(root, PERSONAL_SECRETS_AUDIT_RELATIVE_PATH);
+}
+/**
+ * Append one audit line before any value is read. Throws when the line cannot
+ * be written, so the caller fails closed instead of reading unlogged.
+ * Records secret names only, never values.
+ */
+export function appendPersonalSecretsAudit(root, entry) {
+    const line = {
+        ts: entry.ts ?? new Date().toISOString(),
+        session_id: entry.session_id,
+        locked_company: entry.locked_company,
+        command: "secrets exec",
+        scope: "personal",
+        secret_names: [...entry.secret_names],
+    };
+    const file = personalSecretsAuditPath(root);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(file, `${JSON.stringify(line)}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    catch (error) {
+        throw new Error(`Cannot write the personal secrets audit log (${PERSONAL_SECRETS_AUDIT_RELATIVE_PATH}); refusing to read personal secrets: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return line;
+}
+//# sourceMappingURL=personal-secrets-audit.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.154",
+  "version": "5.345.155",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.154",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.154",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.154",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.154",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.154",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.154"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.155",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.155",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.155",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.155",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.155",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.155"
   }
 }