Skip to content
LogoLogo

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.

Bind a challengeDemo

Walkthrough

Issue the challengeServer

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.

server.ts
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 app

Bind 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>
  )
}

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>
  )
}

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.

server.ts
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 app

Use 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>
  )
}

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>
  )
}

Next steps