@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/app/lib/Client.ts

@@ -0,0 +1,82 @@
+/** Calls Tempo ID's JSON API with `hc`, in process during server rendering. @module */
+import {
+  createIsomorphicFn,
+  getGlobalStartContext,
+} from '@tanstack/react-start'
+import { DetailedError, hc } from 'hono/client'
+import { createContext, useContext } from 'react'
+import type { App } from '../../Api.js'
+
+/** A client for Tempo ID's JSON API. */
+export type Client = ReturnType<typeof create>
+
+/** Returns the `fetch` for the API: in process on the server, the network in the browser. */
+const fetcher = createIsomorphicFn()
+  .server((options: create.Options) => {
+    const context = getGlobalStartContext()!
+    return options.optional ? context.fetchOptional : context.fetch
+  })
+  .client(() => fetch)
+
+/** Returns the page's origin. */
+const origin = createIsomorphicFn()
+  .server(() => getGlobalStartContext()!.origin)
+  .client(() => window.location.origin)
+
+/** The client that the root route provides. */
+export const Context = createContext<Client | undefined>(undefined)
+
+/** Creates a client for the page's origin, so each request carries the session cookie. */
+export function create(options: create.Options = {}) {
+  return hc<App>(origin(), { fetch: fetcher(options) })
+}
+
+export declare namespace create {
+  type Options = {
+    /**
+     * Whether the page renders without the data of the client's calls, so a rate limit's refusal of
+     * one during a server render leaves the page's status as it is. Defaults to `false`.
+     */
+    optional?: boolean | undefined
+  }
+}
+
+/** Returns the `error_description` of a refusal from `parseResponse`, or a generic message. */
+export function message(error: unknown) {
+  if (error instanceof DetailedError) {
+    const data: unknown = error.detail?.data
+    if (
+      typeof data === 'object' &&
+      data !== null &&
+      'error_description' in data &&
+      typeof data.error_description === 'string'
+    )
+      return data.error_description
+    return 'Something went wrong. Try again.'
+  }
+  return 'Tempo ID cannot be reached. Check the connection, and try again.'
+}
+
+/** Returns the `reason` of a refusal from `parseResponse`, or `undefined`. */
+export function reason(error: unknown) {
+  if (!(error instanceof DetailedError)) return undefined
+  const data: unknown = error.detail?.data
+  if (
+    typeof data === 'object' &&
+    data !== null &&
+    'reason' in data &&
+    typeof data.reason === 'string'
+  )
+    return data.reason
+  return undefined
+}
+
+/**
+ * Returns the root route's client.
+ * @throws {Error} Outside the root route.
+ */
+export function use() {
+  const client = useContext(Context)
+  if (!client) throw new Error('The client is used outside the root route.')
+  return client
+}

package/src/app/lib/Inbox.ts

@@ -0,0 +1,11 @@
+/** Names that the dev toolbar shares with `src/app/inbox.ts`, without Node imports. @module */
+/* istanbul ignore file -- Only the dev toolbar and the dev server read it. */
+
+/** Carries Void's dev-trigger token, which the JSON inbox requires. */
+export const header = 'x-void-dev-trigger'
+
+/** The path of the JSON inbox. */
+export const path = '/__devtools/inbox'
+
+/** Serves the token to the toolbar, without CORS headers. */
+export const tokenPath = '/__devtools/token'

package/src/app/lib/Loader.ts

@@ -0,0 +1,21 @@
+/** Shared parts of the pages' loaders. @module */
+import { redirect as router_redirect } from '@tanstack/react-router'
+
+/** Throws a 302 redirect to `href`. Set `document` for a path that no route serves. */
+export function redirect(options: redirect.Options): never {
+  const { document = false, href } = options
+  throw router_redirect({
+    href,
+    ...(document ? { reloadDocument: true } : {}),
+    statusCode: 302,
+  })
+}
+
+export declare namespace redirect {
+  type Options = {
+    /** Whether the browser loads `href` as a document. Defaults to `false`. */
+    document?: boolean | undefined
+    /** A path or an absolute URL. */
+    href: string
+  }
+}

package/src/app/lib/Upgrade.ts

@@ -0,0 +1,221 @@
+/**
+ * Finds and runs the upgrade of a wallet.tempo passkey's wallet, on a chain whose accounts are
+ * configurable, so the wallet that a user signs in with or approves for is configurable. The passkey
+ * signs each upgrade in the browser, through `POST /v1/account/upgrade`.
+ * @module
+ */
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { parseResponse } from 'hono/client'
+import { Authentication } from 'webauthx/client'
+import type * as Chain from '../../internal/Chain.js'
+import * as Client from './Client.js'
+
+/** Wraps a failure of the browser's passkey ceremony. */
+export class CeremonyError extends Error {
+  override name = 'Upgrade.CeremonyError'
+}
+
+/**
+ * Milliseconds that a page signs an upgrade's passkey step for. The server keeps a step for 5
+ * minutes, so a page prepares another before then.
+ */
+export const stepLifetime = 4 * 60 * 1000
+
+/** An upgrade that waits for the user's passkey. */
+export type Pending = {
+  /** The chain whose accounts are configurable, where the upgrade applies. */
+  chain: Chain.Chain
+  /** The wallet that upgrades. */
+  target: Target
+}
+
+/** A wallet that upgrades: the user's linked account, or a passkey of the email that has not linked. */
+export type Target = { account: `0x${string}` } | { credentialId: string }
+
+/**
+ * Returns the upgrade that the approval of a key waits for, after its `upgrade` refusal: `account`,
+ * the refused account, on the key's chain. Without `account`, a passkey of the user's email that has
+ * not linked waits. Its upgrade links it, on the key's chain when that chain's accounts are
+ * configurable, else on the first such chain. A failed read returns none, so the refusal shows.
+ */
+export async function forKey(
+  client: Client.Client,
+  options: forKey.Options,
+): Promise<Pending | undefined> {
+  const { chains } = await parseResponse(client.i.chains.$get()).catch(() => ({
+    chains: [],
+  }))
+  const configurable = chains.filter((entry) => entry.configurable)
+  const keyed = configurable.find((entry) => entry.name === options.chain)
+  if (options.account)
+    return keyed
+      ? { chain: keyed.name, target: { account: options.account } }
+      : undefined
+
+  const chain = keyed ?? configurable[0]
+  if (!chain) return undefined
+  const { passkeys } = await parseResponse(
+    client.i.account.passkeys.$get(),
+  ).catch(() => ({ passkeys: [] }))
+  const [unlinked] = passkeys
+  if (!unlinked) return undefined
+  return { chain: chain.name, target: { credentialId: unlinked.credentialId } }
+}
+
+export declare namespace forKey {
+  type Options = {
+    /** The account that the key's refusal names. Absent when a passkey of the email has not linked. */
+    account?: `0x${string}` | undefined
+    /** The name of the key's chain. Absent for a chain that no name lists. */
+    chain?: Chain.Chain | undefined
+  }
+}
+
+/**
+ * Returns the first upgrade that waits for the signed-in user on `chain`, as `GET
+ * /i/account/upgrades` lists it: a linked passkey's account that is not configurable there, or, for
+ * a user without an account, a passkey of the email that has not linked. A chain whose accounts are
+ * not configurable, or a failed read, returns none, so the page continues without the upgrade.
+ */
+export async function pending(
+  client: Client.Client,
+  options: pending.Options,
+): Promise<Pending | undefined> {
+  const { upgrades } = await parseResponse(
+    client.i.account.upgrades.$get({ query: { chain: options.chain } }),
+  ).catch(() => ({ upgrades: [] }))
+  const [first] = upgrades
+  if (!first) return undefined
+  if ('account' in first)
+    return { chain: first.chain, target: { account: first.account } }
+  return { chain: first.chain, target: { credentialId: first.credentialId } }
+}
+
+export declare namespace pending {
+  type Options = {
+    /** The chain to check, such as the one that the page shows. */
+    chain: Chain.Chain
+  }
+}
+
+/**
+ * Requests the passkey step of `options`' upgrade, and returns its options for
+ * `navigator.credentials.get()`.
+ */
+export async function prepare(client: Client.Client, options: Pending) {
+  const data = await request(client, options)
+  if (!('step' in data))
+    throw new Error('The upgrade returned no passkey step.')
+  return data.step.options
+}
+
+/**
+ * Sends the first request of `options`' upgrade, which returns the passkey step, or the account when
+ * the chain already holds the upgrade, which the request then saves.
+ */
+function request(client: Client.Client, options: Pending) {
+  return parseResponse(
+    client.v1.account.upgrade.$post({
+      json: { ...options.target, chain: options.chain },
+    }),
+  )
+}
+
+/**
+ * Returns the mutation that signs `pending`'s upgrade with the passkey and sends it. The hook
+ * prepares the passkey step ahead of the click, since a browser such as Safari spends a click's user
+ * activation on a request before the ceremony. `preparing` holds while that first step loads, so the
+ * page holds Continue until then. `stale` marks a session that signed in more than 10 minutes
+ * before, so no upgrade can run.
+ */
+export function use(options: use.Options) {
+  const { pending } = options
+  const client = Client.use()
+  const queryClient = useQueryClient()
+  const queryKey = ['upgrade', pending?.chain, pending?.target]
+  const step = useQuery({
+    enabled: pending !== undefined,
+    queryFn: () => request(client, pending!),
+    queryKey,
+    refetchInterval: stepLifetime,
+    // A hidden tab keeps its step fresh, and a tab that comes back after a stale step prepares
+    // another, since the server keeps a step for 5 minutes.
+    refetchIntervalInBackground: true,
+    refetchOnWindowFocus: true,
+    retry: false,
+    staleTime: stepLifetime,
+  })
+  const mutation = useMutation({
+    async mutationFn() {
+      if (!pending) throw new Error('No upgrade waits.')
+      // A step that failed to load, such as for a session older than 10 minutes, loads now, so its
+      // refusal shows. So does one older than 4 minutes, which the server may already have expired.
+      const state =
+        queryClient.getQueryState<Awaited<ReturnType<typeof request>>>(queryKey)
+      const prepared =
+        state?.data && Date.now() - state.dataUpdatedAt < stepLifetime
+          ? state.data
+          : await request(client, pending)
+      // The chain already held the upgrade, which the request saved, so no passkey signs again.
+      if (!('step' in prepared)) return prepared
+
+      const assertion = await (async () => {
+        try {
+          return await Authentication.sign({
+            getFn: (request) =>
+              navigator.credentials.get(request as CredentialRequestOptions),
+            options: prepared.step.options,
+          })
+        } catch (error) {
+          throw new CeremonyError('Passkey ceremony failed.', { cause: error })
+        }
+      })()
+      try {
+        return await parseResponse(
+          client.v1.account.upgrade.$post({
+            json: {
+              ...pending.target,
+              chain: pending.chain,
+              passkey: { assertion },
+            },
+          }),
+        )
+      } catch (error) {
+        // An account that is configurable already finished its upgrade, such as in another tab, so
+        // the page continues as after its own.
+        if (Client.reason(error) === 'owner_exists') return undefined
+        // The server spends the step's challenge before it sends the upgrade, so a refused or failed
+        // upgrade prepares a new step for the next click.
+        await step.refetch()
+        throw error
+      }
+    },
+    // The mutation stays pending until the callback settles, such as while the page loads again.
+    onSuccess: () => options.onSuccess?.(),
+  })
+  // An upgrade requires a sign-in within the last 10 minutes, which the step's preparation checks.
+  const stale = [step.error, mutation.error].some(
+    (error) => Client.reason(error) === 'reauthentication_required',
+  )
+  return {
+    ...mutation,
+    preparing: pending !== undefined && step.isPending,
+    stale,
+  }
+}
+
+export declare namespace use {
+  type Options = {
+    /** Runs after the upgrade, before the mutation settles. */
+    onSuccess?: (() => unknown) | undefined
+    /** The upgrade that waits, if any. Absent, the hook prepares nothing. */
+    pending: Pending | undefined
+  }
+}
+
+/** Returns the message that a failed upgrade shows. */
+export function message(error: unknown) {
+  if (error instanceof CeremonyError)
+    return 'Your passkey did not sign the upgrade. Continue to try again.'
+  return Client.message(error)
+}

package/src/app/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@tempoxyz/id-app",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@tanstack/react-start": "catalog:"
+  }
+}

package/src/app/public/_headers

@@ -0,0 +1,4 @@
+# Cloudflare's asset layer serves every file under /assets/ without the Worker. Each name carries a
+# hash of its content, so browsers keep the file until a build changes the name.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable

package/src/app/routeTree.gen.ts

@@ -0,0 +1,219 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as AuthorizeRouteImport } from './routes/authorize'
+import { Route as ChooseAccountRouteImport } from './routes/choose-account'
+import { Route as DepositRouteImport } from './routes/deposit'
+import { Route as DeviceRouteImport } from './routes/device'
+import { Route as ErrorRouteImport } from './routes/error'
+import { Route as LoginRouteImport } from './routes/login'
+import { Route as Char91_Char93FlowsRouteImport } from './routes/[_].flows'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const AuthorizeRoute = AuthorizeRouteImport.update({
+  id: '/authorize',
+  path: '/authorize',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ChooseAccountRoute = ChooseAccountRouteImport.update({
+  id: '/choose-account',
+  path: '/choose-account',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const DepositRoute = DepositRouteImport.update({
+  id: '/deposit',
+  path: '/deposit',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const DeviceRoute = DeviceRouteImport.update({
+  id: '/device',
+  path: '/device',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ErrorRoute = ErrorRouteImport.update({
+  id: '/error',
+  path: '/error',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const LoginRoute = LoginRouteImport.update({
+  id: '/login',
+  path: '/login',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const Char91_Char93FlowsRoute = Char91_Char93FlowsRouteImport.update({
+  id: '/_/flows',
+  path: '/_/flows',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/error': typeof ErrorRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/error': typeof ErrorRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/authorize': typeof AuthorizeRoute
+  '/choose-account': typeof ChooseAccountRoute
+  '/deposit': typeof DepositRoute
+  '/device': typeof DeviceRoute
+  '/error': typeof ErrorRoute
+  '/login': typeof LoginRoute
+  '/_/flows': typeof Char91_Char93FlowsRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/error'
+    | '/login'
+    | '/_/flows'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/error'
+    | '/login'
+    | '/_/flows'
+  id:
+    | '__root__'
+    | '/'
+    | '/authorize'
+    | '/choose-account'
+    | '/deposit'
+    | '/device'
+    | '/error'
+    | '/login'
+    | '/_/flows'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  AuthorizeRoute: typeof AuthorizeRoute
+  ChooseAccountRoute: typeof ChooseAccountRoute
+  DepositRoute: typeof DepositRoute
+  DeviceRoute: typeof DeviceRoute
+  ErrorRoute: typeof ErrorRoute
+  LoginRoute: typeof LoginRoute
+  Char91_Char93FlowsRoute: typeof Char91_Char93FlowsRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/authorize': {
+      id: '/authorize'
+      path: '/authorize'
+      fullPath: '/authorize'
+      preLoaderRoute: typeof AuthorizeRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/choose-account': {
+      id: '/choose-account'
+      path: '/choose-account'
+      fullPath: '/choose-account'
+      preLoaderRoute: typeof ChooseAccountRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/deposit': {
+      id: '/deposit'
+      path: '/deposit'
+      fullPath: '/deposit'
+      preLoaderRoute: typeof DepositRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/device': {
+      id: '/device'
+      path: '/device'
+      fullPath: '/device'
+      preLoaderRoute: typeof DeviceRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/error': {
+      id: '/error'
+      path: '/error'
+      fullPath: '/error'
+      preLoaderRoute: typeof ErrorRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/login': {
+      id: '/login'
+      path: '/login'
+      fullPath: '/login'
+      preLoaderRoute: typeof LoginRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/_/flows': {
+      id: '/_/flows'
+      path: '/_/flows'
+      fullPath: '/_/flows'
+      preLoaderRoute: typeof Char91_Char93FlowsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  AuthorizeRoute: AuthorizeRoute,
+  ChooseAccountRoute: ChooseAccountRoute,
+  DepositRoute: DepositRoute,
+  DeviceRoute: DeviceRoute,
+  ErrorRoute: ErrorRoute,
+  LoginRoute: LoginRoute,
+  Char91_Char93FlowsRoute: Char91_Char93FlowsRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

package/src/app/router.tsx

@@ -0,0 +1,47 @@
+/** Creates the router. @module */
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen.js'
+
+/** Returns a router, once per server request and once in the browser. */
+export function getRouter() {
+  return createRouter({
+    // A loader reads the session, so its data is never reused for another navigation.
+    defaultPreloadStaleTime: 0,
+    parseSearch,
+    routeTree,
+    scrollRestoration: true,
+    stringifySearch,
+  })
+}
+
+/**
+ * Parses a search string into strings, with a list for a repeated parameter. The default parses
+ * JSON, which changes a user code of digits.
+ */
+function parseSearch(search: string) {
+  const params = new URLSearchParams(search)
+  return Object.fromEntries(
+    [...new Set(params.keys())].map((key) => {
+      const values = params.getAll(key)
+      return [key, values.length > 1 ? values : values[0]]
+    }),
+  )
+}
+
+/** Serializes search values as {@link parseSearch} reads them. */
+function stringifySearch(search: Record<string, unknown>) {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(search)) {
+    if (value === undefined) continue
+    for (const entry of Array.isArray(value) ? value : [value])
+      params.append(key, String(entry))
+  }
+  const query = params.toString()
+  return query ? `?${query}` : ''
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}