ethwebtoken

README

 ____ ____ ____ ____ ____ ____ ____ ____ ____ ____ ____ 
||e |||t |||h |||w |||e |||b |||t |||o |||k |||e |||n ||
||__|||__|||__|||__|||__|||__|||__|||__|||__|||__|||__||
|/__\|/__\|/__\|/__\|/__\|/__\|/__\|/__\|/__\|/__\|/__\|

Format

ewt = eth.<address>.<claims>.<signature>

Address

The account address in hex encoding, ie. '0x9e63b5BF4b31A7F8d5D8b4f54CD361344Eb744C5'.

Note, you should not take the account address in the ewt at face value -- you must parse the EWT and validate it with the library methods provided. The address is included when used to verify smart wallet based accounts (aka contract-based accounts).

Claims

a base64 encoded JSON object of

interface EWTClaims {
  app: string
  iat: number
  exp: number
  n?: number
  typ?: string
  ogn?: string
}

Fields:

• app (required) - App identifier requesting the issuance of the token
• iat (required) - Issued at unix timestamp of when the token has been signed/issued
• exp (required) - Expired at unix timestamp of when the token is valid until
• n (optional) - Nonce value which can be used as a challenge number for added security
• typ (optional) - Type of authorization for this ewt
• ogn (optional) - Domain origin requesting the issuance of the token

Signature

Signature value of the claims message payload. The signature is computed by the EIP712 eth_signTypedData call of the claims object. The signature may be recoverable with ECRecover to determine the EOA address, or you may have a different encoding such as one used with EIP-1271, to validate the contract-based account signature.

HTTP Authorization Header

EWT's can be used similarly to JWT's, passed to the 'Authorization' header of a HTTP request.

The format of the header is:

Authorization: Bearer <ewt>

for example:

Authorization: Bearer eth.0x8ec767428b824b39c307085e1b9f035464907d31.eyJpYXQiOjE1OTQ3NDMxODEsImV4cCI6MTU5NDc0MzQ4MX0.0x9070796b0ed4597fdfd3ed89c13f26422dd6375329939ab0aa0a65ddafbe10af1048a3bebfdf390127270b1955fa1301afaa10df98890b6a2924ef812acf2ab71c

Example EWT encoding / decoding

EOA account signature

ewt = eth.0x89d9f8f31817badb5d718cd6fb483b71dbd2dfed.eyJhcHAiOiJFV1RUZXN0IiwiaWF0IjoxNTk1NTMwODQwLCJleHAiOjE1OTU1MzExNDB9.0x233ab9164a677a41acc8d52c9e1d1a621acebf9bc8d956c8474618b589acebe10cc350deb4b02bf6951cec8bd23507170f204ca326a5a264b8f6f67fa2619c251c

decodes & verifies to:

• account address: 0x89D9F8f31817BAdb5D718CD6fb483b71DbD2dfeD
• claims: {"app":"EWTTest","iat":1595530840,"exp":1595531140}
• signature: 0x233ab9164a677a41acc8d52c9e1d1a621acebf9bc8d956c8474618b589acebe10cc350deb4b02bf6951cec8bd23507170f204ca326a5a264b8f6f67fa2619c251c

Contract-based account signature (verifiable with EIP 1271)

ewt = eth.0x9e63b5bf4b31a7f8d5d8b4f54cd361344eb744c5.eyJpYXQiOjE1OTQ3NDM4NDgsImV4cCI6MTYyNjI3OTg0OCwibiI6MTMzN30.0x000100012dd090aec5e4a9678f7968533c10fc42b07b9a23fa3b719f79a861adcfc7e1d958e3521bb061c34072f5435681390ccc9be19bf9da32320bd2356d0b4b4d316b1c02

decodes & verifies to:

• account address: 0x9e63b5bf4b31a7f8d5d8b4f54cd361344eb744c5
• message: {"iat":1594743848,"exp":1626279848,"n":1337}
• signature: 0x000100012dd090aec5e4a9678f7968533c10fc42b07b9a23fa3b719f79a861adcfc7e1d958e3521bb061c34072f5435681390ccc9be19bf9da32320bd2356d0b4b4d316b1c02

LICENSE

MIT

Documentation

Index

• Constants
• func Base64UrlDecode(s string) ([]byte, error)
• func Base64UrlEncode(s []byte) string
• func ValidateContractAccountToken(ctx context.Context, provider *ethrpc.Provider, chainID *big.Int, token *Token) (bool, string, error)
• func ValidateEOASignature(address string, message []byte, signatureHex string) (bool, error)
• func ValidateEOAToken(ctx context.Context, provider *ethrpc.Provider, chainID *big.Int, token *Token) (bool, string, error)
• type Claims
  • func (c Claims) Map() map[string]interface{}
  • func (c Claims) MessageDigest() ([]byte, error)
  • func (c *Claims) SetExpiryIn(tm time.Duration)
  • func (c *Claims) SetIssuedAtNow()
  • func (c Claims) TypedData() (*ethcoder.TypedData, error)
  • func (c Claims) Valid() error
• type ETHWebToken
  • func New(validators ...ValidatorFunc) (*ETHWebToken, error)
  • func (w *ETHWebToken) ConfigJsonRpcProvider(ethereumJsonRpcURL string, optChainId ...int64) error
  • func (w *ETHWebToken) ConfigValidators(validators ...ValidatorFunc) error
  • func (w *ETHWebToken) DecodeToken(tokenString string) (bool, *Token, error)
  • func (w *ETHWebToken) EncodeToken(token *Token) (string, error)
  • func (w *ETHWebToken) ValidateToken(token *Token) (bool, error)
  • func (w *ETHWebToken) ValidateTokenClaims(token *Token) (bool, error)
  • func (w *ETHWebToken) ValidateTokenSignature(token *Token) bool
  • func (w *ETHWebToken) Validators() []ValidatorFunc
• type Token
  • func NewToken() *Token
  • func (t *Token) MessageDigest() ([]byte, error)
  • func (t *Token) MessageTypedData() (*ethcoder.TypedData, error)
• type ValidatorFunc

Constants

const (
	EWTVersion = "1"

	EWTPrefix = "eth"
)

const (
	// IsValidSignatureBytes32 is the EIP-1271 magic value we test
	IsValidSignatureBytes32MagicValue = "0x1626ba7e"
)

Functions

func Base64UrlDecode

func Base64UrlDecode(s string) ([]byte, error)

Base64 url-variant decoding with padding stripped. Note, this is the same encoding format as JWT.

func Base64UrlEncode

func Base64UrlEncode(s []byte) string

Base64 url-variant encoding with padding stripped. Note, this is the same encoding format as JWT.

func ValidateContractAccountToken

func ValidateContractAccountToken(ctx context.Context, provider *ethrpc.Provider, chainID *big.Int, token *Token) (bool, string, error)

ValidateContractAccountToken verifies the account proof of the provided ewt, testing if the token has been signed with a smart-contract based account by calling the EIP-1271 method of the remote contract. This method will return success/failure, the account address as a string, and any errors. The wallet contract must be deployed in order for this call to be successful. In order test an undeployed smart-wallet, you will have to implement your own custom validator method.

func ValidateEOASignature

func ValidateEOASignature(address string, message []byte, signatureHex string) (bool, error)

Validate the public key address of an Ethereum signed message

func ValidateEOAToken

func ValidateEOAToken(ctx context.Context, provider *ethrpc.Provider, chainID *big.Int, token *Token) (bool, string, error)

ValidateEOAToken verifies the account proof of the provided ewt, testing if the token has been signed with an EOA (externally owned account) and will return success/failture, the account address as a string, and any errors.

Types

type Claims

type Claims struct {
	App        string `json:"app,omitempty"`
	IssuedAt   int64  `json:"iat,omitempty"`
	ExpiresAt  int64  `json:"exp,omitempty"`
	Nonce      uint64 `json:"n,omitempty"`
	Type       string `json:"typ,omitempty"`
	Origin     string `json:"ogn,omitempty"`
	EWTVersion string `json:"v,omitempty"`
}

func (Claims) Map

func (c Claims) Map() map[string]interface{}

func (Claims) MessageDigest

func (c Claims) MessageDigest() ([]byte, error)

func (*Claims) SetExpiryIn

func (c *Claims) SetExpiryIn(tm time.Duration)

func (*Claims) SetIssuedAtNow

func (c *Claims) SetIssuedAtNow()

func (Claims) TypedData

func (c Claims) TypedData() (*ethcoder.TypedData, error)

func (Claims) Valid

func (c Claims) Valid() error

type ETHWebToken

type ETHWebToken struct {
	// contains filtered or unexported fields
}

func New

func New(validators ...ValidatorFunc) (*ETHWebToken, error)

func (*ETHWebToken) ConfigJsonRpcProvider

func (w *ETHWebToken) ConfigJsonRpcProvider(ethereumJsonRpcURL string, optChainId ...int64) error

func (*ETHWebToken) ConfigValidators

func (w *ETHWebToken) ConfigValidators(validators ...ValidatorFunc) error

func (*ETHWebToken) DecodeToken

func (w *ETHWebToken) DecodeToken(tokenString string) (bool, *Token, error)

DecodeToken will decode an EWT token string and return a Token object

func (*ETHWebToken) EncodeToken

func (w *ETHWebToken) EncodeToken(token *Token) (string, error)

EncodeToken will encode a Token object and return the EWT token string

func (*ETHWebToken) ValidateToken

func (w *ETHWebToken) ValidateToken(token *Token) (bool, error)

func (*ETHWebToken) ValidateTokenClaims

func (w *ETHWebToken) ValidateTokenClaims(token *Token) (bool, error)

func (*ETHWebToken) ValidateTokenSignature

func (w *ETHWebToken) ValidateTokenSignature(token *Token) bool

func (*ETHWebToken) Validators

func (w *ETHWebToken) Validators() []ValidatorFunc

type Token

type Token struct {
	// "eth" prefix
	Prefix string

	// Account addres (in hex)
	Address string

	// Claims object, aka, the message key of an EIP712 signature
	Claims Claims

	// Signature of the message by the account address above (in hex)
	Signature string
}

func NewToken

func NewToken() *Token

func (*Token) MessageDigest

func (t *Token) MessageDigest() ([]byte, error)

func (*Token) MessageTypedData

func (t *Token) MessageTypedData() (*ethcoder.TypedData, error)

type ValidatorFunc

type ValidatorFunc func(ctx context.Context, provider *ethrpc.Provider, chainID *big.Int, token *Token) (bool, string, error)