@indigoai-us/hq-cloud 5.18.1 → 5.19.0

package/src/cli/sync.test.ts

@@ -62,6 +62,18 @@ const mockVendResponse = {
 function setupFetchMock() {
   const fetchMock = vi.fn().mockImplementation(async (url: string) => {
     const urlStr = String(url);
+    // New per-user-namespace slug resolver (hq-pro PR 67). Returns the
+    // mockEntity's uid as the in-namespace match; the caller then
+    // re-fetches it via `/entity/{uid}`, which is matched by the
+    // `/entity/cmp_/` branch below.
+    if (urlStr.includes("/entity/check-slug/me")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+        text: async () => "",
+      };
+    }
     if (urlStr.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(urlStr)) {
       return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
     }

package/src/context.test.ts

@@ -47,6 +47,31 @@ function setupFetchMock(overrides?: {
   fetchMock.mockImplementation(async (url: string) => {
     const urlStr = String(url);
 
+    // New per-user-namespace slug resolver (hq-pro PR 67). Maps slug
+    // lookups to `{available: false, conflictingCompanyUid}` so the
+    // caller follows up with `/entity/{uid}`, which lands in the
+    // `/entity/cmp_` branch below — that's where `entityBody` and
+    // `entityStatus` overrides apply. The check-slug branch only
+    // honors `entityStatus` (so tests can simulate a 404/500 on the
+    // namespace lookup itself); its response shape stays fixed.
+    if (urlStr.includes("/entity/check-slug/me")) {
+      return {
+        ok: (overrides?.entityStatus ?? 200) < 400,
+        status: overrides?.entityStatus ?? 200,
+        json: async () => ({
+          available: false,
+          conflictingCompanyUid: mockEntity.uid,
+        }),
+        text: async () =>
+          JSON.stringify({
+            available: false,
+            conflictingCompanyUid: mockEntity.uid,
+          }),
+      };
+    }
+
+    // Kept for any tests that still mock the legacy global endpoint
+    // directly (none should, post-PR 67 — but harmless if invoked).
     if (urlStr.includes("/entity/by-slug/")) {
       return {
         ok: (overrides?.entityStatus ?? 200) < 400,
@@ -97,10 +122,16 @@ describe("resolveEntityContext", () => {
     expect(ctx.credentials.accessKeyId).toBe("ASIA_TEST_KEY");
     expect(ctx.region).toBe("us-east-1");
 
-    // Verify entity lookup used by-slug endpoint
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(String(fetchMock.mock.calls[0][0])).toContain("/entity/by-slug/company/acme");
-    expect(String(fetchMock.mock.calls[1][0])).toContain("/sts/vend");
+    // Verify entity lookup used the new per-user-namespace endpoint
+    // (PR 67) + a follow-up `/entity/{uid}` materialization + STS.
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(String(fetchMock.mock.calls[0][0])).toContain(
+      "/entity/check-slug/me?type=company&slug=acme",
+    );
+    expect(String(fetchMock.mock.calls[1][0])).toContain(
+      `/entity/${mockEntity.uid}`,
+    );
+    expect(String(fetchMock.mock.calls[2][0])).toContain("/sts/vend");
   });
 
   it("resolves context by UID directly", async () => {
@@ -120,7 +151,9 @@ describe("resolveEntityContext", () => {
     const ctx2 = await resolveEntityContext("acme", mockConfig);
 
     expect(ctx1).toBe(ctx2); // Same reference
-    expect(fetchMock).toHaveBeenCalledTimes(2); // Only 1 entity + 1 vend call
+    // 3 fetches per resolve under the new model: check-slug + entity.get + sts/vend.
+    // 1 resolve here (second call hits cache, no new fetches).
+    expect(fetchMock).toHaveBeenCalledTimes(3);
   });
 
   it("auto-refreshes when credentials expire soon", async () => {
@@ -137,7 +170,8 @@ describe("resolveEntityContext", () => {
     // Second call should refresh because <2 min remaining
     const ctx2 = await resolveEntityContext("acme", mockConfig);
     expect(ctx2).not.toBe(ctx1);
-    expect(fetchMock).toHaveBeenCalledTimes(4); // 2 entity + 2 vend calls
+    // 2 resolves × 3 fetches each = 6 under the new model.
+    expect(fetchMock).toHaveBeenCalledTimes(6);
   });
 
   it("throws when entity has no bucket", async () => {
@@ -153,8 +187,11 @@ describe("resolveEntityContext", () => {
   it("throws on entity lookup failure", async () => {
     setupFetchMock({ entityStatus: 404 });
 
+    // The namespace lookup fails first under the new model — error
+    // message now reflects "Failed to check slug" before the
+    // entity.get(uid) step is reached.
     await expect(resolveEntityContext("nonexistent", mockConfig)).rejects.toThrow(
-      /Failed to find entity/,
+      /Failed to check slug/,
     );
   });
 
@@ -201,12 +238,20 @@ describe("routing by UID prefix and vend-self dispatch", () => {
     expect(vendCalls[0]).toContain("/sts/vend-self");
   });
 
-  it("foo_bar slug: entity resolved via /entity/by-slug/company/foo_bar and credentials via /sts/vend", async () => {
+  it("foo_bar slug: entity resolved via /entity/check-slug/me + /entity/<uid> and credentials via /sts/vend", async () => {
     const calls: string[] = [];
     vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
       const u = String(url);
       calls.push(u);
-      if (u.includes("/entity/by-slug/")) {
+      if (u.includes("/entity/check-slug/me")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+          text: async () => "",
+        };
+      }
+      if (u.includes(`/entity/${mockEntity.uid}`)) {
         return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
       }
       if (u.includes("/sts/vend")) {
@@ -217,19 +262,29 @@ describe("routing by UID prefix and vend-self dispatch", () => {
 
     await resolveEntityContext("foo_bar", mockConfig);
 
-    expect(calls.some((u) => u.includes("/entity/by-slug/company/foo_bar"))).toBe(true);
+    expect(
+      calls.some((u) => u.includes("/entity/check-slug/me?type=company&slug=foo_bar")),
+    ).toBe(true);
     const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
     expect(vendCalls).toHaveLength(1);
     expect(vendCalls[0]).not.toContain("/sts/vend-self");
     expect(vendCalls[0]).toContain("/sts/vend");
   });
 
-  it("team_alpha slug: entity resolved via /entity/by-slug/company/team_alpha and credentials via /sts/vend", async () => {
+  it("team_alpha slug: entity resolved via /entity/check-slug/me + /entity/<uid> and credentials via /sts/vend", async () => {
     const calls: string[] = [];
     vi.stubGlobal("fetch", vi.fn().mockImplementation(async (url: string) => {
       const u = String(url);
       calls.push(u);
-      if (u.includes("/entity/by-slug/")) {
+      if (u.includes("/entity/check-slug/me")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+          text: async () => "",
+        };
+      }
+      if (u.includes(`/entity/${mockEntity.uid}`)) {
         return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
       }
       if (u.includes("/sts/vend")) {
@@ -240,7 +295,9 @@ describe("routing by UID prefix and vend-self dispatch", () => {
 
     await resolveEntityContext("team_alpha", mockConfig);
 
-    expect(calls.some((u) => u.includes("/entity/by-slug/company/team_alpha"))).toBe(true);
+    expect(
+      calls.some((u) => u.includes("/entity/check-slug/me?type=company&slug=team_alpha")),
+    ).toBe(true);
     const vendCalls = calls.filter((u) => u.includes("/sts/vend"));
     expect(vendCalls).toHaveLength(1);
     expect(vendCalls[0]).not.toContain("/sts/vend-self");
@@ -283,7 +340,9 @@ describe("refreshEntityContext", () => {
     const ctx2 = await refreshEntityContext("acme", mockConfig);
 
     expect(ctx2).not.toBe(ctx1);
-    expect(fetchMock).toHaveBeenCalledTimes(4); // 2 initial + 2 refresh
+    // 2 resolves × 3 fetches each = 6 under the new model
+    // (check-slug + entity.get + sts/vend each).
+    expect(fetchMock).toHaveBeenCalledTimes(6);
   });
 });
 

package/src/context.ts

@@ -14,9 +14,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 +82,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 +142,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 +170,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);
 }
 
@@ -171,17 +246,38 @@ async function fetchEntityBySlug(
   slug: string,
   config: VaultServiceConfig,
 ): Promise<EntityResponse> {
-  const res = await fetch(`${config.apiUrl}/entity/by-slug/${type}/${slug}`, {
+  // 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)}` },
   });
-  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(

package/src/vault-client.ts

@@ -332,6 +332,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 +350,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;