@indigoai-us/hq-cloud 5.1.8 → 5.1.9

package/src/bin/sync-runner.test.ts

@@ -15,7 +15,11 @@ import type {
   VaultClientSurface,
 } from "./sync-runner.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
-import type { Membership, EntityInfo } from "../vault-client.js";
+import type {
+  Membership,
+  EntityInfo,
+  PendingInviteByEmail,
+} from "../vault-client.js";
 import { VaultAuthError } from "../vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -70,11 +74,31 @@ function makeVaultStub(
   opts: {
     memberships?: Array<Pick<Membership, "companyUid">>;
     entityGet?: (uid: string) => Promise<EntityInfo>;
+    pendingInvites?: Array<Record<string, unknown>>;
+    ensurePerson?: (hints: {
+      ownerSub: string;
+      displayName: string;
+    }) => Promise<EntityInfo>;
+    claim?: (personUid: string) => Promise<void>;
   } = {},
 ): VaultClientSurface {
   const memberships = opts.memberships ?? [];
+  const pending = opts.pendingInvites ?? [];
   return {
     listMyMemberships: () => Promise.resolve(memberships as Membership[]),
+    listMyPendingInvitesByEmail: () =>
+      Promise.resolve(pending as unknown as PendingInviteByEmail[]),
+    claimPendingInvitesByEmail:
+      opts.claim ?? (() => Promise.resolve(undefined)),
+    ensureMyPersonEntity:
+      opts.ensurePerson ??
+      (() =>
+        Promise.resolve({
+          uid: "ent_person_default",
+          type: "person",
+          slug: "default-person",
+          status: "active",
+        } as unknown as EntityInfo)),
     entity: {
       get:
         opts.entityGet ??
@@ -181,12 +205,9 @@ describe("auth", () => {
   it("emits auth-error when VaultAuthError thrown during discovery", async () => {
     const deps = makeDeps({
       createVaultClient: () => ({
+        ...makeVaultStub(),
         listMyMemberships: () =>
           Promise.reject(new VaultAuthError("token expired")),
-        entity: {
-          get: (uid: string) =>
-            Promise.resolve({ uid, slug: uid } as unknown as EntityInfo),
-        },
       }),
     });
     const code = await runRunner(["--companies"], deps);
@@ -199,11 +220,8 @@ describe("auth", () => {
   it("emits error event and returns 1 on non-auth discovery failure", async () => {
     const deps = makeDeps({
       createVaultClient: () => ({
+        ...makeVaultStub(),
         listMyMemberships: () => Promise.reject(new Error("network down")),
-        entity: {
-          get: (uid: string) =>
-            Promise.resolve({ uid, slug: uid } as unknown as EntityInfo),
-        },
       }),
     });
     const code = await runRunner(["--companies"], deps);
@@ -218,6 +236,150 @@ describe("auth", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// claim-dance (first sign-in)
+// ---------------------------------------------------------------------------
+
+describe("claim-dance", () => {
+  const claims = {
+    sub: "sub-abc",
+    email: "stefan@getindigo.ai",
+    name: "Stefan Johnson",
+  };
+
+  it("claims pending invites + ensures person before listing memberships", async () => {
+    const ensureSpy = vi.fn().mockResolvedValue({
+      uid: "ent_person_stefan",
+      type: "person",
+      slug: "stefan-johnson",
+      status: "active",
+    });
+    const claimSpy = vi.fn().mockResolvedValue(undefined);
+    // First listMyMemberships returns the just-claimed row.
+    let listCalls = 0;
+    const stub = makeVaultStub({
+      pendingInvites: [
+        {
+          membershipKey: "inv_1",
+          companyUid: "cmp_indigo",
+          role: "owner",
+          invitedBy: "sub-admin",
+          invitedAt: "2026-04-20T00:00:00Z",
+        },
+      ],
+      ensurePerson: ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+      claim: claimSpy as unknown as VaultClientSurface["claimPendingInvitesByEmail"],
+    });
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.resolve([{ companyUid: "cmp_indigo" }] as Membership[]);
+    };
+
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(ensureSpy).toHaveBeenCalledWith({
+      ownerSub: "sub-abc",
+      displayName: "Stefan Johnson",
+    });
+    expect(claimSpy).toHaveBeenCalledWith("ent_person_stefan");
+    expect(listCalls).toBe(1);
+    // setup-needed must NOT fire — the user has memberships after the claim.
+    expect(deps.stdout.events().some((e) => e.type === "setup-needed")).toBe(
+      false,
+    );
+  });
+
+  it("skips ensurePerson + claim when no pending invites exist", async () => {
+    const ensureSpy = vi.fn();
+    const claimSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [],
+          ensurePerson:
+            ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+          claim: claimSpy as unknown as VaultClientSurface["claimPendingInvitesByEmail"],
+        }),
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    expect(ensureSpy).not.toHaveBeenCalled();
+    expect(claimSpy).not.toHaveBeenCalled();
+    // No memberships, no invites — truly empty → setup-needed is correct here.
+    expect(deps.stdout.events()).toEqual([{ type: "setup-needed" }]);
+  });
+
+  it("skips claim-dance entirely when no idToken claims are available", async () => {
+    const pendingSpy = vi.fn().mockResolvedValue([]);
+    const stub = makeVaultStub();
+    stub.listMyPendingInvitesByEmail =
+      pendingSpy as unknown as VaultClientSurface["listMyPendingInvitesByEmail"];
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => null,
+    });
+    await runRunner(["--companies"], deps);
+    expect(pendingSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not fail the run when claim-dance throws (best-effort)", async () => {
+    const stub = makeVaultStub({
+      memberships: [{ companyUid: "cmp_a" }],
+    });
+    stub.listMyPendingInvitesByEmail = () =>
+      Promise.reject(new Error("vault 500"));
+    const deps = makeDeps({
+      createVaultClient: () => stub,
+      getIdTokenClaims: () => claims,
+    });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    // Sync proceeds as usual for the existing membership.
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+    expect(deps.stderr.raw()).toContain("claim-dance skipped");
+  });
+
+  it("falls back to given_name + family_name when name claim is absent", async () => {
+    const ensureSpy = vi.fn().mockResolvedValue({
+      uid: "ent_person_x",
+      type: "person",
+      slug: "x",
+      status: "active",
+    });
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          pendingInvites: [
+            {
+              membershipKey: "inv_1",
+              companyUid: "cmp_x",
+              role: "owner",
+              invitedBy: "sub-admin",
+              invitedAt: "2026-04-20T00:00:00Z",
+            },
+          ],
+          ensurePerson:
+            ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+        }),
+      getIdTokenClaims: () => ({
+        sub: "sub-xyz",
+        given_name: "Ada",
+        family_name: "Lovelace",
+      }),
+    });
+    await runRunner(["--companies"], deps);
+    expect(ensureSpy).toHaveBeenCalledWith({
+      ownerSub: "sub-xyz",
+      displayName: "Ada Lovelace",
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // target resolution
 // ---------------------------------------------------------------------------
@@ -236,11 +398,11 @@ describe("target resolution", () => {
     const listSpy = vi.fn();
     const deps = makeDeps({
       createVaultClient: () => ({
-        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
-        entity: {
-          get: (uid: string) =>
+        ...makeVaultStub({
+          entityGet: (uid: string) =>
             Promise.resolve({ uid, slug: "acme" } as unknown as EntityInfo),
-        },
+        }),
+        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
       }),
     });
     const code = await runRunner(["--company", "cmp_abc"], deps);
@@ -303,6 +465,31 @@ describe("fanout-plan", () => {
     expect(plan.companies).toEqual([{ uid: "cmp_ghost", slug: "cmp_ghost" }]);
   });
 
+  it("includes entity.name on plan entries when available", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          memberships: [{ companyUid: "cmp_a" }, { companyUid: "cmp_b" }],
+          entityGet: (uid: string) =>
+            Promise.resolve({
+              uid,
+              slug: uid === "cmp_a" ? "acme" : "beta",
+              name: uid === "cmp_a" ? "Acme Corp" : undefined,
+            } as unknown as EntityInfo),
+        }),
+    });
+
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(0);
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<RunnerEvent, { type: "fanout-plan" }>;
+    expect(plan.companies).toEqual([
+      { uid: "cmp_a", slug: "acme", name: "Acme Corp" },
+      { uid: "cmp_b", slug: "beta" },
+    ]);
+  });
+
   it("degrades to UID when entity.get returns falsy slug", async () => {
     const deps = makeDeps({
       createVaultClient: () =>

package/src/bin/sync-runner.ts

@@ -38,12 +38,15 @@ import * as fs from "fs";
 import { fileURLToPath } from "url";
 import {
   getValidAccessToken,
+  loadCachedTokens,
   VaultClient,
   VaultAuthError,
   type CognitoAuthConfig,
+  type CognitoTokens,
   type VaultServiceConfig,
   type Membership,
   type EntityInfo,
+  type PendingInviteByEmail,
 } from "../index.js";
 import { sync as defaultSync } from "../cli/sync.js";
 import type {
@@ -90,7 +93,7 @@ export type RunnerEvent =
   | { type: "auth-error"; message: string }
   | {
       type: "fanout-plan";
-      companies: Array<{ uid: string; slug: string }>;
+      companies: Array<{ uid: string; slug: string; name?: string }>;
     }
   | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
   | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
@@ -113,11 +116,26 @@ export type RunnerEvent =
  */
 export interface VaultClientSurface {
   listMyMemberships: () => Promise<Membership[]>;
+  listMyPendingInvitesByEmail: () => Promise<PendingInviteByEmail[]>;
+  claimPendingInvitesByEmail: (personUid: string) => Promise<void>;
+  ensureMyPersonEntity: (hints: {
+    ownerSub: string;
+    displayName: string;
+  }) => Promise<EntityInfo>;
   entity: {
     get: (uid: string) => Promise<EntityInfo>;
   };
 }
 
+/** Minimal shape of the claims we read off the Cognito idToken. */
+interface IdTokenClaims {
+  sub?: string;
+  email?: string;
+  name?: string;
+  given_name?: string;
+  family_name?: string;
+}
+
 export interface RunnerDeps {
   /** Where to write ndjson events. Defaults to `process.stdout`. */
   stdout?: { write: (chunk: string) => boolean | void };
@@ -125,16 +143,93 @@ export interface RunnerDeps {
   stderr?: { write: (chunk: string) => boolean | void };
   /** Resolve a valid access token. Defaults to `getValidAccessToken` non-interactive. */
   getAccessToken?: () => Promise<string>;
+  /**
+   * Read the caller's identity claims (sub/email/name) off the cached Cognito
+   * idToken. Defaults to decoding `loadCachedTokens().idToken`. Returns `null`
+   * when no cached tokens exist — the runner will then skip the claim-dance
+   * and fall through to the usual listMyMemberships path.
+   */
+  getIdTokenClaims?: () => IdTokenClaims | null;
   /**
    * Produce a VaultClient-like object. Defaults to `new VaultClient(config)`.
-   * Tests inject a stub here — only `listMyMemberships` and `entity.get` are
-   * called by the runner, so stubs only need to implement those.
+   * Tests inject a stub here — the runner only calls the methods listed in
+   * `VaultClientSurface`.
    */
   createVaultClient?: (config: VaultServiceConfig) => VaultClientSurface;
   /** Sync function. Defaults to `cli/sync.sync`. */
   sync?: (options: SyncOptions) => Promise<SyncResult>;
 }
 
+// ---------------------------------------------------------------------------
+// JWT claim decoder — inlined to avoid pulling a dep just to read an idToken.
+// We do NOT verify the signature here — Cognito already did that when it
+// issued the token, and we only read the public claims (sub/email/name) to
+// drive the claim-dance + create the person entity. If the token is tampered
+// with, the downstream vault-service call will reject it (signature-verified
+// there) long before any claimed value causes harm.
+// ---------------------------------------------------------------------------
+
+function decodeJwtClaims(jwt: string): IdTokenClaims | null {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) return null;
+  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");
+    return JSON.parse(json) as IdTokenClaims;
+  } catch {
+    return null;
+  }
+}
+
+function defaultGetIdTokenClaims(): IdTokenClaims | null {
+  const tokens: CognitoTokens | null = loadCachedTokens();
+  if (!tokens?.idToken) return null;
+  return decodeJwtClaims(tokens.idToken);
+}
+
+/**
+ * Best-effort: claim any email-keyed pending invites that were sent before
+ * this user had a person entity. Mirrors the installer's vault-handoff flow.
+ *
+ * Silent on the happy path — only logs to stderr on soft failures (so a
+ * transient network blip doesn't block the sync). Never throws: a caller who
+ * can't list memberships despite an unclaimed invite is no worse off than the
+ * pre-claim-dance behavior (which was to emit setup-needed).
+ */
+async function runClaimDance(
+  client: VaultClientSurface,
+  claims: IdTokenClaims,
+  stderr: { write: (chunk: string) => boolean | void },
+): Promise<void> {
+  try {
+    const pending = await client.listMyPendingInvitesByEmail();
+    if (pending.length === 0) return;
+
+    const displayName =
+      claims.name ??
+      [claims.given_name, claims.family_name].filter(Boolean).join(" ") ??
+      claims.email ??
+      "";
+    const ownerSub = claims.sub ?? "";
+    if (!ownerSub || !displayName) {
+      stderr.write(
+        "hq-sync-runner: skipping claim-dance — idToken missing sub/name\n",
+      );
+      return;
+    }
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub,
+      displayName,
+    });
+    await client.claimPendingInvitesByEmail(person.uid);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`hq-sync-runner: claim-dance skipped — ${msg}\n`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // argv parser — intentionally minimal (no commander/yargs dep)
 // ---------------------------------------------------------------------------
@@ -244,8 +339,20 @@ export async function runRunner(
   let memberships: Pick<Membership, "companyUid">[];
   try {
     if (parsed.companies) {
+      // Before giving up on memberships, run the claim-dance: new users signed
+      // in via the tray may have email-keyed invites waiting for them. Without
+      // this, an invited user would see "setup-needed" on every tray click.
+      const getClaims = deps.getIdTokenClaims ?? defaultGetIdTokenClaims;
+      const claims = getClaims();
+      if (claims) {
+        await runClaimDance(client, claims, stderr);
+      }
+
       memberships = await client.listMyMemberships();
       if (memberships.length === 0) {
+        // Truly empty — still a valid state (no memberships = nothing to
+        // sync). The tray will show a friendly "create your first company"
+        // CTA rather than an alarm banner.
         emit({ type: "setup-needed" });
         return 0;
       }
@@ -278,16 +385,18 @@ export async function runRunner(
   // The menubar wants "Syncing indigo" in its UI, not the raw cmp_* ULID.
   // If the entity fetch fails for some row (entity deleted, scoping issue),
   // degrade to using the UID as the slug rather than aborting the run.
-  const plan: Array<{ uid: string; slug: string }> = [];
+  const plan: Array<{ uid: string; slug: string; name?: string }> = [];
   for (const m of memberships) {
     let slug = m.companyUid;
+    let name: string | undefined;
     try {
       const info = await client.entity.get(m.companyUid);
       slug = info.slug || m.companyUid;
+      name = info.name;
     } catch {
       // Best-effort — keep UID as the display identifier.
     }
-    plan.push({ uid: m.companyUid, slug });
+    plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
   emit({ type: "fanout-plan", companies: plan });
 

package/src/index.ts

@@ -70,6 +70,7 @@ export type {
   EntityInfo,
   CreateEntityInput,
   CreateEntityResult,
+  PendingInviteByEmail,
 } from "./vault-client.js";
 
 // STS child vending (VLT-8)

package/src/vault-client.test.ts

@@ -387,4 +387,177 @@ describe("API surface", () => {
     const memberships = await client.listMyMemberships();
     expect(memberships).toEqual([]);
   });
+
+  it("listMyPendingInvitesByEmail hits GET /membership/pending-by-email", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        invites: [
+          {
+            membershipKey: "email:stefan@getindigo.ai#cmp_abc",
+            companyUid: "cmp_abc",
+            role: "owner",
+            invitedBy: "sub-admin",
+            invitedAt: "2026-04-20T00:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    const invites = await client.listMyPendingInvitesByEmail();
+    expect(invites).toHaveLength(1);
+    expect(invites[0].companyUid).toBe("cmp_abc");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/membership/pending-by-email",
+    );
+    expect(init.method).toBe("GET");
+  });
+
+  it("listMyPendingInvitesByEmail returns [] when server omits the key", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    const invites = await client.listMyPendingInvitesByEmail();
+    expect(invites).toEqual([]);
+  });
+
+  it("claimPendingInvitesByEmail POSTs personUid to /membership/claim-by-email", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+
+    await client.claimPendingInvitesByEmail("ent_person_stefan");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/membership/claim-by-email",
+    );
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      personUid: "ent_person_stefan",
+    });
+  });
+});
+
+describe("VaultClient identity bootstrap", () => {
+  let client: VaultClient;
+  let fetchSpy: MockInstance<typeof fetch>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+    fetchSpy.mockResolvedValue(jsonResponse(200, {}));
+    client = new VaultClient({
+      apiUrl: "https://vault.test.example.com",
+      authToken: "test-token",
+      region: "us-east-1",
+    });
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it("entity.listByType GETs /entity/by-type/{type}", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          {
+            uid: "ent_person_stefan",
+            slug: "stefan-johnson",
+            type: "person",
+            status: "active",
+          },
+        ],
+      }),
+    );
+
+    const entities = await client.entity.listByType("person");
+    expect(entities).toHaveLength(1);
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe(
+      "https://vault.test.example.com/entity/by-type/person",
+    );
+  });
+
+  it("entity.listByType returns [] when server omits the key", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    const entities = await client.entity.listByType("person");
+    expect(entities).toEqual([]);
+  });
+
+  it("ensureMyPersonEntity short-circuits when a person entity already exists", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          {
+            uid: "ent_person_existing",
+            slug: "already-there",
+            type: "person",
+            status: "active",
+          },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-abc",
+      displayName: "Stefan Johnson",
+    });
+
+    expect(person.uid).toBe("ent_person_existing");
+    // Only one HTTP call — list. No POST /entity.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("ensureMyPersonEntity POSTs /entity with a slug derived from displayName when none exist", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { entities: [] }))
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          entity: {
+            uid: "ent_person_new",
+            slug: "stefan-johnson",
+            type: "person",
+            status: "active",
+          },
+        }),
+      );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-abc",
+      displayName: "Stefan Johnson",
+    });
+
+    expect(person.uid).toBe("ent_person_new");
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    const [url, init] = fetchSpy.mock.calls[1] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/entity");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      type: "person",
+      name: "Stefan Johnson",
+      slug: "stefan-johnson",
+    });
+  });
+
+  it("ensureMyPersonEntity falls back to user-<sub-suffix> when displayName slugifies to empty", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { entities: [] }))
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          entity: {
+            uid: "ent_person_new",
+            slug: "user-12345678",
+            type: "person",
+            status: "active",
+          },
+        }),
+      );
+
+    await client.ensureMyPersonEntity({
+      ownerSub: "sub-abcdef12345678",
+      displayName: "!!!",
+    });
+
+    const [, init] = fetchSpy.mock.calls[1] as [string, RequestInit];
+    const body = JSON.parse(init.body as string);
+    expect(body.slug).toBe("user-12345678");
+  });
 });