feat: add sdk-core vault module interfaces and scaffolding

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

@@ -7,6 +7,7 @@ import { BitGoBase } from '../bitgoBase';
 import { EnterpriseData, EnterpriseFeatureFlag, IEnterprise } from '../enterprise';
 import { getFirstPendingTransaction } from '../internal';
 import { ListWalletOptions, Wallet } from '../wallet';
+import { Safes } from '../safe';
 import { BitGoProofSignatures, EcdsaUtils, SerializedNtildeWithVerifiers } from '../utils/tss/ecdsa';
 import { EcdsaTypes } from '@bitgo/sdk-lib-mpc';
 import { verifyEcdhSignature } from '../ecdh';
@@ -249,4 +250,12 @@ export class Enterprise implements IEnterprise {
   hasFeatureFlags(flags: EnterpriseFeatureFlag[]): boolean {
     return flags.every((targetFlag) => this._enterprise.featureFlags?.includes(targetFlag));
   }
+
+  /**
+   * Get the safes collection accessor scoped to this Enterprise
+   * @experimental
+   */
+  safes(): Safes {
+    return new Safes(this.bitgo, this.id);
+  }
 }

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

@@ -3,6 +3,7 @@ import { IWallet } from '../wallet';
 import { Buffer } from 'buffer';
 import { BitGoProofSignatures, SerializedNtildeWithVerifiers } from '../utils/tss/ecdsa';
 import { EcdhDerivedKeypair } from '../keychain';
+import { ISafes } from '../safe';
 
 // useEnterpriseEcdsaTssChallenge is deprecated
 export type EnterpriseFeatureFlag = 'useEnterpriseEcdsaTssChallenge';
@@ -39,4 +40,6 @@ export interface IEnterprise {
     bitgoNitroChallenge: SerializedNtildeWithVerifiers
   ): Promise<void>;
   hasFeatureFlags(flags: EnterpriseFeatureFlag[]): boolean;
+  /** @experimental */
+  safes(): ISafes;
 }

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

@@ -27,6 +27,7 @@ export * from './tss';
 export { sendSignatureShare } from './tss';
 export * from './types';
 export * from './utils';
+export * from './safe';
 export * from './wallet';
 export * from './webhook';
 export { bitcoinUtil };

modules/sdk-core/src/bitgo/safe/iSafe.ts

@@ -0,0 +1,97 @@
+/**
+ * @prettier
+ *
+ * @experimental The safe client surface is experimental and may change (including breaking
+ * changes) before the public release.
+ */
+// Wire/data shapes are owned by @bitgo/public-types — import them where needed rather than
+// re-exporting from sdk-core.
+import type {
+  FreezeSafeBody,
+  SafeData,
+  SafePermission,
+  SafeRootKeys,
+  SafeShareData,
+  SafeShareKeychain,
+  SafeShareState,
+} from '@bitgo/public-types';
+import type { Wallet, WalletShare } from '../wallet';
+
+export interface InitializeSafeOptions {
+  label: string;
+}
+
+// Phase 3 — the client hands back the 12 key ids it created in Phase 2:
+export interface FinalizeSafeOptions {
+  rootKeys: SafeRootKeys;
+}
+
+/**
+ * Sharing ONE safe wallet with a non-member rides the existing wallet-share handshake (FR-13),
+ * so the result is the existing WalletShare shape.
+ */
+export type WalletShareData = WalletShare;
+
+// ---- per-safe operation options (bodies land in WCN-1203 / WCN-1204) ----
+
+export interface CreateSafeWalletOptions {
+  coin: string;
+  label: string;
+  type?: string;
+  multisigTypeVersion?: string;
+}
+
+interface AddSafeMemberBase {
+  permissions: SafePermission[];
+  /** required when 'spend' is included — the 4 root user keys ECDH-re-encrypted to the invitee */
+  keychains?: SafeShareKeychain[];
+  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 AddSafeMemberOptions =
+  | (AddSafeMemberBase & { userId: string; email?: never })
+  | (AddSafeMemberBase & { email: string; userId?: never });
+
+export interface AddSafeWalletMemberOptions {
+  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 type AcceptSafeShareAsSpenderOptions = {
+  safeShareId: string;
+  userPassword: string;
+  newWalletPassphrase?: string;
+};
+export type AcceptSafeShareAsNonSpenderOptions = {
+  safeShareId: string;
+};
+export type AcceptSafeShareOptions = AcceptSafeShareAsSpenderOptions | AcceptSafeShareAsNonSpenderOptions;
+
+/**
+ * @experimental
+ */
+export interface ISafe {
+  id(): string;
+  enterpriseId(): string;
+  label(): string;
+  status(): SafeData['status'];
+  url(extra?: string): string;
+  createWallet(params: CreateSafeWalletOptions): Promise<Wallet>;
+  // whole-safe: view/admin/spend/dapp; spend opens a key share (also how a spender services a
+  // safeShareRequests entry in UMS orgs)
+  addMember(params: AddSafeMemberOptions): Promise<SafeData>;
+  // share ONE safe wallet, not the whole safe
+  addMemberToWallet(params: AddSafeWalletMemberOptions): Promise<WalletShareData>;
+  listShares(params?: { state?: SafeShareState }): Promise<SafeShareData[]>;
+  acceptShare(params: AcceptSafeShareOptions): Promise<SafeShareData>;
+  freeze(params?: FreezeSafeBody): Promise<SafeData>;
+  archive(): Promise<SafeData>;
+  toJSON(): SafeData;
+}

modules/sdk-core/src/bitgo/safe/iSafes.ts

@@ -0,0 +1,60 @@
+/**
+ * @prettier
+ *
+ * @experimental The safe client surface is experimental and may change (including breaking
+ * changes) before the public release.
+ */
+import { FinalizeSafeOptions, InitializeSafeOptions } from './iSafe';
+import { Safe } from './safe';
+
+/**
+ * Options for safe creation.
+ *
+ * v1 targets the HOT custody model only: the multisig root user/backup keys are generated locally
+ * by the SDK, encrypted with `passphrase`, and registered on BitGo; the MPC roots run the standard
+ * hot ceremonies with the same passphrase. Self-managed cold keys and custodial safes are out of
+ * scope for v1.
+ */
+export interface CreateSafeOptions {
+  label: string;
+  passphrase: string; // encrypts the locally-generated multisig user/backup prvs; shared with the MPC ceremonies
+}
+
+/** Handle returned by `initializeSafe`, threaded into the key ceremonies and finalize. */
+export interface SafeCreationHandle {
+  safeId: string;
+}
+
+/**
+ * The 12 minted root key ids produced by `createSafeKeys`, as 4 ordered [user, backup, bitgo]
+ * triplets — exactly the payload `finalizeSafe` consumes.
+ */
+export type SafeKeys = FinalizeSafeOptions;
+
+export interface ListSafesOptions {
+  cursor?: string; // opaque cursor from a previous response's nextCursor
+  limit?: number;
+}
+
+export interface GetSafeOptions {
+  id: string;
+}
+
+/**
+ * @experimental
+ */
+export interface ISafes {
+  /**
+   * One-call convenience wrapper: initialize → createSafeKeys (4 safeId-tagged ceremonies) →
+   * finalize → keycard. HOT custody only in v1.
+   */
+  generateSafe(params: CreateSafeOptions): Promise<Safe>;
+  /** Phase 1 — initialize a safe (metadata only, no key material). */
+  initializeSafe(params: InitializeSafeOptions): Promise<Safe>;
+  /** Phase 2 — run the 4 root key ceremonies tagged with `safeId`; returns the 12 minted key ids. */
+  createSafeKeys(params: CreateSafeOptions & SafeCreationHandle): Promise<SafeKeys>;
+  /** Phase 3 — finalize a safe with the 12 root key ids. Idempotent. */
+  finalizeSafe(safeId: string, params: FinalizeSafeOptions): Promise<Safe>;
+  list(params?: ListSafesOptions): Promise<{ safes: Safe[]; nextCursor?: string }>;
+  get(params: GetSafeOptions): Promise<Safe>;
+}

modules/sdk-core/src/bitgo/safe/index.ts

@@ -0,0 +1,4 @@
+export * from './iSafe';
+export * from './iSafes';
+export * from './safe';
+export * from './safes';

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

@@ -0,0 +1,128 @@
+/**
+ * @prettier
+ *
+ * @experimental The safe client surface is experimental and may change (including breaking
+ * changes) before the public release.
+ */
+import * as _ from 'lodash';
+import { FreezeSafeBody, SafeData, SafeShareData, SafeShareState } from '@bitgo/public-types';
+import { BitGoBase } from '../bitgoBase';
+import { decodeWithCodec } from '../utils/codecs';
+import { postWithCodec } from '../utils/postWithCodec';
+import { Wallet } from '../wallet';
+import {
+  AcceptSafeShareOptions,
+  AddSafeMemberOptions,
+  AddSafeWalletMemberOptions,
+  CreateSafeWalletOptions,
+  ISafe,
+  WalletShareData,
+} from './iSafe';
+
+/**
+ * @experimental
+ */
+export class Safe implements ISafe {
+  private readonly bitgo: BitGoBase;
+  public readonly _safe: SafeData;
+
+  constructor(bitgo: BitGoBase, safeData: SafeData) {
+    this.bitgo = bitgo;
+    if (!_.isObject(safeData)) {
+      throw new Error('safeData has to be an object');
+    }
+    if (!_.isString(safeData.id)) {
+      throw new Error('safe id has to be a string');
+    }
+    if (!_.isString(safeData.enterpriseId)) {
+      throw new Error('safe enterpriseId has to be a string');
+    }
+    this._safe = safeData;
+  }
+
+  id(): string {
+    return this._safe.id;
+  }
+
+  enterpriseId(): string {
+    return this._safe.enterpriseId;
+  }
+
+  label(): string {
+    return this._safe.label;
+  }
+
+  status(): SafeData['status'] {
+    return this._safe.status;
+  }
+
+  /**
+   * Enterprise-scoped v2 URL for this safe, e.g. /api/v2/enterprise/:eId/safes/:safeId
+   * @param extra
+   */
+  url(extra = ''): string {
+    return this.bitgo.url(`/enterprise/${this.enterpriseId()}/safes/${this.id()}${extra}`, 2);
+  }
+
+  /**
+   * Mint a child wallet in this safe (server-side public derivation — no ceremony).
+   * Body lands in WCN-1203.
+   */
+  async createWallet(params: CreateSafeWalletOptions): Promise<Wallet> {
+    throw new Error('Safe.createWallet is not yet implemented (WCN-1203)');
+  }
+
+  /**
+   * Add a member to the whole safe (view/admin/spend). Spend opens a key share.
+   * Body lands in WCN-1204.
+   */
+  async addMember(params: AddSafeMemberOptions): Promise<SafeData> {
+    throw new Error('Safe.addMember is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Share ONE safe wallet with a non-member via the existing wallet-share handshake (FR-13).
+   * Body lands in WCN-1204.
+   */
+  async addMemberToWallet(params: AddSafeWalletMemberOptions): Promise<WalletShareData> {
+    throw new Error('Safe.addMemberToWallet is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * List the safe key shares visible to the caller.
+   * Body lands in WCN-1204.
+   */
+  async listShares(params: { state?: SafeShareState } = {}): Promise<SafeShareData[]> {
+    throw new Error('Safe.listShares is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Accept a safe key share addressed to the caller.
+   * Body lands in WCN-1204.
+   */
+  async acceptShare(params: AcceptSafeShareOptions): Promise<SafeShareData> {
+    throw new Error('Safe.acceptShare is not yet implemented (WCN-1204)');
+  }
+
+  /**
+   * Freeze the safe — blocks withdrawals on all safe wallets. Safe stays 'active'.
+   * @param params
+   */
+  async freeze(params: FreezeSafeBody = {}): Promise<SafeData> {
+    const response = await postWithCodec(this.bitgo, this.url('/freeze'), FreezeSafeBody, params).result();
+    return decodeWithCodec(SafeData, response, 'SafeData');
+  }
+
+  /**
+   * Archive the safe. Requires every safe wallet to already be archived; also the abandonment
+   * path for a stuck 'initializing' safe.
+   */
+  async archive(): Promise<SafeData> {
+    const response = await this.bitgo.post(this.url('/archive')).send().result();
+    return decodeWithCodec(SafeData, response, 'SafeData');
+  }
+
+  toJSON(): SafeData {
+    return this._safe;
+  }
+}