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/codecs.ts

@@ -0,0 +1,200 @@
+/**
+ * @prettier
+ *
+ * io-ts codecs for the safe REST surface. These are the single source of truth for the
+ * safe data shapes: the TypeScript interfaces in `iSafe.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 SafeData` 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 safe, 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 SafePermission = t.keyof(
+  {
+    view: null,
+    spend: null,
+    admin: null,
+    dapp: null,
+  },
+  'SafePermission'
+);
+
+/** 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 root key ids for a single custody model, keyed by (curve, scheme). */
+export const RootKeysByType = t.type(
+  {
+    secp256k1Multisig: RootKeyTriplet,
+    ecdsaMpc: RootKeyTriplet,
+    eddsaMpc: RootKeyTriplet,
+    ed25519Multisig: RootKeyTriplet,
+  },
+  'RootKeysByType'
+);
+
+/** Custody models a safe's roots can be created under. v1 implements `hot` only. */
+export const SafeCustodyType = t.keyof(
+  {
+    hot: null,
+    cold: null,
+    custodial: null,
+  },
+  'SafeCustodyType'
+);
+
+/**
+ * A safe's root keys grouped by custody model — each model holds its own set of 4 (curve, scheme)
+ * root triplets. Only `hot` is populated in v1; `cold`/`custodial` are reserved for later phases.
+ */
+export const SafeRootKeys = t.partial(
+  {
+    hot: RootKeysByType,
+    cold: RootKeysByType,
+    custodial: RootKeysByType,
+  },
+  'SafeRootKeys'
+);
+
+export const SafeMembershipData = t.intersection(
+  [
+    t.type({
+      userId: t.string,
+      permissions: t.array(SafePermission),
+    }),
+    t.partial({
+      needsRecovery: t.boolean,
+    }),
+  ],
+  'SafeMembershipData'
+);
+
+/** A pending UMS spend grant awaiting a key share — mirror of the wallet's walletShareRequests[]. */
+export const SafeShareRequest = t.type(
+  {
+    userId: t.string,
+    permissions: t.array(SafePermission),
+    createdAt: DateFromISOString,
+  },
+  'SafeShareRequest'
+);
+
+export const SafeFreeze = t.partial(
+  {
+    time: DateFromISOString,
+    expires: DateFromISOString,
+    reason: t.string,
+  },
+  'SafeFreeze'
+);
+
+export const SafeStatus = t.keyof(
+  {
+    initializing: null,
+    active: null,
+    archived: null,
+  },
+  'SafeStatus'
+);
+
+export const SafeData = t.intersection(
+  [
+    t.type({
+      id: t.string,
+      enterpriseId: t.string,
+      label: t.string,
+      status: SafeStatus,
+      creator: t.string,
+      users: t.array(SafeMembershipData),
+      createdAt: DateFromISOString,
+    }),
+    t.partial({
+      safeShareRequests: t.array(SafeShareRequest),
+      freeze: SafeFreeze,
+      rootKeys: SafeRootKeys,
+      archivedAt: DateFromISOString,
+    }),
+  ],
+  'SafeData'
+);
+
+/** Safe key-share states — identical to WalletShare states, no new states. */
+export const SafeShareState = t.keyof(
+  {
+    pendingapproval: null,
+    active: null,
+    accepted: null,
+    canceled: null,
+    rejected: null,
+  },
+  'SafeShareState'
+);
+
+/** One of the 4 root USER keyshares carried on a SafeShare, ECDH-re-encrypted to the recipient. */
+export const SafeShareKeychain = t.type(
+  {
+    rootKeyType: RootKeyType,
+    rootKeyId: t.string,
+    encryptedPrv: t.string,
+    publicIdentifier: t.string,
+    fromPubKey: t.string,
+    toPubKey: t.string,
+    path: t.string,
+  },
+  'SafeShareKeychain'
+);
+
+export const SafeShareData = t.intersection(
+  [
+    t.type({
+      id: t.string,
+      enterpriseId: t.string,
+      safeId: t.string,
+      fromUser: t.string,
+      toUser: t.string,
+      permissions: t.array(SafePermission),
+      state: SafeShareState,
+      createdAt: DateFromISOString,
+    }),
+    t.partial({
+      safeLabel: t.string,
+      message: t.string,
+      pendingApprovalId: t.string,
+      isUMSInitiated: t.boolean,
+      keychains: t.array(SafeShareKeychain),
+      updatedAt: DateFromISOString,
+    }),
+  ],
+  'SafeShareData'
+);
+
+// ---- request bodies ----
+
+/** POST /enterprise/:eId/safes — Phase 1 carries no key material. */
+export const InitializeSafeBody = t.type({ label: t.string }, 'InitializeSafeBody');
+
+/** POST /enterprise/:eId/safes/:safeId/finalize — the 12 key ids as 4 ordered triplets. */
+export const FinalizeSafeBody = t.type({ rootKeys: SafeRootKeys }, 'FinalizeSafeBody');
+
+/** POST /enterprise/:eId/safes/:safeId/freeze */
+export const FreezeSafeBody = t.partial({ duration: t.number }, 'FreezeSafeBody');

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

@@ -0,0 +1,102 @@
+/**
+ * @prettier
+ *
+ * @experimental The safe 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 SafeCodecs from './codecs';
+
+// ---- data shapes (derived from the io-ts codecs in ./codecs — single source of truth) ----
+
+export type RootKeyType = t.TypeOf<typeof SafeCodecs.RootKeyType>;
+export type SafePermission = t.TypeOf<typeof SafeCodecs.SafePermission>;
+export type SafeCustodyType = t.TypeOf<typeof SafeCodecs.SafeCustodyType>;
+export type RootKeysByType = t.TypeOf<typeof SafeCodecs.RootKeysByType>;
+export type SafeRootKeys = t.TypeOf<typeof SafeCodecs.SafeRootKeys>;
+export type SafeMembershipData = t.TypeOf<typeof SafeCodecs.SafeMembershipData>;
+export type SafeShareRequest = t.TypeOf<typeof SafeCodecs.SafeShareRequest>;
+export type SafeData = t.TypeOf<typeof SafeCodecs.SafeData>;
+export type SafeShareState = t.TypeOf<typeof SafeCodecs.SafeShareState>;
+export type SafeShareKeychain = t.TypeOf<typeof SafeCodecs.SafeShareKeychain>;
+export type SafeShareData = t.TypeOf<typeof SafeCodecs.SafeShareData>;
+
+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?: FreezeOptions): Promise<SafeData>;
+  archive(): Promise<SafeData>;
+  toJSON(): SafeData;
+}