@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/TempoAccount.ts

@@ -0,0 +1,545 @@
+/**
+ * Each user's Tempo Accounts: configurable accounts (TIP-1107), each in one realm and owned by one
+ * key. Each kind in {@link kinds}, such as Privy wallets and passkeys, lists the
+ * keys of its kind, and a kind that creates keys creates a user's first account. The key acts as the
+ * account on each chain, except on the chains that `CONFIGURABLE_ACCOUNTS` names, where the account
+ * is configurable, as `ConfigurableAccount` describes. A request names the chain it acts on, and the
+ * owners carry their view of that chain.
+ * @module
+ */
+import { and, eq, inArray, notExists, sql } from 'drizzle-orm'
+import { createMiddleware } from 'hono/factory'
+import { AccountConfig } from 'viem/tempo'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import * as ConfigurableAccount from './ConfigurableAccount.js'
+import type { Env } from './Env.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Owner from './Owner.js'
+import * as Passkey from './owners/Passkey.js'
+import * as Privy from './owners/Privy.js'
+import * as Secp256k1 from './owners/Secp256k1.js'
+import type * as Realm from './Realm.js'
+import * as Timing from './Timing.js'
+
+/** The request names a Tempo Account that is not one of the user's in the app's realms. */
+export class ForeignAccountError extends ErrorResponse.define(
+  'foreign_account',
+) {
+  override readonly name = 'TempoAccount.ForeignAccountError'
+
+  constructor(options: ForeignAccountError.Options) {
+    super({
+      error_description: `Access denied to Tempo Account ${options.account}. Name one of the user's accounts in the app's realms.`,
+      field: options.field ?? 'account',
+      meta: { account: options.account },
+    })
+  }
+}
+
+export declare namespace ForeignAccountError {
+  type Options = {
+    /** The address that the request named. */
+    account: string
+    /** The request field that named the address. Defaults to `account`. */
+    field?: string | undefined
+  }
+}
+
+/**
+ * The kinds of owner keys, in the order that breaks a tie in creation time: a passkey comes before a
+ * Privy wallet created in the same second, and a Privy wallet before a secp256k1 key. The first kind
+ * that creates keys in a realm creates a user's first account there, so a realm with a Privy app
+ * creates Privy wallets even where it also holds secp256k1 owners.
+ */
+export const kinds = [Passkey.owner, Privy.owner, Secp256k1.owner] as const
+
+/**
+ * A request's context. Once {@link middleware} ran, it holds the owner keys that the request listed,
+ * so a request lists each user's keys in the same realms once.
+ */
+export type Context = Owner.Context & {
+  /** The request's variables. */
+  var: {
+    /** The owner keys that the request listed. Absent, as in the CLI, each list reads again. */
+    ownerLists?: Lists | undefined
+  }
+}
+
+/**
+ * The owner keys that one request listed, by user and realms, as each kind's list in the order of
+ * {@link kinds}. {@link middleware} creates it for each request, and {@link forget} empties it after a
+ * write that changes a user's owner keys.
+ */
+export type Lists = Map<
+  string,
+  Promise<readonly (readonly Owner.Owner<Type>[])[]>
+>
+
+/** A user's Tempo Account, as the API returns it. */
+export type TempoAccount = z.output<typeof schema.tempoAccount>
+
+/** The owner type in the API, such as `privy`, `secp256k1`, or `webAuthn`. */
+export type Type = (typeof kinds)[number]['type']
+
+/** Zod schemas for Tempo Accounts as the API returns them. */
+export namespace schema {
+  const address = z
+    .templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]{40}$/)])
+    .meta({
+      description: 'A 20-byte address.',
+      examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+    })
+
+  /** A realm, with its display name. */
+  export const realm = z
+    .object({
+      id: z.string().meta({
+        description: 'The realm ID, such as `default` or `tempo-cash`.',
+        examples: ['tempo-cash'],
+      }),
+      name: z.string().meta({
+        description: 'The realm display name, such as `Tempo Cash`.',
+        examples: ['Tempo Cash'],
+      }),
+    })
+    .meta({
+      description:
+        'A realm, which holds Tempo Accounts. An app reaches only the accounts of its realms.',
+      id: 'Realm',
+    })
+
+  /** A Tempo Account, with its configuration and its realm. */
+  export const tempoAccount = z
+    .object({
+      address: address.meta({
+        description:
+          "The address on the request's chain: the owner key's address, or the initial configuration's address on a chain with configurable accounts. A linked wallet.tempo passkey keeps its own address, also after its upgrade.",
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+      }),
+      config: z
+        .object({
+          chainId: z
+            .number()
+            .int()
+            .optional()
+            .meta({
+              description:
+                'The ID of the chain where the configuration applies, which the request named. Absent on a chain whose accounts are not configurable, and for a wallet.tempo passkey that no upgrade made configurable.',
+              examples: [31318],
+            }),
+          owners: z
+            .array(
+              z
+                .object({
+                  owner: address.meta({
+                    description: 'The address of the owner key.',
+                    examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+                  }),
+                  type: z.enum(kinds.map((kind) => kind.type)).meta({
+                    description:
+                      'Who holds the owner key: a Privy wallet (`privy`), a key that Tempo ID holds in development (`secp256k1`), or a passkey (`webAuthn`), which signs only in the browser.',
+                    examples: ['webAuthn'],
+                  }),
+                  weight: z.number().meta({
+                    description:
+                      "The owner's signing weight, which counts toward `threshold`.",
+                    examples: [1],
+                  }),
+                })
+                .meta({ description: 'One key that signs for the account.' }),
+            )
+            .readonly()
+            .meta({ description: 'The keys that sign for the account.' }),
+          salt: z.templateLiteral(['0x', z.string()]).meta({
+            description:
+              'The 32-byte salt that the account address derives from, as hex.',
+            examples: [`0x${'0'.repeat(64)}`],
+          }),
+          threshold: z.number().meta({
+            description:
+              'The total owner weight that a signature needs to act for the account.',
+            examples: [1],
+          }),
+          version: z.templateLiteral(['0x', z.string()]).meta({
+            description: 'The configuration version, as a hex quantity.',
+            examples: ['0x0'],
+          }),
+        })
+        .meta({
+          description:
+            'The account configuration (TIP-1107): its owners, salt, threshold, and version.',
+        }),
+      realm,
+    })
+    .meta({
+      description:
+        'A configurable Tempo Account (TIP-1107) and its configuration.',
+      id: 'TempoAccount',
+    })
+}
+
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, as {@link held} does, and creates
+ * one in the first realm for a user with none, when a kind creates keys in that realm. On a
+ * deployment with configurable accounts, the new account is configurable from its creation. A user with a
+ * linked owner key, such as a wallet.tempo passkey, receives none. Concurrent calls, through apps
+ * whose realms overlap, and a link at the same time create one account. No database connection
+ * stays open while a kind creates the key.
+ */
+export async function create(
+  c: Context,
+  options: create.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const { db, realms, userId } = options
+  const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load')
+
+  const held = await Timing.measure(
+    c,
+    owners(c, {
+      chainId: options.chainId,
+      db,
+      env: options.env,
+      key: listKey(options),
+      loaded,
+      userId,
+    }),
+    'TempoAccount.owners',
+  )
+  if (held.length > 0) return held
+
+  const creator = (realm: Realm.Realm) => {
+    for (const entry of loaded) {
+      const fn = entry.create?.(realm)
+      if (fn) return fn
+    }
+    return undefined
+  }
+  const realm = realms[0]
+  if (!realm || !creator(realm)) return []
+
+  // A short transaction under the user's lock picks the realm, so the kind's calls after it hold no
+  // database connection. A claim in these realms, from a request through an app whose realms
+  // overlap them, wins over the first realm. A linked key that a kind stored before the claim wins
+  // over both. A link after the claim adds the linked key's account beside the created one.
+  const creates = realms.filter((entry) => creator(entry))
+  const target = await db.transaction(async (tx) => {
+    await Timing.measure(c, Owner.lock(tx, { userId }), 'db.account.lock')
+    const linked = await Timing.measure(
+      c,
+      owners(c, {
+        // The recheck lists a linked key on the chain, as the read before the lock does.
+        chainId: options.chainId,
+        db: tx,
+        env: options.env,
+        loaded: loaded.filter((entry) => !entry.create),
+        userId,
+      }),
+      'TempoAccount.linked',
+    )
+
+    // Only a claim in a realm where a kind creates keys counts.
+    const claims = tx.$with('claims').as(
+      tx
+        .select({ realmId: Schema.firstAccounts.realmId })
+        .from(Schema.firstAccounts)
+        .where(
+          and(
+            eq(Schema.firstAccounts.userId, userId),
+            inArray(
+              Schema.firstAccounts.realmId,
+              creates.map((entry) => entry.id),
+            ),
+          ),
+        ),
+    )
+    // One statement reads the claims and, without a claim or a linked key, claims the first realm.
+    // Both parts read the claims as they were before the statement.
+    const claim = tx.$with('claim').as(
+      tx
+        .insert(Schema.firstAccounts)
+        .select(
+          tx
+            .select({
+              createdAt: sql<Date>`now()`.as('created_at'),
+              realmId: sql<string>`${realm.id}`.as('realm_id'),
+              userId: Schema.user.id,
+            })
+            .from(Schema.user)
+            .where(
+              and(
+                eq(Schema.user.id, userId),
+                notExists(tx.select().from(claims)),
+              ),
+            ),
+        )
+        .onConflictDoNothing()
+        .returning({ realmId: Schema.firstAccounts.realmId }),
+    )
+    const rows = await Timing.measure(
+      c,
+      linked.length > 0
+        ? tx.with(claims).select().from(claims)
+        : tx.with(claims, claim).select().from(claims),
+      'db.account.claims',
+    )
+
+    const claimed = realms.find((entry) =>
+      rows.some((row) => row.realmId === entry.id),
+    )
+    if (claimed) return { realm: claimed }
+    if (linked.length > 0) return { linked }
+    return { realm }
+  })
+  if ('linked' in target) {
+    // Another request linked a key after the read before the lock, so a later list reads again.
+    c.var.ownerLists?.delete(listKey(options))
+    return target.linked
+  }
+
+  const owner = await Timing.measure(
+    c,
+    creator(target.realm)!(c),
+    'TempoAccount.createOwner',
+  )
+  // Another request can link a key while the kind creates this one, so a later list reads again.
+  c.var.ownerLists?.delete(listKey(options))
+
+  // On a chain with configurable accounts, the new key owns the account that its initial
+  // configuration derives, which no row stores.
+  const chain = ConfigurableAccount.on(options)
+  if (!chain) return [owner]
+  return ConfigurableAccount.apply([owner], {
+    chainId: chain.chainId,
+    configs: [],
+  })
+}
+
+export namespace create {
+  export type Options = list.Options
+
+  /** The refusals `create` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = [
+    ...Passkey.owner.errors,
+    ...Privy.owner.errors,
+    ...Secp256k1.owner.errors,
+  ] as const
+}
+
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, oldest first, and creates none.
+ * Each kind reads its keys in parallel.
+ */
+export async function held(
+  c: Context,
+  options: held.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load')
+  return await Timing.measure(
+    c,
+    owners(c, {
+      chainId: options.chainId,
+      db: options.db,
+      env: options.env,
+      key: listKey(options),
+      loaded,
+      userId: options.userId,
+    }),
+    'TempoAccount.owners',
+  )
+}
+
+export namespace held {
+  export type Options = list.Options
+
+  /** The refusals `held` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = create.errors
+}
+
+/**
+ * Returns the user's Tempo Accounts in `realms`, oldest first, as the API returns them, and creates
+ * none. Their owners are those that {@link held} returns.
+ */
+export async function list(
+  c: Context,
+  options: list.Options,
+): Promise<readonly TempoAccount[]> {
+  const owned = await Timing.measure(c, held(c, options), 'TempoAccount.held')
+  return owned.map(serialize)
+}
+
+export namespace list {
+  export type Options = {
+    /**
+     * The ID of the chain that the request acts on. On a chain that `CONFIGURABLE_ACCOUNTS` names,
+     * each owner carries its configurable view, whose address is the account's there. Absent, or on
+     * any other chain, each key acts as its account.
+     */
+    chainId?: number | undefined
+    /** The database. */
+    db: Realm.Database
+    /** The deployment variables that the kinds read. */
+    env: Owner.Env
+    /** The realms that the request reaches, in order. The first holds a user's first account. */
+    realms: readonly Realm.Realm[]
+    /** The user's ID. */
+    userId: string
+  }
+
+  /** The refusals `list` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+  export const errors = create.errors
+}
+
+/**
+ * Empties the owner keys that the request listed. Call it after a write that changes a user's owner
+ * keys outside {@link create}, such as a passkey's link or registration, so a later list in the same
+ * request reads them again.
+ */
+export function forget(c: Context) {
+  c.var.ownerLists?.clear()
+}
+
+/**
+ * Sets `c.var.ownerLists` to an empty {@link Lists} for the request, or to the lists of the page's
+ * request for an in-process call of its loader.
+ */
+export const middleware = createMiddleware<Env>(async (c, next) => {
+  c.set('ownerLists', c.env.ownerLists ?? new Map())
+  await next()
+})
+
+/**
+ * Returns the key of the user's lists in `realms` in {@link Lists}. Each kind reads the realms'
+ * configuration, such as a relying party, so the key holds each realm whole.
+ */
+function listKey(options: Pick<list.Options, 'realms' | 'userId'>) {
+  return JSON.stringify([
+    options.userId,
+    ...options.realms.map((realm) => [
+      realm.id,
+      realm.name,
+      realm.passkeys?.rpId ?? null,
+      realm.privy?.appId ?? null,
+      realm.secp256k1,
+    ]),
+  ])
+}
+
+/** Loads every kind in {@link kinds} for `realms`, in parallel, in the order of {@link kinds}. */
+async function load(c: Owner.Context, options: list.Options) {
+  return await Promise.all(
+    kinds.map((kind): Promise<Owner.Kind.Loaded<Type>> =>
+      kind.load(c, options),
+    ),
+  )
+}
+
+/**
+ * Returns the keys that `loaded` lists, oldest first, and creates none. The kinds are read in
+ * parallel, and an earlier kind wins a tie. On a deployment with configurable accounts, the user's
+ * stored configurations apply, as `ConfigurableAccount.apply` describes.
+ */
+async function owners(
+  c: Context,
+  options: owners.Options,
+): Promise<readonly Owner.Owner<Type>[]> {
+  const { db, key, userId } = options
+  const chain = ConfigurableAccount.on(options)
+  const [lists, configs] = await Promise.all([
+    (() => {
+      const read = () =>
+        Promise.all(options.loaded.map((entry) => entry.list(c, { db })))
+      const stored = c.var.ownerLists
+      if (!key || !stored) return read()
+      const listed = stored.get(key)
+      if (listed) return listed
+      // A failed read stores nothing, so the next list reads again.
+      const reading = read().catch((error: unknown) => {
+        if (stored.get(key) === reading) stored.delete(key)
+        throw error
+      })
+      stored.set(key, reading)
+      return reading
+    })(),
+    chain
+      ? Timing.measure(
+          c,
+          ConfigurableAccount.list(db, { chainId: chain.chainId, userId }),
+          'db.accountConfig.list',
+        )
+      : [],
+  ])
+  const merged = Owner.merge(lists)
+  if (!chain) return merged
+  return ConfigurableAccount.apply(merged, { chainId: chain.chainId, configs })
+}
+
+declare namespace owners {
+  type Options = {
+    /** The chain whose view of the accounts the owners carry, if any. */
+    chainId?: number | undefined
+    /** The database or transaction to read. */
+    db: Realm.Database
+    /** The deployment variables, which name the chains whose accounts are configurable. */
+    env: Owner.Env
+    /**
+     * The key of the lists in {@link Lists}, for a list of every kind. Absent, as under the user's
+     * lock, the lists read again and the request keeps none.
+     */
+    key?: string | undefined
+    /** The loaded kinds to list, in the order of {@link kinds}. */
+    loaded: readonly Owner.Kind.Loaded<Type>[]
+    /** The user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the owner of `account` that signs its keys: a cloud wallet when the account has one, since
+ * Tempo ID signs with it, or else its first owner. A configuration sorts its owners by address, so
+ * the first owner alone does not name it.
+ */
+export function signer(account: TempoAccount) {
+  return (
+    account.config.owners.find((entry) => entry.type !== 'webAuthn') ??
+    account.config.owners[0]
+  )
+}
+
+/**
+ * Returns the Tempo Account that `owner` owns, as the API returns it. A configurable account carries
+ * its configuration on the configurable-accounts chain, with each owner's kind.
+ */
+export function serialize(owner: Owner.Owner): TempoAccount {
+  const { configurable } = owner
+  if (configurable) {
+    const config = AccountConfig.toRpc(configurable.owner.account.config)
+    return schema.tempoAccount.parse({
+      address: configurable.owner.account.address,
+      config: {
+        ...config,
+        chainId: configurable.chainId,
+        owners: config.owners.map((entry) => ({
+          ...entry,
+          type:
+            configurable.owners.find(
+              (candidate) =>
+                candidate.address.toLowerCase() === entry.owner.toLowerCase(),
+            )?.type ?? owner.type,
+        })),
+      },
+      realm: { id: owner.realm.id, name: owner.realm.name },
+    })
+  }
+
+  const config = AccountConfig.toRpc(owner.account.config)
+  return schema.tempoAccount.parse({
+    // The key acts as the account on every chain where it is not configurable.
+    address: Owner.address(owner),
+    config: {
+      ...config,
+      owners: config.owners.map((entry) => ({ ...entry, type: owner.type })),
+    },
+    realm: { id: owner.realm.id, name: owner.realm.name },
+  })
+}

package/src/internal/TestInbox.ts

@@ -0,0 +1,51 @@
+/**
+ * Selects the sign-in codes that a deployment sends to its test inbox instead of emailing them. A
+ * preview sets `TEST_EMAIL_DOMAIN` and binds `TEST_INBOX`, so the end-to-end suite reads the codes of
+ * its test addresses, while every other address still receives email. Only domains that RFC 2606
+ * reserves qualify, so no deployment can divert a real address.
+ * @module
+ */
+
+/** The domains that a test inbox can receive, which RFC 2606 reserves, so no real address uses them. */
+export const domains = ['example.com', 'example.net', 'example.org'] as const
+
+/** A domain that a test inbox can receive. */
+export type Domain = (typeof domains)[number]
+
+/** A message to a test inbox, in the shape of Void's development inbox. */
+export type Message = {
+  /** The subject line. */
+  subject: string
+  /** The plain-text body. */
+  text: string
+  /** The recipients. */
+  to: readonly {
+    /** The recipient's address. */
+    email: string
+  }[]
+}
+
+/** The test inbox's `Capture` entrypoint, which a deployment binds as `TEST_INBOX`. */
+export type Service = {
+  /** Stores `message`. */
+  capture(message: Message): Promise<void>
+}
+
+/**
+ * Returns whether `email` belongs at the test inbox: `domain` is one of {@link domains}, and the
+ * address's domain is exactly `domain`. Returns `false` when `domain` is absent.
+ */
+export function matches(options: matches.Options) {
+  const { domain, email } = options
+  if (!domain || !domains.some((entry) => entry === domain)) return false
+  return email.toLowerCase().endsWith(`@${domain}`)
+}
+
+export declare namespace matches {
+  type Options = {
+    /** The deployment's `TEST_EMAIL_DOMAIN`, or `undefined` when it sets none. */
+    domain?: string | undefined
+    /** The recipient's address. */
+    email: string
+  }
+}