@indigoai-us/hq-cloud 5.18.1 → 5.19.1

package/src/context.ts

@@ -7,6 +7,7 @@
  */
 
 import type { EntityContext, VaultServiceConfig } from "./types.js";
+import { buildClientHeaders } from "./client-info.js";
 
 /** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
 const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
@@ -14,9 +15,56 @@ const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
 /** STS session duration requested from vault-service (15 minutes). */
 const DEFAULT_SESSION_DURATION_SECONDS = 900;
 
-/** Cached contexts keyed by entity UID. */
+/**
+ * Cached contexts.
+ *
+ * Two keying schemes share the map:
+ *   - UID keys: bare `cmp_xxx` / `prs_xxx`. Globally unique by ULID, so
+ *     the cached context is safe to return to any caller asking by uid.
+ *   - Slug keys: `slug:${callerSub}#${slug}`. Under the per-user-namespace
+ *     model on hq-pro (PR 67, live 2026-05-15), the same slug can
+ *     legitimately resolve to different company UIDs for different
+ *     callers. Keying slug entries by `(callerSub, slug)` prevents one
+ *     caller's resolution from being served to another caller against
+ *     the wrong tenant. Codex flagged this as a P1 on PR 67's hq-cloud
+ *     follow-up.
+ */
 const contextCache = new Map<string, EntityContext>();
 
+/**
+ * Extract the Cognito sub claim from a JWT without verifying the
+ * signature. We don't need verification here — the token already
+ * authorized the upstream API call; we're only using `sub` as a
+ * per-caller cache discriminator. If the token is malformed or
+ * missing a sub, fall back to a hash of the whole token (slightly
+ * larger key space, same correctness — different tokens still
+ * get distinct cache entries).
+ */
+function callerKeyFromAccessToken(accessToken: string): string {
+  const parts = accessToken.split(".");
+  if (parts.length === 3) {
+    try {
+      // base64url decode (Node-compatible, no padding required)
+      const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+      const payload = Buffer.from(padded, "base64").toString("utf8");
+      const claims = JSON.parse(payload) as { sub?: unknown };
+      if (typeof claims.sub === "string" && claims.sub.length > 0) {
+        return claims.sub;
+      }
+    } catch {
+      // fall through to token-hash fallback
+    }
+  }
+  // Stable fallback — same token → same key, different tokens → different keys.
+  // (Avoids importing crypto for a sha; the raw token suffix is sufficient as
+  // a cache discriminator and isn't exposed outside this process.)
+  return `tok:${accessToken.slice(-32)}`;
+}
+
+function slugCacheKey(callerKey: string, slug: string): string {
+  return `slug:${callerKey}#${slug}`;
+}
+
 /**
  * Closed-set of recognised entity-UID prefixes. Adding a new entity type
  * means appending one entry here AND extending the dispatch in
@@ -35,20 +83,34 @@ export async function resolveEntityContext(
   companyUidOrSlug: string,
   config: VaultServiceConfig,
 ): Promise<EntityContext> {
-  // Check cache — return if credentials still fresh
-  const cached = contextCache.get(companyUidOrSlug);
-  if (cached && !isExpiringSoon(cached.expiresAt)) {
-    return cached;
-  }
-
-  // Step 1: Resolve entity — if it looks like a known UID prefix, fetch directly;
-  // otherwise look up by slug. Explicit enumeration avoids over-matching slugs
-  // like foo_bar or team_alpha that happen to look like UIDs.
+  // Step 0: Determine whether the input is a UID (globally unique) or a
+  // slug (per-caller). The cache key differs accordingly — see the
+  // `contextCache` jsdoc.
   const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
     companyUidOrSlug.startsWith(p),
   );
   const looksLikePerson = companyUidOrSlug.startsWith("prs_");
 
+  // For slug lookups, scope the cache key by the caller. Resolving the
+  // access token here (once) doubles as a way to extract the sub for
+  // the key — same hop the downstream fetch makes anyway.
+  let cacheKey: string;
+  let callerKey: string | null = null;
+  if (looksLikeUid) {
+    cacheKey = companyUidOrSlug;
+  } else {
+    const token = await resolveAuthToken(config);
+    callerKey = callerKeyFromAccessToken(token);
+    cacheKey = slugCacheKey(callerKey, companyUidOrSlug);
+  }
+
+  // Check cache — return if credentials still fresh.
+  const cached = contextCache.get(cacheKey);
+  if (cached && !isExpiringSoon(cached.expiresAt)) {
+    return cached;
+  }
+
+  // Step 1: Resolve entity — direct fetch by UID or namespace lookup by slug.
   const entity = looksLikeUid
     ? await fetchEntity(companyUidOrSlug, config)
     : await fetchEntityBySlug("company", companyUidOrSlug, config);
@@ -81,9 +143,13 @@ export async function resolveEntityContext(
     expiresAt: vendResult.expiresAt,
   };
 
-  // Cache by both UID and slug for fast lookups
+  // Cache by UID (globally unique) and — if the caller asked by slug —
+  // by `(callerSub, slug)` so the same slug can resolve to different
+  // entities per caller without cross-caller poisoning.
   contextCache.set(entity.uid, ctx);
-  contextCache.set(entity.slug, ctx);
+  if (callerKey) {
+    contextCache.set(slugCacheKey(callerKey, entity.slug), ctx);
+  }
 
   return ctx;
 }
@@ -105,8 +171,18 @@ export async function refreshEntityContext(
   companyUidOrSlug: string,
   config: VaultServiceConfig,
 ): Promise<EntityContext> {
-  // Evict cache entry to force fresh resolution
-  contextCache.delete(companyUidOrSlug);
+  // Evict the entry under whichever key shape applies. UID inputs key
+  // the cache by the bare uid; slug inputs key by `(callerSub, slug)`.
+  const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
+    companyUidOrSlug.startsWith(p),
+  );
+  if (looksLikeUid) {
+    contextCache.delete(companyUidOrSlug);
+  } else {
+    const token = await resolveAuthToken(config);
+    const callerKey = callerKeyFromAccessToken(token);
+    contextCache.delete(slugCacheKey(callerKey, companyUidOrSlug));
+  }
   return resolveEntityContext(companyUidOrSlug, config);
 }
 
@@ -156,7 +232,10 @@ async function fetchEntity(
   config: VaultServiceConfig,
 ): Promise<EntityResponse> {
   const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
-    headers: { Authorization: `Bearer ${await resolveAuthToken(config)}` },
+    headers: {
+      Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
+    },
   });
   if (!res.ok) {
     const body = await res.text();
@@ -171,17 +250,41 @@ async function fetchEntityBySlug(
   slug: string,
   config: VaultServiceConfig,
 ): Promise<EntityResponse> {
-  const res = await fetch(`${config.apiUrl}/entity/by-slug/${type}/${slug}`, {
-    headers: { Authorization: `Bearer ${await resolveAuthToken(config)}` },
+  // Resolve the slug inside the CALLER's namespace via the new
+  // `/entity/check-slug/me` endpoint added in hq-pro PR 67 (live
+  // in prod 2026-05-15). Under the per-user-namespace model the
+  // legacy `/entity/by-slug/{type}/{slug}` either over-matches
+  // (returns another tenant's entity when more than one user holds
+  // the slug) or 409s with SlugNotUniqueError — both wrong for the
+  // sync runner's "I want MY company" intent.
+  const checkUrl = `${config.apiUrl}/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`;
+  const checkRes = await fetch(checkUrl, {
+    headers: {
+      Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
+    },
   });
-  if (!res.ok) {
-    const body = await res.text();
+  if (!checkRes.ok) {
+    const body = await checkRes.text();
     throw new Error(
-      `Failed to find entity by slug ${type}/${slug}: ${res.status} ${body}`,
+      `Failed to check slug ${type}/${slug}: ${checkRes.status} ${body}`,
     );
   }
-  const data = (await res.json()) as { entity: EntityResponse };
-  return data.entity;
+  const check = (await checkRes.json()) as {
+    available: boolean;
+    conflictingCompanyUid?: string;
+  };
+  if (check.available || !check.conflictingCompanyUid) {
+    // The slug isn't in the caller's namespace. From the sync
+    // runner's perspective this is a genuine "not found" — the
+    // caller doesn't have a `${slug}` to sync, even if some other
+    // user does.
+    throw new Error(
+      `No entity in caller's namespace matches ${type}/${slug}. ` +
+        `If you expected to find one, verify you're signed in to the right HQ identity.`,
+    );
+  }
+  return fetchEntity(check.conflictingCompanyUid, config);
 }
 
 async function postVend(
@@ -194,6 +297,7 @@ async function postVend(
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${await resolveAuthToken(config)}`,
+      ...buildClientHeaders(config.clientInfo),
     },
     body: JSON.stringify({ ...body, durationSeconds: DEFAULT_SESSION_DURATION_SECONDS }),
   });

package/src/index.ts

@@ -106,6 +106,7 @@ export type {
   EntityContext,
   VaultCredentials,
   VaultServiceConfig,
+  ClientInfo,
   SyncConfig,
   Credentials,
   JournalEntry,
@@ -115,3 +116,14 @@ export type {
   PullResult,
   DaemonState,
 } from "./types.js";
+
+// Client identification — every first-party caller should construct one of
+// these once at startup and pass it in via VaultServiceConfig.clientInfo.
+export {
+  buildClientHeaders,
+  clientInfoFromPackage,
+  detectHqCoreVersion,
+  HEADER_CLIENT_NAME,
+  HEADER_CLIENT_VERSION,
+  HEADER_HQ_CORE_VERSION,
+} from "./client-info.js";

package/src/types.ts

@@ -91,6 +91,24 @@ export interface VaultCredentials {
   sessionToken: string;
 }
 
+/**
+ * Caller identification stamped on every request to hq-cloud-api so the server
+ * can attribute traffic and gate on minimum versions.
+ */
+export interface ClientInfo {
+  /** Package name, e.g. "@indigoai-us/hq-cli" */
+  name: string;
+  /** Package version, e.g. "5.15.0" */
+  version: string;
+  /**
+   * `hqVersion` from `core/core.yaml` — set when the caller is running inside
+   * an hq-core checkout. Lets the server see scaffold-generation skew.
+   */
+  hqCoreVersion?: string;
+  /** Arbitrary extra key/value pairs forwarded as `x-hq-client-<key>` headers. */
+  extra?: Record<string, string>;
+}
+
 /**
  * Configuration for connecting to the vault-service API.
  */
@@ -110,6 +128,11 @@ export interface VaultServiceConfig {
   authToken: string | (() => string | Promise<string>);
   /** AWS region for S3 client (defaults to entity region or us-east-1) */
   region?: string;
+  /**
+   * Identifies the calling package + version on every outbound request.
+   * Optional for back-compat, but all first-party clients should pass it.
+   */
+  clientInfo?: ClientInfo;
 }
 
 // ── Conflict index (consumed by /resolve-conflicts) ─────────────────────────

package/src/vault-client.ts

@@ -6,7 +6,8 @@
  * share one client instead of each rolling its own HTTP layer.
  */
 
-import type { VaultServiceConfig } from "./types.js";
+import type { ClientInfo, VaultServiceConfig } from "./types.js";
+import { buildClientHeaders } from "./client-info.js";
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -213,6 +214,7 @@ async function sleep(ms: number): Promise<void> {
 export class VaultClient {
   private readonly apiUrl: string;
   private readonly getAuthToken: () => Promise<string>;
+  private readonly clientInfo: ClientInfo | undefined;
 
   constructor(config: VaultServiceConfig) {
     this.apiUrl = config.apiUrl.replace(/\/+$/, "");
@@ -227,6 +229,7 @@ export class VaultClient {
       typeof tok === "function"
         ? async () => tok()
         : async () => tok;
+    this.clientInfo = config.clientInfo;
   }
 
   // -- Membership operations ------------------------------------------------
@@ -332,6 +335,17 @@ export class VaultClient {
       return data.entity;
     },
 
+    /**
+     * Legacy global slug lookup. Under the per-user-namespace model on
+     * hq-pro (PR indigoai-us/hq-pro#67, live in prod 2026-05-15) the
+     * server-side handler now uses `requireUnique: true` — this method
+     * returns a single entity when only one tenant holds the slug, 404s
+     * when nobody does, or 409s with `SlugNotUniqueError` and a list of
+     * colliding `uids` when more than one tenant holds it. Most CLI
+     * call sites have moved to `findInMyNamespace` (which respects the
+     * caller's effective namespace); only flows that genuinely want a
+     * global lookup (admin tooling) should still use this method.
+     */
     findBySlug: async (type: string, slug: string): Promise<EntityInfo> => {
       const data = await this.get<{ entity: EntityInfo }>(
         `/entity/by-slug/${encodeURIComponent(type)}/${encodeURIComponent(slug)}`,
@@ -339,6 +353,32 @@ export class VaultClient {
       return data.entity;
     },
 
+    /**
+     * Resolve an entity by slug within the CALLER's namespace
+     * (owned ∪ active-member-of, soft-deleted excluded). Hits the new
+     * `GET /entity/check-slug/me?type=&slug=` endpoint added in PR 67.
+     *
+     * Returns the full entity when present in the caller's namespace,
+     * or `null` when the slug isn't theirs — even if some OTHER user
+     * happens to own a company with the same slug. This is what every
+     * "find my-company by slug" flow wants under the per-user model;
+     * `findBySlug`'s global semantic would over-match (return a
+     * stranger's entity) or 409 (multi-tenant slug) in those cases.
+     */
+    findInMyNamespace: async (
+      type: string,
+      slug: string,
+    ): Promise<EntityInfo | null> => {
+      const check = await this.get<{
+        available: boolean;
+        conflictingCompanyUid?: string;
+      }>(
+        `/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`,
+      );
+      if (check.available || !check.conflictingCompanyUid) return null;
+      return this.entity.get(check.conflictingCompanyUid);
+    },
+
     create: async (input: CreateEntityInput): Promise<EntityInfo> => {
       const data = await this.post<CreateEntityResult>("/entity", input);
       return data.entity;
@@ -448,6 +488,7 @@ export class VaultClient {
       const headers: Record<string, string> = {
         Authorization: `Bearer ${await this.getAuthToken()}`,
         Accept: "application/json",
+        ...buildClientHeaders(this.clientInfo),
       };
 
       const init: RequestInit = { method, headers };