@indigoai-us/hq-cli 5.77.13 → 5.77.14

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.77.14]
+
+### Fixed
+
+- Extend `HQ_API_KEY` fail-closed: reject metadata-only `hq secrets get`
+  without `--reveal`, and hard-error `hq run` / `hq install` when a vault API
+  key is set (Cognito session required). (#273)
+- Keep the Cognito-only gate on the top-level `hq install` route only — not
+  inside shared `installPack()` — so `hq packs update` cannot un-wire a pack
+  and then abort mid-flight under `HQ_API_KEY`. (#273)
+
 ## [5.77.13]
 
 ### Added

package/dist/commands/pack-install.js

@@ -1613,6 +1613,15 @@ export function runScanPackages(hqRoot, opts = {}) {
     }
 }
 export async function installPack(source, opts = {}) {
+    // NOTE: the HQ_API_KEY fail-closed gate is NOT enforced here. `installPack`
+    // is a shared primitive called both by the top-level `hq install` CLI route
+    // (where Cognito-only is the right gate — checked there instead) AND by
+    // `hq packs update` (packs.ts:runUpdate), which un-wires an existing pack's
+    // contributions BEFORE re-installing. Throwing from inside `installPack`
+    // would leave an update mid-flight (unwired, not reinstalled) whenever
+    // HQ_API_KEY happened to be set. Restricting the assertion to the install
+    // entrypoint keeps `hq packs update` fail-closed at its own call site
+    // instead (checked before it un-wires anything).
     const transport = classify(source);
     const hqRoot = findHqRoot();
     // `readHqVersion` (shared with `hq packs`) reads the CANONICAL

package/dist/commands/pkg-install.js

@@ -23,6 +23,7 @@ import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
+import { assertCognitoOnlyCommand } from '../utils/resolve-vault-credential.js';
 import { MARKETPLACE_PREFIX, installPack, sourceMatchesPackPattern, } from './pack-install.js';
 export function registerPackageInstallCommand(parent) {
     parent
@@ -35,6 +36,11 @@ export function registerPackageInstallCommand(parent) {
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
         .action(async (source, opts) => {
         try {
+            // Gate the top-level `hq install` entrypoint only — `installPack`
+            // itself is also called by `hq packs update` (packs.ts), which must
+            // stay able to fail closed at its OWN call site (before it un-wires
+            // an existing pack) rather than mid-flight inside installPack.
+            assertCognitoOnlyCommand('hq install');
             if (sourceMatchesPackPattern(source)) {
                 await installPack(source, {
                     company: opts.company,

package/dist/commands/run.js

@@ -3,6 +3,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { internal } from 'varlock';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { peekHqApiKey } from '../utils/resolve-vault-credential.js';
 import { computeSha256 } from '../utils/integrity.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
@@ -38,6 +39,9 @@ export function registerRunCommand(program) {
         .allowUnknownOption(true)
         .action(async (opts) => {
         try {
+            if (peekHqApiKey() !== undefined) {
+                throw new Error('HQ_API_KEY is set; `hq run` requires a Cognito session. Unset HQ_API_KEY or use `hq secrets exec`.');
+            }
             const dashIndex = process.argv.indexOf('--');
             const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];
             if (!opts.check && childArgs.length === 0) {

package/dist/commands/secrets.js

@@ -732,6 +732,11 @@ export function registerSecretsCommand(program) {
         try {
             const cred = await resolveVaultCredential();
             if (cred.kind === "api-key") {
+                if (!opts.reveal) {
+                    console.error(chalk.red("HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
+                        "Use --reveal to fetch the value, or unset HQ_API_KEY for metadata-only reads."));
+                    process.exit(1);
+                }
                 const res = await vaultApiFetch({
                     token: cred.token,
                     path: "/v1/keys/secrets/fetch",

package/package.json

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

package/src/commands/pack-install.ts

@@ -2093,6 +2093,15 @@ export async function installPack(
   source: string,
   opts: InstallPackOptions = {}
 ): Promise<void> {
+  // NOTE: the HQ_API_KEY fail-closed gate is NOT enforced here. `installPack`
+  // is a shared primitive called both by the top-level `hq install` CLI route
+  // (where Cognito-only is the right gate — checked there instead) AND by
+  // `hq packs update` (packs.ts:runUpdate), which un-wires an existing pack's
+  // contributions BEFORE re-installing. Throwing from inside `installPack`
+  // would leave an update mid-flight (unwired, not reinstalled) whenever
+  // HQ_API_KEY happened to be set. Restricting the assertion to the install
+  // entrypoint keeps `hq packs update` fail-closed at its own call site
+  // instead (checked before it un-wires anything).
   const transport = classify(source);
   const hqRoot = findHqRoot();
   // `readHqVersion` (shared with `hq packs`) reads the CANONICAL

package/src/commands/packs-update-api-key.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment node
+/**
+ * Regression (Codex P1 follow-up on hq-cli#273): `hq packs update` un-wires a
+ * pack's existing contributions BEFORE calling `installPack()` to re-wire
+ * them. The Cognito-only `HQ_API_KEY` fail-closed gate added for `hq install`
+ * must live ONLY at that top-level CLI route (pkg-install.ts) — NOT inside
+ * the shared `installPack()` primitive `hq packs update` also calls. If it
+ * lived inside `installPack()`, a vault-key session would un-wire a pack and
+ * then throw before re-installing it, leaving the pack unwired with no
+ * symlinks and no rollback.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as os from 'os';
+import { Command } from 'commander';
+
+const { listInstalledPacks, unwirePack, installPack, resolveLatest } = vi.hoisted(() => ({
+  listInstalledPacks: vi.fn(),
+  unwirePack: vi.fn(() => ({ unlinked: [], skipped: [] })),
+  installPack: vi.fn(async () => {}),
+  resolveLatest: vi.fn(async () => ({
+    transport: 'git',
+    current: 'aaa',
+    latest: 'bbb',
+    updateAvailable: true,
+  })),
+}));
+
+vi.mock('./pack-install.js', () => ({
+  classify: vi.fn(() => 'git'),
+  resolveLatest,
+  resolveLatestMarketplace: vi.fn(),
+  runScanPackages: vi.fn(),
+  installPack,
+}));
+
+vi.mock('../utils/pack-contributions.js', () => ({
+  contributionLinks: vi.fn(() => []),
+  linkStatus: vi.fn(() => 'live'),
+  listInstalledPacks,
+  findDependentPacks: vi.fn(() => []),
+  readPackManifest: vi.fn(() => ({ manifest: null })),
+  unwirePack,
+  unwirePackMcp: vi.fn(),
+  readHqVersion: vi.fn(() => '15.0.0'),
+  readRecommendedPackages: vi.fn(() => []),
+  packagesDir: vi.fn((root: string) => `${root}/core/packages`),
+}));
+
+// resolveRoot() falls back to findHqRoot() when --hq-root isn't passed; stub
+// it to a real, existing directory so packs.ts never chdir()s into one.
+vi.mock('../utils/manifest.js', () => ({
+  findHqRoot: vi.fn(() => os.tmpdir()),
+}));
+
+import { registerPacksCommand } from './packs.js';
+
+async function runUpdateCli(...args: string[]): Promise<void> {
+  const program = new Command();
+  program.exitOverride();
+  registerPacksCommand(program);
+  await program.parseAsync(['packs', 'update', ...args], { from: 'user' });
+}
+
+describe('hq packs update leaves no pack unwired under HQ_API_KEY', () => {
+  beforeEach(() => {
+    listInstalledPacks.mockReturnValue([
+      {
+        name: 'hq-pack-demo',
+        dir: '/tmp/hq/core/packages/hq-pack-demo',
+        manifest: {
+          name: 'hq-pack-demo',
+          version: '1.0.0',
+          source: 'https://example.com/demo.git#aaa',
+          contributes: { skills: ['demo'] },
+        },
+      },
+    ]);
+    unwirePack.mockClear();
+    installPack.mockClear();
+  });
+
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
+  it('still calls installPack after unwirePack when HQ_API_KEY is set', async () => {
+    process.env.HQ_API_KEY = 'hqk_probe';
+    await runUpdateCli('hq-pack-demo', '--json');
+
+    expect(unwirePack).toHaveBeenCalledTimes(1);
+    // The regression: installPack must run to completion right after
+    // unwirePack -- it must NOT throw due to a Cognito-only gate, which would
+    // leave the pack unwired with nothing re-installed in its place.
+    expect(installPack).toHaveBeenCalledTimes(1);
+    const unwireOrder = unwirePack.mock.invocationCallOrder[0];
+    const installOrder = installPack.mock.invocationCallOrder[0];
+    expect(unwireOrder).toBeLessThan(installOrder);
+  });
+
+  it('still updates without HQ_API_KEY set (baseline, unchanged behavior)', async () => {
+    await runUpdateCli('hq-pack-demo', '--json');
+    expect(unwirePack).toHaveBeenCalledTimes(1);
+    expect(installPack).toHaveBeenCalledTimes(1);
+  });
+});

package/src/commands/pkg-install.dispatch.test.ts

@@ -4,7 +4,7 @@
  * listings transport (the live install path), not the legacy Cognito-gated
  * registry flow whose backend (/packages, /entitlements) was never deployed.
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Command } from 'commander';
 
 // vi.mock is hoisted above imports/consts, so build the mocks via vi.hoisted()
@@ -48,6 +48,10 @@ describe('hq install dispatch — bare slug routes to marketplace', () => {
     sourceMatchesPackPattern.mockClear();
   });
 
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
   it('routes a bare slug through the marketplace transport', async () => {
     await runInstall('email-assistant');
     expect(installPack).toHaveBeenCalledTimes(1);
@@ -69,3 +73,31 @@ describe('hq install dispatch — bare slug routes to marketplace', () => {
     expect(installPack.mock.calls[0][0]).toBe('@indigoai-us/hq-pack-demo');
   });
 });
+
+describe('hq install dispatch — HQ_API_KEY fail-closed gate', () => {
+  beforeEach(() => {
+    installPack.mockClear();
+    sourceMatchesPackPattern.mockClear();
+  });
+
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
+  it('rejects at the CLI entrypoint before calling installPack when HQ_API_KEY is set', async () => {
+    process.env.HQ_API_KEY = 'hqk_probe';
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((code?: number | string | null) => {
+        throw new Error(`process.exit(${code})`);
+      });
+    try {
+      await expect(runInstall('@indigoai-us/hq-pack-demo')).rejects.toThrow('process.exit(1)');
+      // The gate must fire BEFORE installPack -- a vault-key session must
+      // never reach the pack-fetch/wire path via `hq install`.
+      expect(installPack).not.toHaveBeenCalled();
+    } finally {
+      exitSpy.mockRestore();
+    }
+  });
+});

package/src/commands/pkg-install.ts

@@ -28,6 +28,7 @@ import {
 } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
+import { assertCognitoOnlyCommand } from '../utils/resolve-vault-credential.js';
 import {
   MARKETPLACE_PREFIX,
   installPack,
@@ -51,6 +52,11 @@ export function registerPackageInstallCommand(parent: Command): void {
         opts: { company?: string; allowHooks?: boolean; allowMcp?: boolean; branch?: boolean }
       ) => {
         try {
+          // Gate the top-level `hq install` entrypoint only — `installPack`
+          // itself is also called by `hq packs update` (packs.ts), which must
+          // stay able to fail closed at its OWN call site (before it un-wires
+          // an existing pack) rather than mid-flight inside installPack.
+          assertCognitoOnlyCommand('hq install');
           if (sourceMatchesPackPattern(source)) {
             await installPack(source, {
               company: opts.company,

package/src/commands/run.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { internal } from 'varlock';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { peekHqApiKey } from '../utils/resolve-vault-credential.js';
 import { computeSha256 } from '../utils/integrity.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
@@ -52,6 +53,11 @@ export function registerRunCommand(program: Command): void {
       check?: boolean;
     }) => {
       try {
+        if (peekHqApiKey() !== undefined) {
+          throw new Error(
+            'HQ_API_KEY is set; `hq run` requires a Cognito session. Unset HQ_API_KEY or use `hq secrets exec`.',
+          );
+        }
         const dashIndex = process.argv.indexOf('--');
         const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];
 

package/src/commands/secrets.test.ts

@@ -1945,6 +1945,19 @@ describe("HQ_API_KEY consume path", () => {
     expect(errText).toMatch(/must start with 'hqk_'/);
   });
 
+  it("rejects secrets get without --reveal when HQ_API_KEY is set", async () => {
+    process.env.HQ_API_KEY = "hqk_valid_key";
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["node", "hq", "secrets", "get", "FOO"]),
+    ).rejects.toThrow(/__EXIT__:1/);
+    expect(vaultApiFetch).not.toHaveBeenCalled();
+    const errText = errSpy.mock.calls
+      .map((call) => call.map(String).join(" "))
+      .join("\n");
+    expect(errText).toMatch(/without --reveal is not supported/);
+  });
+
   it("gets a secret via /v1/keys/secrets/fetch when HQ_API_KEY is set", async () => {
     process.env.HQ_API_KEY = "hqk_valid_key";
     vi.mocked(vaultApiFetch).mockResolvedValueOnce(

package/src/commands/secrets.ts

@@ -1055,6 +1055,15 @@ export function registerSecretsCommand(program: Command): void {
         const cred = await resolveVaultCredential();
 
         if (cred.kind === "api-key") {
+          if (!opts.reveal) {
+            console.error(
+              chalk.red(
+                "HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
+                  "Use --reveal to fetch the value, or unset HQ_API_KEY for metadata-only reads.",
+              ),
+            );
+            process.exit(1);
+          }
           const res = await vaultApiFetch({
             token: cred.token,
             path: "/v1/keys/secrets/fetch",