Relay Client Auth

Motivation

WalletConnect supports e2e encrypted messaging between multiple clients. Should a recipient be offline, WalletConnect stores the encrypted messages in the recipient's mailbox until they reconnect. The address of the mailbox is a unique sticky client_id that clients present when they connect to WalletConnect.

This document discusses the creation and usage of the client_id for authentication

Overview

WalletConnect expects an Authorization: Bearer <signed jwt> header when establishing the Websocket connection. Where websocket headers are not supported i.e. browsers, use the URL query param ?auth=<signed jwt>. Server should support both of these mechanisms.

The client_id is a DID of the public key for the key pair generated by the client when instantiating the SDK and persisted for the entire lifecycle.

Clients will generate a unique id per app initialization which will be used as a subject when signing a JWT with the client_id as the issuer and is persisted through duration of the app lifecycle.

Specification

Here we describe how a client can generate a Ed25519 key pair to authenticate itself using the public key as it's client id

Additionally we describe how we can construct and sign a JWT using a client-side generated unique id as subject

Finally we describe how the public key is encoded as did:key identifier which is used as client id.

Client authentication is described with a did-jwt using the following claims:

iat - timestamp when jwt was issued

exp - timestamp when jwt must expire

iss - did:key of client id key.

aud - relay server URL

sub - random nonce (unique per connection)

act - description of action intent. Must be equal to "client_auth"