@solana-mobile/mobile-wallet-adapter-protocol 0.9.8 → 1.0.0

package/.gitignore

@@ -0,0 +1,2 @@
+lib/
+android/build

package/android/.gitignore

@@ -0,0 +1,14 @@
+# OSX
+#
+.DS_Store
+
+# Android/IJ
+#
+.classpath
+.cxx
+.gradle
+.idea
+.project
+.settings
+local.properties
+android.iml

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@solana-mobile/mobile-wallet-adapter-protocol",
     "description": "An implementation of the Solana Mobile Mobile Wallet Adapter protocol. Use this to open a session with a mobile wallet app, and to issue API calls to it.",
-    "version": "0.9.8",
+    "version": "1.0.0",
     "author": "Steven Luscher <steven.luscher@solanamobile.com>",
     "repository": "https://github.com/solana-mobile/mobile-wallet-adapter",
     "license": "Apache-2.0",
@@ -46,6 +46,5 @@
     },
     "peerDependencies": {
         "react-native": ">0.69"
-    },
-    "gitHead": "040622228152826e029bc613f7c6b4b14eefb138"
+    }
 }

package/src/__forks__/react-native/transact.ts

@@ -0,0 +1,106 @@
+import { NativeModules, Platform } from 'react-native';
+
+import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterProtocolError } from '../../errors.js';
+import { MobileWallet, WalletAssociationConfig } from '../../types.js';
+
+type ReactNativeError = Error & { code?: string; userInfo?: Record<string, unknown> };
+
+const LINKING_ERROR =
+    `The package 'solana-mobile-wallet-adapter-protocol' doesn't seem to be linked. Make sure: \n\n` +
+    '- You rebuilt the app after installing the package\n' +
+    '- If you are using Lerna workspaces\n' +
+    '  - You have added `@solana-mobile/mobile-wallet-adapter-protocol` as an explicit dependency, and\n' +
+    '  - You have added `@solana-mobile/mobile-wallet-adapter-protocol` to the `nohoist` section of your package.json\n' +
+    '- You are not using Expo managed workflow\n';
+
+const SolanaMobileWalletAdapter =
+    Platform.OS === 'android' && NativeModules.SolanaMobileWalletAdapter
+        ? NativeModules.SolanaMobileWalletAdapter
+        : new Proxy(
+              {},
+              {
+                  get() {
+                      throw new Error(
+                          Platform.OS !== 'android'
+                              ? 'The package `solana-mobile-wallet-adapter-protocol` is only compatible with React Native Android'
+                              : LINKING_ERROR,
+                      );
+                  },
+              },
+          );
+
+function getErrorMessage(e: ReactNativeError): string {
+    switch (e.code) {
+        case 'ERROR_WALLET_NOT_FOUND':
+            return 'Found no installed wallet that supports the mobile wallet protocol.';
+        default:
+            return e.message;
+    }
+}
+
+function handleError(e: any): never {
+    if (e instanceof Error) {
+        const reactNativeError: ReactNativeError = e;
+        switch (reactNativeError.code) {
+            case undefined:
+                throw e;
+            case 'JSON_RPC_ERROR': {
+                const details = reactNativeError.userInfo as Readonly<{ jsonRpcErrorCode: number }>;
+                throw new SolanaMobileWalletAdapterProtocolError(
+                    0 /* jsonRpcMessageId */,
+                    details.jsonRpcErrorCode,
+                    e.message,
+                );
+            }
+            default:
+                throw new SolanaMobileWalletAdapterError<any>(
+                    reactNativeError.code,
+                    getErrorMessage(reactNativeError),
+                    reactNativeError.userInfo,
+                );
+        }
+    }
+    throw e;
+}
+
+export async function transact<TReturn>(
+    callback: (wallet: MobileWallet) => TReturn,
+    config?: WalletAssociationConfig,
+): Promise<TReturn> {
+    let didSuccessfullyConnect = false;
+    try {
+        await SolanaMobileWalletAdapter.startSession(config);
+        didSuccessfullyConnect = true;
+        const wallet = new Proxy<MobileWallet>({} as MobileWallet, {
+            get<TMethodName extends keyof MobileWallet>(target: MobileWallet, p: TMethodName) {
+                if (target[p] == null) {
+                    const method = p
+                        .toString()
+                        .replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+                        .toLowerCase();
+                    target[p] = async function (params: Parameters<MobileWallet[TMethodName]>[0]) {
+                        try {
+                            return await SolanaMobileWalletAdapter.invoke(method, params);
+                        } catch (e) {
+                            return handleError(e);
+                        }
+                    } as MobileWallet[TMethodName];
+                }
+                return target[p];
+            },
+            defineProperty() {
+                return false;
+            },
+            deleteProperty() {
+                return false;
+            },
+        });
+        return await callback(wallet);
+    } catch (e) {
+        return handleError(e);
+    } finally {
+        if (didSuccessfullyConnect) {
+            await SolanaMobileWalletAdapter.endSession();
+        }
+    }
+}

package/src/arrayBufferToBase64String.ts

@@ -0,0 +1,10 @@
+// https://stackoverflow.com/a/9458996/802047
+export default function arrayBufferToBase64String(buffer: ArrayBuffer) {
+    let binary = '';
+    const bytes = new Uint8Array(buffer);
+    const len = bytes.byteLength;
+    for (let ii = 0; ii < len; ii++) {
+        binary += String.fromCharCode(bytes[ii]);
+    }
+    return window.btoa(binary);
+}

package/src/associationPort.ts

@@ -0,0 +1,19 @@
+import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
+
+declare const tag: unique symbol;
+export type AssociationPort = number & { readonly [tag]: 'AssociationPort' };
+
+export function getRandomAssociationPort(): AssociationPort {
+    return assertAssociationPort(49152 + Math.floor(Math.random() * (65535 - 49152 + 1)));
+}
+
+export function assertAssociationPort(port: number): AssociationPort {
+    if (port < 49152 || port > 65535) {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_ASSOCIATION_PORT_OUT_OF_RANGE,
+            `Association port number must be between 49152 and 65535. ${port} given.`,
+            { port },
+        );
+    }
+    return port as AssociationPort;
+}

package/src/createHelloReq.ts

@@ -0,0 +1,12 @@
+export default async function createHelloReq(ecdhPublicKey: CryptoKey, associationKeypairPrivateKey: CryptoKey) {
+    const publicKeyBuffer = await crypto.subtle.exportKey('raw', ecdhPublicKey);
+    const signatureBuffer = await crypto.subtle.sign(
+        { hash: 'SHA-256', name: 'ECDSA' },
+        associationKeypairPrivateKey,
+        publicKeyBuffer,
+    );
+    const response = new Uint8Array(publicKeyBuffer.byteLength + signatureBuffer.byteLength);
+    response.set(new Uint8Array(publicKeyBuffer), 0);
+    response.set(new Uint8Array(signatureBuffer), publicKeyBuffer.byteLength);
+    return response;
+}

package/src/createSequenceNumberVector.ts

@@ -0,0 +1,11 @@
+export const SEQUENCE_NUMBER_BYTES = 4;
+
+export default function createSequenceNumberVector(sequenceNumber: number): Uint8Array {
+    if (sequenceNumber >= 4294967296) {
+        throw new Error('Outbound sequence number overflow. The maximum sequence number is 32-bytes.');
+    }
+    const byteArray = new ArrayBuffer(SEQUENCE_NUMBER_BYTES);
+    const view = new DataView(byteArray);
+    view.setUint32(0, sequenceNumber, /* littleEndian */ false);
+    return new Uint8Array(byteArray);
+}

package/src/errors.ts

@@ -0,0 +1,93 @@
+// Typescript `enums` thwart tree-shaking. See https://bargsten.org/jsts/enums/
+export const SolanaMobileWalletAdapterErrorCode = {
+    ERROR_ASSOCIATION_PORT_OUT_OF_RANGE: 'ERROR_ASSOCIATION_PORT_OUT_OF_RANGE',
+    ERROR_FORBIDDEN_WALLET_BASE_URL: 'ERROR_FORBIDDEN_WALLET_BASE_URL',
+    ERROR_SECURE_CONTEXT_REQUIRED: 'ERROR_SECURE_CONTEXT_REQUIRED',
+    ERROR_SESSION_CLOSED: 'ERROR_SESSION_CLOSED',
+    ERROR_SESSION_TIMEOUT: 'ERROR_SESSION_TIMEOUT',
+    ERROR_WALLET_NOT_FOUND: 'ERROR_WALLET_NOT_FOUND',
+} as const;
+type SolanaMobileWalletAdapterErrorCodeEnum =
+    typeof SolanaMobileWalletAdapterErrorCode[keyof typeof SolanaMobileWalletAdapterErrorCode];
+
+type ErrorDataTypeMap = {
+    [SolanaMobileWalletAdapterErrorCode.ERROR_ASSOCIATION_PORT_OUT_OF_RANGE]: {
+        port: number;
+    };
+    [SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL]: undefined;
+    [SolanaMobileWalletAdapterErrorCode.ERROR_SECURE_CONTEXT_REQUIRED]: undefined;
+    [SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_CLOSED]: {
+        closeEvent: CloseEvent;
+    };
+    [SolanaMobileWalletAdapterErrorCode.ERROR_SESSION_TIMEOUT]: undefined;
+    [SolanaMobileWalletAdapterErrorCode.ERROR_WALLET_NOT_FOUND]: undefined;
+};
+
+export class SolanaMobileWalletAdapterError<TErrorCode extends SolanaMobileWalletAdapterErrorCodeEnum> extends Error {
+    data: ErrorDataTypeMap[TErrorCode] | undefined;
+    code: TErrorCode;
+    constructor(
+        ...args: ErrorDataTypeMap[TErrorCode] extends Record<string, unknown>
+            ? [code: TErrorCode, message: string, data: ErrorDataTypeMap[TErrorCode]]
+            : [code: TErrorCode, message: string]
+    ) {
+        const [code, message, data] = args;
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'SolanaMobileWalletAdapterError';
+    }
+}
+
+type JSONRPCErrorCode = number;
+
+// Typescript `enums` thwart tree-shaking. See https://bargsten.org/jsts/enums/
+export const SolanaMobileWalletAdapterProtocolErrorCode = {
+    // Keep these in sync with `mobilewalletadapter/common/ProtocolContract.java`.
+    ERROR_AUTHORIZATION_FAILED: -1,
+    ERROR_INVALID_PAYLOADS: -2,
+    ERROR_NOT_SIGNED: -3,
+    ERROR_NOT_SUBMITTED: -4,
+    ERROR_TOO_MANY_PAYLOADS: -5,
+    ERROR_ATTEST_ORIGIN_ANDROID: -100,
+} as const;
+type SolanaMobileWalletAdapterProtocolErrorCodeEnum =
+    typeof SolanaMobileWalletAdapterProtocolErrorCode[keyof typeof SolanaMobileWalletAdapterProtocolErrorCode];
+
+type ProtocolErrorDataTypeMap = {
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_AUTHORIZATION_FAILED]: undefined;
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_INVALID_PAYLOADS]: undefined;
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_NOT_SIGNED]: undefined;
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_NOT_SUBMITTED]: undefined;
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_TOO_MANY_PAYLOADS]: undefined;
+    [SolanaMobileWalletAdapterProtocolErrorCode.ERROR_ATTEST_ORIGIN_ANDROID]: {
+        attest_origin_uri: string;
+        challenge: string;
+        context: string;
+    };
+};
+
+export class SolanaMobileWalletAdapterProtocolError<
+    TErrorCode extends SolanaMobileWalletAdapterProtocolErrorCodeEnum,
+> extends Error {
+    data: ProtocolErrorDataTypeMap[TErrorCode] | undefined;
+    code: TErrorCode | JSONRPCErrorCode;
+    jsonRpcMessageId: number;
+    constructor(
+        ...args: ProtocolErrorDataTypeMap[TErrorCode] extends Record<string, unknown>
+            ? [
+                  jsonRpcMessageId: number,
+                  code: TErrorCode | JSONRPCErrorCode,
+                  message: string,
+                  data: ProtocolErrorDataTypeMap[TErrorCode],
+              ]
+            : [jsonRpcMessageId: number, code: TErrorCode | JSONRPCErrorCode, message: string]
+    ) {
+        const [jsonRpcMessageId, code, message, data] = args;
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.jsonRpcMessageId = jsonRpcMessageId;
+        this.name = 'SolanaMobileWalletAdapterProtocolError';
+    }
+}

package/src/generateAssociationKeypair.ts

@@ -0,0 +1,10 @@
+export default async function generateAssociationKeypair(): Promise<CryptoKeyPair> {
+    return await crypto.subtle.generateKey(
+        {
+            name: 'ECDSA',
+            namedCurve: 'P-256',
+        },
+        false /* extractable */,
+        ['sign'] /* keyUsages */,
+    );
+}

package/src/generateECDHKeypair.ts

@@ -0,0 +1,10 @@
+export default async function generateECDHKeypair(): Promise<CryptoKeyPair> {
+    return await crypto.subtle.generateKey(
+        {
+            name: 'ECDH',
+            namedCurve: 'P-256',
+        },
+        false /* extractable */,
+        ['deriveKey', 'deriveBits'] /* keyUsages */,
+    );
+}

package/src/getAssociateAndroidIntentURL.ts

@@ -0,0 +1,52 @@
+import arrayBufferToBase64String from './arrayBufferToBase64String.js';
+import { assertAssociationPort } from './associationPort.js';
+import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
+import getStringWithURLUnsafeBase64CharactersReplaced from './getStringWithURLUnsafeBase64CharactersReplaced.js';
+
+const INTENT_NAME = 'solana-wallet';
+
+function getPathParts(pathString: string) {
+    return (
+        pathString
+            // Strip leading and trailing slashes
+            .replace(/(^\/+|\/+$)/g, '')
+            // Return an array of directories
+            .split('/')
+    );
+}
+
+function getIntentURL(methodPathname: string, intentUrlBase?: string) {
+    let baseUrl: URL | null = null;
+    if (intentUrlBase) {
+        try {
+            baseUrl = new URL(intentUrlBase);
+        } catch {} // eslint-disable-line no-empty
+        if (baseUrl?.protocol !== 'https:') {
+            throw new SolanaMobileWalletAdapterError(
+                SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL,
+                'Base URLs supplied by wallets must be valid `https` URLs',
+            );
+        }
+    }
+    baseUrl ||= new URL(`${INTENT_NAME}:/`);
+    const pathname = methodPathname.startsWith('/')
+        ? // Method is an absolute path. Replace it wholesale.
+          methodPathname
+        : // Method is a relative path. Merge it with the existing one.
+          [...getPathParts(baseUrl.pathname), ...getPathParts(methodPathname)].join('/');
+    return new URL(pathname, baseUrl);
+}
+
+export default async function getAssociateAndroidIntentURL(
+    associationPublicKey: CryptoKey,
+    putativePort: number,
+    associationURLBase?: string,
+): Promise<URL> {
+    const associationPort = assertAssociationPort(putativePort);
+    const exportedKey = await crypto.subtle.exportKey('raw', associationPublicKey);
+    const encodedKey = arrayBufferToBase64String(exportedKey);
+    const url = getIntentURL('v1/associate/local', associationURLBase);
+    url.searchParams.set('association', getStringWithURLUnsafeBase64CharactersReplaced(encodedKey));
+    url.searchParams.set('port', `${associationPort}`);
+    return url;
+}

package/src/getJWS.ts

@@ -0,0 +1,19 @@
+import arrayBufferToBase64String from './arrayBufferToBase64String.js';
+
+export default async function getJWS(payload: string, privateKey: CryptoKey) {
+    const header = { alg: 'ES256' };
+    const headerEncoded = window.btoa(JSON.stringify(header));
+    const payloadEncoded = window.btoa(payload);
+    const message = `${headerEncoded}.${payloadEncoded}`;
+    const signatureBuffer = await crypto.subtle.sign(
+        {
+            name: 'ECDSA',
+            hash: 'SHA-256',
+        },
+        privateKey,
+        new TextEncoder().encode(message),
+    );
+    const signature = arrayBufferToBase64String(signatureBuffer);
+    const jws = `${message}.${signature}`;
+    return jws;
+}

package/src/getStringWithURLUnsafeBase64CharactersReplaced.ts

@@ -0,0 +1,11 @@
+export default function getStringWithURLUnsafeCharactersReplaced(unsafeBase64EncodedString: string): string {
+    return unsafeBase64EncodedString.replace(
+        /[/+=]/g,
+        (m) =>
+            ({
+                '/': '_',
+                '+': '-',
+                '=': '.',
+            }[m] as string),
+    );
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './transact.js';
+export * from './types.js';

package/src/jsonRpcMessage.ts

@@ -0,0 +1,81 @@
+import createSequenceNumberVector, { SEQUENCE_NUMBER_BYTES } from './createSequenceNumberVector.js';
+import { SolanaMobileWalletAdapterProtocolError } from './errors.js';
+import { SharedSecret } from './parseHelloRsp.js';
+
+const INITIALIZATION_VECTOR_BYTES = 12;
+
+interface JSONRPCRequest<TParams> {
+    id: number;
+    jsonrpc: '2.0';
+    method: string;
+    params: TParams;
+}
+
+type JSONRPCResponse<TMessage> = {
+    id: number;
+    jsonrpc: '2.0';
+    result: TMessage;
+};
+
+export async function encryptJsonRpcMessage<TParams>(
+    jsonRpcMessage: JSONRPCRequest<TParams>,
+    sharedSecret: SharedSecret,
+) {
+    const plaintext = JSON.stringify(jsonRpcMessage);
+    const sequenceNumberVector = createSequenceNumberVector(jsonRpcMessage.id);
+    const initializationVector = new Uint8Array(INITIALIZATION_VECTOR_BYTES);
+    crypto.getRandomValues(initializationVector);
+    const ciphertext = await crypto.subtle.encrypt(
+        getAlgorithmParams(sequenceNumberVector, initializationVector),
+        sharedSecret,
+        new TextEncoder().encode(plaintext),
+    );
+    const response = new Uint8Array(
+        sequenceNumberVector.byteLength + initializationVector.byteLength + ciphertext.byteLength,
+    );
+    response.set(new Uint8Array(sequenceNumberVector), 0);
+    response.set(new Uint8Array(initializationVector), sequenceNumberVector.byteLength);
+    response.set(new Uint8Array(ciphertext), sequenceNumberVector.byteLength + initializationVector.byteLength);
+    return response;
+}
+
+export async function decryptJsonRpcMessage<TMessage>(message: ArrayBuffer, sharedSecret: SharedSecret) {
+    const sequenceNumberVector = message.slice(0, SEQUENCE_NUMBER_BYTES);
+    const initializationVector = message.slice(
+        SEQUENCE_NUMBER_BYTES,
+        SEQUENCE_NUMBER_BYTES + INITIALIZATION_VECTOR_BYTES,
+    );
+    const ciphertext = message.slice(SEQUENCE_NUMBER_BYTES + INITIALIZATION_VECTOR_BYTES);
+    const plaintextBuffer = await crypto.subtle.decrypt(
+        getAlgorithmParams(sequenceNumberVector, initializationVector),
+        sharedSecret,
+        ciphertext,
+    );
+    const plaintext = getUtf8Decoder().decode(plaintextBuffer);
+    const jsonRpcMessage = JSON.parse(plaintext);
+    if (Object.hasOwnProperty.call(jsonRpcMessage, 'error')) {
+        throw new SolanaMobileWalletAdapterProtocolError<typeof jsonRpcMessage.error.code>(
+            jsonRpcMessage.id,
+            jsonRpcMessage.error.code,
+            jsonRpcMessage.error.message,
+        );
+    }
+    return jsonRpcMessage as JSONRPCResponse<TMessage>;
+}
+
+function getAlgorithmParams(sequenceNumber: ArrayBuffer, initializationVector: ArrayBuffer) {
+    return {
+        additionalData: sequenceNumber,
+        iv: initializationVector,
+        name: 'AES-GCM',
+        tagLength: 128, // 16 byte tag => 128 bits
+    };
+}
+
+let _utf8Decoder: TextDecoder | undefined;
+function getUtf8Decoder() {
+    if (_utf8Decoder === undefined) {
+        _utf8Decoder = new TextDecoder('utf-8');
+    }
+    return _utf8Decoder;
+}

package/src/parseHelloRsp.ts

@@ -0,0 +1,44 @@
+/**
+ * A secret agreed upon by the app and the wallet. Used as
+ * a symmetric key to encrypt and decrypt messages over an
+ * unsecured channel.
+ */
+export type SharedSecret = CryptoKey;
+
+export default async function parseHelloRsp(
+    payloadBuffer: ArrayBuffer, // The X9.62-encoded wallet endpoint ephemeral ECDH public keypoint.
+    associationPublicKey: CryptoKey,
+    ecdhPrivateKey: CryptoKey,
+): Promise<SharedSecret> {
+    const [associationPublicKeyBuffer, walletPublicKey] = await Promise.all([
+        crypto.subtle.exportKey('raw', associationPublicKey),
+        crypto.subtle.importKey(
+            'raw',
+            payloadBuffer,
+            { name: 'ECDH', namedCurve: 'P-256' },
+            false /* extractable */,
+            [] /* keyUsages */,
+        ),
+    ]);
+    const sharedSecret = await crypto.subtle.deriveBits({ name: 'ECDH', public: walletPublicKey }, ecdhPrivateKey, 256);
+    const ecdhSecretKey = await crypto.subtle.importKey(
+        'raw',
+        sharedSecret,
+        'HKDF',
+        false /* extractable */,
+        ['deriveKey'] /* keyUsages */,
+    );
+    const aesKeyMaterialVal = await crypto.subtle.deriveKey(
+        {
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: new Uint8Array(associationPublicKeyBuffer),
+            info: new Uint8Array(),
+        },
+        ecdhSecretKey,
+        { name: 'AES-GCM', length: 128 },
+        false /* extractable */,
+        ['encrypt', 'decrypt'],
+    );
+    return aesKeyMaterialVal as SharedSecret;
+}

package/src/startSession.ts

@@ -0,0 +1,94 @@
+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;
+}

package/src/transact.ts

@@ -0,0 +1,268 @@
+import createHelloReq from './createHelloReq.js';
+import { SEQUENCE_NUMBER_BYTES } from './createSequenceNumberVector.js';
+import {
+    SolanaMobileWalletAdapterError,
+    SolanaMobileWalletAdapterErrorCode,
+    SolanaMobileWalletAdapterProtocolError,
+} from './errors.js';
+import generateAssociationKeypair from './generateAssociationKeypair.js';
+import generateECDHKeypair from './generateECDHKeypair.js';
+import { decryptJsonRpcMessage, encryptJsonRpcMessage } from './jsonRpcMessage.js';
+import parseHelloRsp, { SharedSecret } from './parseHelloRsp.js';
+import { startSession } from './startSession.js';
+import { AssociationKeypair, MobileWallet, WalletAssociationConfig } from './types.js';
+
+const WEBSOCKET_CONNECTION_CONFIG = {
+    /**
+     * 300 milliseconds is a generally accepted threshold for what someone
+     * would consider an acceptable response time for a user interface
+     * after having performed a low-attention tapping task. We set the initial
+     * interval at which we wait for the wallet to set up the websocket at
+     * half this, as per the Nyquist frequency, with a progressive backoff
+     * sequence from there. The total wait time is 30s, which allows for the
+     * user to be presented with a disambiguation dialog, select a wallet, and
+     * for the wallet app to subsequently start.
+     */
+    retryDelayScheduleMs: [150, 150, 200, 500, 500, 750, 750, 1000],
+    timeoutMs: 30000,
+} as const;
+const WEBSOCKET_PROTOCOL = 'com.solana.mobilewalletadapter.v1';
+
+type JsonResponsePromises<T> = Record<
+    number,
+    Readonly<{ resolve: (value?: T | PromiseLike<T>) => void; reject: (reason?: unknown) => void }>
+>;
+
+type State =
+    | { __type: 'connected'; sharedSecret: SharedSecret }
+    | { __type: 'connecting'; associationKeypair: AssociationKeypair }
+    | { __type: 'disconnected' }
+    | { __type: 'hello_req_sent'; associationPublicKey: CryptoKey; ecdhPrivateKey: CryptoKey };
+
+function assertSecureContext() {
+    if (typeof window === 'undefined' || window.isSecureContext !== true) {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_SECURE_CONTEXT_REQUIRED,
+            'The mobile wallet adapter protocol must be used in a secure context (`https`).',
+        );
+    }
+}
+
+function assertSecureEndpointSpecificURI(walletUriBase: string) {
+    let url: URL;
+    try {
+        url = new URL(walletUriBase);
+    } catch {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL,
+            'Invalid base URL supplied by wallet',
+        );
+    }
+    if (url.protocol !== 'https:') {
+        throw new SolanaMobileWalletAdapterError(
+            SolanaMobileWalletAdapterErrorCode.ERROR_FORBIDDEN_WALLET_BASE_URL,
+            'Base URLs supplied by wallets must be valid `https` URLs',
+        );
+    }
+}
+
+function getSequenceNumberFromByteArray(byteArray: ArrayBuffer): number {
+    const view = new DataView(byteArray);
+    return view.getUint32(0, /* littleEndian */ false);
+}
+
+export async function transact<TReturn>(
+    callback: (wallet: MobileWallet) => TReturn,
+    config?: WalletAssociationConfig,
+): Promise<TReturn> {
+    assertSecureContext();
+    const associationKeypair = await generateAssociationKeypair();
+    const sessionPort = await startSession(associationKeypair.publicKey, config?.baseUri);
+    const websocketURL = `ws://localhost:${sessionPort}/solana-wallet`;
+    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 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;
+            }
+            const { associationKeypair } = state;
+            socket.removeEventListener('open', handleOpen);
+            const ecdhKeypair = await generateECDHKeypair();
+            socket.send(await createHelloReq(ecdhKeypair.publicKey, associationKeypair.privateKey));
+            state = {
+                __type: 'hello_req_sent',
+                associationPublicKey: associationKeypair.publicKey,
+                ecdhPrivateKey: ecdhKeypair.privateKey,
+            };
+        };
+        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 on port ${sessionPort}.`,
+                    ),
+                );
+            } 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 '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,
+                    );
+                    state = { __type: 'connected', sharedSecret };
+                    const wallet = new Proxy<MobileWallet>({} as MobileWallet, {
+                        get<TMethodName extends keyof MobileWallet>(target: MobileWallet, p: TMethodName) {
+                            if (target[p] == null) {
+                                const method = p
+                                    .toString()
+                                    .replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+                                    .toLowerCase();
+                                target[p] = async function (params: Parameters<MobileWallet[TMethodName]>[0]) {
+                                    const id = nextJsonRpcMessageId++;
+                                    socket.send(
+                                        await encryptJsonRpcMessage(
+                                            {
+                                                id,
+                                                jsonrpc: '2.0',
+                                                method,
+                                                params: params ?? {},
+                                            },
+                                            sharedSecret,
+                                        ),
+                                    );
+                                    return new Promise((resolve, reject) => {
+                                        jsonRpcResponsePromises[id] = {
+                                            resolve(result) {
+                                                switch (p) {
+                                                    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,
+                                        };
+                                    });
+                                } as MobileWallet[TMethodName];
+                            }
+                            return target[p];
+                        },
+                        defineProperty() {
+                            return false;
+                        },
+                        deleteProperty() {
+                            return false;
+                        },
+                    });
+                    try {
+                        resolve(await callback(wallet));
+                    } catch (e) {
+                        reject(e);
+                    } finally {
+                        disposeSocket();
+                        socket.close();
+                    }
+                    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

@@ -0,0 +1,111 @@
+import type { TransactionVersion } from '@solana/web3.js';
+
+export type Account = Readonly<{
+    address: Base64EncodedAddress;
+    label?: string;
+}>;
+
+/**
+ * Properties that wallets may present to users when an app
+ * asks for authorization to execute privileged methods (see
+ * {@link PrivilegedMethods}).
+ */
+export type AppIdentity = Readonly<{
+    uri?: string;
+    icon?: string;
+    name?: string;
+}>;
+
+/**
+ * An ephemeral elliptic-curve keypair on the P-256 curve.
+ * This public key is used to create the association token.
+ * The private key is used during session establishment.
+ */
+export type AssociationKeypair = CryptoKeyPair;
+
+/**
+ * The context returned from a wallet after having authorized a given
+ * account for use with a given application. You can cache this and
+ * use it later to invoke privileged methods.
+ */
+export type AuthorizationResult = Readonly<{
+    accounts: Account[];
+    auth_token: AuthToken;
+    wallet_uri_base: string;
+}>;
+
+export type AuthToken = string;
+
+export type Base64EncodedAddress = string;
+
+type Base64EncodedSignature = string;
+
+type Base64EncodedMessage = string;
+
+type Base64EncodedSignedMessage = string;
+
+type Base64EncodedSignedTransaction = string;
+
+export type Base64EncodedTransaction = string;
+
+export type Cluster = 'devnet' | 'testnet' | 'mainnet-beta';
+
+export type Finality = 'confirmed' | 'finalized' | 'processed';
+
+export type WalletAssociationConfig = Readonly<{
+    baseUri?: string;
+}>;
+
+export interface AuthorizeAPI {
+    authorize(params: { cluster: Cluster; identity: AppIdentity }): Promise<AuthorizationResult>;
+}
+export interface CloneAuthorizationAPI {
+    cloneAuthorization(params: { auth_token: AuthToken }): Promise<Readonly<{ auth_token: AuthToken }>>;
+}
+export interface DeauthorizeAPI {
+    deauthorize(params: { auth_token: AuthToken }): Promise<Readonly<Record<string, never>>>;
+}
+
+export interface GetCapabilitiesAPI {
+    getCapabilities(): Promise<
+        Readonly<{
+            supports_clone_authorization: boolean;
+            supports_sign_and_send_transactions: boolean;
+            max_transactions_per_request: boolean;
+            max_messages_per_request: boolean;
+            supported_transaction_versions: ReadonlyArray<TransactionVersion>;
+        }>
+    >;
+}
+export interface ReauthorizeAPI {
+    reauthorize(params: { auth_token: AuthToken }): Promise<AuthorizationResult>;
+}
+export interface SignMessagesAPI {
+    signMessages(params: {
+        addresses: Base64EncodedAddress[];
+        payloads: Base64EncodedMessage[];
+    }): Promise<Readonly<{ signed_payloads: Base64EncodedSignedMessage[] }>>;
+}
+export interface SignTransactionsAPI {
+    signTransactions(params: {
+        payloads: Base64EncodedTransaction[];
+    }): Promise<Readonly<{ signed_payloads: Base64EncodedSignedTransaction[] }>>;
+}
+export interface SignAndSendTransactionsAPI {
+    signAndSendTransactions(params: {
+        options?: Readonly<{
+            min_context_slot?: number;
+        }>;
+        payloads: Base64EncodedTransaction[];
+    }): Promise<Readonly<{ signatures: Base64EncodedSignature[] }>>;
+}
+
+export interface MobileWallet
+    extends AuthorizeAPI,
+        CloneAuthorizationAPI,
+        DeauthorizeAPI,
+        GetCapabilitiesAPI,
+        ReauthorizeAPI,
+        SignMessagesAPI,
+        SignTransactionsAPI,
+        SignAndSendTransactionsAPI {}

package/tsconfig.cjs.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "outDir": "lib/cjs"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": ["src"],
+    "compilerOptions": {
+        "declarationDir": "./lib/types",
+        "outDir": "lib/esm"
+    }
+}