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"