@indigoai-us/hq-cli 5.10.1 → 5.11.0

package/dist/commands/cloud.js

@@ -13,11 +13,11 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5ddbce6a-fdde-506e-8cdd-2e5b0ad20fff")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="213f074e-13c2-5b95-9519-813adf9adfa9")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, readJournal, getJournalPath, } from "@indigoai-us/hq-cloud";
+import { share, sync, readJournal, getJournalPath, loadCachedTokens, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 export function registerCloudCommands(program) {
     program
@@ -85,6 +85,13 @@ export function registerCloudCommands(program) {
             const onEvent = jsonMode
                 ? (event) => emitJson(event)
                 : undefined;
+            // Stamp every uploaded object's S3 user metadata with the syncing
+            // user's Cognito identity (`Metadata['created-by']`). The hq-console
+            // vault UI's CREATED BY column reads this back via HEAD; without it,
+            // every row renders `—`. Resolved best-effort from the cached
+            // idToken — pre-vended `--creds-from-stdin` paths still get author
+            // attribution as long as the caller is logged in locally.
+            const author = resolveUploadAuthorFromCache();
             const result = await share({
                 paths: targetPaths,
                 company: options.company,
@@ -94,6 +101,7 @@ export function registerCloudCommands(program) {
                 entityContext,
                 hqRoot: options.hqRoot,
                 onEvent,
+                ...(author ? { author } : {}),
             });
             if (jsonMode) {
                 // Synthetic terminal event so subprocess consumers can read final
@@ -226,5 +234,36 @@ async function readAllStdin() {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
+/**
+ * Resolve the syncing user's `UploadAuthor` (sub + email) from the cached
+ * Cognito idToken. Returns `undefined` when no tokens are cached or the
+ * token is missing the required claims — share() then skips the metadata
+ * stamp gracefully (not an error).
+ *
+ * We deliberately decode the JWT here instead of verifying it: Cognito
+ * already verified at issuance, and we only use the public claims to
+ * label the upload's S3 user metadata (no auth decision rides on it).
+ */
+function resolveUploadAuthorFromCache() {
+    const tokens = loadCachedTokens();
+    if (!tokens?.idToken)
+        return undefined;
+    const parts = tokens.idToken.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
+        const json = Buffer.from(padded, "base64").toString("utf-8");
+        const claims = JSON.parse(json);
+        if (claims.sub && claims.email) {
+            return { userSub: claims.sub, email: claims.email };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=cloud.js.map
-//# debugId=5ddbce6a-fdde-506e-8cdd-2e5b0ad20fff
+//# debugId=213f074e-13c2-5b95-9519-813adf9adfa9

package/dist/commands/secrets.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { vaultApiFetch, getCompanyUid, getEntityUid } from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
-export { vaultApiFetch, getCompanyUid };
+export { vaultApiFetch, getCompanyUid, getEntityUid };
 export declare function registerSecretsCommand(program: Command): void;
 //# sourceMappingURL=secrets.d.ts.map

package/dist/commands/secrets.js

@@ -1,13 +1,26 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0239c476-98b8-53c0-9458-1c82dc0d26a9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="217ceadb-01cd-5778-9cc0-6f6d895d8d67")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-export { vaultApiFetch, getCompanyUid };
+import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
+export { vaultApiFetch, getCompanyUid, getEntityUid };
+function scopeOpts(opts) {
+    if (opts.personal && opts.company) {
+        console.error(chalk.red("Error: --personal cannot be combined with --company."));
+        process.exit(1);
+    }
+    return { personal: !!opts.personal, companySlug: opts.company };
+}
+function rejectIfPersonal(opts, action) {
+    if (opts.personal) {
+        console.error(chalk.red(`Error: ${action} is not supported with --personal.`));
+        process.exit(1);
+    }
+}
 function shellSingleQuote(value) {
     return "'" + value.replace(/'/g, "'\\''") + "'";
 }
@@ -115,7 +128,8 @@ export function registerSecretsCommand(program) {
     const secrets = program
         .command("secrets")
         .description("Manage secrets in HQ vault (SSM Parameter Store)")
-        .option("--company <slug>", "Company slug (resolves to companyUid)");
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--personal", "Operate on the caller's personal vault (no sharing)");
     secrets
         .command("set <name>")
         .description("Create or update a secret")
@@ -150,8 +164,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
                 path: `/secrets/${encodeURIComponent(companyUid)}`,
@@ -178,8 +191,7 @@ export function registerSecretsCommand(program) {
         .action(async (name, opts) => {
         try {
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const query = {};
             if (opts.reveal) {
                 query.reveal = "true";
@@ -233,8 +245,7 @@ export function registerSecretsCommand(program) {
                 normalizedPrefix = normalized;
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const query = {};
             if (normalizedPrefix) {
                 query.prefix = normalizedPrefix;
@@ -298,8 +309,7 @@ export function registerSecretsCommand(program) {
                 }
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
                 path: buildSecretNamePath(companyUid, name),
@@ -350,8 +360,7 @@ export function registerSecretsCommand(program) {
                 }
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const revealed = await Promise.all(keys.map(async (key) => {
                 const cached = readCache(companyUid, key);
                 if (cached !== null) {
@@ -420,8 +429,7 @@ export function registerSecretsCommand(program) {
                 }
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const revealed = await Promise.all(keys.map(async (key) => {
                 const cached = readCache(companyUid, key);
                 if (cached !== null) {
@@ -459,6 +467,7 @@ export function registerSecretsCommand(program) {
         .option("--expires <duration>", "Token expiry duration (e.g. 24h, 2d, 30m)", "24h")
         .action(async (name, opts) => {
         try {
+            rejectIfPersonal(secrets.opts(), "generate-link");
             if (!SECRET_NAME_PATTERN.test(name)) {
                 console.error(chalk.red(`Invalid secret name '${name}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_API_KEY or DEV/MY_KEY)`));
                 process.exit(1);
@@ -474,8 +483,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
                 path: buildSecretNamePath(companyUid, name),
@@ -507,6 +515,7 @@ export function registerSecretsCommand(program) {
         .requiredOption("--permission <level>", "Permission level: read | write | admin")
         .action(async (path, opts) => {
         try {
+            rejectIfPersonal(secrets.opts(), "share");
             if (!SECRET_NAME_PATTERN.test(path)) {
                 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);
@@ -523,8 +532,7 @@ export function registerSecretsCommand(program) {
             const granteeType = isEmail ? "email" : "group";
             const granteeId = opts.with;
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
                 path: `/secrets/${encodeURIComponent(companyUid)}/acl/grant`,
@@ -566,6 +574,7 @@ export function registerSecretsCommand(program) {
         .requiredOption("--from <principal>", "Email address or group id to remove")
         .action(async (path, opts) => {
         try {
+            rejectIfPersonal(secrets.opts(), "unshare");
             if (!SECRET_NAME_PATTERN.test(path)) {
                 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);
@@ -578,8 +587,7 @@ export function registerSecretsCommand(program) {
             const granteeType = isEmailFrom ? "email" : "group";
             const granteeId = opts.from;
             const token = await ensureCognitoToken();
-            const companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
                 path: `/secrets/${encodeURIComponent(companyUid)}/acl/revoke`,
@@ -618,13 +626,13 @@ export function registerSecretsCommand(program) {
         .description("Show the ACL (access control list) for a secret path")
         .action(async (path) => {
         try {
+            rejectIfPersonal(secrets.opts(), "acl");
             if (!SECRET_NAME_PATTERN.test(path)) {
                 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 companySlug = secrets.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const secretPath = path;
             const res = await vaultApiFetch({
                 token,
@@ -705,4 +713,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=0239c476-98b8-53c0-9458-1c82dc0d26a9
+//# debugId=217ceadb-01cd-5778-9cc0-6f6d895d8d67

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

@@ -7,4 +7,9 @@ export interface VaultApiOptions {
 }
 export declare function vaultApiFetch(opts: VaultApiOptions): Promise<Response>;
 export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
+export declare function resolveCallerPersonUid(token: string): Promise<string>;
+export declare function getEntityUid(token: string, opts: {
+    personal?: boolean;
+    companySlug?: string;
+}): Promise<string>;
 //# sourceMappingURL=vault-api.d.ts.map

package/dist/utils/vault-api.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4e482805-d129-5563-a77b-97b80410154b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="05d73a12-54b0-559c-a964-de7dff2d48eb")}catch(e){}}();
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 export async function vaultApiFetch(opts) {
     const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
@@ -54,5 +54,38 @@ export async function getCompanyUid(token, companySlug) {
     }
     return resolveCompanyFromMemberships(token);
 }
+// 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) {
+    const res = await vaultApiFetch({
+        token,
+        path: '/entity/by-type/person',
+    });
+    if (!res.ok) {
+        throw new Error("Failed to fetch person entity — run `hq login` and try again");
+    }
+    const data = (await res.json());
+    const persons = (data.entities ?? []).filter((e) => e.type === 'person');
+    if (persons.length === 0) {
+        throw new Error('No person entity found for the caller. Sign in to HQ once to provision one.');
+    }
+    persons.sort((a, b) => {
+        const ac = a.createdAt ?? '';
+        const bc = b.createdAt ?? '';
+        if (ac !== bc)
+            return ac < bc ? -1 : 1;
+        return a.uid < b.uid ? -1 : 1;
+    });
+    return persons[0].uid;
+}
+// Resolves the scope UID (cmp_* or prs_*) for a secrets command. Precedence:
+// `--personal` → caller's canonical person entity; else `--company <slug>` →
+// resolved company UID; else fallback to single active company membership.
+export async function getEntityUid(token, opts) {
+    if (opts.personal) {
+        return resolveCallerPersonUid(token);
+    }
+    return getCompanyUid(token, opts.companySlug);
+}
 //# sourceMappingURL=vault-api.js.map
-//# debugId=4e482805-d129-5563-a77b-97b80410154b
+//# debugId=05d73a12-54b0-559c-a964-de7dff2d48eb

package/package.json

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

package/src/commands/cloud.ts

@@ -23,9 +23,11 @@ import {
   sync,
   readJournal,
   getJournalPath,
+  loadCachedTokens,
   type ConflictStrategy,
   type EntityContext,
   type SyncProgressEvent,
+  type UploadAuthor,
 } from "@indigoai-us/hq-cloud";
 
 import {
@@ -146,6 +148,14 @@ export function registerCloudCommands(program: Command): void {
                 emitJson(event as unknown as Record<string, unknown>)
             : undefined;
 
+          // Stamp every uploaded object's S3 user metadata with the syncing
+          // user's Cognito identity (`Metadata['created-by']`). The hq-console
+          // vault UI's CREATED BY column reads this back via HEAD; without it,
+          // every row renders `—`. Resolved best-effort from the cached
+          // idToken — pre-vended `--creds-from-stdin` paths still get author
+          // attribution as long as the caller is logged in locally.
+          const author = resolveUploadAuthorFromCache();
+
           const result = await share({
             paths: targetPaths,
             company: options.company,
@@ -155,6 +165,7 @@ export function registerCloudCommands(program: Command): void {
             entityContext,
             hqRoot: options.hqRoot,
             onEvent,
+            ...(author ? { author } : {}),
           });
 
           if (jsonMode) {
@@ -343,3 +354,32 @@ async function readAllStdin(): Promise<string> {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
+
+/**
+ * Resolve the syncing user's `UploadAuthor` (sub + email) from the cached
+ * Cognito idToken. Returns `undefined` when no tokens are cached or the
+ * token is missing the required claims — share() then skips the metadata
+ * stamp gracefully (not an error).
+ *
+ * We deliberately decode the JWT here instead of verifying it: Cognito
+ * already verified at issuance, and we only use the public claims to
+ * label the upload's S3 user metadata (no auth decision rides on it).
+ */
+function resolveUploadAuthorFromCache(): UploadAuthor | undefined {
+  const tokens = loadCachedTokens();
+  if (!tokens?.idToken) return undefined;
+  const parts = tokens.idToken.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
+    const json = Buffer.from(padded, "base64").toString("utf-8");
+    const claims = JSON.parse(json) as { sub?: string; email?: string };
+    if (claims.sub && claims.email) {
+      return { userSub: claims.sub, email: claims.email };
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/commands/secrets.ts

@@ -10,9 +10,40 @@ import {
   clearAllCache,
 } from "../utils/secrets-cache.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import {
+  vaultApiFetch,
+  getCompanyUid,
+  getEntityUid,
+} from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
-export { vaultApiFetch, getCompanyUid };
+export { vaultApiFetch, getCompanyUid, getEntityUid };
+
+interface SecretsScopeOpts {
+  company?: string;
+  personal?: boolean;
+}
+
+function scopeOpts(opts: SecretsScopeOpts): {
+  personal: boolean;
+  companySlug: string | undefined;
+} {
+  if (opts.personal && opts.company) {
+    console.error(
+      chalk.red("Error: --personal cannot be combined with --company."),
+    );
+    process.exit(1);
+  }
+  return { personal: !!opts.personal, companySlug: opts.company };
+}
+
+function rejectIfPersonal(opts: SecretsScopeOpts, action: string): void {
+  if (opts.personal) {
+    console.error(
+      chalk.red(`Error: ${action} is not supported with --personal.`),
+    );
+    process.exit(1);
+  }
+}
 
 function shellSingleQuote(value: string): string {
   return "'" + value.replace(/'/g, "'\\''") + "'";
@@ -125,7 +156,11 @@ export function registerSecretsCommand(program: Command): void {
   const secrets = program
     .command("secrets")
     .description("Manage secrets in HQ vault (SSM Parameter Store)")
-    .option("--company <slug>", "Company slug (resolves to companyUid)");
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option(
+      "--personal",
+      "Operate on the caller's personal vault (no sharing)",
+    );
 
   secrets
     .command("set <name>")
@@ -164,8 +199,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const res = await vaultApiFetch({
           token,
@@ -200,8 +237,10 @@ export function registerSecretsCommand(program: Command): void {
     .action(async (name: string, opts: { reveal?: boolean }) => {
       try {
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const query: Record<string, string> = {};
         if (opts.reveal) {
@@ -283,8 +322,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const query: Record<string, string> = {};
         if (normalizedPrefix) {
@@ -364,8 +405,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const res = await vaultApiFetch({
           token,
@@ -427,8 +470,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const revealed = await Promise.all(
           keys.map(async (key) => {
@@ -518,8 +563,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const revealed = await Promise.all(
           keys.map(async (key) => {
@@ -568,6 +615,8 @@ export function registerSecretsCommand(program: Command): void {
     .option("--expires <duration>", "Token expiry duration (e.g. 24h, 2d, 30m)", "24h")
     .action(async (name: string, opts: { expires: string }) => {
       try {
+        rejectIfPersonal(secrets.opts(), "generate-link");
+
         if (!SECRET_NAME_PATTERN.test(name)) {
           console.error(chalk.red(`Invalid secret name '${name}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_API_KEY or DEV/MY_KEY)`));
           process.exit(1);
@@ -586,8 +635,10 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const res = await vaultApiFetch({
           token,
@@ -632,6 +683,8 @@ export function registerSecretsCommand(program: Command): void {
     .requiredOption("--permission <level>", "Permission level: read | write | admin")
     .action(async (path: string, opts: { with: string; permission: string }) => {
       try {
+        rejectIfPersonal(secrets.opts(), "share");
+
         if (!SECRET_NAME_PATTERN.test(path)) {
           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);
@@ -651,8 +704,10 @@ export function registerSecretsCommand(program: Command): void {
         const granteeId = opts.with;
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const res = await vaultApiFetch({
           token,
@@ -695,6 +750,8 @@ export function registerSecretsCommand(program: Command): void {
     .requiredOption("--from <principal>", "Email address or group id to remove")
     .action(async (path: string, opts: { from: string }) => {
       try {
+        rejectIfPersonal(secrets.opts(), "unshare");
+
         if (!SECRET_NAME_PATTERN.test(path)) {
           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);
@@ -709,8 +766,10 @@ export function registerSecretsCommand(program: Command): void {
         const granteeId = opts.from;
 
         const token = await ensureCognitoToken();
-        const companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const res = await vaultApiFetch({
           token,
@@ -751,14 +810,18 @@ export function registerSecretsCommand(program: Command): void {
     .description("Show the ACL (access control list) for a secret path")
     .action(async (path: string) => {
       try {
+        rejectIfPersonal(secrets.opts(), "acl");
+
         if (!SECRET_NAME_PATTERN.test(path)) {
           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 companySlug = secrets.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
 
         const secretPath = path;
         const res = await vaultApiFetch({

package/src/utils/vault-api.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import { getEntityUid, resolveCallerPersonUid } from './vault-api.js';
+
+const fetchMock = vi.fn();
+const originalFetch = globalThis.fetch;
+
+function mockResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe('resolveCallerPersonUid', () => {
+  it('returns the canonical person uid (oldest createdAt, uid tie-break)', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        entities: [
+          { uid: 'prs_b', type: 'person', createdAt: '2026-01-02T00:00:00Z' },
+          { uid: 'prs_a', type: 'person', createdAt: '2026-01-01T00:00:00Z' },
+          { uid: 'prs_c', type: 'person', createdAt: '2026-01-01T00:00:00Z' },
+        ],
+      }),
+    );
+
+    const uid = await resolveCallerPersonUid('tok');
+    expect(uid).toBe('prs_a');
+  });
+
+  it('throws when the caller has no person entity', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(200, { entities: [] }));
+    await expect(resolveCallerPersonUid('tok')).rejects.toThrow(
+      /No person entity/,
+    );
+  });
+
+  it('throws when the API returns an error status', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(401, { error: 'unauth' }));
+    await expect(resolveCallerPersonUid('tok')).rejects.toThrow(
+      /Failed to fetch person entity/,
+    );
+  });
+
+  it('filters out non-person entries before sorting', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        entities: [
+          { uid: 'cmp_a', type: 'company', createdAt: '2025-01-01T00:00:00Z' },
+          { uid: 'prs_a', type: 'person', createdAt: '2026-01-01T00:00:00Z' },
+        ],
+      }),
+    );
+    const uid = await resolveCallerPersonUid('tok');
+    expect(uid).toBe('prs_a');
+  });
+});
+
+describe('getEntityUid', () => {
+  it('routes to person resolution when personal=true', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        entities: [
+          { uid: 'prs_a', type: 'person', createdAt: '2026-01-01T00:00:00Z' },
+        ],
+      }),
+    );
+    const uid = await getEntityUid('tok', { personal: true });
+    expect(uid).toBe('prs_a');
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toMatch(/\/entity\/by-type\/person/);
+  });
+
+  it('routes to company-slug resolution when companySlug is set', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, { entity: { uid: 'cmp_acme' } }),
+    );
+    const uid = await getEntityUid('tok', { companySlug: 'acme' });
+    expect(uid).toBe('cmp_acme');
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toMatch(/\/entity\/by-slug\/company\/acme/);
+  });
+
+  it('falls back to membership lookup when neither personal nor slug is set', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        memberships: [
+          {
+            companyUid: 'cmp_only',
+            role: 'member',
+            status: 'active',
+            membershipKey: 'k',
+          },
+        ],
+      }),
+    );
+    const uid = await getEntityUid('tok', {});
+    expect(uid).toBe('cmp_only');
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toMatch(/\/membership\/me/);
+  });
+});

package/src/utils/vault-api.ts

@@ -78,3 +78,46 @@ export async function getCompanyUid(
   }
   return resolveCompanyFromMemberships(token);
 }
+
+interface PersonEntity {
+  uid: string;
+  type: string;
+  createdAt?: string;
+}
+
+// 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: string): Promise<string> {
+  const res = await vaultApiFetch({
+    token,
+    path: '/entity/by-type/person',
+  });
+  if (!res.ok) {
+    throw new Error("Failed to fetch person entity — run `hq login` and try again");
+  }
+  const data = (await res.json()) as { entities: PersonEntity[] };
+  const persons = (data.entities ?? []).filter((e) => e.type === 'person');
+  if (persons.length === 0) {
+    throw new Error('No person entity found for the caller. Sign in to HQ once to provision one.');
+  }
+  persons.sort((a, b) => {
+    const ac = a.createdAt ?? '';
+    const bc = b.createdAt ?? '';
+    if (ac !== bc) return ac < bc ? -1 : 1;
+    return a.uid < b.uid ? -1 : 1;
+  });
+  return persons[0].uid;
+}
+
+// Resolves the scope UID (cmp_* or prs_*) for a secrets command. Precedence:
+// `--personal` → caller's canonical person entity; else `--company <slug>` →
+// resolved company UID; else fallback to single active company membership.
+export async function getEntityUid(
+  token: string,
+  opts: { personal?: boolean; companySlug?: string },
+): Promise<string> {
+  if (opts.personal) {
+    return resolveCallerPersonUid(token);
+  }
+  return getCompanyUid(token, opts.companySlug);
+}