@solana-mobile/mobile-wallet-adapter-protocol 2.1.3 → 2.1.5

package/src/generateAssociationKeypair.ts

@@ -1,10 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,57 +0,0 @@
-import arrayBufferToBase64String from './arrayBufferToBase64String.js';
-import { assertAssociationPort } from './associationPort.js';
-import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from './errors.js';
-import getStringWithURLUnsafeBase64CharactersReplaced from './getStringWithURLUnsafeBase64CharactersReplaced.js';
-import { ProtocolVersion } from './types.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,
-    protocolVersions: ProtocolVersion[] = ['v1'],
-): 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}`);
-    protocolVersions.forEach( (version) => {
-        url.searchParams.set('v', version);
-    })
-    return url;
-}

package/src/getJWS.ts

@@ -1,19 +0,0 @@
-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

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

package/src/index.ts

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

package/src/jsonRpcMessage.ts

@@ -1,38 +0,0 @@
-import { decryptMessage, encryptMessage } from './encryptedMessage.js';
-import { SolanaMobileWalletAdapterProtocolError } from './errors.js';
-import { SharedSecret } from './parseHelloRsp.js';
-
-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 sequenceNumber = jsonRpcMessage.id;
-    return encryptMessage(plaintext, sequenceNumber, sharedSecret);
-}
-
-export async function decryptJsonRpcMessage<TMessage>(message: ArrayBuffer, sharedSecret: SharedSecret) {
-    const plaintext = await decryptMessage(message, sharedSecret);
-    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>;
-}

package/src/parseHelloRsp.ts

@@ -1,46 +0,0 @@
-import { ENCODED_PUBLIC_KEY_LENGTH_BYTES } from "./encryptedMessage";
-
-/**
- * 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.slice(0, ENCODED_PUBLIC_KEY_LENGTH_BYTES),
-            { 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/parseSessionProps.ts

@@ -1,33 +0,0 @@
-import { decryptMessage } from "./encryptedMessage";
-import { SolanaMobileWalletAdapterError, SolanaMobileWalletAdapterErrorCode } from "./errors";
-import { SharedSecret } from "./parseHelloRsp";
-import { ProtocolVersion, SessionProperties } from "./types";
-
-export default async function parseSessionProps(
-    message: ArrayBuffer, 
-    sharedSecret: SharedSecret
-): Promise<SessionProperties> {
-    const plaintext = await decryptMessage(message, sharedSecret);
-    const jsonProperties = JSON.parse(plaintext);
-    let protocolVersion: ProtocolVersion = 'legacy';
-    if (Object.hasOwnProperty.call(jsonProperties, 'v')) {
-        switch (jsonProperties.v) {
-            case 1:
-            case '1':
-            case 'v1':
-                protocolVersion = 'v1'
-                break;
-            case 'legacy':
-                protocolVersion = 'legacy'
-                break;
-            default:
-                throw new SolanaMobileWalletAdapterError(
-                    SolanaMobileWalletAdapterErrorCode.ERROR_INVALID_PROTOCOL_VERSION, 
-                    `Unknown/unsupported protocol version: ${jsonProperties.v}`
-                );
-        }
-    }
-    return <SessionProperties>({
-        protocol_version: protocolVersion
-    })
-}

package/src/startSession.ts

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

@@ -1,266 +0,0 @@
-import createHelloReq from './createHelloReq.js';
-import createMobileWalletProxy from './createMobileWalletProxy.js';
-import { SEQUENCE_NUMBER_BYTES } from './createSequenceNumberVector.js';
-import { ENCODED_PUBLIC_KEY_LENGTH_BYTES } from './encryptedMessage.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 parseSessionProps from './parseSessionProps.js';
-import { startSession } from './startSession.js';
-import { AssociationKeypair, MobileWallet, SessionProperties, 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; sessionProperties: SessionProperties }
-    | { __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,
-                    );
-                    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(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();
-    });
-}