@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

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,402 @@
+/**
+ * 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.
+ * @module
+ */
+import { PrivyClient } from '@privy-io/node'
+import { createViemAccount } from '@privy-io/node/viem'
+import { Base64 } from 'ox'
+import { Account } from 'viem/tempo'
+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 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
+}
+
+/**
+ * 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: Timing.measure.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',
+    ))
+  // 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.
+  return (
+    wallets(privyUser)[0] ??
+    (await Timing.measure(
+      c,
+      addWallet(c, { app, privyUserId: privyUser.id }),
+      'Privy.addWallet',
+    ))
+  )
+}
+
+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: Timing.measure.Context,
+  options: listWallets.Options,
+): Promise<readonly Wallet[]> {
+  const privyUser = await Timing.measure(
+    c,
+    findUser(c, options),
+    'Privy.findUser',
+  )
+  return privyUser ? wallets(privyUser) : []
+}
+
+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
+}
+
+/**
+ * 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. */
+async function createUser(
+  c: Timing.measure.Context,
+  options: createUser.Options,
+) {
+  return 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.
+    const existing = await Timing.measure(
+      c,
+      findUser(c, options),
+      'Privy.findUser',
+    )
+    if (!existing) throw error
+    return existing
+  })
+}
+
+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. */
+async function findUser(c: Timing.measure.Context, options: findUser.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 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
+  }
+}
+
+/**
+ * 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 a Privy user's embedded Ethereum wallets, in the order Privy created them. */
+function wallets(
+  privyUser: Awaited<ReturnType<typeof createUser>>,
+): 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,
+        },
+      ]
+    }, [])
+}

package/src/internal/Provider.ts

@@ -0,0 +1,125 @@
+/**
+ * The OAuth providers that Tempo ID offers for sign-in, such as Google, and the checks on the page
+ * that a provider sign-in returns to. Better Auth's social sign-in runs each provider's flow.
+ * @module
+ */
+import { eq } from 'drizzle-orm'
+import * as Schema from '../app/db/schema.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import type * as Realm from './Realm.js'
+
+/** The page that a provider sign-in returns to is on neither Tempo ID's origin nor the app's. */
+export class ReturnToNotPermittedError extends ErrorResponse.define(
+  'return_to_not_permitted',
+) {
+  override readonly name = 'Provider.ReturnToNotPermittedError'
+
+  constructor(options: ReturnToNotPermittedError.Options) {
+    super({
+      error_description: `Invalid return_to: ${options.origin} is not an origin of the app's redirect URIs. Return to a page on one of them, and pass the app's client_id.`,
+      field: 'return_to',
+      meta: { origin: options.origin },
+    })
+  }
+}
+
+export declare namespace ReturnToNotPermittedError {
+  type Options = {
+    /** The origin of the refused page. */
+    origin: string
+  }
+}
+
+/** The sign-in names a provider that Tempo ID does not offer. */
+export class UnknownError extends ErrorResponse.define('unknown_provider') {
+  override readonly name = 'Provider.UnknownError'
+
+  constructor(options: UnknownError.Options) {
+    super({
+      error_description: `Unknown provider: ${options.provider} is not offered. Request GET /v1/auth/providers for the providers offered.`,
+      field: 'provider',
+      meta: { provider: options.provider },
+    })
+  }
+}
+
+export declare namespace UnknownError {
+  type Options = {
+    /** The provider that the sign-in names. */
+    provider: string
+  }
+}
+
+/** The ID of an OAuth provider that Tempo ID can offer. */
+export type Provider = keyof typeof names
+
+/** The name to show for each provider that Tempo ID can offer, by its ID. */
+export const names = { google: 'Google' } as const
+
+/** Returns the providers that `options` configures, in the order a page shows them. */
+export function list(options: list.Options): list.ReturnType {
+  return options.google ? [{ id: 'google', name: names.google }] : []
+}
+
+export declare namespace list {
+  type Options = {
+    /** Google's OAuth client. Absent, Tempo ID offers no Google sign-in. */
+    google?: { clientId: string; clientSecret: string } | undefined
+  }
+
+  type ReturnType = readonly {
+    /** The provider's ID. */
+    id: Provider
+    /** The name to show, such as `Google`. */
+    name: string
+  }[]
+}
+
+/**
+ * Returns `returnTo` when a provider sign-in may return there: a page on Tempo ID's own origin, or on
+ * an origin of a redirect URI of the app with `clientId`. Otherwise returns the refusal.
+ */
+export async function returnTo(
+  db: Realm.Database,
+  options: returnTo.Options,
+): Promise<string | ErrorResponse.Instance<typeof returnTo.errors>> {
+  const { clientId, own } = options
+  const url = new URL(options.returnTo, own)
+  // A `blob:` URL carries the origin of the page that made it, so only a page's own scheme passes.
+  if (url.protocol !== 'https:' && url.protocol !== 'http:')
+    return new ReturnToNotPermittedError({ origin: url.origin })
+  if (url.origin === own) return url.href
+
+  const [app] = clientId
+    ? await db
+        .select({ redirectUris: Schema.oauthClient.redirectUris })
+        .from(Schema.oauthClient)
+        .where(eq(Schema.oauthClient.clientId, clientId))
+    : []
+  const origins = (app?.redirectUris ?? []).flatMap((uri) => {
+    const parsed = URL.parse(uri)
+    return parsed &&
+      (parsed.protocol === 'https:' || parsed.protocol === 'http:')
+      ? [parsed.origin]
+      : []
+  })
+  if (!origins.includes(url.origin))
+    return new ReturnToNotPermittedError({ origin: url.origin })
+  return url.href
+}
+
+export namespace returnTo {
+  /** The refusal `returnTo` returns. */
+  export const errors = [ReturnToNotPermittedError] as const
+}
+
+export declare namespace returnTo {
+  type Options = {
+    /** The client ID of the app that the sign-in names, if any. */
+    clientId?: string | undefined
+    /** Tempo ID's own origin. */
+    own: string
+    /** The page to return to, absolute or relative to `own`. */
+    returnTo: string
+  }
+}