@indigoai-us/hq-cli 5.77.11 → 5.77.12

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.77.12]
+
+### Added
+
+- `HQ_API_KEY` fail-closed consume path: `hqk_…` keys route `hq secrets get`
+  / `exec` / `env` through vault key fetch; Cognito-only commands hard-error.
+- `hq api-keys create --deploy-app` (repeatable) and deploy-app column in list
+  output for identity-bound deploy keys. (#270)
+
 ## [5.77.11]
 
 ### Fixed

package/dist/commands/api-keys.js

@@ -1,6 +1,11 @@
 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) {
+    assertCognitoOnlyCommand(label);
+    return ensureCognitoToken();
+}
 function collectRepeatedOption(value, previous) {
     return [...previous, value];
 }
@@ -10,6 +15,11 @@ function formatMaybe(value) {
 function formatPrefixes(prefixes) {
     return prefixes.length > 0 ? prefixes.join(", ") : "-";
 }
+function formatDeployApps(deploy) {
+    if (!deploy?.apps?.length)
+        return "-";
+    return deploy.apps.join(", ");
+}
 function parsePermission(value) {
     if (value === "read" || value === "write" || value === "admin") {
         return value;
@@ -51,6 +61,7 @@ function renderApiKeysTable(apiKeys) {
         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),
@@ -59,6 +70,7 @@ function renderApiKeysTable(apiKeys) {
     const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
     const permissionWidth = Math.max(10, ...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, ...rows.map((row) => row.lastUsedAt.length));
     const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
@@ -67,6 +79,7 @@ function renderApiKeysTable(apiKeys) {
         "NAME".padEnd(nameWidth),
         "PERMISSION".padEnd(permissionWidth),
         "PREFIXES".padEnd(prefixesWidth),
+        "DEPLOY".padEnd(deployWidth),
         "STATUS".padEnd(statusWidth),
         "LAST USED".padEnd(lastUsedWidth),
         "EXPIRES".padEnd(expiresWidth),
@@ -78,6 +91,7 @@ function renderApiKeysTable(apiKeys) {
             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),
@@ -91,20 +105,21 @@ export function registerApiKeysCommand(program) {
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     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)", collectRepeatedOption, [])
-        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--scope <prefix>", "Allowed secret prefix (repeatable)", collectRepeatedOption, [])
+        .option("--deploy-app <id>", "Deploy app id/slug allowed for publish (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Secret permission level: read | write | admin (required when --scope is set)", "read")
         .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
         .action(async (opts) => {
         try {
-            if (opts.scope.length === 0) {
-                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+            if (opts.scope.length === 0 && opts.deployApp.length === 0) {
+                console.error(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().company);
             const res = await vaultApiFetch({
                 token,
@@ -113,8 +128,20 @@ export function registerApiKeysCommand(program) {
                 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 } : {}),
                 },
             });
@@ -131,10 +158,26 @@ export function registerApiKeysCommand(program) {
             console.log(`  Company: ${data.apiKey.companyUid}`);
             console.log(`  Permission: ${data.apiKey.scope.permission}`);
             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:"), err instanceof Error ? err.message : String(err));
@@ -146,7 +189,7 @@ export function registerApiKeysCommand(program) {
         .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().company);
             const res = await vaultApiFetch({
                 token,
@@ -173,7 +216,7 @@ export function registerApiKeysCommand(program) {
         .description("Revoke an API key")
         .action(async (keyId) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys revoke");
             const res = await vaultApiFetch({
                 token,
                 path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,

package/dist/commands/secrets.js

@@ -8,8 +8,14 @@ import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
+import { HQ_API_KEY_PREFIX, assertCognitoOnlyCommand, resolveVaultCredential, } from "../utils/resolve-vault-credential.js";
 import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
+/** Cognito session for secrets commands that do not support HQ_API_KEY. */
+async function requireCognitoTokenForSecrets(commandLabel) {
+    assertCognitoOnlyCommand(commandLabel);
+    return ensureCognitoToken();
+}
 function scopeOpts(opts) {
     if (opts.personal && opts.company) {
         console.error(chalk.red("Error: --personal cannot be combined with --company."));
@@ -424,7 +430,54 @@ function renderPolicyScripts(scripts) {
 // Requests are chunked at MAX_BATCH_NAMES and throw on the FIRST unresolved key
 // with the same `Failed to fetch secret '<k>': <reason>` shape the per-key GET
 // path used — never swallows a failure.
+async function loadRevealedSecretsViaApiKey(token, keys) {
+    const resolved = new Map();
+    const requested = [...new Set(keys)];
+    const cacheScope = "__api_key__";
+    for (const name of requested) {
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/keys/secrets/fetch",
+            method: "POST",
+            body: { name },
+            signal: AbortSignal.timeout(SECRET_LOAD_TIMEOUT_MS),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            if (res.status === 404) {
+                throw new Error(`Failed to fetch secret '${name}': Secret not found`);
+            }
+            if (res.status === 403) {
+                const message = typeof body.error === "string"
+                    ? body.error
+                    : typeof body.message === "string"
+                        ? body.message
+                        : "No read permission";
+                if (body.highSecurity === true) {
+                    throw new Error(highSecuritySandboxOnlyMessage(name));
+                }
+                throw new Error(`Failed to fetch secret '${name}': ${message}`);
+            }
+            if (res.status === 401) {
+                throw new Error(`Failed to fetch secret '${name}': Invalid or missing API key`);
+            }
+            throw new Error(`Failed to fetch secret '${name}': ${extractApiMessage(body, res.statusText)}`);
+        }
+        const secret = typeof body.secret === "object" && body.secret !== null
+            ? body.secret
+            : null;
+        if (typeof secret?.value !== "string") {
+            throw new Error(`Failed to fetch secret '${name}': malformed fetch response`);
+        }
+        removeCacheEntry(cacheScope, name);
+        resolved.set(name, secret.value);
+    }
+    return resolved;
+}
 export async function loadRevealedSecrets(token, companyUid, keys, usage) {
+    if (token.startsWith(HQ_API_KEY_PREFIX)) {
+        return loadRevealedSecretsViaApiKey(token, keys);
+    }
     const resolved = new Map();
     const requested = [...new Set(keys)];
     try {
@@ -632,7 +685,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Secret value exceeds 4096-byte SSM limit (got ${Buffer.byteLength(value, "utf8")} bytes).`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets set");
             const scope = scopeOpts(secrets.opts());
             const companyUid = await getEntityUid(token, scope);
             const scopeLabel = describeSecretsScope({
@@ -677,7 +730,52 @@ export function registerSecretsCommand(program) {
         .option("--reveal", "Include the decrypted secret value")
         .action(async (name, opts) => {
         try {
-            const token = await ensureCognitoToken();
+            const cred = await resolveVaultCredential();
+            if (cred.kind === "api-key") {
+                const res = await vaultApiFetch({
+                    token: cred.token,
+                    path: "/v1/keys/secrets/fetch",
+                    method: "POST",
+                    body: { name },
+                });
+                const body = (await res.json().catch(() => ({})));
+                if (!res.ok) {
+                    if (res.status === 403 && body.highSecurity === true) {
+                        console.error(chalk.red(highSecuritySandboxOnlyMessage(name)));
+                        process.exit(1);
+                    }
+                    console.error(chalk.red(`Failed to get secret: ${extractApiMessage(body, res.statusText)}`));
+                    process.exit(1);
+                }
+                const secret = typeof body.secret === "object" && body.secret !== null
+                    ? body.secret
+                    : null;
+                if (!secret || typeof secret.name !== "string") {
+                    console.error(chalk.red("Failed to get secret: malformed response"));
+                    process.exit(1);
+                }
+                console.log(chalk.bold(`Secret: ${secret.name}`));
+                if (secret.lastModifiedDate) {
+                    console.log(`  Last Modified: ${secret.lastModifiedDate}`);
+                }
+                if (secret.version != null) {
+                    console.log(`  Version:       ${secret.version}`);
+                }
+                console.log(`  Tier:          ${normalizeSecretTier(secret.tier)}`);
+                console.log(`  Script Lock:   ${normalizeScriptLockMode(secret.scriptLock?.mode)}`);
+                if (opts.reveal) {
+                    if (typeof secret.value !== "string") {
+                        console.error(chalk.red("Failed to get secret: reveal requested but response omitted secret.value"));
+                        process.exit(1);
+                    }
+                    console.log(`  Value:         ${secret.value}`);
+                }
+                else {
+                    console.log(`  Value:         ${chalk.dim("[REDACTED]")}`);
+                }
+                return;
+            }
+            const token = cred.token;
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -748,7 +846,7 @@ export function registerSecretsCommand(program) {
         .option("--quiet", "Suppress the present/absent line (use the exit code only)")
         .action(async (name, opts) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets exists");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -791,7 +889,7 @@ export function registerSecretsCommand(program) {
                 }
                 normalizedPrefix = normalized;
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets list");
             const scope = scopeOpts(secrets.opts());
             const companyUid = await getEntityUid(token, scope);
             const scopeLabel = describeSecretsScope({
@@ -865,7 +963,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -926,7 +1024,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Error: provide at least one of --tier or --lock-script."));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -971,7 +1069,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const usage = await buildSecretUsage("exec", opts.script, opts.id, opts.attestation);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1009,7 +1107,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1040,7 +1138,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1087,7 +1185,7 @@ export function registerSecretsCommand(program) {
                     return;
                 }
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1131,7 +1229,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(opts.only);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
             const companyUid = await getEntityUid(token, scope);
             const client = new SandboxRunnerClient();
@@ -1184,9 +1282,13 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("exec", _opts.script, _opts.scriptId));
+            const cred = await resolveVaultCredential();
+            const companyUid = cred.kind === "api-key"
+                ? "__api_key__"
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+                ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
+                : undefined);
             const secretEnv = {};
             for (const key of keys) {
                 const value = revealed.get(key);
@@ -1231,9 +1333,13 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
             }
             const keys = parseSecretNameList(opts.only);
-            const token = await ensureCognitoToken();
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
-            const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("env", opts.script, opts.scriptId));
+            const cred = await resolveVaultCredential();
+            const companyUid = cred.kind === "api-key"
+                ? "__api_key__"
+                : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
+            const revealed = await loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
+                ? await buildSecretUsage("env", opts.script, opts.scriptId)
+                : undefined);
             for (const key of keys) {
                 const value = revealed.get(key);
                 // loadRevealedSecrets throws on any unresolved key, so a miss here is
@@ -1270,7 +1376,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Maximum expiry is 7 days (7d)."));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1316,7 +1422,7 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1373,7 +1479,7 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1422,7 +1528,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${path}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoTokenForSecrets("secrets");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const secretPath = path;
             const res = await vaultApiFetch({

package/dist/utils/resolve-vault-credential.d.ts

@@ -0,0 +1,30 @@
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export declare 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 declare function peekHqApiKey(): string | 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 declare function resolveVaultCredential(options?: {
+    interactive?: boolean;
+}): Promise<VaultCredential>;
+/**
+ * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
+ * (list, set, ACL, api-keys admin, etc.).
+ */
+export declare function assertCognitoOnlyCommand(commandLabel: string): void;
+//# sourceMappingURL=resolve-vault-credential.d.ts.map

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/package.json

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

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();
   });