@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/actions/redirect.ts

@@ -0,0 +1,502 @@
+/**
+ * Signs the user in on Tempo ID's pages, which redirect back with a code. `start` and `complete`
+ * keep the redirect's state in `storage`, and, with the default storage, its PKCE verifier in the
+ * tab's `sessionStorage` too. `createUrl` and `handleCallback` leave it to the app.
+ * @module
+ */
+import { Base64, Bytes, Hash } from 'ox'
+import type { Account } from 'viem/tempo'
+import { type Auth, ChallengeWithoutKeyError, RequestError } from '../Auth.js'
+import type { Authorization } from '../Authorization.js'
+import * as AccessKey from '../internal/accessKey.js'
+import * as Api from '../internal/api.js'
+import { keyAuthorization } from '../internal/request.js'
+import * as Store from '../internal/store.js'
+import * as Verifier from '../internal/verifier.js'
+import * as Pending from '../Pending.js'
+import type { Permissions } from '../Permissions.js'
+
+/** `complete` received a `key` other than the one that `start` received. */
+export class KeyMismatchError extends Error {
+  override readonly name = 'Actions.redirect.KeyMismatchError'
+
+  constructor(options: { stored: boolean }) {
+    super(
+      options.stored
+        ? 'The redirect authorized a key, but `complete` received `key: false`. Pass the `key` that `start` received.'
+        : 'The redirect authorized no key, but `complete` did not receive `key: false`. Pass the `key` that `start` received.',
+    )
+  }
+}
+
+/**
+ * Finishes a {@link start} when the page loads with Tempo ID's callback, and returns `undefined`
+ * otherwise. It redeems the code once, however often the page calls it. With the default storage,
+ * it sends the code exchange at once, from the tab's copy of the verifier, before IndexedDB returns
+ * the rest of the redirect's state. A callback that denies the
+ * redirect, such as `error=access_denied`, throws a `RequestError` with that `code` and status 0.
+ *
+ * @example
+ * ```ts
+ * const authorization =
+ *   (await Actions.redirect.complete(auth)) ??
+ *   (await Actions.authorize(auth))
+ * ```
+ */
+export function complete<const key extends boolean = true>(
+  auth: Auth,
+  options: complete.Options<key> = {},
+): Promise<complete.ReturnType<key>> {
+  completed ??= (async () => {
+    const url = new URL(window.location.href)
+    // The tab's ticket starts the code exchange before the storage's first read, which waits behind
+    // the page's first tasks. It runs only for this page's own redirect, with the `key` it began
+    // with, so the checks below refuse nothing that it redeemed.
+    const ticket = Verifier.take(auth)
+    const early =
+      ticket &&
+      url.searchParams.has('code') &&
+      url.searchParams.get('state') === ticket.state &&
+      ticket.key === (options.key !== false)
+        ? redeem(auth, { pending: ticket, url })
+        : undefined
+    // A refusal surfaces from the await below, after the checks of the stored redirect.
+    early?.catch(() => undefined)
+    const store = Store.get(auth)!
+    const stored = (await store.getItem(storageKey)) as
+      | Pending.Pending
+      | Pending.WithoutKey
+      | null
+      | undefined
+    // A registered redirect URI may hold its own `error`, which the app keeps. Only an `error` that
+    // the callback added after it belongs to the authorization response.
+    const redirectUri = stored?.redirectUri ?? url.origin
+    const registered = new URL(redirectUri).searchParams
+    const added = (name: string) => response(url, { name, redirectUri })
+    // A custom `storage` may return `null` for a missing item.
+    const ours =
+      stored != null && url.searchParams.get('state') === stored.state
+    // The result's type follows `key`, so a redirect that `start` began with another `key` fails. The
+    // state and the URL stay, so a page load that passes the right `key` finishes the redirect.
+    if (
+      ours &&
+      url.searchParams.has('code') &&
+      (stored.key === false) !== (options.key === false)
+    )
+      throw new KeyMismatchError({ stored: stored.key !== false })
+
+    await store.removeItem(storageKey)
+    // The app keeps its own query and fragment, without the callback's parameters. A code this page
+    // did not request is dropped too, since it redeems for whoever crafted its request. A page that is
+    // no callback of this page keeps its own `state` and `error` parameters.
+    const callback = [
+      'code',
+      'error',
+      'error_description',
+      'error_uri',
+      'state',
+    ]
+    if (ours || url.searchParams.has('code')) {
+      const clean = new URL(url)
+      for (const name of callback) {
+        clean.searchParams.delete(name)
+        for (const value of registered.getAll(name))
+          clean.searchParams.append(name, value)
+      }
+      window.history.replaceState(
+        null,
+        '',
+        clean.pathname + clean.search + clean.hash,
+      )
+    }
+
+    // A denial of this page's redirect throws, so the app never mistakes it for a page load
+    // without a callback and authorizes another way.
+    const error = added('error')
+    if (ours && error)
+      throw new RequestError({
+        code: error,
+        message: added('error_description') ?? error,
+        status: 0,
+        uri: added('error_uri'),
+      })
+    if (!url.searchParams.has('code') || !stored) return undefined
+    return finish({
+      accessKey: options.accessKey,
+      body: await (ours && early
+        ? early
+        : redeem(auth, { pending: stored, url })),
+      pending: stored,
+    })
+  })()
+  // The check above holds the stored redirect to `key`, which types the result.
+  return completed as Promise<complete.ReturnType<key>>
+}
+
+export declare namespace complete {
+  type Options<key extends boolean = true> = {
+    /** The key that the app passed to {@link start}, if any. */
+    accessKey?: Account.Account | undefined
+    /** Must equal `start`'s `key`, or {@link KeyMismatchError} throws. Defaults to `true`. */
+    key?: key | undefined
+  }
+
+  /** `undefined` when the page is not a redirect's callback. */
+  type ReturnType<key extends boolean = true> =
+    | (key extends false ? handleCallback.WithoutKey : Authorization)
+    | undefined
+}
+
+/**
+ * Returns the authorization URL, `/oauth2/authorize`, which redirects to Tempo ID's sign-in or
+ * approval page, and the `Pending` state to keep until the callback. {@link handleCallback} redeems
+ * the code.
+ *
+ * @example
+ * ```ts
+ * const { pending, url } = await Actions.redirect.createUrl(auth, {
+ *   redirectUri: 'https://app.example/auth/callback',
+ * })
+ * await seal(c, 'oauth', pending)
+ * return c.redirect(url)
+ * ```
+ */
+export async function createUrl<const key extends boolean = true>(
+  auth: Auth,
+  options: createUrl.Options<key> = {},
+): Promise<createUrl.ReturnType<key>> {
+  if (options.key === false && options.challenge !== undefined)
+    throw new ChallengeWithoutKeyError()
+  const redirectUri =
+    options.redirectUri ?? auth.redirectUri ?? `${window.location.origin}/`
+  const key =
+    options.key === false
+      ? undefined
+      : await AccessKey.resolve(options.accessKey)
+  const pending = Pending.from({
+    ...(key ? key.material : { key: false }),
+    redirectUri,
+    // `Bytes.random` needs only `crypto.getRandomValues`, which React Native polyfills.
+    state: Base64.fromBytes(Bytes.random(16), base64url),
+    verifier: Base64.fromBytes(Bytes.random(32), base64url),
+  })
+  const authorization = key
+    ? keyAuthorization(auth, {
+        accessKey: key.accessKey,
+        permissions: options.permissions,
+      })
+    : undefined
+  // The issuer's endpoint redirects to the sign-in page at once. `/authorize` redirects here first.
+  const url = new URL('/oauth2/authorize', auth.url)
+  url.search = new URLSearchParams({
+    ...(options.challenge === undefined
+      ? {}
+      : { challenge: options.challenge }),
+    client_id: auth.clientId,
+    code_challenge: Base64.fromBytes(
+      Hash.sha256(Bytes.fromString(pending.verifier)),
+      base64url,
+    ),
+    code_challenge_method: 'S256',
+    ...(authorization
+      ? {
+          key_authorization: Base64.fromString(
+            JSON.stringify(authorization),
+            base64url,
+          ),
+        }
+      : {}),
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: auth.scope,
+    state: pending.state,
+  }).toString()
+  // `options.key` decides both the type and the runtime value of `pending`.
+  return { pending, url: url.href } as createUrl.ReturnType<key>
+}
+
+export declare namespace createUrl {
+  type Options<key extends boolean = true> = {
+    /**
+     * The key to authorize. Defaults to a new key, whose material `pending` keeps. Its `access`
+     * names the Tempo Account, which defaults to the one the user selects, or the user's oldest.
+     */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message whose EIP-191 hash the key authorization binds as its `witness`. Needs the
+     * `tempo-id:sign` scope. With `key: false`, the call throws `Auth.ChallengeWithoutKeyError`.
+     */
+    challenge?: ([key] extends [false] ? never : string) | undefined
+    /** Whether the sign-in authorizes an access key. Defaults to `true`. */
+    key?: key | undefined
+    /** What the key may do. The user approves it, so it may exceed the headless ceiling. */
+    permissions?: Permissions | undefined
+    /** Defaults to the instance's `redirectUri`, or the page's origin. */
+    redirectUri?: string | undefined
+  }
+
+  type ReturnType<key extends boolean = true> = {
+    /** What to keep until the callback, such as in a sealed cookie. */
+    pending: key extends false ? Pending.WithoutKey : Pending.Pending
+    /** Where to send the browser. */
+    url: string
+  }
+}
+
+/**
+ * Checks the callback's `state`, and redeems its code for the authorization. Throws a
+ * `RequestError` for a forged `state`, a callback without a `code`, or a refused code.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.redirect.handleCallback(auth, {
+ *   pending: await unseal(c, 'oauth'),
+ *   url: c.req.url,
+ * })
+ * ```
+ */
+export async function handleCallback<
+  const pending extends Pending.Pending | Pending.WithoutKey = Pending.Pending,
+>(
+  auth: Auth,
+  options: handleCallback.Options<pending>,
+): Promise<handleCallback.ReturnType<pending>> {
+  return finish({
+    accessKey: options.accessKey,
+    body: await redeem(auth, {
+      pending: options.pending,
+      url: new URL(options.url),
+    }),
+    pending: options.pending,
+  }) as handleCallback.ReturnType<pending>
+}
+
+export declare namespace handleCallback {
+  type Options<
+    pending extends Pending.Pending | Pending.WithoutKey = Pending.Pending,
+  > = {
+    /** The key that the app passed to `createUrl`, if any. */
+    accessKey?: Account.Account | undefined
+    /** What `createUrl` returned to keep. */
+    pending: pending
+    /** The callback URL that Tempo ID redirected to. */
+    url: string | URL
+  }
+
+  /** The authorization, without its key for a `Pending.WithoutKey`. */
+  type ReturnType<
+    pending extends Pending.Pending | Pending.WithoutKey = Pending.Pending,
+  > = [pending] extends [Pending.WithoutKey]
+    ? WithoutKey
+    : [pending] extends [Pending.Pending]
+      ? Authorization
+      : Authorization | WithoutKey
+
+  /** A sign-in without a key: the tokens and the user. */
+  type WithoutKey = Omit<Authorization, 'account' | 'key'>
+}
+
+/**
+ * Checks the callback's `state`, and redeems its code with the verifier of `pending`. Throws a
+ * `RequestError` for a forged `state`, a callback without a `code`, or a refused code.
+ */
+async function redeem(auth: Auth, options: redeem.Options) {
+  const { redirectUri, state, verifier } = options.pending
+  const { url } = options
+  const added = (name: string) => response(url, { name, redirectUri })
+  // State comes first, so a forged link cannot supply the error an app shows.
+  if (url.searchParams.get('state') !== state)
+    throw new RequestError({
+      code: 'invalid_request',
+      field: 'state',
+      message:
+        'Invalid `state` in the callback URL. Start sign-in again from this app.',
+      status: 400,
+    })
+  const code = url.searchParams.get('code')
+  if (!code)
+    throw new RequestError({
+      code: added('error') ?? 'invalid_request',
+      field: 'code',
+      message:
+        added('error_description') ??
+        'Missing `code` in the callback URL. Start sign-in again.',
+      status: 400,
+    })
+
+  return await Api.token(auth, {
+    code,
+    code_verifier: verifier,
+    grant_type: 'authorization_code',
+    redirect_uri: redirectUri,
+  })
+}
+
+declare namespace redeem {
+  type Options = {
+    /** The redirect's state, of which the exchange reads `redirectUri`, `state`, and `verifier`. */
+    pending: Pick<Pending.Pending, 'redirectUri' | 'state' | 'verifier'>
+    /** The callback URL that Tempo ID redirected to. */
+    url: URL
+  }
+}
+
+/**
+ * Returns the authorization of a redeemed code, with the key of `pending`, or the tokens and the
+ * user for a `Pending.WithoutKey`. Throws a `RequestError` when a redirect with a key receives no
+ * key authorization.
+ */
+function finish(
+  options: finish.Options,
+): Authorization | handleCallback.WithoutKey {
+  const { body } = options
+  // The exchange's fields stay out of the key's material.
+  const {
+    key,
+    redirectUri: _redirectUri,
+    state: _state,
+    verifier: _verifier,
+    ...material
+  } = options.pending
+  // `pending.key` decides both the type and the runtime value of the result.
+  if (key === false) {
+    const tokens = Api.tokens(body)
+    return { ...tokens, user: Api.user(tokens) }
+  }
+  if (!body.account || !body.key_authorization)
+    throw new RequestError({
+      code: 'invalid_grant',
+      message:
+        'Missing key authorization in the token response. The code was already redeemed, or did not request a key. Start sign-in again.',
+      status: 400,
+    })
+  return Api.authorization(
+    {
+      account: body.account,
+      key_authorization: body.key_authorization,
+      tokens: body,
+    },
+    { accessKey: options.accessKey, material },
+  )
+}
+
+declare namespace finish {
+  type Options = {
+    /** The key that the app passed to `createUrl`, if any. */
+    accessKey?: Account.Account | undefined
+    /** The token response of the redeemed code. */
+    body: Api.TokenResponse
+    /** The redirect's state, whose key material the authorization's key holds. */
+    pending: Pending.Pending | Pending.WithoutKey
+  }
+}
+
+/**
+ * Prefetches the scripts and style sheets of Tempo ID's sign-in page, from `GET /v1/auth/assets`, so
+ * the page that {@link start} opens loads them from the browser's cache. A browser partitions its
+ * cache by site, so only a page on Tempo ID's site, such as `app.tempo.xyz` for `id.tempo.xyz`,
+ * gains. Returns the URLs of the assets. Outside a browser, it prefetches nothing.
+ *
+ * It never throws. A failed read returns no URLs, and the sign-in page loads its assets itself.
+ *
+ * @example
+ * ```ts
+ * // Once the sign-in button shows:
+ * void Actions.redirect.prefetch(auth)
+ * ```
+ */
+export async function prefetch(auth: Auth): Promise<prefetch.ReturnType> {
+  const urls = await (async () => {
+    // The list is public, so the request carries no cookie.
+    const { assets } = await Api.json<{ assets: readonly string[] }>(
+      await (auth.fetch ?? fetch)(new URL('/v1/auth/assets', auth.url)),
+    )
+    return assets.map((path) => new URL(path, auth.url).href)
+  })().catch(() => [])
+  if (typeof document === 'undefined') return urls
+
+  const linked = new Set(
+    [...document.querySelectorAll<HTMLLinkElement>('link[rel="prefetch"]')].map(
+      (link) => link.href,
+    ),
+  )
+  for (const href of urls) {
+    if (linked.has(href)) continue
+    const link = document.createElement('link')
+    link.href = href
+    link.rel = 'prefetch'
+    document.head.appendChild(link)
+  }
+  return urls
+}
+
+export declare namespace prefetch {
+  /** The absolute URLs of the sign-in page's scripts and style sheets. */
+  type ReturnType = readonly string[]
+}
+
+/**
+ * Sends the browser to Tempo ID's pages to sign in, and keeps the redirect's state in `storage`.
+ * With the default storage, it also keeps the `state`, the redirect URI, and the PKCE verifier in
+ * the tab's `sessionStorage`, without the key's material. {@link complete} finishes it when the
+ * browser returns.
+ *
+ * @example
+ * ```ts
+ * await Actions.redirect.start(auth)
+ * ```
+ */
+export async function start(
+  auth: Auth,
+  options: start.Options = {},
+): Promise<void> {
+  const { pending, url } = await createUrl(auth, options)
+  await Store.get(auth)!.setItem(storageKey, pending)
+  Verifier.save(auth, pending)
+  window.location.assign(url)
+}
+
+export declare namespace start {
+  type Options = {
+    /** The key to authorize, which {@link complete} needs too. Defaults to a new key. */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message whose EIP-191 hash the key authorization binds as its `witness`. Needs the
+     * `tempo-id:sign` scope and a key.
+     */
+    challenge?: string | undefined
+    /** Whether the sign-in authorizes an access key. Defaults to `true`. */
+    key?: boolean | undefined
+    /** What the key may do. The user approves it, so it may exceed the headless ceiling. */
+    permissions?: Permissions | undefined
+  }
+}
+
+/** Unpadded URL-safe Base64, as PKCE and `key_authorization` use. */
+const base64url = { pad: false, url: true } as const
+
+/** The redirect this page load returns from, so its code is redeemed once. */
+let completed: Promise<complete.ReturnType<boolean>> | undefined
+
+/** Where a redirect keeps its state in `storage`. */
+const storageKey = 'tempo-id:redirect'
+
+/**
+ * Returns the first value of `name` that the authorization response added to the callback URL. The
+ * issuer appends its parameters after the registered redirect URI's own.
+ */
+function response(url: URL, options: response.Options) {
+  const registered = new URL(options.redirectUri).searchParams.getAll(
+    options.name,
+  ).length
+  return url.searchParams.getAll(options.name)[registered]
+}
+
+declare namespace response {
+  type Options = {
+    /** The callback parameter, such as `error`. */
+    name: string
+    /** The registered redirect URI that the callback URL extends. */
+    redirectUri: string
+  }
+}

package/src/client/internal/accessKey.ts

@@ -0,0 +1,54 @@
+/**
+ * Resolves the access key that a sign-in authorizes: the app's own, or a new one.
+ * @module
+ */
+import { WebCryptoP256 } from 'ox'
+import { Account, Secp256k1 } from 'viem/tempo'
+import type * as Key from '../Key.js'
+
+/**
+ * Returns the app's key, or creates one: a non-extractable `CryptoKey` in a browser, or else a
+ * secp256k1 key.
+ */
+export async function resolve(
+  accessKey: Account.Account | undefined,
+): Promise<resolve.ReturnType> {
+  if (accessKey) return { accessKey, material: {} }
+
+  if (typeof indexedDB !== 'undefined') {
+    const keyPair = await WebCryptoP256.createKeyPair()
+    return {
+      accessKey: Account.fromWebCryptoP256(keyPair),
+      material: { keyPair },
+    }
+  }
+
+  const privateKey = Secp256k1.randomPrivateKey()
+  return {
+    accessKey: Account.fromSecp256k1(privateKey),
+    material: { privateKey },
+  }
+}
+
+/**
+ * Rebuilds a key that {@link resolve} generated from its material. Returns `undefined` for the
+ * empty material of the app's own key.
+ */
+export function restore(
+  material: Key.Material,
+): resolve.ReturnType | undefined {
+  if (material.keyPair)
+    return { accessKey: Account.fromWebCryptoP256(material.keyPair), material }
+  if (material.privateKey)
+    return { accessKey: Account.fromSecp256k1(material.privateKey), material }
+  return undefined
+}
+
+export declare namespace resolve {
+  type ReturnType = {
+    /** A Viem account that signs with the key. */
+    accessKey: Account.Account
+    /** What the authorization keeps to rebuild the key. Empty for the app's own key. */
+    material: Key.Material
+  }
+}

package/src/client/internal/account.ts

@@ -0,0 +1,18 @@
+/**
+ * The state of an `Auth.account()`, which the `tempoId` extension reads and writes through
+ * {@link key}.
+ * @module
+ */
+import type { Account } from 'viem/tempo'
+import type * as Key from '../Key.js'
+
+/** Holds an `Auth.account()`'s state. Other accounts lack it. */
+export const key = Symbol('tempo-id.account')
+
+/** What an `Auth.account()` signs as. */
+export type State = {
+  /** The signed-in access key account, or `undefined` while signed out. */
+  account: Account.AccessKeyAccount | undefined
+  /** The same key as data, which `client.auth.account.upgrade` registers, or `undefined`. */
+  key: Key.Key | undefined
+}