@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/PendingKey.ts

@@ -0,0 +1,104 @@
+/**
+ * Key authorizations that the approval page signed, held until the app redeems the code that the
+ * same approval returned. A signed authorization lets whoever holds its key spend, so no redirect
+ * carries it. Each row is keyed by the app's client ID and the request's PKCE challenge, and only
+ * the redemption that proves the challenge's verifier takes it.
+ * @module
+ */
+import { and, eq, gt } from 'drizzle-orm'
+import * as Schema from '../app/db/schema.js'
+import type * as KeyAuthorization from './KeyAuthorization.js'
+import type * as Realm from './Realm.js'
+
+/** Seconds that a signed key authorization waits for its code's redemption, as long as the code lasts. */
+export const lifetime = 10 * 60
+
+/** A signed key authorization, and the Tempo Account that it acts for. */
+export type PendingKey = {
+  /** The Tempo Account that the key acts for. */
+  account: `0x${string}`
+  /** The signed key authorization, in the node's RPC format. */
+  keyAuthorization: Awaited<ReturnType<typeof KeyAuthorization.sign>>
+}
+
+/**
+ * Holds `key` for the app with `clientId` and the PKCE challenge `codeChallenge`, for
+ * {@link lifetime} seconds, or until the key expires if sooner. A later approval of the same request
+ * by the same user replaces the key that an earlier approval left, so the key matches the approval
+ * that the user made last. Another user's approval replaces nothing.
+ */
+export async function put(db: Realm.Database, options: put.Options) {
+  const { clientId, codeChallenge, expiry, key, userId } = options
+  const values = {
+    account: key.account,
+    expiresAt: new Date(Math.min(Date.now() + lifetime * 1000, expiry * 1000)),
+    keyAuthorization: key.keyAuthorization,
+    userId,
+  }
+  await db
+    .insert(Schema.pendingKeys)
+    .values({ ...values, clientId, codeChallenge })
+    .onConflictDoUpdate({
+      set: { ...values, createdAt: new Date() },
+      setWhere: eq(Schema.pendingKeys.userId, userId),
+      target: [Schema.pendingKeys.clientId, Schema.pendingKeys.codeChallenge],
+    })
+}
+
+export declare namespace put {
+  type Options = {
+    /** The client ID of the app that requested the key. */
+    clientId: string
+    /** The S256 PKCE challenge of the authorization request. */
+    codeChallenge: string
+    /** When the signed key expires, in Unix seconds, which bounds how long the row waits. */
+    expiry: number
+    /** The signed key authorization, and the account that it acts for. */
+    key: PendingKey
+    /** The ID of the user who approved the key. */
+    userId: string
+  }
+}
+
+/**
+ * Deletes the key held for the app with `clientId`, the PKCE challenge `codeChallenge`, and the
+ * user `userId`, and returns it. Returns `undefined` when none is held, when it expired, or when an
+ * earlier redemption took it, so a second code for the same challenge carries no key.
+ */
+export async function take(
+  db: Realm.Database,
+  options: take.Options,
+): Promise<PendingKey | undefined> {
+  const { clientId, codeChallenge, userId } = options
+  const [row] = await db
+    .delete(Schema.pendingKeys)
+    .where(
+      and(
+        eq(Schema.pendingKeys.clientId, clientId),
+        eq(Schema.pendingKeys.codeChallenge, codeChallenge),
+        gt(Schema.pendingKeys.expiresAt, new Date()),
+        // A challenge that an app reuses for another user's request never carries this user's key.
+        eq(Schema.pendingKeys.userId, userId),
+      ),
+    )
+    .returning({
+      account: Schema.pendingKeys.account,
+      keyAuthorization: Schema.pendingKeys.keyAuthorization,
+    })
+  if (!row) return undefined
+  return {
+    account: row.account as `0x${string}`,
+    keyAuthorization: row.keyAuthorization as PendingKey['keyAuthorization'],
+  }
+}
+
+export declare namespace take {
+  type Options = {
+    /** The client ID of the app that redeems the code. */
+    clientId: string
+    /** The PKCE challenge that the redemption's verifier proved. */
+    codeChallenge: string
+    /** The ID of the user whom the code names. */
+    userId: string
+  }
+}

package/src/internal/Privy.ts

@@ -0,0 +1,536 @@
+/**
+ * Each user's Privy embedded wallets, which hold the owner keys of their Privy-owned Tempo Accounts.
+ * Each realm's Privy app keys the user by their user ID, the `sub` of every token Tempo ID issues,
+ * as a custom auth ID. Tempo ID reads and creates wallets with the app secret, and signs as a wallet
+ * with a token that only Privy trusts. Each request reads a Privy user from Privy at most once.
+ * @module
+ */
+import { PrivyClient, type User as PrivyUser } from '@privy-io/node'
+import { createViemAccount } from '@privy-io/node/viem'
+import { createMiddleware } from 'hono/factory'
+import { Base64 } from 'ox'
+import { Account } from 'viem/tempo'
+import type { Env } from './Env.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as Timing from './Timing.js'
+
+/** No `PRIVY_JWT_PRIVATE_KEY` is set, so Tempo ID cannot sign as a Privy wallet. */
+export class SigningKeyMissingError extends Error {
+  override readonly name = 'Privy.SigningKeyMissingError'
+
+  constructor() {
+    super(
+      'Missing PRIVY_JWT_PRIVATE_KEY. Set the RS256 private key whose public half each Privy app trusts.',
+    )
+  }
+}
+
+/** How long a token for Privy lasts, in seconds: long enough for one signing request. */
+const tokenLifetime = 60
+
+/** A realm's Privy app, which holds the owner wallets of the realm's Privy-owned accounts. */
+export type App = {
+  /** The Privy app ID. */
+  appId: string
+  /** The Privy app secret. */
+  appSecret: string
+}
+
+/** A context that carries the request's timing and the Privy users that the request read. */
+export type Context = {
+  /** The request's variables. */
+  var: Pick<Env['Variables'], 'privyUsers' | 'timing'>
+}
+
+/** A user's Privy user in one Privy app, with its wallets. */
+export type User = {
+  /** The Privy user ID, which owns the wallets. */
+  id: string
+  /** The user's embedded Ethereum wallets, oldest first. */
+  wallets: readonly Wallet[]
+}
+
+/**
+ * The Privy users that one request read or created, by Privy app ID and user ID. An entry holds
+ * `undefined` when the user has no Privy user yet. An entry without an app ID marks a user that the
+ * request created, who has no Privy user in any app. {@link middleware} creates it for each request,
+ * so no entry outlives its request.
+ */
+export type Users = Map<string, Promise<User | undefined>>
+
+/** A user's Privy wallet. */
+export type Wallet = {
+  /** The wallet's address. */
+  address: `0x${string}`
+  /** When Privy created the wallet, or a lower bound when Privy omits it. */
+  createdAt: Date
+  /** The Privy wallet ID, which signing requests name. */
+  id: string
+}
+
+/**
+ * Records that the request created the user with `userId`, so the request reads no Privy user for
+ * them from Privy. Privy keys each user by the user's ID, and no Privy app holds a new ID before
+ * the request creates its Privy user.
+ */
+export function created(c: Context, options: created.Options) {
+  c.var.privyUsers.set(
+    memoKey({ app: undefined, userId: options.userId }),
+    Promise.resolve(undefined),
+  )
+}
+
+export declare namespace created {
+  type Options = {
+    /** The ID of the user that the request created. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the user's first Privy wallet in `app`, and creates their Privy user and the wallet when
+ * they have none. Concurrent first calls return the same wallet, and hold no database connection
+ * while Privy responds.
+ */
+export async function firstWallet(
+  c: Context,
+  options: firstWallet.Options,
+): Promise<Wallet> {
+  const { app, userId } = options
+
+  const privyUser =
+    (await Timing.measure(c, findUser(c, { app, userId }), 'Privy.findUser')) ??
+    (await Timing.measure(
+      c,
+      createUser(c, { app, userId }),
+      'Privy.createUser',
+    ))
+  const first = privyUser.wallets[0]
+  if (first) return first
+
+  // The user is created without a wallet, so every call that finds no wallet sends the same
+  // idempotent create, and concurrent calls receive one wallet.
+  const wallet = await Timing.measure(
+    c,
+    addWallet(c, { app, privyUserId: privyUser.id }),
+    'Privy.addWallet',
+  )
+  remember(c, { app, user: { id: privyUser.id, wallets: [wallet] }, userId })
+  return wallet
+}
+
+export namespace firstWallet {
+  export type Options = {
+    /** The Privy app that holds the user's wallets. */
+    app: App
+    /** The user's ID. */
+    userId: string
+  }
+
+  /** The refusals `firstWallet` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = ErrorResponse.fromUpstream.errors
+}
+
+/**
+ * Returns the user's Privy wallets in `app`, oldest first, or none when they have no Privy user yet.
+ * Creates nothing.
+ */
+export async function listWallets(
+  c: Context,
+  options: listWallets.Options,
+): Promise<readonly Wallet[]> {
+  const privyUser = await Timing.measure(
+    c,
+    findUser(c, options),
+    'Privy.findUser',
+  )
+  return privyUser?.wallets ?? []
+}
+
+export namespace listWallets {
+  export type Options = {
+    /** The Privy app that holds the user's wallets. */
+    app: App
+    /** The user's ID. */
+    userId: string
+  }
+
+  /** The refusals `listWallets` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = ErrorResponse.fromUpstream.errors
+}
+
+/** Sets `c.var.privyUsers` to an empty {@link Users} for the request. */
+export const middleware = createMiddleware<Env>(async (c, next) => {
+  c.set('privyUsers', new Map())
+  await next()
+})
+
+/**
+ * Returns a token that names the user for `app`, which Privy exchanges for the right to sign as the
+ * user's wallet. `privateKey` signs it, and Privy trusts only that key's public half, so no token
+ * that Tempo ID issues to apps signs as a wallet. It lasts {@link tokenLifetime} seconds, and its
+ * `aud` is the Privy app ID. Throws {@link SigningKeyMissingError} without `privateKey`.
+ */
+export async function token(
+  auth: token.Auth,
+  options: token.Options,
+): Promise<string> {
+  const { app, privateKey, userId } = options
+  if (!privateKey) throw new SigningKeyMissingError()
+
+  const key = await crypto.subtle.importKey(
+    'pkcs8',
+    new Uint8Array(
+      Base64.toBytes(privateKey.replace(/-----[^-]+-----|\s/g, '')),
+    ),
+    { hash: 'SHA-256', name: 'RSASSA-PKCS1-v1_5' },
+    true,
+    ['sign'],
+  )
+  const jwk = (await crypto.subtle.exportKey('jwk', key)) as JsonWebKey
+  const now = Math.floor(Date.now() / 1000)
+
+  // Better Auth signs with this key alone, never with the keys that sign apps' tokens.
+  const signed = await auth.api.signJWT({
+    body: {
+      overrideOptions: {
+        adapter: {
+          getJwks: () => [
+            {
+              alg: 'RS256',
+              createdAt: new Date(0),
+              id: 'privy',
+              privateKey: JSON.stringify(jwk),
+              publicKey: JSON.stringify({ e: jwk.e, kty: jwk.kty, n: jwk.n }),
+            },
+          ],
+        },
+        jwks: {
+          disablePrivateKeyEncryption: true,
+          keyPairConfig: { alg: 'RS256' },
+        },
+      },
+      payload: {
+        aud: app.appId,
+        exp: now + tokenLifetime,
+        iat: now,
+        sub: userId,
+      },
+    },
+  })
+  return signed.token
+}
+
+export declare namespace token {
+  /** The capability that signs the token: Better Auth's in-process `signJWT`. */
+  type Auth = {
+    /** Better Auth's server API. */
+    api: {
+      /** Signs `payload` with the key set that `overrideOptions` names. */
+      signJWT: (input: {
+        body: {
+          overrideOptions?: Record<string, unknown> | undefined
+          payload: Record<string, unknown>
+        }
+      }) => Promise<{ token: string }>
+    }
+  }
+
+  type Options = {
+    /** The Privy app that exchanges the token. */
+    app: App
+    /** The `PRIVY_JWT_PRIVATE_KEY` variable, as PKCS #8 PEM. */
+    privateKey: string | undefined
+    /** The user's ID, the token's `sub`. */
+    userId: string
+  }
+}
+
+/** Returns the Tempo Account that `wallet` owns, which signs only with `token`. */
+export function toAccount(options: toAccount.Options) {
+  const { app, token, wallet } = options
+  return Account.fromConfig({
+    owners: [
+      createViemAccount(client(app), {
+        address: wallet.address,
+        // Privy signs as the wallet only with its owner's token.
+        ...(token ? { authorizationContext: { user_jwts: [token] } } : {}),
+        walletId: wallet.id,
+      }),
+    ],
+  })
+}
+
+export declare namespace toAccount {
+  type Options = {
+    /** The Privy app that holds `wallet`. */
+    app: App
+    /** The token from {@link token}, which signing requires. Absent, the account cannot sign. */
+    token?: string | undefined
+    /** The owner wallet. */
+    wallet: Wallet
+  }
+}
+
+/**
+ * Adds an embedded wallet to a Privy user. While a concurrent create with the same idempotency key
+ * is still in progress, Privy refuses with a 400, so the create waits and resends a bounded number
+ * of times until Privy returns the first create's wallet.
+ */
+async function addWallet(
+  c: Timing.measure.Context,
+  options: addWallet.Options,
+): Promise<Wallet> {
+  for (let attempt = 1; ; attempt++) {
+    const created = await Timing.measure(
+      c,
+      client(options.app)
+        .wallets()
+        .create({
+          chain_type: 'ethereum',
+          // A retry after a timeout or a 5xx, by the SDK or a later request, returns the wallet that
+          // the first attempt created instead of a second one.
+          idempotency_key: `tempo-id:first-wallet:${options.privyUserId}`,
+          owner: { user_id: options.privyUserId },
+        }),
+      'privy.wallets.create',
+    ).catch((error: unknown) => {
+      if (attempt < addWallet.attempts && inProgress(error)) return undefined
+      throw error
+    })
+
+    if (created)
+      return {
+        address: created.address as Wallet['address'],
+        createdAt: new Date(created.created_at),
+        id: created.id,
+      }
+
+    await Timing.measure(
+      c,
+      new Promise((resolve) => setTimeout(resolve, addWallet.interval)),
+      'Privy.addWallet.wait',
+    )
+  }
+}
+
+namespace addWallet {
+  /** The most creates that one call sends. */
+  export const attempts = 10
+
+  /** The wait between creates, in milliseconds. */
+  export const interval = 250
+
+  export type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The Privy user's ID, which owns the new wallet. */
+    privyUserId: string
+  }
+}
+
+/**
+ * Returns a client for the Privy app `app`. A request waits at most 8 seconds for each of two
+ * attempts, so a slow Privy fails the request with `upstream_unavailable` well before the SDK's
+ * one-minute default.
+ */
+function client(app: App) {
+  return new PrivyClient({
+    appId: app.appId,
+    appSecret: app.appSecret,
+    maxRetries: 1,
+    timeout: 8_000,
+  })
+}
+
+/**
+ * Creates the Privy user for a user ID, without a wallet, and keeps it in the request's
+ * {@link Users}.
+ */
+async function createUser(
+  c: Context,
+  options: createUser.Options,
+): Promise<User> {
+  const created = await Timing.measure(
+    c,
+    client(options.app)
+      .users()
+      .create({
+        linked_accounts: [
+          { custom_user_id: options.userId, type: 'custom_auth' },
+        ],
+      }),
+    'privy.users.create',
+  ).catch(async (error: unknown) => {
+    // A concurrent request may create the user first, so a conflict reads it instead. The read
+    // skips the request's `Users`, which hold no user for the ID.
+    const existing = await Timing.measure(
+      c,
+      getUser(c, options),
+      'Privy.getUser',
+    )
+    if (!existing) throw error
+    return existing
+  })
+
+  const user = toUser(created)
+  remember(c, { app: options.app, user, userId: options.userId })
+  return user
+}
+
+declare namespace createUser {
+  type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The user's ID, which Privy stores as the custom auth ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the Privy user for a user ID, or `undefined` when there is none yet. The request's
+ * {@link Users} keep the result, so the request reads each user from Privy once. Concurrent calls
+ * share one read, and a failed read is not kept.
+ */
+async function findUser(
+  c: Context,
+  options: findUser.Options,
+): Promise<User | undefined> {
+  const users = c.var.privyUsers
+  const key = memoKey(options)
+  const pending =
+    users.get(key) ??
+    users.get(memoKey({ app: undefined, userId: options.userId })) ??
+    (async () => {
+      const found = await Timing.measure(
+        c,
+        getUser(c, options),
+        'Privy.getUser',
+      )
+      return found ? toUser(found) : undefined
+    })()
+  users.set(key, pending)
+
+  return await pending.catch((error: unknown) => {
+    if (users.get(key) === pending) users.delete(key)
+    throw error
+  })
+}
+
+declare namespace findUser {
+  type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The user's ID, which Privy stores as the custom auth ID. */
+    userId: string
+  }
+}
+
+/** Reads the Privy user for a user ID from Privy, or `undefined` when there is none yet. */
+async function getUser(c: Timing.measure.Context, options: getUser.Options) {
+  return await Timing.measure(
+    c,
+    client(options.app)
+      .users()
+      .getByCustomAuthID({ custom_user_id: options.userId }),
+    'privy.users.get',
+  ).catch((error: unknown) => {
+    if (error instanceof Error && 'status' in error && error.status === 404)
+      return undefined
+    throw error
+  })
+}
+
+declare namespace getUser {
+  type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The user's ID, which Privy stores as the custom auth ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns whether `error` is Privy's refusal of a create whose idempotency key names a create still
+ * in progress. Privy marks it only with a 400 and its message.
+ */
+function inProgress(error: unknown) {
+  return (
+    error instanceof Error &&
+    'status' in error &&
+    error.status === 400 &&
+    error.message.includes('idempotency key is still in progress')
+  )
+}
+
+/**
+ * Returns the key of the user with `userId` in `app`, in the request's {@link Users}. Without `app`,
+ * the key marks a user that the request created.
+ */
+function memoKey(options: memoKey.Options) {
+  return JSON.stringify([options.app?.appId ?? null, options.userId])
+}
+
+declare namespace memoKey {
+  type Options = {
+    /** The Privy app that holds the user, or `undefined` for a user that the request created. */
+    app: App | undefined
+    /** The user's ID. */
+    userId: string
+  }
+}
+
+/** Keeps `user` as the Privy user for `userId` in `app`, in the request's {@link Users}. */
+function remember(c: Context, options: remember.Options) {
+  c.var.privyUsers.set(memoKey(options), Promise.resolve(options.user))
+}
+
+declare namespace remember {
+  type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The Privy user, with every wallet that the request knows. */
+    user: User
+    /** The user's ID. */
+    userId: string
+  }
+}
+
+/** Returns the Privy user `privyUser` as a {@link User}. */
+function toUser(privyUser: PrivyUser): User {
+  return { id: privyUser.id, wallets: wallets(privyUser) }
+}
+
+/** Returns a Privy user's embedded Ethereum wallets, in the order Privy created them. */
+function wallets(privyUser: PrivyUser): readonly Wallet[] {
+  return privyUser.linked_accounts
+    .flatMap((entry) =>
+      entry.type === 'wallet' &&
+      'chain_type' in entry &&
+      entry.chain_type === 'ethereum' &&
+      'connector_type' in entry &&
+      entry.connector_type === 'embedded' &&
+      'id' in entry &&
+      entry.id
+        ? [{ ...entry, id: entry.id }]
+        : [],
+    )
+    .sort((a, b) => (a.wallet_index ?? 0) - (b.wallet_index ?? 0))
+    .reduce<readonly Wallet[]>((list, entry) => {
+      // Privy records a wallet's creation as its first verification, in seconds. Without it, the
+      // first wallet was created with the user, and a later one after the wallet before it. That
+      // time is a lower bound that keeps the wallets in order.
+      const createdAt =
+        typeof entry.first_verified_at === 'number'
+          ? new Date(entry.first_verified_at * 1000)
+          : (list.at(-1)?.createdAt ?? new Date(privyUser.created_at * 1000))
+      return [
+        ...list,
+        {
+          address: entry.address as Wallet['address'],
+          createdAt,
+          id: entry.id,
+        },
+      ]
+    }, [])
+}