@solana-mobile/mobile-wallet-adapter-protocol 2.1.3 → 2.2.0-new-arch-beta

package/src/getAssociateAndroidIntentURL.ts

@@ -2,6 +2,7 @@ import arrayBufferToBase64String from './arrayBufferToBase64String.js';
 import { assertAssociationPort } from './associationPort.js';
 import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
 import getStringWithURLUnsafeBase64CharactersReplaced from './getStringWithURLUnsafeBase64CharactersReplaced.js';
+import { assertReflectorId } from './reflectorId.js';
 import { ProtocolVersion } from './types.js';
 
 const INTENT_NAME = 'solana-wallet';
@@ -55,3 +56,23 @@ export default async function getAssociateAndroidIntentURL(
     })
     return url;
 }
+
+export async function getRemoteAssociateAndroidIntentURL(
+    associationPublicKey: CryptoKey,
+    hostAuthority: string,
+    putativeId: number,
+    associationURLBase?: string,
+    protocolVersions: ProtocolVersion[] = ['v1'],
+): Promise<URL> {
+    const reflectorId = assertReflectorId(putativeId);
+    const exportedKey = await crypto.subtle.exportKey('raw', associationPublicKey);
+    const encodedKey = arrayBufferToBase64String(exportedKey);
+    const url = getIntentURL('v1/associate/remote', associationURLBase);
+    url.searchParams.set('association', getStringWithURLUnsafeBase64CharactersReplaced(encodedKey));
+    url.searchParams.set('reflector', `${hostAuthority}`);
+    url.searchParams.set('id', `${reflectorId}`);
+    protocolVersions.forEach( (version) => {
+        url.searchParams.set('v', version);
+    })
+    return url;
+}

package/src/reflectorId.ts

@@ -0,0 +1,31 @@
+import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
+
+declare const tag: unique symbol;
+export type ReflectorId = number & { readonly [tag]: 'ReflectorId' };
+
+export function getRandomReflectorId(): ReflectorId {
+    return assertReflectorId(getRandomInt(0, 9007199254740991)); // 0 < id < 2^53 - 1
+}
+
+function getRandomInt(min: number, max: number) {
+    const randomBuffer = new Uint32Array(1);
+
+    window.crypto.getRandomValues(randomBuffer);
+
+    let randomNumber = randomBuffer[0] / (0xffffffff + 1);
+
+    min = Math.ceil(min);
+    max = Math.floor(max);
+    return Math.floor(randomNumber * (max - min + 1)) + min;
+}
+
+export function assertReflectorId(id: number): ReflectorId {
+    if (id < 0 || id > 9007199254740991) { // 0 < id < 2^53 - 1
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_REFLECTOR_ID_OUT_OF_RANGE,
+            `Association port number must be between 49152 and 65535. ${id} given.`,
+            { id },
+        );
+    }
+    return id as ReflectorId;
+}

package/src/startSession.ts

@@ -1,94 +1,130 @@
-import { AssociationPort, getRandomAssociationPort } from './associationPort.js';
-import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
-import getAssociateAndroidIntentURL from './getAssociateAndroidIntentURL.js';
-
-// Typescript `enums` thwart tree-shaking. See https://bargsten.org/jsts/enums/
-const Browser = {
-    Firefox: 0,
-    Other: 1,
-} as const;
-type BrowserEnum = typeof Browser[keyof typeof Browser];
-
-function assertUnreachable(x: never): never {
-    return x;
-}
-
-function getBrowser(): BrowserEnum {
-    return navigator.userAgent.indexOf('Firefox/') !== -1 ? Browser.Firefox : Browser.Other;
-}
-
-function getDetectionPromise() {
-    // Chrome and others silently fail if a custom protocol is not supported.
-    // For these, we wait to see if the browser is navigated away from in
-    // a reasonable amount of time (ie. the native wallet opened).
-    return new Promise<void>((resolve, reject) => {
-        function cleanup() {
-            clearTimeout(timeoutId);
-            window.removeEventListener('blur', handleBlur);
-        }
-        function handleBlur() {
-            cleanup();
-            resolve();
-        }
-        window.addEventListener('blur', handleBlur);
-        const timeoutId = setTimeout(() => {
-            cleanup();
-            reject();
-        }, 2000);
-    });
-}
-
-let _frame: HTMLIFrameElement | null = null;
-function launchUrlThroughHiddenFrame(url: URL) {
-    if (_frame == null) {
-        _frame = document.createElement('iframe');
-        _frame.style.display = 'none';
-        document.body.appendChild(_frame);
-    }
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    _frame.contentWindow!.location.href = url.toString();
-}
-
-export async function startSession(
-    associationPublicKey: CryptoKey,
-    associationURLBase?: string,
-): Promise<AssociationPort> {
-    const randomAssociationPort = getRandomAssociationPort();
-    const associationUrl = await getAssociateAndroidIntentURL(
-        associationPublicKey,
-        randomAssociationPort,
-        associationURLBase,
-    );
-    if (associationUrl.protocol === 'https:') {
-        // The association URL is an Android 'App Link' or iOS 'Universal Link'.
-        // These are regular web URLs that are designed to launch an app if it
-        // is installed or load the actual target webpage if not.
-        window.location.assign(associationUrl);
-    } else {
-        // The association URL has a custom protocol (eg. `solana-wallet:`)
-        try {
-            const browser = getBrowser();
-            switch (browser) {
-                case Browser.Firefox:
-                    // If a custom protocol is not supported in Firefox, it throws.
-                    launchUrlThroughHiddenFrame(associationUrl);
-                    // If we reached this line, it's supported.
-                    break;
-                case Browser.Other: {
-                    const detectionPromise = getDetectionPromise();
-                    window.location.assign(associationUrl);
-                    await detectionPromise;
-                    break;
-                }
-                default:
-                    assertUnreachable(browser);
-            }
-        } catch (e) {
-            throw new SolanaMobileWalletAdapterError(
-                SolanaMobileWalletAdapterErrorCode.ERROR_WALLET_NOT_FOUND,
-                'Found no installed wallet that supports the mobile wallet protocol.',
-            );
-        }
-    }
-    return randomAssociationPort;
-}
+import { AssociationPort, getRandomAssociationPort } from './associationPort.js';
+import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
+import getAssociateAndroidIntentURL, { getRemoteAssociateAndroidIntentURL } from './getAssociateAndroidIntentURL.js';
+import { assertReflectorId, getRandomReflectorId, ReflectorId } from './reflectorId.js';
+
+// Typescript `enums` thwart tree-shaking. See https://bargsten.org/jsts/enums/
+const Browser = {
+    Firefox: 0,
+    Other: 1,
+} as const;
+type BrowserEnum = typeof Browser[keyof typeof Browser];
+
+function assertUnreachable(x: never): never {
+    return x;
+}
+
+function getBrowser(): BrowserEnum {
+    return navigator.userAgent.indexOf('Firefox/') !== -1 ? Browser.Firefox : Browser.Other;
+}
+
+function getDetectionPromise() {
+    // Chrome and others silently fail if a custom protocol is not supported.
+    // For these, we wait to see if the browser is navigated away from in
+    // a reasonable amount of time (ie. the native wallet opened).
+    return new Promise<void>((resolve, reject) => {
+        function cleanup() {
+            clearTimeout(timeoutId);
+            window.removeEventListener('blur', handleBlur);
+        }
+        function handleBlur() {
+            cleanup();
+            resolve();
+        }
+        window.addEventListener('blur', handleBlur);
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            reject();
+        }, 2000);
+    });
+}
+
+let _frame: HTMLIFrameElement | null = null;
+function launchUrlThroughHiddenFrame(url: URL) {
+    if (_frame == null) {
+        _frame = document.createElement('iframe');
+        _frame.style.display = 'none';
+        document.body.appendChild(_frame);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    _frame.contentWindow!.location.href = url.toString();
+}
+
+async function launchAssociation(associationUrl: URL) {
+    if (associationUrl.protocol === 'https:') {
+        // The association URL is an Android 'App Link' or iOS 'Universal Link'.
+        // These are regular web URLs that are designed to launch an app if it
+        // is installed or load the actual target webpage if not.
+        window.location.assign(associationUrl);
+    } else {
+        // The association URL has a custom protocol (eg. `solana-wallet:`)
+        try {
+            const browser = getBrowser();
+            switch (browser) {
+                case Browser.Firefox:
+                    // If a custom protocol is not supported in Firefox, it throws.
+                    launchUrlThroughHiddenFrame(associationUrl);
+                    // If we reached this line, it's supported.
+                    break;
+                case Browser.Other: {
+                    const detectionPromise = getDetectionPromise();
+                    window.location.assign(associationUrl);
+                    await detectionPromise;
+                    break;
+                }
+                default:
+                    assertUnreachable(browser);
+            }
+        } catch (e) {
+            throw new SolanaMobileWalletAdapterError(
+                SolanaMobileWalletAdapterErrorCode.ERROR_WALLET_NOT_FOUND,
+                'Found no installed wallet that supports the mobile wallet protocol.',
+            );
+        }
+    }
+}
+
+export async function startSession(
+    associationPublicKey: CryptoKey,
+    associationURLBase?: string,
+): Promise<AssociationPort> {
+    const randomAssociationPort = getRandomAssociationPort();
+    const associationUrl = await getAssociateAndroidIntentURL(
+        associationPublicKey,
+        randomAssociationPort,
+        associationURLBase,
+    );
+    await launchAssociation(associationUrl);
+    return randomAssociationPort;
+}
+
+export async function startRemoteSession(
+    associationPublicKey: CryptoKey,
+    hostAuthority: string,
+    associationURLBase?: string,
+): Promise<ReflectorId> {
+    const randomReflectorId = getRandomReflectorId();
+    const associationUrl = await getRemoteAssociateAndroidIntentURL(
+        associationPublicKey,
+        hostAuthority,
+        randomReflectorId,
+        associationURLBase,
+    );
+    await launchAssociation(associationUrl);
+    return randomReflectorId;
+}
+
+export async function getRemoteSessionUrl(
+    associationPublicKey: CryptoKey,
+    hostAuthority: string,
+    associationURLBase?: string,
+): Promise<{associationUrl: URL, reflectorId: ReflectorId }> {
+    const randomReflectorId = getRandomReflectorId();
+    const associationUrl = await getRemoteAssociateAndroidIntentURL(
+        associationPublicKey,
+        hostAuthority,
+        randomReflectorId,
+        associationURLBase,
+    );
+    return { associationUrl, reflectorId: randomReflectorId };
+}

package/src/transact.ts

@@ -12,8 +12,8 @@ import generateECDHKeypair from './generateECDHKeypair.js';
 import { decryptJsonRpcMessage, encryptJsonRpcMessage } from './jsonRpcMessage.js';
 import parseHelloRsp, { SharedSecret } from './parseHelloRsp.js';
 import parseSessionProps from './parseSessionProps.js';
-import { startSession } from './startSession.js';
-import { AssociationKeypair, MobileWallet, SessionProperties, WalletAssociationConfig } from './types.js';
+import { startSession, startRemoteSession, getRemoteSessionUrl } from './startSession.js';
+import { AssociationKeypair, MobileWallet, RemoteMobileWallet, RemoteWalletAssociationConfig, SessionProperties, WalletAssociationConfig } from './types.js';
 
 const WEBSOCKET_CONNECTION_CONFIG = {
     /**
@@ -102,8 +102,15 @@ export async function transact<TReturn>(
                 );
                 return;
             }
-            const { associationKeypair } = state;
             socket.removeEventListener('open', handleOpen);
+
+            // previous versions of this library and walletlib incorrectly implemented the MWA session 
+            // establishment protocol for local connections. The dapp is supposed to wait for the 
+            // APP_PING message before sending the HELLO_REQ. Instead, the dapp was sending the HELLO_REQ 
+            // immediately upon connection to the websocket server regardless of wether or not an 
+            // APP_PING was sent by the wallet/websocket server. We must continue to support this behavior 
+            // in case the user is using a wallet that has not updated their walletlib implementation. 
+            const { associationKeypair } = state;
             const ecdhKeypair = await generateECDHKeypair();
             socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
             state = {
@@ -132,7 +139,7 @@ export async function transact<TReturn>(
                 reject(
                     new SolanaMobileWalletAdapterError(
                         SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_TIMEOUT,
-                        `Failed to connect to the wallet websocket on port ${sessionPort}.`,
+                        `Failed to connect to the wallet websocket at ${websocketURL}.`,
                     ),
                 );
             } else {
@@ -146,6 +153,18 @@ export async function transact<TReturn>(
         const handleMessage = async (evt: MessageEvent<Blob>) => {
             const responseBuffer = await evt.data.arrayBuffer();
             switch (state.__type) {
+                case 'connecting':
+                    if (responseBuffer.byteLength !== 0) {
+                        throw new Error('Encountered unexpected message while connecting');
+                    }
+                    const ecdhKeypair = await generateECDHKeypair();
+                    socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                    state = {
+                        __type: 'hello_req_sent',
+                        associationPublicKey: associationKeypair.publicKey,
+                        ecdhPrivateKey: ecdhKeypair.privateKey,
+                    };
+                    break;
                 case 'connected':
                     try {
                         const sequenceNumberVector = responseBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
@@ -169,6 +188,17 @@ export async function transact<TReturn>(
                     }
                     break;
                 case 'hello_req_sent': {
+                    // if we receive an APP_PING message (empty message), resend the HELLO_REQ (see above)
+                    if (responseBuffer.byteLength === 0) {
+                        const ecdhKeypair = await generateECDHKeypair();
+                        socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                        state = {
+                            __type: 'hello_req_sent',
+                            associationPublicKey: associationKeypair.publicKey,
+                            ecdhPrivateKey: ecdhKeypair.privateKey,
+                        };
+                        break;
+                    }
                     const sharedSecret = await parseHelloRsp(
                         responseBuffer,
                         state.associationPublicKey,
@@ -264,3 +294,206 @@ export async function transact<TReturn>(
         attemptSocketConnection();
     });
 }
+
+export async function transactRemote<TReturn>(
+    callback: (wallet: RemoteMobileWallet) => TReturn,
+    config: RemoteWalletAssociationConfig,
+): Promise<{associationUrl: URL, result: Promise<TReturn>}> {
+    assertSecureContext();
+    const associationKeypair = await generateAssociationKeypair();
+    const { associationUrl, reflectorId } = await getRemoteSessionUrl(associationKeypair.publicKey, config.remoteHostAuthority, config?.baseUri);
+    const websocketURL = `wss://${config?.remoteHostAuthority}/reflect?id=${reflectorId}`;
+
+    let connectionStartTime: number;
+    const getNextRetryDelayMs = (() => {
+        const schedule = [...WEBSOCKET_CONNECTION_CONFIG.retryDelayScheduleMs];
+        return () => (schedule.length > 1 ? (schedule.shift() as number) : schedule[0]);
+    })();
+    let nextJsonRpcMessageId = 1;
+    let lastKnownInboundSequenceNumber = 0;
+    let state: State = { __type: 'disconnected' };
+    return { associationUrl, result: new Promise((resolve, reject) => {
+        let socket: WebSocket;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const jsonRpcResponsePromises: JsonResponsePromises<any> = {};
+        const handleOpen = async () => {
+            if (state.__type !== 'connecting') {
+                console.warn(
+                    'Expected adapter state to be `connecting` at the moment the websocket opens. ' +
+                        `Got \`${state.__type}\`.`,
+                );
+                return;
+            }
+            socket.removeEventListener('open', handleOpen);
+        };
+        const handleClose = (evt: CloseEvent) => {
+            if (evt.wasClean) {
+                state = { __type: 'disconnected' };
+            } else {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_CLOSED,
+                        `The wallet session dropped unexpectedly (${evt.code}: ${evt.reason}).`,
+                        { closeEvent: evt },
+                    ),
+                );
+            }
+            disposeSocket();
+        };
+        const handleError = async (_evt: Event) => {
+            disposeSocket();
+            if (Date.now() - connectionStartTime >= WEBSOCKET_CONNECTION_CONFIG.timeoutMs) {
+                reject(
+                    new SolanaMobileWalletAdapterError(
+                        SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_TIMEOUT,
+                        `Failed to connect to the wallet websocket at ${websocketURL}.`,
+                    ),
+                );
+            } else {
+                await new Promise((resolve) => {
+                    const retryDelayMs = getNextRetryDelayMs();
+                    retryWaitTimeoutId = window.setTimeout(resolve, retryDelayMs);
+                });
+                attemptSocketConnection();
+            }
+        };
+        const handleMessage = async (evt: MessageEvent<Blob>) => {
+            const responseBuffer = await evt.data.arrayBuffer();
+            switch (state.__type) {
+                case 'connecting':
+                    if (responseBuffer.byteLength !== 0) {
+                        throw new Error('Encountered unexpected message while connecting');
+                    }
+                    const ecdhKeypair = await generateECDHKeypair();
+                    socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+                    state = {
+                        __type: 'hello_req_sent',
+                        associationPublicKey: associationKeypair.publicKey,
+                        ecdhPrivateKey: ecdhKeypair.privateKey,
+                    };
+                    break;
+                case 'connected':
+                    try {
+                        const sequenceNumberVector = responseBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                        const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                        if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                            throw new Error('Encrypted message has invalid sequence number');
+                        }
+                        lastKnownInboundSequenceNumber = sequenceNumber;
+                        const jsonRpcMessage = await decryptJsonRpcMessage(responseBuffer, state.sharedSecret);
+                        const responsePromise = jsonRpcResponsePromises[jsonRpcMessage.id];
+                        delete jsonRpcResponsePromises[jsonRpcMessage.id];
+                        responsePromise.resolve(jsonRpcMessage.result);
+                    } catch (e) {
+                        if (e instanceof SolanaMobileWalletAdapterProtocolError) {
+                            const responsePromise = jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            delete jsonRpcResponsePromises[e.jsonRpcMessageId];
+                            responsePromise.reject(e);
+                        } else {
+                            throw e;
+                        }
+                    }
+                    break;
+                case 'hello_req_sent': {
+                    const sharedSecret = await parseHelloRsp(
+                        responseBuffer,
+                        state.associationPublicKey,
+                        state.ecdhPrivateKey,
+                    );
+                    const sessionPropertiesBuffer = responseBuffer.slice(ENCODED_PUBLIC_KEY_LENGTH_BYTES);
+                    const sessionProperties = sessionPropertiesBuffer.byteLength !== 0 
+                        ? await (async () => {
+                            const sequenceNumberVector = sessionPropertiesBuffer.slice(0, SEQUENCE_NUMBER_BYTES);
+                            const sequenceNumber = getSequenceNumberFromByteArray(sequenceNumberVector);
+                            if (sequenceNumber !== (lastKnownInboundSequenceNumber + 1)) {
+                                throw new Error('Encrypted message has invalid sequence number');
+                            }
+                            lastKnownInboundSequenceNumber = sequenceNumber;
+                            return parseSessionProps(sessionPropertiesBuffer, sharedSecret);
+                        })() : <SessionProperties> { protocol_version: 'legacy' };
+                    state = { __type: 'connected', sharedSecret, sessionProperties };
+                    const wallet = createMobileWalletProxy(sessionProperties.protocol_version,
+                        async (method, params) => {
+                            const id = nextJsonRpcMessageId++;
+                            socket.send(
+                                await encryptJsonRpcMessage(
+                                    {
+                                        id,
+                                        jsonrpc: '2.0' as const,
+                                        method,
+                                        params: params ?? {},
+                                    }, 
+                                    sharedSecret,
+                                ),
+                            );
+                            return new Promise((resolve, reject) => {
+                                jsonRpcResponsePromises[id] = {
+                                    resolve(result) {
+                                        switch (method) {
+                                            case 'authorize':
+                                            case 'reauthorize': {
+                                                const { wallet_uri_base } = result as Awaited<
+                                                    ReturnType<MobileWallet['authorize' | 'reauthorize']>
+                                                >;
+                                                if (wallet_uri_base != null) {
+                                                    try {
+                                                        assertSecureEndpointSpecificURI(wallet_uri_base);
+                                                    } catch (e) {
+                                                        reject(e);
+                                                        return;
+                                                    }
+                                                }
+                                                break;
+                                            }
+                                        }
+                                        resolve(result);
+                                    },
+                                    reject,
+                                };
+                            });
+                        })
+                    try {
+                        resolve(await callback(new Proxy(wallet as RemoteMobileWallet, {
+                            get<TMethodName extends keyof RemoteMobileWallet>(target: RemoteMobileWallet, p: TMethodName) {
+                                if (p == 'terminateSession') {
+                                    return async function () {
+                                        disposeSocket();
+                                        socket.close();
+                                        return;
+                                    };
+                                } else return target[p];
+                            },
+                        })))
+                    } catch (e) {
+                        reject(e);
+                    }
+                    break;
+                }
+            }
+        };
+        let disposeSocket: () => void;
+        let retryWaitTimeoutId: number;
+        const attemptSocketConnection = () => {
+            if (disposeSocket) {
+                disposeSocket();
+            }
+            state = { __type: 'connecting', associationKeypair };
+            if (connectionStartTime === undefined) {
+                connectionStartTime = Date.now();
+            }
+            socket = new WebSocket(websocketURL, [WEBSOCKET_PROTOCOL]);
+            socket.addEventListener('open', handleOpen);
+            socket.addEventListener('close', handleClose);
+            socket.addEventListener('error', handleError);
+            socket.addEventListener('message', handleMessage);
+            disposeSocket = () => {
+                window.clearTimeout(retryWaitTimeoutId);
+                socket.removeEventListener('open', handleOpen);
+                socket.removeEventListener('close', handleClose);
+                socket.removeEventListener('error', handleError);
+                socket.removeEventListener('message', handleMessage);
+            };
+        };
+        attemptSocketConnection();
+    })};
+}

package/src/types.ts

@@ -73,6 +73,10 @@ export type WalletAssociationConfig = Readonly<{
     baseUri?: string;
 }>;
 
+export type RemoteWalletAssociationConfig = WalletAssociationConfig & Readonly<{
+    remoteHostAuthority: string;
+}>;
+
 export interface AuthorizeAPI {
     /**
      * @deprecated Replaced by updated authorize() method, which adds MWA 2.0 spec support.
@@ -150,6 +154,13 @@ export interface MobileWallet
         SignTransactionsAPI,
         SignAndSendTransactionsAPI {}
 
+export interface TerminateSessionAPI {
+    terminateSession(): void
+}
+
+export interface RemoteMobileWallet
+    extends MobileWallet, TerminateSessionAPI {}
+
 // optional features
 export const SolanaSignTransactions = 'solana:signTransactions'
 export const SolanaCloneAuthorization = 'solana:cloneAuthorization'