@indigoai-us/hq-cloud 6.11.12 → 6.11.13

package/src/vault-client.ts

@@ -8,6 +8,7 @@
 
 import type { ClientInfo, VaultServiceConfig } from "./types.js";
 import { buildClientHeaders } from "./client-info.js";
+import { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -444,6 +445,306 @@ async function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// ---------------------------------------------------------------------------
+// Response schemas
+// ---------------------------------------------------------------------------
+
+type VaultResponseSchema<T> = z.ZodType<T>;
+
+const membershipRoleSchema = z.enum(["owner", "admin", "member", "guest"]);
+const membershipStatusSchema = z.enum(["pending", "active", "revoked"]);
+const grantPermissionSchema = z.enum(["read", "write", "admin"]);
+const grantSourceSchema = z.enum(["person", "email", "group", "open"]);
+const presignOpSchema = z.enum(["get", "put", "delete"]);
+const syncModeSchema = z.enum(["shared", "all", "custom"]);
+const vendPurposeSchema = z.enum(["sync", "browse"]);
+const vaultOperationSchema = z.enum(["read-only", "read-write", "staged-write"]);
+
+// Membership/entity rows are intentionally permissive on field optionality:
+// current command tests and server flows use short rows outside sync decisions.
+const membershipSchema = z
+  .object({
+    membershipKey: z.string().optional(),
+    personUid: z.string().optional(),
+    companyUid: z.string().optional(),
+    role: membershipRoleSchema.optional(),
+    status: membershipStatusSchema.optional(),
+    allowedPrefixes: z.array(z.string()).optional(),
+    inviteToken: z.string().optional(),
+    invitedBy: z.string().optional(),
+    invitedAt: z.string().optional(),
+    acceptedAt: z.string().optional(),
+    revokedAt: z.string().optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+  })
+  .strip() as unknown as VaultResponseSchema<Membership>;
+
+const entityInfoSchema = z
+  .object({
+    uid: z.string(),
+    slug: z.string(),
+    type: z.string(),
+    name: z.string().optional(),
+    bucketName: z.string().optional(),
+    status: z.string(),
+    createdAt: z.string().optional(),
+  })
+  .strip() as unknown as VaultResponseSchema<EntityInfo>;
+
+const pendingInviteByEmailSchema: VaultResponseSchema<PendingInviteByEmail> = z
+  .object({
+    membershipKey: z.string(),
+    companyUid: z.string(),
+    role: membershipRoleSchema,
+    inviteToken: z.string().optional(),
+    invitedBy: z.string(),
+    invitedAt: z.string(),
+  })
+  .strip();
+
+const explicitGrantSchema: VaultResponseSchema<ExplicitGrant> = z
+  .object({
+    companyUid: z.string(),
+    path: z.string(),
+    permission: grantPermissionSchema,
+    source: grantSourceSchema,
+  })
+  .strip();
+
+const vaultListedObjectSchema: VaultResponseSchema<VaultListedObject> = z
+  .object({
+    key: z.string(),
+    size: z.number(),
+    lastModified: z.string().nullable(),
+    etag: z.string().nullable(),
+    permission: grantPermissionSchema,
+  })
+  .strip();
+
+const presignResultRowSchema: VaultResponseSchema<PresignResultRow> = z
+  .object({
+    key: z.string(),
+    op: presignOpSchema,
+    url: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    expiresIn: z.number().optional(),
+    expiresAt: z.string().optional(),
+    error: z.string().optional(),
+    code: z.string().optional(),
+  })
+  .strip();
+
+const membershipSyncConfigSchema: VaultResponseSchema<MembershipSyncConfig> = z
+  .object({
+    membershipId: z.string(),
+    syncMode: syncModeSchema,
+    customPaths: z.array(z.string()).optional(),
+    isDefault: z.boolean(),
+    updatedAt: z.string().optional(),
+    updatedBy: z.string().optional(),
+  })
+  .strip();
+
+const vendCredentialsSchema: VaultResponseSchema<VendCredentials> = z
+  .object({
+    accessKeyId: z.string(),
+    secretAccessKey: z.string(),
+    sessionToken: z.string(),
+    expiration: z.string(),
+  })
+  .strip();
+
+const stsCredentialsSchema: VaultResponseSchema<StsChildCredentials> = z
+  .object({
+    accessKeyId: z.string(),
+    secretAccessKey: z.string(),
+    sessionToken: z.string(),
+  })
+  .strip();
+
+const telemetryOptInResponseSchema: VaultResponseSchema<TelemetryOptInResponse> =
+  z
+    .object({
+      enabled: z.boolean().default(false),
+      updatedAt: z.string().nullable().default(null),
+    })
+    .strip();
+
+const usageIngestResultSchema: VaultResponseSchema<UsageIngestResult> = z
+  .object({
+    ok: z.boolean(),
+    written: z.number(),
+    skipped: z.array(
+      z
+        .object({
+          index: z.number(),
+          code: z.string(),
+          error: z.string(),
+        })
+        .strip(),
+    ),
+  })
+  .strip();
+
+const createInviteResponseSchema: VaultResponseSchema<CreateInviteResult> = z
+  .object({
+    membership: membershipSchema,
+    inviteToken: z.string(),
+  })
+  .strip();
+
+const acceptInviteResponseSchema: VaultResponseSchema<AcceptInviteResult> = z
+  .object({
+    membership: membershipSchema,
+  })
+  .strip();
+
+const membershipsResponseSchema: VaultResponseSchema<{ memberships: Membership[] }> =
+  z
+    .object({
+      memberships: z.array(membershipSchema),
+    })
+    .strip();
+
+const pendingInvitesByEmailResponseSchema: VaultResponseSchema<{
+  invites?: PendingInviteByEmail[];
+}> = z
+  .object({
+    invites: z.array(pendingInviteByEmailSchema).optional(),
+  })
+  .strip();
+
+const membersResponseSchema: VaultResponseSchema<{ members: Membership[] }> = z
+  .object({
+    members: z.array(membershipSchema),
+  })
+  .strip();
+
+const membershipResponseSchema: VaultResponseSchema<{ membership: Membership }> =
+  z
+    .object({
+      membership: membershipSchema,
+    })
+    .strip();
+
+const invitesResponseSchema: VaultResponseSchema<{ invites: Membership[] }> = z
+  .object({
+    invites: z.array(membershipSchema),
+  })
+  .strip();
+
+const explicitGrantsResponseSchema: VaultResponseSchema<{
+  grants?: ExplicitGrant[];
+  computedAt: string;
+}> = z
+  .object({
+    grants: z.array(explicitGrantSchema).optional(),
+    computedAt: z.string(),
+  })
+  .strip();
+
+const listFilesResponseSchema: VaultResponseSchema<{
+  objects: VaultListedObject[];
+  cursor: string | null;
+  truncated: boolean;
+}> = z
+  .object({
+    objects: z.array(vaultListedObjectSchema).default([]),
+    cursor: z.string().nullable().default(null),
+    truncated: z.boolean().default(false),
+  })
+  .strip();
+
+const presignResponseSchema: VaultResponseSchema<{
+  results: PresignResultRow[];
+  expiresAt: string;
+}> = z
+  .object({
+    results: z.array(presignResultRowSchema),
+    expiresAt: z.string(),
+  })
+  .strip();
+
+const entityResponseSchema: VaultResponseSchema<{ entity: EntityInfo }> = z
+  .object({
+    entity: entityInfoSchema,
+  })
+  .strip();
+
+const checkSlugMeResponseSchema: VaultResponseSchema<{
+  available: boolean;
+  conflictingCompanyUid?: string;
+}> = z
+  .object({
+    available: z.boolean(),
+    conflictingCompanyUid: z.string().optional(),
+  })
+  .strip();
+
+const createEntityResponseSchema: VaultResponseSchema<CreateEntityResult> = z
+  .object({
+    entity: entityInfoSchema,
+  })
+  .strip();
+
+const entitiesResponseSchema: VaultResponseSchema<{ entities?: EntityInfo[] }> =
+  z
+    .object({
+      entities: z.array(entityInfoSchema).optional(),
+    })
+    .strip();
+
+const provisionBucketResponseSchema: VaultResponseSchema<{
+  bucketName: string;
+  kmsKeyId: string;
+}> = z
+  .object({
+    bucketName: z.string(),
+    kmsKeyId: z.string(),
+  })
+  .strip();
+
+const vendResponseSchema: VaultResponseSchema<VendResult> = z
+  .object({
+    credentials: vendCredentialsSchema,
+    paths: z.array(z.string()),
+    operations: vaultOperationSchema,
+    purpose: vendPurposeSchema,
+    policySize: z.number(),
+    requestId: z.string().optional(),
+  })
+  .strip();
+
+const stsVendResponseSchema: VaultResponseSchema<{
+  credentials: StsChildCredentials;
+  expiresAt: string;
+}> = z
+  .object({
+    credentials: stsCredentialsSchema,
+    expiresAt: z.string(),
+  })
+  .strip();
+
+const vendChildResponseSchema: VaultResponseSchema<VendChildResult> = z
+  .object({
+    credentials: stsCredentialsSchema,
+    sessionName: z.string(),
+    expiresAt: z.string(),
+  })
+  .strip();
+
+const emptyObjectResponseSchema = z.object({}).strip();
+
+function summarizeZodIssues(issues: readonly z.core.$ZodIssue[]): string {
+  return issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}
+
 // ---------------------------------------------------------------------------
 // VaultClient
 // ---------------------------------------------------------------------------
@@ -472,17 +773,19 @@ export class VaultClient {
   // -- Membership operations ------------------------------------------------
 
   async createInvite(input: CreateInviteInput): Promise<CreateInviteResult> {
-    const data = await this.post<{ membership: Membership; inviteToken: string }>(
+    const data = await this.post(
       "/membership/invite",
       input,
+      createInviteResponseSchema,
     );
     return data;
   }
 
   async acceptInvite(token: string, personUid: string): Promise<AcceptInviteResult> {
-    const data = await this.post<{ membership: Membership }>(
+    const data = await this.post(
       "/membership/accept",
       { token, personUid },
+      acceptInviteResponseSchema,
     );
     return data;
   }
@@ -494,7 +797,11 @@ export class VaultClient {
    * 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 });
+    await this.post(
+      "/membership/revoke",
+      { membershipKey, companyUid },
+      emptyObjectResponseSchema,
+    );
   }
 
   /**
@@ -513,7 +820,7 @@ export class VaultClient {
    * Backed by `GET /membership/me` (see hq-pro ADR-0002).
    */
   async listMyMemberships(): Promise<Membership[]> {
-    const data = await this.get<{ memberships: Membership[] }>("/membership/me");
+    const data = await this.get("/membership/me", membershipsResponseSchema);
     return data.memberships;
   }
 
@@ -527,8 +834,9 @@ export class VaultClient {
    * person exists.
    */
   async listMyPendingInvitesByEmail(): Promise<PendingInviteByEmail[]> {
-    const data = await this.get<{ invites: PendingInviteByEmail[] }>(
+    const data = await this.get(
       "/membership/pending-by-email",
+      pendingInvitesByEmailResponseSchema,
     );
     return data.invites ?? [];
   }
@@ -539,27 +847,34 @@ export class VaultClient {
    * have no pending invites. The caller's email is inferred from the JWT.
    */
   async claimPendingInvitesByEmail(personUid: string): Promise<void> {
-    await this.post("/membership/claim-by-email", { personUid });
+    await this.post(
+      "/membership/claim-by-email",
+      { personUid },
+      emptyObjectResponseSchema,
+    );
   }
 
   async listMembersOfCompany(companyUid: string): Promise<Membership[]> {
-    const data = await this.get<{ members: Membership[] }>(
+    const data = await this.get(
       `/membership/company/${encodeURIComponent(companyUid)}`,
+      membersResponseSchema,
     );
     return data.members;
   }
 
   async updateRole(input: UpdateRoleInput): Promise<Membership> {
-    const data = await this.post<{ membership: Membership }>(
+    const data = await this.post(
       "/membership/role",
       input,
+      membershipResponseSchema,
     );
     return data.membership;
   }
 
   async listPendingInvites(companyUid: string): Promise<Membership[]> {
-    const data = await this.get<{ invites: Membership[] }>(
+    const data = await this.get(
       `/membership/company/${encodeURIComponent(companyUid)}/pending`,
+      invitesResponseSchema,
     );
     return data.invites;
   }
@@ -581,8 +896,9 @@ export class VaultClient {
    * state without catching errors.
    */
   async listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]> {
-    const data = await this.get<{ grants: ExplicitGrant[]; computedAt: string }>(
+    const data = await this.get(
       `/v1/files/grants?company=${encodeURIComponent(companyUid)}`,
+      explicitGrantsResponseSchema,
     );
     return data.grants ?? [];
   }
@@ -608,15 +924,14 @@ export class VaultClient {
     const qs = new URLSearchParams({ company: companyUid });
     if (prefix) qs.set("prefix", prefix);
     if (cursor) qs.set("cursor", cursor);
-    const data = await this.get<{
-      objects?: VaultListedObject[];
-      cursor?: string | null;
-      truncated?: boolean;
-    }>(`/v1/files/list?${qs.toString()}`);
+    const data = await this.get(
+      `/v1/files/list?${qs.toString()}`,
+      listFilesResponseSchema,
+    );
     return {
-      objects: data.objects ?? [],
-      cursor: data.cursor ?? null,
-      truncated: data.truncated ?? false,
+      objects: data.objects,
+      cursor: data.cursor,
+      truncated: data.truncated,
     };
   }
 
@@ -632,7 +947,7 @@ export class VaultClient {
     expiresIn?: number;
     keys: PresignKeyInput[];
   }): Promise<{ results: PresignResultRow[]; expiresAt: string }> {
-    return this.post<{ results: PresignResultRow[]; expiresAt: string }>(
+    return this.post(
       `/v1/files/presign`,
       {
         company: input.companyUid,
@@ -640,6 +955,7 @@ export class VaultClient {
         ...(input.expiresIn ? { expiresIn: input.expiresIn } : {}),
         keys: input.keys,
       },
+      presignResponseSchema,
     );
   }
 
@@ -659,8 +975,9 @@ export class VaultClient {
   async getMembershipSyncConfig(
     membershipId: string,
   ): Promise<MembershipSyncConfig> {
-    return this.get<MembershipSyncConfig>(
+    return this.get(
       `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
+      membershipSyncConfigSchema,
     );
   }
 
@@ -678,10 +995,11 @@ export class VaultClient {
     membershipId: string,
     partial: SetMembershipSyncConfigInput,
   ): Promise<MembershipSyncConfig> {
-    return this.request<MembershipSyncConfig>(
+    return this.request(
       "PUT",
       `/v1/memberships/${encodeURIComponent(membershipId)}/sync-config`,
       partial,
+      membershipSyncConfigSchema,
     );
   }
 
@@ -689,7 +1007,10 @@ export class VaultClient {
 
   readonly entity = {
     get: async (uid: string): Promise<EntityInfo> => {
-      const data = await this.get<{ entity: EntityInfo }>(`/entity/${encodeURIComponent(uid)}`);
+      const data = await this.get(
+        `/entity/${encodeURIComponent(uid)}`,
+        entityResponseSchema,
+      );
       return data.entity;
     },
 
@@ -705,8 +1026,9 @@ export class VaultClient {
      * global lookup (admin tooling) should still use this method.
      */
     findBySlug: async (type: string, slug: string): Promise<EntityInfo> => {
-      const data = await this.get<{ entity: EntityInfo }>(
+      const data = await this.get(
         `/entity/by-slug/${encodeURIComponent(type)}/${encodeURIComponent(slug)}`,
+        entityResponseSchema,
       );
       return data.entity;
     },
@@ -727,25 +1049,24 @@ export class VaultClient {
       type: string,
       slug: string,
     ): Promise<EntityInfo | null> => {
-      const check = await this.get<{
-        available: boolean;
-        conflictingCompanyUid?: string;
-      }>(
+      const check = await this.get(
         `/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`,
+        checkSlugMeResponseSchema,
       );
       if (check.available || !check.conflictingCompanyUid) return null;
       return this.entity.get(check.conflictingCompanyUid);
     },
 
     create: async (input: CreateEntityInput): Promise<EntityInfo> => {
-      const data = await this.post<CreateEntityResult>("/entity", input);
+      const data = await this.post("/entity", input, createEntityResponseSchema);
       return data.entity;
     },
 
     /** Return every entity of `type` owned by the caller (scoped by JWT). */
     listByType: async (type: string): Promise<EntityInfo[]> => {
-      const data = await this.get<{ entities: EntityInfo[] }>(
+      const data = await this.get(
         `/entity/by-type/${encodeURIComponent(type)}`,
+        entitiesResponseSchema,
       );
       return data.entities ?? [];
     },
@@ -789,9 +1110,10 @@ export class VaultClient {
   // -- Provisioning operations (VLT-2) -----------------------------------------
 
   async provisionBucket(companyUid: string): Promise<{ bucketName: string; kmsKeyId: string }> {
-    const data = await this.post<{ bucketName: string; kmsKeyId: string }>(
+    const data = await this.post(
       "/provision/bucket",
       { companyUid },
+      provisionBucketResponseSchema,
     );
     return data;
   }
@@ -820,7 +1142,7 @@ export class VaultClient {
    * objects without ever materialising them under `companies/{co}/`.
    */
   async vend(input: VendInput): Promise<VendResult> {
-    return this.post<VendResult>("/vend", input);
+    return this.post("/vend", input, vendResponseSchema);
   }
 
   // -- STS operations (VLT-8) -----------------------------------------------
@@ -848,7 +1170,7 @@ export class VaultClient {
       };
       expiresAt: string;
     }> => {
-      return this.post("/sts/vend", input);
+      return this.post("/sts/vend", input, stsVendResponseSchema);
     },
     /**
      * Vend task-scoped child credentials strictly narrower than the caller's
@@ -864,14 +1186,14 @@ export class VaultClient {
      * the parent task for incident response.
      */
     vendChild: async (input: VendChildInput): Promise<VendChildResult> => {
-      const data = await this.post<VendChildResult>("/sts/vend-child", input);
+      const data = await this.post("/sts/vend-child", input, vendChildResponseSchema);
       return data;
     },
     vendSelf: async (input: { personUid: string; durationSeconds?: number }): Promise<{
       credentials: { accessKeyId: string; secretAccessKey: string; sessionToken: string };
       expiresAt: string;
     }> => {
-      return this.post("/sts/vend-self", input);
+      return this.post("/sts/vend-self", input, stsVendResponseSchema);
     },
   };
 
@@ -891,7 +1213,7 @@ export class VaultClient {
    * either yes or no; see `./telemetry.ts::collectAndSendTelemetry`.
    */
   async getTelemetryOptIn(): Promise<TelemetryOptInResponse> {
-    return this.get<TelemetryOptInResponse>("/v1/usage/opt-in");
+    return this.get("/v1/usage/opt-in", telemetryOptInResponseSchema);
   }
 
   /**
@@ -903,7 +1225,7 @@ export class VaultClient {
    * 1 MiB pre-flush cap which is the binding limit in practice.
    */
   async postUsage(batch: UsageBatch): Promise<UsageIngestResult> {
-    return this.post<UsageIngestResult>("/v1/usage", batch);
+    return this.post("/v1/usage", batch, usageIngestResultSchema);
   }
 
   /**
@@ -916,20 +1238,29 @@ export class VaultClient {
   async postSkillInvocations(
     batch: SkillInvocationBatch,
   ): Promise<SkillInvocationIngestResult> {
-    return this.post<SkillInvocationIngestResult>("/v1/skill-invocations", batch);
+    return this.post("/v1/skill-invocations", batch, usageIngestResultSchema);
   }
 
   // -- HTTP primitives with retry -------------------------------------------
 
-  private async get<T>(path: string): Promise<T> {
-    return this.request<T>("GET", path);
+  private async get<T>(path: string, schema: VaultResponseSchema<T>): Promise<T> {
+    return this.request("GET", path, undefined, schema);
   }
 
-  private async post<T>(path: string, body?: unknown): Promise<T> {
-    return this.request<T>("POST", path, body);
+  private async post<T>(
+    path: string,
+    body: unknown | undefined,
+    schema: VaultResponseSchema<T>,
+  ): Promise<T> {
+    return this.request("POST", path, body, schema);
   }
 
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  private async request<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    schema: VaultResponseSchema<T>,
+  ): Promise<T> {
     let lastError: Error | undefined;
 
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
@@ -962,7 +1293,28 @@ export class VaultClient {
 
       if (res.ok) {
         if (res.status === 204) return undefined as T;
-        return (await res.json()) as T;
+        const responseBody = await res.text();
+        let decoded: unknown;
+        try {
+          decoded = JSON.parse(responseBody);
+        } catch (err) {
+          throw new VaultClientError(
+            `Invalid JSON response from vault-service for ${method} ${path}`,
+            502,
+            err instanceof Error ? err.message : responseBody,
+          );
+        }
+
+        const parsed = schema.safeParse(decoded);
+        if (!parsed.success) {
+          throw new VaultClientError(
+            `Invalid response from vault-service for ${method} ${path}: ${summarizeZodIssues(parsed.error.issues)}`,
+            502,
+            responseBody,
+          );
+        }
+
+        return parsed.data;
       }
 
       const responseBody = await res.text();