Skip to content
LogoLogo

Verify signed messages

A server verifies a message that the access key signs for a Tempo Account.

Overview

After a sign-in, the access key signs messages for the Tempo Account with no prompt. The chain accepts every live access key of the account, also another app's, so a server counts the signature only if the user's access token names the access key. A signature verifies only after the access key's first transaction registers it.

The demo signs in, sends 0.01 OUSD as the access key's first transaction, and signs a message, which the site's server verifies. Before the transaction, the server refuses the signature.

Verify a signed messageDemo

Walkthrough

The steps build a React page and a Hono server.

Install the packages

Create the instanceClient

The react plugin adds useSession, and the viem plugin adds signMessage.

tempo.config.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  // Each sign-in requests an access key that sends up to 100 OUSD for a day.
  accessKey: () => ({
    expiry: '1d',
    limits: [{ limit: '100', token: 'ousd' }],
  }),
  chain: 'testnet',
  plugins: [react(), viem()],
})

Sign the user inClient

The session's accessKey.account is the Tempo Account that the access key signs for.

import { accounts } from './tempo.config.js'
 
export function App() {
  const { session } = accounts.useSession()
  const address = session?.accessKey?.account 
 
  if (!address)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return (
    <main>
      <p>Tempo Account {address}</p>
    </main>
  )
}

Send the first transactionClient

The first transaction carries the key authorization, and registers the access key on the chain.

import { accounts } from './tempo.config.js'
 
export function App() {
  const { session } = accounts.useSession()
  const address = session?.accessKey?.account
 
  if (!address)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return (
    <main>
      <p>Tempo Account {address}</p>
      <button
        onClick={() =>
          accounts.pay({ 
            amount: '0.01', 
            to: '0x000000000000000000000000000000000000dEaD', 
            token: 'ousd', 
          }) 
        }
        type="button"
      > 
        Send 0.01 OUSD 
      </button> 
    </main>
  )
}

Sign the messageClient

import { accounts } from './tempo.config.js'
 
const message = 'I agree to the terms of app.example.'
 
export function App() {
  const { session } = accounts.useSession()
  const address = session?.accessKey?.account
 
  if (!address)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return (
    <main>
      <p>Tempo Account {address}</p>
      <button
        onClick={() =>
          accounts.pay({
            amount: '0.01',
            to: '0x000000000000000000000000000000000000dEaD',
            token: 'ousd',
          })
        }
        type="button"
      >
        Send 0.01 OUSD
      </button>
      <button
        onClick={async () => { 
          const signature = await accounts.signMessage({ message }) 
        }}
        type="button"
      > 
        Prove the account 
      </button> 
    </main>
  )
}

Send the signatureClient

session.fetch sends the signature with the session's access token.

import { useState } from 'react'
import { accounts } from './tempo.config.js'
 
const message = 'I agree to the terms of app.example.'
 
export function App() {
  const { session } = accounts.useSession()
  const [proven, setProven] = useState<string>() 
  const address = session?.accessKey?.account
 
  if (!address)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return (
    <main>
      <p>Tempo Account {address}</p>
      <button
        onClick={() =>
          accounts.pay({
            amount: '0.01',
            to: '0x000000000000000000000000000000000000dEaD',
            token: 'ousd',
          })
        }
        type="button"
      >
        Send 0.01 OUSD
      </button>
      <button
        onClick={async () => {
          const signature = await accounts.signMessage({ message })
          const response = await accounts.session.fetch({ 
            init: { 
              body: JSON.stringify({ address, message, signature }), 
              headers: { 'content-type': 'application/json' }, 
              method: 'POST', 
            }, 
            url: '/api/message', 
          }) 
          const body = await response.json() 
          setProven(body.address) 
        }}
        type="button"
      >
        Prove the account
      </button>
      {proven && <p>The server verified {proven}.</p>}
    </main>
  )
}

Create the instance of the serverServer

Name the app's clientId, so the instance accepts only the app's access tokens.

api.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [viem()],
})

Verify the signatureServer

verifyMessage verifies the access token, then the signature. An access key's signature counts only if the token names it for the address, on the instance's chain. The owner's signature also counts.

api.ts
import { AccessToken, Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
import { Hono } from 'hono'
import { isAddress, isHex } from 'viem'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [viem()],
})
 
const app = new Hono()
 
app.post('/api/message', async (c) => {
  const [, accessToken] = c.req.header('authorization')?.split(' ') ?? []
  if (!accessToken) return c.json({ error: 'invalid_token' }, 401)
 
  const { address, message, signature } = await c.req.json()
  if (
    !isAddress(address) ||
    typeof message !== 'string' ||
    !isHex(signature)
  )
    return c.json({ error: 'invalid_request' }, 400)
 
  try {
    const valid = await accounts.verifyMessage({
      accessToken,
      address,
      message,
      signature,
    })
    if (!valid) return c.json({ error: 'invalid_signature' }, 400)
  } catch (error) {
    if (error instanceof AccessToken.InvalidError)
      return c.json({ error: 'invalid_token' }, 401)
    throw error
  }
 
  // The access key of the app signed `message` for `address`.
  return c.json({ address })
})
 
export default app

A signature verifies each time. If a message counts once, add a server challenge to it, and spend the challenge.

Use cases

Each use case sets one option of verifyMessage or of the viem plugin, or verifies another kind of signature.

Verify a DPoP token

If a DPoP key binds the access token, pass the request's proof as dpop. verifyMessage refuses no repeated proof, so the API refuses one with tokens.verifyAccessToken, as Bind DPoP keys shows.

api.ts
import { AccessToken, Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
import { Hono } from 'hono'
import { isAddress, isHex } from 'viem'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [viem()],
})
 
const app = new Hono()
 
app.post('/api/message', async (c) => {
  const [scheme, accessToken] = c.req.header('authorization')?.split(' ') ?? [] 
  if (!accessToken) return c.json({ error: 'invalid_token' }, 401)
 
  const { address, message, signature } = await c.req.json()
  if (
    !isAddress(address) ||
    typeof message !== 'string' ||
    !isHex(signature)
  )
    return c.json({ error: 'invalid_request' }, 400)
 
  try {
    const valid = await accounts.verifyMessage({
      accessToken,
      address,
      dpop: {
        method: c.req.method,
        proof: c.req.header('dpop'),
        scheme,
        url: c.req.url,
      },
      message,
      signature,
    })
    if (!valid) return c.json({ error: 'invalid_signature' }, 400)
  } catch (error) {
    if (error instanceof AccessToken.InvalidError)
      return c.json({ error: 'invalid_token' }, 401)
    throw error
  }
 
  return c.json({ address })
})
 
export default app

Verify typed data

accounts.signTypedData signs typed data (EIP-712) with the access key. accounts.verifyTypedData verifies it with the same accessToken.

api.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
import type { Address, Hex } from 'viem'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [viem()],
})
 
export async function verify(options: {
  accessToken: string
  address: Address
  signature: Hex
}) {
  return await accounts.verifyTypedData({
    accessToken: options.accessToken,
    address: options.address,
    domain: { name: 'app.example', version: '1' },
    message: { terms: 'I agree to the terms of app.example.' },
    primaryType: 'Agreement',
    signature: options.signature,
    types: { Agreement: [{ name: 'terms', type: 'string' }] },
  })
}

Verify a hash

accounts.verifyHash verifies a signature of a 32-byte hash, such as one that the app computed itself. An access key's signature counts as verifyMessage decides.

api.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [viem()],
})
 
export async function verify(
  options: Parameters<typeof accounts.verifyHash>[0],
) {
  return await accounts.verifyHash(options) 
}

Accept the tokens of several apps

The accessTokens option of the plugin takes the options of the access token's verifier, as the tokens plugin does. With clientIds, a server counts the access keys of each named app.

api.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
 
const accounts = Accounts.create({
  chain: 'testnet',
  clientId: 'https://app.example',
  plugins: [
    viem({
      accessTokens: {
        clientIds: ['https://app.example', 'https://admin.example'],
      },
    }),
  ],
})

Next steps