@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/dist/commands/files-browse.js

@@ -40,8 +40,9 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
 import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
-import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
-import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, buildVaultConfig, } from "../utils/cognito-session.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
+import { getCompanyUid, looksLikeCompanyUid, vaultApiFetch, } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 // ── Pure helpers ────────────────────────────────────────────────────────────
 /**
@@ -636,6 +637,119 @@ export function createCompanyPresignClient(input) {
 function makeCompanyPresignFactory(token) {
     return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
 }
+// ── HQ_API_KEY vault client (keyed routes only) ──────────────────────────────
+/** Fail-closed error the top-level handler prints without a Sentry report. */
+function apiKeyUnsupported(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+/**
+ * Bucket name handed to the orchestrators on the keyed company path.
+ *
+ * `runBrowse`/`runCat`/`runGet` require a non-empty `bucketName` and pass it as
+ * `Bucket` on each S3-shaped command, but the keyed client sends
+ * `/v1/keys/files/list` + `/v1/keys/files/presign`, which resolve the real
+ * bucket server-side from the company uid — so this value is never read.
+ */
+const API_KEY_BUCKET_RESOLVED_SERVER_SIDE = "resolved-server-side";
+/**
+ * `FilesBrowseVaultClient` for a Bearer `hqk_` key.
+ *
+ * `VaultClient` talks to the Cognito-JWT routes directly — it never passes
+ * through `vaultApiFetch`, so it cannot be handed an `hqk_` token: the key
+ * would arrive at a JWT-only route and come back as a 401 that reads like the
+ * caller is logged out. Company browse/cat/get/search need only three things
+ * from the client, and each has a keyed answer:
+ *
+ *   - the company uid — supplied explicitly (`--company cmp_…` or
+ *     HQ_COMPANY_UID). A key is company-bound and entity slug resolution has no
+ *     keyed route, so a slug is refused rather than guessed.
+ *   - the bucket name — unused on this path (see the constant above).
+ *   - the caller's explicit grants — `GET /v1/keys/files/grants` (files:read),
+ *     so the `shared-with-you` vs `role-bypass` column stays accurate.
+ *
+ * The identity surfaces a key cannot reach (`sts.vend`/`vendSelf` for the
+ * personal vault, `entity.get`, `listMyMemberships` for the cross-company
+ * roll-up) throw a fail-closed error naming the Cognito requirement.
+ */
+export function createApiKeyBrowseVaultClient(token) {
+    const needsCognito = (surface) => apiKeyUnsupported(`HQ_API_KEY is set; ${surface} is not supported for API keys — hq-pro ` +
+        `serves no vault API-key route for it. Unset HQ_API_KEY to use your ` +
+        `Cognito session.`);
+    return {
+        sts: {
+            vend: () => {
+                throw needsCognito("STS credential vending");
+            },
+            vendSelf: () => {
+                throw needsCognito("the personal vault (--personal)");
+            },
+        },
+        async listMyExplicitGrants(companyUid) {
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/files/grants",
+                query: { company: companyUid },
+            });
+            if (!res.ok) {
+                const body = (await res.json().catch(() => ({})));
+                throw new Error(body.message ?? body.error ?? `files grants failed (${res.status})`);
+            }
+            const body = (await res.json());
+            return body.grants ?? [];
+        },
+        listMyMemberships: () => {
+            throw needsCognito("the cross-company roll-up");
+        },
+        entity: {
+            get: () => {
+                throw needsCognito("entity lookup by uid");
+            },
+            findInMyNamespace: async (_type, ref) => {
+                // A key cannot resolve a slug (no keyed `/entity/check-slug/me`), so the
+                // company must already be a uid. The CLI layer resolves `--company` /
+                // HQ_COMPANY_UID through `getCompanyUid`, which rejects a slug under a
+                // key — this guard covers a path-derived slug reaching us anyway.
+                if (!looksLikeCompanyUid(ref)) {
+                    throw apiKeyUnsupported(`HQ_API_KEY is set; the company must be a uid (cmp_…) — resolving ` +
+                        `the slug '${ref}' needs a Cognito session. Pass --company cmp_… ` +
+                        `(or set HQ_COMPANY_UID) and anchor the path at ` +
+                        `'companies/cmp_…/'.`);
+                }
+                return {
+                    uid: ref,
+                    slug: ref,
+                    bucketName: API_KEY_BUCKET_RESOLVED_SERVER_SIDE,
+                };
+            },
+        },
+    };
+}
+/** Fail-closed error for `--personal` (and the roll-up) under an API key. */
+function personalVaultNeedsCognito() {
+    return apiKeyUnsupported(`HQ_API_KEY is set; --personal is not supported for API keys — a key is ` +
+        `company-bound and the personal vault is reached by vending STS ` +
+        `credentials, which no /v1/keys route serves. Target a company with ` +
+        `--company cmp_… instead, or unset HQ_API_KEY to use your Cognito session.`);
+}
+/**
+ * The caller's credential plus the vault client that can carry it.
+ *
+ * `cognito` is undefined under HQ_API_KEY: `VaultClient` speaks only the JWT
+ * routes, so the keyed adapter stands in for the company path — and the
+ * personal path, which needs `VaultClient.entity.listByType` plus an STS vend,
+ * has nothing to run on and must fail closed at its branch.
+ */
+async function resolveBrowseSession() {
+    const cred = await resolveVaultCredential();
+    if (cred.kind === "api-key") {
+        return {
+            token: cred.token,
+            client: createApiKeyBrowseVaultClient(cred.token),
+        };
+    }
+    const cognito = new VaultClient(buildVaultConfig(cred.token));
+    return { token: cred.token, client: cognito, cognito };
+}
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group
@@ -659,23 +773,23 @@ export function registerFilesBrowseCommands(filesCmd) {
             if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
-            const accessToken = await ensureCognitoToken();
-            const vaultConfig = buildVaultConfig(accessToken);
-            const client = new VaultClient(vaultConfig);
+            const { token: accessToken, client, cognito } = await resolveBrowseSession();
             if (options.personal) {
+                if (!cognito)
+                    throw personalVaultNeedsCognito();
                 // Personal-vault path. Resolve the caller's canonical person
                 // entity once; the orchestrator does the bucket lookup + vend.
                 // Empty [path] → list bucket root.
                 const personalUid = await resolveCanonicalPersonUid({
-                    listMyMemberships: () => client.listMyMemberships(),
-                    listPersonEntities: () => client.entity.listByType("person"),
+                    listMyMemberships: () => cognito.listMyMemberships(),
+                    listPersonEntities: () => cognito.entity.listByType("person"),
                     getEntity: async () => null,
                 });
                 const result = await runBrowse({
                     pathPrefix: pathArg ?? "",
                     personalMode: true,
                     personalUid,
-                    vaultClient: client,
+                    vaultClient: cognito,
                     s3Factory: defaultS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
@@ -746,13 +860,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
-            const accessToken = await ensureCognitoToken();
-            const vaultConfig = buildVaultConfig(accessToken);
-            const client = new VaultClient(vaultConfig);
+            const { token: accessToken, client, cognito } = await resolveBrowseSession();
             if (options.personal) {
+                if (!cognito)
+                    throw personalVaultNeedsCognito();
                 const personalUid = await resolveCanonicalPersonUid({
-                    listMyMemberships: () => client.listMyMemberships(),
-                    listPersonEntities: () => client.entity.listByType("person"),
+                    listMyMemberships: () => cognito.listMyMemberships(),
+                    listPersonEntities: () => cognito.entity.listByType("person"),
                     getEntity: async () => null,
                 });
                 const result = await runCat({
@@ -761,7 +875,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                     hqRoot: options.hqRoot,
                     personalMode: true,
                     personalUid,
-                    vaultClient: client,
+                    vaultClient: cognito,
                     s3Factory: defaultS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
@@ -811,9 +925,16 @@ export function registerFilesBrowseCommands(filesCmd) {
         try {
             // `--company` is bound on the parent `files` group — read merged opts.
             const company = command.optsWithGlobals().company;
-            const accessToken = await ensureCognitoToken();
-            const vaultConfig = buildVaultConfig(accessToken);
-            const client = new VaultClient(vaultConfig);
+            const { token: accessToken, client, cognito } = await resolveBrowseSession();
+            // The roll-up fans out over `listMyMemberships` + `entity.get`, neither
+            // of which a key can reach. Refuse up front so the caller is told to
+            // scope the query instead of watching it fail mid-fan-out.
+            if (!cognito && !company) {
+                throw apiKeyUnsupported(`HQ_API_KEY is set; the cross-company roll-up is not supported for ` +
+                    `API keys — a key is bound to one company and the roll-up needs ` +
+                    `your membership graph. Scope it with --company cmp_… (or set ` +
+                    `HQ_COMPANY_UID), or unset HQ_API_KEY.`);
+            }
             let companyUid;
             if (company) {
                 // Confirm membership + resolve UID, same early-failure pattern as
@@ -845,12 +966,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
-            const accessToken = await ensureCognitoToken();
-            const client = new VaultClient(buildVaultConfig(accessToken));
+            const { token: accessToken, client, cognito } = await resolveBrowseSession();
             if (options.personal) {
+                if (!cognito)
+                    throw personalVaultNeedsCognito();
                 const personalUid = await resolveCanonicalPersonUid({
-                    listMyMemberships: () => client.listMyMemberships(),
-                    listPersonEntities: () => client.entity.listByType("person"),
+                    listMyMemberships: () => cognito.listMyMemberships(),
+                    listPersonEntities: () => cognito.entity.listByType("person"),
                     getEntity: async () => null,
                 });
                 const rows = await runSearch({
@@ -858,7 +980,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                     companySlug: "personal",
                     personalMode: true,
                     personalUid,
-                    vaultClient: client,
+                    vaultClient: cognito,
                     s3Factory: defaultS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
@@ -891,8 +1013,7 @@ export function registerFilesBrowseCommands(filesCmd) {
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .action(async (pathArg, options, command) => {
         try {
-            const accessToken = await ensureCognitoToken();
-            const client = new VaultClient(buildVaultConfig(accessToken));
+            const { token: accessToken, client } = await resolveBrowseSession();
             // `--company` is bound on the parent `files` group — read merged opts.
             const companyOpt = command.optsWithGlobals().company;
             const slug = companyOpt ?? parseCompanySlugFromPath(pathArg);

package/dist/commands/files.js

@@ -1,7 +1,8 @@
 import chalk from "chalk";
 import open from "open";
 import * as readline from "node:readline";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
+import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
 // ---------------------------------------------------------------------------
@@ -92,6 +93,31 @@ export function registerFilesCommand(program) {
         .command("files")
         .description("Manage file access controls in HQ vault")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
+    // An exported HQ_API_KEY must never fall back to the caller's Cognito session
+    // (that would ignore the key's scope entirely), so every subcommand is gated.
+    //
+    // hq-pro serves keyed `/v1/keys/files/…` parallels for the LIST-shaped reads
+    // (`list`, `versions`, `versions-list`, `grants`, `tombstones`) and the
+    // presign/delete/restore writes — those subcommands work under a key. The ACL
+    // and share-session surfaces are still Cognito-only: they live on the
+    // unversioned `/files/{companyUid}/acl…` + `/share-session` routes, which have
+    // no `/v1/keys` parallel. Marking them `routeAvailable: false` fails them
+    // closed AT THE GATE with the capability named, instead of letting the key
+    // travel to a JWT-only route and come back as a login-looking 401.
+    gateApiKeyCapabilities(files, {
+        default: "files:read",
+        bySubcommand: {
+            share: { capability: "files:write", routeAvailable: false },
+            unshare: { capability: "files:write", routeAvailable: false },
+            acl: { capability: "files:read", routeAvailable: false },
+            delete: "files:write",
+            restore: "files:write",
+            // `hq files search` filters a `/v1/files/list` listing (see runSearch) —
+            // it does NOT call the content-search route, so `files:read` is the
+            // capability hq-pro will actually check on `/v1/keys/files/list`.
+            search: "files:read",
+        },
+    });
     files
         .command("share [paths...]")
         .description("Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
@@ -184,7 +210,7 @@ export function registerFilesCommand(program) {
                     ? principal.trim().toLowerCase()
                     : principal;
             const principalLabel = isAll ? "everyone in the company" : granteeId;
-            const token = await ensureCognitoToken();
+            const token = (await resolveVaultCredential()).token;
             const companySlug = files.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
             const res = await vaultApiFetch({
@@ -239,7 +265,7 @@ export function registerFilesCommand(program) {
         .action(async (prefix) => {
         try {
             const canonicalPrefix = normalizeFilePrefix(prefix);
-            const token = await ensureCognitoToken();
+            const token = (await resolveVaultCredential()).token;
             const companySlug = files.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
             // `/acl/tree` carries the prefix's own row metadata (directRow) and the
@@ -477,7 +503,7 @@ async function runDirectGrant(params) {
             : principal;
     // Display label used in success messages — `@all` reads better than `""`.
     const principalLabel = isAll ? "everyone in the company" : granteeId;
-    const token = await ensureCognitoToken();
+    const token = (await resolveVaultCredential()).token;
     const companyUid = await getCompanyUid(token, params.companySlug);
     let res = await vaultApiFetch({
         token,
@@ -555,7 +581,7 @@ async function runShareSession(params) {
         }
         expiresInMs = parsed;
     }
-    const token = await ensureCognitoToken();
+    const token = (await resolveVaultCredential()).token;
     const companyUid = await getCompanyUid(token, params.companySlug);
     let session;
     try {
@@ -721,7 +747,7 @@ export async function runFilesDelete(params, deps = {}) {
         console.error(chalk.red("Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key."));
         process.exit(1);
     }
-    const token = await ensureCognitoToken();
+    const token = (await resolveVaultCredential()).token;
     // Personal scope resolves the vault server-side from the caller's identity —
     // no company to look up. Company scope resolves the companyUid as before.
     const companyUid = params.personal
@@ -905,7 +931,7 @@ function formatFilesRecoveryError(err, key) {
 }
 async function resolveRecoveryScope(params) {
     assertRecoveryScope(params.personal, params.companySlug);
-    const token = await ensureCognitoToken();
+    const token = (await resolveVaultCredential()).token;
     if (params.personal) {
         return { token, personal: true };
     }

package/dist/commands/members.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
+import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
@@ -369,6 +370,16 @@ export function registerMembersCommand(program) {
         .command("members")
         .description("Manage company memberships and invites")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
+    // Membership routes are Cognito-JWT only today; an API key must fail closed
+    // rather than fall back to the caller's session.
+    gateApiKeyCapabilities(members, {
+        default: "members:read",
+        bySubcommand: {
+            promote: "members:write",
+            invite: "members:write",
+            revoke: "members:write",
+        },
+    });
     // Canonical role-change command. `promote` is the discoverable verb users
     // reach for; `set-role` is kept as an alias for the older name. The route is a
     // GENERAL role change, so the help text and success message are honest that it
@@ -386,7 +397,7 @@ export function registerMembersCommand(program) {
                 console.error(chalk.red(`Invalid role '${newRole}': must be one of owner, admin, member, guest`));
                 process.exit(1);
             }
-            const token = await ensureCognitoToken();
+            const token = (await resolveVaultCredential()).token;
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
             const membershipKey = await resolveRoleChangeTarget(token, companyUid, target);
@@ -425,7 +436,7 @@ export function registerMembersCommand(program) {
         let companyUid;
         let companySlug;
         try {
-            token = await ensureCognitoToken();
+            token = (await resolveVaultCredential()).token;
             companySlug = members.opts().company;
             companyUid = await getCompanyUid(token, companySlug);
             const callerUid = await getCallerPersonUid(token);
@@ -608,7 +619,7 @@ export function registerMembersCommand(program) {
         .option("--pending", "List pending invites instead of active members")
         .action(async (opts) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = (await resolveVaultCredential()).token;
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
             if (opts.pending) {
@@ -677,7 +688,7 @@ export function registerMembersCommand(program) {
         .description("Revoke a pending invite. Accepts an email, personUid, full membershipKey, or legacy inviteToken.")
         .action(async (target) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = (await resolveVaultCredential()).token;
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
             const membershipKey = resolveRevokeTargetToMembershipKey(target, companyUid);

package/dist/commands/pack-install.d.ts

@@ -125,6 +125,19 @@ export interface MarketplaceDeps {
     download: (url: string) => Promise<Uint8Array | {
         expired: true;
     }>;
+    /**
+     * Record the install against the listing (`POST /v1/listings/{id}/installs`).
+     *
+     * Load-bearing under HQ_API_KEY: browse + download are PUBLIC, so this is the
+     * only call that ever presents the key — which makes it the only place hq-pro
+     * can enforce `packs:install` on the key's REAL grants. The CLI-side
+     * capability gate can check the catalog, never the presented key. Optional so
+     * test doubles written before the keyed wire keep compiling.
+     */
+    recordInstall?: (input: {
+        listingId: string;
+        companySlug?: string;
+    }) => Promise<void>;
 }
 interface RawListingSummary {
     listingId?: string;
@@ -167,6 +180,7 @@ export declare function defaultMarketplaceDeps(): MarketplaceDeps;
  */
 export declare function fetchMarketplace(source: string, tmpDir: string, deps: MarketplaceDeps, opts?: {
     requireSignature?: boolean;
+    company?: string;
 }): Promise<FetchResult>;
 export interface LatestResult {
     transport: Transport;

package/dist/commands/pack-install.js

@@ -49,8 +49,9 @@ import { findHqRoot } from '../utils/manifest.js';
 import { readHqVersion, routeContribution, listInstalledPacks } from '../utils/pack-contributions.js';
 import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
 import { safeExtractTarball } from './safe-extract.js';
-import { getCompanyUid, vaultApiFetchPublic } from '../utils/vault-api.js';
+import { getCompanyUid, vaultApiFetch, vaultApiFetchPublic, } from '../utils/vault-api.js';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { formatApiKeyCapabilityDenial, peekHqApiKey, } from '../utils/resolve-vault-credential.js';
 import { redactSecrets, SECRET_REDACTION, registerMcpServers, McpManifestError, } from './mcp-registration.js';
 import { listSecretCacheScopes } from '../utils/secrets-cache.js';
 import { loadRevealedSecrets } from './secrets.js';
@@ -375,6 +376,31 @@ export function defaultMarketplaceDeps() {
             }
             return new Uint8Array(await response.arrayBuffer());
         },
+        recordInstall: async ({ listingId, companySlug }) => {
+            // Only the API-key path calls this. A Cognito (or logged-out) install
+            // stays on the public browse+download wire — `hq install` must keep
+            // working without a login, and forcing one here would be a regression.
+            const apiKey = peekHqApiKey();
+            if (apiKey === undefined)
+                return;
+            const res = await vaultApiFetch({
+                token: apiKey,
+                // Rewritten to POST /v1/keys/listings/{id}/installs, which hq-pro
+                // serves behind `requireCapability: 'packs:install'`.
+                path: `/v1/listings/${encodeURIComponent(listingId)}/installs`,
+                method: 'POST',
+                body: companySlug
+                    ? { scope: 'company', companySlug }
+                    : { scope: 'personal' },
+            });
+            if (res.ok)
+                return;
+            const body = (await res.json().catch(() => ({})));
+            // 403 carries hq-pro's granted/missing capability report — render it so
+            // the operator sees what the presented key actually holds.
+            throw Object.assign(new Error(formatApiKeyCapabilityDenial(body, `HQ_API_KEY was refused for this install (HTTP ${res.status}). ` +
+                `The key needs the 'packs:install' capability.`)), { expected: true });
+        },
     };
 }
 /**
@@ -389,6 +415,17 @@ export function defaultMarketplaceDeps() {
 export async function fetchMarketplace(source, tmpDir, deps, opts = {}) {
     const { slug, version } = parseMarketplaceSource(source);
     let listing = await deps.resolveListing(slug, version);
+    // Authorize the install SERVER-side before pulling any bytes. Under
+    // HQ_API_KEY this is the only call that presents the key, so it is what
+    // actually enforces `packs:install` against the key's real grants — the
+    // listing browse + tarball download are both public and would happily serve
+    // a key that holds nothing. A no-op on the Cognito path.
+    if (deps.recordInstall) {
+        await deps.recordInstall({
+            listingId: listing.listingId,
+            ...(opts.company !== undefined ? { companySlug: opts.company } : {}),
+        });
+    }
     // Download with a single expired-URL retry: a presigned URL can expire
     // between resolve and download, surfacing as a raw S3 403. We re-resolve the
     // detail by id to mint a fresh URL and retry ONCE rather than leaking the 403.
@@ -1649,7 +1686,10 @@ export async function installPack(source, opts = {}) {
                 fetched = fetchLocal(source, tmpDir);
                 break;
             case 'marketplace':
-                fetched = await fetchMarketplace(source, tmpDir, opts.marketplaceDeps ?? defaultMarketplaceDeps(), { requireSignature: opts.requireSignature });
+                fetched = await fetchMarketplace(source, tmpDir, opts.marketplaceDeps ?? defaultMarketplaceDeps(), {
+                    requireSignature: opts.requireSignature,
+                    ...(opts.company !== undefined ? { company: opts.company } : {}),
+                });
                 break;
         }
         const pkg = validateManifest(fetched.payloadDir, hqVersion);

package/dist/commands/pkg-install.js

@@ -23,8 +23,41 @@ 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 { peekHqApiKey, requireApiKeyCapability, } from '../utils/resolve-vault-credential.js';
 import { MARKETPLACE_PREFIX, installPack, sourceMatchesPackPattern, } from './pack-install.js';
+/**
+ * True when `source` installs through the marketplace — an explicit
+ * `marketplace:` source, or a bare slug (which the dispatch below rewrites into
+ * one). Every other shape (npm scope, git URL, local path) is fetched from npm,
+ * GitHub, or the filesystem.
+ */
+function isMarketplaceInstall(source) {
+    return (source.startsWith(MARKETPLACE_PREFIX) || !sourceMatchesPackPattern(source));
+}
+/**
+ * Refuse an `HQ_API_KEY` install whose transport never presents the key.
+ *
+ * `requireApiKeyCapability` can only confirm that hq-cli KNOWS `packs:install`;
+ * the key's real grants live on the server. The marketplace transport gets them
+ * checked, because it records the install at
+ * `POST /v1/keys/listings/{id}/installs` (see `MarketplaceDeps.recordInstall`).
+ * An npm/git/local source talks to npm, GitHub, or the filesystem and never
+ * reaches hq-pro, so a key holding no capabilities at all would install exactly
+ * as well as a fully scoped one — the gate would be theatre. Fail closed and
+ * name the two ways forward.
+ */
+function assertApiKeyCanAuthorizeInstall(source) {
+    if (peekHqApiKey() === undefined)
+        return;
+    if (isMarketplaceInstall(source))
+        return;
+    throw Object.assign(new Error(`HQ_API_KEY is set; 'hq install ${source}' is not supported for API keys ` +
+        `— this source is fetched directly from npm/git/disk, so hq-pro never ` +
+        `sees the key and cannot enforce 'packs:install'.\n` +
+        `  Install from the marketplace instead (a bare slug or ` +
+        `'marketplace:<slug>'), where the key IS authorized server-side.\n` +
+        `  Unset HQ_API_KEY to use your Cognito session.`), { expected: true });
+}
 export function registerPackageInstallCommand(parent) {
     parent
         .command('install <source>')
@@ -40,7 +73,11 @@ export function registerPackageInstallCommand(parent) {
             // 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');
+            //
+            // Capability gate: under HQ_API_KEY the install must present a key
+            // with packs:install (hq-pro serves POST /v1/keys/listings/…/installs).
+            requireApiKeyCapability('packs:install', 'hq install');
+            assertApiKeyCanAuthorizeInstall(source);
             if (sourceMatchesPackPattern(source)) {
                 await installPack(source, {
                     company: opts.company,

package/dist/commands/run.js

@@ -3,7 +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 { apiKeyCapabilityGateMessage, 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';
@@ -39,8 +39,12 @@ export function registerRunCommand(program) {
         .allowUnknownOption(true)
         .action(async (opts) => {
         try {
+            // `hq run` batch-loads through `/secrets/{uid}/load`, which has no
+            // Bearer `hqk_` parallel route — `hq secrets exec` is the API-key path.
             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`.');
+                throw new Error(`${apiKeyCapabilityGateMessage('secrets:read', 'hq run', {
+                    routeAvailable: false,
+                })}\n  Use \`hq secrets exec --only <NAME> -- <command>\` with this key instead.`);
             }
             const dashIndex = process.argv.indexOf('--');
             const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];