@indigoai-us/hq-cli 5.77.11 → 5.77.12

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.`,
+  );
+}