@tempoxyz/id 0.0.1 → 0.0.2

package/src/internal/TempoAccount.ts

@@ -9,12 +9,14 @@
  */
 import { and, eq, inArray, notExists, sql } from 'drizzle-orm'
 import { createMiddleware } from 'hono/factory'
+import { Address } from 'ox'
 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 type * as Log from './Log.js'
 import * as Owner from './Owner.js'
 import * as Passkey from './owners/Passkey.js'
 import * as Privy from './owners/Privy.js'
@@ -46,6 +48,22 @@ export declare namespace ForeignAccountError {
   }
 }
 
+/** A kind of owner key did not list within the deadline that {@link addresses} received. */
+export class TimeoutError extends Error {
+  override readonly name = 'TempoAccount.TimeoutError'
+
+  constructor(options: TimeoutError.Options) {
+    super(`The owner keys did not list within ${options.timeout} ms.`)
+  }
+}
+
+export declare namespace TimeoutError {
+  type Options = {
+    /** The deadline, in milliseconds. */
+    timeout: number
+  }
+}
+
 /**
  * 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
@@ -105,7 +123,7 @@ export namespace schema {
     })
     .meta({
       description:
-        'A realm, which holds Tempo Accounts. An app reaches only the accounts of its realms.',
+        'A realm, which holds Tempo Accounts. An app reaches only the accounts in its realms.',
       id: 'Realm',
     })
 
@@ -113,8 +131,7 @@ export namespace schema {
   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.",
+        description: "The account's address on the request's chain.",
         examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
       }),
       config: z
@@ -125,7 +142,7 @@ export namespace schema {
             .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.',
+                'The ID of the chain where the configuration applies. Absent if the account is not configurable on the chain.',
               examples: [31318],
             }),
           owners: z
@@ -138,7 +155,7 @@ export namespace schema {
                   }),
                   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.',
+                      "The owner key's holder: a Privy wallet (`privy`), a development key (`secp256k1`), or a passkey (`webAuthn`).",
                     examples: ['webAuthn'],
                   }),
                   weight: z.number().meta({
@@ -157,8 +174,7 @@ export namespace schema {
             examples: [`0x${'0'.repeat(64)}`],
           }),
           threshold: z.number().meta({
-            description:
-              'The total owner weight that a signature needs to act for the account.',
+            description: 'The total owner weight that a signature needs.',
             examples: [1],
           }),
           version: z.templateLiteral(['0x', z.string()]).meta({
@@ -390,6 +406,163 @@ export namespace list {
   export const errors = create.errors
 }
 
+/**
+ * Returns every address of the user's Tempo Accounts in `realms`, de-duplicated and in no meaningful
+ * order: each account's address on a chain whose accounts are not configurable, and its address on
+ * each chain that `CONFIGURABLE_ACCOUNTS` names. It creates no account. Each kind lists on its own,
+ * so a kind that reads an upstream service and fails, such as Privy during an outage, leaves out its
+ * addresses and returns its error in `errors` instead of throwing. A failure of the database throws.
+ */
+export async function addresses(
+  c: Context,
+  options: addresses.Options,
+): Promise<addresses.ReturnType> {
+  const {
+    db,
+    env,
+    maxAge,
+    timeout,
+    upstream = true,
+    userId,
+    waitUntil,
+    warn,
+  } = options
+
+  // A request that already listed the user's keys in these realms, such as a headless sign-in, reads
+  // them again from its lists. A failed list fails as a whole, so each kind lists again below, and a
+  // failure of the database throws there. A list that misses the deadline already spent the upstream
+  // kinds' time, so the upstream kinds list no more.
+  const listed = await (async () => {
+    const reading = c.var.ownerLists?.get(listKey(options))
+    if (!reading) return undefined
+    try {
+      const lists = await Timing.measure(
+        c,
+        within(reading, { timeout, waitUntil }),
+        'TempoAccount.owners',
+      )
+      return { lists }
+    } catch (error) {
+      if (error instanceof TimeoutError) return { error }
+      return undefined
+    }
+  })()
+  const errors: unknown[] = listed && 'error' in listed ? [listed.error] : []
+  const remoteAllowed = upstream && errors.length === 0
+  const lists =
+    (listed && 'lists' in listed ? listed.lists : undefined) ??
+    (await Promise.all(
+      kinds.map(async (kind): Promise<readonly Owner.Owner<Type>[]> => {
+        // Only a kind that reads an upstream service, such as Privy, declares refusals. The deadline
+        // applies to that kind alone, so a slow database leaves out no key that it holds.
+        const remote = kind.errors.length > 0
+        if (remote && !remoteAllowed) return []
+        // `load` reads only the database, such as a realm's Privy app, so its failure fails the call,
+        // as any other read of the database does.
+        const loaded = await Timing.measure(
+          c,
+          kind.load(c, options),
+          'TempoAccount.load',
+        )
+        try {
+          return await Timing.measure(
+            c,
+            within<readonly Owner.Owner<Type>[]>(
+              loaded.list(c, { db, maxAge, waitUntil, warn }),
+              { timeout: remote ? timeout : undefined, waitUntil },
+            ),
+            'TempoAccount.owners',
+          )
+        } catch (error) {
+          if (!remote) throw error
+          errors.push(error)
+          return []
+        }
+      }),
+    ))
+  const merged = Owner.merge(lists)
+
+  const chains = ConfigurableAccount.chains({
+    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrls: env.RPC_URLS,
+    value: env.CONFIGURABLE_ACCOUNTS,
+  })
+  const views = await Promise.all(
+    chains.map(async (chain) => {
+      const configs = await Timing.measure(
+        c,
+        ConfigurableAccount.list(db, { chainId: chain.chainId, userId }),
+        'db.accountConfig.list',
+      )
+      const applied = ConfigurableAccount.apply(merged, {
+        chainId: chain.chainId,
+        configs,
+      })
+      // `apply` lists a configuration through its key's owner, which a kind that failed leaves out.
+      // A configuration that names a listed key among its owners is the user's through that key.
+      const owned = configs.filter((config) =>
+        config.owners.some((member) =>
+          merged.some((entry) =>
+            Address.isEqual(Owner.key(entry), member.address),
+          ),
+        ),
+      )
+      return [
+        ...applied.map((owner) => Owner.address(owner)),
+        ...owned.map((config) => config.address),
+      ]
+    }),
+  )
+
+  const unique = new Map<string, Address.Address>()
+  for (const entry of [
+    ...merged.map((owner) => Owner.address(owner)),
+    ...views.flat(),
+  ]) {
+    const address = Address.checksum(entry)
+    unique.set(address.toLowerCase(), address)
+  }
+  return { addresses: [...unique.values()], errors }
+}
+
+export declare namespace addresses {
+  type Options = Omit<list.Options, 'chainId'> & {
+    /**
+     * How old, in seconds, a cached read of an upstream service, such as Privy's wallets, may be.
+     * Absent, each kind reads its upstream service.
+     */
+    maxAge?: number | undefined
+    /**
+     * How long each kind that reads an upstream service, such as Privy, may list, in milliseconds.
+     * Such a kind that takes longer leaves out its addresses, and returns a {@link TimeoutError} in
+     * `errors`. The kinds that read only the database have no deadline. Absent, no deadline applies.
+     */
+    timeout?: number | undefined
+    /**
+     * Whether the kinds that read an upstream service, such as Privy, list. Defaults to `true`.
+     * `false` leaves out their addresses without an error.
+     */
+    upstream?: boolean | undefined
+    /**
+     * Keeps a read that missed `timeout` alive after the response, such as
+     * `c.executionCtx.waitUntil`, so it still fills its cache. Absent, the runtime may end it.
+     */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+    /**
+     * Logs a recoverable problem with the request's details, such as a failure of the cache of
+     * Privy's wallets. Absent, the kinds log without them.
+     */
+    warn?: ((options: Log.Options) => void) | undefined
+  }
+
+  type ReturnType = {
+    /** The addresses, checksummed, each once. */
+    addresses: readonly Address.Address[]
+    /** The failures of the kinds whose addresses are left out. Empty when every kind listed. */
+    errors: readonly unknown[]
+  }
+}
+
 /**
  * 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
@@ -543,3 +716,44 @@ export function serialize(owner: Owner.Owner): TempoAccount {
     realm: { id: owner.realm.id, name: owner.realm.name },
   })
 }
+
+/**
+ * Returns the value of `promise`, or rejects with a {@link TimeoutError} once `timeout` milliseconds
+ * pass. Without `timeout`, it waits for `promise`.
+ */
+async function within<value>(
+  promise: Promise<value>,
+  options: within.Options,
+): Promise<value> {
+  const { timeout, waitUntil } = options
+  if (timeout === undefined) return await promise
+
+  // A read that rejects after the deadline has no caller left, so its rejection is dropped.
+  const settled = promise.then(
+    () => undefined,
+    () => undefined,
+  )
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      // The read continues past the response, so a late answer still fills its cache, such as the
+      // Privy wallets that the next grant reads.
+      waitUntil?.(settled)
+      reject(new TimeoutError({ timeout }))
+    }, timeout)
+  })
+  try {
+    return await Promise.race([promise, expired])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+declare namespace within {
+  type Options = {
+    /** The deadline, in milliseconds. Absent, none applies. */
+    timeout?: number | undefined
+    /** Keeps the read alive after the response when the deadline passes. Absent, the runtime may end it. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+  }
+}

package/src/internal/owners/Privy.ts

@@ -61,16 +61,29 @@ export const owner = Owner.kind({
           return toOwner(app, realm, wallet)
         }
       },
-      async list(c) {
+      async list(c, listOptions) {
+        const { maxAge, waitUntil, warn } = listOptions
         const lists = await Promise.all(
           realms.map(async (realm) => {
             const app = apps.get(realm.id)
             if (!app) return []
-            const wallets = await Timing.measure(
-              c,
-              Privy.listWallets(c, { app, userId }),
-              'Privy.listWallets',
-            )
+            const wallets = await (maxAge === undefined
+              ? Timing.measure(
+                  c,
+                  Privy.listWallets(c, { app, userId }),
+                  'Privy.listWallets',
+                )
+              : Timing.measure(
+                  c,
+                  Privy.cachedWallets(c, {
+                    app,
+                    maxAge,
+                    userId,
+                    waitUntil,
+                    warn,
+                  }),
+                  'Privy.cachedWallets',
+                ))
             return wallets.map((wallet) => toOwner(app, realm, wallet))
           }),
         )