@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.14.5

package/out/src/WalletAuthenticationManager.js

@@ -3,12 +3,170 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WalletAuthenticationManager = exports.WABAccountContinuityError = void 0;
 const CWIStyleWalletManager_1 = require("./CWIStyleWalletManager");
 const sdk_1 = require("@bsv/sdk");
+const utils_1 = require("@bsv/sdk/primitives/utils");
 const WABTransport_1 = require("./wab-client/WABTransport");
+const WABResponseValidation_1 = require("./wab-client/WABResponseValidation");
+const ScriptTemplateBRC29_1 = require("./utility/ScriptTemplateBRC29");
+const generateChange_1 = require("./storage/methods/generateChange");
 const DEFAULT_AUTH_SESSION_TTL_MS = 10 * 60 * 1000;
 const MAX_AUTH_SESSION_TTL_MS = 60 * 60 * 1000;
+const AUTH_COMPONENT = 'wallet-toolbox.authentication-manager';
+const AUTH_EVENT = 'wallet-toolbox.authentication.';
+const EXISTING_USER = 'existing-user';
+const NEW_USER = 'new-user';
+const PENDING_REGISTRATION = 'pending';
+const WAB_FAUCET_RECOVERY_BASKET = 'wab faucet recovery';
+const WAB_FAUCET_RECOVERY_VERSION = 1;
+const MAX_WAB_FAUCET_RECOVERY_BEEF_BYTES = 16 * 1024 * 1024;
+function parseFaucetRecoveryInstructions(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 2048)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    if (record.version !== WAB_FAUCET_RECOVERY_VERSION ||
+        typeof record.faucetOutpoint !== 'string' ||
+        !/^[0-9a-f]{64}\.(?:0|[1-9]\d*)$/i.test(record.faucetOutpoint) ||
+        typeof record.derivationPrefix !== 'string' ||
+        typeof record.derivationSuffix !== 'string' ||
+        typeof record.senderIdentityKey !== 'string') {
+        return undefined;
+    }
+    try {
+        const prefix = (0, utils_1.toArray)(record.derivationPrefix, 'base64');
+        const suffix = (0, utils_1.toArray)(record.derivationSuffix, 'base64');
+        if (prefix.length === 0 ||
+            prefix.length > 64 ||
+            suffix.length === 0 ||
+            suffix.length > 64 ||
+            (0, utils_1.toBase64)(prefix) !== record.derivationPrefix ||
+            (0, utils_1.toBase64)(suffix) !== record.derivationSuffix ||
+            sdk_1.PublicKey.fromString(record.senderIdentityKey).toString() !== record.senderIdentityKey) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return record;
+}
+function transactionInputOutpoint(transaction, inputIndex) {
+    const input = transaction.inputs[inputIndex];
+    if (input == null || !Number.isSafeInteger(input.sourceOutputIndex) || input.sourceOutputIndex < 0)
+        return undefined;
+    const sourceTxid = input.sourceTXID ?? input.sourceTransaction?.id('hex');
+    if (sourceTxid == null || !/^[0-9a-f]{64}$/i.test(sourceTxid))
+        return undefined;
+    return `${sourceTxid.toLowerCase()}.${input.sourceOutputIndex}`;
+}
+async function recoverWABFaucetPayment(wallet, faucetOutpoint, adminOriginator, resumeNosend = true) {
+    const label = `wab faucet ${faucetOutpoint.slice(0, 64)}`;
+    const listed = await wallet.listOutputs({
+        basket: WAB_FAUCET_RECOVERY_BASKET,
+        include: 'entire transactions',
+        includeCustomInstructions: true,
+        limit: 100
+    }, adminOriginator);
+    if (!Array.isArray(listed.outputs))
+        throw new Error('Wallet returned invalid faucet recovery outputs.');
+    const candidates = listed.outputs.flatMap(output => {
+        const instructions = parseFaucetRecoveryInstructions(output.customInstructions);
+        return instructions?.faucetOutpoint.toLowerCase() === faucetOutpoint ? [{ output, instructions }] : [];
+    });
+    if (candidates.length > 1)
+        throw new Error('Wallet returned ambiguous faucet recovery outputs.');
+    if (candidates.length === 1) {
+        if (!Array.isArray(listed.BEEF) ||
+            listed.BEEF.length === 0 ||
+            listed.BEEF.length > MAX_WAB_FAUCET_RECOVERY_BEEF_BYTES) {
+            throw new Error('Wallet omitted bounded faucet recovery transaction evidence.');
+        }
+        const { output, instructions } = candidates[0];
+        const match = /^([0-9a-f]{64})\.(0|[1-9]\d*)$/i.exec(output.outpoint);
+        if (match == null)
+            throw new Error('Wallet returned an invalid faucet recovery outpoint.');
+        const outputIndex = Number(match[2]);
+        if (!Number.isSafeInteger(outputIndex) || outputIndex > 0xffffffff) {
+            throw new Error('Wallet returned an invalid faucet recovery output index.');
+        }
+        const beef = sdk_1.Beef.fromBinaryStrict(listed.BEEF);
+        const transaction = beef.findTxid(match[1].toLowerCase())?.tx;
+        const transactionOutput = transaction?.outputs[outputIndex];
+        if (transaction == null ||
+            transactionOutput == null ||
+            transactionOutput.satoshis !== output.satoshis ||
+            transaction.inputs.filter((_, index) => transactionInputOutpoint(transaction, index) === faucetOutpoint)
+                .length !== 1) {
+            throw new Error('Wallet returned unrelated faucet recovery transaction evidence.');
+        }
+        const result = await wallet.internalizeAction({
+            tx: beef.toBinaryAtomic(transaction.id('hex')),
+            outputs: [
+                {
+                    outputIndex,
+                    protocol: 'wallet payment',
+                    paymentRemittance: {
+                        derivationPrefix: instructions.derivationPrefix,
+                        derivationSuffix: instructions.derivationSuffix,
+                        senderIdentityKey: instructions.senderIdentityKey
+                    }
+                }
+            ],
+            description: 'Recover WAB faucet funding'
+        }, adminOriginator);
+        if (result.accepted !== true)
+            throw new Error('Wallet did not accept its recovered WAB faucet payment.');
+        return true;
+    }
+    const actions = await wallet.listActions({
+        labels: [label],
+        includeLabels: true,
+        includeInputs: true,
+        includeOutputs: true,
+        includeOutputLockingScripts: true,
+        limit: 10
+    }, adminOriginator);
+    if (!Array.isArray(actions.actions))
+        throw new Error('Wallet returned invalid faucet recovery actions.');
+    const matchingActions = actions.actions.filter(action => action.labels?.includes(label));
+    if (matchingActions.length === 0)
+        return false;
+    if (matchingActions.length !== 1)
+        throw new Error('Wallet returned ambiguous faucet recovery actions.');
+    const action = matchingActions[0];
+    const matchingInputs = action.inputs?.filter(input => input.sourceOutpoint.toLowerCase() === faucetOutpoint) ?? [];
+    const matchingOutputs = action.outputs?.filter(output => {
+        const instructions = parseFaucetRecoveryInstructions(output.customInstructions);
+        return instructions?.faucetOutpoint.toLowerCase() === faucetOutpoint;
+    }) ?? [];
+    if (matchingInputs.length !== 1 || matchingOutputs.length !== 1) {
+        throw new Error('Wallet returned unrelated faucet recovery action evidence.');
+    }
+    if ((action.status === 'completed' || action.status === 'sending' || action.status === 'unproven') &&
+        matchingOutputs[0].basket === 'default') {
+        return true;
+    }
+    if (action.status === 'nosend') {
+        if (!resumeNosend)
+            throw new Error('Prior WAB faucet action remained unsent after broadcast retry.');
+        await wallet.createAction({
+            description: 'Resume WAB faucet broadcast',
+            options: { sendWith: [action.txid], acceptDelayedBroadcast: false }
+        }, adminOriginator);
+        return await recoverWABFaucetPayment(wallet, faucetOutpoint, adminOriginator, false);
+    }
+    throw new Error('Prior WAB faucet action requires reconciliation before retrying.');
+}
 class WABAccountContinuityError extends Error {
     code = 'WERR_WAB_ACCOUNT_CONTINUITY';
-    constructor(message = 'WAB and UMP account state did not agree. Retry or use account recovery.') {
+    constructor(message = 'WAB and UMP accounts disagree; retry or recover.') {
         super(message);
         this.name = 'WABAccountContinuityError';
     }
@@ -24,12 +182,14 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
     wabClient; // instance of WABClient
     authMethod; // chosen AuthMethod interactor
     authSession;
+    phoneChangeSession;
+    pendingRegistrationPresentationKey;
     authSessionTtlMs;
     constructor(...[adminOriginator, walletBuilder, interactor, recoveryKeySaver, passwordRetriever, wabClient, authMethod, stateSnapshot, options = {}]) {
         super(adminOriginator, walletBuilder, interactor, recoveryKeySaver, passwordRetriever, 
         // Here, we provide a custom new wallet funder that uses the Secret Server
         async (presentationKey, wallet, adminOriginator) => {
-            const faucetResponse = await this.wabClient.requestFaucet(sdk_1.Utils.toHex(presentationKey));
+            const faucetResponse = await this.wabClient.requestFaucet((0, utils_1.toHex)(presentationKey));
             const paymentData = faucetResponse.paymentData;
             const faucetSucceeded = faucetResponse.success;
             if (faucetSucceeded !== true || paymentData == null) {
@@ -47,37 +207,139 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
                 throw new Error('Faucet response missing required fields: k, tx, or txid');
             }
             try {
+                if (!/^[0-9a-f]{64}$/i.test(paymentData.txid)) {
+                    throw new Error('Faucet transaction ID is invalid.');
+                }
+                if (!/^[0-9a-f]{1,64}$/i.test(paymentData.k)) {
+                    throw new Error('Faucet R-puzzle scalar is invalid.');
+                }
+                const faucetK = new sdk_1.PrivateKey(paymentData.k, 16, 'be', 'error');
+                if (faucetK.isZero()) {
+                    throw new Error('Faucet R-puzzle scalar is invalid.');
+                }
                 const tx = sdk_1.Transaction.fromAtomicBEEF(paymentData.tx);
-                const faucetRedeemTXCreationResult = await wallet.createAction({
+                const txid = tx.id('hex');
+                if (txid !== paymentData.txid.toLowerCase()) {
+                    throw new Error('Faucet transaction ID does not match its transaction data.');
+                }
+                const faucetOutput = tx.outputs[0];
+                if (faucetOutput == null) {
+                    throw new Error('Faucet transaction output 0 is missing.');
+                }
+                const faucetSatoshis = faucetOutput.satoshis;
+                if (typeof faucetSatoshis !== 'number' ||
+                    !Number.isSafeInteger(faucetSatoshis) ||
+                    faucetSatoshis <= 0 ||
+                    faucetSatoshis > 21e14) {
+                    throw new Error('Faucet transaction output 0 has an invalid amount.');
+                }
+                let rValue = faucetK.toPublicKey().getX().toArray();
+                if (rValue[0] > 127)
+                    rValue = [0, ...rValue];
+                const faucetRedemptionPuzzle = new sdk_1.RPuzzle();
+                if (faucetOutput.lockingScript.toHex() !== faucetRedemptionPuzzle.lock(rValue).toHex()) {
+                    throw new Error('Faucet transaction output 0 does not match its R-puzzle scalar.');
+                }
+                const randomRedemptionPrivateKey = sdk_1.PrivateKey.fromRandom();
+                const faucetRedeemUnlocker = faucetRedemptionPuzzle.unlock(faucetK, randomRedemptionPrivateKey);
+                const outpoint = `${txid}.0`;
+                if (paymentData.outputIndex !== undefined && paymentData.outputIndex !== 0) {
+                    throw new Error('Faucet response output index does not match output 0.');
+                }
+                if (paymentData.amount !== undefined && paymentData.amount !== faucetSatoshis) {
+                    throw new Error('Faucet response amount does not match output 0.');
+                }
+                if (await recoverWABFaucetPayment(wallet, outpoint, adminOriginator))
+                    return;
+                const identityResult = await wallet.getPublicKey({ identityKey: true }, adminOriginator);
+                const identityKey = sdk_1.PublicKey.fromString(identityResult.publicKey).toString();
+                const paymentSender = sdk_1.PrivateKey.fromRandom();
+                const derivationPrefix = (0, utils_1.toBase64)((0, sdk_1.Random)(16));
+                const derivationSuffix = (0, utils_1.toBase64)((0, sdk_1.Random)(16));
+                const paymentTemplate = new ScriptTemplateBRC29_1.ScriptTemplateBRC29({
+                    derivationPrefix,
+                    derivationSuffix,
+                    keyDeriver: new sdk_1.CachedKeyDeriver(paymentSender)
+                });
+                const paymentLock = paymentTemplate.lock(paymentSender.toString(), identityKey).toHex();
+                const recoveryInstructions = JSON.stringify({
+                    version: 1,
+                    faucetOutpoint: outpoint,
+                    derivationPrefix,
+                    derivationSuffix,
+                    senderIdentityKey: paymentSender.toPublicKey().toString()
+                });
+                const signed = await (0, sdk_1.completeBoundAction)(wallet, {
                     inputBEEF: tx.toBEEF(),
                     inputs: [
                         {
-                            outpoint: `${paymentData.txid}.0`,
+                            outpoint,
                             unlockingScriptLength: 108,
                             inputDescription: 'Fund from faucet'
                         }
                     ],
+                    outputs: [
+                        {
+                            lockingScript: paymentLock,
+                            satoshis: generateChange_1.maxPossibleSatoshis,
+                            outputDescription: 'Receive WAB faucet funds',
+                            basket: 'wab faucet recovery',
+                            customInstructions: recoveryInstructions
+                        }
+                    ],
+                    labels: [`wab faucet ${txid}`],
                     description: 'Fund wallet',
                     options: {
-                        acceptDelayedBroadcast: false
+                        acceptDelayedBroadcast: false,
+                        noSend: true,
+                        randomizeOutputs: false
                     }
-                }, adminOriginator);
-                if (faucetRedeemTXCreationResult.signableTransaction == null) {
-                    throw new Error('Faucet redemption did not return a signableTransaction');
-                }
-                const faucetRedeemTX = sdk_1.Transaction.fromAtomicBEEF(faucetRedeemTXCreationResult.signableTransaction.tx);
-                const faucetRedemptionPuzzle = new sdk_1.RPuzzle();
-                const randomRedemptionPrivateKey = sdk_1.PrivateKey.fromRandom();
-                const faucetRedeemUnlocker = faucetRedemptionPuzzle.unlock(new sdk_1.BigNumber(paymentData.k, 16), randomRedemptionPrivateKey);
-                const faucetRedeemUnlockingScript = await faucetRedeemUnlocker.sign(faucetRedeemTX, 0);
-                await wallet.signAction({
-                    reference: faucetRedeemTXCreationResult.signableTransaction.reference,
-                    spends: {
+                }, {
+                    inputSigners: {
+                        [outpoint]: async (transaction, inputIndex) => await faucetRedeemUnlocker.sign(transaction, inputIndex)
+                    },
+                    outputSatoshisRanges: {
                         0: {
-                            unlockingScript: faucetRedeemUnlockingScript.toHex()
+                            minimumSatoshis: 1,
+                            maximumSatoshis: faucetSatoshis
                         }
                     }
+                }, adminOriginator);
+                const matches = signed.outputs.flatMap((output, outputIndex) => {
+                    const outputSatoshis = output.satoshis;
+                    return output.lockingScript.toHex() === paymentLock &&
+                        typeof outputSatoshis === 'number' &&
+                        outputSatoshis >= 1 &&
+                        outputSatoshis <= faucetSatoshis
+                        ? [outputIndex]
+                        : [];
                 });
+                if (matches.length !== 1) {
+                    throw new Error('Faucet redemption omitted or duplicated its wallet-owned output.');
+                }
+                const redemptionTxid = signed.id('hex');
+                await wallet.createAction({
+                    description: 'Broadcast WAB faucet funding',
+                    options: { sendWith: [redemptionTxid], acceptDelayedBroadcast: false }
+                }, adminOriginator);
+                const internalized = await wallet.internalizeAction({
+                    tx: signed.toAtomicBEEF(),
+                    outputs: [
+                        {
+                            outputIndex: matches[0],
+                            protocol: 'wallet payment',
+                            paymentRemittance: {
+                                derivationPrefix,
+                                derivationSuffix,
+                                senderIdentityKey: paymentSender.toPublicKey().toString()
+                            }
+                        }
+                    ],
+                    description: 'Receive WAB faucet funding'
+                }, adminOriginator);
+                if (internalized.accepted !== true) {
+                    throw new Error('Wallet did not accept its WAB faucet payment.');
+                }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -87,9 +349,7 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
         this.wabClient = wabClient;
         this.authMethod = authMethod;
         const authSessionTtlMs = options.authSessionTtlMs ?? DEFAULT_AUTH_SESSION_TTL_MS;
-        if (!Number.isInteger(authSessionTtlMs) ||
-            authSessionTtlMs <= 0 ||
-            authSessionTtlMs > MAX_AUTH_SESSION_TTL_MS) {
+        if (!Number.isInteger(authSessionTtlMs) || authSessionTtlMs <= 0 || authSessionTtlMs > MAX_AUTH_SESSION_TTL_MS) {
             throw new TypeError(`authSessionTtlMs must be between 1 and ${MAX_AUTH_SESSION_TTL_MS}.`);
         }
         this.authSessionTtlMs = authSessionTtlMs;
@@ -109,12 +369,13 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
      */
     async startAuth(payload) {
         if (this.authMethod == null) {
-            throw new Error('No AuthMethod selected in WalletAuthenticationManager');
+            throw new Error('No WAB authentication method selected.');
         }
         const authMethod = this.authMethod;
         if (this.authenticated)
             throw new Error('User is already authenticated');
         this.cancelAuth();
+        this.pendingRegistrationPresentationKey = undefined;
         const presentationKey = this.generateTemporaryPresentationKey();
         const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : undefined;
         this.authSession = {
@@ -124,8 +385,8 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
             ...(correlationId !== undefined ? { correlationId } : {})
         };
         this.telemetry.capture({
-            name: 'wallet-toolbox.authentication.wab-start.started',
-            component: 'wallet-toolbox.authentication-manager',
+            name: `${AUTH_EVENT}wab-start.started`,
+            component: AUTH_COMPONENT,
             severity: 'debug',
             correlationId,
             attributes: { methodType: authMethod.methodType }
@@ -134,14 +395,12 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
             const startRes = await this.wabClient.startAuthMethod(authMethod, presentationKey, payload, correlationId);
             const startSucceeded = startRes.success;
             if (startSucceeded !== true) {
-                const message = startRes.message != null && startRes.message.length > 0
-                    ? startRes.message
-                    : 'Failed to start WAB auth method';
+                const message = startRes.message != null && startRes.message.length > 0 ? startRes.message : 'Failed to start WAB auth method';
                 throw new Error(message);
             }
             this.telemetry.capture({
-                name: 'wallet-toolbox.authentication.wab-start.completed',
-                component: 'wallet-toolbox.authentication-manager',
+                name: `${AUTH_EVENT}wab-start.completed`,
+                component: AUTH_COMPONENT,
                 severity: 'info',
                 correlationId,
                 attributes: { methodType: authMethod.methodType }
@@ -150,14 +409,12 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
         catch (error) {
             this.cancelAuth();
             this.telemetry.capture({
-                name: 'wallet-toolbox.authentication.wab-start.failed',
-                component: 'wallet-toolbox.authentication-manager',
+                name: `${AUTH_EVENT}wab-start.failed`,
+                component: AUTH_COMPONENT,
                 severity: 'warn',
                 correlationId,
                 attributes: { methodType: authMethod.methodType },
-                error: error instanceof WABTransport_1.WABClientError
-                    ? error
-                    : new Error('WAB authentication start failed.')
+                error: error instanceof WABTransport_1.WABClientError ? error : new Error('WAB authentication start failed.')
             });
             throw error;
         }
@@ -167,31 +424,29 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
      */
     async completeAuth(payload) {
         if (this.authMethod == null || this.authSession == null) {
-            throw new Error('No AuthMethod selected in WalletAuthenticationManager or startAuth has yet to be called.');
+            throw new Error('Start WAB authentication first.');
         }
         const authMethod = this.authMethod;
         if (this.authSession.methodType !== authMethod.methodType) {
             this.cancelAuth();
-            throw new Error('The selected authentication method changed. Start authentication again.');
+            throw new Error('WAB authentication method changed; restart.');
         }
         if (Date.now() >= this.authSession.expiresAt) {
             this.cancelAuth();
-            throw new Error('The WAB authentication session expired. Start authentication again.');
+            throw new Error('WAB authentication expired; restart.');
         }
         const session = this.authSession;
         const result = await this.wabClient.completeAuthMethod(authMethod, session.presentationKey, payload, session.correlationId);
         const authSucceeded = result.success;
         if (authSucceeded !== true || result.presentationKey == null || result.presentationKey.length === 0) {
             this.telemetry.capture({
-                name: 'wallet-toolbox.authentication.wab-complete.rejected',
-                component: 'wallet-toolbox.authentication-manager',
+                name: `${AUTH_EVENT}wab-complete.rejected`,
+                component: AUTH_COMPONENT,
                 severity: 'warn',
                 correlationId: session.correlationId,
                 attributes: { methodType: session.methodType }
             });
-            const message = result.message != null && result.message.length > 0
-                ? result.message
-                : 'Failed to complete WAB auth';
+            const message = result.message != null && result.message.length > 0 ? result.message : 'Failed to complete WAB auth';
             throw new Error(message);
         }
         if (!/^[0-9a-fA-F]{64}$/.test(result.presentationKey)) {
@@ -200,13 +455,14 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
         }
         this.cancelAuth();
         const wabAccountStatus = this.inferAccountStatus(result, session.presentationKey);
+        const registrationStatus = this.readRegistrationStatus(result);
         try {
-            await this.providePresentationKey(sdk_1.Utils.toArray(result.presentationKey, 'hex'));
+            await this.provideWABPresentationKey(result, wabAccountStatus);
         }
         catch (error) {
             this.telemetry.capture({
-                name: 'wallet-toolbox.authentication.ump-continuity.failed',
-                component: 'wallet-toolbox.authentication-manager',
+                name: `${AUTH_EVENT}ump-continuity.failed`,
+                component: AUTH_COMPONENT,
                 severity: 'warn',
                 correlationId: session.correlationId,
                 attributes: {
@@ -217,27 +473,12 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
             });
             throw error;
         }
-        if (wabAccountStatus === 'existing-user' && this.authenticationFlow !== 'existing-user') {
-            super.destroy();
-            const error = new WABAccountContinuityError();
-            this.telemetry.capture({
-                name: 'wallet-toolbox.authentication.account-continuity.mismatch',
-                component: 'wallet-toolbox.authentication-manager',
-                severity: 'error',
-                correlationId: session.correlationId,
-                attributes: {
-                    methodType: session.methodType,
-                    wabAccountStatus,
-                    umpAccountStatus: 'new-user'
-                },
-                error
-            });
-            throw error;
-        }
-        const continuity = wabAccountStatus === this.authenticationFlow ? 'matched' : 'ump-existing';
+        this.assertAccountContinuity(wabAccountStatus, registrationStatus, session);
+        await this.reconcilePendingRegistration(result, registrationStatus);
+        const continuity = this.describeContinuity(wabAccountStatus, registrationStatus);
         this.telemetry.capture({
-            name: 'wallet-toolbox.authentication.completed',
-            component: 'wallet-toolbox.authentication-manager',
+            name: `${AUTH_EVENT}completed`,
+            component: AUTH_COMPONENT,
             severity: continuity === 'matched' ? 'info' : 'warn',
             correlationId: session.correlationId,
             attributes: {
@@ -251,40 +492,252 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
     cancelAuth() {
         this.authSession = undefined;
     }
+    /**
+     * Publishes a new UMP token before committing WAB's registration state.
+     * Finalization is deliberately best-effort: if its response is lost, the
+     * next verified login finds the UMP token and repairs WAB idempotently.
+     */
+    async providePassword(password) {
+        const shouldFinalize = this.pendingRegistrationPresentationKey != null && this.authenticationFlow === NEW_USER;
+        await super.providePassword(password);
+        if (shouldFinalize)
+            await this.finalizePendingRegistration();
+    }
+    readRegistrationStatus(result) {
+        const status = result.registrationStatus;
+        if (status === undefined)
+            return 'active';
+        if (status !== 'pending' && status !== 'active') {
+            throw new WABAccountContinuityError('WAB returned an invalid registration status.');
+        }
+        return status;
+    }
+    assertAccountContinuity(wabAccountStatus, registrationStatus, session) {
+        const mismatch = wabAccountStatus === EXISTING_USER && this.authenticationFlow !== EXISTING_USER;
+        if (!mismatch || registrationStatus === PENDING_REGISTRATION)
+            return;
+        super.destroy();
+        const error = new WABAccountContinuityError();
+        this.telemetry.capture({
+            name: `${AUTH_EVENT}account-continuity.mismatch`,
+            component: AUTH_COMPONENT,
+            severity: 'error',
+            correlationId: session.correlationId,
+            attributes: {
+                methodType: session.methodType,
+                wabAccountStatus,
+                umpAccountStatus: NEW_USER
+            },
+            error
+        });
+        throw error;
+    }
+    async reconcilePendingRegistration(result, registrationStatus) {
+        if (registrationStatus !== PENDING_REGISTRATION)
+            return;
+        this.pendingRegistrationPresentationKey = result.presentationKey;
+        if (this.authenticationFlow === EXISTING_USER)
+            await this.finalizePendingRegistration();
+    }
+    describeContinuity(wabAccountStatus, registrationStatus) {
+        if (registrationStatus === PENDING_REGISTRATION && this.authenticationFlow === NEW_USER) {
+            return 'registration-resumed';
+        }
+        if (wabAccountStatus === this.authenticationFlow)
+            return 'matched';
+        return 'ump-existing';
+    }
+    async finalizePendingRegistration() {
+        const presentationKey = this.pendingRegistrationPresentationKey;
+        if (presentationKey == null)
+            return;
+        try {
+            const result = await this.wabClient.finalizeRegistration(presentationKey);
+            if (result.success !== true || result.registrationStatus !== 'active') {
+                throw new Error(result.message || 'WAB registration finalization was not acknowledged.');
+            }
+            this.pendingRegistrationPresentationKey = undefined;
+            this.telemetry.capture({
+                name: `${AUTH_EVENT}registration-finalize.completed`,
+                component: AUTH_COMPONENT,
+                severity: 'info'
+            });
+        }
+        catch (error) {
+            this.telemetry.capture({
+                name: `${AUTH_EVENT}registration-finalize.deferred`,
+                component: AUTH_COMPONENT,
+                severity: 'warn',
+                error: new Error('WAB registration finalization was deferred.', { cause: error })
+            });
+        }
+    }
+    readPendingPhoneChange(result) {
+        const presentationKey = result.pendingPresentationKey;
+        const changeId = result.pendingPhoneChangeId;
+        if (presentationKey === undefined && changeId === undefined)
+            return undefined;
+        if (!/^[0-9a-fA-F]{64}$/.test(presentationKey ?? '') || !Number.isSafeInteger(changeId) || changeId <= 0) {
+            throw new WABAccountContinuityError('WAB returned invalid pending phone-change data.');
+        }
+        return { presentationKey: presentationKey, changeId: changeId };
+    }
+    async provideWABPresentationKey(result, wabAccountStatus) {
+        const umpTokenOutpoint = typeof result.umpTokenOutpoint === 'string' ? result.umpTokenOutpoint : undefined;
+        const lookupOptions = umpTokenOutpoint == null ? undefined : { pinnedOutpoint: umpTokenOutpoint };
+        const pending = this.readPendingPhoneChange(result);
+        let usePending = false;
+        try {
+            await this.providePresentationKey((0, utils_1.toArray)(result.presentationKey, 'hex'), lookupOptions);
+        }
+        catch (error) {
+            if (pending == null)
+                throw error;
+            usePending = true;
+        }
+        if (pending != null &&
+            (usePending || (wabAccountStatus === EXISTING_USER && this.authenticationFlow !== EXISTING_USER))) {
+            await this.providePresentationKey((0, utils_1.toArray)(pending.presentationKey, 'hex'), lookupOptions);
+            if (this.authenticationFlow === EXISTING_USER) {
+                await this.finalizePendingPhoneChange(result.presentationKey, pending);
+            }
+        }
+    }
+    async finalizePendingPhoneChange(currentPresentationKey, pending) {
+        const finalized = await this.phoneChange('finalize', {
+            changeId: pending.changeId,
+            presentationKey: currentPresentationKey,
+            newPresentationKey: pending.presentationKey
+        });
+        if (finalized.success !== true || finalized.changeId !== pending.changeId) {
+            throw new WABAccountContinuityError(finalized.message || 'WAB could not finalize the pending phone change.');
+        }
+    }
+    /**
+     * Starts OTP verification for a replacement phone number. The same number
+     * is valid and intentionally produces a fresh presentation key/hash.
+     */
+    async startPhoneNumberChange(phoneNumber) {
+        if (!this.authenticated)
+            throw new Error('Not authenticated');
+        const normalizedPhone = phoneNumber.trim();
+        const currentPresentationKey = (0, utils_1.toHex)(await this.getFactor('presentationKey'));
+        const response = await this.phoneChange('start', {
+            presentationKey: currentPresentationKey,
+            phoneNumber: normalizedPhone
+        });
+        if (response.success !== true)
+            throw new Error(response.message || 'Phone change failed');
+        this.phoneChangeSession = {
+            phoneNumber: normalizedPhone,
+            presentationKey: currentPresentationKey
+        };
+    }
+    /**
+     * Completes phone verification and stages the WAB association before
+     * publishing the UMP key rotation. WAB retains both the current and pending
+     * presentation keys until finalization, so either side of an interrupted
+     * transition remains recoverable on the next verified login.
+     */
+    async completePhoneNumberChange(otp) {
+        const session = this.phoneChangeSession;
+        if (session == null)
+            throw new Error('No phone change');
+        if (session.changeToken == null) {
+            const authorization = await this.phoneChange('complete', {
+                presentationKey: session.presentationKey,
+                phoneNumber: session.phoneNumber,
+                otp: otp.trim()
+            });
+            if (authorization.success !== true) {
+                throw new Error(authorization.message || 'Phone change failed');
+            }
+            const resumable = /^[0-9a-fA-F]{64}$/.test(authorization.pendingPresentationKey ?? '') &&
+                Number.isSafeInteger(authorization.pendingPhoneChangeId) &&
+                authorization.pendingPhoneChangeId > 0;
+            if (resumable) {
+                session.newKey = (0, utils_1.toArray)(authorization.pendingPresentationKey, 'hex');
+                session.changeId = authorization.pendingPhoneChangeId;
+            }
+            else if (typeof authorization.changeToken === 'string' && authorization.changeToken.length > 0) {
+                session.changeToken = authorization.changeToken;
+            }
+            else {
+                throw new Error(authorization.message || 'Phone change failed');
+            }
+        }
+        session.newKey ??= (0, sdk_1.Random)(32);
+        if (session.changeId == null) {
+            const committed = await this.phoneChange('commit', {
+                changeToken: session.changeToken,
+                presentationKey: session.presentationKey,
+                newPresentationKey: (0, utils_1.toHex)(session.newKey)
+            });
+            if (committed.success !== true || !Number.isSafeInteger(committed.changeId) || committed.changeId <= 0) {
+                throw new Error(committed.message || 'Phone change failed');
+            }
+            session.changeId = committed.changeId;
+        }
+        const changeId = session.changeId;
+        if (session.umpUpdated !== true) {
+            await this.changePresentationKey(session.newKey);
+            session.umpUpdated = true;
+        }
+        const finalized = await this.phoneChange('finalize', {
+            changeId,
+            presentationKey: session.presentationKey,
+            newPresentationKey: (0, utils_1.toHex)(session.newKey)
+        });
+        if (finalized.success !== true || finalized.changeId !== changeId) {
+            throw new Error(finalized.message || 'Phone change failed');
+        }
+        this.phoneChangeSession = undefined;
+        return { changeId };
+    }
+    cancelPhoneNumberChange() {
+        this.phoneChangeSession = undefined;
+    }
     destroy() {
         this.cancelAuth();
+        this.cancelPhoneNumberChange();
+        this.pendingRegistrationPresentationKey = undefined;
         super.destroy();
     }
+    async phoneChange(phase, body) {
+        const response = await this.wabClient.transport.request(`/auth/phone-change/${phase}`, {
+            operation: 'phone-change',
+            body
+        });
+        return (0, WABResponseValidation_1.validateWABOperationResponse)(response, `phone-change-${phase}`);
+    }
     inferAccountStatus(result, temporaryPresentationKey) {
         if (result.presentationKey == null) {
             throw new WABAccountContinuityError('WAB did not return a presentation key.');
         }
         const keyMatchesTemporary = this.constantTimeHexEqual(result.presentationKey, temporaryPresentationKey);
         const rawAccountStatus = result.accountStatus;
-        if (rawAccountStatus !== undefined &&
-            rawAccountStatus !== 'new-user' &&
-            rawAccountStatus !== 'existing-user') {
-            throw new WABAccountContinuityError('WAB returned an invalid account-continuity status.');
+        if (rawAccountStatus !== undefined && rawAccountStatus !== NEW_USER && rawAccountStatus !== EXISTING_USER) {
+            throw new WABAccountContinuityError('WAB returned an invalid account status.');
         }
         const rawExistingUser = result.existingUser;
         if (rawExistingUser !== undefined && typeof rawExistingUser !== 'boolean') {
-            throw new WABAccountContinuityError('WAB returned an invalid existing-user status.');
+            throw new WABAccountContinuityError('WAB returned invalid existing-user data.');
         }
         if (rawAccountStatus !== undefined &&
             rawExistingUser !== undefined &&
-            (rawAccountStatus === 'existing-user') !== rawExistingUser) {
-            throw new WABAccountContinuityError('WAB returned contradictory account-continuity statuses.');
+            (rawAccountStatus === EXISTING_USER) !== rawExistingUser) {
+            throw new WABAccountContinuityError('WAB returned conflicting account status.');
         }
         let compatibilityStatus;
         if (typeof rawExistingUser === 'boolean') {
-            compatibilityStatus = rawExistingUser ? 'existing-user' : 'new-user';
+            compatibilityStatus = rawExistingUser ? EXISTING_USER : NEW_USER;
         }
         const explicitStatus = rawAccountStatus ?? compatibilityStatus;
-        if ((explicitStatus === 'new-user' && !keyMatchesTemporary) ||
-            (explicitStatus === 'existing-user' && keyMatchesTemporary)) {
-            throw new WABAccountContinuityError('WAB returned contradictory account-continuity data.');
+        if ((explicitStatus === NEW_USER && !keyMatchesTemporary) ||
+            (explicitStatus === EXISTING_USER && keyMatchesTemporary)) {
+            throw new WABAccountContinuityError('WAB returned conflicting account status.');
         }
-        return explicitStatus ?? (keyMatchesTemporary ? 'new-user' : 'existing-user');
+        return explicitStatus ?? (keyMatchesTemporary ? NEW_USER : EXISTING_USER);
     }
     constantTimeHexEqual(left, right) {
         if (left.length !== right.length)
@@ -300,7 +753,7 @@ class WalletAuthenticationManager extends CWIStyleWalletManager_1.CWIStyleWallet
     generateTemporaryPresentationKey() {
         // For the 'startAuth' call, we can generate a random 32 bytes → 64 hex chars.
         const randomBytes = (0, sdk_1.Random)(32); // array of length 32
-        return sdk_1.Utils.toHex(randomBytes);
+        return (0, utils_1.toHex)(randomBytes);
     }
 }
 exports.WalletAuthenticationManager = WalletAuthenticationManager;