@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/DeviceRequest.ts

@@ -0,0 +1,244 @@
+/**
+ * Records where a device code's request came from and the key that it requests, reads it as the
+ * device page shows it, for `GET /v1/device/requests/:code` and the page's loader, and signs its key
+ * on approval.
+ * @module
+ */
+import type { Context } from 'hono'
+import * as Apps from '../../internal/Apps.js'
+import * as Authorize from '../../internal/Authorize.js'
+import * as Device from '../../internal/Device.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as KeyAuthorization from '../../internal/KeyAuthorization.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as Timing from '../../internal/Timing.js'
+import { db } from './Database.js'
+import * as KeySigner from './KeySigner.js'
+import type * as Session from './Session.js'
+
+/**
+ * Stores the name that the device reported, if any, with its IP address and its city and country,
+ * and the key that it requests, for the device code `deviceCode` that Better Auth just issued. The
+ * device page shows them, so a code from either device authorization endpoint shows where it came
+ * from.
+ */
+export async function create(c: Context<Env>, options: create.Options) {
+  const cf = c.req.raw.cf
+  const location = [cf?.city, cf?.country].filter(Boolean).join(', ')
+  await Timing.measure(
+    c,
+    Device.create(db, {
+      challenge: options.challenge ?? null,
+      device: options.device,
+      deviceCode: options.deviceCode,
+      expiresAt: new Date(Date.now() + options.expiresIn * 1000),
+      ip: c.req.header('cf-connecting-ip') ?? null,
+      key: options.key ?? null,
+      location: location || null,
+    }),
+    'Device.create',
+  )
+}
+
+export declare namespace create {
+  type Options = {
+    /** The message whose hash becomes the key's witness. Absent for a request without one. */
+    challenge?: string | undefined
+    /** The name that the device reported. Null for a code from `POST /device/code`. */
+    device: string | null
+    /** The device code that Better Auth issued. */
+    deviceCode: string
+    /** Seconds until the device code expires. */
+    expiresIn: number
+    /**
+     * The key that the device requests, with every default filled, before the challenge is bound.
+     * Absent for a request without a key.
+     */
+    key?: KeyAuthorization.Key | undefined
+  }
+}
+
+/**
+ * Returns the request of the live user code `code`, as the user typed it, in the shape of
+ * `GET /v1/device/requests/:code`, with the client ID of the app that requested it. Binds a pending code to the signed-in user who reads it first, so
+ * no user who learns the code later approves it into another account (GHSA-cq3f-vc6p-68fh). Returns
+ * `UnknownCodeError` for an unknown or expired code, and for a code that another user holds, so the
+ * refusal reveals nothing about another user's code.
+ */
+export async function read(c: Session.get.Context, options: read.Options) {
+  const userCode = Device.normalize(options.code)
+  const found = userCode
+    ? await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+    : undefined
+  if (!userCode || !found) return new Device.UnknownCodeError()
+
+  // The binding is one conditional update, so of two concurrent reads only one binds the code.
+  const bound = await (async () => {
+    if (found.status !== 'pending' || found.userId) return found
+    const stored = await Timing.measure(
+      c,
+      Device.bind(db, { id: found.id, userId: options.userId }),
+      'Device.bind',
+    )
+    if (stored) return { ...found, userId: options.userId }
+    // Another read bound the code, or the code expired, between the read and the binding.
+    return await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+  })()
+  if (!bound || (bound.userId && bound.userId !== options.userId))
+    return new Device.UnknownCodeError()
+
+  // A deleted app has no name, and the code then shows it unverified.
+  return {
+    // The chain of the request's key, whose view of the accounts the page shows.
+    chainId: found.key?.chainId,
+    clientId: found.clientId,
+    request: {
+      ...(found.appName ? { app: { name: found.appName } } : {}),
+      ...(found.challenge ? { challenge: found.challenge } : {}),
+      created_at: Math.floor(found.createdAt.getTime() / 1000),
+      ...(found.device ? { device: found.device } : {}),
+      ...(found.ip ? { ip: found.ip } : {}),
+      ...(found.key
+        ? { key_authorization: KeyAuthorization.describe(found.key) }
+        : {}),
+      ...(found.location ? { location: found.location } : {}),
+      status: bound.status,
+      user_code: bound.userCode,
+    },
+  }
+}
+
+export declare namespace read {
+  type Options = {
+    /** The user code, as the user typed it. */
+    code: string
+    /** The ID of the signed-in user who reads the code. */
+    userId: string
+  }
+}
+
+export namespace read {
+  /** The refusals `read` returns. */
+  export const errors = [Device.UnknownCodeError] as const
+}
+
+/**
+ * Checks the key of the device code's request `request` again, as of now, and signs it as the owner
+ * of the account that the key names, else the account that the device page showed, else the app's
+ * selected account, else the user's oldest. A user who holds no account receives a first account
+ * before the key is signed. A passkey owner signs with `assertion`. Without one, it returns the
+ * options of the passkey step. Returns the signed key and its account, or a refusal.
+ */
+export async function sign(c: Context<Env>, options: sign.Options) {
+  const { request, session } = options
+  // `Device.get` returns a request with its key, and the caller signs only that one.
+  const key = request.key!
+
+  // A code lasts minutes, so approval checks the key again at its own time and against the app as
+  // it is now, as the approval page does: an expiry can pass, the app can lose `tempo-id:sign`, or
+  // an admin can disable or delete the app.
+  const app = await Timing.measure(
+    c,
+    Apps.get(db, { clientId: request.clientId, enabled: true }).catch(
+      (error: unknown) => {
+        if (error instanceof Apps.NotFoundError) return undefined
+        throw error
+      },
+    ),
+    'Apps.get',
+  )
+  if (!app?.device || app.secret || !app.firstParty)
+    return new Authorize.RejectedError({
+      description: `Approval refused: \`client_id\` ${request.clientId} names no enabled public first-party device app. Deny the request, and start the sign-in again.`,
+    })
+  const refused =
+    KeyAuthorization.check(key) ??
+    KeyAuthorization.checkChallenge({ app, clientId: request.clientId, key })
+  if (refused) return refused
+
+  const signing = await Timing.measure(
+    c,
+    KeySigner.resolve(c, {
+      account: key.account ?? options.account,
+      chainId: key.chainId,
+      clientId: request.clientId,
+      cookie: c.req.header('cookie'),
+      // The approval is an explicit decision on Tempo ID's own page, as on the approval page.
+      create: true,
+      // The device page runs the passkey step.
+      passkey: true,
+      sessionId: session.session.id,
+      userId: session.user.id,
+    }),
+    'KeySigner.resolve',
+  )
+  // Only a passkey whose relying party does not cover Tempo ID's origin reaches it.
+  if (signing instanceof KeyAuthorization.WebAuthnRequiredError) {
+    const account = signing.response.meta?.account as `0x${string}`
+    return new KeyAuthorization.WebAuthnRequiredError({
+      account,
+      description: `Passkey required: the passkey of Tempo Account ${account} signs only at its own relying party, which the device page is not part of. Name another account, or deny the request.`,
+    })
+  }
+  if (signing instanceof ErrorResponse.ResponseError) return signing
+
+  // Only the passkey step issues a challenge, so an assertion for another owner verifies nothing.
+  if (options.assertion && signing.owner.signer)
+    return new Passkey.WebAuthnRejectedError()
+  if (!options.assertion && !signing.owner.signer)
+    return {
+      options: await Timing.measure(
+        c,
+        KeySigner.challenge(c, {
+          account: signing.account,
+          clientId: request.clientId,
+          key,
+          owner: signing.owner,
+          userId: session.user.id,
+        }),
+        'KeySigner.challenge',
+      ),
+    }
+
+  const signed = await Timing.measure(
+    c,
+    KeySigner.sign(c, {
+      account: signing.account,
+      assertion: options.assertion,
+      clientId: request.clientId,
+      key,
+      owner: signing.owner,
+      userId: session.user.id,
+    }),
+    'KeySigner.sign',
+  )
+  if (signed instanceof ErrorResponse.ResponseError) return signed
+  return { account: signing.account, keyAuthorization: signed }
+}
+
+export declare namespace sign {
+  type Options = {
+    /** The account that the device page showed, if any. */
+    account?: `0x${string}` | undefined
+    /** The passkey's assertion over the options of the passkey step, for a passkey owner. */
+    assertion?: Passkey.Assertion | undefined
+    /** The device code's request, which holds a key. */
+    request: Device.Request
+    /** The signed-in session and its user. */
+    session: { session: { id: string }; user: { id: string } }
+  }
+}
+
+export namespace sign {
+  /** The refusals `sign` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.check.errors,
+    Authorize.RejectedError,
+    ...KeyAuthorization.checkChallenge.errors,
+    ...KeySigner.resolve.errors,
+    ...KeySigner.sign.errors,
+    KeyAuthorization.WebAuthnRequiredError,
+    Passkey.WebAuthnRejectedError,
+  ] as const
+}

package/src/api/lib/FirstAccount.ts

@@ -0,0 +1,136 @@
+/**
+ * Creates the first Tempo Account of a user at sign-in, in the realm of the sign-in: the first realm
+ * of the app that the sign-in continues, or the `default` realm without one. Every sign-in calls it,
+ * and waits for it, so a user holds a wallet once signed in. A user whose creation failed receives
+ * one at the next sign-in, or from the account page.
+ * @module
+ */
+import { and, eq, isNotNull, sql } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { env } from 'void/env'
+import * as Schema from '../../app/db/schema.js'
+import type { Env } from '../../internal/Env.js'
+import * as Log from '../../internal/Log.js'
+import * as RateLimit from '../../internal/RateLimit.js'
+import * as Realm from '../../internal/Realm.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Configure from './Configure.js'
+import * as Cors from './Cors.js'
+import { db } from './Database.js'
+
+/**
+ * Creates the first Tempo Account of the user with `userId` in the realm of the sign-in, when the
+ * user holds none there and a kind creates keys in that realm, as `POST /v1/account` does. A user
+ * with an account, or with a linked owner key such as a wallet.tempo passkey, receives none. On a
+ * deployment with configurable accounts, neither does a user whose email has a wallet.tempo passkey
+ * that has not linked yet, since its upgrade on the account page links it as the user's account,
+ * unless Tempo ID stores a passkey of the user. A sign-in from a first-party app's page creates
+ * none, since it names no app, and the app's own `POST /v1/account`, which its sign-in actions
+ * send, creates the account in the app's first realm. The call counts against the user's
+ * `ACCOUNT_LIMIT`, and a spent limit skips it.
+ *
+ * A user who claimed a first account, or whose passkey owns one, returns at once, so a sign-in
+ * reads no Privy app for a user who holds a wallet. Any other sign-in waits for the creation,
+ * however long Privy takes, so its response follows the wallet. It never fails the sign-in. A
+ * failure, such as a Privy outage, logs a warning, and the account page or the next sign-in
+ * creates the account.
+ */
+export async function create(c: Context<Env>, options: create.Options) {
+  const { clientId, userId } = options
+  if (Cors.appOrigin(c)) return
+  try {
+    // One statement answers both checks, since a sign-in waits on each round trip.
+    const [held] = await Timing.measure(
+      c,
+      db
+        .select({
+          held: sql<boolean>`exists (${db
+            .select({ realmId: Schema.firstAccounts.realmId })
+            .from(Schema.firstAccounts)
+            .where(eq(Schema.firstAccounts.userId, userId))}) or exists (${db
+            .select({ id: Schema.keys.id })
+            .from(Schema.keys)
+            .where(
+              and(
+                eq(Schema.keys.userId, userId),
+                isNotNull(Schema.keys.address),
+              ),
+            )})`,
+        })
+        .from(sql`(values (1)) as one`),
+      'db.account.held',
+    )
+    if (held?.held) return
+
+    // The creation reads every realm's Privy app, whose quota every user shares.
+    const admitted = await RateLimit.count(c, {
+      binding: 'ACCOUNT_LIMIT',
+      key: userId,
+    })
+    if (!admitted) return
+
+    const stored = await Timing.measure(
+      c,
+      Realm.forRequest(c, {
+        clientId: clientId ?? undefined,
+        db,
+        own: new URL(env.URL).origin,
+      }),
+      'Realm.forRequest',
+    )
+    const realms = await Timing.measure(
+      c,
+      Realm.withDefaults(c, { db, origin: env.URL, realms: stored }),
+      'Realm.withDefaults',
+    )
+    // On a deployment with configurable accounts, a wallet.tempo passkey of the user's email becomes
+    // the user's account through its upgrade, so the sign-in creates no cloud wallet beside it. The
+    // email is read only where the lookup runs.
+    const email = await (async () => {
+      if (options.email !== undefined) return options.email
+      if (!Configure.looksUpUpgrade(c, { realms })) return undefined
+      const [row] = await Timing.measure(
+        c,
+        db
+          .select({ email: Schema.user.email })
+          .from(Schema.user)
+          .where(eq(Schema.user.id, userId)),
+        'db.user.get',
+      )
+      return row?.email
+    })()
+    if (
+      email !== undefined &&
+      (await Timing.measure(
+        c,
+        Configure.awaitsUpgrade(c, { email, realms, userId }),
+        'Configure.awaitsUpgrade',
+      ))
+    )
+      return
+    await Timing.measure(
+      c,
+      TempoAccount.create(c, { db, env, realms, userId }),
+      'TempoAccount.create',
+    )
+  } catch (error) {
+    Log.warn(c, {
+      error,
+      fields: { clientId: clientId ?? undefined },
+      message:
+        'The sign-in created no first account, since its creation failed.',
+    })
+  }
+}
+
+export declare namespace create {
+  type Options = {
+    /** The client ID of the app that the sign-in continues, or `null` for a sign-in without one. */
+    clientId: string | null
+    /** The user's verified email, when the sign-in holds it. Absent, the call reads it if needed. */
+    email?: string | undefined
+    /** The ID of the user who signed in. */
+    userId: string
+  }
+}