@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/lib/PasskeyLink.ts

@@ -0,0 +1,162 @@
+/**
+ * The link cookie, which holds a verified wallet.tempo passkey without an email until an emailed
+ * code names its user. Only the code sign-in that sends back the email step's nonce, with an
+ * assertion of the same passkey, links it. A cookie left in a shared browser thus links nothing for
+ * the next person.
+ * @module
+ */
+import type { Context } from 'hono'
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import { Base64, Hex } from 'ox'
+import { env } from 'void/env'
+import type { Env } from '../../internal/Env.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as Timing from '../../internal/Timing.js'
+import type * as Wallet from '../../internal/Wallet.js'
+
+/** Workers' `crypto.subtle`, whose `timingSafeEqual` the project's Node types leave out. */
+type Subtle = SubtleCrypto & {
+  timingSafeEqual(a: ArrayBuffer, b: ArrayBuffer): boolean
+}
+
+/** The cookie's name, which the `__Host-` prefix pins to the host that set it with `Path=/`. */
+const name = 'tempo-id-passkey-link'
+
+/** The prefix that `hono/cookie` adds, `__Host-`. */
+const prefix = 'host'
+
+/**
+ * Returns the deferred passkey that the link cookie holds for `nonce`, or `undefined` when there is
+ * none, or the cookie or the nonce does not match. The cookie stays until `release`, so a failed
+ * write can retry.
+ */
+export async function claim(c: Context<Env>, options: claim.Options) {
+  const sealed = getCookie(c, name, prefix)
+  if (!sealed) return undefined
+
+  const link = await Timing.measure(
+    c,
+    Passkey.unseal(sealed, {
+      host: new URL(c.req.url).host,
+      secret: env.SECRET,
+    }),
+    'Passkey.unseal',
+  )
+  if (!link) return undefined
+
+  // The nonce is a secret, so it is compared in constant time, through hashes of equal length.
+  const [expected, received] = await Timing.measure(
+    c,
+    Promise.all(
+      [link.nonce, options.nonce].map((value) =>
+        crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)),
+      ),
+    ),
+    'crypto.digest',
+  )
+  return (crypto.subtle as Subtle).timingSafeEqual(expected!, received!)
+    ? link
+    : undefined
+}
+
+export declare namespace claim {
+  type Options = {
+    /** The nonce from the email step, which the code sign-in sent back. */
+    nonce: string
+  }
+}
+
+/**
+ * Seals a verified wallet.tempo passkey in the link cookie for 5 minutes, and returns the nonce
+ * that the email step carries.
+ */
+export async function defer(c: Context<Env>, options: defer.Options) {
+  const nonce = Base64.fromBytes(crypto.getRandomValues(new Uint8Array(32)), {
+    pad: false,
+    url: true,
+  })
+  const sealed = await Timing.measure(
+    c,
+    Passkey.seal(
+      {
+        address: options.credential.address,
+        createdAt: options.credential.createdAt,
+        expiresAt: Math.floor(Date.now() / 1000) + Passkey.linkLifetime,
+        host: new URL(c.req.url).host,
+        id: options.id,
+        nonce,
+        publicKey: options.credential.publicKey,
+        rpId: options.rpId,
+      },
+      { secret: env.SECRET },
+    ),
+    'Passkey.seal',
+  )
+  setCookie(c, name, sealed, {
+    httpOnly: true,
+    maxAge: Passkey.linkLifetime,
+    path: '/',
+    prefix,
+    sameSite: 'Lax',
+    secure: true,
+  })
+  return nonce
+}
+
+export declare namespace defer {
+  type Options = {
+    /** The passkey that wallet.tempo returned, which the assertion verified. */
+    credential: Wallet.Credential
+    /** The credential ID, base64url. */
+    id: string
+    /** The relying party the challenge was issued for. */
+    rpId: string
+  }
+}
+
+/**
+ * Returns the SHA-256 digest of the email step's `nonce`, as hex. A challenge for the link stores
+ * the digest, since the nonce is a secret.
+ */
+export async function digest(options: digest.Options) {
+  const bytes = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(options.nonce),
+  )
+  return Hex.fromBytes(new Uint8Array(bytes))
+}
+
+export declare namespace digest {
+  type Options = {
+    /** The nonce from the email step. */
+    nonce: string
+  }
+}
+
+/**
+ * Returns whether the challenge digest `expected` is the digest of `nonce`, compared in constant
+ * time.
+ */
+export async function matches(options: matches.Options) {
+  if (!options.expected) return false
+  const received = await digest({ nonce: options.nonce })
+  if (received.length !== options.expected.length) return false
+  return (crypto.subtle as Subtle).timingSafeEqual(
+    Hex.toBytes(received as Hex.Hex).buffer as ArrayBuffer,
+    Hex.toBytes(options.expected as Hex.Hex).buffer as ArrayBuffer,
+  )
+}
+
+export declare namespace matches {
+  type Options = {
+    /** The digest that the challenge stores, or `undefined` for a sign-in challenge. */
+    expected: string | undefined
+    /** The nonce that the code sign-in sent back. */
+    nonce: string
+  }
+}
+
+/** Clears the link cookie. */
+export function release(c: Context<Env>) {
+  deleteCookie(c, name, { path: '/', prefix, secure: true })
+}

package/src/api/lib/Session.ts

@@ -0,0 +1,64 @@
+/**
+ * Reads the request's session, and forwards the cookie that Better Auth reissues when it extends the
+ * session, so the browser keeps the session as long as the database does. Reads the session token
+ * and expires the session cookies for logout.
+ * @module
+ */
+import type * as Hono from 'hono'
+import { getSignedCookie } from 'hono/cookie'
+import type { Env } from '../../internal/Env.js'
+import * as Timing from '../../internal/Timing.js'
+
+/**
+ * Sets the cookies that expire the session cookies on the response of `c`. Without the session
+ * cookie, Better Auth's sign-out reads and deletes nothing, so it makes no database call.
+ */
+export async function clear(c: Hono.Context<Env>) {
+  const result = await Timing.measure(
+    c,
+    c.var.auth.api.signOut({ headers: new Headers(), returnHeaders: true }),
+    'auth.signOut',
+  )
+  for (const cookie of result.headers.getSetCookie())
+    c.header('set-cookie', cookie, { append: true })
+}
+
+/**
+ * Returns the request's session, or `null` without one. Better Auth extends a session that is older
+ * than a day, and the extended cookie goes on the response.
+ */
+export async function get(c: get.Context) {
+  const result = await Timing.measure(
+    c,
+    c.var.auth.api.getSession({
+      headers: c.req.raw.headers,
+      returnHeaders: true,
+    }),
+    'auth.getSession',
+  )
+  for (const cookie of result.headers.getSetCookie())
+    c.header('set-cookie', cookie, { append: true })
+  return result.response
+}
+
+export declare namespace get {
+  /** A context that carries the request's Better Auth instance and timing, such as a page loader's. */
+  type Context = Pick<Hono.Context<Env>, 'header' | 'req'> & {
+    /** The request's variables. */
+    var: Pick<Env['Variables'], 'auth' | 'timing'>
+  }
+}
+
+/**
+ * Returns the session token in the signed session cookie of `c`, or `undefined` without the cookie
+ * or when its signature does not verify. It makes no database call.
+ */
+export async function token(c: Hono.Context<Env>) {
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const value = await Timing.measure(
+    c,
+    getSignedCookie(c, context.secret, context.authCookies.sessionToken.name),
+    'cookie.verify',
+  )
+  return value || undefined
+}

package/src/api/lib/SignInConsent.ts

@@ -0,0 +1,393 @@
+/**
+ * Grants the key of an app's authorization request when a sign-in on the sign-in page continues it.
+ * The sign-in page shows the request's key before the sign-in, so the sign-in approves it, as the
+ * approval page does. A key that the sign-in cannot sign, such as one that another passkey owns,
+ * keeps the redirect to the approval page. A sign-in that reaches the account step holds its grant
+ * until the user chooses an account. A chosen account that a passkey owns takes the passkey step on
+ * the account step, which signs the key without the approval page.
+ * @module
+ */
+import { verifyOAuthQueryParams } from '@better-auth/oauth-provider'
+import type { Context } from 'hono'
+import { Hex } from 'ox'
+import { env } from 'void/env'
+import * as Apps from '../../internal/Apps.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 Log from '../../internal/Log.js'
+import * as Passkey from '../../internal/Passkey.js'
+import * as RateLimit from '../../internal/RateLimit.js'
+import * as SignInGrant from '../../internal/SignInGrant.js'
+import * as Timing from '../../internal/Timing.js'
+import * as Consent from './Consent.js'
+import { db } from './Database.js'
+
+/**
+ * Returns where an account step continues: `redirect`, which Better Auth returned once the user chose
+ * `account`, or the app's `redirect_uri` with a code when a sign-in held a grant for the request and
+ * the session. The grant is taken once. An account that a passkey owns returns the passkey step
+ * instead, and holds the grant again for the repeated selection, whose `assertion` signs the key.
+ */
+export async function afterAccountStep(
+  c: Context<Env>,
+  options: afterAccountStep.Options,
+): Promise<afterAccountStep.ReturnType> {
+  // The account step already stored the choice, so an unexpected failure keeps its redirect.
+  return await Timing.measure(
+    c,
+    accountStep(c, options),
+    'SignInConsent.accountStep',
+  ).catch((error: unknown) => {
+    Log.warn(c, {
+      error,
+      message: 'An account step kept its redirect, since its grant failed.',
+    })
+    return { redirect: options.redirect }
+  })
+}
+
+export declare namespace afterAccountStep {
+  type Options = {
+    /** The account that the user chose on the account step. */
+    account: `0x${string}`
+    /** The passkey's assertion over the options of the passkey step, for a repeated selection. */
+    assertion?: Passkey.Assertion | undefined
+    /** The request headers, with the account step's selection in the cookie. */
+    headers: Headers
+    /** The redirect that Better Auth returned once the user chose the account. */
+    redirect: string
+    /** The signed-in session. */
+    session: Consent.Session
+  }
+
+  type ReturnType = grant.ReturnType
+}
+
+/**
+ * Returns where a sign-in continues: `redirect`, which Better Auth returned for the app's
+ * authorization request, or the app's `redirect_uri` with a code once the sign-in grants the
+ * request's key. Only a redirect to the approval page or to the account step, for a request with a
+ * key and without a `challenge`, grants anything, and only for the first sign-in of that request.
+ * `setCookie` holds the `Set-Cookie` headers of the sign-in, which carry the new session.
+ */
+export async function afterSignIn(
+  c: Context<Env>,
+  options: afterSignIn.Options,
+): Promise<string> {
+  // Better Auth already created the session, so an unexpected failure keeps the sign-in's redirect.
+  return await Timing.measure(
+    c,
+    signIn(c, options),
+    'SignInConsent.signIn',
+  ).catch((error: unknown) => {
+    Log.warn(c, {
+      error,
+      message: 'A sign-in kept its redirect, since its grant failed.',
+    })
+    return options.redirect
+  })
+}
+
+export declare namespace afterSignIn {
+  type Options = {
+    /**
+     * The assertion and witness of the sign-in with key signature, for a passkey sign-in whose
+     * challenge was the key's digest.
+     */
+    keySignature?: Consent.KeySignature | undefined
+    /** The redirect that Better Auth returned for the continued authorization request. */
+    redirect: string
+    /** The `Set-Cookie` headers of the sign-in, which carry the new session. */
+    setCookie: readonly string[]
+  }
+}
+
+/**
+ * Returns the challenge of a sign-in with key signature for the sign-in page's `oauthQuery`: the
+ * digest of the request's key with a random witness, and that witness. Returns `undefined` for a
+ * forged or expired query, a request without a key, a request with a `challenge`, a request that a
+ * sign-in already spent, and a third-party app's request, whose sign-in takes a random challenge.
+ */
+export async function keyChallenge(
+  c: Context<Env>,
+  options: keyChallenge.Options,
+): Promise<keyChallenge.ReturnType | undefined> {
+  const query = new URLSearchParams(options.oauthQuery)
+  // Only the approval page grants a third-party app's key, so no passkey signs it here.
+  if (
+    !query.has('key_authorization') ||
+    query.has('challenge') ||
+    Apps.thirdParty(query.get('client_id') ?? '')
+  )
+    return undefined
+
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const verified = await Timing.measure(
+    c,
+    verifyOAuthQueryParams(options.oauthQuery, context.secret),
+    'auth.verifyOAuthQueryParams',
+  )
+  if (!verified) return undefined
+  // A spent request grants nothing at sign-in, so its sign-in takes a random challenge.
+  const spent = await Timing.measure(
+    c,
+    SignInGrant.spent(db, { query }),
+    'SignInGrant.spent',
+  )
+  if (spent) return undefined
+
+  const key = Authorize.fromQuery(query)
+  if (!key || key instanceof ErrorResponse.ResponseError) return undefined
+  const witness = Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32)))
+  return {
+    digest: KeyAuthorization.digest({ key: { ...key, witness } }),
+    witness,
+  }
+}
+
+export declare namespace keyChallenge {
+  type Options = {
+    /** The sign-in page's query string, which Better Auth signed. */
+    oauthQuery: string
+  }
+
+  type ReturnType = {
+    /** The digest of the request's key with `witness`, which the passkey signs as its challenge. */
+    digest: Hex.Hex
+    /** The random witness that the digest binds. */
+    witness: Hex.Hex
+  }
+}
+
+/** Continues an account step for {@link afterAccountStep}, which catches its failures. */
+async function accountStep(
+  c: Context<Env>,
+  options: afterAccountStep.Options,
+): Promise<afterAccountStep.ReturnType> {
+  const { account, assertion, headers, redirect, session } = options
+  const url = URL.parse(redirect, env.URL)
+  if (
+    !url ||
+    url.origin !== new URL(env.URL).origin ||
+    url.pathname !== '/authorize'
+  )
+    return { redirect }
+  // A request with a challenge signs a message that only the approval page shows.
+  if (url.searchParams.has('challenge')) return { redirect }
+
+  const held = await Timing.measure(
+    c,
+    SignInGrant.take(db, {
+      query: url.searchParams,
+      sessionId: session.session.id,
+    }),
+    'SignInGrant.take',
+  )
+  if (!held) return { redirect }
+  const keySignature = (() => {
+    const parsed = Passkey.schema.assertion.safeParse(held.assertion)
+    if (!parsed.success || !held.witness) return undefined
+    return { assertion: parsed.data, witness: held.witness }
+  })()
+  const granted = await grant(c, {
+    account,
+    assertion,
+    headers,
+    keySignature,
+    redirect,
+    session,
+    url,
+  })
+  // The chosen account's passkey signs only in the browser, so the grant waits for the repeated
+  // selection that carries its assertion.
+  if ('options' in granted)
+    await Timing.measure(
+      c,
+      SignInGrant.hold(db, {
+        keySignature: held.witness
+          ? { assertion: held.assertion, witness: held.witness }
+          : undefined,
+        query: url.searchParams,
+        sessionId: session.session.id,
+      }),
+      'SignInGrant.hold',
+    )
+  return granted
+}
+
+/**
+ * Approves the request of the approval page's `url`, and returns the app's redirect, or the options
+ * of the passkey step for an account that a passkey owns. A refusal or a spent rate limit keeps
+ * `redirect`, so the approval page shows the request.
+ */
+async function grant(
+  c: Context<Env>,
+  options: grant.Options,
+): Promise<grant.ReturnType> {
+  const { headers, redirect, session, url } = options
+  // A grant reads the user's accounts and calls Privy, as an approval does.
+  const limited = await Timing.measure(
+    c,
+    RateLimit.check(c, {
+      limits: [{ binding: 'AUTHORIZE_LIMIT', key: session.user.id }],
+    }),
+    'RateLimit.check',
+  )
+  if (limited) return { redirect }
+
+  const approved = await Timing.measure(
+    c,
+    Consent.approve(c, {
+      account: options.account,
+      assertion: options.assertion,
+      headers,
+      keySignature: options.keySignature,
+      oauthQuery: url.search.slice(1),
+      session,
+      // The sign-in page shows no account, so a user with several chooses one on a page that does.
+      single: true,
+    }),
+    'Consent.approve',
+  ).catch((error: unknown) => {
+    // An upstream failure, such as a Privy outage, keeps the approval page, which shows it.
+    Log.warn(c, {
+      error,
+      message:
+        'A sign-in could not grant the key that the sign-in page showed.',
+    })
+    return undefined
+  })
+  if (!approved || approved instanceof ErrorResponse.ResponseError)
+    return { redirect }
+  if ('options' in approved) return { options: approved.options }
+  return { redirect: approved.redirect }
+}
+
+declare namespace grant {
+  type Options = {
+    /** The account that the user chose on the account step, 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 assertion and witness of the sign-in with key signature, if the sign-in was one. */
+    keySignature: Consent.KeySignature | undefined
+    /** The redirect that keeps the approval page. */
+    redirect: string
+    /** The signed-in session. */
+    session: Consent.Session
+    /** The approval page's URL, whose query Better Auth signed. */
+    url: URL
+  }
+
+  type ReturnType =
+    | {
+        /** The options of the passkey step, which the account's passkey signs in the browser. */
+        options: Consent.PasskeyOptions
+      }
+    | {
+        /** Where the browser continues: the app's redirect, or the approval page. */
+        redirect: string
+      }
+}
+
+/**
+ * Returns the request's headers with the cookies of `setCookie` in its `Cookie` header, so Better
+ * Auth reads the session that a sign-in just created.
+ */
+export function sessionHeaders(
+  c: Context<Env>,
+  options: sessionHeaders.Options,
+) {
+  const cookies = new Map(
+    (c.req.header('cookie') ?? '')
+      .split(';')
+      .map((entry) => entry.trim())
+      .filter(Boolean)
+      .map((entry) => {
+        const index = entry.indexOf('=')
+        return [entry.slice(0, index), entry.slice(index + 1)] as const
+      }),
+  )
+  for (const header of options.setCookie) {
+    const [pair = ''] = header.split(';')
+    const index = pair.indexOf('=')
+    if (index > 0)
+      cookies.set(pair.slice(0, index).trim(), pair.slice(index + 1))
+  }
+  const headers = new Headers(c.req.raw.headers)
+  headers.set(
+    'cookie',
+    [...cookies].map(([name, value]) => `${name}=${value}`).join('; '),
+  )
+  return headers
+}
+
+export declare namespace sessionHeaders {
+  type Options = {
+    /** The `Set-Cookie` headers of the sign-in. */
+    setCookie: readonly string[]
+  }
+}
+
+/** Continues a sign-in for {@link afterSignIn}, which catches its failures. */
+async function signIn(
+  c: Context<Env>,
+  options: afterSignIn.Options,
+): Promise<string> {
+  const { keySignature, redirect, setCookie } = options
+  const url = URL.parse(redirect, env.URL)
+  if (!url || url.origin !== new URL(env.URL).origin) return redirect
+  if (url.pathname !== '/authorize' && url.pathname !== '/choose-account')
+    return redirect
+  const query = url.searchParams
+  // A request with a challenge signs a message that only the approval page shows. A third-party app
+  // names itself, so only the approval page, which shows the host that serves its metadata
+  // document, grants its key.
+  if (
+    !query.has('key_authorization') ||
+    query.has('challenge') ||
+    Apps.thirdParty(query.get('client_id') ?? '')
+  )
+    return redirect
+
+  const headers = sessionHeaders(c, { setCookie })
+  // The sign-in created the session in this request, so the session needs no read.
+  const session = c.var.newSession
+  if (!session) return redirect
+
+  // A replayed request grants nothing, so its sign-in opens the approval page.
+  const spent = await Timing.measure(
+    c,
+    SignInGrant.spend(db, { query }),
+    'SignInGrant.spend',
+  )
+  if (!spent) return redirect
+
+  if (url.pathname === '/choose-account') {
+    await Timing.measure(
+      c,
+      SignInGrant.hold(db, {
+        keySignature,
+        query,
+        sessionId: session.session.id,
+      }),
+      'SignInGrant.hold',
+    )
+    return redirect
+  }
+
+  // The sign-in page runs no passkey step, so an account that another passkey owns keeps the
+  // approval page.
+  const granted = await grant(c, {
+    headers,
+    keySignature,
+    redirect,
+    session,
+    url,
+  })
+  return 'options' in granted ? redirect : granted.redirect
+}