@indigoai-us/hq-cloud 5.1.0 → 5.1.9

package/src/cli/sync.ts

@@ -0,0 +1,225 @@
+/**
+ * `hq sync` command — pull everything allowed from entity vault (VLT-5 US-002).
+ *
+ * Pulls all files the caller's STS session policy permits.
+ * Never auto-overwrites local changes — prompts on conflict.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { VaultServiceConfig } from "../types.js";
+import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
+import { downloadFile, listRemoteFiles } from "../s3.js";
+import { readJournal, writeJournal, hashFile, updateEntry, getEntry } from "../journal.js";
+import { createIgnoreFilter } from "../ignore.js";
+import { resolveConflict } from "./conflict.js";
+import type { ConflictStrategy } from "./conflict.js";
+
+/**
+ * Per-file events emitted by `sync()` as it progresses.
+ *
+ * When `SyncOptions.onEvent` is set, these events are delivered to the caller
+ * in place of the default human-readable `console.log` / `console.error`
+ * output. This is the seam that lets `hq-sync-runner` stream ndjson to the
+ * AppBar menubar without the engine knowing anything about ndjson (ADR-0001).
+ *
+ * The human CLI (`hq sync`) leaves `onEvent` undefined and falls through to
+ * `defaultConsoleLogger` below, which preserves the existing tty output.
+ */
+export type SyncProgressEvent =
+  | { type: "progress"; path: string; bytes: number; message?: string }
+  | { type: "error"; path: string; message: string };
+
+export interface SyncOptions {
+  /** Company slug or UID (defaults to active company from config) */
+  company?: string;
+  /** Non-interactive conflict strategy */
+  onConflict?: ConflictStrategy;
+  /** Vault service config */
+  vaultConfig: VaultServiceConfig;
+  /** HQ root directory */
+  hqRoot: string;
+  /**
+   * Per-file event callback. When present, suppresses the default
+   * `console.log`/`console.error` human output — the caller is expected to
+   * render events themselves (e.g. emit ndjson to stdout). When absent, the
+   * default human logger is used. See `SyncProgressEvent`.
+   */
+  onEvent?: (event: SyncProgressEvent) => void;
+}
+
+export interface SyncResult {
+  filesDownloaded: number;
+  bytesDownloaded: number;
+  filesSkipped: number;
+  conflicts: number;
+  aborted: boolean;
+}
+
+/**
+ * Sync (pull) all allowed files from the entity vault.
+ */
+export async function sync(options: SyncOptions): Promise<SyncResult> {
+  const { company, onConflict, vaultConfig, hqRoot } = options;
+  const emit = options.onEvent ?? defaultConsoleLogger;
+
+  // Resolve company
+  const companyRef = company ?? resolveActiveCompany(hqRoot);
+  if (!companyRef) {
+    throw new Error(
+      "No company specified and no active company found. " +
+      "Use --company <slug> or set up .hq/config.json.",
+    );
+  }
+
+  // Resolve entity context
+  let ctx = await resolveEntityContext(companyRef, vaultConfig);
+  const shouldSync = createIgnoreFilter(hqRoot);
+  const journal = readJournal(ctx.slug);
+
+  let filesDownloaded = 0;
+  let bytesDownloaded = 0;
+  let filesSkipped = 0;
+  let conflicts = 0;
+
+  // List all remote files (IAM session policy filters at the AWS layer)
+  const remoteFiles = await listRemoteFiles(ctx);
+
+  for (const remoteFile of remoteFiles) {
+    const localPath = path.join(hqRoot, remoteFile.key);
+
+    // Apply ignore rules
+    if (!shouldSync(localPath)) {
+      filesSkipped++;
+      continue;
+    }
+
+    // Auto-refresh context if credentials expiring
+    if (isExpiringSoon(ctx.expiresAt)) {
+      ctx = await refreshEntityContext(companyRef, vaultConfig);
+    }
+
+    // Check for local conflict
+    const journalEntry = getEntry(journal, remoteFile.key);
+
+    if (fs.existsSync(localPath)) {
+      const localHash = hashFile(localPath);
+
+      // If local file has changed since last sync, it's a conflict
+      if (journalEntry && journalEntry.hash !== localHash) {
+        conflicts++;
+
+        const resolution = await resolveConflict(
+          {
+            path: remoteFile.key,
+            localHash,
+            remoteModified: remoteFile.lastModified,
+            localModified: fs.statSync(localPath).mtime,
+            direction: "pull",
+          },
+          onConflict,
+        );
+
+        if (resolution === "abort") {
+          writeJournal(ctx.slug, journal);
+          return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: true };
+        }
+        if (resolution === "keep" || resolution === "skip") {
+          filesSkipped++;
+          continue;
+        }
+        // "overwrite" falls through to download
+      } else if (journalEntry && journalEntry.hash === localHash) {
+        // Local unchanged since last sync — check if remote changed
+        // by comparing etag/timestamp
+        const lastSyncTime = new Date(journalEntry.syncedAt).getTime();
+        const remoteModTime = remoteFile.lastModified.getTime();
+        if (remoteModTime <= lastSyncTime) {
+          // Remote hasn't changed either — skip
+          filesSkipped++;
+          continue;
+        }
+      }
+    }
+
+    // Download
+    try {
+      await downloadFile(ctx, remoteFile.key, localPath);
+
+      const hash = hashFile(localPath);
+      const stat = fs.statSync(localPath);
+      updateEntry(journal, remoteFile.key, hash, stat.size, "down");
+
+      // Attach message from journal entry if present
+      const remoteJournalMessage = (journalEntry as { message?: string } | undefined)?.message;
+      emit({
+        type: "progress",
+        path: remoteFile.key,
+        bytes: stat.size,
+        ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
+      });
+
+      filesDownloaded++;
+      bytesDownloaded += stat.size;
+    } catch (err) {
+      // STS session policy may deny access to some paths — this is expected
+      // for guest members with allowedPrefixes
+      if (isAccessDenied(err)) {
+        filesSkipped++;
+      } else {
+        emit({
+          type: "error",
+          path: remoteFile.key,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  writeJournal(ctx.slug, journal);
+
+  return { filesDownloaded, bytesDownloaded, filesSkipped, conflicts, aborted: false };
+}
+
+/**
+ * Resolve active company from .hq/config.json.
+ */
+function resolveActiveCompany(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      return config.activeCompany ?? config.companySlug;
+    } catch {
+      // Ignore parse errors
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check if an error is an S3 access denied (expected for filtered guests).
+ */
+function isAccessDenied(err: unknown): boolean {
+  if (err && typeof err === "object" && "name" in err) {
+    return err.name === "AccessDenied" || err.name === "Forbidden";
+  }
+  return false;
+}
+
+/**
+ * Default human-readable event rendering. Preserves the exact output format
+ * that `hq sync` emitted before SyncProgressEvent was introduced, so callers
+ * without an `onEvent` see no behavioral change.
+ */
+function defaultConsoleLogger(event: SyncProgressEvent): void {
+  if (event.type === "progress") {
+    if (event.message) {
+      console.log(`  ✓ ${event.path} — "${event.message}"`);
+    } else {
+      console.log(`  ✓ ${event.path}`);
+    }
+  } else if (event.type === "error") {
+    console.error(`  ✗ ${event.path} — ${event.message}`);
+  }
+}

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);
+  });
+});