@indigoai-us/hq-cloud 5.21.0 → 5.23.0

package/src/vault-client.ts

@@ -151,6 +151,137 @@ export interface CreateEntityResult {
   entity: EntityInfo;
 }
 
+// -- Browse-vs-sync types (US-002, US-003, US-004) -----------------------
+
+/**
+ * Source kind for an explicit per-company file-ACL grant. Mirrors the
+ * server enum in hq-pro `vault-service/handlers/files-grants.ts`.
+ *
+ * `'open'` collapses two server-side shapes that are indistinguishable to
+ * the caller — the legacy `acl.open === true` floor and an explicit
+ * `granteeType: 'company-wide'` row. Both mean "every active member of
+ * this company sees this prefix".
+ */
+export type GrantSource = "person" | "email" | "group" | "open";
+
+/** Permission level surfaced on a grant row. Matches `AclPermission`. */
+export type GrantPermission = "read" | "write" | "admin";
+
+/**
+ * One row in the response of `GET /v1/files/grants?company={uid}`.
+ *
+ * Role-bypass (owner/admin) entries are intentionally excluded by the
+ * server — this is the caller's EXPLICIT grant graph, not the full set
+ * of prefixes they can touch by virtue of role.
+ */
+export interface ExplicitGrant {
+  companyUid: string;
+  path: string;
+  permission: GrantPermission;
+  source: GrantSource;
+}
+
+/**
+ * Effective sync mode for a single membership. Mirrors the server's
+ * resolved view from `GET /v1/memberships/{id}/sync-config`:
+ *
+ *   - `shared` — sync only `shared/` and the caller's `personal/` prefix
+ *   - `all`    — sync every prefix the caller has read access to
+ *   - `custom` — sync the explicit `customPaths` list (server validates)
+ *
+ * `isDefault: true` means no row exists in DDB and the server is
+ * falling back to its built-in default (currently `'all'` for legacy
+ * memberships created pre-US-003). When `true`, `updatedAt`/`updatedBy`
+ * are absent because there's no row to attribute.
+ */
+export type SyncMode = "shared" | "all" | "custom";
+
+export interface MembershipSyncConfig {
+  membershipId: string;
+  syncMode: SyncMode;
+  customPaths?: string[];
+  /**
+   * `true` when the server returned the built-in default because no
+   * sync-config row exists for this membership. PUT always returns
+   * `false` — writing the row is what makes it non-default.
+   */
+  isDefault: boolean;
+  /** Present only when a sync-config row exists (i.e. `isDefault: false`). */
+  updatedAt?: string;
+  /** Present only when a sync-config row exists. PersonUid of the writer. */
+  updatedBy?: string;
+}
+
+/**
+ * Input shape for {@link VaultClient.setMembershipSyncConfig}. The server
+ * validates the combination — `customPaths` is required when `syncMode`
+ * is `'custom'` and rejected otherwise.
+ */
+export interface SetMembershipSyncConfigInput {
+  syncMode: SyncMode;
+  customPaths?: string[];
+}
+
+// -- Raw vend (legacy POST /vend, purpose-aware after US-009) -------------
+
+/**
+ * Why the caller is requesting STS-scoped credentials. Mirrors the
+ * hq-pro vault-service enum (`src/vault-service/policy-builder.ts`).
+ *
+ *   - `'sync'`   — background machine sync. Role-bypass MUST NOT widen
+ *     the path set: credentials are scoped to exactly the requested
+ *     paths (which the sync engine has already narrowed via US-005).
+ *   - `'browse'` — interactive exploration (hq-console Explore,
+ *     `hq files browse`, admin spelunking). Admin/owner role-bypass
+ *     APPLIES — the caller may receive credentials covering paths
+ *     beyond their explicit ACL grants.
+ *
+ * The server defaults missing/empty to `'sync'` (the safer choice).
+ * The client doesn't mirror that default — every caller should be
+ * explicit about its intent so audit rows are accurate.
+ */
+export type VendPurpose = "sync" | "browse";
+
+export type VaultOperation = "read-only" | "read-write" | "staged-write";
+
+/**
+ * Input shape for {@link VaultClient.vend}. The server validates
+ * combinations — e.g. `purpose: 'sync'` rejects bucket-wide `'*'` paths
+ * as defense in depth against role-bypass widening on the sync path.
+ */
+export interface VendInput {
+  paths: string[];
+  operations: VaultOperation;
+  /** Why these credentials are being vended. See {@link VendPurpose}. */
+  purpose: VendPurpose;
+  /** STS session lifetime in seconds. Server default is 900 (15m). */
+  duration?: number;
+}
+
+export interface VendCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+  /** ISO-8601 STS-native expiration string. */
+  expiration: string;
+}
+
+export interface VendResult {
+  credentials: VendCredentials;
+  /** Echo of the server-resolved paths after ACL intersection. */
+  paths: string[];
+  operations: VaultOperation;
+  /** Echo of the effective purpose (server-defaulted to 'sync' if absent). */
+  purpose: VendPurpose;
+  /**
+   * Size of the rendered IAM session policy in characters. Lets the
+   * caller detect when it's nearing the 2048-char IAM ceiling so it can
+   * fan out across multiple vends or shrink its path set.
+   */
+  policySize: number;
+  requestId?: string;
+}
+
 // -- STS child vending (VLT-8) --------------------------------------------
 
 export type TaskAction = "read" | "write";
@@ -356,6 +487,71 @@ export class VaultClient {
     return data.invites;
   }
 
+  // -- Browse-vs-sync (US-002, US-003, US-004) -----------------------------
+
+  /**
+   * List the caller's EXPLICIT per-company file-ACL grants. Backed by
+   * `GET /v1/files/grants?company={companyUid}` (hq-pro US-002).
+   *
+   * Role-bypass (owner/admin) entries are excluded server-side — the
+   * response is the caller's actual grant graph, not the full set of
+   * prefixes they can touch by virtue of role. Used by the
+   * browse-vs-sync UI to render an honest grant graph and by the
+   * sync engine to narrow what it pulls.
+   *
+   * Returns `[]` (NOT a 404) when the caller has no explicit grants in
+   * this company, so call sites can treat "empty graph" as a normal
+   * state without catching errors.
+   */
+  async listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]> {
+    const data = await this.get<{ grants: ExplicitGrant[]; computedAt: string }>(
+      `/v1/files/grants?company=${encodeURIComponent(companyUid)}`,
+    );
+    return data.grants ?? [];
+  }
+
+  /**
+   * Read the effective sync-mode for a single membership. Backed by
+   * `GET /v1/memberships/{id}/sync-config` (hq-pro US-003).
+   *
+   * The server resolves the effective view — when no row exists for the
+   * membership it returns the built-in default with `isDefault: true`
+   * and omits `updatedAt`/`updatedBy`. Callers should treat `isDefault:
+   * true` as "no explicit config yet" rather than special-casing 404.
+   *
+   * Authorization: caller must own the membership OR hold admin/owner
+   * on the company that the membership belongs to. The server 404s
+   * tombstoned/revoked memberships.
+   */
+  async getMembershipSyncConfig(
+    membershipId: string,
+  ): Promise<MembershipSyncConfig> {
+    return this.get<MembershipSyncConfig>(
+      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+    );
+  }
+
+  /**
+   * Write the sync-mode for a single membership. Backed by
+   * `PUT /v1/memberships/{id}/sync-config` (hq-pro US-003).
+   *
+   * Server validates: `customPaths` is required when `syncMode` is
+   * `'custom'` and rejected otherwise. The returned row reflects the
+   * persisted state with `isDefault: false` (writing the row is what
+   * makes it non-default) and the server-assigned `updatedAt` +
+   * `updatedBy`.
+   */
+  async setMembershipSyncConfig(
+    membershipId: string,
+    partial: SetMembershipSyncConfigInput,
+  ): Promise<MembershipSyncConfig> {
+    return this.request<MembershipSyncConfig>(
+      "PUT",
+      `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+      partial,
+    );
+  }
+
   // -- Entity operations ----------------------------------------------------
 
   readonly entity = {
@@ -467,6 +663,33 @@ export class VaultClient {
     return data;
   }
 
+  // -- Raw vend (POST /vend) ------------------------------------------------
+
+  /**
+   * POST `/vend` — vend STS-scoped credentials for an explicit path list.
+   *
+   * This is the legacy raw-vend endpoint (distinct from `/sts/vend`,
+   * `/sts/vend-self`, and `/sts/vend-child`). Per US-009 it accepts a
+   * `purpose` discriminator that controls whether admin/owner
+   * role-bypass widens the resulting session policy beyond the
+   * caller's explicit ACL grants:
+   *
+   *   - `purpose: 'browse'` — role-bypass APPLIES (interactive
+   *     `hq files browse`, admin spelunking).
+   *   - `purpose: 'sync'`   — role-bypass SUPPRESSED (background sync;
+   *     credentials are scoped to exactly what the caller has explicitly
+   *     been granted, regardless of role).
+   *
+   * The server defaults missing/empty to `'sync'` but every first-party
+   * caller should be explicit so audit attribution is correct.
+   *
+   * Used by `hq files browse`/`hq files cat` (US-008) to peek at vault
+   * objects without ever materialising them under `companies/{co}/`.
+   */
+  async vend(input: VendInput): Promise<VendResult> {
+    return this.post<VendResult>("/vend", input);
+  }
+
   // -- STS operations (VLT-8) -----------------------------------------------
 
   readonly sts = {