chore: add Pr review comments

WCN-1192

TICKET: WCN-1192

Author: davidkaplanbitgo

modules/sdk-core/src/bitgo/enterprise/enterprise.ts

@@ -253,8 +253,9 @@ export class Enterprise implements IEnterprise {
 
   /**
    * Get the vaults collection accessor scoped to this Enterprise
+   * @experimental
    */
   vaults(): Vaults {
-    return new Vaults(this.bitgo, this.baseCoin, this.id);
+    return new Vaults(this.bitgo, this.id);
   }
 }

modules/sdk-core/src/bitgo/enterprise/iEnterprise.ts

@@ -40,5 +40,6 @@ export interface IEnterprise {
     bitgoNitroChallenge: SerializedNtildeWithVerifiers
   ): Promise<void>;
   hasFeatureFlags(flags: EnterpriseFeatureFlag[]): boolean;
+  /** @experimental */
   vaults(): IVaults;
 }

modules/sdk-core/src/bitgo/vault/codecs.ts

@@ -0,0 +1,178 @@
+/**
+ * @prettier
+ *
+ * io-ts codecs for the vault REST surface. These are the single source of truth for the
+ * vault data shapes: the TypeScript interfaces in `iVault.ts` are derived from them via
+ * `t.TypeOf`, request bodies are encoded with `postWithCodec`, and responses are decoded
+ * (and validated) with `decodeWithCodec` — so there are no `as VaultData` casts.
+ *
+ * Timestamps use `DateFromISOString`: the wire representation stays an ISO-8601 string while
+ * the decoded object exposes a real `Date`.
+ */
+import * as t from 'io-ts';
+import { DateFromISOString } from 'io-ts-types';
+
+/**
+ * The four static root-key slots of a vault, keyed by (curve, scheme):
+ * - secp256k1Multisig ① — ex. UTXO/XRP/XTZ/TRX/EOS
+ * - ecdsaMpc          ② — ex. EVM/Cosmos (DKLS)
+ * - eddsaMpc          ③ — ex. SOL/SUI/NEAR/TON/APT/DOT
+ * - ed25519Multisig   ④ — ex. ALGO/XLM/HBAR
+ */
+export const RootKeyType = t.keyof(
+  {
+    secp256k1Multisig: null,
+    ecdsaMpc: null,
+    eddsaMpc: null,
+    ed25519Multisig: null,
+  },
+  'RootKeyType'
+);
+
+export const VaultPermission = t.keyof(
+  {
+    view: null,
+    spend: null,
+    admin: null,
+    dapp: null,
+  },
+  'VaultPermission'
+);
+
+/** An ordered [userKeyId, backupKeyId, bitgoKeyId] triplet — same shape/order as wallet.keys[]. */
+export const RootKeyTriplet = t.tuple([t.string, t.string, t.string], 'RootKeyTriplet');
+
+/** The 12 static root key ids, by (curve, scheme). */
+export const VaultRootKeys = t.type(
+  {
+    secp256k1Multisig: RootKeyTriplet,
+    ecdsaMpc: RootKeyTriplet,
+    eddsaMpc: RootKeyTriplet,
+    ed25519Multisig: RootKeyTriplet,
+  },
+  'VaultRootKeys'
+);
+
+export const VaultMembershipData = t.intersection(
+  [
+    t.type({
+      userId: t.string,
+      permissions: t.array(VaultPermission),
+    }),
+    t.partial({
+      needsRecovery: t.boolean,
+    }),
+  ],
+  'VaultMembershipData'
+);
+
+/** A pending UMS spend grant awaiting a key share — mirror of the wallet's walletShareRequests[]. */
+export const VaultShareRequest = t.type(
+  {
+    userId: t.string,
+    permissions: t.array(VaultPermission),
+    createdAt: DateFromISOString,
+  },
+  'VaultShareRequest'
+);
+
+export const VaultFreeze = t.partial(
+  {
+    time: DateFromISOString,
+    expires: DateFromISOString,
+    reason: t.string,
+  },
+  'VaultFreeze'
+);
+
+export const VaultStatus = t.keyof(
+  {
+    initializing: null,
+    active: null,
+    archived: null,
+  },
+  'VaultStatus'
+);
+
+export const VaultData = t.intersection(
+  [
+    t.type({
+      id: t.string,
+      enterpriseId: t.string,
+      label: t.string,
+      // freeze is NOT a status — a frozen vault stays 'active' with the freeze field set (wallet precedent)
+      status: VaultStatus,
+      creator: t.string,
+      users: t.array(VaultMembershipData),
+      createdAt: DateFromISOString,
+    }),
+    t.partial({
+      vaultShareRequests: t.array(VaultShareRequest),
+      freeze: VaultFreeze,
+      rootKeys: VaultRootKeys,
+      archivedAt: DateFromISOString,
+    }),
+  ],
+  'VaultData'
+);
+
+/** Vault key-share states — identical to WalletShare states, no new states. */
+export const VaultShareState = t.keyof(
+  {
+    pendingapproval: null,
+    active: null,
+    accepted: null,
+    canceled: null,
+    rejected: null,
+  },
+  'VaultShareState'
+);
+
+/** One of the 4 root USER keyshares carried on a VaultShare, ECDH-re-encrypted to the recipient. */
+export const VaultShareKeychain = t.type(
+  {
+    rootKeyType: RootKeyType,
+    rootKeyId: t.string,
+    encryptedPrv: t.string,
+    publicIdentifier: t.string,
+    fromPubKey: t.string,
+    toPubKey: t.string,
+    path: t.string,
+  },
+  'VaultShareKeychain'
+);
+
+export const VaultShareData = t.intersection(
+  [
+    t.type({
+      id: t.string,
+      enterpriseId: t.string,
+      vaultId: t.string,
+      fromUser: t.string,
+      toUser: t.string,
+      permissions: t.array(VaultPermission),
+      state: VaultShareState,
+      createdAt: DateFromISOString,
+    }),
+    t.partial({
+      vaultLabel: t.string,
+      message: t.string,
+      pendingApprovalId: t.string,
+      isUMSInitiated: t.boolean,
+      keychains: t.array(VaultShareKeychain),
+      updatedAt: DateFromISOString,
+    }),
+  ],
+  'VaultShareData'
+);
+
+// ---- request bodies ----
+
+/** POST /enterprise/:eId/vaults — Phase 1 carries no key material. */
+export const InitializeVaultBody = t.type({ label: t.string }, 'InitializeVaultBody');
+
+/** POST /enterprise/:eId/vaults/:vId/finalize — the 12 key ids as 4 ordered triplets. */
+export const FinalizeVaultBody = t.type({ rootKeys: VaultRootKeys }, 'FinalizeVaultBody');
+
+/** POST/DELETE /enterprise/:eId/vaults/:vId/freeze */
+export const FreezeVaultBody = t.partial({ duration: t.number }, 'FreezeVaultBody');

modules/sdk-core/src/bitgo/vault/iVault.ts

@@ -1,99 +1,34 @@
 /**
  * @prettier
+ *
+ * @experimental The vault client surface is experimental and may change (including breaking
+ * changes) before the public release.
  */
+import * as t from 'io-ts';
 import type { FreezeOptions, Wallet, WalletShare } from '../wallet';
+import * as VaultCodecs from './codecs';
 
-/**
- * The four static root-key slots of a vault, keyed by (curve, scheme):
- * - secp256k1Multisig ① — UTXO/XRP/XTZ/TRX/EOS
- * - ecdsaMpc          ② — EVM/Cosmos (DKLS)
- * - eddsaMpc          ③ — SOL/SUI/NEAR/TON/APT/DOT
- * - ed25519Multisig   ④ — ALGO/XLM/HBAR
- */
-export type RootKeyType = 'secp256k1Multisig' | 'ecdsaMpc' | 'eddsaMpc' | 'ed25519Multisig';
-
-export type VaultPermission = 'view' | 'spend' | 'admin' | 'dapp';
+// ---- data shapes (derived from the io-ts codecs in ./codecs — single source of truth) ----
 
-/**
- * The 12 static root key ids, by (curve, scheme). Each entry is an ordered
- * [userKeyId, backupKeyId, bitgoKeyId] triplet — same shape and order as wallet.keys[].
- */
-export type VaultRootKeys = Record<RootKeyType, [userKeyId: string, backupKeyId: string, bitgoKeyId: string]>;
-
-export interface VaultMembershipData {
-  userId: string; // new-model naming convention
-  permissions: VaultPermission[];
-  needsRecovery?: boolean;
-}
-
-/**
- * A pending UMS spend grant awaiting a key share — mirror of the wallet's walletShareRequests[].
- * Returned to spenders/admins and serviced via addMember.
- */
-export interface VaultShareRequest {
-  userId: string;
-  permissions: VaultPermission[];
-  createdAt: string;
-}
-
-export interface VaultData {
-  id: string;
-  enterpriseId: string;
-  label: string;
-  // freeze is NOT a status — a frozen vault stays 'active' with the freeze field set (wallet precedent)
-  status: 'initializing' | 'active' | 'archived';
-  creator: string;
-  users: VaultMembershipData[];
-  vaultShareRequests?: VaultShareRequest[];
-  freeze?: { time?: string; expires?: string; reason?: string };
-  rootKeys?: VaultRootKeys; // ordered, like wallet.keys
-  archivedAt?: string;
-  createdAt: string;
-}
+export type RootKeyType = t.TypeOf<typeof VaultCodecs.RootKeyType>;
+export type VaultPermission = t.TypeOf<typeof VaultCodecs.VaultPermission>;
+export type VaultRootKeys = t.TypeOf<typeof VaultCodecs.VaultRootKeys>;
+export type VaultMembershipData = t.TypeOf<typeof VaultCodecs.VaultMembershipData>;
+export type VaultShareRequest = t.TypeOf<typeof VaultCodecs.VaultShareRequest>;
+export type VaultData = t.TypeOf<typeof VaultCodecs.VaultData>;
+export type VaultShareState = t.TypeOf<typeof VaultCodecs.VaultShareState>;
+export type VaultShareKeychain = t.TypeOf<typeof VaultCodecs.VaultShareKeychain>;
+export type VaultShareData = t.TypeOf<typeof VaultCodecs.VaultShareData>;
 
 export interface InitializeVaultOptions {
-  label: string; // Phase 1 carries no key material — key generation happens in Phase 2 via the existing keychain APIs
+  label: string;
 }
 
 // Phase 3 — the client hands back the 12 key ids it created in Phase 2:
 export interface FinalizeVaultOptions {
   rootKeys: VaultRootKeys;
 }
 
-/** Vault key-share states — identical to WalletShare states, no new states. */
-export type VaultShareState = 'pendingapproval' | 'active' | 'accepted' | 'canceled' | 'rejected';
-
-/**
- * One of the 4 root USER keyshares carried on a VaultShare, ECDH-re-encrypted to the recipient.
- * Body semantics land in the Part VI SDK ticket (WCN-1204).
- */
-export interface VaultShareKeychain {
-  rootKeyType: RootKeyType;
-  rootKeyId: string;
-  encryptedPrv: string;
-  publicIdentifier: string;
-  fromPubKey: string;
-  toPubKey: string;
-  path: string;
-}
-
-export interface VaultShareData {
-  id: string;
-  enterpriseId: string;
-  vaultId: string;
-  vaultLabel?: string;
-  fromUser: string;
-  toUser: string;
-  permissions: VaultPermission[];
-  state: VaultShareState;
-  message?: string;
-  pendingApprovalId?: string;
-  isUMSInitiated?: boolean;
-  keychains?: VaultShareKeychain[];
-  createdAt: string;
-  updatedAt?: string;
-}
-
 /**
  * Sharing ONE vault wallet with a non-member rides the existing wallet-share handshake (FR-13),
  * so the result is the existing WalletShare shape.
@@ -106,34 +41,45 @@ export interface CreateVaultWalletOptions {
   coin: string;
   label: string;
   type?: string;
-  multisigType?: string;
   multisigTypeVersion?: string;
 }
 
-export interface AddVaultMemberOptions {
-  userId?: string;
-  email?: string;
+interface AddVaultMemberBase {
   permissions: VaultPermission[];
-  // required when 'spend' is included — the 4 root user keys ECDH-re-encrypted to the invitee
+  /** required when 'spend' is included — the 4 root user keys ECDH-re-encrypted to the invitee */
   keychains?: VaultShareKeychain[];
   message?: string;
+  /** when true, suppress the invitation email that would otherwise be sent to `email` */
   disableEmail?: boolean;
 }
 
+/** Add a member by either `userId` or `email` — exactly one is required. */
+export type AddVaultMemberOptions =
+  | (AddVaultMemberBase & { userId: string; email?: never })
+  | (AddVaultMemberBase & { email: string; userId?: never });
+
 export interface AddVaultWalletMemberOptions {
   walletId: string;
+  /** required — sharing re-encrypts the user key, which needs hardened derivation from the passphrase */
+  walletPassphrase: string;
   email?: string;
   permissions?: string[];
   message?: string;
 }
 
-export interface AcceptVaultShareOptions {
+export type AcceptVaultShareAsSpenderOptions = {
   vaultShareId: string;
-  userPassword?: string;
+  userPassword: string;
   newWalletPassphrase?: string;
-  overrideEncryptedPrv?: string;
-}
+};
+export type AcceptVaultShareAsNonSpenderOptions = {
+  vaultShareId: string;
+};
+export type AcceptVaultShareOptions = AcceptVaultShareAsSpenderOptions | AcceptVaultShareAsNonSpenderOptions;
 
+/**
+ * @experimental
+ */
 export interface IVault {
   id(): string;
   enterpriseId(): string;
@@ -144,7 +90,7 @@ export interface IVault {
   // whole-vault: view/admin/spend; spend opens a key share (also how a spender services a
   // vaultShareRequests entry in UMS orgs)
   addMember(params: AddVaultMemberOptions): Promise<VaultData>;
-  // share ONE vault wallet (FR-13), not the whole vault
+  // share ONE vault wallet, not the whole vault
   addMemberToWallet(params: AddVaultWalletMemberOptions): Promise<WalletShareData>;
   listShares(params?: { state?: VaultShareState }): Promise<VaultShareData[]>;
   acceptShare(params: AcceptVaultShareOptions): Promise<VaultShareData>;