@indigoai-us/hq-cloud 5.1.0 → 5.1.8

package/src/vault-client.ts

@@ -0,0 +1,400 @@
+/**
+ * VaultClient — typed SDK for vault-service membership operations (VLT-7 US-001).
+ *
+ * Wraps vault-service HTTP API with shared auth, retry, and typed errors.
+ * Colocated with hq-cloud so /invite, /promote, /accept and future commands
+ * share one client instead of each rolling its own HTTP layer.
+ */
+
+import type { VaultServiceConfig } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+export class VaultClientError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly body?: string,
+  ) {
+    super(message);
+    this.name = "VaultClientError";
+  }
+}
+
+export class VaultAuthError extends VaultClientError {
+  constructor(message = "Authentication failed — session expired or invalid") {
+    super(message, 401);
+    this.name = "VaultAuthError";
+  }
+}
+
+export class VaultPermissionDeniedError extends VaultClientError {
+  constructor(message = "Permission denied — admin role required") {
+    super(message, 403);
+    this.name = "VaultPermissionDeniedError";
+  }
+}
+
+export class VaultNotFoundError extends VaultClientError {
+  constructor(message = "Resource not found") {
+    super(message, 404);
+    this.name = "VaultNotFoundError";
+  }
+}
+
+export class VaultConflictError extends VaultClientError {
+  constructor(message = "Conflict — resource already exists or was already accepted") {
+    super(message, 409);
+    this.name = "VaultConflictError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type MembershipRole = "owner" | "admin" | "member" | "guest";
+export type MembershipStatus = "pending" | "active" | "revoked";
+
+export interface Membership {
+  membershipKey: string;
+  personUid: string;
+  companyUid: string;
+  role: MembershipRole;
+  status: MembershipStatus;
+  allowedPrefixes?: string[];
+  inviteToken?: string;
+  invitedBy: string;
+  invitedAt: string;
+  acceptedAt?: string;
+  revokedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateInviteInput {
+  personUid?: string;
+  inviteeEmail?: string;
+  companyUid: string;
+  role: MembershipRole;
+  allowedPrefixes?: string[];
+  invitedBy: string;
+}
+
+export interface CreateInviteResult {
+  membership: Membership;
+  inviteToken: string;
+}
+
+export interface AcceptInviteResult {
+  membership: Membership;
+}
+
+export interface UpdateRoleInput {
+  membershipKey: string;
+  newRole: MembershipRole;
+  allowedPrefixes?: string[];
+  updaterUid: string;
+  /** Required so the server can authorize the caller as admin/owner of the company. */
+  companyUid: string;
+}
+
+export interface EntityInfo {
+  uid: string;
+  slug: string;
+  type: string;
+  bucketName?: string;
+  status: string;
+}
+
+export interface CreateEntityInput {
+  type: "person" | "company";
+  slug: string;
+  name: string;
+  email?: string;
+  ownerUid?: string;
+}
+
+export interface CreateEntityResult {
+  entity: EntityInfo;
+}
+
+// -- STS child vending (VLT-8) --------------------------------------------
+
+export type TaskAction = "read" | "write";
+
+export interface TaskScope {
+  /** S3 key prefixes the child may access (e.g. ["drafts/"]). */
+  allowedPrefixes: string[];
+  /** Defaults to ["read", "write"]. Use ["read"] for read-only children. */
+  allowedActions?: TaskAction[];
+}
+
+export interface VendChildInput {
+  companyUid: string;
+  /** ULID generated by the parent task. Flows into STS session name for audit. */
+  taskId: string;
+  /** Short human-readable description (<256 chars). Logged alongside the session. */
+  taskDescription: string;
+  taskScope: TaskScope;
+  /**
+   * Child session duration in seconds. Defaults to 900 on the server — AWS STS
+   * AssumeRole enforces a 900s floor. The task-scoped policy is the security
+   * boundary, not the duration.
+   */
+  durationSeconds?: number;
+}
+
+export interface StsChildCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+export interface VendChildResult {
+  credentials: StsChildCredentials;
+  /** STS session name: `${parentPersonUid}--task--${taskId}` — used in CloudTrail.
+   *  (Dash-separated because AWS STS `roleSessionName` disallows colons.) */
+  sessionName: string;
+  /** ISO-8601 session expiration. */
+  expiresAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Retry config
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+
+function isTransient(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ---------------------------------------------------------------------------
+// VaultClient
+// ---------------------------------------------------------------------------
+
+export class VaultClient {
+  private readonly apiUrl: string;
+  private readonly authToken: string;
+
+  constructor(config: VaultServiceConfig) {
+    this.apiUrl = config.apiUrl.replace(/\/+$/, "");
+    this.authToken = config.authToken;
+  }
+
+  // -- Membership operations ------------------------------------------------
+
+  async createInvite(input: CreateInviteInput): Promise<CreateInviteResult> {
+    const data = await this.post<{ membership: Membership; inviteToken: string }>(
+      "/membership/invite",
+      input,
+    );
+    return data;
+  }
+
+  async acceptInvite(token: string, personUid: string): Promise<AcceptInviteResult> {
+    const data = await this.post<{ membership: Membership }>(
+      "/membership/accept",
+      { token, personUid },
+    );
+    return data;
+  }
+
+  /**
+   * Revoke a membership. The handler needs both the membershipKey AND the
+   * companyUid so it can authorize the caller as admin/owner of the company
+   * before performing the revoke. (We can't infer companyUid from the key
+   * alone without an extra DDB read, and the caller already knows it.)
+   */
+  async revokeMembership(membershipKey: string, companyUid: string): Promise<void> {
+    await this.post("/membership/revoke", { membershipKey, companyUid });
+  }
+
+  /**
+   * List the caller's own active memberships.
+   *
+   * Server infers the caller's identity from the Cognito JWT `sub` claim and
+   * returns the union of active memberships across every person entity owned
+   * by that sub (orphan-tolerant — prior failed provisioning runs can leave
+   * multiple `prs_*` rows for the same Cognito identity).
+   *
+   * Returns `[]` — NOT a 404 — when the caller has no person entity yet.
+   * This lets `hq-sync-runner` distinguish "signed in but not bootstrapped"
+   * (empty array → emit `setup-needed`) from "auth broken" (throws
+   * VaultAuthError) without catching HTTP errors for flow control.
+   *
+   * Backed by `GET /membership/me` (see hq-pro ADR-0002).
+   */
+  async listMyMemberships(): Promise<Membership[]> {
+    const data = await this.get<{ memberships: Membership[] }>("/membership/me");
+    return data.memberships;
+  }
+
+  async listMembersOfCompany(companyUid: string): Promise<Membership[]> {
+    const data = await this.get<{ members: Membership[] }>(
+      `/membership/company/${encodeURIComponent(companyUid)}`,
+    );
+    return data.members;
+  }
+
+  async updateRole(input: UpdateRoleInput): Promise<Membership> {
+    const data = await this.post<{ membership: Membership }>(
+      "/membership/role",
+      input,
+    );
+    return data.membership;
+  }
+
+  async listPendingInvites(companyUid: string): Promise<Membership[]> {
+    const data = await this.get<{ invites: Membership[] }>(
+      `/membership/company/${encodeURIComponent(companyUid)}/pending`,
+    );
+    return data.invites;
+  }
+
+  // -- Entity operations ----------------------------------------------------
+
+  readonly entity = {
+    get: async (uid: string): Promise<EntityInfo> => {
+      const data = await this.get<{ entity: EntityInfo }>(`/entity/${encodeURIComponent(uid)}`);
+      return data.entity;
+    },
+
+    findBySlug: async (type: string, slug: string): Promise<EntityInfo> => {
+      const data = await this.get<{ entity: EntityInfo }>(
+        `/entity/by-slug/${encodeURIComponent(type)}/${encodeURIComponent(slug)}`,
+      );
+      return data.entity;
+    },
+
+    create: async (input: CreateEntityInput): Promise<EntityInfo> => {
+      const data = await this.post<CreateEntityResult>("/entity", input);
+      return data.entity;
+    },
+  };
+
+  // -- Provisioning operations (VLT-2) -----------------------------------------
+
+  async provisionBucket(companyUid: string): Promise<{ bucketName: string; kmsKeyId: string }> {
+    const data = await this.post<{ bucketName: string; kmsKeyId: string }>(
+      "/provision/bucket",
+      { companyUid },
+    );
+    return data;
+  }
+
+  // -- STS operations (VLT-8) -----------------------------------------------
+
+  readonly sts = {
+    /**
+     * Vend task-scoped child credentials strictly narrower than the caller's
+     * own membership. Backed by the vault-service `POST /sts/vend-child`
+     * route (kebab-case to match the rest of the vault-service API).
+     *
+     * The child policy is intersected with the caller's membership on the
+     * server — if `taskScope.allowedPrefixes` requests anything the parent
+     * can't see, the server throws ScopeExceedsParentError before calling STS.
+     *
+     * Session name format: `${parentPersonUid}--task--${taskId}` — this lands
+     * in CloudTrail verbatim, so every child S3 action can be traced back to
+     * the parent task for incident response.
+     */
+    vendChild: async (input: VendChildInput): Promise<VendChildResult> => {
+      const data = await this.post<VendChildResult>("/sts/vend-child", input);
+      return data;
+    },
+  };
+
+  // -- HTTP primitives with retry -------------------------------------------
+
+  private async get<T>(path: string): Promise<T> {
+    return this.request<T>("GET", path);
+  }
+
+  private async post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>("POST", path, body);
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      if (attempt > 0) {
+        const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+        await sleep(delay);
+      }
+
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${this.authToken}`,
+        Accept: "application/json",
+      };
+
+      const init: RequestInit = { method, headers };
+
+      if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(body);
+      }
+
+      let res: Response;
+      try {
+        res = await fetch(`${this.apiUrl}${path}`, init);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < MAX_RETRIES) continue;
+        throw lastError;
+      }
+
+      if (res.ok) {
+        if (res.status === 204) return undefined as T;
+        return (await res.json()) as T;
+      }
+
+      const responseBody = await res.text();
+
+      // Non-retryable errors → throw immediately
+      if (!isTransient(res.status)) {
+        throw this.mapError(res.status, responseBody);
+      }
+
+      // Retryable — store and loop
+      lastError = this.mapError(res.status, responseBody);
+    }
+
+    throw lastError ?? new VaultClientError("Request failed after retries", 500);
+  }
+
+  private mapError(status: number, body: string): VaultClientError {
+    const message = this.extractMessage(body);
+
+    switch (status) {
+      case 401:
+        return new VaultAuthError(message);
+      case 403:
+        return new VaultPermissionDeniedError(message);
+      case 404:
+        return new VaultNotFoundError(message);
+      case 409:
+        return new VaultConflictError(message);
+      default:
+        return new VaultClientError(message || `Request failed with status ${status}`, status, body);
+    }
+  }
+
+  private extractMessage(body: string): string {
+    try {
+      const parsed = JSON.parse(body) as { message?: string; error?: string };
+      return parsed.message ?? parsed.error ?? body;
+    } catch {
+      return body;
+    }
+  }
+}

package/src/watcher.ts

@@ -1,12 +1,17 @@
 /**
  * File watcher — monitors HQ directory for changes
  * Uses chokidar with debounced batching
+ *
+ * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
+ * When re-enabled, the constructor will need an EntityContext (or a context resolver)
+ * to be passed in for entity-aware S3 operations.
  */
 
 import * as fs from "fs";
 import * as path from "path";
 import { watch } from "chokidar";
 import type { FSWatcher } from "chokidar";
+import type { EntityContext } from "./types.js";
 import { createIgnoreFilter, isWithinSizeLimit } from "./ignore.js";
 import { readJournal, writeJournal, hashFile, updateEntry } from "./journal.js";
 import { uploadFile, deleteRemoteFile } from "./s3.js";
@@ -22,13 +27,15 @@ interface PendingChange {
 export class SyncWatcher {
   private watcher: FSWatcher | null = null;
   private hqRoot: string;
+  private ctx: EntityContext;
   private shouldSync: (filePath: string) => boolean;
   private pendingChanges = new Map<string, PendingChange>();
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
   private processing = false;
 
-  constructor(hqRoot: string) {
+  constructor(hqRoot: string, ctx: EntityContext) {
     this.hqRoot = hqRoot;
+    this.ctx = ctx;
     this.shouldSync = createIgnoreFilter(hqRoot);
   }
 
@@ -91,12 +98,12 @@ export class SyncWatcher {
     const batch = new Map(this.pendingChanges);
     this.pendingChanges.clear();
 
-    const journal = readJournal(this.hqRoot);
+    const journal = readJournal(this.ctx.slug);
 
     for (const [relativePath, change] of batch) {
       try {
         if (change.type === "unlink") {
-          await deleteRemoteFile(relativePath);
+          await deleteRemoteFile(this.ctx, relativePath);
           delete journal.files[relativePath];
         } else {
           const hash = hashFile(change.absolutePath);
@@ -106,7 +113,7 @@ export class SyncWatcher {
           const existing = journal.files[relativePath];
           if (existing && existing.hash === hash) continue;
 
-          await uploadFile(change.absolutePath, relativePath);
+          await uploadFile(this.ctx, change.absolutePath, relativePath);
           updateEntry(journal, relativePath, hash, stat.size, "up");
         }
       } catch (err) {
@@ -119,7 +126,7 @@ export class SyncWatcher {
       }
     }
 
-    writeJournal(this.hqRoot, journal);
+    writeJournal(this.ctx.slug, journal);
     this.processing = false;
 
     // Process any changes that came in while we were flushing

package/test/invite-flow.integration.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Invite → Accept → Promote integration test (VLT-7 US-003).
+ *
+ * Mocks the vault-service HTTP API to test the full lifecycle round-trip:
+ * admin creates invite → invitee accepts → admin promotes to guest with paths.
+ *
+ * Uses mocked fetch (not a real vault-service) to keep the test self-contained
+ * and runnable offline. Real E2E tests against dev stage are in the e2eTests
+ * section of the PRD.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { invite } from "../src/cli/invite.js";
+import { accept, parseToken } from "../src/cli/accept.js";
+import { promote } from "../src/cli/promote.js";
+import type { VaultServiceConfig } from "../src/types.js";
+import type { Membership } from "../src/vault-client.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const VAULT_CONFIG: VaultServiceConfig = {
+  apiUrl: "https://vault.test.example.com",
+  authToken: "admin-jwt",
+};
+
+const INVITEE_CONFIG: VaultServiceConfig = {
+  apiUrl: "https://vault.test.example.com",
+  authToken: "invitee-jwt",
+};
+
+let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Token parsing
+// ---------------------------------------------------------------------------
+
+describe("parseToken", () => {
+  it("extracts token from hq:// magic link", () => {
+    expect(parseToken("hq://accept/tok_abc123")).toBe("tok_abc123");
+  });
+
+  it("extracts token from https:// URL", () => {
+    expect(parseToken("https://hq.indigoai.com/accept/tok_xyz")).toBe("tok_xyz");
+  });
+
+  it("returns raw token unchanged", () => {
+    expect(parseToken("tok_raw_token")).toBe("tok_raw_token");
+  });
+
+  it("trims whitespace", () => {
+    expect(parseToken("  hq://accept/tok_abc  ")).toBe("tok_abc");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full round-trip
+// ---------------------------------------------------------------------------
+
+describe("invite → accept → promote lifecycle", () => {
+  const pendingMembership: Membership = {
+    membershipKey: "psn_invitee#cmp_acme",
+    personUid: "psn_invitee",
+    companyUid: "cmp_acme",
+    role: "member",
+    status: "pending",
+    inviteToken: "tok_secure_random_32bytes",
+    invitedBy: "psn_admin",
+    invitedAt: "2026-04-15T00:00:00Z",
+    createdAt: "2026-04-15T00:00:00Z",
+    updatedAt: "2026-04-15T00:00:00Z",
+  };
+
+  const activeMembership: Membership = {
+    ...pendingMembership,
+    status: "active",
+    inviteToken: undefined,
+    acceptedAt: "2026-04-15T00:01:00Z",
+    updatedAt: "2026-04-15T00:01:00Z",
+  };
+
+  it("admin invites → invitee accepts → admin promotes to guest with paths", async () => {
+    // --- Step 1: Admin creates invite ---
+    fetchSpy
+      // entity.findBySlug("company", "acme")
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_acme", slug: "acme", type: "company", status: "active" } }),
+      )
+      // createInvite
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          membership: pendingMembership,
+          inviteToken: "tok_secure_random_32bytes",
+        }),
+      );
+
+    const inviteResult = await invite({
+      target: "alice@example.com",
+      role: "member",
+      company: "acme",
+      vaultConfig: VAULT_CONFIG,
+      callerUid: "psn_admin",
+    });
+
+    expect(inviteResult.magicLink).toBe("hq://accept/tok_secure_random_32bytes");
+    expect(inviteResult.membership.status).toBe("pending");
+
+    // --- Step 2: Invitee accepts ---
+    fetchSpy
+      // acceptInvite
+      .mockResolvedValueOnce(
+        jsonResponse(200, { membership: activeMembership }),
+      )
+      // entity.get for company slug resolution
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_acme", slug: "acme", type: "company", status: "active" } }),
+      );
+
+    const acceptResult = await accept({
+      tokenOrLink: inviteResult.magicLink,
+      callerUid: "psn_invitee",
+      vaultConfig: INVITEE_CONFIG,
+    });
+
+    expect(acceptResult.membership.status).toBe("active");
+    expect(acceptResult.membership.role).toBe("member");
+    expect(acceptResult.companySlug).toBe("acme");
+
+    // --- Step 3: Admin promotes member → guest with paths ---
+    fetchSpy
+      // entity.findBySlug for company resolution
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_acme", slug: "acme", type: "company", status: "active" } }),
+      )
+      // updateRole
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          membership: {
+            ...activeMembership,
+            role: "guest",
+            allowedPrefixes: ["docs/"],
+            updatedAt: "2026-04-15T00:02:00Z",
+          },
+        }),
+      );
+
+    const promoteResult = await promote({
+      target: "psn_invitee",
+      newRole: "guest",
+      paths: "docs/",
+      company: "acme",
+      callerUid: "psn_admin",
+      vaultConfig: VAULT_CONFIG,
+    });
+
+    expect(promoteResult.membership.role).toBe("guest");
+    expect(promoteResult.membership.allowedPrefixes).toEqual(["docs/"]);
+  });
+
+  it("double-accept returns conflict error", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { message: "Already accepted" }),
+    );
+
+    await expect(
+      accept({
+        tokenOrLink: "tok_already_accepted",
+        callerUid: "psn_invitee",
+        vaultConfig: INVITEE_CONFIG,
+      }),
+    ).rejects.toThrow("This invite was already accepted");
+  });
+
+  it("demoting last owner returns conflict error", async () => {
+    fetchSpy
+      // entity.findBySlug
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_acme", slug: "acme", type: "company", status: "active" } }),
+      )
+      // updateRole — 409 because last owner
+      .mockResolvedValueOnce(
+        jsonResponse(409, { message: "Cannot remove last owner" }),
+      );
+
+    await expect(
+      promote({
+        target: "psn_owner",
+        newRole: "member",
+        company: "acme",
+        callerUid: "psn_owner",
+        vaultConfig: VAULT_CONFIG,
+      }),
+    ).rejects.toThrow("Cannot leave company without an owner");
+  });
+
+  it("non-admin invite returns permission error", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { entity: { uid: "cmp_acme", slug: "acme", type: "company", status: "active" } }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(403, { message: "Forbidden" }),
+      );
+
+    await expect(
+      invite({
+        target: "bob@example.com",
+        company: "acme",
+        vaultConfig: VAULT_CONFIG,
+        callerUid: "psn_member",
+      }),
+    ).rejects.toThrow("Permission denied — only admins and owners can invite members");
+  });
+
+  it("accept with wrong person returns permission error", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { message: "Identity mismatch" }),
+    );
+
+    await expect(
+      accept({
+        tokenOrLink: "tok_for_someone_else",
+        callerUid: "psn_wrong",
+        vaultConfig: INVITEE_CONFIG,
+      }),
+    ).rejects.toThrow("This invite was for a different person");
+  });
+});