feat(script): improve upgrade-wallet-encryption robustness

WCN-174
- Fail early for MPCv2 wallets when --boxA/--boxB not provided to avoid generating incomplete keycards
- Handle already-unlocked session gracefully instead of crashing
- Strip whitespace from box values to handle PDF line-wrapped JSON
- Clarify --accessToken must be a session token from login, not a UI OAuth token

TICKET: WCN-174

Author: pranavjain97

scripts/upgrade-wallet-encryption.ts

@@ -8,16 +8,17 @@
  *     --coin tbtc \
  *     --walletId <walletId> \
  *     --passphrase <walletPassphrase> \
- *     --accessToken <bearerToken> \
+ *     --accessToken <sessionToken> \
  *     [--otp <code>] \
  *     [--boxD <ciphertext>] \
  *     [--boxA <ciphertext>] \
  *     [--boxB <ciphertext>] \
  *     [--passcodeEncryptionCode <code>] \
  *     [--dry-run]
  *
- * --accessToken: Short-lived BitGo access token. Generate this using the following guide
- *                https://developers.bitgo.com/docs/get-started-access-tokens#1-create-short-lived-access-token
+ * --accessToken: A session token obtained by logging in via the BitGo API (POST /api/v2/user/login).
+ *                Note: UI-generated OAuth access tokens lack the scope for the passcoderecovery endpoint.
+ *                Use a session token from login instead.
  * --boxD: Box D from the original keycard. Required if the wallet passphrase has been changed since the
  *         wallet was created (i.e. the current passphrase is not the original one used at creation time).
  * --boxA: Box A from the original keycard. Required for MPCv2 wallets — reducedEncryptedPrv is never stored
@@ -155,11 +156,11 @@ function parseArgs() {
     .option('coin', { type: 'string', demandOption: true, description: 'Coin ticker (e.g. tbtc, teth)' })
     .option('walletId', { type: 'string', demandOption: true, description: 'Wallet ID' })
     .option('passphrase', { type: 'string', demandOption: true, description: 'Current wallet passphrase' })
-    .option('accessToken', { type: 'string', demandOption: true, description: 'Short-lived BitGo access token' })
+    .option('accessToken', { type: 'string', demandOption: true, description: 'Session token from POST /api/v2/user/login' })
     .option('otp', { type: 'string', description: 'OTP for session unlock' })
-    .option('boxD', { type: 'string', description: 'Box D ciphertext from the original keycard' })
-    .option('boxA', { type: 'string', description: 'Box A ciphertext from the original keycard (MPCv2)' })
-    .option('boxB', { type: 'string', description: 'Box B ciphertext from the original keycard' })
+    .option('boxD', { type: 'string', description: 'Box D ciphertext from the original keycard', coerce: (v: string) => v?.replace(/\s/g, '') })
+    .option('boxA', { type: 'string', description: 'Box A ciphertext from the original keycard (MPCv2)', coerce: (v: string) => v?.replace(/\s/g, '') })
+    .option('boxB', { type: 'string', description: 'Box B ciphertext from the original keycard', coerce: (v: string) => v?.replace(/\s/g, '') })
     .option('passcodeEncryptionCode', {
       type: 'string',
       description: 'Passcode encryption code (fetched automatically if omitted)',
@@ -204,16 +205,33 @@ async function main() {
   if (dryRun) console.log('[dry-run] No changes will be persisted.');
 
   const bitgo = new BitGo({ env });
+
   bitgo.authenticateWithAccessToken({ accessToken });
 
   if (!dryRun) {
-    await bitgo.unlock({ otp: otp ?? '0000000', duration: 600 });
-    console.log('Session unlocked.');
+    try {
+      await bitgo.unlock({ otp: otp ?? '0000000', duration: 600 });
+      console.log('Session unlocked.');
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('already unlocked longer')) {
+        console.log('Session already unlocked (longer duration) — proceeding.');
+      } else {
+        throw err;
+      }
+    }
   }
 
   const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });
   console.log(`Wallet: ${wallet.label()} (${walletId})`);
 
+  if (wallet.multisigTypeVersion() === 'MPCv2' && (!boxA || !boxB)) {
+    throw new Error(
+      'This is an MPCv2 wallet. --boxA and --boxB are required to re-encrypt the reducedEncryptedPrv ' +
+        'key shares stored on the keycard. Without them the new keycard will be missing Box A and Box B.'
+    );
+  }
+
   // Fetch passcodeEncryptionCode — needed to decrypt Box D (when provided) and to generate Box D
   // in the new keycard. Always fetched when boxD is provided; otherwise skipped in dry-run.
   const needsPec = boxD || !dryRun;