@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/cognito-auth.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for cognito-auth.ts — focus on the `expiresAt` shape contract.
+ *
+ * Canonical on-disk shape is ISO 8601 (what both writers emit). The reader
+ * also tolerates a raw number (ms since epoch) for forward/backward compat
+ * during rollouts, and fails safe on anything unparseable.
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Sandbox HOME *before* importing the module — it reads os.homedir() at load
+// time to compute the cache file path.
+let originalHome: string | undefined;
+let tmpHome: string;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-cognito-auth-test-"));
+  process.env.HOME = tmpHome;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+async function importModule() {
+  return await import("./cognito-auth.js");
+}
+
+const baseTokens = {
+  accessToken: "access",
+  idToken: "id",
+  refreshToken: "refresh",
+  tokenType: "Bearer" as const,
+};
+
+// ---------------------------------------------------------------------------
+// Reader: isExpiring accepts both shapes and fails safe
+// ---------------------------------------------------------------------------
+
+describe("isExpiring — expiresAt shape tolerance", () => {
+  it("returns false for ISO string far in the future", async () => {
+    const { isExpiring } = await importModule();
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    expect(isExpiring({ ...baseTokens, expiresAt: future })).toBe(false);
+  });
+
+  it("returns true for ISO string within the buffer window", async () => {
+    const { isExpiring } = await importModule();
+    const soon = new Date(Date.now() + 10 * 1000).toISOString();
+    expect(isExpiring({ ...baseTokens, expiresAt: soon }, 60)).toBe(true);
+  });
+
+  it("returns false for raw number (ms) far in the future", async () => {
+    const { isExpiring } = await importModule();
+    const future = Date.now() + 60 * 60 * 1000;
+    // Cast because the type says string; the point is runtime tolerance.
+    expect(
+      isExpiring({ ...baseTokens, expiresAt: future as unknown as string }),
+    ).toBe(false);
+  });
+
+  it("returns true for raw number (ms) within the buffer window", async () => {
+    const { isExpiring } = await importModule();
+    const soon = Date.now() + 10 * 1000;
+    expect(
+      isExpiring(
+        { ...baseTokens, expiresAt: soon as unknown as string },
+        60,
+      ),
+    ).toBe(true);
+  });
+
+  it("fails safe (returns true) for malformed expiresAt", async () => {
+    const { isExpiring } = await importModule();
+    expect(
+      isExpiring({ ...baseTokens, expiresAt: "not a date" }),
+    ).toBe(true);
+    expect(
+      isExpiring({
+        ...baseTokens,
+        expiresAt: undefined as unknown as string,
+      }),
+    ).toBe(true);
+    expect(
+      isExpiring({
+        ...baseTokens,
+        expiresAt: Number.NaN as unknown as string,
+      }),
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Round-trip: writers emit ISO, readers read ISO
+// ---------------------------------------------------------------------------
+
+describe("expiresAt shape round-trip", () => {
+  it("saveCachedTokens + loadCachedTokens preserves ISO string shape", async () => {
+    const { saveCachedTokens, loadCachedTokens } = await importModule();
+    const iso = new Date(Date.now() + 3600 * 1000).toISOString();
+    saveCachedTokens({ ...baseTokens, expiresAt: iso });
+    const loaded = loadCachedTokens();
+    expect(loaded).not.toBeNull();
+    expect(typeof loaded?.expiresAt).toBe("string");
+    expect(loaded?.expiresAt).toBe(iso);
+    expect(loaded?.expiresAt).toMatch(
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/,
+    );
+  });
+
+  it("refreshTokens writes an ISO string to cache", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            access_token: "new-access",
+            id_token: "new-id",
+            refresh_token: "new-refresh",
+            expires_in: 3600,
+            token_type: "Bearer",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      ),
+    );
+
+    const { refreshTokens, loadCachedTokens } = await importModule();
+    const result = await refreshTokens(
+      {
+        region: "us-east-1",
+        userPoolDomain: "hq-vault-dev",
+        clientId: "test-client",
+      },
+      "prior-refresh-token",
+    );
+
+    expect(typeof result.expiresAt).toBe("string");
+    expect(result.expiresAt).toMatch(
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/,
+    );
+
+    const onDisk = loadCachedTokens();
+    expect(onDisk?.expiresAt).toBe(result.expiresAt);
+    expect(typeof onDisk?.expiresAt).toBe("string");
+  });
+});

package/src/cognito-auth.ts

@@ -85,9 +85,26 @@ export function clearCachedTokens(): void {
   if (fs.existsSync(TOKEN_FILE)) fs.unlinkSync(TOKEN_FILE);
 }
 
+/**
+ * Parse `expiresAt` to epoch-ms. Canonical on-disk shape is ISO 8601 (what
+ * both writers in this file emit), but older/external writers may have left a
+ * raw number. Accept both so a shape mismatch during rollout doesn't wedge
+ * sign-in. Returns null for anything unparseable — callers should treat that
+ * as "expired" and force a refresh.
+ */
+function parseExpiresAtMs(raw: unknown): number | null {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : null;
+  if (typeof raw === "string") {
+    const ms = new Date(raw).getTime();
+    return Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}
+
 /** True when the token expires within the given buffer (default 60s). */
 export function isExpiring(tokens: CognitoTokens, bufferSeconds = 60): boolean {
-  const expiresAt = new Date(tokens.expiresAt).getTime();
+  const expiresAt = parseExpiresAtMs(tokens.expiresAt);
+  if (expiresAt === null) return true;
   return expiresAt - Date.now() < bufferSeconds * 1000;
 }
 

package/src/context.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Unit tests for context.ts — entity context resolution (VLT-5 US-001).
+ *
+ * Uses a mock fetch to simulate vault-service API responses.
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  resolveEntityContext,
+  refreshEntityContext,
+  clearContextCache,
+  isExpiringSoon,
+} from "./context.js";
+import type { VaultServiceConfig } from "./types.js";
+
+const mockConfig: VaultServiceConfig = {
+  apiUrl: "https://vault-api.test",
+  authToken: "test-jwt-token",
+  region: "us-east-1",
+};
+
+const mockEntity = {
+  uid: "cmp_01ABCDEF",
+  slug: "acme",
+  bucketName: "hq-vault-acme-123",
+  status: "active",
+};
+
+const mockVendResponse = {
+  credentials: {
+    accessKeyId: "ASIA_TEST_KEY",
+    secretAccessKey: "test-secret",
+    sessionToken: "test-session-token",
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+};
+
+function setupFetchMock(overrides?: {
+  entityStatus?: number;
+  entityBody?: unknown;
+  vendStatus?: number;
+  vendBody?: unknown;
+}) {
+  const fetchMock = vi.fn();
+
+  fetchMock.mockImplementation(async (url: string) => {
+    const urlStr = String(url);
+
+    if (urlStr.includes("/entity/by-slug/")) {
+      return {
+        ok: (overrides?.entityStatus ?? 200) < 400,
+        status: overrides?.entityStatus ?? 200,
+        json: async () => overrides?.entityBody ?? { entity: mockEntity },
+        text: async () => JSON.stringify(overrides?.entityBody ?? { entity: mockEntity }),
+      };
+    }
+
+    if (urlStr.includes("/entity/cmp_")) {
+      return {
+        ok: (overrides?.entityStatus ?? 200) < 400,
+        status: overrides?.entityStatus ?? 200,
+        json: async () => overrides?.entityBody ?? { entity: mockEntity },
+        text: async () => JSON.stringify(overrides?.entityBody ?? { entity: mockEntity }),
+      };
+    }
+
+    if (urlStr.includes("/sts/vend")) {
+      return {
+        ok: (overrides?.vendStatus ?? 200) < 400,
+        status: overrides?.vendStatus ?? 200,
+        json: async () => overrides?.vendBody ?? mockVendResponse,
+        text: async () => JSON.stringify(overrides?.vendBody ?? mockVendResponse),
+      };
+    }
+
+    return { ok: false, status: 404, text: async () => "Not found" };
+  });
+
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("resolveEntityContext", () => {
+  beforeEach(() => {
+    clearContextCache();
+    vi.restoreAllMocks();
+  });
+
+  it("resolves context by slug", async () => {
+    const fetchMock = setupFetchMock();
+
+    const ctx = await resolveEntityContext("acme", mockConfig);
+
+    expect(ctx.uid).toBe("cmp_01ABCDEF");
+    expect(ctx.bucketName).toBe("hq-vault-acme-123");
+    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");
+  });
+
+  it("resolves context by UID directly", async () => {
+    const fetchMock = setupFetchMock();
+
+    const ctx = await resolveEntityContext("cmp_01ABCDEF", mockConfig);
+
+    expect(ctx.uid).toBe("cmp_01ABCDEF");
+    // Verify entity lookup used direct UID endpoint
+    expect(String(fetchMock.mock.calls[0][0])).toContain("/entity/cmp_01ABCDEF");
+  });
+
+  it("returns cached context when credentials are fresh", async () => {
+    const fetchMock = setupFetchMock();
+
+    const ctx1 = await resolveEntityContext("acme", mockConfig);
+    const ctx2 = await resolveEntityContext("acme", mockConfig);
+
+    expect(ctx1).toBe(ctx2); // Same reference
+    expect(fetchMock).toHaveBeenCalledTimes(2); // Only 1 entity + 1 vend call
+  });
+
+  it("auto-refreshes when credentials expire soon", async () => {
+    const almostExpired = new Date(Date.now() + 60 * 1000).toISOString(); // 1 min left
+    const fetchMock = setupFetchMock({
+      vendBody: {
+        credentials: mockVendResponse.credentials,
+        expiresAt: almostExpired,
+      },
+    });
+
+    const ctx1 = await resolveEntityContext("acme", mockConfig);
+
+    // 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
+  });
+
+  it("throws when entity has no bucket", async () => {
+    setupFetchMock({
+      entityBody: { entity: { ...mockEntity, bucketName: undefined } },
+    });
+
+    await expect(resolveEntityContext("acme", mockConfig)).rejects.toThrow(
+      /no bucket provisioned/,
+    );
+  });
+
+  it("throws on entity lookup failure", async () => {
+    setupFetchMock({ entityStatus: 404 });
+
+    await expect(resolveEntityContext("nonexistent", mockConfig)).rejects.toThrow(
+      /Failed to find entity/,
+    );
+  });
+
+  it("throws on STS vend failure", async () => {
+    setupFetchMock({ vendStatus: 403 });
+
+    await expect(resolveEntityContext("acme", mockConfig)).rejects.toThrow(
+      /STS vend failed/,
+    );
+  });
+});
+
+describe("refreshEntityContext", () => {
+  beforeEach(() => {
+    clearContextCache();
+    vi.restoreAllMocks();
+  });
+
+  it("evicts cache and fetches fresh credentials", async () => {
+    const fetchMock = setupFetchMock();
+
+    const ctx1 = await resolveEntityContext("acme", mockConfig);
+    const ctx2 = await refreshEntityContext("acme", mockConfig);
+
+    expect(ctx2).not.toBe(ctx1);
+    expect(fetchMock).toHaveBeenCalledTimes(4); // 2 initial + 2 refresh
+  });
+});
+
+describe("isExpiringSoon", () => {
+  it("returns false when well within TTL", () => {
+    const future = new Date(Date.now() + 10 * 60 * 1000).toISOString();
+    expect(isExpiringSoon(future)).toBe(false);
+  });
+
+  it("returns true when within 2 minutes", () => {
+    const soon = new Date(Date.now() + 90 * 1000).toISOString();
+    expect(isExpiringSoon(soon)).toBe(true);
+  });
+
+  it("returns true when already expired", () => {
+    const past = new Date(Date.now() - 1000).toISOString();
+    expect(isExpiringSoon(past)).toBe(true);
+  });
+});

package/src/context.ts

@@ -0,0 +1,178 @@
+/**
+ * Entity context resolution (VLT-5 US-001).
+ *
+ * Resolves an entity (company) via vault-service, vends STS-scoped credentials,
+ * and returns an EntityContext for S3 operations. Handles auto-refresh when
+ * credentials are within 2 minutes of expiry.
+ */
+
+import type { EntityContext, VaultServiceConfig } from "./types.js";
+
+/** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
+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. */
+const contextCache = new Map<string, EntityContext>();
+
+/**
+ * Look up an entity by slug or UID via vault-service, then vend STS-scoped
+ * credentials for that entity. Returns an EntityContext ready for S3 ops.
+ *
+ * Caches the result and auto-refreshes when the credentials are within
+ * 2 minutes of expiry.
+ */
+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 UID (cmp_*), fetch directly;
+  // otherwise look up by slug
+  const entity = companyUidOrSlug.startsWith("cmp_")
+    ? await fetchEntity(companyUidOrSlug, config)
+    : await fetchEntityBySlug("company", companyUidOrSlug, config);
+
+  if (!entity.bucketName) {
+    throw new Error(
+      `Entity ${entity.uid} (${entity.slug}) has no bucket provisioned. ` +
+      `Run VLT-2 bucket provisioning first.`,
+    );
+  }
+
+  // Step 2: Vend STS-scoped credentials
+  const vendResult = await vendCredentials(entity.uid, config);
+
+  const ctx: EntityContext = {
+    uid: entity.uid,
+    slug: entity.slug,
+    bucketName: entity.bucketName,
+    region: config.region ?? "us-east-1",
+    credentials: {
+      accessKeyId: vendResult.credentials.accessKeyId,
+      secretAccessKey: vendResult.credentials.secretAccessKey,
+      sessionToken: vendResult.credentials.sessionToken,
+    },
+    expiresAt: vendResult.expiresAt,
+  };
+
+  // Cache by both UID and slug for fast lookups
+  contextCache.set(entity.uid, ctx);
+  contextCache.set(entity.slug, ctx);
+
+  return ctx;
+}
+
+/**
+ * Check if credentials are expiring within the refresh threshold.
+ */
+export function isExpiringSoon(expiresAt: string): boolean {
+  const expiryMs = new Date(expiresAt).getTime();
+  const nowMs = Date.now();
+  return expiryMs - nowMs < REFRESH_THRESHOLD_MS;
+}
+
+/**
+ * Force-refresh a cached context. Useful when an S3 operation fails with
+ * an expired credentials error.
+ */
+export async function refreshEntityContext(
+  companyUidOrSlug: string,
+  config: VaultServiceConfig,
+): Promise<EntityContext> {
+  // Evict cache entry to force fresh resolution
+  contextCache.delete(companyUidOrSlug);
+  return resolveEntityContext(companyUidOrSlug, config);
+}
+
+/**
+ * Clear the entire context cache. Useful for tests.
+ */
+export function clearContextCache(): void {
+  contextCache.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Vault-service API calls
+// ---------------------------------------------------------------------------
+
+interface EntityResponse {
+  uid: string;
+  slug: string;
+  bucketName?: string;
+  status: string;
+}
+
+interface VendResponse {
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration: string;
+  };
+  expiresAt: string;
+}
+
+async function fetchEntity(
+  uid: string,
+  config: VaultServiceConfig,
+): Promise<EntityResponse> {
+  const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
+    headers: { Authorization: `Bearer ${config.authToken}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Failed to fetch entity ${uid}: ${res.status} ${body}`);
+  }
+  const data = (await res.json()) as { entity: EntityResponse };
+  return data.entity;
+}
+
+async function fetchEntityBySlug(
+  type: string,
+  slug: string,
+  config: VaultServiceConfig,
+): Promise<EntityResponse> {
+  const res = await fetch(`${config.apiUrl}/entity/by-slug/${type}/${slug}`, {
+    headers: { Authorization: `Bearer ${config.authToken}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(
+      `Failed to find entity by slug ${type}/${slug}: ${res.status} ${body}`,
+    );
+  }
+  const data = (await res.json()) as { entity: EntityResponse };
+  return data.entity;
+}
+
+async function vendCredentials(
+  companyUid: string,
+  config: VaultServiceConfig,
+): Promise<VendResponse> {
+  const res = await fetch(`${config.apiUrl}/sts/vend`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.authToken}`,
+    },
+    body: JSON.stringify({
+      companyUid,
+      durationSeconds: DEFAULT_SESSION_DURATION_SECONDS,
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(
+      `STS vend failed for ${companyUid}: ${res.status} ${body}`,
+    );
+  }
+  return (await res.json()) as VendResponse;
+}

package/src/daemon-worker.ts

@@ -1,9 +1,16 @@
 /**
  * Daemon worker — runs as a detached child process
  * Watches HQ directory and syncs changes to S3
+ *
+ * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
+ * When re-enabled, this worker will need to resolve an EntityContext before
+ * constructing the SyncWatcher. The process argv will need to include company
+ * context (slug or UID) and vault-service config.
  */
 
-import { SyncWatcher } from "./watcher.js";
+// Day 1: SyncWatcher now requires an EntityContext.
+// This file is retained for the automatic-sync milestone but is not functional
+// until the daemon startup path is updated to resolve entity context.
 
 const hqRoot = process.argv[2];
 
@@ -12,21 +19,8 @@ if (!hqRoot) {
   process.exit(1);
 }
 
-const watcher = new SyncWatcher(hqRoot);
-watcher.start();
-
-// Handle graceful shutdown
-process.on("SIGTERM", () => {
-  watcher.stop();
-  process.exit(0);
-});
-
-process.on("SIGINT", () => {
-  watcher.stop();
-  process.exit(0);
-});
-
-// Keep process alive
-setInterval(() => {
-  // Heartbeat — could add remote change polling here
-}, 30_000);
+console.error(
+  "Day 1: daemon-worker is not yet wired to entity context resolution. " +
+  "Use 'hq share' and 'hq sync' for manual sync.",
+);
+process.exit(1);

package/src/daemon.ts

@@ -1,6 +1,8 @@
 /**
  * Background sync daemon management
  * Manages a child process that runs the file watcher
+ *
+ * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
  */
 
 import * as fs from "fs";