@indigoai-us/hq-cloud 6.14.12 → 6.14.13

package/src/vault-client.test.ts

@@ -92,8 +92,8 @@ describe("auth header injection", () => {
 
 describe("error mapping", () => {
   it("maps 401 to VaultAuthError", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      jsonResponse(401, { message: "Token expired" }),
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(jsonResponse(401, { message: "Token expired" })),
     );
 
     await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
@@ -197,13 +197,100 @@ describe("retry behavior", () => {
     expect(fetchSpy).toHaveBeenCalledTimes(4);
   });
 
-  it("does not retry on 401 (non-transient)", async () => {
-    fetchSpy.mockResolvedValueOnce(jsonResponse(401, { message: "Expired" }));
+  // Regression: the deploy access-gate 401 of 2026-07-19. A token that expired
+  // mid-request is recoverable — callers passing a getter can mint a fresh one —
+  // but the client threw instead of retrying, so a transient auth lapse surfaced
+  // as a hard failure and the caller degraded a members-only gate to a password.
+  it("retries a 401 once when the token getter yields a fresh token", async () => {
+    const tokens = ["stale-token", "fresh-token"];
+    const getToken = vi.fn(async () => tokens.shift() ?? "fresh-token");
+    const c = new VaultClient({ ...TEST_CONFIG, authToken: getToken });
 
-    await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(401, { message: "Token expired" }))
+      .mockResolvedValueOnce(jsonResponse(200, { members: [{ personUid: "psn_1" }] }));
+
+    const result = await c.listMembersOfCompany("cmp_abc");
+    expect(result).toHaveLength(1);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+    const authHeader = (call: number) =>
+      (fetchSpy.mock.calls[call]![1] as RequestInit).headers as Record<string, string>;
+    expect(authHeader(0).Authorization).toBe("Bearer stale-token");
+    expect(authHeader(1).Authorization).toBe("Bearer fresh-token");
+  });
+
+  it("does not retry a 401 when the getter returns the same token", async () => {
+    const getToken = vi.fn(async () => "unchanging-token");
+    const c = new VaultClient({ ...TEST_CONFIG, authToken: getToken });
+
+    fetchSpy.mockResolvedValue(jsonResponse(401, { message: "Nope" }));
+
+    await expect(c.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
     expect(fetchSpy).toHaveBeenCalledTimes(1);
   });
 
+  // Review finding: the auth retry used to share the transient budget, so a
+  // 401 on the LAST attempt set the flag, hit `continue`, and fell out of the
+  // loop having never actually retried — the recovery silently did nothing in
+  // exactly the case it was written for.
+  it("still retries when the 401 lands on the final attempt", async () => {
+    const tokens = ["stale", "stale", "stale", "stale", "fresh"];
+    const getToken = vi.fn(async () => tokens.shift() ?? "fresh");
+    const c = new VaultClient({ ...TEST_CONFIG, authToken: getToken });
+
+    // Burn the whole transient budget first (attempts 0,1,2), so the 401 lands
+    // on attempt 3 — the last one the shared-budget loop would ever run.
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(401, { message: "Token expired" }))
+      .mockResolvedValueOnce(jsonResponse(200, { members: [{ personUid: "psn_1" }] }));
+
+    const result = await c.listMembersOfCompany("cmp_abc");
+    expect(result).toHaveLength(1);
+    // 5th call only happens if the auth retry got its own budget.
+    expect(fetchSpy).toHaveBeenCalledTimes(5);
+  });
+
+  // Review finding: a 401 consumed a transient-retry slot, so a request that
+  // hit an auth lapse had fewer retries left for genuine 5xx afterwards.
+  it("does not spend transient-retry budget on the auth retry", async () => {
+    const tokens = ["stale", "fresh"];
+    const getToken = vi.fn(async () => tokens.shift() ?? "fresh");
+    const c = new VaultClient({ ...TEST_CONFIG, authToken: getToken });
+
+    // 401 (free retry) then three 500s — the full transient budget must still
+    // be available, so the 4th call succeeds.
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(401, { message: "Token expired" }))
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(500, { message: "boom" }))
+      .mockResolvedValueOnce(jsonResponse(200, { members: [{ personUid: "psn_1" }] }));
+
+    const result = await c.listMembersOfCompany("cmp_abc");
+    expect(result).toHaveLength(1);
+    expect(fetchSpy).toHaveBeenCalledTimes(5);
+  });
+
+  it("retries a 401 at most once even if the token keeps changing", async () => {
+    let n = 0;
+    const getToken = vi.fn(async () => `token-${n++}`);
+    const c = new VaultClient({ ...TEST_CONFIG, authToken: getToken });
+
+    // mockImplementation (not mockResolvedValue): each attempt needs its own
+    // Response, since the body can only be read once.
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(jsonResponse(401, { message: "Still no" })),
+    );
+
+    await expect(c.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
+    // 1 initial + exactly 1 auth retry — never a retry storm against the authorizer
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
   it("does not retry on 403 (non-transient)", async () => {
     fetchSpy.mockResolvedValueOnce(jsonResponse(403, { message: "Forbidden" }));
 
@@ -908,8 +995,10 @@ describe("listMyExplicitGrants (US-004)", () => {
   });
 
   it("maps 401 to VaultAuthError", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      jsonResponse(401, { error: "Missing or invalid authorization token" }),
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(
+        jsonResponse(401, { error: "Missing or invalid authorization token" }),
+      ),
     );
 
     await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
@@ -980,8 +1069,8 @@ describe("getMembershipSyncConfig (US-004)", () => {
   });
 
   it("maps 401 to VaultAuthError", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      jsonResponse(401, { error: "Token expired" }),
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(jsonResponse(401, { error: "Token expired" })),
     );
 
     await expect(
@@ -1067,8 +1156,8 @@ describe("setMembershipSyncConfig (US-004)", () => {
   });
 
   it("maps 401 to VaultAuthError", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      jsonResponse(401, { error: "Token expired" }),
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(jsonResponse(401, { error: "Token expired" })),
     );
 
     await expect(

package/src/vault-client.ts

@@ -10,6 +10,7 @@ import type { ClientInfo, VaultServiceConfig } from "./types.js";
 import { buildClientHeaders } from "./client-info.js";
 import { emitCloudTelemetry } from "./telemetry-events.js";
 import { z } from "zod";
+import { accessTokenFingerprint } from "./cognito-auth.js";
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -27,7 +28,10 @@ export class VaultClientError extends Error {
 }
 
 export class VaultAuthError extends VaultClientError {
-  constructor(message = "Authentication failed — session expired or invalid") {
+  constructor(
+    message = "Authentication failed — session expired or invalid",
+    public readonly tokenFingerprint?: string,
+  ) {
     super(message, 401);
     this.name = "VaultAuthError";
   }
@@ -1375,15 +1379,33 @@ export class VaultClient {
   ): Promise<T> {
     let lastError: Error | undefined;
     const maxRetries = options.maxRetries ?? MAX_RETRIES;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      if (attempt > 0) {
+    // A 401 is not in isTransient() because most 401s are genuinely terminal.
+    // But one shape of 401 is fully recoverable: the access token expired
+    // between the caller resolving it and this request landing. Callers that
+    // pass a getter (getValidAccessToken) can mint a fresh token on demand, so
+    // we re-resolve once and retry IF the token actually changed. Static-string
+    // callers get the same value back and fall through to the throw, so this
+    // costs them nothing. Bounded to one attempt: a genuinely bad credential
+    // must not turn into a retry storm against the authorizer.
+    let authRetried = false;
+    // The auth retry gets its own budget rather than borrowing from the
+    // transient one. Sharing had two defects: a 401 early on left fewer
+    // retries for later 5xx, and a 401 on the FINAL attempt set the flag,
+    // hit `continue`, and fell out of the loop having never actually retried.
+    let maxAttempts = maxRetries;
+    // Backoff exists to let a rate limit or a struggling server recover.
+    // Neither applies to a token swap, so the auth retry goes out immediately.
+    let noBackoffAt = -1;
+
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+      if (attempt > 0 && attempt !== noBackoffAt) {
         const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
         await sleep(delay);
       }
 
+      const authToken = await this.getAuthToken();
       const headers: Record<string, string> = {
-        Authorization: `Bearer ${await this.getAuthToken()}`,
+        Authorization: `Bearer ${authToken}`,
         Accept: "application/json",
         ...buildClientHeaders(this.clientInfo),
       };
@@ -1410,7 +1432,7 @@ export class VaultClient {
         res = await fetch(`${this.apiUrl}${path}`, init);
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
-        if (attempt < maxRetries) continue;
+        if (attempt < maxAttempts) continue;
         throw lastError;
       } finally {
         if (timeout !== undefined) clearTimeout(timeout);
@@ -1444,24 +1466,47 @@ export class VaultClient {
 
       const responseBody = await res.text();
 
+      // Expired-token 401 → re-resolve once and retry with the fresh token.
+      // Residual gap (deliberate): if the local cache still considers the token
+      // valid — clock skew, or a server-side revocation the client can't see —
+      // the getter returns the same string and we fall through to the throw.
+      // Fixing that needs a force-refresh hook on the token getter contract.
+      if (res.status === 401 && !authRetried) {
+        authRetried = true;
+        const refreshed = await this.getAuthToken().catch(() => undefined);
+        if (refreshed && refreshed !== authToken) {
+          lastError = this.mapError(res.status, responseBody, authToken);
+          maxAttempts++; // free retry — must not eat the transient budget
+          noBackoffAt = attempt + 1;
+          continue;
+        }
+      }
+
       // Non-retryable errors → throw immediately
       if (!isTransient(res.status)) {
-        throw this.mapError(res.status, responseBody);
+        throw this.mapError(res.status, responseBody, authToken);
       }
 
       // Retryable — store and loop
-      lastError = this.mapError(res.status, responseBody);
+      lastError = this.mapError(res.status, responseBody, authToken);
     }
 
     throw lastError ?? new VaultClientError("Request failed after retries", 500);
   }
 
-  private mapError(status: number, body: string): VaultClientError {
+  private mapError(
+    status: number,
+    body: string,
+    authToken?: string,
+  ): VaultClientError {
     const message = this.extractMessage(body);
 
     switch (status) {
       case 401:
-        return new VaultAuthError(message);
+        return new VaultAuthError(
+          message,
+          authToken ? accessTokenFingerprint(authToken) : undefined,
+        );
       case 403:
         return new VaultPermissionDeniedError(message);
       case 404:

package/test/share-sync.integration.test.ts

@@ -1,5 +1,5 @@
 /**
- * Integration test: share/sync lifecycle (VLT-5 US-003).
+ * Integration test: laptop → vault → mini share/sync lifecycle (VLT-5 US-003).
  *
  * Exercises the full share/sync cycle against a real dev-stage company entity
  * using real STS vending (VLT-3). Requires:
@@ -7,14 +7,17 @@
  *   - VAULT_AUTH_TOKEN env var (Cognito JWT for an active member)
  *   - VAULT_TEST_COMPANY env var (company slug with an active entity + bucket)
  *
- * Run: pnpm test:e2e
+ * Run: pnpm test:e2e:laptop-mini
  *
  * This test:
- *   1. M1 shares file A
- *   2. M2 (same creds, different local dir) syncs → receives A
- *   3. M2 shares file B
- *   4. M1 syncs → receives B
- *   5. M1 edits A locally + M2 pushes newer A → M1 syncs with --on-conflict=keep
+ *   1. Laptop shares a handoff into the vault
+ *   2. Mini (same membership, separate local root) syncs and receives it
+ *   3. Mini shares a finding back through the vault
+ *   4. Laptop syncs and receives it
+ *   5. Laptop keeps a local edit when Mini pushes a divergent update
+ *
+ * This deliberately exercises the vault transport only. The optional git
+ * handoff mirror is a separate subsystem and is not required for this path.
  *
  * Cleanup: all shared files are deleted from S3 on teardown.
  */
@@ -42,7 +45,7 @@ const canRun = VAULT_API_URL && VAULT_AUTH_TOKEN && VAULT_TEST_COMPANY;
 
 const TEST_PREFIX = `__integration-test-${Date.now()}`;
 
-describe.skipIf(!canRun)("share-sync integration", () => {
+describe.skipIf(!canRun)("laptop-vault-mini share-sync integration", () => {
   let vaultConfig: VaultServiceConfig;
   let m1Root: string;
   let m2Root: string;
@@ -100,7 +103,7 @@ describe.skipIf(!canRun)("share-sync integration", () => {
     }
   });
 
-  it("completes the full share/sync lifecycle", async () => {
+  it("moves a handoff laptop → vault → mini and a finding back", async () => {
     await setup();
 
     // --- Step 1: M1 shares file A ---