feat: implement safe createSafeKeys and finalize orchestrator

modules/sdk-core/src/bitgo/keychain/iKeychains.ts

@@ -151,6 +151,9 @@ export interface AddKeychainOptions {
    *  Sent as `webauthnInfo` in the POST /key body so the backend can link
    *  the passkey to the keychain in the same request. */
   webauthnInfo?: WebauthnInfo;
+  /** Public id of the safe this key is a root of (Wallet Safes v1). When set, the backend tags
+   *  the key with the safe and stamps its curve server-side. @experimental */
+  safeId?: string;
 }
 
 export interface ApiKeyShare {
@@ -178,6 +181,8 @@ export interface CreateBackupOptions {
   encryptedPrv?: string;
   passphrase?: string;
   encryptionVersion?: EncryptionVersion;
+  /** Public id of the safe this backup key is a root of (Wallet Safes v1). @experimental */
+  safeId?: string;
 }
 
 export interface CreateBitGoOptions {
@@ -186,6 +191,8 @@ export interface CreateBitGoOptions {
   reqId?: IRequestTracer;
   keyType?: KeyType;
   isDistributedCustody?: boolean;
+  /** Public id of the safe this BitGo key is a root of (Wallet Safes v1). @experimental */
+  safeId?: string;
 }
 
 export type DecryptedRetrofitPayload = {
@@ -202,6 +209,9 @@ export interface CreateMpcOptions {
   retrofit?: DecryptedRetrofitPayload;
   webauthnInfo?: WebauthnKeyEncryptionInfo;
   encryptionVersion?: EncryptionVersion;
+  /** Public id of the safe these MPC root keys belong to (Wallet Safes v1). Threaded through the
+   *  ceremony so the resulting user/backup/bitgo keys land tagged. @experimental */
+  safeId?: string;
 }
 
 export interface RecreateMpcOptions extends Omit<CreateMpcOptions, 'retrofit' | 'multisigType'> {

modules/sdk-core/src/bitgo/keychain/keychains.ts

@@ -257,6 +257,7 @@ export class Keychains implements IKeychains {
         'originalPasscodeEncryptionCode',
         'enterprise',
         'derivedFromParentWithSeed',
+        'safeId',
       ]
     );
 
@@ -295,6 +296,7 @@ export class Keychains implements IKeychains {
         coinSpecific: params.coinSpecific,
         webauthnDevices: params.webauthnDevices,
         webauthnInfo: params.webauthnInfo,
+        safeId: params.safeId,
       })
       .result();
   }
@@ -384,6 +386,7 @@ export class Keychains implements IKeychains {
       retrofit: params.retrofit,
       webauthnInfo: params.webauthnInfo,
       encryptionVersion: params.encryptionVersion,
+      safeId: params.safeId,
     });
   }
 

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

@@ -17,11 +17,15 @@ import type {
 } from '@bitgo/public-types';
 import type { Wallet, WalletShare } from '../wallet';
 
+/** @experimental */
 export interface InitializeSafeOptions {
   label: string;
 }
 
-// Phase 3 — the client hands back the 12 key ids it created in Phase 2:
+/**
+ * Phase 3 — the client hands back the 12 key ids it created in Phase 2.
+ * @experimental
+ */
 export interface FinalizeSafeOptions {
   rootKeys: SafeRootKeys;
 }

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

@@ -14,28 +14,39 @@ import { Safe } from './safe';
  * 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.
+ * @experimental
  */
 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. */
+/**
+ * Handle returned by `initializeSafe`, threaded into the key ceremonies and finalize.
+ * @experimental
+ */
 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.
+ * @experimental
  */
 export type SafeKeys = FinalizeSafeOptions;
 
+/**
+ * @experimental
+ */
 export interface ListSafesOptions {
   cursor?: string; // opaque cursor from a previous response's nextCursor
   limit?: number;
 }
 
+/**
+ * @experimental
+ */
 export interface GetSafeOptions {
   id: string;
 }
@@ -45,16 +56,33 @@ export interface GetSafeOptions {
  */
 export interface ISafes {
   /**
-   * One-call convenience wrapper: initialize → createSafeKeys (4 safeId-tagged ceremonies) →
-   * finalize → keycard. HOT custody only in v1.
+   * One-call convenience wrapper chaining the three creation phases:
+   * initialize → createSafeKeys (4 safeId-tagged ceremonies) → finalize. HOT custody only in v1.
+   * @experimental
    */
   generateSafe(params: CreateSafeOptions): Promise<Safe>;
-  /** Phase 1 — initialize a safe (metadata only, no key material). */
+  /**
+   * Phase 1 — initialize a safe (metadata only, no key material).
+   * @experimental
+   */
   initializeSafe(params: InitializeSafeOptions): Promise<Safe>;
-  /** Phase 2 — run the 4 root key ceremonies tagged with `safeId`; returns the 12 minted key ids. */
+  /**
+   * Phase 2 — run the 4 root key ceremonies tagged with `safeId`; returns the 12 minted key ids.
+   * @experimental
+   */
   createSafeKeys(params: CreateSafeOptions & SafeCreationHandle): Promise<SafeKeys>;
-  /** Phase 3 — finalize a safe with the 12 root key ids. Idempotent. */
+  /**
+   * Phase 3 — finalize a safe with the 12 root key ids. Idempotent.
+   * @experimental
+   */
   finalizeSafe(safeId: string, params: FinalizeSafeOptions): Promise<Safe>;
+  /**
+   * Archive a safe. Also the abandonment path for a stuck `initializing` safe.
+   * @experimental
+   */
+  archiveSafe(safeId: string): Promise<Safe>;
+  /** @experimental */
   list(params?: ListSafesOptions): Promise<{ safes: Safe[]; nextCursor?: string }>;
+  /** @experimental */
   get(params: GetSafeOptions): Promise<Safe>;
 }