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

package/src/internal/Balance.ts

@@ -0,0 +1,168 @@
+/**
+ * The balance of a Tempo Account: its holdings of the USD tokens that Viem's token list names on a
+ * chain, summed in USD. Viem reads each token's TIP-20 `balanceOf` from the chain's node, in one
+ * batched request.
+ * @module
+ */
+import type { Context } from 'hono'
+import { Value } from 'ox'
+import {
+  BaseError,
+  ContractFunctionRevertedError,
+  createClient,
+  http,
+} from 'viem'
+import { readContract } from 'viem/actions'
+import { Actions } from 'viem/tempo'
+import { z } from 'zod'
+import type { Env } from './Env.js'
+import * as KeyAuthorization from './KeyAuthorization.js'
+import * as Log from './Log.js'
+import * as Timing from './Timing.js'
+
+/** The chain is not a Tempo chain, so no token list names its tokens. */
+export class UnknownChainError extends Error {
+  override readonly name = 'Balance.UnknownChainError'
+
+  constructor(options: UnknownChainError.Options) {
+    super(`Unknown chain: ${options.chainId}.`)
+  }
+}
+
+export declare namespace UnknownChainError {
+  type Options = {
+    /** The chain's ID. */
+    chainId: number
+  }
+}
+
+/** How long a read waits for the node, in milliseconds. A slower read fails, and the page continues. */
+const timeout = 3_000
+
+export namespace schema {
+  /** A balance, as the API returns it. */
+  export const balance = z
+    .object({
+      amount: z.string().meta({
+        description: 'The sum in USD, as a decimal string.',
+        examples: ['12.5'],
+      }),
+      currency: z
+        .literal('USD')
+        .meta({ description: 'The currency of `amount`.' }),
+    })
+    .meta({
+      description: "An account's holdings of USD tokens.",
+      id: 'Balance',
+    })
+}
+
+/**
+ * Returns the balance of the account at `address` on the chain with `chainId`, in USD. A token that
+ * the chain has not initialized holds nothing. Rejects when the chain is not a Tempo chain, or when
+ * the node fails or is slower than 3 seconds.
+ */
+export async function get(options: get.Options): Promise<get.ReturnType> {
+  const { address, chainId } = options
+  const chain = KeyAuthorization.chains.find((entry) => entry.id === chainId)
+  if (!chain) throw new UnknownChainError({ chainId })
+
+  const client = createClient({
+    chain,
+    transport: http(options.rpcUrl, { batch: true, retryCount: 0, timeout }),
+  })
+  const tokens = KeyAuthorization.listings({ chainId }).filter(
+    (token) => token.currency === 'USD',
+  )
+  const amounts = await Promise.all(
+    tokens.map(async (token) =>
+      readContract(
+        client,
+        Actions.token.getBalance.call({
+          account: address,
+          token: token.address,
+        }),
+      ).catch((error: unknown) => {
+        if (uninitialized(error)) return 0n
+        throw error
+      }),
+    ),
+  )
+
+  // The tokens can differ in decimals, so each amount scales to the largest before they add up.
+  const decimals = Math.max(0, ...tokens.map((token) => token.decimals))
+  const total = tokens.reduce(
+    (sum, token, index) =>
+      sum + amounts[index]! * 10n ** BigInt(decimals - token.decimals),
+    0n,
+  )
+  return { amount: Value.format(total, decimals), currency: 'USD' }
+}
+
+export declare namespace get {
+  type Options = {
+    /** The account's address. */
+    address: `0x${string}`
+    /** The ID of the chain to read. */
+    chainId: number
+    /** The RPC URL that replaces the chain's own, if any. */
+    rpcUrl?: string | undefined
+  }
+
+  type ReturnType = {
+    /** The sum in USD, as a decimal string, such as `12.5`. */
+    amount: string
+    /** The currency of `amount`: always `USD`. */
+    currency: 'USD'
+  }
+}
+
+/** Returns whether `error` is the TIP-20 `Uninitialized` revert of a token that the chain does not hold. */
+function uninitialized(error: unknown) {
+  if (!(error instanceof BaseError)) return false
+  const reverted = error.walk(
+    (cause) => cause instanceof ContractFunctionRevertedError,
+  )
+  return (
+    reverted instanceof ContractFunctionRevertedError &&
+    reverted.data?.errorName === 'Uninitialized'
+  )
+}
+
+/**
+ * Returns the balance of each account in `accounts` on the chain with `chainId`, in order, as
+ * {@link get} reads it. A failed or slow read logs, and returns `null` for its account.
+ */
+export function list(c: Context<Env>, options: list.Options) {
+  const { accounts, chainId, rpcUrl } = options
+  return Promise.all(
+    accounts.map((account) =>
+      Timing.measure(
+        c,
+        get({ address: account.address, chainId, rpcUrl }),
+        'Balance.get',
+      ).catch((error: unknown) => {
+        Log.warn(c, {
+          error,
+          fields: { chainId },
+          message: 'A balance failed to load.',
+        })
+        return null
+      }),
+    ),
+  )
+}
+
+export declare namespace list {
+  type Options = {
+    /** The accounts, each by its address. */
+    accounts: readonly {
+      /** The account's address. */
+      address: `0x${string}`
+    }[]
+    /** The ID of the chain to read. */
+    chainId: number
+    /** The RPC URL that replaces the chain's own, if any. */
+    rpcUrl?: string | undefined
+  }
+}

package/src/internal/BodyLimit.ts

@@ -0,0 +1,36 @@
+/**
+ * Caps request bodies before a validator or route reads them, and refuses a larger body with an
+ * OAuth error response. The largest legitimate body, an authorization request whose key limits
+ * every Tempo token, is under 20 KB, far below the cap.
+ * @module
+ */
+import { bodyLimit } from 'hono/body-limit'
+import * as ErrorResponse from './ErrorResponse.js'
+
+/** The request body exceeds {@link maxSize}. */
+export class BodyTooLargeError extends ErrorResponse.define('body_too_large') {
+  override readonly name = 'BodyLimit.BodyTooLargeError'
+
+  constructor() {
+    super({
+      error_description: `Invalid request body: exceeds the ${maxSize}-byte maximum. Send a body of ${maxSize} bytes or fewer.`,
+      meta: { maximum: maxSize },
+    })
+  }
+}
+
+/** The refusals {@link middleware} returns. */
+export const errors = [BodyTooLargeError] as const
+
+/** The largest body the API reads, in bytes. */
+export const maxSize = 64 * 1024
+
+/**
+ * Refuses a body over {@link maxSize} with `body_too_large`. It checks `Content-Length` when the
+ * request sends one. Otherwise it counts the streamed bytes as it buffers them for the route, which
+ * reads the buffered copy once.
+ */
+export const middleware = bodyLimit({
+  maxSize,
+  onError: (c) => ErrorResponse.json(c, new BodyTooLargeError()),
+})

package/src/internal/Chain.ts

@@ -0,0 +1,16 @@
+/**
+ * The Tempo chains whose balances Tempo ID reads, by the name that the `chain` parameter carries.
+ * The pages keep the parameter, so a chosen chain stays as the browser moves between them.
+ * @module
+ */
+import { tempo, tempoTestnet } from 'viem/tempo/chains'
+import { z } from 'zod'
+
+/** Each chain's ID, by its name. */
+export const ids = { mainnet: tempo.id, testnet: tempoTestnet.id } as const
+
+/** A chain's name: `mainnet` or `testnet`. */
+export const schema = z.enum(['mainnet', 'testnet'])
+
+/** A chain's name: `mainnet` or `testnet`. */
+export type Chain = z.output<typeof schema>

package/src/internal/Device.ts

@@ -0,0 +1,469 @@
+/**
+ * The device grant (RFC 8628) for CLIs, on Better Auth's device plugin. A CLI requests a code, a
+ * signed-in user approves it on the device page from any browser, and the CLI polls until it
+ * receives tokens. Better Auth holds each code's state in `device_code`, and `device_requests` holds
+ * what the CLI reported and the key that it requested, which the page shows. Approval signs the key
+ * and holds it in the same row, and the first redemption of the device code takes it.
+ * @module
+ */
+import { and, eq, exists, gt, isNull, sql } from 'drizzle-orm'
+import { Hex } from 'ox'
+import * as Schema from '../app/db/schema.js'
+import * as Authorize from './Authorize.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import type * as KeyAuthorization from './KeyAuthorization.js'
+import type * as PendingKey from './PendingKey.js'
+import type * as Realm from './Realm.js'
+
+/** The user code was already approved or denied. */
+export class AlreadyDecidedError extends ErrorResponse.define(
+  'already_decided',
+) {
+  override readonly name = 'Device.AlreadyDecidedError'
+
+  constructor() {
+    super({
+      error_description: 'Code already approved or denied.',
+      field: 'code',
+    })
+  }
+}
+
+/** The user did not decide the device code yet. */
+export class ApprovalPendingError extends ErrorResponse.define(
+  'approval_pending',
+) {
+  override readonly name = 'Device.ApprovalPendingError'
+
+  constructor() {
+    super({
+      error_description:
+        'Approval pending. Poll again after `interval` seconds.',
+    })
+  }
+}
+
+/** The device code is unknown, expired, or already redeemed. */
+export class DeviceCodeExpiredError extends ErrorResponse.define(
+  'device_code_expired',
+) {
+  override readonly name = 'Device.DeviceCodeExpiredError'
+
+  constructor() {
+    super({ error_description: 'Device code expired. Request a new code.' })
+  }
+}
+
+/** The device polled before its interval passed. */
+export class PollingTooFastError extends ErrorResponse.define(
+  'polling_too_fast',
+) {
+  override readonly name = 'Device.PollingTooFastError'
+
+  constructor() {
+    super({
+      error_description: 'Polling too fast. Add 5 seconds to `interval`.',
+    })
+  }
+}
+
+/** The user denied the device code. */
+export class RequestDeniedError extends ErrorResponse.define('request_denied') {
+  override readonly name = 'Device.RequestDeniedError'
+
+  constructor() {
+    super({ error_description: 'The user denied the request.' })
+  }
+}
+
+/** The user code is wrong or expired. */
+export class UnknownCodeError extends ErrorResponse.define('unknown_code') {
+  override readonly name = 'Device.UnknownCodeError'
+
+  constructor() {
+    super({
+      error_description:
+        'Invalid or expired code. Check the code in the terminal.',
+      field: 'code',
+    })
+  }
+}
+
+/** What the CLI reported with a device code, and the code's state, as the device page shows them. */
+export type Request = {
+  /** The message whose EIP-191 hash is the key's witness. Absent for a request without one. */
+  challenge?: string | undefined
+  /** The client ID of the app that requested the code. */
+  clientId: string
+  /** When the CLI requested the code. */
+  createdAt: Date
+  /**
+   * The name that the CLI reported, such as its hostname. Absent for a code from `POST /device/code`,
+   * which reports none.
+   */
+  device?: string | undefined
+  /** The ID of the `device_code` row. */
+  id: string
+  /** The CLI's IP address. Absent when it is unknown. */
+  ip?: string | undefined
+  /**
+   * The key that the CLI requested, with every default filled and the challenge bound as its
+   * witness. Absent for a request without a key.
+   */
+  key?: KeyAuthorization.Key | undefined
+  /** The CLI's city and country, from its IP address. Absent when they are unknown. */
+  location?: string | undefined
+  /** Whether the user approved or denied the code. `pending` until the user decides. */
+  status: 'approved' | 'denied' | 'pending'
+  /** The user code, as the pages show it, such as `BCDF-GHJK`. */
+  userCode: string
+  /** The ID of the user whom the code is bound to, the first to read or decide it. Absent until then. */
+  userId?: string | undefined
+}
+
+/**
+ * The client ID of the app that a device grant of `/v1/device/authorize` signs in to without a
+ * `client_id`. `tempo-id login` uses it.
+ */
+export const clientId = 'tempo-cli'
+
+/** The scopes of every device grant of `/v1/device/authorize`. */
+export const scope = 'openid email offline_access'
+
+/** Seconds that a device code lasts. */
+export const lifetime = 10 * 60
+
+/** Seconds that a CLI waits between polls. */
+export const interval = 5
+
+/** Consonants only, so codes spell no words and survive being read aloud. */
+const consonants = 'BCDFGHJKLMNPQRSTVWXZ'
+
+/**
+ * Returns the client ID of the app that requested the live user code `userCode`, as
+ * {@link normalize} returns it, while the code is pending and bound to no user. Returns `undefined`
+ * for any other code, so a sign-in that returns to the device page reveals nothing about a code that
+ * is unknown, expired, decided, or held. The read binds nothing.
+ */
+export async function client(db: Realm.Database, options: client.Options) {
+  const found = await get(db, options)
+  if (!found || found.status !== 'pending' || found.userId) return undefined
+  return found.clientId
+}
+
+export declare namespace client {
+  type Options = {
+    /** The user code, as {@link normalize} returns it. */
+    userCode: string
+  }
+}
+
+/**
+ * Stores what the CLI reported with the device code whose row has `id`, and the key that it
+ * requested, until the code expires at `expiresAt`.
+ */
+export async function create(db: Realm.Database, options: create.Options) {
+  const { challenge, device, expiresAt, id, ip, location } = options
+  // The key's bigints are stored as hex quantities, which the request schema parses back.
+  const key = options.key
+    ? (JSON.parse(
+        JSON.stringify(options.key, (_, value: unknown) =>
+          typeof value === 'bigint' ? Hex.fromNumber(value) : value,
+        ),
+      ) as unknown)
+    : null
+  await db
+    .insert(Schema.deviceRequests)
+    .values({ challenge, device, expiresAt, id, ip, key, location })
+}
+
+export declare namespace create {
+  type Options = {
+    /** The message whose hash becomes the key's witness. Null for a request without one. */
+    challenge: string | null
+    /** The name that the CLI reported, such as its hostname. Null for a code from `POST /device/code`. */
+    device: string | null
+    /** When the device code expires. */
+    expiresAt: Date
+    /** The ID of the device code's `device_code` row. */
+    id: string
+    /** The CLI's IP address. Null when it is unknown. */
+    ip: string | null
+    /**
+     * The key that the CLI requested, with every default filled, before the challenge is bound.
+     * Null for a request without a key.
+     */
+    key: KeyAuthorization.Key | null
+    /** The CLI's city and country. Null when they are unknown. */
+    location: string | null
+  }
+}
+
+/**
+ * Returns `userCode` as the pages show it, in two groups of four, such as `BCDF-GHJK`. Better Auth
+ * stores the code without the hyphen.
+ */
+export function format(userCode: string) {
+  return `${userCode.slice(0, 4)}-${userCode.slice(4)}`
+}
+
+/**
+ * Returns the request of the live device code `userCode`, as {@link normalize} returns it, with the
+ * code's state. Returns `undefined` for an unknown or expired code.
+ */
+export async function get(
+  db: Realm.Database,
+  options: get.Options,
+): Promise<Request | undefined> {
+  const [row] = await db
+    .select({
+      challenge: Schema.deviceRequests.challenge,
+      clientId: Schema.deviceCode.clientId,
+      createdAt: Schema.deviceRequests.createdAt,
+      device: Schema.deviceRequests.device,
+      expiresAt: Schema.deviceCode.expiresAt,
+      id: Schema.deviceCode.id,
+      ip: Schema.deviceRequests.ip,
+      key: Schema.deviceRequests.key,
+      location: Schema.deviceRequests.location,
+      status: Schema.deviceCode.status,
+      userCode: Schema.deviceCode.userCode,
+      userId: Schema.deviceCode.userId,
+    })
+    .from(Schema.deviceCode)
+    .leftJoin(
+      Schema.deviceRequests,
+      eq(Schema.deviceRequests.id, Schema.deviceCode.id),
+    )
+    .where(
+      and(
+        eq(Schema.deviceCode.userCode, options.userCode),
+        gt(Schema.deviceCode.expiresAt, new Date()),
+      ),
+    )
+  // Better Auth sets the client ID of every code that an app requests.
+  if (!row?.clientId) return undefined
+  // The stored key passed the same schema when the CLI requested it.
+  const key = row.key
+    ? Authorize.schema.redirect.parse({
+        challenge: row.challenge ?? undefined,
+        key_authorization: row.key,
+      })
+    : undefined
+  return {
+    ...(row.challenge ? { challenge: row.challenge } : {}),
+    clientId: row.clientId,
+    // Tempo ID stores each code's request just after Better Auth issues the code, so a read between
+    // the two finds none. Every code lasts `lifetime` seconds.
+    createdAt:
+      row.createdAt ?? new Date(row.expiresAt.getTime() - lifetime * 1000),
+    ...(row.device ? { device: row.device } : {}),
+    id: row.id,
+    ...(row.ip ? { ip: row.ip } : {}),
+    ...(key ? { key } : {}),
+    ...(row.location ? { location: row.location } : {}),
+    status: status(row.status),
+    userCode: format(row.userCode),
+    ...(row.userId ? { userId: row.userId } : {}),
+  }
+}
+
+export declare namespace get {
+  type Options = {
+    /** The user code, as {@link normalize} returns it. */
+    userCode: string
+  }
+}
+
+/**
+ * Holds `key`, which approval signed, in the request of the device code whose row has `id`, until
+ * the first redemption of the code takes it. Holds it only while the code is pending, bound to the
+ * user with `userId`, and holds no key yet, and returns whether it did. Of concurrent approvals, only
+ * the one that holds its key goes on to approve the code.
+ */
+export async function hold(db: Realm.Database, options: hold.Options) {
+  const { id, key, userId } = options
+  const rows = await db
+    .update(Schema.deviceRequests)
+    .set({ account: key.account, keyAuthorization: key.keyAuthorization })
+    .where(
+      and(
+        eq(Schema.deviceRequests.id, id),
+        isNull(Schema.deviceRequests.keyAuthorization),
+        exists(
+          db
+            .select({ id: Schema.deviceCode.id })
+            .from(Schema.deviceCode)
+            .where(
+              and(
+                eq(Schema.deviceCode.id, id),
+                eq(Schema.deviceCode.status, 'pending'),
+                eq(Schema.deviceCode.userId, userId),
+                gt(Schema.deviceCode.expiresAt, new Date()),
+              ),
+            ),
+        ),
+      ),
+    )
+    .returning({ id: Schema.deviceRequests.id })
+  return rows.length > 0
+}
+
+export declare namespace hold {
+  type Options = {
+    /** The ID of the device code's `device_code` row. */
+    id: string
+    /** The signed key authorization, and the account that it acts for. */
+    key: PendingKey.PendingKey
+    /** The ID of the user who approves the code, whom the code must be bound to. */
+    userId: string
+  }
+}
+
+/**
+ * Releases `key`, which `hold` held for the device code whose row has `id`, while the code is
+ * still pending, so the approving user can approve again after a failed approval. Another
+ * approval's key stays.
+ */
+export async function release(db: Realm.Database, options: release.Options) {
+  const { id, key } = options
+  await db
+    .update(Schema.deviceRequests)
+    .set({ account: null, keyAuthorization: null })
+    .where(
+      and(
+        eq(Schema.deviceRequests.id, id),
+        sql`${Schema.deviceRequests.keyAuthorization} = ${JSON.stringify(key.keyAuthorization)}::jsonb`,
+        exists(
+          db
+            .select({ id: Schema.deviceCode.id })
+            .from(Schema.deviceCode)
+            .where(
+              and(
+                eq(Schema.deviceCode.id, id),
+                eq(Schema.deviceCode.status, 'pending'),
+              ),
+            ),
+        ),
+      ),
+    )
+}
+
+export declare namespace release {
+  type Options = {
+    /** The ID of the device code's `device_code` row. */
+    id: string
+    /** The key that `hold` held. */
+    key: PendingKey.PendingKey
+  }
+}
+
+/**
+ * Returns the ID of the `device_code` row of `deviceCode`, the CLI's secret code, or `undefined`
+ * when no row holds it.
+ */
+export async function id(db: Realm.Database, options: id.Options) {
+  const [row] = await db
+    .select({ id: Schema.deviceCode.id })
+    .from(Schema.deviceCode)
+    .where(eq(Schema.deviceCode.deviceCode, options.deviceCode))
+  return row?.id
+}
+
+export declare namespace id {
+  type Options = {
+    /** The device code that the CLI holds. */
+    deviceCode: string
+  }
+}
+
+/**
+ * Returns what a user typed as a user code, in the form that Better Auth stores: eight consonants in
+ * upper case, without the hyphen. Returns `undefined` when the value cannot be a user code.
+ */
+export function normalize(value: string) {
+  const characters = value.toUpperCase().replace(/[^A-Z]/g, '')
+  if (
+    characters.length !== 8 ||
+    [...characters].some((character) => !consonants.includes(character))
+  )
+    return undefined
+  return characters
+}
+
+/** The path of the device page, the verification URI. */
+export const page = '/device'
+
+/**
+ * Returns the device page that sign-in returns the browser to, from the `return_to` value `value`:
+ * the exact path `/device`, with at most one query parameter, the user code, as `code` or
+ * `user_code`. Parses `value` against Tempo ID's own `origin`, and rebuilds the path from the
+ * normalized code. Returns `undefined` for any other value, such as another path, host, or scheme, a
+ * protocol-relative or backslash form, or another parameter, so sign-in redirects only to the
+ * device page.
+ */
+export function returnTo(
+  value: string | null | undefined,
+  options: returnTo.Options,
+) {
+  // Only a path-absolute value names Tempo ID's own page. `//` and `/\` name another host.
+  if (!value || !value.startsWith('/') || /^\/[/\\]/.test(value))
+    return undefined
+  const base = new URL(options.origin)
+  const url = URL.parse(value, base)
+  if (!url || url.origin !== base.origin || url.pathname !== page || url.hash)
+    return undefined
+
+  const keys = [...url.searchParams.keys()]
+  if (keys.length === 0) return page
+  const [key] = keys
+  if (keys.length > 1 || (key !== 'code' && key !== 'user_code'))
+    return undefined
+  const userCode = normalize(url.searchParams.get(key) ?? '')
+  if (!userCode) return undefined
+  return `${page}?${new URLSearchParams({ code: format(userCode) })}`
+}
+
+export declare namespace returnTo {
+  type Options = {
+    /** Tempo ID's origin, such as `https://id.tempo.xyz`, which the path resolves against. */
+    origin: string
+  }
+}
+
+/**
+ * Deletes the request of the device code whose row has `id`, once its redemption issued tokens, and
+ * returns the signed key that approval held in it. Returns `undefined` when it holds none, or when
+ * another redemption took it.
+ */
+export async function take(
+  db: Realm.Database,
+  options: take.Options,
+): Promise<PendingKey.PendingKey | undefined> {
+  const [row] = await db
+    .delete(Schema.deviceRequests)
+    .where(eq(Schema.deviceRequests.id, options.id))
+    .returning({
+      account: Schema.deviceRequests.account,
+      keyAuthorization: Schema.deviceRequests.keyAuthorization,
+    })
+  if (!row?.account || !row.keyAuthorization) return undefined
+  return {
+    account: row.account as `0x${string}`,
+    keyAuthorization:
+      row.keyAuthorization as PendingKey.PendingKey['keyAuthorization'],
+  }
+}
+
+export declare namespace take {
+  type Options = {
+    /** The ID of the redeemed device code's `device_code` row. */
+    id: string
+  }
+}
+
+/** Returns the state that Better Auth stores in `device_code.status`. */
+function status(value: string): Request['status'] {
+  if (value === 'approved' || value === 'denied') return value
+  return 'pending'
+}