@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/s3.ts

@@ -1,5 +1,9 @@
 /**
- * S3 operations — upload, download, list, delete
+ * S3 operations — upload, download, list, delete.
+ *
+ * VLT-5: All operations now accept an EntityContext (entity-aware bucket +
+ * STS-scoped credentials) instead of reading static env config. The caller
+ * is responsible for resolving the context via resolveEntityContext().
  */
 
 import * as fs from "fs";
@@ -10,79 +14,56 @@ import {
   GetObjectCommand,
   ListObjectsV2Command,
   DeleteObjectCommand,
+  HeadObjectCommand,
 } from "@aws-sdk/client-s3";
-import type { Credentials, SyncConfig } from "./types.js";
-import { readCredentials, refreshAwsCredentials } from "./auth.js";
-
-let s3Client: S3Client | null = null;
-
-function getConfig(creds: Credentials): SyncConfig {
-  const prefix = creds.teamId
-    ? `teams/${creds.teamId}/users/${creds.userId}/hq/`
-    : `users/${creds.userId}/hq/`;
-  return {
-    bucket: creds.bucket,
-    region: creds.region,
-    userId: creds.userId,
-    prefix,
-  };
-}
-
-async function getClient(): Promise<{ client: S3Client; config: SyncConfig }> {
-  let creds = readCredentials();
-  if (!creds) {
-    throw new Error("Not authenticated. Run 'hq sync init' first.");
-  }
-
-  // Refresh if expired or missing access key
-  if (!creds.accessKeyId || (creds.expiration && new Date(creds.expiration) < new Date())) {
-    creds = await refreshAwsCredentials(creds);
-  }
-
-  if (!s3Client) {
-    s3Client = new S3Client({
-      region: creds.region,
-      credentials: {
-        accessKeyId: creds.accessKeyId,
-        secretAccessKey: creds.secretAccessKey,
-        sessionToken: creds.sessionToken,
-      },
-    });
-  }
+import type { EntityContext } from "./types.js";
 
-  return { client: s3Client, config: getConfig(creds) };
+/**
+ * Build an S3Client from an EntityContext's STS-scoped credentials.
+ * A new client is created each time to ensure fresh credentials are used
+ * (the caller handles caching/refresh at the EntityContext level).
+ */
+function buildClient(ctx: EntityContext): S3Client {
+  return new S3Client({
+    region: ctx.region,
+    credentials: {
+      accessKeyId: ctx.credentials.accessKeyId,
+      secretAccessKey: ctx.credentials.secretAccessKey,
+      sessionToken: ctx.credentials.sessionToken,
+    },
+  });
 }
 
 export async function uploadFile(
+  ctx: EntityContext,
   localPath: string,
-  relativePath: string
+  key: string,
 ): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+  const client = buildClient(ctx);
   const body = fs.readFileSync(localPath);
 
   await client.send(
     new PutObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
       Body: body,
-      ContentType: getMimeType(relativePath),
-    })
+      ContentType: getMimeType(key),
+    }),
   );
 }
 
 export async function downloadFile(
-  relativePath: string,
-  localPath: string
+  ctx: EntityContext,
+  key: string,
+  localPath: string,
 ): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+  const client = buildClient(ctx);
 
   const response = await client.send(
     new GetObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
-    })
+    }),
   );
 
   if (!response.Body) {
@@ -104,34 +85,33 @@ export async function downloadFile(
 
 export interface RemoteFile {
   key: string;
-  relativePath: string;
   size: number;
   lastModified: Date;
   etag: string;
 }
 
-export async function listRemoteFiles(): Promise<RemoteFile[]> {
-  const { client, config } = await getClient();
+export async function listRemoteFiles(
+  ctx: EntityContext,
+  prefix?: string,
+): Promise<RemoteFile[]> {
+  const client = buildClient(ctx);
   const files: RemoteFile[] = [];
   let continuationToken: string | undefined;
 
   do {
     const response = await client.send(
       new ListObjectsV2Command({
-        Bucket: config.bucket,
-        Prefix: config.prefix,
+        Bucket: ctx.bucketName,
+        Prefix: prefix,
         ContinuationToken: continuationToken,
-      })
+      }),
     );
 
     for (const obj of response.Contents || []) {
       if (!obj.Key || !obj.Size) continue;
-      const relativePath = obj.Key.replace(config.prefix, "");
-      if (!relativePath) continue;
 
       files.push({
         key: obj.Key,
-        relativePath,
         size: obj.Size,
         lastModified: obj.LastModified || new Date(),
         etag: obj.ETag || "",
@@ -144,18 +124,48 @@ export async function listRemoteFiles(): Promise<RemoteFile[]> {
   return files;
 }
 
-export async function deleteRemoteFile(relativePath: string): Promise<void> {
-  const { client, config } = await getClient();
-  const key = `${config.prefix}${relativePath}`;
+export async function deleteRemoteFile(
+  ctx: EntityContext,
+  key: string,
+): Promise<void> {
+  const client = buildClient(ctx);
 
   await client.send(
     new DeleteObjectCommand({
-      Bucket: config.bucket,
+      Bucket: ctx.bucketName,
       Key: key,
-    })
+    }),
   );
 }
 
+/**
+ * Check if a remote key exists and return its metadata.
+ */
+export async function headRemoteFile(
+  ctx: EntityContext,
+  key: string,
+): Promise<{ lastModified: Date; etag: string; size: number } | null> {
+  const client = buildClient(ctx);
+  try {
+    const response = await client.send(
+      new HeadObjectCommand({
+        Bucket: ctx.bucketName,
+        Key: key,
+      }),
+    );
+    return {
+      lastModified: response.LastModified || new Date(),
+      etag: response.ETag || "",
+      size: response.ContentLength || 0,
+    };
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && "name" in err && err.name === "NotFound") {
+      return null;
+    }
+    throw err;
+  }
+}
+
 function getMimeType(filePath: string): string {
   const ext = path.extname(filePath).toLowerCase();
   const mimeTypes: Record<string, string> = {

package/src/types.ts

@@ -57,3 +57,40 @@ export interface DaemonState {
   startedAt: string;
   hqRoot: string;
 }
+
+/**
+ * Entity-aware context for vault-backed S3 operations (VLT-5).
+ * Resolved from vault-service entity registry + STS vending.
+ */
+export interface EntityContext {
+  /** Entity UID (cmp_*) */
+  uid: string;
+  /** Entity slug (human-readable, stable key for per-company local state). */
+  slug: string;
+  /** S3 bucket name for this entity */
+  bucketName: string;
+  /** AWS region */
+  region: string;
+  /** STS-scoped credentials */
+  credentials: VaultCredentials;
+  /** When the credentials expire (ISO 8601) */
+  expiresAt: string;
+}
+
+export interface VaultCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+/**
+ * Configuration for connecting to the vault-service API.
+ */
+export interface VaultServiceConfig {
+  /** Vault API base URL (e.g. https://vault-api.example.com) */
+  apiUrl: string;
+  /** Cognito JWT token for authentication */
+  authToken: string;
+  /** AWS region for S3 client (defaults to entity region or us-east-1) */
+  region?: string;
+}

package/src/vault-client.test.ts

@@ -0,0 +1,390 @@
+/**
+ * VaultClient unit tests (VLT-7 US-001).
+ *
+ * Uses mocked fetch to assert retry behavior, error mapping, and auth header injection.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from "vitest";
+import {
+  VaultClient,
+  VaultAuthError,
+  VaultPermissionDeniedError,
+  VaultNotFoundError,
+  VaultConflictError,
+  VaultClientError,
+} from "./vault-client.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function textResponse(status: number, body: string): Response {
+  return new Response(body, { status });
+}
+
+const TEST_CONFIG = {
+  apiUrl: "https://vault.test.example.com",
+  authToken: "test-jwt-token-123",
+};
+
+let client: VaultClient;
+let fetchSpy: MockInstance<typeof fetch>;
+
+beforeEach(() => {
+  client = new VaultClient(TEST_CONFIG);
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Auth header injection
+// ---------------------------------------------------------------------------
+
+describe("auth header injection", () => {
+  it("sends Bearer token on every request", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { members: [] }),
+    );
+
+    await client.listMembersOfCompany("cmp_abc");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer test-jwt-token-123");
+  });
+
+  it("sets Content-Type on POST requests", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { membership: {}, inviteToken: "tok" }),
+    );
+
+    await client.createInvite({
+      companyUid: "cmp_abc",
+      role: "member",
+      invitedBy: "psn_xyz",
+    });
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    const headers = init.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+describe("error mapping", () => {
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { message: "Token expired" }),
+    );
+
+    await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
+  });
+
+  it("maps 403 to VaultPermissionDeniedError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { message: "Admin required" }),
+    );
+
+    await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultPermissionDeniedError);
+  });
+
+  it("maps 404 to VaultNotFoundError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { message: "Not found" }),
+    );
+
+    await expect(client.entity.get("cmp_missing")).rejects.toThrow(VaultNotFoundError);
+  });
+
+  it("maps 409 to VaultConflictError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { message: "Already accepted" }),
+    );
+
+    await expect(client.acceptInvite("tok", "psn_abc")).rejects.toThrow(VaultConflictError);
+  });
+
+  it("preserves error message from response body", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { message: "Only admins can invite" }),
+    );
+
+    try {
+      await client.createInvite({
+        companyUid: "cmp_abc",
+        role: "member",
+        invitedBy: "psn_xyz",
+      });
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultPermissionDeniedError);
+      expect((err as VaultPermissionDeniedError).message).toBe("Only admins can invite");
+    }
+  });
+
+  it("handles non-JSON error bodies gracefully", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      textResponse(404, "Not Found"),
+    );
+
+    try {
+      await client.entity.findBySlug("company", "test");
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultNotFoundError);
+      expect((err as VaultNotFoundError).message).toBe("Not Found");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Retry behavior
+// ---------------------------------------------------------------------------
+
+describe("retry behavior", () => {
+  it("retries on 429 and succeeds on second attempt", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(429, { message: "Rate limited" }))
+      .mockResolvedValueOnce(jsonResponse(200, { members: [{ personUid: "psn_1" }] }));
+
+    const result = await client.listMembersOfCompany("cmp_abc");
+    expect(result).toHaveLength(1);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries on 500 and succeeds on third attempt", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(500, { message: "Internal error" }))
+      .mockResolvedValueOnce(jsonResponse(502, { message: "Bad gateway" }))
+      .mockResolvedValueOnce(jsonResponse(200, { membership: { role: "admin" } }));
+
+    const result = await client.updateRole({
+      membershipKey: "psn_1#cmp_abc",
+      newRole: "admin",
+      updaterUid: "psn_owner",
+      companyUid: "cmp_abc",
+    });
+    expect(result.role).toBe("admin");
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws after exhausting all retries on persistent 500", async () => {
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(jsonResponse(500, { message: "Down" })),
+    );
+
+    await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultClientError);
+    // 1 initial + 3 retries = 4
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+
+  it("does not retry on 401 (non-transient)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(401, { message: "Expired" }));
+
+    await expect(client.listMembersOfCompany("cmp_abc")).rejects.toThrow(VaultAuthError);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not retry on 403 (non-transient)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(403, { message: "Forbidden" }));
+
+    await expect(client.createInvite({
+      companyUid: "cmp_abc",
+      role: "member",
+      invitedBy: "psn_xyz",
+    })).rejects.toThrow(VaultPermissionDeniedError);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on network errors (fetch throws)", async () => {
+    fetchSpy
+      .mockRejectedValueOnce(new Error("ECONNRESET"))
+      .mockResolvedValueOnce(jsonResponse(200, { members: [] }));
+
+    const result = await client.listMembersOfCompany("cmp_abc");
+    expect(result).toEqual([]);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// API surface
+// ---------------------------------------------------------------------------
+
+describe("API surface", () => {
+  it("createInvite sends correct body and URL", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { membershipKey: "psn_1#cmp_abc", role: "member", status: "pending" },
+        inviteToken: "tok_secure_random",
+      }),
+    );
+
+    const result = await client.createInvite({
+      companyUid: "cmp_abc",
+      role: "member",
+      invitedBy: "psn_owner",
+      inviteeEmail: "alice@example.com",
+    });
+
+    expect(result.inviteToken).toBe("tok_secure_random");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/membership/invite");
+    expect(JSON.parse(init.body as string)).toEqual({
+      companyUid: "cmp_abc",
+      role: "member",
+      invitedBy: "psn_owner",
+      inviteeEmail: "alice@example.com",
+    });
+  });
+
+  it("acceptInvite sends token and personUid", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { status: "active", role: "member" },
+      }),
+    );
+
+    const result = await client.acceptInvite("tok_abc", "psn_invitee");
+    expect(result.membership.status).toBe("active");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/membership/accept");
+    expect(JSON.parse(init.body as string)).toEqual({
+      token: "tok_abc",
+      personUid: "psn_invitee",
+    });
+  });
+
+  it("updateRole sends correct payload", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { role: "guest", allowedPrefixes: ["docs/"] },
+      }),
+    );
+
+    const result = await client.updateRole({
+      membershipKey: "psn_1#cmp_abc",
+      newRole: "guest",
+      allowedPrefixes: ["docs/"],
+      updaterUid: "psn_admin",
+      companyUid: "cmp_abc",
+    });
+
+    expect(result.role).toBe("guest");
+    expect(result.allowedPrefixes).toEqual(["docs/"]);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/membership/role");
+    expect(JSON.parse(init.body as string)).toEqual({
+      membershipKey: "psn_1#cmp_abc",
+      newRole: "guest",
+      allowedPrefixes: ["docs/"],
+      updaterUid: "psn_admin",
+      companyUid: "cmp_abc",
+    });
+  });
+
+  it("entity.get calls correct URL", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" },
+      }),
+    );
+
+    const entity = await client.entity.get("cmp_abc");
+    expect(entity.slug).toBe("acme");
+
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe("https://vault.test.example.com/entity/cmp_abc");
+  });
+
+  it("entity.findBySlug calls correct URL", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entity: { uid: "cmp_abc", slug: "acme", type: "company", status: "active" },
+      }),
+    );
+
+    const entity = await client.entity.findBySlug("company", "acme");
+    expect(entity.uid).toBe("cmp_abc");
+
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe("https://vault.test.example.com/entity/by-slug/company/acme");
+  });
+
+  it("revokeMembership calls POST /membership/revoke with companyUid", async () => {
+    fetchSpy.mockResolvedValueOnce(new Response(null, { status: 204 }));
+
+    await client.revokeMembership("psn_1#cmp_abc", "cmp_abc");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/membership/revoke");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      membershipKey: "psn_1#cmp_abc",
+      companyUid: "cmp_abc",
+    });
+  });
+
+  it("listPendingInvites calls correct URL", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { invites: [{ status: "pending" }] }),
+    );
+
+    const invites = await client.listPendingInvites("cmp_abc");
+    expect(invites).toHaveLength(1);
+
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe("https://vault.test.example.com/membership/company/cmp_abc/pending");
+  });
+
+  it("listMyMemberships hits GET /membership/me and unwraps memberships[]", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "psn_1#cmp_a", role: "owner", status: "active" },
+          { membershipKey: "psn_1#cmp_b", role: "member", status: "active" },
+        ],
+      }),
+    );
+
+    const memberships = await client.listMyMemberships();
+    expect(memberships).toHaveLength(2);
+    expect(memberships[0].membershipKey).toBe("psn_1#cmp_a");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/membership/me");
+    expect(init.method).toBe("GET");
+    // No body on GET.
+    expect(init.body).toBeUndefined();
+  });
+
+  it("listMyMemberships returns [] for callers with no person entity (bootstrap case)", async () => {
+    // Server returns 200 + { memberships: [] } rather than 404 when the
+    // caller is signed in but hasn't been provisioned yet. The SDK must
+    // surface an empty array, NOT throw — hq-sync-runner relies on this
+    // to emit `setup-needed` without catching HTTP errors.
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { memberships: [] }),
+    );
+
+    const memberships = await client.listMyMemberships();
+    expect(memberships).toEqual([]);
+  });
+});