@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/internal/api.ts

@@ -0,0 +1,242 @@
+/**
+ * Calls Tempo ID's API, and reads its responses into what the actions return.
+ * @module
+ */
+import { Base64 } from 'ox'
+import type { KeyAuthorization } from 'ox/tempo'
+import type { Account } from 'viem/tempo'
+import { type Auth, RequestError } from '../Auth.js'
+import type { Authorization } from '../Authorization.js'
+import * as Key from '../Key.js'
+import type { TempoAccount } from '../TempoAccount.js'
+import type { Tokens } from '../Tokens.js'
+import type { User } from '../User.js'
+
+/**
+ * Builds an authorization from Tempo ID's response and the sign-in's key: generated material, or
+ * the app's `accessKey`. Throws `server_error` for a response without the key authorization.
+ */
+export function authorization<chainId extends number = number>(
+  body: Headless,
+  options: {
+    accessKey?: Account.Account | undefined
+    material: Key.Material
+  },
+): Authorization<chainId> {
+  const { accessKey, material } = options
+  // A response to a request with a key always carries one, so its absence is a fault.
+  if (!body.account || !body.key_authorization)
+    throw new RequestError({
+      code: 'server_error',
+      message:
+        'Missing key authorization in the response to a request with a key. Sign in again.',
+      status: 200,
+    })
+  const key = Key.from<chainId>({
+    ...material,
+    account: body.account,
+    keyAuthorization: body.key_authorization,
+  })
+  const tokens_ =
+    'accessToken' in body.tokens ? body.tokens : tokens(body.tokens)
+  return {
+    ...tokens_,
+    account: Key.toAccount(key, { accessKey }),
+    key,
+    user: user(tokens_),
+  }
+}
+
+/** What the headless API returns for an authorization. */
+export type Headless = {
+  /** The Tempo Account the key acts for, present for a request with a key. */
+  account?: Key.Key['account'] | undefined
+  /** The signed key authorization, in RPC format, present for a request with a key. */
+  key_authorization?: KeyAuthorization.Rpc | undefined
+  /** The issued tokens, raw from the token endpoint or already read into `Tokens`. */
+  tokens: TokenResponse | Tokens
+  /** Present when the key's account waits for its upgrade, so the key signed as its own. */
+  upgrade_available?: true | undefined
+}
+
+/** Reads a JSON response, and throws a {@link RequestError} for a refusal. */
+export async function json<value = unknown>(
+  response: Response,
+): Promise<value> {
+  // Some refusals, such as the CSRF check's, return plain text.
+  const body = (await response.json().catch(() => ({}))) as value &
+    Partial<ErrorBody>
+  if (!response.ok) throw error(body, { status: response.status })
+  return body
+}
+
+/** An OAuth error response, with Tempo ID's extension members. */
+export type ErrorBody = {
+  /** The OAuth error code, which `reason` determines. */
+  error: string
+  /** The fault and its fix. Its wording may change. */
+  error_description?: string | undefined
+  /** The errors page, at the refusal's `reason`. */
+  error_uri?: string | undefined
+  /** The request field at fault, as a dotted path. */
+  field?: string | undefined
+  /** The values the refusal compared. Base units are decimal strings. */
+  meta?: Readonly<Record<string, number | string>> | undefined
+  /** A stable name for the refusal. The issuer's own errors carry none. */
+  reason?: RequestError.Reason | undefined
+}
+
+/** Returns a {@link RequestError} for an OAuth error response, or a refusal without a body. */
+export function error(body: Partial<ErrorBody>, options: { status: number }) {
+  return new RequestError({
+    code: body.error ?? 'server_error',
+    field: body.field,
+    message:
+      body.error_description ??
+      body.error ??
+      `Request failed with status ${options.status}.`,
+    meta: body.meta,
+    reason: body.reason,
+    status: options.status,
+    uri: body.error_uri,
+  })
+}
+
+/** Posts JSON to Tempo ID's API with the session cookie. */
+export function post(auth: Auth, path: string, options: { json: unknown }) {
+  return (auth.fetch ?? fetch)(new URL(path, auth.url), {
+    body: JSON.stringify(options.json),
+    credentials: 'include',
+    headers: { 'content-type': 'application/json' },
+    method: 'POST',
+  })
+}
+
+/** Posts a form to the token endpoint, with the client ID and any client secret. */
+export async function token(auth: Auth, body: Record<string, string>) {
+  return json<TokenResponse>(
+    await (auth.fetch ?? fetch)(new URL('/oauth2/token', auth.url), {
+      body: new URLSearchParams({
+        ...body,
+        client_id: auth.clientId,
+        ...(auth.clientSecret ? { client_secret: auth.clientSecret } : {}),
+      }),
+      method: 'POST',
+    }),
+  )
+}
+
+/** Reads the account's address, its owners, the type of the owner that signs its keys, and its realm. */
+export function tempoAccount(account: TempoAccountResponse): TempoAccount {
+  // A configuration sorts its owners by address. A cloud wallet signs the account's keys whenever it
+  // is an owner, so it names the account's owner before a passkey does.
+  const owner =
+    account.config.owners.find((entry) => entry.type !== 'webAuthn') ??
+    account.config.owners[0]
+  return {
+    address: account.address,
+    owner: owner.type,
+    owners: account.config.owners.map((entry) => ({
+      address: entry.owner,
+      type: entry.type,
+    })),
+    realm: { id: account.realm.id, name: account.realm.name },
+  }
+}
+
+/** A Tempo Account as the API returns it, with the fields that the package reads. */
+export type TempoAccountResponse = {
+  /** The account's address on the chain of the request. */
+  address: `0x${string}`
+  /** The account's configuration. */
+  config: {
+    /** The owners in the API's order, each with its address and key type, such as `privy`. */
+    owners: readonly [Owner, ...Owner[]]
+  }
+  /** The account's realm. */
+  realm: {
+    /** `default`, or a realm that an app's settings name, such as `tempo-cash`. */
+    id: string
+    /** The display name, such as `Tempo Cash`. */
+    name: string
+  }
+}
+
+/** What the token endpoint returns. A redirect's code adds its key authorization. */
+export type TokenResponse = {
+  /** The access token for the app's API requests. */
+  access_token: string
+  /** The Tempo Account the key acts for, present with `key_authorization`. */
+  account?: Key.Key['account'] | undefined
+  /** The access token's lifetime, in seconds. */
+  expires_in: number
+  /** The OIDC ID token, which names the user. A refresh may omit it. */
+  id_token?: string | undefined
+  /** The signed key authorization that the user approved, if any. */
+  key_authorization?: KeyAuthorization.Rpc | undefined
+  /** Exchanges for new tokens through `Actions.refresh`. It rotates on every refresh. */
+  refresh_token?: string | undefined
+}
+
+/** Reads the signed-in user from the ID token of `tokens`. */
+export function user(tokens: Tokens): User {
+  const claims = JSON.parse(
+    Base64.toString(tokens.idToken!.split('.')[1]!),
+  ) as { email: string; sub: string }
+  return { email: claims.email, id: claims.sub }
+}
+
+/** Reads a token response into `Tokens`. */
+export function tokens(response: TokenResponse): Tokens {
+  return {
+    accessToken: response.access_token,
+    expiresAt: Date.now() + response.expires_in * 1000,
+    idToken: response.id_token,
+    refreshToken: response.refresh_token,
+  }
+}
+
+/**
+ * Rethrows an error after a sign-in verified as a {@link RequestError} marked `signedIn`. An error
+ * without a response, such as a network error, has status 0 and the original as its `cause`.
+ */
+export function signedIn(error: unknown): never {
+  if (!(error instanceof RequestError))
+    throw new RequestError({
+      cause: error,
+      code: 'server_error',
+      message:
+        'Authorization failed after the sign-in, with no response from Tempo ID. The user is signed in, so authorize again.',
+      signedIn: true,
+      status: 0,
+    })
+  throw new RequestError({
+    cause: error.cause,
+    code: error.code,
+    field: error.field,
+    message: error.message,
+    meta: error.meta,
+    reason: error.reason,
+    signedIn: true,
+    status: error.status,
+    uri: error.uri,
+  })
+}
+
+/** Reads an authorization without a key: the tokens and the user. */
+export function withoutKey(body: Headless): WithoutKey {
+  const tokens_ =
+    'accessToken' in body.tokens ? body.tokens : tokens(body.tokens)
+  return { ...tokens_, user: user(tokens_) }
+}
+
+/** An authorization without a key: the tokens and the user. */
+export type WithoutKey = Omit<Authorization, 'account' | 'key'>
+
+/** One owner of a Tempo Account, as the API returns it. */
+type Owner = {
+  /** The address of the owner key. */
+  owner: `0x${string}`
+  /** The kind of key that holds it, such as `privy` or `webAuthn`. */
+  type: string
+}

package/src/client/internal/headless.ts

@@ -0,0 +1,308 @@
+/**
+ * Authorizes the app after a headless sign-in, for `Actions.email.signIn` and
+ * `Actions.passkey.signIn`.
+ * @module
+ */
+import { Authentication, type Types } from 'ox/webauthn'
+import type { Account } from 'viem/tempo'
+import { type Auth, RequestError } from '../Auth.js'
+import type { Authorization } from '../Authorization.js'
+import type { Permissions } from '../Permissions.js'
+import * as AccessKey from './accessKey.js'
+import * as Api from './api.js'
+import { request } from './request.js'
+
+/** A headless authorization, and whether its account can upgrade, as the actions return them. */
+export type Result = {
+  /** The authorization, without its key for `key: false`. */
+  authorization: Authorization | Api.WithoutKey
+  /**
+   * Whether the key's account is a wallet.tempo passkey's that waits for its upgrade on the key's
+   * chain. The key signed as the passkey's own account, and `Actions.account.upgrade` with it
+   * registers the key and upgrades the account.
+   */
+  upgradeAvailable: boolean
+}
+
+/**
+ * Sends `POST /v1/account`, which creates the user's first Tempo Account, then
+ * `POST /v1/authorize`. A sign-in without a key skips the account. Each refusal is marked
+ * `signedIn`. An authorization for a user other than `userId` throws `session_changed`.
+ */
+export async function authorize(
+  auth: Auth,
+  options: authorize.Options,
+): Promise<Result> {
+  const { challenge, getFn, permissions } = options
+  // The user is signed in already, so every failure from here on, key generation included, is marked.
+  try {
+    const key =
+      options.key === false
+        ? undefined
+        : await AccessKey.resolve(options.accessKey)
+    if (key)
+      await Api.json(
+        await Api.post(auth, '/v1/account', {
+          json: { client_id: auth.clientId },
+        }),
+      )
+    const body = await Api.json<Api.Headless>(
+      await post(auth, {
+        getFn,
+        json: request(auth, {
+          accessKey: key?.accessKey,
+          challenge,
+          permissions,
+        }),
+      }),
+    )
+    const authorization = key
+      ? Api.authorization(body, key)
+      : Api.withoutKey(body)
+    if (authorization.user.id !== options.userId) throw sessionChanged()
+    return { authorization, upgradeAvailable: body.upgrade_available === true }
+  } catch (error) {
+    return Api.signedIn(error)
+  }
+}
+
+export declare namespace authorize {
+  type Options = {
+    /** The key to authorize. Defaults to a new key. */
+    accessKey?: Account.Account | undefined
+    /** A message that the key's witness binds. */
+    challenge?: string | undefined
+    /** Runs the ceremony of the passkey that owns the account. Defaults to `navigator.credentials.get`. */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /** Whether the sign-in authorizes an access key. Defaults to `true`. */
+    key?: boolean | undefined
+    /** What the key may do. */
+    permissions?: Permissions | undefined
+    /** The user that the sign-in verified. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the authorization that a sign-in returned in its own response. For a server that returns
+ * none, such as one that predates it, it calls {@link authorize}. Each refusal is marked `signedIn`.
+ */
+export async function complete(
+  auth: Auth,
+  options: complete.Options,
+): Promise<Result> {
+  const { body, key } = options
+  if (!body.authorization)
+    // The request's own `accessKey`, so a key that the library generates keeps its material.
+    return await authorize(auth, { ...options.request, userId: body.user.id })
+  try {
+    const signed =
+      'step' in body.authorization
+        ? await Api.json<Api.Headless>(
+            await sign(auth, {
+              getFn: options.request.getFn,
+              json: options.authorize,
+              step: body.authorization,
+            }),
+          )
+        : body.authorization
+    const authorization = key
+      ? Api.authorization(signed, key)
+      : Api.withoutKey(signed)
+    if (authorization.user.id !== body.user.id) throw sessionChanged()
+    return {
+      authorization,
+      upgradeAvailable: signed.upgrade_available === true,
+    }
+  } catch (error) {
+    return Api.signedIn(error)
+  }
+}
+
+export declare namespace complete {
+  type Options = {
+    /** The authorization request that the sign-in sent, which the passkey step repeats. */
+    authorize: ReturnType<typeof request>
+    /** The sign-in's response. */
+    body: {
+      /**
+       * The authorization, or the passkey step for a passkey-owned account. Absent from a server
+       * that predates the authorization in the sign-in.
+       */
+      authorization?: Api.Headless | Step | undefined
+      /** The signed-in user. */
+      user: { id: string }
+    }
+    /** The key that the request authorized, or `undefined` without one. */
+    key: AccessKey.resolve.ReturnType | undefined
+    /** The sign-in's options, for a server that returns no authorization. */
+    request: prepare.Options
+  }
+}
+
+/**
+ * Returns the key, or none with `key: false`, and the authorization request that a sign-in sends:
+ * an emailed-code sign-in with its code, and a passkey sign-in with its options.
+ */
+export async function prepare(auth: Auth, options: prepare.Options) {
+  const key =
+    options.key === false
+      ? undefined
+      : await AccessKey.resolve(options.accessKey)
+  return {
+    authorize: request(auth, {
+      accessKey: key?.accessKey,
+      challenge: options.challenge,
+      permissions: options.permissions,
+    }),
+    key,
+  }
+}
+
+export declare namespace prepare {
+  type Options = Omit<authorize.Options, 'userId'>
+}
+
+/**
+ * Reads the JSON response of a sign-in that carried the authorization request. A refusal with the
+ * `Tempo-Id-Signed-In` header came after the session started, so it is marked `signedIn`.
+ */
+export async function read<value>(response: Response): Promise<value> {
+  try {
+    return await Api.json<value>(response)
+  } catch (error) {
+    if (response.headers.get('Tempo-Id-Signed-In') === 'true')
+      return Api.signedIn(error)
+    throw error
+  }
+}
+
+/**
+ * Sends `POST /v1/authorize` with `json`. For a request with a key, on a page that runs passkey
+ * ceremonies, it requests the passkey step, signs it with {@link sign}, and returns the repeated
+ * request's response. Otherwise it returns the response of the one request.
+ */
+export async function post(auth: Auth, options: post.Options) {
+  const { getFn, json, passkey = true } = options
+  const response = await Api.post(auth, '/v1/authorize', {
+    json: {
+      ...json,
+      ...(passkey && steps(json, { getFn }) ? { passkey: true } : {}),
+    },
+  })
+  if (!response.ok) return response
+  // A successful response is the authorization or the step, which Tempo ID's schema validates.
+  const body = (await response.clone().json()) as Api.Headless | Step
+  if (!('step' in body)) return response
+  const signed = await sign(auth, { getFn, json, step: body })
+  if (signed.ok) return signed
+  // A session that ended during the ceremony reads as a missing session, as on the first request.
+  // Any other refusal, such as `webauthn_rejected`, which also has status 401, throws its reason.
+  const refused = (await signed
+    .clone()
+    .json()
+    .catch(() => ({}))) as Partial<Api.ErrorBody>
+  if (refused.reason !== 'session_required') await Api.json(signed)
+  return signed
+}
+
+export declare namespace post {
+  type Options = {
+    /** Runs the ceremony of the passkey that owns the account. Defaults to `navigator.credentials.get`. */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /** The authorization request. */
+    json: ReturnType<typeof request>
+    /** Whether a passkey-owned account signs the key on the page. Defaults to `true`. */
+    passkey?: boolean | undefined
+  }
+}
+
+/**
+ * Signs the options of the passkey `step` with the passkey on the page, and repeats
+ * `POST /v1/authorize` with the assertion and the step's expiry. Returns that response. A failed
+ * ceremony, such as a dismissed prompt or a passkey that this device does not hold, throws
+ * `webauthn_required`, so the app can authorize through a redirect.
+ */
+export async function sign(auth: Auth, options: sign.Options) {
+  const { getFn, json, step } = options
+  const deserialized = Authentication.deserializeOptions(step.step.options)
+  const signed = 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,
+  ).catch((error: unknown) => {
+    throw new RequestError({
+      cause: error,
+      code: 'interaction_required',
+      message:
+        "Passkey ceremony failed: the account's passkey did not sign the key on this page. Authorize through a redirect, whose approval page signs it.",
+      reason: 'webauthn_required',
+      status: 0,
+    })
+  })
+  const assertion = Authentication.serializeResponse(signed)
+  // The step's expiry keeps the digest that the passkey signed, in place of a new default.
+  return await Api.post(auth, '/v1/authorize', {
+    json: {
+      ...json,
+      ...(json.key_authorization
+        ? {
+            key_authorization: {
+              ...json.key_authorization,
+              expiry: step.expiry,
+            },
+          }
+        : {}),
+      passkey: { assertion },
+    },
+  })
+}
+
+export declare namespace sign {
+  type Options = {
+    /** Runs the passkey's ceremony. Defaults to `navigator.credentials.get`. */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /** The authorization request that returned the step. */
+    json: ReturnType<typeof request>
+    /** The passkey step. */
+    step: Step
+  }
+}
+
+/**
+ * Returns whether a request asks for the passkey step: it carries a key, and the page runs passkey
+ * ceremonies, through `getFn` or `navigator.credentials`.
+ */
+export function steps(
+  json: ReturnType<typeof request>,
+  options: Pick<post.Options, 'getFn'>,
+) {
+  if (!json.key_authorization) return false
+  return (
+    options.getFn !== undefined ||
+    globalThis.navigator?.credentials !== undefined
+  )
+}
+
+/** The passkey step of a headless authorization, which the page signs before it repeats the request. */
+export type Step = {
+  /** The key's expiry in Unix seconds, which the repeated request sends. */
+  expiry: number
+  /** The step. */
+  step: {
+    /** The options for `navigator.credentials.get()`, whose challenge is the key's digest. */
+    options: Types.CredentialRequestOptions<true>
+    /** The kind of step. */
+    type: 'passkey'
+  }
+}
+
+/** Returns the refusal of an authorization for another user than the sign-in's. */
+function sessionChanged() {
+  return new RequestError({
+    code: 'invalid_request',
+    message:
+      'Session changed: another sign-in replaced this one before the authorization. Sign in again.',
+    reason: 'session_changed',
+    status: 409,
+  })
+}

package/src/client/internal/indexedDb.ts

@@ -0,0 +1,44 @@
+/**
+ * The default `storage` in a browser. IndexedDB keeps a non-extractable `CryptoKey` as it is.
+ * @module
+ */
+/* istanbul ignore file -- IndexedDB exists only in a browser. */
+import type { Storage } from '../Storage.js'
+
+/** Opens a store in the page's IndexedDB. */
+export function create(): Storage {
+  const database = new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open('tempo-id')
+    request.onupgradeneeded = () => request.result.createObjectStore(store)
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () => reject(request.error)
+  })
+
+  /** Runs one request against the store, and resolves with its result. */
+  async function run<value>(
+    mode: IDBTransactionMode,
+    fn: (objectStore: IDBObjectStore) => IDBRequest<value>,
+  ) {
+    const objectStore = (await database)
+      .transaction(store, mode)
+      .objectStore(store)
+    return new Promise<value>((resolve, reject) => {
+      const request = fn(objectStore)
+      request.onsuccess = () => resolve(request.result)
+      request.onerror = () => reject(request.error)
+    })
+  }
+
+  return {
+    getItem: (key) => run('readonly', (objectStore) => objectStore.get(key)),
+    async removeItem(key) {
+      await run('readwrite', (objectStore) => objectStore.delete(key))
+    },
+    async setItem(key, value) {
+      await run('readwrite', (objectStore) => objectStore.put(value, key))
+    },
+  }
+}
+
+/** The object store that holds every value. */
+const store = 'store'

package/src/client/internal/request.ts

@@ -0,0 +1,70 @@
+/**
+ * Builds the requests that the actions send, in Tempo ID's wire format.
+ * @module
+ */
+import { Hex } from 'ox'
+import type { Account } from 'viem/tempo'
+import type { Auth } from '../Auth.js'
+import type { Permissions } from '../Permissions.js'
+
+/** Returns the authorization request, with a key authorization request when `accessKey` is set. */
+export function request(
+  auth: Auth,
+  options: {
+    /** The key to authorize, if any. */
+    accessKey?: Account.Account | undefined
+    /** The Tempo Account the key acts for, in place of the one `accessKey` names. */
+    account?: `0x${string}` | undefined
+    /** A message that the key's witness binds. */
+    challenge?: string | undefined
+    permissions?: Permissions | undefined
+  },
+) {
+  const { accessKey, challenge } = options
+  return {
+    ...(challenge === undefined ? {} : { challenge }),
+    client_id: auth.clientId,
+    ...(accessKey
+      ? { key_authorization: keyAuthorization(auth, { ...options, accessKey }) }
+      : {}),
+    redirect_uri:
+      auth.redirectUri ?? `${globalThis.location?.origin ?? auth.url}/`,
+    scope: auth.scope,
+    // A key of a wallet.tempo passkey's account that waits for its upgrade signs as the passkey's
+    // own account, and the sign-in then registers the key and upgrades the account.
+    ...(accessKey ? { skip_upgrade: true } : {}),
+  }
+}
+
+/**
+ * Returns the key authorization request. An access key account names its Tempo Account, and a plain
+ * key leaves the choice to Tempo ID.
+ */
+export function keyAuthorization(
+  auth: Auth,
+  options: {
+    /** The key to authorize. */
+    accessKey: Account.Account
+    /** The Tempo Account the key acts for, in place of the one `accessKey` names. */
+    account?: `0x${string}` | undefined
+    permissions?: Permissions | undefined
+  },
+) {
+  const { accessKey, permissions = {} } = options
+  const account =
+    options.account ??
+    (accessKey.accessKeyAddress ? accessKey.address : undefined)
+  return {
+    ...(account ? { account } : {}),
+    address: accessKey.accessKeyAddress ?? accessKey.address,
+    chainId: Hex.fromNumber(permissions.chainId ?? auth.chainId),
+    expiry: permissions.expiry,
+    keyType: accessKey.keyType,
+    limits: permissions.limits?.map(({ limit, period, token }) => ({
+      limit: Hex.fromNumber(limit),
+      ...(period ? { period } : {}),
+      token,
+    })),
+    scopes: permissions.scopes,
+  }
+}

package/src/client/internal/store.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves where actions keep state across page loads.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import type { Storage } from '../Storage.js'
+import * as IndexedDb from './indexedDb.js'
+
+/** The default `storage`, opened on first use. */
+let indexedDb: Storage | undefined
+
+/**
+ * Returns the instance's `storage`, or else IndexedDB. Returns `undefined` outside a browser
+ * without `storage`.
+ */
+export function get(auth: Auth) {
+  if (auth.storage) return auth.storage
+  if (typeof indexedDB === 'undefined') return undefined
+  return (indexedDb ??= IndexedDb.create())
+}