Sign challenges
A Tempo Account signs a challenge of a server at sign-in, and the server verifies it.
Overview
A server that acts for an address, such as a credit to it, needs proof that the user controls it. The server issues a one-time challenge, the Tempo Account signs it at sign-in, and the server spends it and verifies the signature.
The demo signs a challenge of the site's server in Tempo ID's dialog. The server returns the proven address, then refuses the same proof.
Walkthrough
The steps build a React page and a Hono server.
Issue the challengeServer
Issue a message, and keep it in a store until it expires. Tempo ID's dialog shows the message to the user before the signature.
- Name the app's host, so the signature serves no other server.
- Add a random value, so no two challenges are equal.
- Use plain text, with newlines. Tempo ID refuses control and format characters, such as a bidi override.
import { Store } from 'accounts'
import { Hono } from 'hono'
const app = new Hono()
const challenges = Store.memory()
app.post('/api/challenge', async (c) => {
const { host } = new URL(c.req.url)
const challenge = [
`${host} asks for a proof of your Tempo Account.`,
`Nonce: ${crypto.randomUUID()}`,
].join('\n')
// The challenge lasts 5 minutes.
const expiresAt = Date.now() + 5 * 60 * 1000
await challenges.setItem(challenge, true, { expiresAt })
return c.json({ challenge })
})
export default appCreate the instanceClient
The page's origin is its client ID, so the app needs no registration.
import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Sign in with the challengeClient
Pass the challenge as challenge of dialog.signIn, with accessKey set to false. Tempo ID's dialog shows it, and the account's owner signs its EIP-191 hash, as personal_sign does. With an access key, the key authorization signs it instead, as Bind challenges describes.
The sign-ins of other plugins take a challenge too, such as redirect.signIn and device.signIn.
import { accounts } from './tempo.config.js'
export function App() {
return (
<button
onClick={async () => {
const issued = await fetch('/api/challenge', { method: 'POST' })
const { challenge } = await issued.json()
const session = await accounts.dialog.signIn({
accessKey: false,
challenge,
})
}}
type="button"
>
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })The session holds the account as address, and the signature as challengeSignature.
Send the proofClient
Send the account, the challenge, and the signature to the server, with no token.
import { useState } from 'react'
import { accounts } from './tempo.config.js'
export function App() {
const [proven, setProven] = useState<string>()
if (proven) return <p>The server verified {proven}.</p>
return (
<button
onClick={async () => {
const issued = await fetch('/api/challenge', { method: 'POST' })
const { challenge } = await issued.json()
const session = await accounts.dialog.signIn({
accessKey: false,
challenge,
})
const response = await fetch('/api/verify', {
body: JSON.stringify({
address: session.address,
challenge,
signature: session.challengeSignature,
}),
headers: { 'content-type': 'application/json' },
method: 'POST',
})
const { address } = await response.json()
setProven(address)
}}
type="button"
>
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Spend the challengeServer
The chain does not spend a challenge, so a copied signature verifies again. Take the challenge from the store with takeItem before the signature check, so the server refuses an unknown or spent challenge.
import { Store } from 'accounts'
import { Hono } from 'hono'
import { isAddress, isHex } from 'viem'
const app = new Hono()
const challenges = Store.memory()
app.post('/api/challenge', async (c) => {
const { host } = new URL(c.req.url)
const challenge = [
`${host} asks for a proof of your Tempo Account.`,
`Nonce: ${crypto.randomUUID()}`,
].join('\n')
// The challenge lasts 5 minutes.
const expiresAt = Date.now() + 5 * 60 * 1000
await challenges.setItem(challenge, true, { expiresAt })
return c.json({ challenge })
})
app.post('/api/verify', async (c) => {
const { address, challenge, signature } = await c.req.json()
if (
!isAddress(address) ||
typeof challenge !== 'string' ||
!isHex(signature)
)
return c.json({ error: 'invalid_request' }, 400)
// `takeItem` reads and deletes in one step, so one request spends it.
if (!(await challenges.takeItem?.(challenge)))
return c.json({ error: 'invalid_challenge' }, 400)
return c.json({})
})
export default appVerify the signatureServer
Viem's verifyMessage counts the account owner's signature on the instance's chain, and refuses an access key's.
import { Store } from 'accounts'
import { Hono } from 'hono'
import { isAddress, isHex } from 'viem'
import { createClient, http, isAddress, isHex } from 'viem'
import { verifyMessage } from 'viem/actions'
import { tempoTestnet } from 'viem/chains'
const app = new Hono()
const challenges = Store.memory()
const client = createClient({ chain: tempoTestnet, transport: http() })
app.post('/api/challenge', async (c) => {
const { host } = new URL(c.req.url)
const challenge = [
`${host} asks for a proof of your Tempo Account.`,
`Nonce: ${crypto.randomUUID()}`,
].join('\n')
// The challenge lasts 5 minutes.
const expiresAt = Date.now() + 5 * 60 * 1000
await challenges.setItem(challenge, true, { expiresAt })
return c.json({ challenge })
})
app.post('/api/verify', async (c) => {
const { address, challenge, signature } = await c.req.json()
if (
!isAddress(address) ||
typeof challenge !== 'string' ||
!isHex(signature)
)
return c.json({ error: 'invalid_request' }, 400)
// `takeItem` reads and deletes in one step, so one request spends it.
if (!(await challenges.takeItem?.(challenge)))
return c.json({ error: 'invalid_challenge' }, 400)
const valid = await verifyMessage(client, {
address,
message: challenge,
signature,
})
if (!valid) return c.json({ error: 'invalid_signature' }, 400)
// The user controls `address`.
return c.json({ address })
})
export default appUse cases
Each use case sets the challenge of dialog.signIn in another form, or beside another option.
Fetch the challenge in the dialog
A function as challenge returns the challenge after the dialog opens. The call then comes before any await of the click handler, as the dialog's popup fallback needs. Its signal aborts once the call ends.
import { accounts } from './tempo.config.js'
export function App() {
async function signIn() {
let challenge = ''
const session = await accounts.dialog.signIn({
accessKey: false,
challenge: async (signal) => {
const issued = await fetch('/api/challenge', { method: 'POST', signal })
challenge = ((await issued.json()) as { challenge: string }).challenge
return challenge
},
})
await fetch('/api/verify', {
body: JSON.stringify({
address: session.address,
challenge,
signature: session.challengeSignature,
}),
headers: { 'content-type': 'application/json' },
method: 'POST',
})
}
return (
<button onClick={() => void signIn()} type="button">
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })Bind the challenge to an access key
With an accessKey request, the key authorization of the access key binds the challenge, and challengeSignature is its signature. Viem's verifyMessage refuses such a signature, so the server verifies it as Bind challenges shows.
import { accounts } from './tempo.config.js'
export function App() {
return (
<button
onClick={() =>
accounts.dialog.signIn({
accessKey: {
expiry: '1d',
limits: [{ limit: '100', token: 'ousd' }],
},
challenge: async (signal) => {
const issued = await fetch('/api/challenge', {
method: 'POST',
signal,
})
return ((await issued.json()) as { challenge: string }).challenge
},
})
}
type="button"
>
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
export const accounts = Accounts.create({ chain: 'testnet' })