@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/api/lib/DeviceRequest.ts

@@ -0,0 +1,265 @@
+/**
+ * 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 { isAPIError } from 'better-auth/api'
+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 id = await Timing.measure(
+    c,
+    Device.id(db, { deviceCode: options.deviceCode }),
+    'Device.id',
+  )
+  if (!id) throw new Error('The device code has no row.')
+
+  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,
+      expiresAt: new Date(Date.now() + options.expiresIn * 1000),
+      id,
+      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()
+
+  // Better Auth binds only a pending code without a user, in one conditional update, so of two
+  // concurrent reads only one binds it.
+  const bound = await (async () => {
+    if (found.status !== 'pending' || found.userId) return found
+    try {
+      await Timing.measure(
+        c,
+        c.var.auth.api.deviceVerify({
+          headers: c.req.raw.headers,
+          query: { user_code: userCode },
+        }),
+        'auth.deviceVerify',
+      )
+    } catch (error) {
+      // The code expired between the read and the binding.
+      if (isAPIError(error)) return undefined
+      throw error
+    }
+    return await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+  })()
+  if (!bound || (bound.userId && bound.userId !== options.userId))
+    return new Device.UnknownCodeError()
+
+  // A registered app has a name, but a deleted one has none, and the code then shows it unverified.
+  const app = await Timing.measure(
+    c,
+    Apps.get(db, { clientId: found.clientId }).catch((error: unknown) => {
+      if (error instanceof Apps.NotFoundError) return undefined
+      throw error
+    }),
+    'Apps.get',
+  )
+  return {
+    clientId: found.clientId,
+    request: {
+      ...(app?.name ? { app: { name: app.name } } : {}),
+      ...(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)
+    return new Authorize.RejectedError({
+      description: `Approval refused: \`client_id\` ${request.clientId} names no enabled public 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,
+      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,90 @@
+/**
+ * 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,
+ * so a user with no account, such as one whose first creation failed, receives one at the next.
+ * @module
+ */
+import type { Context } from 'hono'
+import { env } from 'void/env'
+import type { Env } from '../../internal/Env.js'
+import * as Log from '../../internal/Log.js'
+import * as Realm from '../../internal/Realm.js'
+import * as TempoAccount from '../../internal/TempoAccount.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Cors from './Cors.js'
+import { db } from './Database.js'
+
+/**
+ * How long a sign-in waits for the creation, in milliseconds. A slower creation, such as one that
+ * waits on Privy, continues after the response, and the sign-in does not wait for it.
+ */
+const deadline = 2_000
+
+/**
+ * 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. A
+ * sign-in from a first-party app's page creates none, since the app's `POST /v1/account` creates
+ * the account in the app's own realm. The call counts against the user's `ACCOUNT_LIMIT`, and a
+ * spent limit skips it.
+ *
+ * It never fails the sign-in, and the sign-in waits for it {@link deadline} at most. A failure, such
+ * as a Privy outage, logs a warning, and the next sign-in or `POST /v1/account` creates the account.
+ */
+export async function create(c: Context<Env>, options: create.Options) {
+  const { clientId, userId } = options
+  if (Cors.appOrigin(c)) return
+
+  const work = (async () => {
+    try {
+      // The creation reads every realm's Privy app, whose quota every user shares.
+      const outcome = await Timing.measure(
+        c,
+        c.env.ACCOUNT_LIMIT.limit({ key: userId }),
+        'ratelimit.limit',
+      )
+      if (!outcome.success) return
+
+      const stored = await Timing.measure(
+        c,
+        Realm.forRequest(db, {
+          clientId: clientId ?? undefined,
+          own: new URL(env.URL).origin,
+        }),
+        'Realm.forRequest',
+      )
+      const realms = await Timing.measure(
+        c,
+        Realm.withDefaults(db, { origin: env.URL, realms: stored }),
+        'Realm.withDefaults',
+      )
+      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.',
+      })
+    }
+  })()
+  // The work catches and logs its own failure, so the Worker keeps it running past the response.
+  c.executionCtx.waitUntil(work)
+  await Promise.race([
+    work,
+    new Promise<void>((resolve) => setTimeout(resolve, deadline)),
+  ])
+}
+
+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 ID of the user who signed in. */
+    userId: string
+  }
+}