@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/app/routes/__root.tsx

@@ -0,0 +1,172 @@
+/**
+ * The document of every page, with the shared API and query clients. The router keeps `chain` on
+ * every page. @module
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  retainSearchParams,
+  Scripts,
+} from '@tanstack/react-router'
+import { Toast, vars as ds } from '@tempoxyz/ds'
+import { lazy, type ReactNode, Suspense, useEffect, useState } from 'react'
+import reset from 'zyzz/reset.css?url'
+import type * as Chain from '../../internal/Chain.js'
+import * as ChainName from '../../internal/ChainName.js'
+import * as Client from '../lib/Client.js'
+import { NotFound } from '../screens/NotFound.js'
+import { style, vars } from '../zyzz.config.js'
+
+/**
+ * The Tempo mark, as Tempo Wallet and the Tempo Developer Console show it. Inline, so the browser
+ * makes no request for it and never requests `/favicon.ico`.
+ */
+const favicon = `data:image/svg+xml,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 269 269"><rect width="269" height="269" fill="#000"/><path d="M123.273 190.794H93.445L121.09 105.318H85.7334L93.445 80.2642H191.95L184.238 105.318H150.773L123.273 190.794Z" fill="#fff"/></svg>',
+)}`
+
+export const Route = createRootRoute({
+  component: Root,
+  head: () => ({
+    links: [
+      { href: reset, rel: 'stylesheet' },
+      { href: favicon, rel: 'icon', type: 'image/svg+xml' },
+    ],
+    meta: [
+      { charSet: 'utf-8' },
+      { content: 'width=device-width, initial-scale=1', name: 'viewport' },
+      { title: 'Tempo ID' },
+      { content: 'Sign in to Tempo.', name: 'description' },
+    ],
+  }),
+  notFoundComponent: NotFoundPage,
+  // 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.
+    return { chain: ChainName.read(search.chain) }
+  },
+})
+
+/** The search parameters of every page. */
+type Search = {
+  /** The chain of the balances. Defaults to Tempo mainnet. */
+  chain?: Chain.Chain | undefined
+}
+
+/** The dev toolbar, in its own chunk, loaded after hydration. */
+const DevTools = lazy(async () => ({
+  default: (await import('../components/DevTools.js')).DevTools,
+}))
+
+/** The `localStorage` key of the toolbar choice in a build. */
+const devToolsKey = 'tempo-id:devtools'
+
+/** Renders the page with the shared clients. */
+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())
+  const devTools = useDevTools()
+
+  return (
+    <Client.Context value={client}>
+      <QueryClientProvider client={queryClient}>
+        {/* Every page can confirm a change with a toast. */}
+        <Toast.Provider>
+          <Outlet />
+          <Toast.Viewport />
+          {devTools && (
+            <Suspense fallback={null}>
+              <DevTools />
+            </Suspense>
+          )}
+        </Toast.Provider>
+      </QueryClientProvider>
+    </Client.Context>
+  )
+}
+
+/**
+ * Returns whether the dev toolbar renders: in `vp dev`, or from `?devtools` to `?devtools=false`.
+ */
+function useDevTools() {
+  const [enabled, setEnabled] = useState(false)
+
+  useEffect(() => {
+    if (import.meta.env.DEV) {
+      setEnabled(true)
+      return
+    }
+
+    const value = new URLSearchParams(location.search).get('devtools')
+    const off = value === 'false' || value === '0'
+    try {
+      if (off) localStorage.removeItem(devToolsKey)
+      else if (value !== null) localStorage.setItem(devToolsKey, 'true')
+      setEnabled(localStorage.getItem(devToolsKey) === 'true')
+    } catch {
+      // Blocked storage keeps the parameter's choice for this page only.
+      setEnabled(value !== null && !off)
+    }
+  }, [])
+
+  return enabled
+}
+
+/** Renders the not-found screen. */
+function NotFoundPage() {
+  return (
+    <main {...styles.page()}>
+      <NotFound />
+    </main>
+  )
+}
+
+/**
+ * Renders the HTML document around the page. `data-hydrated` turns `true` once React hydrates the
+ * document, which the end-to-end suite waits for before it types or clicks: a click before hydration
+ * submits a form natively.
+ */
+function Document(props: Document.Props) {
+  const [hydrated, setHydrated] = useState(false)
+  useEffect(() => setHydrated(true), [])
+
+  return (
+    <html
+      className={`${ds().className} ${vars().className}`}
+      data-hydrated={hydrated}
+      lang="en"
+    >
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {props.children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+
+declare namespace Document {
+  type Props = {
+    /** The page. */
+    children: ReactNode
+  }
+}
+
+namespace styles {
+  export const page = style({
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: '100dvh !custom',
+    paddingBlock: '64',
+    paddingInline: '16',
+  })
+}

package/src/app/routes/authorize.tsx

@@ -0,0 +1,379 @@
+/**
+ * The approval page, where the signed-in user approves or denies an app's request. For a
+ * wallet.tempo passkey's wallet that waits for its upgrade, Approve shows the upgrade step, and
+ * both Continue and Not now finish the approval and return to the app. @module
+ */
+import { type UseMutationResult, useMutation } from '@tanstack/react-query'
+import { Await, createFileRoute } from '@tanstack/react-router'
+import { parseResponse } from 'hono/client'
+import { type ReactNode, useState } from 'react'
+import { Authentication } from 'webauthx/client'
+import * as Client from '../lib/Client.js'
+import * as Loader from '../lib/Loader.js'
+import * as Upgrade from '../lib/Upgrade.js'
+import { Approval, InvalidRequest } from '../screens/Approval.js'
+import { WalletUpgrade } from '../screens/WalletUpgrade.js'
+import { style } from '../zyzz.config.js'
+
+/** Wraps a failure of the browser's passkey ceremony. */
+class CeremonyError extends Error {
+  override name = 'Page.CeremonyError'
+}
+
+export const Route = createFileRoute('/authorize')({
+  component: () => <Page {...Route.useLoaderData()} />,
+  /**
+   * Returns no request for a query that Better Auth did not sign, and redirects a visitor without a
+   * session to sign-in. Otherwise returns the request, or redirects a refused key to the app. The
+   * account that approval signs for follows as `preview`, which the page streams in after it renders.
+   */
+  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)
+    // Apps start at `/oauth2/authorize`, which signs the query, so an unsigned one is no request.
+    if (!query.get('sig')) return { preview: null, request: null }
+
+    const client = Client.create()
+    const result = await (async () => {
+      try {
+        return await parseResponse(
+          client.i.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 })
+    if (!result.request) return { preview: null, request: null }
+
+    // The owners' lookup can call every realm's Privy app, so the page renders without waiting for it.
+    return {
+      preview: preview(client, { query, request: result.request }),
+      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: Page.Decision) {
+      const json = {
+        accept: variables.accept,
+        // Approval signs for the account that the page shows.
+        ...(variables.account ? { account: variables.account } : {}),
+        oauth_query: window.location.search.slice(1),
+        session_id: props.request?.session ?? '',
+        ...(variables.skipUpgrade ? { skip_upgrade: true } : {}),
+      }
+      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
+
+  if (!props.request || !props.preview)
+    return (
+      <main {...styles.page()}>
+        <InvalidRequest />
+      </main>
+    )
+
+  // A denial needs no account, so Deny works while the account loads. Approve waits for it.
+  const approval = (request: Page.Request, options: Page.approval.Options) => (
+    <Approval
+      account={request.account}
+      app={request.app}
+      approving={decided && consent.variables.accept}
+      checking={options.checking}
+      denying={decided && !consent.variables.accept}
+      destination={request.destination}
+      email={request.email}
+      verified={request.verified}
+      error={
+        consent.error && Client.reason(consent.error) !== 'webauthn_required'
+          ? message(consent.error)
+          : undefined
+      }
+      keyAuthorization={request.key}
+      logo={request.logo}
+      onApprove={
+        options.onApprove ??
+        (() => consent.mutate({ accept: true, account: request.key?.account }))
+      }
+      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
+      }
+    />
+  )
+
+  return (
+    <main {...styles.page()}>
+      <Await
+        fallback={approval(props.request, { checking: true })}
+        promise={props.preview}
+      >
+        {(preview) => (
+          <Previewed approval={approval} consent={consent} preview={preview} />
+        )}
+      </Await>
+    </main>
+  )
+}
+
+declare namespace Page {
+  namespace approval {
+    type Options = {
+      /** Whether the account that approval signs for loads, which holds Approve. */
+      checking: boolean
+      /** Runs on Approve in place of the decision, such as to show the upgrade step first. */
+      onApprove?: (() => void) | undefined
+    }
+  }
+
+  /** The user's decision on the request, which `POST /v1/authorize/consent` records. */
+  type Decision = {
+    /** Whether the user approves the request. */
+    accept: boolean
+    /** The account that the page shows for the key, if any. */
+    account?: `0x${string}` | undefined
+    /** Whether the user skipped the wallet's upgrade, so the passkey signs for the wallet as it is. */
+    skipUpgrade?: boolean | undefined
+  }
+
+  type Props = {
+    /** The request with the account that approval signs for, which follows `request`. */
+    preview: Promise<Preview> | null
+    /** `null` for a forged or expired query or an unknown app. It holds no account. */
+    request: Request | null
+  }
+
+  /** The request with the account that approval signs for. */
+  type Preview = {
+    /** The request, with its account and the key's refusal. */
+    request: Request
+    /** The wallet upgrade that approval waits for, or `null`. */
+    upgrade: Upgrade.Pending | null
+  }
+
+  /** The request that the page shows. */
+  type Request = {
+    /** Absent unless the user holds several accounts in the app's realms. */
+    account?: Approval.Account | undefined
+    /** The app's display name. */
+    app: string
+    /** The host of the app's redirect URI, or the scheme of a native app. */
+    destination: string
+    /** The signed-in user's address. */
+    email: string
+    /** Absent without a key authorization. */
+    key?: Approval.Key | undefined
+    /** The app's logo as a `data:` URL, if any. */
+    logo?: string | undefined
+    /** The signed-in session's ID, which the decision names. */
+    session: string
+    /** Whether the app is registered, which marks its name as verified. */
+    verified: boolean
+  }
+}
+
+/**
+ * Renders the approval with the account that approval signs for. For a wallet.tempo passkey's
+ * wallet that waits for its upgrade, Approve shows the upgrade step, since approval cannot sign the
+ * key before it. Continue upgrades the wallet, and Not now signs the key for the wallet as it is.
+ * Both then approve the request, so the browser returns to the app.
+ */
+function Previewed(props: Previewed.Props) {
+  const { consent, preview } = props
+  const client = Client.use()
+  const pending = preview.upgrade ?? undefined
+  const account = preview.request.key?.account
+  const upgrade = Upgrade.use({
+    // The approval starts before the upgrade settles, so Continue holds until the browser leaves.
+    onSuccess: () => consent.mutate({ accept: true, account }),
+    pending,
+  })
+  // A session older than 10 minutes cannot upgrade. Without a session, the page's loader sends the
+  // browser to sign-in, and back to the request.
+  const signOut = useMutation({
+    mutationFn: () => parseResponse(client.v1.auth.logout.$post()),
+    onSuccess: () => window.location.reload(),
+  })
+  // Whether Approve opened the upgrade step.
+  const [opened, setOpened] = useState(false)
+  const decided = consent.isPending || consent.isSuccess
+  const skipping = decided && consent.variables.skipUpgrade === true
+
+  // A failed approval shows the request again, with its error.
+  if (pending && opened && !consent.isError)
+    return (
+      <WalletUpgrade
+        error={(() => {
+          const error = signOut.error ?? upgrade.error
+          if (!error || (upgrade.stale && !signOut.error)) return undefined
+          return Upgrade.message(error)
+        })()}
+        onContinue={() => upgrade.mutate()}
+        onSignIn={upgrade.stale ? () => signOut.mutate() : undefined}
+        onSkip={() =>
+          consent.mutate({ accept: true, account, skipUpgrade: true })
+        }
+        preparing={upgrade.preparing}
+        skipping={skipping}
+        upgrading={
+          upgrade.isPending ||
+          (decided && !skipping) ||
+          signOut.isPending ||
+          signOut.isSuccess
+        }
+      />
+    )
+
+  const { key } = preview.request
+  if (!pending || !key)
+    return props.approval(preview.request, { checking: false })
+
+  // The upgrade step resolves the key's `upgrade` refusal, so Approve stays enabled. After the
+  // upgrade, Approve repeats the approval alone, and the page shows the request while it runs.
+  return props.approval(
+    { ...preview.request, key: { ...key, refusal: undefined } },
+    {
+      checking: false,
+      onApprove: () => {
+        if (upgrade.isSuccess) {
+          setOpened(false)
+          consent.mutate({ accept: true, account })
+          return
+        }
+        consent.reset()
+        setOpened(true)
+      },
+    },
+  )
+}
+
+declare namespace Previewed {
+  type Props = {
+    /** Renders the approval of `request`. */
+    approval: (
+      request: Page.Request,
+      options: Page.approval.Options,
+    ) => ReactNode
+    /** The decision on the request, which the page's approval shares. */
+    consent: UseMutationResult<{ redirect: string }, Error, Page.Decision>
+    /** The request with the account that approval signs for. */
+    preview: Page.Preview
+  }
+}
+
+/**
+ * Returns `request` with the account that approval signs for, the key's refusal, and the upgrade
+ * that an `upgrade` refusal waits for. A failed read holds the approval of a key with `unavailable`,
+ * as a failed read of the owners does.
+ */
+async function preview(
+  client: Client.Client,
+  options: preview.Options,
+): Promise<Page.Preview> {
+  const result = await parseResponse(
+    client.v1.authorize.request.$get({
+      query: { oauth_query: options.query.toString() },
+    }),
+  ).catch(() => undefined)
+  const read = result && 'request' in result ? result.request : undefined
+  if (!read) {
+    const { key } = options.request
+    return {
+      request: {
+        ...options.request,
+        ...(key ? { key: { ...key, refusal: 'unavailable' } } : {}),
+      },
+      upgrade: null,
+    }
+  }
+
+  // An `upgrade` refusal names the account to upgrade on the key's chain, or none for a passkey of
+  // the email that has not linked.
+  const key = read.key
+  const upgrade =
+    key?.refusal === 'upgrade'
+      ? await Upgrade.forKey(client, {
+          account: key.account,
+          chain: key.chain.name,
+        })
+      : undefined
+  return { request: read, upgrade: upgrade ?? null }
+}
+
+declare namespace preview {
+  type Options = {
+    /** The approval page's signed query. */
+    query: URLSearchParams
+    /** The request that the page renders first. */
+    request: Page.Request
+  }
+}
+
+/** Returns the message for `error`, such as for a canceled ceremony. */
+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 its 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: '100dvh !custom',
+    paddingBlock: '64',
+    paddingInline: '16',
+  })
+}

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

@@ -0,0 +1,144 @@
+/** The account step, where the signed-in user chooses the Tempo Account for an app. @module */
+import { useMutation } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import { Callout } from '@tempoxyz/ds'
+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 { InvalidRequest } from '../screens/Approval.js'
+import { ChooseAccount } from '../screens/ChooseAccount.js'
+import { style } from '../zyzz.config.js'
+
+/** Wraps a failure of the browser's passkey ceremony. */
+class CeremonyError extends Error {
+  override name = 'Page.CeremonyError'
+}
+
+export const Route = createFileRoute('/choose-account')({
+  component: () => <Page {...Route.useLoaderData()} />,
+  /**
+   * Returns no request for a query that Better Auth did not sign, and redirects a visitor without a
+   * session to sign-in. Otherwise returns the step or the refusal's message.
+   */
+  loader: async (match): Promise<Page.Props> => {
+    const { searchStr } = match.location
+    const query = new URLSearchParams(searchStr)
+    if (!query.get('sig')) return { error: null, request: null }
+
+    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({
+    async mutationFn(variables: { account: `0x${string}` }) {
+      const json = {
+        account: variables.account,
+        oauth_query: window.location.search.slice(1),
+      }
+      const selected = await parseResponse(
+        client.v1.authorize.account.$post({ json }),
+      )
+      if (!('step' in selected)) return selected
+
+      // The passkey signs the key authorization's digest, which the step's options carry.
+      const assertion = await Authentication.sign({
+        options: { publicKey: selected.step.options.publicKey },
+      }).catch((error: unknown) => {
+        throw new CeremonyError('Passkey ceremony failed.', { cause: error })
+      })
+      const signed = await parseResponse(
+        client.v1.authorize.account.$post({
+          json: { ...json, passkey: { assertion } },
+        }),
+      )
+      if ('step' in signed)
+        throw new Error('The selection requested a second passkey step.')
+      return signed
+    },
+    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 (
+            <Callout intent="negative">
+              <Callout.Icon />
+              <Callout.Content>{props.error}</Callout.Content>
+            </Callout>
+          )
+        if (!props.request) return <InvalidRequest />
+        return (
+          <ChooseAccount
+            accounts={props.request.accounts}
+            app={props.request.app}
+            error={select.error ? message(select.error) : undefined}
+            onChoose={(account) => select.mutate({ account })}
+            selecting={selecting}
+          />
+        )
+      })()}
+    </main>
+  )
+}
+
+declare namespace Page {
+  type Props = {
+    /** The refusal's message, or `null` when the step loaded. */
+    error: string | null
+    /** `null` for a forged or expired query or an unknown app. */
+    request: {
+      /** Oldest first. */
+      accounts: ChooseAccount.Props['accounts']
+      /** The app's display name. */
+      app: string
+    } | null
+  }
+}
+
+/** Returns the message for `error`, such as for a canceled ceremony. */
+function message(error: unknown) {
+  if (!(error instanceof CeremonyError)) return Client.message(error)
+  if (names(error).includes('NotAllowedError'))
+    return 'The passkey request was canceled. Choose the account again to continue.'
+  return 'Your passkey did not sign the request. Choose the account again to continue.'
+}
+
+/** Returns the names of `error` and its 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: '100dvh !custom',
+    paddingBlock: '64',
+    paddingInline: '16',
+  })
+}