Bind challenges
Bind a server's challenge to an access key at sign-in, so the server knows the access key that signs.
Overview
A sign-in can carry a server's challenge, whose EIP-191 hash the key authorization holds as its witness. The account owner's one signature thus proves to the server which access key the user authorized for the app.
The demo requests a challenge from a route of the site, signs a user in with it, and sends the key authorization to a second route, which verifies it.
Walkthrough
The message names the server's origin and a nonce, and the store keeps it for five minutes. Tempo ID's approval page shows it to the user.
import { Store } from 'accounts'
import { Hono } from 'hono'
const challenges = Store.memory()
const app = new Hono()
app.post('/challenge', async (c) => {
const id = crypto.randomUUID()
const challenge = `app.example asks for proof of this sign-in.\n\nNonce: ${id}`
await challenges.setItem(id, challenge, { expiresAt: Date.now() + 300_000 })
return c.json({ challenge, id })
})
export default appBind the challenge at sign-inClient
The click requests the challenge, and passes it to the sign-in as challenge.
import { useState } from 'react'
import { accounts } from './tempo.config.js'
type Issued = { challenge: string; id: string }
type Proven = { accessKey: string; account: string }
export function App() {
const [proven, setProven] = useState<Proven>()
async function signIn() {
const response = await fetch('/challenge', { method: 'POST' })
const issued: Issued = await response.json()
const session = await accounts.dialog.signIn({
challenge: issued.challenge,
})
}
if (proven) return <p>The server verified access key {proven.accessKey}.</p>
return (
<button onClick={signIn} type="button">
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [react()],
})Send the proofClient
session.fetch posts the signed key authorization with the session's access token. The access key itself never leaves the page.
import { useState } from 'react'
import { accounts } from './tempo.config.js'
type Issued = { challenge: string; id: string }
type Proven = { accessKey: string; account: string }
export function App() {
const [proven, setProven] = useState<Proven>()
async function signIn() {
const challenge = await fetch('/challenge', { method: 'POST' })
const issued: Issued = await challenge.json()
const session = await accounts.dialog.signIn({
challenge: issued.challenge,
})
const response = await accounts.session.fetch({
init: {
body: JSON.stringify({
id: issued.id,
keyAuthorization: session.accessKey!.keyAuthorization,
}),
headers: { 'content-type': 'application/json' },
method: 'POST',
},
url: '/verify',
})
setProven(await response.json())
}
if (proven) return <p>The server verified access key {proven.accessKey}.</p>
return (
<button onClick={signIn} type="button">
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [react()],
})Verify the proofServer
The store's takeItem reads and deletes the challenge atomically, so each challenge verifies at most once.
The tokens plugin accepts only the access tokens of the app's own client ID. tokens.verifyChallenge then checks the witness, that the token names the access key, and the owner's signature, on the instance's chain.
import { Accounts, Challenge, Store } from 'accounts'
import { tokens } from 'accounts/plugins'
import { Hono } from 'hono'
const accounts = Accounts.create({
chain: 'testnet',
clientId: 'https://app.example',
plugins: [tokens()],
})
const challenges = Store.memory()
const app = new Hono()
app.post('/challenge', async (c) => {
const id = crypto.randomUUID()
const challenge = `app.example asks for proof of this sign-in.\n\nNonce: ${id}`
await challenges.setItem(id, challenge, { expiresAt: Date.now() + 300_000 })
return c.json({ challenge, id })
})
app.post('/verify', async (c) => {
const { id, keyAuthorization } = await c.req.json()
const token = await accounts.tokens.verifyAccessToken(c.req.raw)
if (!token) return c.json({ error: 'invalid_token' }, 401)
// The chain spends no witness, so the server spends the challenge.
const challenge = await challenges.takeItem?.(id)
if (typeof challenge !== 'string')
return c.json({ error: 'invalid_request' }, 400)
try {
const { accessKey, account } = await accounts.tokens.verifyChallenge({
accessToken: token,
challenge,
keyAuthorization,
})
return c.json({ accessKey, account })
} catch (error) {
if (error instanceof Challenge.InvalidError)
return c.json({ error: 'invalid_proof' }, 400)
throw error
}
})
export default appUse cases
Each use case passes the challenge of a sign-in in another form, or to another call.
Fetch the challenge after the dialog opens
A function as challenge fetches the message after the dialog or the popup opens. The click thus opens a popup also where the page cannot frame the dialog, since no request runs before it.
import { accounts } from './tempo.config.js'
type Issued = { challenge: string; id: string }
export function App() {
async function signIn() {
const issued: Issued[] = []
const session = await accounts.dialog.signIn({
challenge: async (signal) => {
const response = await fetch('/challenge', { method: 'POST', signal })
issued.push(await response.json())
return issued[0]!.challenge
},
})
await accounts.session.fetch({
init: {
body: JSON.stringify({
id: issued[0]!.id,
keyAuthorization: session.accessKey!.keyAuthorization,
}),
headers: { 'content-type': 'application/json' },
method: 'POST',
},
url: '/verify',
})
}
return (
<button onClick={signIn} type="button">
Sign in with Tempo
</button>
)
}import { Accounts } from 'accounts'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [react()],
})Bind a challenge with no page
accounts.authorize takes a challenge too, and shows no page. Only a first-party app with the tempo-id:sign scope may send it, and the call returns undefined without a Tempo ID session.
import { accounts } from './tempo.config.js'
type Issued = { challenge: string; id: string }
export function App() {
async function authorize() {
const response = await fetch('/challenge', { method: 'POST' })
const issued: Issued = await response.json()
const session = await accounts.authorize({ challenge: issued.challenge })
if (!session?.accessKey) return
await accounts.session.fetch({
init: {
body: JSON.stringify({
id: issued.id,
keyAuthorization: session.accessKey.keyAuthorization,
}),
headers: { 'content-type': 'application/json' },
method: 'POST',
},
url: '/verify',
})
}
return (
<button onClick={authorize} type="button">
Prove the access key
</button>
)
}import { Accounts } from 'accounts'
import { react } from 'accounts/react'
export const accounts = Accounts.create({
accessKey: () => ({
expiry: '1d',
limits: [{ limit: '10', token: 'ousd' }],
}),
chain: 'testnet',
plugins: [react()],
})