@indigoai-us/hq-cli 5.47.10 → 5.47.11

package/src/commands/secrets.ts

@@ -2,13 +2,16 @@ import { Command } from "commander";
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
+import * as nodePath from "node:path";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import {
+  DEFAULT_SECRETS_CACHE_TTL_MS,
   readCache,
   writeCache,
   removeCacheEntry,
   clearAllCache,
 } from "../utils/secrets-cache.js";
+import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
 import {
   vaultApiFetch,
@@ -157,6 +160,192 @@ function promptSecretInteractively(): Promise<string> {
 // server (the legacy per-key GET path had no such cap).
 const MAX_BATCH_NAMES = 100;
 
+export type SecretTier = "standard" | "sensitive" | "nuclear";
+export type SecretScriptLockMode = "off" | "enforced";
+export type SecretUsageChannel =
+  | "run"
+  | "exec"
+  | "env"
+  | "reveal"
+  | "submit-link";
+
+export interface SecretScriptUsage {
+  scriptId: string;
+  path: string;
+  sha256: string;
+  attestationLevel: string;
+}
+
+export interface SecretUsage {
+  channel: SecretUsageChannel;
+  reason?: string;
+  script?: SecretScriptUsage;
+}
+
+export interface SecretMetadata {
+  tier?: SecretTier;
+  scriptLock?: {
+    mode?: SecretScriptLockMode;
+    requiredAttestation?: string;
+  };
+  cacheTtlMs?: number;
+}
+
+export interface SecretLoadSuccessRow extends SecretMetadata {
+  name: string;
+  value?: string;
+}
+
+export interface SecretLoadResponse {
+  secrets: SecretLoadSuccessRow[];
+  errors: Array<{ name: string; code: string; message?: string }>;
+}
+
+interface SecretGetResponse {
+  secret: {
+    name: string;
+    companyUid: string;
+    type?: string;
+    lastModifiedDate?: string;
+    version?: number;
+    value?: string;
+  } & SecretMetadata;
+}
+
+interface SecretPolicyScript {
+  scriptId: string;
+  scriptPath: string;
+  sha256: string;
+  attestationLevel: string;
+}
+
+interface SecretPolicyRecord {
+  path: string;
+  tier?: SecretTier;
+  scriptLock?: {
+    mode?: SecretScriptLockMode;
+    requiredAttestation?: string;
+  };
+  scripts?: SecretPolicyScript[];
+}
+
+interface SecretPolicyResponse {
+  policy?: SecretPolicyRecord;
+  scripts?: SecretPolicyScript[];
+}
+
+function normalizeSecretTier(tier?: string): SecretTier {
+  return tier === "sensitive" || tier === "nuclear" ? tier : "standard";
+}
+
+function normalizeScriptLockMode(mode?: string): SecretScriptLockMode {
+  return mode === "enforced" ? "enforced" : "off";
+}
+
+function normalizeCacheTtlMs(cacheTtlMs?: number): number {
+  return typeof cacheTtlMs === "number"
+    ? cacheTtlMs
+    : DEFAULT_SECRETS_CACHE_TTL_MS;
+}
+
+function extractApiMessage(
+  body: Record<string, unknown>,
+  fallback: string,
+): string {
+  const message = typeof body.message === "string" ? body.message : undefined;
+  const error = typeof body.error === "string" ? body.error : undefined;
+  return message ?? error ?? fallback;
+}
+
+async function buildSecretUsage(
+  channel: SecretUsageChannel,
+  scriptPath?: string,
+  scriptId?: string,
+  attestationLevel = "self-asserted-hash",
+): Promise<SecretUsage> {
+  if (!scriptPath) {
+    return { channel };
+  }
+  const resolvedPath = nodePath.resolve(scriptPath);
+  return {
+    channel,
+    script: {
+      scriptId: scriptId ?? resolvedPath,
+      path: resolvedPath,
+      sha256: await computeSha256(resolvedPath),
+      attestationLevel,
+    },
+  };
+}
+
+function normalizePolicyRecord(
+  secretPath: string,
+  data: SecretPolicyResponse,
+): SecretPolicyRecord & { scripts: SecretPolicyScript[] } {
+  const policy = data.policy ?? { path: secretPath };
+  const scripts = Array.isArray(policy.scripts)
+    ? policy.scripts
+    : Array.isArray(data.scripts)
+      ? data.scripts
+      : [];
+  return {
+    path: policy.path ?? secretPath,
+    tier: normalizeSecretTier(policy.tier),
+    scriptLock: {
+      mode: normalizeScriptLockMode(policy.scriptLock?.mode),
+      requiredAttestation: policy.scriptLock?.requiredAttestation,
+    },
+    scripts,
+  };
+}
+
+function renderPolicySummary(policy: SecretPolicyRecord): void {
+  console.log(chalk.bold(`Policy: ${policy.path}`));
+  console.log(`  Tier:          ${normalizeSecretTier(policy.tier)}`);
+  console.log(
+    `  Script Lock:   ${normalizeScriptLockMode(policy.scriptLock?.mode)}`,
+  );
+  if (policy.scriptLock?.requiredAttestation) {
+    console.log(
+      `  Attestation:   ${policy.scriptLock.requiredAttestation}`,
+    );
+  }
+}
+
+function renderPolicyScripts(scripts: SecretPolicyScript[]): void {
+  if (scripts.length === 0) {
+    console.log(chalk.dim("No approved scripts."));
+    return;
+  }
+
+  const idWidth = Math.max(2, ...scripts.map((script) => script.scriptId.length));
+  const pathWidth = Math.max(
+    6,
+    ...scripts.map((script) => script.scriptPath.length),
+  );
+  const attestationWidth = Math.max(
+    11,
+    ...scripts.map((script) => script.attestationLevel.length),
+  );
+  const header = [
+    "ID".padEnd(idWidth),
+    "SCRIPT".padEnd(pathWidth),
+    "ATTESTATION".padEnd(attestationWidth),
+    "SHA256",
+  ].join("  ");
+  console.log(chalk.bold(header));
+  for (const script of scripts) {
+    console.log(
+      [
+        script.scriptId.padEnd(idWidth),
+        script.scriptPath.padEnd(pathWidth),
+        script.attestationLevel.padEnd(attestationWidth),
+        script.sha256,
+      ].join("  "),
+    );
+  }
+}
+
 // HQ-4H — load + decrypt secrets through the BATCH-LOAD endpoint
 // (`POST /secrets/{companyUid}/load`) instead of one single-secret GET per key.
 //
@@ -179,6 +368,7 @@ export async function loadRevealedSecrets(
   token: string,
   companyUid: string,
   keys: string[],
+  usage?: SecretUsage,
 ): Promise<Map<string, string>> {
   const resolved = new Map<string, string>();
   const missing: string[] = [];
@@ -197,18 +387,23 @@ export async function loadRevealedSecrets(
       token,
       path: `/secrets/${encodeURIComponent(companyUid)}/load`,
       method: "POST",
-      body: { names: chunk },
+      body: usage ? { names: chunk, usage } : { names: chunk },
     });
     if (!res.ok) {
-      const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+      const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      const message = extractApiMessage(body, res.statusText);
+      if (
+        res.status >= 400 &&
+        res.status < 500 &&
+        typeof body.code === "string"
+      ) {
+        throw new Error(message);
+      }
       throw new Error(
-        `Failed to batch-load secrets: ${body.error ?? res.statusText}`,
+        `Failed to batch-load secrets: ${message}`,
       );
     }
-    const data = (await res.json()) as {
-      secrets: Array<{ name: string; value?: string }>;
-      errors: Array<{ name: string; code: string; message?: string }>;
-    };
+    const data = (await res.json()) as SecretLoadResponse;
 
     for (const s of data.secrets ?? []) {
       if (s.value == null) {
@@ -216,7 +411,10 @@ export async function loadRevealedSecrets(
           `Secret '${s.name}' has no value (reveal may not be permitted).`,
         );
       }
-      writeCache(companyUid, s.name, s.value);
+      const cacheTtlMs = normalizeCacheTtlMs(s.cacheTtlMs);
+      if (cacheTtlMs > 0) {
+        writeCache(companyUid, s.name, s.value, cacheTtlMs);
+      }
       resolved.set(s.name, s.value);
     }
 
@@ -333,35 +531,32 @@ export function registerSecretsCommand(program: Command): void {
           scopeOpts(secrets.opts()),
         );
 
-        const query: Record<string, string> = {};
-        if (opts.reveal) {
-          query.reveal = "true";
-        }
-
         const res = await vaultApiFetch({
           token,
           path: buildSecretNamePath(companyUid, name),
-          query: Object.keys(query).length > 0 ? query : undefined,
         });
 
         if (!res.ok) {
-          const body = await res.json().catch(() => ({}));
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
           console.error(
-            chalk.red(`Failed to get secret: ${(body as Record<string, string>).error ?? res.statusText}`),
+            chalk.red(`Failed to get secret: ${extractApiMessage(body, res.statusText)}`),
           );
           process.exit(1);
         }
 
-        const data = (await res.json()) as {
-          secret: {
-            name: string;
-            companyUid: string;
-            type?: string;
-            lastModifiedDate?: string;
-            version?: number;
-            value?: string;
-          };
-        };
+        const data = (await res.json()) as SecretGetResponse;
+
+        let revealedValue: string | undefined;
+        let revealError: string | null = null;
+        if (opts.reveal) {
+          try {
+            revealedValue = (
+              await loadRevealedSecrets(token, companyUid, [name], await buildSecretUsage("reveal"))
+            ).get(name);
+          } catch (err) {
+            revealError = err instanceof Error ? err.message : String(err);
+          }
+        }
 
         const s = data.secret;
         console.log(chalk.bold(`Secret: ${s.name}`));
@@ -371,11 +566,19 @@ export function registerSecretsCommand(program: Command): void {
         if (s.version != null) {
           console.log(`  Version:       ${s.version}`);
         }
-        if (opts.reveal && s.value != null) {
-          console.log(`  Value:         ${s.value}`);
+        console.log(`  Tier:          ${normalizeSecretTier(s.tier)}`);
+        console.log(
+          `  Script Lock:   ${normalizeScriptLockMode(s.scriptLock?.mode)}`,
+        );
+        if (opts.reveal && revealedValue != null) {
+          console.log(`  Value:         ${revealedValue}`);
         } else {
           console.log(`  Value:         ${chalk.dim("[REDACTED]")}`);
         }
+        if (revealError) {
+          console.error(chalk.red(revealError));
+          process.exit(1);
+        }
       } catch (err) {
         console.error(
           chalk.red("Error:"),
@@ -490,7 +693,14 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const data = (await res.json()) as {
-          secrets: { name: string; lastModifiedDate?: string; version?: number; permission?: "admin" | "write" | "read" }[];
+          secrets: Array<
+            {
+              name: string;
+              lastModifiedDate?: string;
+              version?: number;
+              permission?: "admin" | "write" | "read";
+            } & SecretMetadata
+          >;
         };
 
         if (data.secrets.length === 0) {
@@ -500,21 +710,33 @@ export function registerSecretsCommand(program: Command): void {
 
         const nameWidth = Math.max(4, ...data.secrets.map((s) => s.name.length));
         const hasPermission = data.secrets.some((s) => s.permission !== undefined);
+        const tierWidth = Math.max(
+          4,
+          ...data.secrets.map((s) => normalizeSecretTier(s.tier).length),
+        );
+        const scriptLockWidth = Math.max(
+          11,
+          ...data.secrets.map((s) => normalizeScriptLockMode(s.scriptLock?.mode).length),
+        );
         if (hasPermission) {
           const accessWidth = Math.max(6, ...data.secrets.map((s) => (s.permission ?? "-").length));
-          const header = `${"NAME".padEnd(nameWidth)}  ${"ACCESS".padEnd(accessWidth)}  LAST MODIFIED`;
+          const header = `${"NAME".padEnd(nameWidth)}  ${"ACCESS".padEnd(accessWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
             const access = s.permission ?? "-";
+            const tier = normalizeSecretTier(s.tier);
+            const scriptLock = normalizeScriptLockMode(s.scriptLock?.mode);
             const modified = s.lastModifiedDate ?? "-";
-            console.log(`${s.name.padEnd(nameWidth)}  ${access.padEnd(accessWidth)}  ${modified}`);
+            console.log(`${s.name.padEnd(nameWidth)}  ${access.padEnd(accessWidth)}  ${tier.padEnd(tierWidth)}  ${scriptLock.padEnd(scriptLockWidth)}  ${modified}`);
           }
         } else {
-          const header = `${"NAME".padEnd(nameWidth)}  LAST MODIFIED`;
+          const header = `${"NAME".padEnd(nameWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
+            const tier = normalizeSecretTier(s.tier);
+            const scriptLock = normalizeScriptLockMode(s.scriptLock?.mode);
             const modified = s.lastModifiedDate ?? "-";
-            console.log(`${s.name.padEnd(nameWidth)}  ${modified}`);
+            console.log(`${s.name.padEnd(nameWidth)}  ${tier.padEnd(tierWidth)}  ${scriptLock.padEnd(scriptLockWidth)}  ${modified}`);
           }
         }
       } catch (err) {
@@ -526,6 +748,309 @@ export function registerSecretsCommand(program: Command): void {
       }
     });
 
+  const policy = secrets
+    .command("policy")
+    .description("View or update secret access policy");
+
+  policy
+    .command("get <path>")
+    .description("Show the policy for a secret path")
+    .action(async (secretPath: string) => {
+      try {
+        rejectIfPersonal(secrets.opts(), "policy get");
+
+        if (!SECRET_NAME_PATTERN.test(secretPath)) {
+          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 companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/policy`,
+          query: { path: secretPath },
+        });
+
+        if (res.status === 404) {
+          renderPolicySummary(
+            normalizePolicyRecord(secretPath, { policy: { path: secretPath } }),
+          );
+          return;
+        }
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+          console.error(
+            chalk.red(`Failed to get policy: ${extractApiMessage(body, res.statusText)}`),
+          );
+          process.exit(1);
+        }
+
+        const data = (await res.json()) as SecretPolicyResponse;
+        renderPolicySummary(normalizePolicyRecord(secretPath, data));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  policy
+    .command("set <path>")
+    .description("Set the policy for a secret path")
+    .option("--tier <tier>", "Secret tier: standard | sensitive | nuclear")
+    .option("--lock-script <mode>", "Script-lock mode: off | enforce")
+    .action(async (
+      secretPath: string,
+      opts: { tier?: string; lockScript?: string },
+    ) => {
+      try {
+        rejectIfPersonal(secrets.opts(), "policy set");
+
+        if (!SECRET_NAME_PATTERN.test(secretPath)) {
+          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 tier = opts.tier;
+        if (
+          tier !== undefined &&
+          tier !== "standard" &&
+          tier !== "sensitive" &&
+          tier !== "nuclear"
+        ) {
+          console.error(chalk.red(`Invalid tier '${tier}': must be one of standard, sensitive, nuclear`));
+          process.exit(1);
+        }
+
+        let scriptLock:
+          | { mode: SecretScriptLockMode }
+          | undefined;
+        if (opts.lockScript !== undefined) {
+          if (opts.lockScript === "off") {
+            scriptLock = { mode: "off" };
+          } else if (opts.lockScript === "enforce") {
+            scriptLock = { mode: "enforced" };
+          } else {
+            console.error(chalk.red(`Invalid script lock mode '${opts.lockScript}': must be one of off, enforce`));
+            process.exit(1);
+          }
+        }
+
+        if (tier === undefined && scriptLock === undefined) {
+          console.error(chalk.red("Error: provide at least one of --tier or --lock-script."));
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/policy`,
+          method: "PUT",
+          body: {
+            path: secretPath,
+            ...(tier !== undefined ? { tier } : {}),
+            ...(scriptLock ? { scriptLock } : {}),
+          },
+        });
+
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+          console.error(
+            chalk.red(`Failed to set policy: ${extractApiMessage(body, res.statusText)}`),
+          );
+          process.exit(1);
+        }
+
+        const data = (await res.json().catch(() => ({}))) as SecretPolicyResponse;
+        console.log(chalk.green(`Policy updated for '${secretPath}'.`));
+        renderPolicySummary(
+          normalizePolicyRecord(
+            secretPath,
+            data.policy ? data : { policy: { path: secretPath, tier, scriptLock } },
+          ),
+        );
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  const script = secrets
+    .command("script")
+    .description("Manage approved scripts for script-locked secrets");
+
+  script
+    .command("approve <path>")
+    .description("Approve a script for a secret path")
+    .requiredOption("--id <scriptId>", "Stable script identifier")
+    .requiredOption("--script <path>", "Path to the local script file")
+    .option(
+      "--attestation <level>",
+      "Attestation level",
+      "self-asserted-hash",
+    )
+    .action(async (
+      secretPath: string,
+      opts: { id: string; script: string; attestation: string },
+    ) => {
+      try {
+        rejectIfPersonal(secrets.opts(), "script approve");
+
+        if (!SECRET_NAME_PATTERN.test(secretPath)) {
+          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 usage = await buildSecretUsage(
+          "exec",
+          opts.script,
+          opts.id,
+          opts.attestation,
+        );
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/policy/scripts`,
+          method: "POST",
+          body: {
+            path: secretPath,
+            scriptId: usage.script?.scriptId,
+            scriptPath: usage.script?.path,
+            sha256: usage.script?.sha256,
+            attestationLevel: usage.script?.attestationLevel,
+          },
+        });
+
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+          console.error(
+            chalk.red(`Failed to approve script: ${extractApiMessage(body, res.statusText)}`),
+          );
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Approved script '${opts.id}' for '${secretPath}'.`));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  script
+    .command("revoke <path>")
+    .description("Revoke an approved script from a secret path")
+    .requiredOption("--id <scriptId>", "Stable script identifier")
+    .action(async (secretPath: string, opts: { id: string }) => {
+      try {
+        rejectIfPersonal(secrets.opts(), "script revoke");
+
+        if (!SECRET_NAME_PATTERN.test(secretPath)) {
+          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 companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/policy/scripts`,
+          method: "DELETE",
+          body: { path: secretPath, scriptId: opts.id },
+        });
+
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+          console.error(
+            chalk.red(`Failed to revoke script: ${extractApiMessage(body, res.statusText)}`),
+          );
+          process.exit(1);
+        }
+
+        console.log(chalk.green(`Revoked script '${opts.id}' for '${secretPath}'.`));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  script
+    .command("list <path>")
+    .description("List approved scripts for a secret path")
+    .action(async (secretPath: string) => {
+      try {
+        rejectIfPersonal(secrets.opts(), "script list");
+
+        if (!SECRET_NAME_PATTERN.test(secretPath)) {
+          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 companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+        const res = await vaultApiFetch({
+          token,
+          path: `/secrets/${encodeURIComponent(companyUid)}/policy`,
+          query: { path: secretPath },
+        });
+
+        if (res.status === 404) {
+          const policyRecord = normalizePolicyRecord(secretPath, {
+            policy: { path: secretPath },
+          });
+          renderPolicySummary(policyRecord);
+          renderPolicyScripts(policyRecord.scripts);
+          return;
+        }
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+          console.error(
+            chalk.red(`Failed to list scripts: ${extractApiMessage(body, res.statusText)}`),
+          );
+          process.exit(1);
+        }
+
+        const data = (await res.json()) as SecretPolicyResponse;
+        const policyRecord = normalizePolicyRecord(secretPath, data);
+        renderPolicySummary(policyRecord);
+        renderPolicyScripts(policyRecord.scripts);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
   secrets
     .command("delete <name>")
     .description("Delete a secret")
@@ -582,8 +1107,9 @@ export function registerSecretsCommand(program: Command): void {
     .command("exec")
     .description("Run a command with secrets injected as env vars")
     .requiredOption("--only <keys>", "Comma-separated list of secret names to inject (required)")
+    .option("--script <path>", "Attach local script identity for script-locked secrets")
     .allowUnknownOption(true)
-    .action(async (_opts: { only: string }, cmd: Command) => {
+    .action(async (_opts: { only: string; script?: string }, cmd: Command) => {
       try {
         const rawArgs = cmd.args;
         const dashIndex = process.argv.indexOf("--");
@@ -618,7 +1144,12 @@ export function registerSecretsCommand(program: Command): void {
           scopeOpts(secrets.opts()),
         );
 
-        const revealed = await loadRevealedSecrets(token, companyUid, keys);
+        const revealed = await loadRevealedSecrets(
+          token,
+          companyUid,
+          keys,
+          await buildSecretUsage("exec", _opts.script),
+        );
 
         const secretEnv: Record<string, string> = {};
         for (const key of keys) {
@@ -661,7 +1192,8 @@ export function registerSecretsCommand(program: Command): void {
     .command("env")
     .description("Print 'export KEY=VALUE' lines suitable for: source <(hq secrets env --only K1,K2)")
     .requiredOption("--only <keys>", "Comma-separated list of secret names to print (required)")
-    .action(async (opts: { only: string }) => {
+    .option("--script <path>", "Attach local script identity for script-locked secrets")
+    .action(async (opts: { only: string; script?: string }) => {
       try {
         const redact = process.stdout.isTTY;
         if (redact) {
@@ -691,7 +1223,12 @@ export function registerSecretsCommand(program: Command): void {
           scopeOpts(secrets.opts()),
         );
 
-        const revealed = await loadRevealedSecrets(token, companyUid, keys);
+        const revealed = await loadRevealedSecrets(
+          token,
+          companyUid,
+          keys,
+          await buildSecretUsage("env", opts.script),
+        );
 
         for (const key of keys) {
           const value = revealed.get(key);