@indigoai-us/hq-cli 5.28.0 → 5.30.0

package/.claude/policies/hq-cli-interactive-reads-use-sts-vend.md

@@ -0,0 +1,49 @@
+---
+id: hq-cli-interactive-reads-use-sts-vend
+title: Interactive vault reads vend via /sts/vend, never the legacy POST /vend
+scope: repo
+trigger: any hq-cli command that vends vault credentials to read/list company objects (files browse, files cat, files get/search, or any new interactive read surface)
+enforcement: hard
+public: false
+version: 1
+created: 2026-05-29
+updated: 2026-05-29
+source: back-pressure-failure
+applies_to: [aws]
+---
+
+## Rule
+
+Interactive vault reads in hq-cli MUST vend through the multi-tenant STS
+routes — `VaultClient.sts.vend({ companyUid })` (`POST /sts/vend`, company) or
+`VaultClient.sts.vendSelf({ personUid })` (`POST /sts/vend-self`, personal).
+NEVER vend through the legacy `VaultClient.vend(...)` (`POST /vend`).
+
+The legacy `POST /vend` (hq-pro `VaultVendFunction` → `vend.handler`) builds
+its IAM policy against a static `process.env.BUCKET_ARN`, but the hq-pro infra
+(`infra/vault-service.ts`) deliberately does NOT set `BUCKET_ARN` — production
+is multi-tenant with one bucket per company. At runtime `BUCKET_ARN` is
+`undefined`, so the session policy contains `"Resource":[null,"undefined/…"]`
+and STS rejects it with `MalformedPolicyDocument: Syntax error at position
+(-1,-1)` → the client sees a 500 "Failed to generate credentials". Only
+`/sts/vend{,-self,-child}` resolve the per-entity bucket (`entity.bucketArn`)
+and apply role/ACL scoping server-side (owner/admin → full access; member/
+guest → per-prefix). `policy-builder.ts` even documents that `POST /vend` "has
+no production callers" — treat it as dead.
+
+Related namespace rule: company vault bucket keys are **company-relative**
+(`knowledge/foo.md`, NOT `companies/<slug>/knowledge/foo.md`). Translate the
+CLI's anchored `companies/<slug>/…` form to the bucket-relative key at the S3
+boundary (`toBucketRelative` / `toCompanyAnchored` in `files-browse.ts`), and
+normalize ACL grant paths with `grantPathToPrefix` before `startsWith`
+classification. Listing/getting with the anchored prefix returns nothing.
+
+## Rationale
+
+`hq files browse`/`cat` (US-009) were wired to `POST /vend`, which 500'd on
+every multi-tenant call. The root cause was an undefined `BUCKET_ARN` env on
+the vend Lambda, not a stale deploy — redeploying clean source did not fix it.
+The working fix routed both commands through `/sts/vend` + `/sts/vend-self`
+(client-only, hq-cloud 5.43.0 / hq-cli 5.29.0) and fixed the company-relative
+namespace translation. Captured so future interactive-read surfaces reach for
+the STS routes from the start and don't resurrect the dead `POST /vend`.

package/dist/commands/files-browse.d.ts

@@ -17,31 +17,57 @@
  *                 `hq sync` owns, and writing a peeked object there would
  *                 silently re-import it into the sync envelope.
  *
- * Both subcommands vend via the new `purpose: 'browse'` path
- * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
- * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
- * keeping browse on its own vend call is the acceptance-criteria-1
- * separation we need.
+ * Both subcommands vend through the multi-tenant STS routes —
+ * `VaultClient.sts.vend` (`/sts/vend`, company) and `.sts.vendSelf`
+ * (`/sts/vend-self`, personal). These resolve the caller's per-entity bucket
+ * and apply role/ACL scoping server-side (owner/admin → full access; member/
+ * guest → per-prefix). The legacy `POST /vend` is deliberately NOT used: it
+ * assumes a single static `BUCKET_ARN` that is unset in multi-tenant prod, so
+ * it builds an invalid policy and STS rejects it (`MalformedPolicyDocument`).
  *
- * Cross-package note: depends on `VendInput`/`VendResult` + the
- * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
- * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
- * `pnpm.overrides` until that release ships to npm.
+ * Namespace note: company vault keys are company-relative (no
+ * `companies/<slug>/` prefix). The CLI speaks the anchored form for user
+ * familiarity and translates at the S3 boundary via `toBucketRelative` /
+ * `toCompanyAnchored`.
+ *
+ * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
+ * methods and `grantPathToPrefix` from hq-cloud.
  */
 import { Command } from "commander";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
-import { type VendResult, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type ExplicitGrant } from "@indigoai-us/hq-cloud";
+/** STS-vended credential set the browse/cat path consumes. */
+export interface BrowseCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+/** Minimal STS-vend response shape (both `/sts/vend` and `/sts/vend-self`). */
+export interface BrowseVendResult {
+    credentials: BrowseCredentials;
+}
 /**
  * Subset of `VaultClient` this command actually uses — exposed so tests
  * can stub vend + grants without standing up a real `VaultClient`.
+ *
+ * Browse/cat vend through the multi-tenant `/sts/vend` (company) and
+ * `/sts/vend-self` (personal) routes — NOT the legacy `POST /vend`, which
+ * assumes a single static bucket and is non-functional in multi-tenant
+ * production (it builds a policy against an undefined `BUCKET_ARN`, so STS
+ * rejects it with `MalformedPolicyDocument`). The STS routes resolve the
+ * caller's per-entity bucket and apply role/ACL scoping server-side.
  */
 export interface FilesBrowseVaultClient {
-    vend(input: {
-        paths: string[];
-        operations: "read-only" | "read-write" | "staged-write";
-        purpose: "sync" | "browse";
-        duration?: number;
-    }): Promise<VendResult>;
+    sts: {
+        vend(input: {
+            companyUid: string;
+            durationSeconds?: number;
+        }): Promise<BrowseVendResult>;
+        vendSelf(input: {
+            personUid: string;
+            durationSeconds?: number;
+        }): Promise<BrowseVendResult>;
+    };
     listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
     entity: {
         get(uid: string): Promise<{
@@ -96,15 +122,33 @@ export interface BrowseRow {
  */
 export declare function parseCompanySlugFromPath(prefix: string): string;
 /**
- * Classify a single S3 key against the caller's explicit-grant list. Any
- * grant whose `path` is a prefix of the key contributes `shared-with-you`;
- * otherwise the key is only visible via role-bypass on the vend call.
+ * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
+ * the vault bucket actually stores. Company vault buckets are already
+ * company-scoped, so their keys carry NO `companies/<slug>/` prefix (e.g.
+ * `knowledge/foo.md`, not `companies/indigo/knowledge/foo.md`). The CLI speaks
+ * the anchored form for user familiarity; we strip the anchor at the S3
+ * boundary. A path without the anchor (or personal-mode, bucket-relative
+ * paths) passes through unchanged.
+ */
+export declare function toBucketRelative(pathOrPrefix: string, slug: string): string;
+/**
+ * Re-attach the `companies/<slug>/` anchor to a company-relative bucket key
+ * for display + `hq files cat` round-trip, so the CLI surface keeps speaking
+ * the anchored form the user passed in.
+ */
+export declare function toCompanyAnchored(bucketRelKey: string, slug: string): string;
+/**
+ * Classify a single company-relative S3 key against the caller's
+ * (already-normalized) explicit-grant prefixes. Any prefix that covers the
+ * key contributes `shared-with-you`; otherwise the key is visible only via
+ * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
+ * prefix is a company-wide grant and matches everything.
  *
- * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
- * `coalescePrefixes` would shrink the list further but isn't required for
- * correctness — `startsWith` already short-circuits on the first match.
+ * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
+ * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
+ * calling this — keeping this helper pure and trivially testable.
  */
-export declare function classifyAclSource(key: string, grants: ExplicitGrant[]): AclSource;
+export declare function classifyAclSource(bucketRelKey: string, grantPrefixes: string[]): AclSource;
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -151,15 +195,17 @@ export interface RunBrowseInput {
 }
 export interface RunBrowseResult {
     rows: BrowseRow[];
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files browse <path>` orchestrator.
  *
  *   1. Parse slug from prefix (or use override).
  *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
- *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   3. Vend read creds via the multi-tenant STS route (`/sts/vend` company,
+ *      `/sts/vend-self` personal) — resolves the per-entity bucket + role/ACL.
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2 over the
+ *      company-relative key space.
  *   5. Fetch explicit grants once, classify each key.
  *
  * Pure-ish: no console output, no process.exit — caller renders + exits.
@@ -197,7 +243,7 @@ export interface RunCatResult {
         kind: "file";
         absPath: string;
     };
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
@@ -254,6 +300,78 @@ export declare function runSharedWithMe(input: RunSharedWithMeInput): Promise<Sh
  * Render `shared-with-me` rows as a padded table. Mirrors `formatBrowseTable`.
  */
 export declare function formatSharedWithMeTable(rows: SharedWithMeRow[]): string;
+export interface RunSearchInput {
+    /** Case-insensitive substring matched against each object's full key. */
+    query: string;
+    /** Company slug to search (ignored under personalMode). */
+    companySlug: string;
+    personalMode?: boolean;
+    personalUid?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+}
+/**
+ * `hq files search <query>` orchestrator. Lists the company (or personal)
+ * vault under its root via `runBrowse`, then filters to keys containing the
+ * query (case-insensitive). v1 is a name/path search over the listing — no
+ * content search. Rows carry the same ACL-source classification as browse.
+ *
+ * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
+ */
+export declare function runSearch(input: RunSearchInput): Promise<BrowseRow[]>;
+interface PinFile {
+    version: number;
+    /** companySlug → sorted list of company-relative pinned prefixes. */
+    pins: Record<string, string[]>;
+}
+/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
+export declare function pinFilePath(hqRoot: string): string;
+/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
+export declare function readPins(hqRoot: string): PinFile;
+/**
+ * Register a company-relative prefix in the per-machine pin set. Pins are what
+ * keep an on-demand `hq files get` from being pruned by the next *scoped*
+ * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
+ * into its pull scope. Idempotent + sorted for stable diffs.
+ */
+export declare function addPin(hqRoot: string, companySlug: string, prefix: string): void;
+export interface RunGetInput {
+    /** Vault path to materialize: `companies/<slug>/...` (file or prefix). */
+    path: string;
+    /**
+     * Override destination directory. Default (omitted) writes in place under
+     * `<hqRoot>/companies/<slug>/...` — the tree `hq sync` manages — and
+     * registers a pin. `--into` writes outside that envelope and pins nothing.
+     */
+    into?: string;
+    hqRoot: string;
+    companySlug?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+}
+export interface RunGetResult {
+    filesWritten: number;
+    bytesWritten: number;
+    destinations: string[];
+    /** Set only for in-place (no `--into`) materialization. */
+    pinned?: {
+        companySlug: string;
+        prefix: string;
+    };
+}
+/**
+ * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
+ * the local HQ tree on demand. Unlike `cat` (which refuses to write under
+ * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
+ * default — that's the point: pull a path you have access to but don't sync.
+ * It then registers a pin so the next scoped sync keeps it.
+ *
+ * Company mode only in v1 — materializing a personal vault would target the
+ * HQ root itself, which is too broad to do implicitly.
+ */
+export declare function runGet(input: RunGetInput): Promise<RunGetResult>;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group
@@ -261,4 +379,5 @@ export declare function formatSharedWithMeTable(rows: SharedWithMeRow[]): string
  * new browse-vs-sync subcommands so they share the `--company` switch.
  */
 export declare function registerFilesBrowseCommands(filesCmd: Command): void;
+export {};
 //# sourceMappingURL=files-browse.d.ts.map