@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/Configure.ts

@@ -0,0 +1,921 @@
+/**
+ * Changes the owners of the signed-in user's Tempo Account on a chain whose accounts are
+ * configurable, for the account page's routes. {@link find} reads the account in the app's realms.
+ * {@link send} installs a change that an owner signs on the server. A passkey owner signs in the
+ * browser instead: {@link request} returns the passkey step, and {@link confirm} sends the change
+ * with the passkey's assertion. Each change stores the configuration that the chain installed.
+ * @module
+ */
+import { and, eq, inArray, isNotNull } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { Address, type Hex } from 'ox'
+import { env } from 'void/env'
+import { Authentication } from 'webauthx/server'
+import * as Schema from '../../app/db/schema.js'
+import * as Chain from '../../internal/Chain.js'
+import * as ConfigurableAccount from '../../internal/ConfigurableAccount.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as Log from '../../internal/Log.js'
+import * as Owner from '../../internal/Owner.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as Realm from '../../internal/Realm.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Wallet from '../../internal/Wallet.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Validation from '../../internal/Validation.js'
+import { db } from './Database.js'
+
+/**
+ * Spends the passkey step that {@link request} issued with `assertion`, sends its change, and stores
+ * the installed configuration. Returns `webauthn_rejected` for an assertion of another passkey, or
+ * over a spent, expired, or forged challenge. `link`, when present, runs after the assertion verifies
+ * and before the change is sent, and can refuse it. A step with a key's registration sends it first,
+ * with `keySignature`, and sends the change only once the chain registered the key.
+ */
+export async function confirm(
+  c: Context<Env>,
+  options: confirm.Options,
+): Promise<
+  ConfigurableAccount.Config | ErrorResponse.Instance<typeof confirm.errors>
+> {
+  const { account, assertion, client, credential, userId } = options
+  const challenge = await Timing.measure(
+    c,
+    Passkey.takeSignature(db, {
+      account,
+      authenticatorData: assertion.metadata.authenticatorData,
+      clientId: ConfigurableAccount.clientId,
+      clientDataJSON: assertion.metadata.clientDataJSON,
+      credentialId: assertion.id,
+      expiry: Math.floor(Date.now() / 1000) + ConfigurableAccount.lifetime,
+      signature: assertion.signature,
+      userId,
+      verify: (challenge) =>
+        challenge.account === account.toLowerCase() &&
+        challenge.clientId === ConfigurableAccount.clientId &&
+        challenge.credential.id === credential.id &&
+        challenge.credential.publicKey === credential.publicKey &&
+        assertion.id === credential.id &&
+        Passkey.verify(assertion, {
+          challenge: challenge.digest,
+          origin: options.origin ?? new URL(env.URL).origin,
+          publicKey: credential.publicKey,
+          rpId: credential.rpId,
+        }),
+    }),
+    'Passkey.takeSignature',
+  )
+  const pending = challenge
+    ? await Timing.measure(
+        c,
+        ConfigurableAccount.takePending(db, {
+          digest: challenge.digest,
+          userId,
+        }),
+        'ConfigurableAccount.takePending',
+      )
+    : undefined
+  if (!challenge || !pending) return new Passkey.WebAuthnRejectedError()
+  const { registration } = pending
+  if (registration && !options.keySignature) return keySignatureRequired()
+
+  const refused = options.link
+    ? await Timing.measure(c, options.link(), 'Configure.link')
+    : undefined
+  if (refused) return refused
+
+  // The upgrade retires the signature of the account's own key, so the key that it signed reaches
+  // the chain first, and a failed registration sends no upgrade.
+  if (registration)
+    await submit(c, () =>
+      ConfigurableAccount.sendRegistration({
+        account,
+        client,
+        digest: registration.digest,
+        signature: options.keySignature!,
+        transaction: registration.transaction,
+      }),
+    )
+
+  const installed = await submit(c, () =>
+    ConfigurableAccount.sendSigned({
+      assertion,
+      client,
+      current: pending.current,
+      digest: challenge.digest,
+      publicKey: credential.publicKey,
+      target: pending.target,
+      transaction: pending.transaction,
+    }),
+  )
+  await Timing.measure(
+    c,
+    ConfigurableAccount.save(db, { config: installed, userId }),
+    'db.accountConfig.save',
+  )
+  return installed
+}
+
+export namespace confirm {
+  export type Options = {
+    /** The address of the account that the change installs. */
+    account: Hex.Hex
+    /** The passkey's assertion over the step's challenge. */
+    assertion: Passkey.Assertion
+    /** A client of the chain. */
+    client: ConfigurableAccount.Client
+    /** The passkey that signs the change. */
+    credential: Owner.Credential
+    /** The access key's raw signature over the digest of the step's registration, if it has one. */
+    keySignature?: Hex.Hex | undefined
+    /**
+     * Runs once the assertion verifies, before the change is sent, such as to link the passkey to
+     * the user. Returns a refusal to stop the change, or `undefined` to send it.
+     */
+    link?:
+      | (() => Promise<TempoAccount.ForeignAccountError | undefined>)
+      | undefined
+    /** The origin of the page that ran the ceremony. Defaults to Tempo ID's own. */
+    origin?: string | undefined
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  /** The refusals `confirm` returns or throws. */
+  export const errors = [
+    ...ErrorResponse.fromUpstream.errors,
+    ConfigurableAccount.ConflictError,
+    Passkey.WebAuthnRejectedError,
+    TempoAccount.ForeignAccountError,
+    Validation.InvalidFieldError,
+  ] as const
+}
+
+/**
+ * Returns the chain that `chain` names, its client, and the user's account at `account` on it, in
+ * the realms of the app that `clientId` names, with the account's configuration. Without `chain`, the
+ * first chain that `CONFIGURABLE_ACCOUNTS` names. Without `clientId`, the `default` realm.
+ */
+export async function find(
+  c: Context<Env>,
+  options: find.Options,
+): Promise<find.ReturnType | ErrorResponse.Instance<typeof find.errors>> {
+  const { account, clientId, userId } = options
+  const chain = resolve({ chain: options.chain })
+  if (chain instanceof ErrorResponse.ResponseError) return chain
+
+  const realms = await Timing.measure(
+    c,
+    reach(c, { clientId }),
+    'Configure.reach',
+  )
+  const owners = await Timing.measure(
+    c,
+    TempoAccount.held(c, {
+      chainId: chain.chainId,
+      db,
+      env,
+      realms,
+      userId,
+    }),
+    'TempoAccount.held',
+  )
+  const owner = owners.find(
+    (entry) => Owner.address(entry).toLowerCase() === account.toLowerCase(),
+  )
+  if (!owner) return new TempoAccount.ForeignAccountError({ account })
+
+  return {
+    chain,
+    client: ConfigurableAccount.client({
+      apiUrl: Chain.apiUrl({
+        apiUrls: env.TEMPO_API_URLS,
+        chainId: chain.chainId,
+      }),
+      chain,
+    }),
+    current: ConfigurableAccount.of(owner),
+    owner,
+    owners,
+    realms,
+  }
+}
+
+export namespace find {
+  export type Options = {
+    /** The account's address on the chain. */
+    account: `0x${string}`
+    /** The chain that the request names. Absent, the first chain whose accounts are configurable. */
+    chain?: string | undefined
+    /** The app whose realms hold the account. Absent, the `default` realm. */
+    clientId?: string | undefined
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  export type ReturnType = {
+    /** The chain, which `CONFIGURABLE_ACCOUNTS` names. */
+    chain: ConfigurableAccount.Entry
+    /** A client of the chain, which sends configuration changes. */
+    client: ConfigurableAccount.Client
+    /** The account's configuration. Absent for a linked key that no upgrade made configurable. */
+    current: ConfigurableAccount.Config | undefined
+    /** The key that owns the account, with its configurable view, if any. */
+    owner: Owner.Owner
+    /** Every account of the user in the realms, as `TempoAccount.held` returns them on the chain. */
+    owners: readonly Owner.Owner[]
+    /** The realms that the request reaches, in order. */
+    realms: readonly Realm.Realm[]
+  }
+
+  /** The refusals `find` returns or throws. */
+  export const errors = [
+    ...TempoAccount.held.errors,
+    ConfigurableAccount.DisabledError,
+    TempoAccount.ForeignAccountError,
+  ] as const
+}
+
+/** Returns the realms of the app that `clientId` names, as Tempo ID's own page reaches them. */
+export async function reach(c: Context<Env>, options: reach.Options) {
+  const stored = await Timing.measure(
+    c,
+    Realm.forRequest(c, {
+      clientId: options.clientId,
+      db,
+      origin: c.req.header('origin'),
+      own: new URL(env.URL).origin,
+    }),
+    'Realm.forRequest',
+  )
+  return await Timing.measure(
+    c,
+    Realm.withDefaults(c, { db, origin: env.URL, realms: stored }),
+    'Realm.withDefaults',
+  )
+}
+
+export declare namespace reach {
+  type Options = {
+    /** The app whose realms the request reaches. Absent, the `default` realm. */
+    clientId?: string | undefined
+  }
+}
+
+/**
+ * Prepares the change that installs `target` for `credential`, a passkey, to sign in the browser.
+ * Stores the passkey's signature challenge and the change for 5 minutes, and returns the options for
+ * `navigator.credentials.get()`, whose challenge is the transaction's digest.
+ */
+export async function request(c: Context<Env>, options: request.Options) {
+  const { account, client, credential, current, registration, target, userId } =
+    options
+  const prepared = await submit(c, () =>
+    ConfigurableAccount.request({
+      client,
+      current,
+      publicKey: credential.publicKey,
+      target,
+    }),
+  )
+  await Timing.measure(
+    c,
+    Passkey.requestSignature(db, {
+      account,
+      clientId: ConfigurableAccount.clientId,
+      credential,
+      digest: prepared.digest,
+      userId,
+    }),
+    'Passkey.requestSignature',
+  )
+  await Timing.measure(
+    c,
+    ConfigurableAccount.storePending(db, {
+      current,
+      digest: prepared.digest,
+      registration,
+      target,
+      transaction: prepared.transaction,
+      userId,
+    }),
+    'ConfigurableAccount.storePending',
+  )
+  return Authentication.getOptions({
+    challenge: prepared.digest,
+    credentialId: [credential.id],
+    rpId: credential.rpId,
+    userVerification: 'required',
+  }).options
+}
+
+export namespace request {
+  export type Options = {
+    /** The address of the account that the change installs. */
+    account: Hex.Hex
+    /** A client of the chain. */
+    client: ConfigurableAccount.Client
+    /** The passkey that signs the change. */
+    credential: Owner.Credential
+    /** The account's configuration. Absent for an upgrade. */
+    current: ConfigurableAccount.Config | undefined
+    /** A key's registration, which the chain receives before the change. Absent without one. */
+    registration?:
+      | ConfigurableAccount.requestRegistration.ReturnType
+      | undefined
+    /** The configuration to install. */
+    target: ConfigurableAccount.Config
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the chain that `chain` names when `CONFIGURABLE_ACCOUNTS` names it, or the first such chain
+ * without `chain`. Returns `configurable_accounts_disabled` otherwise.
+ */
+export function resolve(
+  options: resolve.Options,
+): ConfigurableAccount.Entry | ConfigurableAccount.DisabledError {
+  const configurable = ConfigurableAccount.chains({
+    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrls: env.RPC_URLS,
+    value: env.CONFIGURABLE_ACCOUNTS,
+  })
+  const chain =
+    options.chain === undefined
+      ? configurable[0]
+      : configurable.find((entry) => entry.name === options.chain)
+  if (chain) return chain
+  return new ConfigurableAccount.DisabledError({
+    chain: options.chain,
+    configured: configurable.map((entry) => entry.name),
+  })
+}
+
+export declare namespace resolve {
+  type Options = {
+    /** The chain that the request names, if any. */
+    chain?: string | undefined
+  }
+}
+
+/**
+ * Returns whether a user with `email` waits for a wallet.tempo passkey's upgrade to become their
+ * account in `realms`: the deployment flags a chain, `realms` include the `default` realm, where the
+ * passkey links, Tempo ID stores no passkey of the user, and wallet.tempo holds a passkey of the
+ * email that has not linked. Such a user receives no cloud wallet on any chain, since the passkey
+ * becomes their account. A failed lookup waits, since a cloud wallet created beside the passkey
+ * would stay, and the next request looks again.
+ */
+export async function awaitsUpgrade(
+  c: Context<Env>,
+  options: awaitsUpgrade.Options,
+) {
+  const { email, realms, userId } = options
+  const wallet = c.env.WALLET
+  if (!wallet || !looksUpUpgrade(c, { realms })) return false
+
+  // A passkey that Tempo ID stores for the user is authoritative, so the request reads no passkey
+  // of the email from wallet.tempo, whose lookup is slower than the database.
+  const [stored] = await Timing.measure(
+    c,
+    db
+      .select({ id: Schema.keys.id })
+      .from(Schema.keys)
+      .where(eq(Schema.keys.userId, userId))
+      .limit(1),
+    'db.keys.stored',
+  )
+  if (stored) return false
+
+  const listed = await Timing.measure(
+    c,
+    Wallet.credentials(wallet, { email }),
+    'Wallet.credentials',
+  ).catch((error: unknown) => {
+    Log.warn(c, {
+      error,
+      message:
+        'The wallet service failed a passkey lookup by email, so no cloud wallet was created.',
+    })
+    return undefined
+  })
+  if (!listed) return true
+  return (await withoutLinked(c, { listed })).length > 0
+}
+
+export declare namespace awaitsUpgrade {
+  type Options = {
+    /** The signed-in user's verified email. */
+    email: string
+    /** The realms where the request would create the user's account. */
+    realms: readonly Pick<Realm.Realm, 'id'>[]
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns whether {@link awaitsUpgrade} looks up the user's email for `realms`: the deployment flags
+ * a chain, binds the wallet service, and `realms` include the `default` realm. Otherwise it returns
+ * `false` without the email, so a caller that holds none reads it only when this returns `true`.
+ */
+export function looksUpUpgrade(
+  c: Context<Env>,
+  options: looksUpUpgrade.Options,
+) {
+  if (!options.realms.some((realm) => realm.id === Realm.defaultId))
+    return false
+  if (!c.env.WALLET) return false
+  return (
+    ConfigurableAccount.chains({
+      rpcUrl: env.TEMPO_RPC_URL,
+      rpcUrls: env.RPC_URLS,
+      value: env.CONFIGURABLE_ACCOUNTS,
+    }).length > 0
+  )
+}
+
+export declare namespace looksUpUpgrade {
+  type Options = {
+    /** The realms where the request would create the user's account. */
+    realms: readonly Pick<Realm.Realm, 'id'>[]
+  }
+}
+
+/**
+ * Returns the wallet.tempo passkeys of `email`, the signed-in user's, that link to no user on Tempo
+ * ID yet. Returns none without the wallet service, or when it fails, which it logs, so a page that
+ * offers them still loads.
+ */
+export async function unlinked(
+  c: Context<Env>,
+  options: unlinked.Options,
+): Promise<readonly Wallet.Listed[]> {
+  if (!c.env.WALLET) return []
+  const listed = await Timing.measure(
+    c,
+    Wallet.credentials(c.env.WALLET, { email: options.email }),
+    'Wallet.credentials',
+  ).catch((error: unknown) => {
+    // A wallet service without the method, or one that fails, lists none.
+    Log.warn(c, {
+      error,
+      message: 'The wallet service failed a passkey lookup by email.',
+    })
+    return []
+  })
+  return await withoutLinked(c, { listed })
+}
+
+export declare namespace unlinked {
+  type Options = {
+    /** The signed-in user's verified email. */
+    email: string
+  }
+}
+
+/**
+ * Returns the upgrades that wait for the user with `userId` on the chain that `chain` names, or
+ * none when `CONFIGURABLE_ACCOUNTS` does not name it. First comes each linked wallet.tempo passkey's
+ * account without a stored configuration on the chain. Then, for a user who holds no account yet,
+ * each wallet.tempo passkey of `email` that has not linked, which its upgrade links. It reads stored
+ * rows, and wallet.tempo only for a user without an account, never a chain.
+ */
+export async function upgrades(
+  c: Context<Env>,
+  options: upgrades.Options,
+): Promise<readonly upgrades.Entry[]> {
+  const { email, userId } = options
+  const chain = ConfigurableAccount.chains({
+    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrls: env.RPC_URLS,
+    value: env.CONFIGURABLE_ACCOUNTS,
+  }).find((entry) => entry.name === options.chain)
+  if (!chain) return []
+
+  // Each kind of owner that Tempo ID stores marks an account that the user already holds: a passkey
+  // that owns one, a development key, or the claim of a first account, which a cloud wallet holds.
+  const [passkeys, configs, secp256k1, claims] = await Promise.all([
+    Timing.measure(
+      c,
+      db
+        .select({ address: Schema.keys.address, source: Schema.keys.source })
+        .from(Schema.keys)
+        .where(
+          and(eq(Schema.keys.userId, userId), isNotNull(Schema.keys.address)),
+        ),
+      'db.keys.list',
+    ),
+    Timing.measure(
+      c,
+      db
+        .select({
+          address: Schema.accountConfigs.address,
+          chainId: Schema.accountConfigs.chainId,
+        })
+        .from(Schema.accountConfigs)
+        .where(eq(Schema.accountConfigs.userId, userId)),
+      'db.accountConfigs.list',
+    ),
+    Timing.measure(
+      c,
+      db
+        .select({ address: Schema.secp256k1Owners.address })
+        .from(Schema.secp256k1Owners)
+        .where(eq(Schema.secp256k1Owners.userId, userId))
+        .limit(1),
+      'db.secp256k1Owners.list',
+    ),
+    Timing.measure(
+      c,
+      db
+        .select({ realmId: Schema.firstAccounts.realmId })
+        .from(Schema.firstAccounts)
+        .where(eq(Schema.firstAccounts.userId, userId))
+        .limit(1),
+      'db.firstAccounts.list',
+    ),
+  ])
+
+  // `wallet` is the earlier name of the `tempo-wallet` source, as `owners/Passkey.ts` reads it.
+  const roots = passkeys.flatMap((entry) =>
+    entry.address && ['tempo-wallet', 'wallet'].includes(entry.source)
+      ? [entry.address]
+      : [],
+  )
+  const linked = roots
+    .filter(
+      (address) =>
+        !configs.some(
+          (config) =>
+            config.chainId === chain.chainId && config.address === address,
+        ),
+    )
+    .map((address) => ({
+      account: Address.checksum(address as Address.Address),
+      chain: chain.name,
+    }))
+  if (passkeys.length > 0 || secp256k1.length > 0 || claims.length > 0)
+    return linked
+
+  const listed = await Timing.measure(
+    c,
+    unlinked(c, { email }),
+    'Configure.unlinked',
+  )
+  return listed.map((entry) => ({
+    chain: chain.name,
+    credentialId: entry.credentialId,
+  }))
+}
+
+export declare namespace upgrades {
+  /** An upgrade that waits: a linked passkey's account, or a passkey of the email that has not linked. */
+  type Entry =
+    | {
+        /** The linked wallet.tempo passkey's account, which upgrades in place. */
+        account: `0x${string}`
+        /** The name of the chain where it upgrades. */
+        chain: string
+      }
+    | {
+        /** The name of the chain where it upgrades. */
+        chain: string
+        /** The credential ID of the wallet.tempo passkey, which the upgrade links. */
+        credentialId: string
+      }
+
+  type Options = {
+    /** The name of the chain to list upgrades on. */
+    chain: string
+    /** The signed-in user's verified email. */
+    email: string
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the root passkey account that an upgrade covers on the chain that `chain` names: the user's
+ * account at `account`, which a linked wallet.tempo passkey owns, or the account of the wallet.tempo
+ * passkey `credentialId`, which links to the user with the upgrade. wallet.tempo's email of that
+ * passkey must be `email`, the user's, which the sign-in proved. Returns `owner_exists` for an
+ * account that is configurable already, and `not_configurable` for one that no passkey owns.
+ */
+export async function root(
+  c: Context<Env>,
+  options: root.Options,
+): Promise<root.ReturnType | ErrorResponse.Instance<typeof root.errors>> {
+  const { clientId, credentialId, email, userId } = options
+  if (options.account) {
+    const found = await Timing.measure(
+      c,
+      find(c, {
+        account: options.account,
+        chain: options.chain,
+        clientId,
+        userId,
+      }),
+      'Configure.find',
+    )
+    if (found instanceof ErrorResponse.ResponseError) return found
+    const { owner } = found
+    const address = Owner.address(owner)
+    if (found.current)
+      return new ConfigurableAccount.OwnerExistsError({
+        account: address,
+        owner: 'configurable',
+      })
+    if (!owner.credential)
+      return new ConfigurableAccount.NotConfigurableError({
+        account: address,
+        reason: 'cloud',
+      })
+    return {
+      account: address,
+      chain: found.chain,
+      client: found.client,
+      credential: owner.credential,
+      link: undefined,
+      owners: found.owners,
+      realm: owner.realm,
+    }
+  }
+
+  const chain = resolve({ chain: options.chain })
+  if (chain instanceof ErrorResponse.ResponseError) return chain
+  const realms = await Timing.measure(
+    c,
+    reach(c, { clientId }),
+    'Configure.reach',
+  )
+  // wallet.tempo's passkeys belong to the `default` realm's relying party.
+  const realm = realms.find((entry) => entry.id === Realm.defaultId)
+  const relyingParty = realm
+    ? Passkey.relyingParty([realm], { origin: env.URL })
+    : undefined
+  if (!realm || !relyingParty)
+    return new Passkey.NotPermittedError({ clientId })
+
+  const id = credentialId!
+  const refused = new TempoAccount.ForeignAccountError({
+    account: id,
+    field: 'credentialId',
+  })
+  const wallet = c.env.WALLET
+    ? await Timing.measure(
+        c,
+        Wallet.credential(c.env.WALLET, { id }),
+        'Wallet.credential',
+      ).catch((error: unknown) => {
+        // Only the binding call throws, so the failure is wallet.tempo's.
+        Log.warn(c, {
+          error,
+          message: 'The wallet service failed a passkey lookup.',
+        })
+        throw (
+          (error instanceof Error && ErrorResponse.fromUpstream(error)) ||
+          new ErrorResponse.UpstreamUnavailableError()
+        )
+      })
+    : undefined
+  if (!wallet || wallet.email?.toLowerCase() !== email.toLowerCase())
+    return refused
+
+  const owners = await Timing.measure(
+    c,
+    TempoAccount.held(c, {
+      chainId: chain.chainId,
+      db,
+      env,
+      realms,
+      userId,
+    }),
+    'TempoAccount.held',
+  )
+  const account = Address.checksum(wallet.address as Address.Address)
+  if (
+    owners.some(
+      (entry) =>
+        entry.configurable && Address.isEqual(Owner.key(entry), account),
+    )
+  )
+    return new ConfigurableAccount.OwnerExistsError({
+      account,
+      owner: 'configurable',
+    })
+
+  return {
+    account,
+    chain,
+    client: ConfigurableAccount.client({
+      apiUrl: Chain.apiUrl({
+        apiUrls: env.TEMPO_API_URLS,
+        chainId: chain.chainId,
+      }),
+      chain,
+    }),
+    credential: { id, publicKey: wallet.publicKey, rpId: relyingParty.rpId },
+    // The link runs once the passkey signed the upgrade, which proves the user holds it. A passkey
+    // that links to another user, in a race, refuses the upgrade.
+    link: async () => {
+      const linked = await Timing.measure(
+        c,
+        Passkey.link(db, {
+          credential: wallet,
+          id,
+          rpId: relyingParty.rpId,
+          userId,
+        }),
+        'Passkey.link',
+      )
+      TempoAccount.forget(c)
+      return linked === userId ? undefined : refused
+    },
+    owners,
+    realm,
+  }
+}
+
+export namespace root {
+  export type Options = {
+    /** The user's account that a linked passkey owns. Absent with `credentialId`. */
+    account?: `0x${string}` | undefined
+    /** The chain that the request names. Absent, the first chain whose accounts are configurable. */
+    chain?: string | undefined
+    /** The app whose realms hold the account. Absent, the `default` realm. */
+    clientId?: string | undefined
+    /** A wallet.tempo passkey that has not linked to the user yet. Absent with `account`. */
+    credentialId?: string | undefined
+    /** The signed-in user's verified email. */
+    email: string
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  export type ReturnType = {
+    /** The account's address, the passkey's own. */
+    account: Hex.Hex
+    /** The chain, which `CONFIGURABLE_ACCOUNTS` names. */
+    chain: ConfigurableAccount.Entry
+    /** A client of the chain. */
+    client: ConfigurableAccount.Client
+    /** The passkey, which signs the upgrade as the account's root key. */
+    credential: Owner.Credential
+    /** Links the passkey to the user, for a passkey that has not linked yet. */
+    link: confirm.Options['link']
+    /** The user's accounts on the chain. */
+    owners: readonly Owner.Owner[]
+    /** The realm of the account, where a cloud wallet that joins it comes from. */
+    realm: Realm.Realm
+  }
+
+  /** The refusals `root` returns or throws. */
+  export const errors = [
+    ...ErrorResponse.fromUpstream.errors,
+    ...find.errors,
+    ConfigurableAccount.NotConfigurableError,
+    ConfigurableAccount.OwnerExistsError,
+    Passkey.NotPermittedError,
+  ] as const
+}
+
+/**
+ * Sends the change that installs `target` with `signing`'s server signer, and stores the installed
+ * configuration. A failure of the chain or the Tempo API responds with `upstream_unavailable`.
+ */
+export async function send(
+  c: Context<Env>,
+  options: send.Options,
+): Promise<ConfigurableAccount.Config> {
+  const { client, current, signing, target, userId } = options
+  const account = await Timing.measure(
+    c,
+    signing.signer!(c, { auth: c.var.auth }),
+    'Owner.signer',
+  )
+  const installed = await submit(c, () =>
+    ConfigurableAccount.send({ account, client, current, target }),
+  )
+  await Timing.measure(
+    c,
+    ConfigurableAccount.save(db, { config: installed, userId }),
+    'db.accountConfig.save',
+  )
+  return installed
+}
+
+export namespace send {
+  export type Options = {
+    /** A client of the chain. */
+    client: ConfigurableAccount.Client
+    /** The account's configuration, if any. */
+    current: ConfigurableAccount.Config | undefined
+    /** The owner that signs, from {@link signer}, with a server signer. */
+    signing: Owner.Owner
+    /** The configuration to install. */
+    target: ConfigurableAccount.Config
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  /** The refusals `send` throws: those of {@link submit}. */
+  export const errors = [
+    ...ErrorResponse.fromUpstream.errors,
+    ConfigurableAccount.ConflictError,
+  ] as const
+}
+
+/**
+ * Returns the owner that signs a change of `owner`'s configuration: the key that acts as the
+ * account, which signs its upgrade, or the configurable view, whose owners sign an update.
+ */
+export function signer(owner: Owner.Owner, options: signer.Options) {
+  return options.current ? owner.configurable!.owner : owner
+}
+
+export declare namespace signer {
+  type Options = {
+    /** The account's configuration, if any. */
+    current: ConfigurableAccount.Config | undefined
+  }
+}
+
+/**
+ * Runs `fn`, a change on the chain, and maps a failure that is not a refusal to
+ * `upstream_unavailable`, after it logs it. A configuration conflict stays a refusal.
+ */
+export async function submit<result>(
+  c: Context<Env>,
+  fn: () => Promise<result>,
+): Promise<result> {
+  try {
+    return await Timing.measure(c, fn(), 'ConfigurableAccount.send')
+  } catch (error) {
+    if (error instanceof ErrorResponse.ResponseError) throw error
+    if (error instanceof Error) {
+      const upstream = ErrorResponse.fromUpstream(error)
+      if (upstream) throw upstream
+    }
+    // A node's refusal or a reverted transaction is the chain's failure, so it maps the same way.
+    Log.warn(c, {
+      error,
+      message: 'The chain did not install the account configuration.',
+    })
+    throw new ErrorResponse.UpstreamUnavailableError()
+  }
+}
+
+export namespace submit {
+  /** The refusals `submit` throws. */
+  export const errors = [
+    ...ErrorResponse.fromUpstream.errors,
+    ConfigurableAccount.ConflictError,
+  ] as const
+}
+
+/** Returns the refusal of a step with a key's registration whose repeated request has no signature. */
+function keySignatureRequired() {
+  return new Validation.InvalidFieldError({
+    issues: [
+      {
+        message:
+          "The step registers the key before the upgrade, so the request needs the access key's signature over `step.key.digest`. Request a new step, and send both signatures",
+        path: ['key', 'signature'],
+      },
+    ],
+  })
+}
+
+/** Returns the passkeys of `listed` that link to no user on Tempo ID. */
+async function withoutLinked(c: Context<Env>, options: withoutLinked.Options) {
+  const { listed } = options
+  if (listed.length === 0) return []
+
+  const linked = await Timing.measure(
+    c,
+    db
+      .select({ id: Schema.keys.id })
+      .from(Schema.keys)
+      .where(
+        inArray(
+          Schema.keys.id,
+          listed.map((entry) => entry.credentialId),
+        ),
+      ),
+    'db.keys.linked',
+  )
+  return listed.filter(
+    (entry) => !linked.some((row) => row.id === entry.credentialId),
+  )
+}
+
+declare namespace withoutLinked {
+  type Options = {
+    /** The wallet.tempo passkeys of the user's email. */
+    listed: readonly Wallet.Listed[]
+  }
+}