@0xsequence/provider 0.0.0-2021823181734

package/src/transports/window-transport/window-message-handler.ts

@@ -0,0 +1,166 @@
+import {
+  ProviderMessageRequest,
+  ProviderMessage,
+  EventType,
+  InitState,
+  WindowSessionParams,
+  OpenWalletIntent,
+  ProviderRpcError,
+  TransportSession
+} from '../../types'
+import { WalletRequestHandler } from '../wallet-request-handler'
+import { BaseWalletTransport } from '../base-wallet-transport'
+import { logger, sanitizeNumberString, base64DecodeObject } from '@0xsequence/utils'
+
+export class WindowMessageHandler extends BaseWalletTransport {
+  protected parentWindow: Window
+
+  private _isPopup: boolean = false
+
+  constructor(walletRequestHandler: WalletRequestHandler) {
+    super(walletRequestHandler)
+    this._init = InitState.NIL
+  }
+
+  register() {
+    const isPopup = parent.window.opener !== null
+    this._isPopup = isPopup
+    if (isPopup !== true) {
+      return
+    }
+
+    // record open details (sessionId + default network) from the window url
+    const { pathname, search: rawParams } = new URL(window.location.href)
+
+    let session: TransportSession | null = this.getWindowTransportSession(rawParams)
+
+    // provider should always include sid when opening a new window
+    const isNewWindowSession = !!session.sessionId
+
+    // attempt to restore previous session in the case of a redirect or window reload
+    if (!isNewWindowSession) {
+      session = this.getCachedTransportSession()
+    }
+
+    if (!session) {
+      logger.error('window session is undefined')
+      return
+    }
+
+    if (session.intent && isNewWindowSession) {
+      window.history.replaceState({ openWalletIntent: true }, document.title, pathname)
+    }
+
+    // record parent window instance for communication
+    this.parentWindow = parent.window.opener
+
+    // listen for window-transport requests
+    window.addEventListener('message', this.onWindowEvent, false)
+    this._registered = true
+
+    // send open event to the app which opened us
+    this.open(session)
+      .then(opened => {
+        if (!opened) {
+          const err = `failed to open to network ${session?.networkId}`
+          logger.error(err)
+          this.notifyClose({ message: err } as ProviderRpcError)
+          window.close()
+        }
+      })
+      .catch(e => {
+        const err = `failed to open to network ${session?.networkId}, due to: ${e}`
+        logger.error(err)
+        this.notifyClose({ message: err } as ProviderRpcError)
+        window.close()
+      })
+  }
+
+  unregister() {
+    window.removeEventListener('message', this.onWindowEvent)
+    this._registered = false
+  }
+
+  // onmessage is called when (the wallet) receives request messages from the dapp
+  // over the window post-messaging transport
+  private onWindowEvent = async (event: MessageEvent) => {
+    if (!event.origin || event.origin === '') {
+      // skip same-origin or when event.origin is empty/undefined
+      return
+    }
+    if (this.appOrigin && event.origin !== this.appOrigin) {
+      // skip message as not from expected app origin
+      return
+    }
+
+    // Wallet always expects json-rpc request messages from a dapp
+    let request: ProviderMessageRequest
+    try {
+      request = JSON.parse(event.data)
+    } catch (err) {
+      // event is not a ProviderMessage JSON object, skip
+      return
+    }
+
+    logger.debug('RECEIVED MESSAGE', request)
+
+    // Record event origin for valid init ack
+    if (this._init !== InitState.OK && this.isValidInitAck(request)) {
+      this.appOrigin = event.origin
+    }
+    if (this._init === InitState.OK && (!this.appOrigin || this.appOrigin.length < 8)) {
+      // impossible state
+      logger.error('impossible state, init.OK and appOrigin required')
+      return
+    }
+
+    // Handle message via the base transport
+    this.handleMessage(request)
+  }
+
+  // postMessage sends message to the dapp window
+  sendMessage(message: ProviderMessage<any>) {
+    // prepare payload
+    const payload = JSON.stringify(message)
+
+    // post-message to app.
+    // only for init requests, we send to '*' origin
+    if (message.type === EventType.INIT) {
+      this.postMessage(payload, true)
+    } else {
+      this.postMessage(payload)
+    }
+  }
+
+  get isPopup(): boolean {
+    return this._isPopup
+  }
+
+  private postMessage(message: any, init = false) {
+    if (init !== true && this._init !== InitState.OK) {
+      logger.error('impossible state, should not be calling postMessage until inited')
+      return
+    }
+
+    if (init) {
+      // init message transmission to global target -- for 'init' payloads only
+      this.parentWindow.postMessage(message, '*')
+    } else {
+      // open message transmission
+      if (this.appOrigin && this.appOrigin.length > 4) { // just above '.com'
+        this.parentWindow.postMessage(message, this.appOrigin)
+      } else {
+        logger.error('unable to postMessage as parentOrigin is invalid')
+      }
+    }
+  }
+
+  private getWindowTransportSession = (windowParams: string | undefined): TransportSession => {
+    const params = new WindowSessionParams(windowParams)
+    return {
+      sessionId: params.get('sid'),
+      networkId: params.get('net'),
+      intent: base64DecodeObject<OpenWalletIntent>(params.get('intent'))
+    }
+  }
+}

package/src/transports/window-transport/window-message-provider.ts

@@ -0,0 +1,183 @@
+import { OpenWalletIntent, ProviderMessage, InitState, EventType, WindowSessionParams } from '../../types'
+import { BaseProviderTransport } from '../base-provider-transport'
+import { logger, base64EncodeObject } from '@0xsequence/utils'
+import { isBrowserExtension } from '../../utils'
+
+// ..
+let registeredWindowMessageProvider: WindowMessageProvider | undefined
+
+export class WindowMessageProvider extends BaseProviderTransport {
+  private walletURL: URL
+  private walletWindow: Window | null
+
+  constructor(walletAppURL: string) {
+    super()
+    this.walletURL = new URL(walletAppURL)
+  }
+
+  register = () => {
+    if (registeredWindowMessageProvider) {
+      throw new Error('A WindowMessageProvider is already registered. There can only be one.')
+    }
+
+    // listen for incoming messages from wallet
+    window.addEventListener('message', this.onWindowEvent)
+    registeredWindowMessageProvider = this
+
+    // open heartbeat
+    this.on('open', () => {
+      // Heartbeat to track if window closed
+      const popup = this.walletWindow
+      const interval = setInterval(() => {
+        if (popup && popup.closed) {
+          clearInterval(interval)
+          this.close()
+        }
+      }, 500)
+    })
+
+    // close clean up
+    this.on('close', () => {
+      if (this.walletWindow) {
+        this.walletWindow.close()
+        this.walletWindow = null
+      }
+    })
+
+    this._registered = true
+  }
+
+  unregister = () => {
+    this._registered = false
+    this.closeWallet()
+
+    // disable message listener
+    if (registeredWindowMessageProvider === this) {
+      registeredWindowMessageProvider = undefined
+    }
+    window.removeEventListener('message', this.onWindowEvent)
+
+    // clear event listeners
+    this.events.removeAllListeners()
+  }
+
+  openWallet = (path?: string, intent?: OpenWalletIntent, networkId?: string | number): void => {
+    if (this.walletWindow && this.isOpened()) {
+      // TODO: update the location of window to path
+      this.walletWindow.focus()
+      return
+    }
+
+    // Instantiate new walletURL for this call
+    const walletURL = new URL(this.walletURL.href)
+    const windowSessionParams = new WindowSessionParams()
+
+    if (path && path !== '') {
+      walletURL.pathname = path.toLowerCase()
+    }
+
+    // Set session, intent and network id on walletURL
+    this._init = InitState.NIL
+    this._sessionId = `${performance.now()}`
+    windowSessionParams.set('sid', this._sessionId)
+    if (intent) {
+      // for the window-transport, we eagerly/optimistically set the origin host
+      // when connecting to the wallet, however, this will be verified and enforced
+      // on the wallet-side, so if a dapp provides the wrong origin, it will be dropped.
+      if (intent.type === 'connect') {
+        if (!intent.options) intent.options = {}
+
+        // skip setting origin host if we're in an browser extension execution context
+        // allow origin that is passed in
+        if (!isBrowserExtension()) {
+          intent.options.origin = window.location.origin
+        }
+      }
+      // encode intent as base6 url-encoded param
+      windowSessionParams.set('intent', base64EncodeObject(intent))
+    }
+    if (networkId) {
+      windowSessionParams.set('net', `${networkId}`)
+    }
+
+    // Open popup window on center of the app window
+    const windowSize = [450, 750]
+    const windowPos = [
+      Math.abs(window.screenX + window.innerWidth / 2 - windowSize[0] / 2),
+      Math.abs(window.screenY + window.innerHeight / 2 - windowSize[1] / 2)
+    ]
+
+    const windowFeatures =
+      `toolbar=0,location=0,menubar=0,scrollbars=yes,status=yes` +
+      `,width=${windowSize[0]},height=${windowSize[1]}` +
+      `,left=${windowPos[0]},top=${windowPos[1]}`
+
+    // serialize params
+    walletURL.search = windowSessionParams.toString()
+
+    this.walletWindow = window.open(walletURL.href, 'sequence.app', windowFeatures)
+
+    // TODO: move this somewhere else
+    // TODO: perhaps we trigger a .on('openTimeout') event..? maybe.. could help.
+
+    // Popup blocking detection and notice
+    // let warned = false
+    // const warnPopupBlocked = () => {
+    //   if (warned) return
+    //   warned = true
+    //   // alert('popup is blocked! hey yo') // NOTE: for debug purposes only
+    //   throw new Error('popup is blocked')
+    // }
+
+    // const popupCheck = setTimeout(() => {
+    //   if (!popup || popup.closed || typeof popup.closed === 'undefined') {
+    //     // popup is definitely blocked if we reach here.
+    //     warnPopupBlocked()
+    //   }
+    // }, 1000)
+
+    // const popupBlocked = popup === null || popup === undefined
+    // if (popupBlocked) {
+    //   warnPopupBlocked()
+    //   return
+    // }
+  }
+
+  closeWallet() {
+    this.close()
+    this.walletWindow?.close()
+  }
+
+  // onmessage, receives ProviderMessageResponse from the wallet post-message transport
+  private onWindowEvent = (event: MessageEvent) => {
+    // Security check, ensure message is coming from wallet origin url
+    if (event.origin !== this.walletURL.origin) {
+      // Safetly can skip events not from the wallet
+      return
+    }
+
+    let message: ProviderMessage<any>
+    try {
+      message = JSON.parse(event.data)
+    } catch (err) {
+      // event is not a ProviderMessage JSON object, skip
+      return
+    }
+
+    if (!message) {
+      throw new Error('ProviderMessage object is empty')
+    }
+
+    // handle message with base message provider
+    this.handleMessage(message)
+  }
+
+  sendMessage(message: ProviderMessage<any>) {
+    if (!this.walletWindow) {
+      logger.warn('WindowMessageProvider: sendMessage failed as walletWindow is unavailable')
+      return
+    }
+    const postedMessage = typeof message !== 'string' ? JSON.stringify(message) : message
+    this.walletWindow.postMessage(postedMessage, this.walletURL.origin)
+  }
+}

package/src/types.ts

@@ -0,0 +1,252 @@
+import { NetworkConfig, WalletContext, JsonRpcRequest, JsonRpcResponse, JsonRpcHandler } from '@0xsequence/network'
+import { TypedData } from '@0xsequence/utils'
+
+export interface ProviderTransport extends JsonRpcHandler, ProviderMessageTransport, ProviderMessageRequestHandler {
+  register(): void
+  unregister(): void
+
+  openWallet(path?: string, intent?: OpenWalletIntent, networkId?: string | number): void
+  closeWallet(): void
+
+  isOpened(): boolean
+  isConnected(): boolean
+
+  on<K extends keyof ProviderEventTypes>(event: K, fn: ProviderEventTypes[K]): void
+  once<K extends keyof ProviderEventTypes>(event: K, fn: ProviderEventTypes[K]): void
+  emit<K extends keyof ProviderEventTypes>(event: K, ...args: Parameters<ProviderEventTypes[K]>): boolean
+
+  waitUntilOpened(): Promise<WalletSession | undefined>
+  waitUntilConnected(): Promise<ConnectDetails>
+}
+
+export interface WalletTransport extends JsonRpcHandler, ProviderMessageTransport, ProviderMessageRequestHandler {
+  register(): void
+  unregister(): void
+
+  notifyOpen(openInfo: { chainId?: string, sessionId?: string, session?: WalletSession, error?: string }): void
+  notifyClose(error?: ProviderRpcError): void
+
+  notifyConnect(connectDetails: ConnectDetails): void
+  notifyAccountsChanged(accounts: string[]): void
+  notifyChainChanged(chainIdHex: string): void
+  notifyNetworks(networks: NetworkConfig[]): void
+}
+
+export interface ProviderMessage<T> {
+  idx: number       // message id number
+  type: string      // message type
+  data: T           // the ethereum json-rpc payload
+  chainId?: number  // chain id which the message is intended
+}
+
+export type ProviderMessageRequest = ProviderMessage<JsonRpcRequest>
+
+export type ProviderMessageResponse = ProviderMessage<JsonRpcResponse>
+
+// ProviderMessageCallback is used to respond to ProviderMessage requests. The error
+// argument is for exceptions during the execution, and response is the response payload
+// which may contain the result or an error payload from the wallet.
+export type ProviderMessageResponseCallback = (error?: ProviderRpcError, response?: ProviderMessageResponse) => void
+
+export interface ProviderRpcError extends Error {
+  message: string
+  code?: number
+  data?: { [key: string]: any }
+}
+
+export interface ProviderMessageRequestHandler {
+  // sendMessageRequest sends a ProviderMessageRequest over the wire to the wallet.
+  // This method is similar to `sendMessage`, but it expects a response to this message.
+  sendMessageRequest(message: ProviderMessageRequest): Promise<ProviderMessageResponse>
+}
+
+export interface ProviderMessageTransport {
+  // handleMessage will handle a message received from the remote wallet
+  handleMessage(message: ProviderMessage<any>): void
+
+  // sendMessage will send the provider message over the wire
+  sendMessage(message: ProviderMessage<any>): void
+}
+
+export type WindowSessionParam = 'sid' | 'net' | 'intent'
+
+export interface WindowSessionParams extends URLSearchParams {
+  get(name: WindowSessionParam): string | null
+  set(name: WindowSessionParam, value: string): void
+}
+
+export class WindowSessionParams extends URLSearchParams {
+  static new(init?: Record<WindowSessionParam, string> | string) {
+    return new URLSearchParams(init) as WindowSessionParams
+  }
+}
+
+export interface TransportSession {
+  sessionId?: string | null
+  networkId?: string | number | null,
+  intent?: OpenWalletIntent,
+}
+
+export enum EventType {
+  OPEN = 'open',
+  CLOSE = 'close',
+
+  MESSAGE = 'message',
+  CONNECT = 'connect',
+  DISCONNECT = 'disconnect',
+  ACCOUNTS_CHANGED = 'accountsChanged',
+  CHAIN_CHANGED = 'chainChanged',
+
+  NETWORKS = 'networks',
+  WALLET_CONTEXT = 'walletContext',
+
+  INIT = 'init',
+  DEBUG = '_debug'
+}
+
+export interface WalletEventTypes {
+  'open': (openInfo: { chainId?: string, sessionId?: string, session?: WalletSession, error?: string }) => void
+  'close': (error?: ProviderRpcError) => void
+
+  'connect': (connectDetails: ConnectDetails) => void
+  'disconnect': (error?: ProviderRpcError) => void
+
+  'accountsChanged': (accounts: string[]) => void
+  'chainChanged': (chainIdHex: string) => void
+
+  'networks': (networks: NetworkConfig[]) => void
+  'walletContext': (walletContext: WalletContext) => void
+}
+
+export interface ProviderEventTypes extends WalletEventTypes {
+  'message': (message: ProviderMessageResponse) => void
+}
+
+export enum OpenState {
+  CLOSED = 0,
+  OPENING = 1,
+  OPENED = 2
+}
+
+export enum InitState {
+  NIL = 0,
+  SENT_NONCE = 1,
+  OK = 2
+}
+
+export interface ConnectOptions {
+  // networkId specifics the default network a dapp would like to connect to. This field
+  // is optional as it can be provided a number of different ways.
+  networkId?: string | number
+
+  // app name of the dapp which will be announced to user on connect screen
+  app?: string
+
+  // origin hint of the dapp's host opening the wallet. This value will automatically
+  // be determined and verified for integrity, and can be omitted.
+  origin?: string
+
+  // expiry number (in seconds) to expire connect session. default is 1 week of seconds.
+  expiry?: number
+
+  // authorize will perform an ETHAuth eip712 signing and return the proof to the dapp.
+  authorize?: boolean
+
+  // askForEmail will prompt to give permission to the dapp to access email address
+  // TODO: this feature is currently not used as the wallet does not report emails yet
+  askForEmail?: boolean
+
+  // refresh flag will force a full re-connect (ie. disconnect then connect again)
+  refresh?: boolean
+
+  // keepWalletOpened will keep the wallet window opened after connecting. The default
+  // is to automatically close the wallet after connecting.
+  keepWalletOpened?: boolean
+}
+
+export interface ConnectDetails {
+  // chainId (in hex) and error are defined by EIP-1193 expected fields
+  chainId?: string
+  error?: string
+
+  // connected flag denotes user-accepted the connect request
+  connected: boolean
+
+  // session include account and network information needed by the dapp wallet provider.
+  session?: WalletSession
+
+  // proof is a signed typedData (EIP-712) payload using ETHAuth domain.
+  // NOTE: the proof is signed to the `authChainId`, as the canonical auth chain.
+  proof?: ETHAuthProof
+
+  // email address provided from wallet to the dapp, as request + accepted
+  // by a user during a connect request
+  email?: string
+}
+
+export type PromptConnectDetails = Pick<ConnectDetails, 'chainId' | 'error' | 'connected' | 'proof' | 'email'>
+
+export type OpenWalletIntent =
+  { type: 'connect'; options?: ConnectOptions } |
+  { type: 'jsonRpcRequest'; method: string }
+
+export interface MessageToSign {
+  message?: string
+  typedData?: TypedData
+  chainId?: number
+}
+
+export interface ETHAuthProof {
+  // eip712 typed-data payload for ETHAuth domain as input
+  typedData: TypedData
+
+  // signature encoded in an ETHAuth proof string
+  proofString: string
+}
+
+export interface WalletSession {
+  // Wallet context
+  walletContext?: WalletContext
+
+  // Account address of the wallet
+  accountAddress?: string
+
+  // Networks in use for the session. The default/dapp network will show
+  // up as the first one in the list as the "main chain"
+  networks?: NetworkConfig[]
+
+  // Caching provider responses for things such as account and chainId
+  providerCache?: { [key: string]: any }
+}
+
+export class ProviderError extends Error {
+  constructor(message?: string) {
+    super(message)
+    this.name = 'ProviderError'
+  }
+}
+
+export const ErrSignedInRequired = new ProviderError('Wallet is not signed in. Connect a wallet and try again.')
+
+// TODO: lets build some nice error handling tools, prob in /utils ...
+
+export interface TypedEventEmitter<Events>{
+  addListener<E extends keyof Events> (event: E, listener: Events[E]): this
+  on<E extends keyof Events> (event: E, listener: Events[E]): this
+  once<E extends keyof Events> (event: E, listener: Events[E]): this
+  prependListener<E extends keyof Events> (event: E, listener: Events[E]): this
+  prependOnceListener<E extends keyof Events> (event: E, listener: Events[E]): this
+
+  off<E extends keyof Events>(event: E, listener: Events[E]): this
+  removeAllListeners<E extends keyof Events> (event?: E): this
+  removeListener<E extends keyof Events> (event: E, listener: Events[E]): this
+
+  emit<E extends keyof Events> (event: E, ...args: Arguments<Events[E]>): boolean
+  eventNames (): (keyof Events | string | symbol)[]
+  listeners<E extends keyof Events> (event: E): Function[]
+  listenerCount<E extends keyof Events> (event: E): number
+}
+
+type Arguments<T> = [T] extends [(...args: infer U) => any]
+  ? U
+  : [T] extends [void] ? [] : [T]

package/src/utils.ts

@@ -0,0 +1,76 @@
+import { BigNumberish, BytesLike } from 'ethers'
+import { WalletContext } from '@0xsequence/network'
+import { WalletConfig, addressOf, DecodedSignature } from '@0xsequence/config'
+import { packMessageData } from '@0xsequence/utils'
+import { Web3Provider } from './provider'
+import { isValidSignature as _isValidSignature, recoverConfig } from '@0xsequence/wallet'
+
+export const isValidSignature = async (
+  address: string,
+  digest: Uint8Array,
+  sig: string,
+  provider: Web3Provider,
+  chainId?: number,
+  walletContext?: WalletContext
+): Promise<boolean | undefined> => {
+  chainId = chainId || await provider.getChainId()
+  walletContext = walletContext || await provider.getSigner().getWalletContext()
+  return _isValidSignature(address, digest, sig, provider, walletContext, chainId)
+}
+
+export const recoverWalletConfig = async (
+  address: string,
+  digest: BytesLike,
+  signature: string | DecodedSignature,
+  chainId: BigNumberish,
+  walletContext?: WalletContext
+): Promise<WalletConfig> => {
+  const subDigest = packMessageData(address, chainId, digest)
+  const config = await recoverConfig(subDigest, signature)
+
+  if (walletContext) {
+    const recoveredWalletAddress = addressOf(config, walletContext)
+    if (config.address && config.address !== recoveredWalletAddress) {
+      throw new Error('recovered address does not match the WalletConfig address, check the WalletContext')
+    } else {
+      config.address = recoveredWalletAddress
+    }
+  }
+
+  return config
+}
+
+export const isBrowserExtension = (): boolean => window.location.protocol === 'chrome-extension:' || window.location.protocol === 'moz-extension:'
+
+// window.localstorage helper
+export class LocalStore<T extends Object = string> {
+  readonly key: string
+
+  constructor(key: string, public def?: T) {
+    this.key = key
+  }
+
+  get(): T | undefined {
+    const val = window.localStorage.getItem(this.key)
+
+    if (val === null) {
+      return this.def
+    }
+
+    try {
+      return JSON.parse(val)
+    } catch (err) {
+      console.error(err)
+    }
+
+    return
+  }
+
+  set(val: T | undefined) {
+    val ? window.localStorage.setItem(this.key, JSON.stringify(val)) : window.localStorage.removeItem(this.key)
+  }
+
+  del() {
+    window.localStorage.removeItem(this.key)
+  }
+}