@indigoai-us/hq-cli 5.77.11 → 5.77.13

package/src/packaging.test.ts

@@ -61,4 +61,49 @@ describe("packaging: runtime dependencies", () => {
     expect(pkg.dependencies).toHaveProperty("@aws-sdk/client-s3");
     expect(pkg.devDependencies).not.toHaveProperty("@aws-sdk/client-s3");
   });
+
+  it("ships the IoT data-plane client imported by the session heartbeat", () => {
+    expect(pkg.dependencies).toHaveProperty("@aws-sdk/client-iot-data-plane");
+    expect(pkg.devDependencies).not.toHaveProperty(
+      "@aws-sdk/client-iot-data-plane",
+    );
+  });
+});
+
+/**
+ * Regression pin for the 2026-07 dead-heartbeat incident.
+ *
+ * The Outpost's systemd unit invoked `outpost-session-heartbeat-runner`, a
+ * command that was never written. The provisioning test asserted only that the
+ * generated user-data CONTAINED that string, so it passed for the entire life
+ * of the bug while the box logged "command not found" every five seconds and
+ * the box audit reported the service healthy.
+ *
+ * The lesson: asserting that a command NAME appears somewhere proves nothing.
+ * Assert the command RESOLVES. If `hq outposts heartbeat` is ever renamed,
+ * un-registered, or dropped from the build, this fails here — before a box is
+ * provisioned against it.
+ */
+describe("packaging: on-box commands the Outpost user-data invokes", () => {
+  it("registers `hq outposts heartbeat`", async () => {
+    const { Command } = await import("commander");
+    const { registerOutpostsCommand } = await import("./commands/outposts.js");
+
+    const program = new Command();
+    registerOutpostsCommand(program);
+
+    const outposts = program.commands.find((c) => c.name() === "outposts");
+    expect(outposts, "`hq outposts` must be registered").toBeDefined();
+
+    const heartbeat = outposts?.commands.find((c) => c.name() === "heartbeat");
+    expect(heartbeat, "`hq outposts heartbeat` must be registered").toBeDefined();
+
+    // The flags the systemd unit passes must all exist, or the unit dies on an
+    // "unknown option" at boot — a failure mode indistinguishable from the one
+    // this test exists to prevent.
+    const flags = (heartbeat?.options ?? []).map((o) => o.long);
+    expect(flags).toEqual(
+      expect.arrayContaining(["--once", "--interval", "--home", "--api-base-url"]),
+    );
+  });
 });

package/src/utils/resolve-vault-credential.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./cognito-session.js", () => ({
+  ensureCognitoToken: vi.fn(async () => "cognito-token"),
+}));
+
+import { ensureCognitoToken } from "./cognito-session.js";
+import {
+  assertCognitoOnlyCommand,
+  HQ_API_KEY_PREFIX,
+  peekHqApiKey,
+  resolveVaultCredential,
+} from "./resolve-vault-credential.js";
+
+afterEach(() => {
+  delete process.env.HQ_API_KEY;
+  vi.clearAllMocks();
+});
+
+describe("peekHqApiKey", () => {
+  it("returns undefined when unset or blank", () => {
+    expect(peekHqApiKey()).toBeUndefined();
+    process.env.HQ_API_KEY = "   ";
+    expect(peekHqApiKey()).toBeUndefined();
+  });
+
+  it("returns trimmed value when set", () => {
+    process.env.HQ_API_KEY = "  hqk_abc  ";
+    expect(peekHqApiKey()).toBe("hqk_abc");
+  });
+});
+
+describe("resolveVaultCredential", () => {
+  it("uses Cognito when HQ_API_KEY is unset", async () => {
+    const cred = await resolveVaultCredential();
+    expect(cred).toEqual({ kind: "cognito", token: "cognito-token" });
+    expect(ensureCognitoToken).toHaveBeenCalledOnce();
+  });
+
+  it("returns api-key credential for hqk_ without calling Cognito", async () => {
+    process.env.HQ_API_KEY = `${HQ_API_KEY_PREFIX}valid`;
+    const cred = await resolveVaultCredential();
+    expect(cred).toEqual({
+      kind: "api-key",
+      token: `${HQ_API_KEY_PREFIX}valid`,
+    });
+    expect(ensureCognitoToken).not.toHaveBeenCalled();
+  });
+
+  it("fails closed on invalid prefix (no Cognito fallback)", async () => {
+    process.env.HQ_API_KEY = "hqk_totally_invalid".replace("hqk_", "bad_");
+    process.env.HQ_API_KEY = "not_a_vault_key";
+    await expect(resolveVaultCredential()).rejects.toThrow(/must start with/);
+    expect(ensureCognitoToken).not.toHaveBeenCalled();
+  });
+});
+
+describe("assertCognitoOnlyCommand", () => {
+  it("no-ops when HQ_API_KEY unset", () => {
+    expect(() => assertCognitoOnlyCommand("secrets list")).not.toThrow();
+  });
+
+  it("throws when HQ_API_KEY is set", () => {
+    process.env.HQ_API_KEY = `${HQ_API_KEY_PREFIX}x`;
+    expect(() => assertCognitoOnlyCommand("secrets list")).toThrow(
+      /not supported for API keys/,
+    );
+  });
+});

package/src/utils/resolve-vault-credential.ts

@@ -0,0 +1,60 @@
+import { ensureCognitoToken } from "./cognito-session.js";
+
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export const HQ_API_KEY_PREFIX = "hqk_";
+
+export type VaultCredential =
+  | { kind: "api-key"; token: string }
+  | { kind: "cognito"; token: string };
+
+/**
+ * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
+ * Does not validate prefix — use {@link resolveVaultCredential} for that.
+ */
+export function peekHqApiKey(): string | undefined {
+  const raw = process.env.HQ_API_KEY;
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Resolve vault auth for CLI commands.
+ *
+ * When `HQ_API_KEY` is set it is authoritative: must be a vault key (`hqk_…`)
+ * and Cognito is never used as a fallback (fail-closed). When unset, uses the
+ * cached Cognito session (interactive login if needed).
+ */
+export async function resolveVaultCredential(options?: {
+  interactive?: boolean;
+}): Promise<VaultCredential> {
+  const apiKey = peekHqApiKey();
+  if (apiKey !== undefined) {
+    if (!apiKey.startsWith(HQ_API_KEY_PREFIX)) {
+      throw new Error(
+        `HQ_API_KEY must start with '${HQ_API_KEY_PREFIX}' (vault API key). ` +
+          `Got a value that is not a vault key — refusing to fall back to Cognito. ` +
+          `Unset HQ_API_KEY to use your session, or create a key with \`hq api-keys create\`.`,
+      );
+    }
+    return { kind: "api-key", token: apiKey };
+  }
+
+  const token = await ensureCognitoToken({
+    interactive: options?.interactive,
+  });
+  return { kind: "cognito", token };
+}
+
+/**
+ * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
+ * (list, set, ACL, api-keys admin, etc.).
+ */
+export function assertCognitoOnlyCommand(commandLabel: string): void {
+  if (peekHqApiKey() === undefined) return;
+  throw new Error(
+    `HQ_API_KEY is set; '${commandLabel}' is not supported for API keys. ` +
+      `API keys support scoped secret reads via \`hq secrets get\`, \`hq secrets exec\`, ` +
+      `and \`hq secrets env\`. Unset HQ_API_KEY to use your Cognito session.`,
+  );
+}

package/src/utils/vault-api.ts

@@ -5,6 +5,13 @@ import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
 
 export interface VaultApiOptions {
+  /**
+   * Control-plane origin. Defaults to DEFAULT_VAULT_API_URL. Set it when a
+   * caller has been pointed at another deployment, so identity and every
+   * other call resolve against the SAME plane — a token minted for one and
+   * sent to another is simply rejected, which reads as an auth failure.
+   */
+  baseUrl?: string;
   token: string;
   path: string;
   method?: string;
@@ -72,7 +79,7 @@ async function peekPlanLimitStatus(response: Response): Promise<Response> {
 }
 
 export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
-  const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
+  const url = new URL(opts.path, opts.baseUrl ?? DEFAULT_VAULT_API_URL);
   if (opts.query) {
     for (const [k, v] of Object.entries(opts.query)) {
       url.searchParams.set(k, v);
@@ -335,10 +342,14 @@ interface PersonEntity {
 
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.
-export async function resolveCallerPersonUid(token: string): Promise<string> {
+export async function resolveCallerPersonUid(
+  token: string,
+  baseUrl?: string,
+): Promise<string> {
   const res = await vaultApiFetch({
     token,
     path: '/entity/by-type/person',
+    baseUrl,
   });
   if (!res.ok) {
     throw new Error("Failed to fetch person entity — run `hq login` and try again");