@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/api/lib/Consent.ts

@@ -0,0 +1,339 @@
+/**
+ * Records a signed-in user's approval of an app's authorization request, as the approval page does,
+ * and as a sign-in does that showed the request's key on the sign-in page. An approval of a request
+ * with a key signs the key as the owner of the account first, so a refused key issues no code.
+ * @module
+ */
+import { isNativePrivateUseRedirectUri } from '@better-auth/core/utils/redirect-uri'
+import { verifyOAuthQueryParams } from '@better-auth/oauth-provider'
+import { isAPIError } from 'better-auth/api'
+import type { Context } from 'hono'
+import type { Hex } from 'ox'
+import * as z from 'zod'
+import * as Apps from '../../internal/Apps.js'
+import * as core_Auth from '../../internal/Auth.js'
+import * as Authorize from '../../internal/Authorize.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 PendingKey from '../../internal/PendingKey.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Validation from '../../internal/Validation.js'
+import { db } from './Database.js'
+import * as KeySigner from './KeySigner.js'
+
+/** Better Auth's result, which names the redirect: a path on Tempo ID, or the app's URL. */
+const result = z.object({ url: z.string().min(1) })
+
+/**
+ * Approves the authorization request that `oauthQuery` carries for the signed-in `session`, and
+ * returns the app's redirect. A request with a key first has its key signed by the account's owner,
+ * and the first redemption of the code returns it. A passkey-owned account returns the options of
+ * the passkey step, unless `oneTap` holds an assertion of that passkey over the key's digest.
+ * Better Auth stores the consent before it returns the redirect, so the next request of the app
+ * with the same scopes skips the approval page.
+ */
+export async function approve(
+  c: Context<Env>,
+  options: approve.Options,
+): Promise<approve.ReturnType | ErrorResponse.Instance<typeof approve.errors>> {
+  const { headers, oauthQuery, session } = options
+
+  // Better Auth stores the consent before it returns the redirect, so the signed redirect URI is
+  // checked first, or an approval would let the app's next request reach it without this page.
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const verified = await Timing.measure(
+    c,
+    verifyOAuthQueryParams(oauthQuery, context.secret),
+    'auth.verifyOAuthQueryParams',
+  )
+  if (!verified) return new core_Auth.AuthorizationExpiredError()
+  const query = new URLSearchParams(oauthQuery)
+  checkRedirect(query)
+
+  // The caller counts each approval of a key on the user's `AUTHORIZE_LIMIT`, since it reads the
+  // user's accounts and calls Privy.
+  const keyed = keyedQuery(query)
+  const pending = keyed
+    ? await Timing.measure(
+        c,
+        approveKey(c, {
+          account: options.account,
+          assertion: options.assertion,
+          oneTap: options.oneTap,
+          query,
+          session,
+          single: options.single,
+        }),
+        'Consent.approveKey',
+      )
+    : undefined
+  if (pending instanceof ErrorResponse.ResponseError) return pending
+  if (pending && 'options' in pending) return { options: pending.options }
+
+  const approved = await Timing.measure(
+    c,
+    c.var.auth.api.oauth2Consent({
+      // A call with a request returns a `Response` unless `asResponse` is false.
+      asResponse: false,
+      body: { accept: true, oauth_query: oauthQuery },
+      headers,
+      // An authorization that asks to sign in again continues through the request.
+      request: new Request(c.req.url, { headers, method: 'POST' }),
+    }),
+    'auth.oauth2Consent',
+  ).catch((error: unknown) => {
+    // Better Auth refuses a forged or expired request before it stores anything.
+    if (isAPIError(error) && error.body?.error === 'invalid_signature')
+      return new core_Auth.AuthorizationExpiredError()
+    throw error
+  })
+  if (approved instanceof ErrorResponse.ResponseError) return approved
+  const redirect = result.parse(approved).url
+
+  // The signed key waits for the code's redemption, since a redirect URL reaches history, logs, and
+  // `Referer` headers. A redirect without a code, such as to sign in again, holds no key.
+  const code = URL.parse(redirect)?.searchParams.get('code')
+  if (pending && code)
+    await Timing.measure(
+      c,
+      PendingKey.put(db, {
+        clientId: pending.clientId,
+        codeChallenge: pending.codeChallenge,
+        expiry: pending.expiry,
+        key: { account: pending.account, keyAuthorization: pending.signed },
+        userId: session.user.id,
+      }),
+      'PendingKey.put',
+    )
+  return { redirect }
+}
+
+export declare namespace approve {
+  type Options = {
+    /** The account that the approval page showed, if any. */
+    account?: `0x${string}` | undefined
+    /** The passkey's assertion over the options of the passkey step, if any. */
+    assertion?: Passkey.Assertion | undefined
+    /** The request headers, with the cookie of the signed-in session. */
+    headers: Headers
+    /** The signed query string of the approved authorization request. */
+    oauthQuery: string
+    /** A passkey sign-in whose assertion signed the key's digest, if any. */
+    oneTap?: OneTap | undefined
+    /** The signed-in session. */
+    session: Session
+    /**
+     * Whether a user who holds several accounts and chose none is refused, in place of the oldest
+     * account. A sign-in that grants the key sets it, since it shows no account. Defaults to `false`.
+     */
+    single?: boolean | undefined
+  }
+
+  type ReturnType =
+    | {
+        /** The options of the passkey step, which a passkey-owned account's approval returns. */
+        options: PasskeyOptions
+      }
+    | {
+        /** The app's redirect: its `redirect_uri` with a code, or a path on Tempo ID. */
+        redirect: string
+      }
+}
+
+export namespace approve {
+  /** The refusals `approve` returns. Its return type admits no other. */
+  export const errors = [
+    ...Authorize.checkKey.errors,
+    ...KeySigner.resolve.errors,
+    ...KeySigner.sign.errors,
+    core_Auth.AuthorizationExpiredError,
+    Authorize.RejectedError,
+    KeyAuthorization.WebAuthnRequiredError,
+    Passkey.WebAuthnRejectedError,
+    Validation.InvalidFieldError,
+  ] as const
+}
+
+/** Returns whether the authorization request `query` carries a key or a challenge, which an approval signs. */
+export function keyedQuery(query: URLSearchParams) {
+  return query.has('key_authorization') || query.has('challenge')
+}
+
+/** A passkey sign-in whose challenge was the digest of the request's key. */
+export type OneTap = {
+  /** The passkey's assertion, which signed the sign-in and the key's digest. */
+  assertion: Passkey.Assertion
+  /** The random witness that the key's digest binds. */
+  witness: Hex.Hex
+}
+
+/** The request options of the passkey step, for `navigator.credentials.get()`. */
+type PasskeyOptions = Awaited<ReturnType<typeof KeySigner.challenge>>
+
+/** A signed-in session, as `Session.get` returns it. */
+export type Session = { session: { id: string }; user: { id: string } }
+
+/**
+ * Throws when the `redirect_uri` of the signed authorization `query` is missing, or uses a scheme
+ * other than `http:`, `https:`, or a native app's private-use scheme. Better Auth refuses a
+ * `javascript:`, `data:`, or `vbscript:` redirect URI, and registration refuses every reserved
+ * scheme, such as `file:`. One here is a corrupt registration.
+ */
+export function checkRedirect(query: URLSearchParams) {
+  const url = URL.parse(query.get('redirect_uri') ?? '')
+  if (
+    !url ||
+    (url.protocol !== 'http:' &&
+      url.protocol !== 'https:' &&
+      !isNativePrivateUseRedirectUri(url))
+  )
+    throw new Error("The app's redirect URI uses a refused scheme.")
+}
+
+/**
+ * Checks and signs the key authorization that the approved request `query` carries, as the owner of
+ * the account that the key names, else the account that the approval 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`, or with the assertion of
+ * `oneTap` when that passkey owns the account. Without either, it returns the options of the
+ * passkey step. Returns what `PendingKey.put` holds, `undefined` for a request without a key, or a
+ * refusal.
+ */
+async function approveKey(c: Context<Env>, options: approveKey.Options) {
+  const { oneTap, query, session } = options
+  const requested = Authorize.fromQuery(query)
+  if (!requested || requested instanceof ErrorResponse.ResponseError)
+    return requested
+
+  // Better Auth verified the query's signature, which covers its client ID and challenge.
+  const clientId = query.get('client_id')!
+  const codeChallenge = query.get('code_challenge')
+
+  const app = await Timing.measure(
+    c,
+    Apps.get(db, { clientId }).catch((error: unknown) => {
+      if (error instanceof Apps.NotFoundError) return undefined
+      throw error
+    }),
+    'Apps.get',
+  )
+  const refused = Authorize.checkKey({
+    app,
+    clientId,
+    codeChallenge,
+    key: requested,
+  })
+  if (refused) return refused
+
+  const signing = await Timing.measure(
+    c,
+    KeySigner.resolve(c, {
+      account: requested.account ?? options.account,
+      clientId,
+      cookie: c.req.header('cookie'),
+      // The approval is an explicit decision on Tempo ID's own page, so a user who holds no account
+      // receives the first one here, never on a cross-site GET or a headless authorization.
+      create: true,
+      // The approval page runs the passkey step.
+      passkey: true,
+      sessionId: session.session.id,
+      single: options.single,
+      userId: session.user.id,
+    }),
+    'KeySigner.resolve',
+  )
+  // The approval page is the redirect's page, so the refusal names no other flow. 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 approval page is not part of. Name another account, or deny the request.`,
+    })
+  }
+  if (signing instanceof ErrorResponse.ResponseError) return signing
+
+  // A one-tap sign-in signs only for the account that its own passkey owns. Its digest binds the
+  // sign-in's witness, so the key carries that witness.
+  const tapped =
+    oneTap && signing.owner.credential?.id === oneTap.assertion.id
+      ? oneTap
+      : undefined
+  const key = tapped ? { ...requested, witness: tapped.witness } : requested
+  const assertion = tapped?.assertion ?? options.assertion
+
+  // 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 (!assertion && !signing.owner.signer)
+    return {
+      options: await Timing.measure(
+        c,
+        KeySigner.challenge(c, {
+          account: signing.account,
+          clientId,
+          key,
+          owner: signing.owner,
+          userId: session.user.id,
+        }),
+        'KeySigner.challenge',
+      ),
+    }
+
+  // The sign-in already spent its own challenge, so the key's digest is recorded as a signature
+  // request here, and `KeySigner.sign` spends it, which records the assertion as spent.
+  if (tapped)
+    await Timing.measure(
+      c,
+      Passkey.requestSignature(db, {
+        account: signing.account,
+        clientId,
+        credential: signing.owner.credential!,
+        digest: KeyAuthorization.digest({ key }),
+        userId: session.user.id,
+      }),
+      'Passkey.requestSignature',
+    )
+
+  const signed = await Timing.measure(
+    c,
+    KeySigner.sign(c, {
+      account: signing.account,
+      // A server signer ignores the assertion of a one-tap sign-in by another passkey.
+      assertion: signing.owner.signer ? undefined : assertion,
+      clientId,
+      key,
+      owner: signing.owner,
+      userId: session.user.id,
+    }),
+    'KeySigner.sign',
+  )
+  if (signed instanceof ErrorResponse.ResponseError) return signed
+  return {
+    account: signing.account,
+    clientId,
+    // `checkKey` refuses a request without a challenge.
+    codeChallenge: codeChallenge!,
+    expiry: key.expiry,
+    signed,
+  }
+}
+
+declare namespace approveKey {
+  type Options = {
+    /** The account that the approval page showed, if any. */
+    account: `0x${string}` | undefined
+    /** The passkey's assertion over the passkey step's options, if any. */
+    assertion: Passkey.Assertion | undefined
+    /** A passkey sign-in whose assertion signed the key's digest, if any. */
+    oneTap: OneTap | undefined
+    /** The approved authorization request, whose signature Better Auth verified. */
+    query: URLSearchParams
+    /** The signed-in session. */
+    session: Session
+    /** Whether a user who holds several accounts and chose none is refused. */
+    single: boolean | undefined
+  }
+}

package/src/api/lib/Cors.ts

@@ -0,0 +1,107 @@
+/**
+ * The CORS policies of the root app. First-party apps call `/v1/*` from their own pages with the
+ * session cookie, and any page calls the OAuth endpoints that a client authenticates without a
+ * cookie, such as the token endpoint.
+ * @module
+ */
+import type { Context } from 'hono'
+import { cors } from 'hono/cors'
+import { createMiddleware } from 'hono/factory'
+import { env } from 'void/env'
+import * as Apps from '../../internal/Apps.js'
+import type { Env } from '../../internal/Env.js'
+import * as ErrorResponse from '../../internal/ErrorResponse.js'
+import * as RateLimit from '../../internal/RateLimit.js'
+import * as RequestId from '../../internal/RequestId.js'
+import * as Timing from '../../internal/Timing.js'
+import { db } from './Database.js'
+
+/** The response headers outside the CORS safelist that apps read. */
+const exposeHeaders = [...RateLimit.headers, RequestId.header]
+
+/**
+ * The `/v1` routes that an app's page calls. The routes behind Tempo ID's own pages, such as
+ * `/v1/authorize/consent` and `/v1/authorize/account`, stay off the list, so only those pages
+ * decide consent and the account step.
+ */
+const paths = new Set([
+  '/v1/account',
+  '/v1/auth/code',
+  '/v1/auth/code/verify',
+  '/v1/auth/logout',
+  '/v1/auth/passkey/options',
+  '/v1/auth/passkey/verify',
+  '/v1/auth/providers',
+  '/v1/auth/session',
+  '/v1/authorize',
+  '/v1/realms',
+])
+
+/**
+ * Returns the `Origin` of a request from a page other than Tempo ID's own, such as a first-party
+ * app's page, or `undefined` for Tempo ID's own page and for a request without `Origin`.
+ */
+export function appOrigin(c: Context<Env>) {
+  const origin = c.req.header('origin')
+  if (!origin) return undefined
+  // Tempo ID's pages send the origin they load from: `URL`, or the request's own origin where Tempo
+  // ID serves at another address, such as a test harness.
+  if ([new URL(env.URL).origin, new URL(c.req.url).origin].includes(origin))
+    return undefined
+  return origin
+}
+
+/**
+ * Grants credentialed CORS on the `/v1` routes that an app's page calls, to the origin of a
+ * redirect URI of an enabled first-party app, one that skips consent, and to no other origin. A
+ * request without an `Origin`, from Tempo ID's own origin, or to another route, passes through
+ * unchanged.
+ */
+export const firstParty = createMiddleware<Env>((c, next) => {
+  if (!paths.has(c.req.path)) return next()
+  return cors({
+    credentials: true,
+    exposeHeaders,
+    origin: async (origin) => {
+      if (!origin || origin === new URL(env.URL).origin) return null
+      const allowed = await Timing.measure(
+        c,
+        Apps.firstPartyOrigin(db, { origin }),
+        'Apps.firstPartyOrigin',
+      )
+      return allowed ? origin : null
+    },
+  })(c, next)
+})
+
+/**
+ * Grants CORS without credentials to every origin, for the discovery documents, the JWKS, and the
+ * OAuth endpoints that read no cookie. Each of those endpoints requires its own credential, such
+ * as a code with its PKCE verifier, a client secret, or a Bearer token. The documents and the JWKS
+ * are public.
+ */
+export const oauth = cors({ exposeHeaders })
+
+/**
+ * Refuses a request that continues an app's authorization request with `oauth_query` from an origin
+ * other than Tempo ID's own, or the request's own. Only Tempo ID's pages continue one, so a first-party app's page, which
+ * CORS admits, cannot sign the user in to another app or approve its request. A request without an
+ * `Origin` comes from no browser page, which sends no other user's session cookie.
+ */
+export function ownPage(
+  c: Context<Env>,
+  options: ownPage.Options,
+): ErrorResponse.Instance<typeof ownPage.errors> | undefined {
+  if (!options.oauth_query || !appOrigin(c)) return undefined
+  return new ErrorResponse.CrossSiteRequestError()
+}
+
+export namespace ownPage {
+  export type Options = {
+    /** The query string of the authorization request that the request continues, if any. */
+    oauth_query?: string | undefined
+  }
+
+  /** The refusals `ownPage` returns. Its return type admits no other. */
+  export const errors = [ErrorResponse.CrossSiteRequestError] as const
+}

package/src/api/lib/Database.ts

@@ -0,0 +1,10 @@
+/**
+ * Void's database client, typed for Tempo ID's Postgres tables. Void writes the Postgres type of
+ * `void/db` to `.void/db.d.ts`, which `tsc` excludes as generated, so `tsc` reads Void's D1 default.
+ * @module
+ */
+import { db as client } from 'void/db'
+import type * as Realm from '../../internal/Realm.js'
+
+/** The request's Drizzle client, which Void connects through Hyperdrive or `DATABASE_URL`. */
+export const db = client as unknown as Realm.Database