@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/Consent.ts

@@ -0,0 +1,388 @@
+/**
+ * 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 Owner from '../../internal/Owner.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 `keySignature` holds an assertion of that passkey over the key's digest.
+ * With `skipUpgrade`, a wallet.tempo passkey whose wallet waits for its upgrade signs as its own
+ * account, and a passkey of the user's email that has not linked links once its assertion verifies.
+ * 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,
+          email: options.email,
+          keySignature: options.keySignature,
+          query,
+          session,
+          single: options.single,
+          skipUpgrade: options.skipUpgrade,
+        }),
+        '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 signed-in user's verified email, when the caller holds it. `skipUpgrade` reads it, and so
+     * does the creation of a first account, which reads it from the database otherwise.
+     */
+    email?: string | undefined
+    /** The request headers, with the cookie of the signed-in session. */
+    headers: Headers
+    /** A passkey sign-in whose assertion signed the key's digest, if any. */
+    keySignature?: KeySignature | undefined
+    /** The signed query string of the approved authorization request. */
+    oauthQuery: string
+    /** 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
+    /**
+     * Whether the user skipped the upgrade of the wallet.tempo passkey's wallet that the key waits
+     * for, as `KeySigner.resolve` reads it. With `email`, a passkey of that email that has not
+     * linked then signs too, as `KeySigner.unlinked` returns it. Defaults to `false`.
+     */
+    skipUpgrade?: 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,
+    ...KeySigner.unlinked.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 KeySignature = {
+  /** 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()`. */
+export 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
+ * `keySignature` when that passkey owns the account. Without either, it returns the options of the
+ * passkey step. With `skipUpgrade`, a user who holds no account signs with a wallet.tempo passkey of
+ * their email that has not linked, which links once its assertion verifies. 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 { keySignature, 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,
+    query,
+  })
+  if (refused) return refused
+
+  const resolved = await Timing.measure(
+    c,
+    KeySigner.resolve(c, {
+      account: requested.account ?? options.account,
+      chainId: requested.chainId,
+      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,
+      email: options.email,
+      // The approval page runs the passkey step.
+      passkey: true,
+      sessionId: session.session.id,
+      single: options.single,
+      skipUpgrade: options.skipUpgrade,
+      userId: session.user.id,
+    }),
+    'KeySigner.resolve',
+  )
+  // A user who holds no account and skips the upgrade signs with the passkey of their email that the
+  // upgrade would link. The repeated approval names that passkey through its assertion.
+  const email =
+    options.skipUpgrade && resolved instanceof Authorize.RejectedError
+      ? options.email
+      : undefined
+  const unlinked =
+    email === undefined
+      ? undefined
+      : await Timing.measure(
+          c,
+          KeySigner.unlinked(c, {
+            clientId,
+            credentialId: options.assertion?.id,
+            email,
+            userId: session.user.id,
+          }),
+          'KeySigner.unlinked',
+        )
+  const signing = (() => {
+    if (unlinked) return unlinked
+    // An assertion of any other passkey verifies nothing.
+    if (email !== undefined && options.assertion)
+      return new Passkey.WebAuthnRejectedError()
+    return resolved
+  })()
+  // 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 sign-in with key signature signs only for the account that its own passkey owns. Its digest
+  // binds the sign-in's witness, so the key carries that witness. A configurable account's owners
+  // sign its digest, which the sign-in's assertion does not sign.
+  const tapped =
+    keySignature &&
+    !Owner.configured(signing.owner) &&
+    signing.owner.credential?.id === keySignature.assertion.id
+      ? keySignature
+      : 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',
+      ),
+    }
+
+  const signed = await Timing.measure(
+    c,
+    KeySigner.sign(c, {
+      account: signing.account,
+      // A server signer ignores the assertion of a sign-in with key signature by another passkey.
+      assertion: signing.owner.signer ? undefined : assertion,
+      // The sign-in already spent its own challenge, which was the key's digest.
+      challenge: tapped ? 'sign-in' : 'stored',
+      clientId,
+      key,
+      owner: signing.owner,
+      userId: session.user.id,
+    }),
+    'KeySigner.sign',
+  )
+  if (signed instanceof ErrorResponse.ResponseError) return signed
+
+  // The assertion over the key proved that the user holds the passkey, so it links before the code
+  // issues.
+  const linked = unlinked
+    ? await Timing.measure(c, unlinked.link(), 'KeySigner.link')
+    : undefined
+  if (linked) return linked
+  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
+    /** The signed-in user's verified email, if the caller holds it. */
+    email: string | undefined
+    /** A passkey sign-in whose assertion signed the key's digest, if any. */
+    keySignature: KeySignature | 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
+    /** Whether the user skipped the upgrade that the key waits for. */
+    skipUpgrade: boolean | undefined
+  }
+}

package/src/api/lib/Cors.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 * as Cache from '../../internal/Cache.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'
+import * as Headless from './Headless.js'
+
+/** The response headers outside the CORS safelist that apps read. */
+const exposeHeaders = [...RateLimit.headers, RequestId.header]
+
+/**
+ * How long a browser caches a granted preflight, in seconds. Chromium caps it at 7200. A cached
+ * preflight skips the grant, so `firstParty` refuses each write from an origin without one.
+ */
+const maxAge = 7200
+
+/**
+ * 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/account/upgrade',
+  '/v1/auth/code',
+  '/v1/auth/code/verify',
+  '/v1/auth/logout',
+  '/v1/auth/passkey/options',
+  '/v1/auth/passkey/verify',
+  '/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. Any
+ * other origin's write is refused with `cross_site_request`, since a cached preflight lets it
+ * through. A request without an `Origin`, from Tempo ID's own origin, or to another route, passes
+ * through unchanged.
+ */
+export const firstParty = createMiddleware<Env>(async (c, next) => {
+  if (!paths.has(c.req.path)) return next()
+
+  const origin = appOrigin(c)
+  const write = !['GET', 'HEAD', 'OPTIONS'].includes(c.req.method)
+  const allowed =
+    origin !== undefined &&
+    (await Timing.measure(
+      c,
+      (async () => {
+        // A write reads the app rows again, so a disabled app's origin is refused at its next
+        // write. The route reads the matched apps from `c.var.firstParty`, so it reads no app
+        // again. A read takes only a cached match, so a new app's origin is first-party at once.
+        if (write) {
+          const apps = await Apps.firstPartyOrigin(db, { origin })
+          c.set('firstParty', apps)
+          return apps.length > 0
+        }
+        return await Cache.read(
+          c,
+          async () => (await Apps.firstPartyOrigin(db, { origin })).length > 0,
+          ['apps.firstPartyOrigin', origin],
+          { keep: (matches) => matches },
+        )
+      })(),
+      'Apps.firstPartyOrigin',
+    ))
+  if (origin && !allowed && write)
+    return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+
+  return cors({
+    credentials: true,
+    // The page of a sign-in with key signature reads whether a refusal came after the sign-in.
+    exposeHeaders: [...exposeHeaders, Headless.signedInHeader],
+    maxAge,
+    origin: () => (allowed ? origin : null),
+  })(c, next)
+})
+
+/**
+ * Grants CORS without credentials to every origin, for the discovery documents, the JWKS, the chain
+ * list, the sign-in page's assets, 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, the JWKS, the chain list, and the assets are public.
+ */
+export const oauth = cors({ exposeHeaders })
+
+/**
+ * Refuses a request to an internal route from anything but Tempo ID's own page: a request whose
+ * `Sec-Fetch-Site` is not `same-origin`, which covers first-party apps that CORS admits. Without
+ * the header, as from a browser without Fetch Metadata such as Safari before 16.4, the request
+ * needs Tempo ID's own `Origin`, so a request from no browser page is refused. A caller that sets
+ * either header itself also holds the user's session cookie, so it acts as the user.
+ */
+export function internal(
+  c: Context<Env>,
+): ErrorResponse.Instance<typeof internal.errors> | undefined {
+  const site = c.req.header('sec-fetch-site')
+  if (site === 'same-origin') return undefined
+  if (site === undefined && c.req.header('origin') && !appOrigin(c))
+    return undefined
+  return new ErrorResponse.CrossSiteRequestError()
+}
+
+export namespace internal {
+  /** The refusals `internal` returns. Its return type admits no other. */
+  export const errors = [ErrorResponse.CrossSiteRequestError] as const
+}
+
+/**
+ * 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