@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/client/actions/passkey.ts

@@ -0,0 +1,141 @@
+/**
+ * Signs the user in with a passkey from the app's own sign-in form, and authorizes the app's key.
+ * By default the browser offers every passkey it holds for the relying party of the app's realms,
+ * so the app needs no email first. A non-empty `credentialId` narrows that to the passkeys it names.
+ * @module
+ */
+import { Authentication, type Types } from 'ox/webauthn'
+import type { Account } from 'viem/tempo'
+import { type Auth, ChallengeWithoutKeyError } from '../Auth.js'
+import type { Authorization } from '../Authorization.js'
+import * as Api from '../internal/api.js'
+import * as Headless from '../internal/headless.js'
+import type { Permissions } from '../Permissions.js'
+
+/**
+ * Signs the user in with a passkey, then authorizes the app for the signed-in user, as
+ * `Actions.email.signIn` does. Only a first-party app authorizes this way. The page's origin must
+ * be the origin of one of the app's redirect URIs, and the relying party of the app's realms must
+ * cover it, or the call throws `passkey_not_permitted`. A sign-in with a key
+ * creates the user's first Tempo Account with `POST /v1/account`, then sends `POST /v1/authorize`.
+ * With `key: false`, the call returns the tokens and the user alone.
+ *
+ * Returns the email step for a wallet.tempo passkey whose account has no email. The app then signs
+ * the user in with `Actions.email.signIn`, which takes the step's `link` and links the passkey once
+ * the passkey signs again.
+ *
+ * A refusal after the passkey verified throws a `RequestError` whose `signedIn` is `true`, since
+ * the user is signed in. A passkey-owned account throws `webauthn_required`, since a passkey signs a
+ * key only on a page that shows it, and `Actions.redirect.start` then authorizes the key on Tempo
+ * ID's pages.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.passkey.signIn(auth)
+ * if ('step' in result) showEmailForm()
+ * ```
+ */
+export async function signIn<
+  const chainId extends number = number,
+  const key extends boolean = true,
+>(
+  auth: Auth,
+  options: signIn.Options<chainId, key> = {},
+): Promise<signIn.ReturnType<chainId, key>> {
+  const { credentialId, getFn, mediation } = options
+  // A challenge rides in the key, so a sign-in without one refuses it before it signs in.
+  if (options.key === false && options.challenge !== undefined)
+    throw new ChallengeWithoutKeyError()
+  const requested = await Api.json<{
+    options: Types.CredentialRequestOptions<true>
+  }>(
+    await Api.post(auth, '/v1/auth/passkey/options', {
+      json: {
+        // The app's realms decide the relying party, which must cover the page's origin.
+        client_id: auth.clientId,
+        ...(credentialId === undefined ? {} : { credentialId }),
+        ...(mediation === undefined ? {} : { mediation }),
+      },
+    }),
+  )
+  const deserialized = Authentication.deserializeOptions(requested.options)
+  const assertion = Authentication.serializeResponse(
+    await Authentication.sign(
+      // ox reads `getFn` beside request options at runtime, which its types admit only beside a challenge.
+      getFn ? ({ ...deserialized, getFn } as never) : deserialized,
+    ),
+  )
+  const body = await Api.json<
+    { step: signIn.EmailStep } | { user: { id: string } }
+  >(await Api.post(auth, '/v1/auth/passkey/verify', { json: { assertion } }))
+  if ('step' in body)
+    return { step: { link: body.step.link, type: body.step.type } }
+
+  // `key` decides both the type and the runtime value of the result.
+  return (await Headless.authorize(auth, {
+    ...options,
+    userId: body.user.id,
+  })) as signIn.ReturnType<chainId, key>
+}
+
+export declare namespace signIn {
+  type Options<chainId extends number = number, key extends boolean = true> = {
+    /**
+     * The key to authorize, as a Viem account. Its `access` names the Tempo Account, which
+     * defaults to the one the app selected, or the user's oldest. Defaults to a new key.
+     */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message the owner's signature binds, such as a sign-in challenge the app's backend issued.
+     * Tempo ID binds its EIP-191 hash as the key authorization's `witness`. Only an app with the
+     * `tempo-id:sign` scope may send one, and only with a key.
+     */
+    challenge?: ([key] extends [false] ? never : string) | undefined
+    /**
+     * The credential ID, or up to 16 IDs, the browser offers. Each is unpadded base64url, as
+     * `PublicKeyCredential.id` reports it, of 1 to 1,023 bytes. A padded or otherwise non-canonical
+     * encoding throws a `RequestError` with reason `invalid_field`. Defaults to every passkey the
+     * browser holds for the relying party, as an empty list does.
+     */
+    credentialId?: readonly string[] | string | undefined
+    /**
+     * Runs the WebAuthn ceremony in place of `navigator.credentials.get`, such as a native passkey
+     * module. Its assertion must report the origin of the page that sends the requests, so an
+     * Android app's facet origin is refused.
+     */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /** How the browser mediates the ceremony, such as `conditional` for passkey autofill. Defaults to the browser's own mediation. */
+    mediation?: 'conditional' | 'optional' | 'required' | 'silent' | undefined
+    /**
+     * Whether the sign-in authorizes an access key. With `false`, the call creates no Tempo
+     * Account, and returns the tokens and the user alone. Defaults to `true`.
+     */
+    key?: key | undefined
+    /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
+    permissions?: Permissions<chainId> | undefined
+  }
+
+  /** The step a wallet.tempo passkey without an email needs: an emailed code, which links it. */
+  type EmailStep = {
+    /** Passed as `link` to `Actions.email.signIn`, which links the passkey to that user. */
+    link: string
+    /** The kind of step. */
+    type: 'email'
+  }
+
+  /**
+   * The authorization, or the tokens and the user alone with `key: false`, or the email step of a
+   * wallet.tempo passkey without an email. A `boolean` `key` returns either authorization.
+   */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > =
+    | (key extends false
+        ? Omit<Authorization<chainId>, 'account' | 'key'>
+        : Authorization<chainId>)
+    | {
+        /** The email step to complete before the authorization. */
+        step: EmailStep
+      }
+}

package/src/client/actions/provider.ts

@@ -0,0 +1,70 @@
+/**
+ * Signs the user in to Tempo ID through an OAuth provider or an SSO connection, from the app's
+ * own sign-in buttons.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+import type { Provider } from '../Provider.js'
+
+/**
+ * Lists the OAuth providers Tempo ID offers, for an app that shows its own sign-in buttons.
+ *
+ * @example
+ * ```ts
+ * const providers = await Actions.provider.list(auth)
+ * // [{ id: 'google', name: 'Google' }]
+ * ```
+ */
+export async function list(auth: Auth): Promise<list.ReturnType> {
+  const { providers } = await Api.json<{ providers: list.ReturnType }>(
+    await (auth.fetch ?? fetch)(new URL('/v1/auth/providers', auth.url)),
+  )
+  return providers
+}
+
+export declare namespace list {
+  type ReturnType = readonly {
+    /** The provider's short name, which `signIn` takes. */
+    id: Provider
+    /** The name to show, such as `Google`. */
+    name: string
+  }[]
+}
+
+/**
+ * Sends the browser to an OAuth provider, or to the SSO connection a `Step` names, and back to
+ * `returnTo` signed in to Tempo ID. Unlike `Actions.email.signIn`, it does not authorize the
+ * app: the app calls `Actions.authorize` once the browser returns.
+ *
+ * @example
+ * ```ts
+ * Actions.provider.signIn(auth, { provider: 'google' })
+ * ```
+ */
+export function signIn(auth: Auth, options: signIn.Options): void {
+  const url =
+    'url' in options
+      ? new URL(options.url)
+      : new URL(`/v1/auth/oauth/${options.provider}`, auth.url)
+  url.searchParams.set('return_to', options.returnTo ?? window.location.href)
+  // An account step after the sign-in lists the accounts of this app's realms.
+  url.searchParams.set('client_id', auth.clientId)
+  window.location.assign(url)
+}
+
+export declare namespace signIn {
+  type Options = (
+    | {
+        /** The OAuth provider to sign in with, from `list`. */
+        provider: Provider
+      }
+    | {
+        /** The URL of a `Step`, such as the SSO connection an address requires. */
+        url: string
+      }
+  ) & {
+    /** Where to return. Defaults to the current page. It must be on one of the app's origins. */
+    returnTo?: string | undefined
+  }
+}

package/src/client/actions/realm.ts

@@ -0,0 +1,36 @@
+/**
+ * Lists the realms the app reaches: the sets of Tempo Accounts its settings name.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+
+/**
+ * Lists the realms the app reaches, in its settings' order. The first holds a user's first account.
+ *
+ * @example
+ * ```ts
+ * const realms = await Actions.realm.list(auth)
+ * // [{ id: 'default', name: 'Tempo' }]
+ * ```
+ */
+export async function list(auth: Auth): Promise<list.ReturnType> {
+  const { realms } = await Api.json<{ realms: list.ReturnType }>(
+    await (auth.fetch ?? fetch)(
+      new URL(
+        `/v1/realms?${new URLSearchParams({ client_id: auth.clientId })}`,
+        auth.url,
+      ),
+    ),
+  )
+  return realms
+}
+
+export declare namespace list {
+  type ReturnType = readonly {
+    /** The realm ID, such as `default` or `tempo-cash`. */
+    id: string
+    /** The realm's display name, such as `Tempo Cash`. */
+    name: string
+  }[]
+}

package/src/client/actions/redirect.ts

@@ -0,0 +1,408 @@
+/**
+ * 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` for a browser app. `createUrl` and `handleCallback` leave
+ * it to the app to keep, for a backend or a native 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 Pending from '../Pending.js'
+import type { Permissions } from '../Permissions.js'
+
+/** `complete` received a `key` that differs from the one `start` received for the stored redirect. */
+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. The code is redeemed once, however often the page calls this. A callback that denies
+ * this page's redirect, such as `error=access_denied`, throws a `RequestError` with that `error` as
+ * its `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 store = Store.get(auth)!
+    const stored = (await store.getItem(storageKey)) as
+      | Pending.Pending
+      | Pending.WithoutKey
+      | null
+      | undefined
+    const url = new URL(window.location.href)
+    // 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 handleCallback(auth, {
+      accessKey: options.accessKey,
+      pending: stored,
+      url,
+    })
+  })()
+  // 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 the app passed to {@link start}, if it supplied one. */
+    accessKey?: Account.Account | undefined
+    /**
+     * The `key` that {@link start} received: `false` for a sign-in without a key. Defaults to
+     * `true`. A stored redirect that `start` began with another `key` throws
+     * {@link KeyMismatchError}.
+     */
+    key?: key | undefined
+  }
+
+  /**
+   * The authorization, or the tokens and the user alone for a sign-in without a key. `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 URL that signs the user in on Tempo ID's pages and redirects back with a code,
+ * and the `Pending` state to keep until then, such as in a sealed cookie.
+ * {@link handleCallback} redeems the code for the tokens and the key authorization.
+ *
+ * @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
+  const url = new URL('/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,
+    ),
+    ...(authorization
+      ? {
+          key_authorization: Base64.fromString(
+            JSON.stringify(authorization),
+            base64url,
+          ),
+        }
+      : {}),
+    redirect_uri: redirectUri,
+    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, as a Viem account. Its `access` names the Tempo Account, which
+     * defaults to the one the user selected at sign-in, or their oldest. Defaults to a new key, whose material `pending` keeps.
+     */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message the owner's signature binds, such as a sign-in challenge the app's backend issued.
+     * Tempo ID binds its EIP-191 hash as the key authorization's `witness`. Only an app with the
+     * `tempo-id:sign` scope may send one. With `key: false`, the call throws
+     * `Auth.ChallengeWithoutKeyError`.
+     */
+    challenge?: ([key] extends [false] ? never : string) | undefined
+    /**
+     * Whether the sign-in authorizes an access key. With `false`, the request carries no key
+     * authorization, and {@link handleCallback} returns the tokens and the user alone. Defaults to
+     * `true`.
+     */
+    key?: key | undefined
+    /** What the key may do. Tempo ID's pages show it, and the headless ceiling fills what it leaves out. */
+    permissions?: Permissions | undefined
+    /** Where Tempo ID redirects back to. Defaults to the instance's `redirectUri`. */
+    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
+  }
+}
+
+/**
+ * Finishes a sign-in redirect: checks its state, and redeems the code with the PKCE verifier (and
+ * the client secret, for a backend) for the tokens and the key authorization.
+ *
+ * @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>> {
+  const { key, redirectUri, state, verifier, ...material } = options.pending
+  const url = new URL(options.url)
+  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,
+    })
+
+  const body = await Api.token(auth, {
+    code,
+    code_verifier: verifier,
+    grant_type: 'authorization_code',
+    redirect_uri: redirectUri,
+  })
+  // `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),
+    } as handleCallback.ReturnType<pending>
+  }
+  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 },
+  ) as handleCallback.ReturnType<pending>
+}
+
+export declare namespace handleCallback {
+  type Options<
+    pending extends Pending.Pending | Pending.WithoutKey = Pending.Pending,
+  > = {
+    /** The key the app passed to `createUrl`, if it supplied one. */
+    accessKey?: Account.Account | undefined
+    /** What `createUrl` returned to keep. */
+    pending: pending
+    /** The callback URL Tempo ID redirected to. */
+    url: string | URL
+  }
+
+  /**
+   * The authorization, or the tokens and the user alone for a `Pending.WithoutKey`. A `pending`
+   * typed as either returns either.
+   */
+  type ReturnType<
+    pending extends Pending.Pending | Pending.WithoutKey = Pending.Pending,
+  > = [pending] extends [Pending.WithoutKey]
+    ? WithoutKey
+    : [pending] extends [Pending.Pending]
+      ? Authorization
+      : Authorization | WithoutKey
+
+  /** What a sign-in without a key returns: the tokens and the user. */
+  type WithoutKey = Omit<Authorization, 'account' | 'key'>
+}
+
+/**
+ * Sends the browser to Tempo ID's pages to sign in, keeping the redirect's state in `storage`.
+ * {@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)
+  window.location.assign(url)
+}
+
+export declare namespace start {
+  type Options = {
+    /**
+     * The key to authorize, as a Viem account. Pass it to {@link complete} too. Defaults to a new
+     * key, which `storage` keeps until the browser returns.
+     */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message the owner's signature binds, such as a sign-in challenge the app's backend issued.
+     * Tempo ID binds its EIP-191 hash as the key authorization's `witness`. Only an app with the
+     * `tempo-id:sign` scope may send one.
+     */
+    challenge?: string | undefined
+    /**
+     * Whether the sign-in authorizes an access key. With `false`, {@link complete} returns the
+     * tokens and the user alone. Defaults to `true`.
+     */
+    key?: boolean | undefined
+    /** What the key may do. Tempo ID's pages show it, and the headless ceiling fills what it leaves out. */
+    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. A
+ * registered redirect URI may hold its own `error` parameters, which come first, since the issuer
+ * appends a refusal's. It replaces `code` and `state`, which have one value.
+ */
+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` or `error_description`. */
+    name: string
+    /** The registered redirect URI that the callback URL extends. */
+    redirectUri: string
+  }
+}