@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/src/app/routes/__root.tsx

@@ -0,0 +1,91 @@
+/**
+ * The document of every page: its language, the theme tokens on the root element, the head, and the
+ * API and query clients that every page shares. The `chain` search parameter stays on every page
+ * that the router opens.
+ * @module
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  retainSearchParams,
+  Scripts,
+} from '@tanstack/react-router'
+import { type ReactNode, useState } from 'react'
+import reset from 'zyzz/reset.css?url'
+import * as Chain from '../../internal/Chain.js'
+import * as Client from '../lib/Client.js'
+import { script, vars } from '../zyzz.config.js'
+
+export const Route = createRootRoute({
+  component: Root,
+  head: () => ({
+    links: [
+      { href: reset, rel: 'stylesheet' },
+      // The pages have no icon, so an empty one keeps the browser from requesting `/favicon.ico`.
+      { href: 'data:,', rel: 'icon' },
+    ],
+    meta: [
+      { charSet: 'utf-8' },
+      { content: 'width=device-width, initial-scale=1', name: 'viewport' },
+      { title: 'Tempo ID' },
+      { content: 'Sign in to Tempo.', name: 'description' },
+    ],
+    // Restores a saved color scheme before the first paint.
+    scripts: [{ children: script() }],
+  }),
+  // A chosen chain stays on every page that the router opens.
+  search: { middlewares: [retainSearchParams(['chain'])] },
+  shellComponent: Document,
+  validateSearch: (search: Record<string, unknown>): Search => {
+    // The router merges each route's search over the parsed query, so an invalid value is
+    // replaced, not left in place, and the retained parameter never carries it.
+    const chain = Chain.schema.safeParse(search.chain)
+    return { chain: chain.success ? chain.data : undefined }
+  },
+})
+
+/** The search parameters that every page reads. */
+type Search = {
+  /** The chain whose balances pages show, in place of Tempo mainnet. */
+  chain?: Chain.Chain | undefined
+}
+
+/** Renders the page with the clients that every page shares. */
+function Root() {
+  // One of each for the document's lifetime, so neither holds state of another visitor.
+  const [client] = useState(Client.create)
+  const [queryClient] = useState(() => new QueryClient())
+
+  return (
+    <Client.Context value={client}>
+      <QueryClientProvider client={queryClient}>
+        <Outlet />
+      </QueryClientProvider>
+    </Client.Context>
+  )
+}
+
+/** Renders the HTML document around the page. */
+function Document(props: Document.Props) {
+  return (
+    // The scheme script changes the root element's classes before React hydrates.
+    <html className={vars().className} lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {props.children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+
+declare namespace Document {
+  type Props = {
+    /** The page. */
+    children: ReactNode
+  }
+}

package/src/app/routes/authorize.tsx

@@ -0,0 +1,197 @@
+/**
+ * The approval page: the signed-in user approves or denies an app's authorization request, and the
+ * browser returns to the app's redirect. A passkey-owned account signs the key with its passkey in
+ * this browser, which takes a second request.
+ * @module
+ */
+import { useMutation } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { parseResponse } from 'hono/client'
+import { Authentication } from 'webauthx/client'
+import * as Client from '../lib/Client.js'
+import * as Loader from '../lib/Loader.js'
+import { Approval, InvalidRequest } from '../screens/Approval.js'
+import { style } from '../zyzz.config.js'
+
+/** Wraps a failure of the browser's passkey ceremony, which reaches no API. */
+class CeremonyError extends Error {
+  override name = 'Page.CeremonyError'
+}
+
+export const Route = createFileRoute('/authorize')({
+  // The route splitter drops the style namespace, so the component stays in this chunk.
+  codeSplitGroupings: [],
+  component: () => <Page {...Route.useLoaderData()} />,
+  /**
+   * Sends an app's request without Better Auth's signature to `/oauth2/authorize`, which takes the
+   * same query and returns the browser here signed. The request gains `response_type=code` and
+   * `code_challenge_method=S256` when it names neither, since `/oauth2/authorize` requires both.
+   * Sends a visitor without a session to sign-in, with the query unchanged, so the sign-in
+   * continues the request. Otherwise returns the request that `GET /v1/authorize/request` reads,
+   * and redirects a key that Tempo ID refuses to the app with the refusal.
+   */
+  loader: async (match): Promise<Page.Props> => {
+    const { searchStr } = match.location
+    // Better Auth reads the query with `URLSearchParams`, so the page reads it the same way, and a
+    // malformed escape cannot show one request and approve another.
+    const query = new URLSearchParams(searchStr)
+    if (!query.get('sig')) {
+      const forwarded = new URLSearchParams(query)
+      if (!forwarded.has('code_challenge_method'))
+        forwarded.set('code_challenge_method', 'S256')
+      if (!forwarded.has('response_type'))
+        forwarded.set('response_type', 'code')
+      Loader.redirect({
+        document: true,
+        href: `/oauth2/authorize?${forwarded}`,
+      })
+    }
+
+    const client = Client.create()
+    const result = await (async () => {
+      try {
+        return await parseResponse(
+          client.v1.authorize.request.$get({
+            query: { oauth_query: query.toString() },
+          }),
+        )
+      } catch (error) {
+        if (Client.reason(error) === 'session_required')
+          Loader.redirect({ href: `/login${searchStr}` })
+        throw error
+      }
+    })()
+    if ('redirect' in result)
+      Loader.redirect({ document: true, href: result.redirect })
+    return { request: result.request }
+  },
+  // The loader reads the whole query, so a change to any parameter loads the page again.
+  loaderDeps: (match) => ({ search: match.search }),
+})
+
+/** Renders the page. */
+function Page(props: Page.Props) {
+  const client = Client.use()
+  const consent = useMutation({
+    async mutationFn(variables: { accept: boolean }) {
+      const json = {
+        accept: variables.accept,
+        // Approval signs for the account that the page shows.
+        ...(props.request?.key?.account
+          ? { account: props.request.key.account }
+          : {}),
+        oauth_query: window.location.search.slice(1),
+        session_id: props.request?.session ?? '',
+      }
+      const decided = await parseResponse(
+        client.v1.authorize.consent.$post({ json }),
+      )
+      if (!('step' in decided)) return decided
+
+      // The passkey signs the key authorization's digest, which the step's options carry.
+      const assertion = await Authentication.sign({
+        options: { publicKey: decided.step.options.publicKey },
+      }).catch((error: unknown) => {
+        throw new CeremonyError('Passkey ceremony failed.', { cause: error })
+      })
+      const signed = await parseResponse(
+        client.v1.authorize.consent.$post({
+          json: { ...json, passkey: { assertion } },
+        }),
+      )
+      if ('step' in signed)
+        throw new Error('The approval requested a second passkey step.')
+      return signed
+    },
+    // Without a session, the page's loader sends the browser to sign-in, which continues the request.
+    onError: (error) => {
+      if (Client.reason(error) === 'session_required') window.location.reload()
+    },
+    onSuccess: (data) => window.location.assign(data.redirect),
+  })
+  // The decision holds both buttons until the browser leaves, after the request succeeds too.
+  const decided = consent.isPending || consent.isSuccess
+
+  return (
+    <main {...styles.page()}>
+      {props.request ? (
+        <Approval
+          app={props.request.app}
+          approving={decided && consent.variables.accept}
+          denying={decided && !consent.variables.accept}
+          destination={props.request.destination}
+          email={props.request.email}
+          error={
+            consent.error &&
+            Client.reason(consent.error) !== 'webauthn_required'
+              ? message(consent.error)
+              : undefined
+          }
+          keyAuthorization={props.request.key}
+          onApprove={() => consent.mutate({ accept: true })}
+          onDeny={() => consent.mutate({ accept: false })}
+          // The API's refusal names the other flows, and the screen states the step here instead.
+          refusal={
+            Client.reason(consent.error) === 'webauthn_required'
+              ? 'passkey'
+              : undefined
+          }
+        />
+      ) : (
+        <InvalidRequest />
+      )}
+    </main>
+  )
+}
+
+declare namespace Page {
+  type Props = {
+    /**
+     * The request that the page shows, or `null` for a forged or expired query or a request without
+     * a known app.
+     */
+    request: {
+      /** The app's display name. */
+      app: string
+      /** The host of the app's redirect URI, or its scheme for a native app. */
+      destination: string
+      /** The signed-in user's address. */
+      email: string
+      /** The key authorization that the request carries, if any. */
+      key?: Approval.Key | undefined
+      /** The ID of the signed-in session, which the decision names. */
+      session: string
+    } | null
+  }
+}
+
+/**
+ * Returns the message to show for `error`. A ceremony that the user cancels, or that times out,
+ * fails with a `NotAllowedError` from the browser, which the passkey library wraps in its own error.
+ * A refused assertion takes a new passkey step, which the next approval starts.
+ */
+function message(error: unknown) {
+  if (Client.reason(error) === 'webauthn_rejected')
+    return 'Your passkey did not sign the approval. Approve again, or deny the request.'
+  if (!(error instanceof CeremonyError)) return Client.message(error)
+  if (names(error).includes('NotAllowedError'))
+    return 'The passkey request was canceled. Approve again, or deny the request.'
+  return 'Your passkey did not sign the approval. Approve again, or deny the request.'
+}
+
+/** Returns the names of `error` and of each error in its chain of causes. */
+function names(error: unknown): readonly string[] {
+  if (!(error instanceof Error)) return []
+  return [error.name, ...names(error.cause)]
+}
+
+namespace styles {
+  export const page = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: 'screen',
+    paddingBlock: 16,
+    paddingInline: 4,
+  })
+}

package/src/app/routes/choose-account.tsx

@@ -0,0 +1,111 @@
+/**
+ * The account step: the signed-in user chooses the Tempo Account that an app uses, and the app's
+ * authorization continues.
+ * @module
+ */
+import { useMutation } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { parseResponse } from 'hono/client'
+import { ErrorMessage } from '../components/ErrorMessage.js'
+import * as Client from '../lib/Client.js'
+import * as Loader from '../lib/Loader.js'
+import { InvalidRequest } from '../screens/Approval.js'
+import { ChooseAccount } from '../screens/ChooseAccount.js'
+import { style } from '../zyzz.config.js'
+
+export const Route = createFileRoute('/choose-account')({
+  // The route splitter drops the style namespace, so the component stays in this chunk.
+  codeSplitGroupings: [],
+  component: () => <Page {...Route.useLoaderData()} />,
+  /**
+   * Sends a request without Better Auth's signature to `/oauth2/authorize`, and a visitor without a
+   * session to sign-in, each with the query unchanged. Otherwise returns the account step that
+   * `GET /v1/authorize/accounts` reads, or the refusal's message, such as for a spent account limit.
+   */
+  loader: async (match): Promise<Page.Props> => {
+    const { searchStr } = match.location
+    const query = new URLSearchParams(searchStr)
+    if (!query.get('sig'))
+      Loader.redirect({ document: true, href: `/oauth2/authorize${searchStr}` })
+
+    const client = Client.create()
+    try {
+      const found = await parseResponse(
+        client.v1.authorize.accounts.$get({
+          query: { oauth_query: query.toString() },
+        }),
+      )
+      return { error: null, request: found.request }
+    } catch (error) {
+      if (Client.reason(error) === 'session_required')
+        Loader.redirect({ href: `/login${searchStr}` })
+      return { error: Client.message(error), request: null }
+    }
+  },
+  // The loader reads the whole query, so a change to any parameter loads the page again.
+  loaderDeps: (match) => ({ search: match.search }),
+})
+
+/** Renders the page. */
+function Page(props: Page.Props) {
+  const client = Client.use()
+  const select = useMutation({
+    mutationFn: (variables: { account: `0x${string}` }) =>
+      parseResponse(
+        client.v1.authorize.account.$post({
+          json: {
+            account: variables.account,
+            oauth_query: window.location.search.slice(1),
+          },
+        }),
+      ),
+    onSuccess: (data) => window.location.assign(data.redirect),
+  })
+  // The choice holds every row until the browser leaves, after the request succeeds too.
+  const selecting =
+    select.isPending || select.isSuccess ? select.variables.account : undefined
+
+  return (
+    <main {...styles.page()}>
+      {(() => {
+        if (props.error)
+          return <ErrorMessage align="center">{props.error}</ErrorMessage>
+        if (!props.request) return <InvalidRequest />
+        return (
+          <ChooseAccount
+            accounts={props.request.accounts}
+            app={props.request.app}
+            error={select.error ? Client.message(select.error) : undefined}
+            onChoose={(account) => select.mutate({ account })}
+            selecting={selecting}
+          />
+        )
+      })()}
+    </main>
+  )
+}
+
+declare namespace Page {
+  type Props = {
+    /** Why the step failed to load, such as a spent account limit, or `null` when it loaded. */
+    error: string | null
+    /** The step that the page shows, or `null` for a forged or expired query or a request without a known app. */
+    request: {
+      /** The user's accounts in the app's realms, oldest first. */
+      accounts: ChooseAccount.Props['accounts']
+      /** The app's display name. */
+      app: string
+    } | null
+  }
+}
+
+namespace styles {
+  export const page = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: 'screen',
+    paddingBlock: 16,
+    paddingInline: 4,
+  })
+}

package/src/app/routes/deposit.tsx

@@ -0,0 +1,105 @@
+/** The deposit page: how to send stablecoins to one of the signed-in user's Tempo Accounts. @module */
+import { createFileRoute } from '@tanstack/react-router'
+import { parseResponse } from 'hono/client'
+import * as Client from '../lib/Client.js'
+import * as Loader from '../lib/Loader.js'
+import { Deposit } from '../screens/Deposit.js'
+import { style } from '../zyzz.config.js'
+
+export const Route = createFileRoute('/deposit')({
+  // The route splitter drops the style namespace, so the component stays in this chunk.
+  codeSplitGroupings: [],
+  component: () => <Page {...Route.useLoaderData()} />,
+  /**
+   * Redirects a visitor without a session to sign-in. Otherwise returns the method that the query
+   * names, and the account at the query's `address` when it is one of the user's accounts in the
+   * `default` realm. For another address, a spent account limit, or a failed read, it returns
+   * `address: null` with the reason. The page creates no account.
+   */
+  loader: async (match): Promise<Page.Props> => {
+    const client = Client.create()
+    const session = await parseResponse(client.v1.auth.session.$get())
+    // The sign-in page's query leaves the address out.
+    if (!session.user) Loader.redirect({ href: '/login' })
+
+    const { address, method } = match.deps
+    const shown = method === 'tempo' ? method : null
+    const account = await parseResponse(
+      client.v1.account.$get({ query: {} }),
+    ).catch((error: unknown) => ({ error }))
+    if ('error' in account)
+      return {
+        address: null,
+        error:
+          Client.reason(account.error) === 'rate_limited'
+            ? Client.message(account.error)
+            : 'Your wallets failed to load. Reload the page to try again.',
+        method: shown,
+      }
+
+    // Only one of the user's own accounts receives a deposit through this page.
+    const found = account.tempo.find(
+      (entry) => entry.address.toLowerCase() === address?.toLowerCase(),
+    )
+    if (!found)
+      return {
+        address: null,
+        error:
+          'This wallet was not found. Go back to your account, then choose Deposit.',
+        method: shown,
+      }
+    return { address: found.address, error: null, method: shown }
+  },
+  loaderDeps: (match: { search: Search }) => ({
+    address: match.search.address,
+    method: match.search.method,
+  }),
+  validateSearch: (search: Record<string, unknown>): Search => ({
+    ...(typeof search.address === 'string' ? { address: search.address } : {}),
+    ...(typeof search.method === 'string' ? { method: search.method } : {}),
+  }),
+})
+
+/** The search parameters that the page reads. */
+type Search = {
+  /** The account that receives the deposit. */
+  address?: string | undefined
+  /** The method that the page shows, such as `tempo`, or the list of networks without one. */
+  method?: string | undefined
+}
+
+/** Renders the page. */
+function Page(props: Page.Props) {
+  return (
+    <main {...styles.page()} aria-label="Deposit">
+      <Deposit
+        address={props.address ?? undefined}
+        error={props.error ?? undefined}
+        method={props.method ?? undefined}
+      />
+    </main>
+  )
+}
+
+declare namespace Page {
+  type Props = {
+    /** The account that receives the deposit, or `null` when the query names none of the user's. */
+    address: `0x${string}` | null
+    /** Why the page shows no address, or `null` when it shows one. */
+    error: string | null
+    /** The method that the page shows, or `null` for the list of networks. */
+    method: 'tempo' | null
+  }
+}
+
+namespace styles {
+  // Content starts at the same height as on the account page, so the titles line up.
+  export const page = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: 'screen',
+    paddingBlock: 16,
+    paddingInline: 4,
+  })
+}