@indigoai-us/hq-cli 5.77.11 → 5.77.13

package/dist/utils/resolve-vault-credential.js

@@ -0,0 +1,48 @@
+import { ensureCognitoToken } from "./cognito-session.js";
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export const HQ_API_KEY_PREFIX = "hqk_";
+/**
+ * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
+ * Does not validate prefix — use {@link resolveVaultCredential} for that.
+ */
+export function peekHqApiKey() {
+    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) {
+    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) {
+    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.`);
+}
+//# sourceMappingURL=resolve-vault-credential.js.map

package/dist/utils/vault-api.d.ts

@@ -1,4 +1,11 @@
 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;
@@ -20,7 +27,7 @@ export declare function vaultApiFetchPublic(opts: {
 }): Promise<Response>;
 export declare function looksLikeCompanyUid(ref: string): boolean;
 export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
-export declare function resolveCallerPersonUid(token: string): Promise<string>;
+export declare function resolveCallerPersonUid(token: string, baseUrl?: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {
     personal?: boolean;
     companySlug?: string;

package/dist/utils/vault-api.js

@@ -63,7 +63,7 @@ async function peekPlanLimitStatus(response) {
     }
 }
 export async function vaultApiFetch(opts) {
-    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);
@@ -274,10 +274,11 @@ export async function getCompanyUid(token, companySlug) {
 }
 // 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) {
+export async function resolveCallerPersonUid(token, baseUrl) {
     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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.77.11",
+  "version": "5.77.13",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -21,6 +21,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@indigoai-us/hq-cloud": "^6.14.27",
     "@indigoai-us/hq-onboarding": "^0.1.0",
@@ -42,6 +43,7 @@
     "@types/node": "^22.0.0",
     "@types/semver": "^7.5.8",
     "@vitest/coverage-v8": "4.1.6",
+    "aws-sdk-client-mock": "^4.1.0",
     "eslint": "^10.5.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.61.1",

package/src/commands/api-keys.test.ts

@@ -126,10 +126,78 @@ describe("hq api-keys create", () => {
       .map((call) => call.map((value) => String(value)).join(" "))
       .join("\n");
     expect(printed).toContain("Store this key now");
-    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(1);
+    expect(printed).toContain("export HQ_API_KEY=");
+    expect(printed).toContain("hq secrets get");
+    // Key value appears in Store line + export line only (not in list metadata).
+    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(2);
     expect(errSpy).not.toHaveBeenCalled();
     expect(exitSpy).not.toHaveBeenCalled();
   });
+
+  it("includes deploy scope when --deploy-app is set", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_deploy",
+          companyUid: "cmp_acme",
+          name: "Deploy key",
+          scope: {
+            allowedPrefixes: ["CI"],
+            permission: "read",
+            deploy: {
+              apps: ["my-app", "other-app"],
+              capabilities: ["deploy:write"],
+            },
+          },
+          status: "active",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: null,
+        },
+        key: { value: "hqk_deploy_secret" },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "api-keys",
+        "create",
+        "--name",
+        "Deploy key",
+        "--scope",
+        "CI",
+        "--deploy-app",
+        "my-app",
+        "--deploy-app",
+        "other-app",
+      ],
+      { from: "user" },
+    );
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      method: "POST",
+      body: {
+        companyUid: "cmp_acme",
+        name: "Deploy key",
+        allowedPrefixes: ["CI"],
+        permission: "read",
+        deploy: {
+          apps: ["my-app", "other-app"],
+          capabilities: ["deploy:write"],
+        },
+      },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("Deploy apps:");
+    expect(printed).toContain("my-app, other-app");
+    expect(printed).toContain("hq-deploy API");
+  });
 });
 
 describe("hq api-keys list", () => {
@@ -145,6 +213,10 @@ describe("hq api-keys list", () => {
             scope: {
               allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
               permission: "read",
+              deploy: {
+                apps: ["preview-app"],
+                capabilities: ["deploy:write"],
+              },
             },
             status: "active",
             createdAt: "2026-06-19T12:00:00.000Z",
@@ -173,9 +245,11 @@ describe("hq api-keys list", () => {
       .map((call) => call.map((value) => String(value)).join(" "))
       .join("\n");
     expect(printed).toContain("KEY ID");
+    expect(printed).toContain("DEPLOY");
     expect(printed).toContain("key_123");
     expect(printed).toContain("CI key");
     expect(printed).toContain("HQ_PRO/HQ_PROD, HQ_PRO/HQ_DEV");
+    expect(printed).toContain("preview-app");
     expect(printed).not.toContain("hqk_should_not_print");
     expect(exitSpy).not.toHaveBeenCalled();
   });

package/src/commands/api-keys.ts

@@ -1,8 +1,14 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { assertCognitoOnlyCommand } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "./secrets.js";
 
+async function requireCognitoForApiKeys(label: string): Promise<string> {
+  assertCognitoOnlyCommand(label);
+  return ensureCognitoToken();
+}
+
 type ApiKeyPermission = "read" | "write" | "admin";
 
 interface ApiKeyMetadata {
@@ -12,6 +18,10 @@ interface ApiKeyMetadata {
   scope: {
     allowedPrefixes: string[];
     permission: ApiKeyPermission;
+    deploy?: {
+      apps: string[];
+      capabilities: string[];
+    };
   };
   status: string;
   createdAt: string;
@@ -42,6 +52,7 @@ interface ApiKeysGroupOptions {
 interface CreateApiKeyOptions {
   name: string;
   scope: string[];
+  deployApp: string[];
   permission: string;
   expires?: string;
 }
@@ -58,6 +69,13 @@ function formatPrefixes(prefixes: string[]): string {
   return prefixes.length > 0 ? prefixes.join(", ") : "-";
 }
 
+function formatDeployApps(
+  deploy?: { apps: string[]; capabilities: string[] },
+): string {
+  if (!deploy?.apps?.length) return "-";
+  return deploy.apps.join(", ");
+}
+
 function parsePermission(value: string): ApiKeyPermission {
   if (value === "read" || value === "write" || value === "admin") {
     return value;
@@ -107,6 +125,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     name: apiKey.name,
     permission: apiKey.scope.permission,
     prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+    deployApps: formatDeployApps(apiKey.scope.deploy),
     status: apiKey.status,
     lastUsedAt: formatMaybe(apiKey.lastUsedAt),
     expiresAt: formatMaybe(apiKey.expiresAt),
@@ -119,6 +138,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     ...rows.map((row) => row.permission.length),
   );
   const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+  const deployWidth = Math.max(6, ...rows.map((row) => row.deployApps.length));
   const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
   const lastUsedWidth = Math.max(
     11,
@@ -134,6 +154,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     "NAME".padEnd(nameWidth),
     "PERMISSION".padEnd(permissionWidth),
     "PREFIXES".padEnd(prefixesWidth),
+    "DEPLOY".padEnd(deployWidth),
     "STATUS".padEnd(statusWidth),
     "LAST USED".padEnd(lastUsedWidth),
     "EXPIRES".padEnd(expiresWidth),
@@ -147,6 +168,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
         row.name.padEnd(nameWidth),
         row.permission.padEnd(permissionWidth),
         row.prefixes.padEnd(prefixesWidth),
+        row.deployApps.padEnd(deployWidth),
         row.status.padEnd(statusWidth),
         row.lastUsedAt.padEnd(lastUsedWidth),
         row.expiresAt.padEnd(expiresWidth),
@@ -163,32 +185,42 @@ export function registerApiKeysCommand(program: Command): Command {
 
   apiKeys
     .command("create")
-    .description("Create a new API key")
+    .description(
+      "Create a new API key (vault secrets and/or scoped deploy via --deploy-app)",
+    )
     .requiredOption("--name <label>", "Human-readable label for the API key")
     .option(
       "--scope <prefix>",
-      "Allowed prefix (repeatable)",
+      "Allowed secret prefix (repeatable)",
+      collectRepeatedOption,
+      [],
+    )
+    .option(
+      "--deploy-app <id>",
+      "Deploy app id/slug allowed for publish (repeatable)",
       collectRepeatedOption,
       [],
     )
     .option(
       "--permission <level>",
-      "Permission level: read | write | admin",
+      "Secret permission level: read | write | admin (required when --scope is set)",
       "read",
     )
     .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
     .action(async (opts: CreateApiKeyOptions) => {
       try {
-        if (opts.scope.length === 0) {
+        if (opts.scope.length === 0 && opts.deployApp.length === 0) {
           console.error(
-            chalk.red("Error: at least one --scope <prefix> is required."),
+            chalk.red(
+              "Error: provide at least one --scope <prefix> and/or --deploy-app <id>.",
+            ),
           );
           process.exit(1);
         }
 
         const permission = parsePermission(opts.permission);
         const expiresAt = parseExpires(opts.expires);
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys create");
         const companyUid = await getCompanyUid(
           token,
           (apiKeys.opts() as ApiKeysGroupOptions).company,
@@ -201,8 +233,20 @@ export function registerApiKeysCommand(program: Command): Command {
           body: {
             companyUid,
             name: opts.name,
-            allowedPrefixes: opts.scope,
-            permission,
+            ...(opts.scope.length > 0
+              ? { allowedPrefixes: opts.scope, permission }
+              : {}),
+            ...(opts.deployApp.length > 0
+              ? {
+                  deploy: {
+                    apps: opts.deployApp,
+                    capabilities: ["deploy:write"],
+                  },
+                }
+              : {}),
+            ...(opts.scope.length === 0 && opts.deployApp.length > 0
+              ? { permission }
+              : {}),
             ...(expiresAt ? { expiresAt } : {}),
           },
         });
@@ -225,10 +269,42 @@ export function registerApiKeysCommand(program: Command): Command {
         console.log(
           `  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`,
         );
+        console.log(
+          `  Deploy apps: ${formatDeployApps(data.apiKey.scope.deploy)}`,
+        );
         console.log(`  Status: ${data.apiKey.status}`);
         console.log(`  Created: ${data.apiKey.createdAt}`);
         console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
         console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+        console.log("");
+        console.log(chalk.bold("Usage"));
+        console.log(
+          "  This key acts as you (Cognito identity), limited to the scopes above.",
+        );
+        console.log("  Export it for automation (never falls back to a session):");
+        console.log(`\n  export HQ_API_KEY='${data.key.value}'\n`);
+        console.log("  Vault secrets:");
+        console.log("    hq secrets get <NAME> --reveal");
+        console.log("    hq secrets exec --only <NAME> -- <command>");
+        console.log(
+          "    Or HTTP: POST /v1/keys/secrets/fetch with Authorization: Bearer <key>",
+        );
+        if (data.apiKey.scope.deploy?.apps?.length) {
+          console.log("  Deploy (scoped apps only):");
+          console.log(
+            "    Authorization: Bearer <key> against the hq-deploy API",
+          );
+          console.log(
+            chalk.dim(
+              "    Cannot change access-mode, password, or mint hqd_ keys.",
+            ),
+          );
+        }
+        console.log(
+          chalk.dim(
+            "  Unsupported under HQ_API_KEY: secrets list/set/share/acl (use a Cognito session).",
+          ),
+        );
       } catch (err) {
         console.error(
           chalk.red("Error:"),
@@ -243,7 +319,7 @@ export function registerApiKeysCommand(program: Command): Command {
     .description("List API keys for a company")
     .action(async () => {
       try {
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys list");
         const companyUid = await getCompanyUid(
           token,
           (apiKeys.opts() as ApiKeysGroupOptions).company,
@@ -280,7 +356,7 @@ export function registerApiKeysCommand(program: Command): Command {
     .description("Revoke an API key")
     .action(async (keyId: string) => {
       try {
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys revoke");
         const res = await vaultApiFetch({
           token,
           path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,