@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Device.ts

@@ -0,0 +1,471 @@
+/**
+ * The device grant (RFC 8628) for CLIs, on Better Auth's device plugin, which holds each code in
+ * `device_code`. `device_requests` holds what the CLI reported, the requested key, and the signed
+ * key until the first redemption takes it. Each write is one conditional update.
+ * @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 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',
+    })
+  }
+}
+
+/** A device code's state, and what the CLI reported with it, for the device page. */
+export type Request = {
+  /** The requesting app's name. Absent once an admin deletes the app. */
+  appName?: string | undefined
+  /** The message whose EIP-191 hash is the key's witness, if any. */
+  challenge?: string | undefined
+  /** The requesting app's client ID. */
+  clientId: string
+  /** When the CLI requested the code. */
+  createdAt: Date
+  /** The CLI's reported name, such as its hostname. Absent for a code from `POST /device/code`. */
+  device?: string | undefined
+  /** The ID of the `device_code` row. */
+  id: string
+  /** The CLI's IP address, if known. */
+  ip?: string | undefined
+  /** The requested key, with its defaults filled and the challenge as its witness, if any. */
+  key?: KeyAuthorization.Key | undefined
+  /** The CLI's city and country, from its IP address, if known. */
+  location?: string | undefined
+  /** `pending` until the user approves or denies the code. */
+  status: 'approved' | 'denied' | 'pending'
+  /** As the pages show it, such as `BCDF-GHJK`. */
+  userCode: string
+  /** The user that the code is bound to: the first to read or decide it. Absent until then. */
+  userId?: string | undefined
+}
+
+/** The scopes of a device authorization request that names none. */
+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'
+
+/**
+ * Binds the live, pending, unbound device code with row `id` to `userId`, as Better Auth's
+ * `/device` does. Returns whether it did. Of concurrent calls, only one binds the code.
+ */
+export async function bind(db: Realm.Database, options: bind.Options) {
+  const rows = await db
+    .update(Schema.deviceCode)
+    .set({ userId: options.userId })
+    .where(
+      and(
+        eq(Schema.deviceCode.id, options.id),
+        eq(Schema.deviceCode.status, 'pending'),
+        isNull(Schema.deviceCode.userId),
+        gt(Schema.deviceCode.expiresAt, new Date()),
+      ),
+    )
+    .returning({ id: Schema.deviceCode.id })
+  return rows.length > 0
+}
+
+export declare namespace bind {
+  type Options = {
+    /** The `device_code` row ID. */
+    id: string
+    /** The signed-in user who reads or decides the code. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the client ID of the app that requested the live, pending, unbound `userCode`, and binds
+ * nothing. Returns `undefined` for any other code, so a sign-in reveals nothing about it.
+ */
+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 `deviceCode`, and the key that it requested, until `expiresAt`.
+ * Rejects a code without a `device_code` row.
+ */
+export async function create(db: Realm.Database, options: create.Options) {
+  const { challenge, device, deviceCode, expiresAt, 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
+  const id = db
+    .select({ id: Schema.deviceCode.id })
+    .from(Schema.deviceCode)
+    .where(eq(Schema.deviceCode.deviceCode, deviceCode))
+  await db.insert(Schema.deviceRequests).values({
+    challenge,
+    device,
+    expiresAt,
+    id: sql`(${id})`,
+    ip,
+    key,
+    location,
+  })
+}
+
+export declare namespace create {
+  type Options = {
+    /** The message whose hash becomes the key's witness, or null. */
+    challenge: string | null
+    /** The CLI's reported name, such as its hostname. Null for a code from `POST /device/code`. */
+    device: string | null
+    /** The device code that Better Auth just issued. */
+    deviceCode: string
+    /** When the device code expires. */
+    expiresAt: Date
+    /** The CLI's IP address, or null. */
+    ip: string | null
+    /** The requested key, with its defaults filled and no challenge bound, or null. */
+    key: KeyAuthorization.Key | null
+    /** The CLI's city and country, or null. */
+    location: string | null
+  }
+}
+
+/**
+ * Records `status` on the live, pending device code with row `id` that is bound to `userId`, as
+ * Better Auth's `/device/approve` and `/device/deny` do. Returns whether it did. Of concurrent
+ * decisions, only one records its status.
+ */
+export async function decide(db: Realm.Database, options: decide.Options) {
+  const rows = await db
+    .update(Schema.deviceCode)
+    .set({ status: options.status })
+    .where(
+      and(
+        eq(Schema.deviceCode.id, options.id),
+        eq(Schema.deviceCode.status, 'pending'),
+        eq(Schema.deviceCode.userId, options.userId),
+        gt(Schema.deviceCode.expiresAt, new Date()),
+      ),
+    )
+    .returning({ id: Schema.deviceCode.id })
+  return rows.length > 0
+}
+
+export declare namespace decide {
+  type Options = {
+    /** The `device_code` row ID. */
+    id: string
+    /** As Better Auth stores it in `device_code.status`. */
+    status: 'approved' | 'denied'
+    /** The deciding user, whom the code must be bound to. */
+    userId: string
+  }
+}
+
+/** Returns `userCode` in two groups of four, such as `BCDF-GHJK`, as the pages show it. */
+export function format(userCode: string) {
+  return `${userCode.slice(0, 4)}-${userCode.slice(4)}`
+}
+
+/** Returns the request of the live `userCode`, with its state and app name, or `undefined`. */
+export async function get(
+  db: Realm.Database,
+  options: get.Options,
+): Promise<Request | undefined> {
+  const [row] = await db
+    .select({
+      appName: Schema.oauthClient.name,
+      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),
+    )
+    // The name is display data, so a disabled app still names the code, as the page shows it.
+    .leftJoin(
+      Schema.oauthClient,
+      eq(Schema.oauthClient.clientId, Schema.deviceCode.clientId),
+    )
+    .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.appName ? { appName: row.appName } : {}),
+    ...(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 the signed `key` for the device code with row `id` until the first redemption takes it.
+ * Returns whether the code was pending, bound to `userId`, and held no key. Of concurrent
+ * approvals, only the one that holds its key approves 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 `device_code` row ID. */
+    id: string
+    /** The signed key authorization, and its account. */
+    key: PendingKey.PendingKey
+    /** The approving user, whom the code must be bound to. */
+    userId: string
+  }
+}
+
+/**
+ * Releases `key` from the pending device code with row `id`, so the 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 `device_code` row ID. */
+    id: string
+    /** The key that `hold` held. */
+    key: PendingKey.PendingKey
+  }
+}
+
+/**
+ * Returns the `device_code` row of the CLI's secret `deviceCode`: its ID and the client ID of the app
+ * that requested it. Returns `undefined` for an unknown or redeemed code.
+ */
+export async function find(db: Realm.Database, options: find.Options) {
+  const [row] = await db
+    .select({
+      clientId: Schema.deviceCode.oauthClientId,
+      id: Schema.deviceCode.id,
+    })
+    .from(Schema.deviceCode)
+    .where(eq(Schema.deviceCode.deviceCode, options.deviceCode))
+  return row
+}
+
+export declare namespace find {
+  type Options = {
+    /** The device code that the CLI holds. */
+    deviceCode: string
+  }
+}
+
+/** Returns a typed user code as Better Auth stores it, 8 upper-case consonants, or `undefined`. */
+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 to, from the `return_to` value: the exact path
+ * `/device`, with at most the user code as `code` or `user_code`. Returns `undefined` for any other
+ * value, 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, which the path resolves against. */
+    origin: string
+  }
+}
+
+/**
+ * Deletes the request of the redeemed device code with row `id`, and returns its held key. Returns
+ * `undefined` when it holds none, or 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 `device_code` row ID of the redeemed code. */
+    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'
+}

package/src/internal/Env.ts

@@ -0,0 +1,92 @@
+/**
+ * The Hono environment that Tempo ID's middleware and route apps share.
+ * @module
+ */
+import type { Context } from 'hono'
+import type * as Apps from './Apps.js'
+import type * as Auth from './Auth.js'
+import type * as Cache from './Cache.js'
+import type * as Limits from './Limits.js'
+import type * as Privy from './Privy.js'
+import type * as RateLimit from './RateLimit.js'
+import type * as RequestId from './RequestId.js'
+import type * as TempoAccount from './TempoAccount.js'
+import type * as TestInbox from './TestInbox.js'
+import type * as Timing from './Timing.js'
+import type * as Wallet from './Wallet.js'
+
+/** The bindings and variables of a request. */
+export type Env = {
+  /** The bindings that the root app reads, with each rate limit by its name. */
+  Bindings: {
+    /**
+     * The handler's cache, from `App.create`. Absent, as in `vp dev`, `IsolateCache.middleware`
+     * creates one.
+     */
+    CACHE?: Cache.Cache | undefined
+    /** Serves third-party apps' metadata documents in place of their hosts. Absent, hosts do. */
+    CLIENT_METADATA?: Apps.fetchMetadata.Fetcher | undefined
+    /**
+     * The owner keys that a page's request listed, which each in-process call of its loaders shares,
+     * so the page lists each user's keys once. Absent for a request from a browser or an app.
+     */
+    ownerLists?: TempoAccount.Lists | undefined
+    /**
+     * Renders the page of `options.request`, or of `c`'s request, through TanStack Start, or the
+     * not-found page. A page of another URL than `c`'s replaces the browser's URL with its own.
+     */
+    pages: (c: Context<Env>, options?: Pages) => Promise<Response>
+    /**
+     * Returns the paths of the sign-in page's scripts and style sheets on Tempo ID's origin, from the
+     * build's manifest, without duplicates.
+     */
+    signInAssets: () => Promise<readonly string[]>
+    /** Receives the codes of addresses under `TEST_EMAIL_DOMAIN`. Only a preview binds it. */
+    TEST_INBOX?: TestInbox.Service | undefined
+    /**
+     * wallet.tempo's `Credentials` entrypoint, which links its passkeys at their first sign-in.
+     * Absent, only stored passkeys sign in.
+     */
+    WALLET?: Wallet.Service | undefined
+  } & Record<Limits.Limit, RateLimit.Limiter>
+  /** The values that middleware sets on `c.var`. */
+  Variables: Variables
+}
+
+/** The options of the `pages` binding. */
+export type Pages = {
+  /** The request of the page to render, on Tempo ID's origin. Defaults to `c`'s request. */
+  request?: Request | undefined
+}
+
+/** The values that middleware sets on `c.var` for each request. */
+export type Variables = {
+  /**
+   * Whether the request already chose the app's account, as `POST /v1/authorize` does, so the
+   * account step reads no accounts again.
+   */
+  accountChosen?: boolean | undefined
+  /** The request's Better Auth instance, from `Auth.middleware`. */
+  auth: Auth.Instance
+  /** The handler's cache, from `IsolateCache.middleware`. */
+  cache: Cache.Cache
+  /**
+   * The outcomes of the request's rate limit counters, by binding and key, which `RateLimit.count`
+   * keeps so the request counts against each once.
+   */
+  counted?: Map<string, Promise<boolean>> | undefined
+  /** The enabled first-party apps at `Origin`, which `Cors.firstParty` reads for a write only. */
+  firstParty?: readonly Apps.App[] | undefined
+  /** The session that a sign-in in this request created. Absent before a sign-in. */
+  newSession?: { session: { id: string }; user: { id: string } } | undefined
+  /** The owner keys that the request listed, from `TempoAccount.middleware`. */
+  ownerLists?: TempoAccount.Lists | undefined
+  /** The Privy users that the request read or created. */
+  privyUsers: Privy.Users
+  /** The codes of the response's OAuth error body, which `RequestId.middleware()` sets. */
+  refusal: RequestId.Refusal | undefined
+  /** The request ID, which `RequestId.middleware()` assigns. */
+  requestId: string
+  /** The request's timings, which `Timing.measure` appends to. */
+  timing: Timing.Timing
+}