@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/src/client/Storage.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a redirect keeps its state until Tempo ID redirects back.
+ * @module
+ */
+/** Keeps a redirect's state, as structured-clone storage such as IndexedDB does. */
+export type Storage = {
+  /** Reads the value at `key`, or `undefined`. */
+  getItem: (key: string) => Promise<unknown>
+  /** Deletes the value at `key`. */
+  removeItem: (key: string) => Promise<void>
+  /** Writes `value` at `key`, without serializing it. */
+  setItem: (key: string, value: unknown) => Promise<void>
+}
+
+/**
+ * Instantiates a {@link Storage}.
+ *
+ * @example
+ * ```ts
+ * const storage = Storage.from({
+ *   getItem: (key) => idb.get(key),
+ *   removeItem: (key) => idb.del(key),
+ *   setItem: (key, value) => idb.set(key, value),
+ * })
+ * ```
+ */
+export function from(value: Storage): Storage {
+  return value
+}

package/src/client/TempoAccount.ts

@@ -0,0 +1,42 @@
+/**
+ * One of a user's Tempo Accounts.
+ * @module
+ */
+/** One of the user's Tempo Accounts. */
+export type TempoAccount = {
+  /** The account's address, the same on every Tempo chain. */
+  address: `0x${string}`
+  /**
+   * Who holds the account's owner key: a Privy wallet, which Tempo ID signs with (`privy`), a key
+   * that Tempo ID holds and signs with in development (`secp256k1`), or a passkey, which signs only
+   * on a Tempo ID page (`webAuthn`). Treat another value as an owner that may refuse a key
+   * authorization.
+   */
+  owner: 'privy' | 'secp256k1' | 'webAuthn' | (string & {})
+  /**
+   * The realm the account belongs to: `default`, or one the app's settings name, such as
+   * `tempo-cash`, with its display name. An app reaches only the accounts of its realms.
+   */
+  realm: {
+    /** The realm ID: `default`, or one an app's settings name, such as `tempo-cash`. */
+    id: string
+    /** The realm's display name, such as `Tempo Cash`. */
+    name: string
+  }
+}
+
+/**
+ * Instantiates a {@link TempoAccount}.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = TempoAccount.from({
+ *   address: '0x…',
+ *   owner: 'privy',
+ *   realm: { id: 'default', name: 'Tempo' },
+ * })
+ * ```
+ */
+export function from(value: TempoAccount): TempoAccount {
+  return value
+}

package/src/client/Tokens.ts

@@ -0,0 +1,27 @@
+/**
+ * The app's tokens for Tempo APIs.
+ * @module
+ */
+/** The app's tokens for Tempo APIs. */
+export type Tokens = {
+  /** The Bearer token Tempo APIs accept. */
+  accessToken: string
+  /** When the access token expires, in milliseconds. */
+  expiresAt: number
+  /** The OIDC ID token, which names the user. A refresh may omit it. */
+  idToken?: string | undefined
+  /** Exchanges for new tokens through `Actions.refresh`. It rotates on every refresh. */
+  refreshToken?: string | undefined
+}
+
+/**
+ * Instantiates a {@link Tokens}.
+ *
+ * @example
+ * ```ts
+ * const tokens = Tokens.from({ ...saved, ...(await Actions.refresh(auth, { refreshToken })) })
+ * ```
+ */
+export function from(value: Tokens): Tokens {
+  return value
+}

package/src/client/User.ts

@@ -0,0 +1,23 @@
+/**
+ * The signed-in user.
+ * @module
+ */
+/** The signed-in user. */
+export type User = {
+  /** The user's verified email address. */
+  email: string
+  /** The user's ID, the `sub` of every token. */
+  id: string
+}
+
+/**
+ * Instantiates a {@link User}.
+ *
+ * @example
+ * ```ts
+ * const user = User.from({ email: claims.email, id: claims.sub })
+ * ```
+ */
+export function from(value: User): User {
+  return value
+}

package/src/client/actions/account.ts

@@ -0,0 +1,57 @@
+/**
+ * Reads the signed-in user's Tempo Account for the app, with its realm.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+import type { TempoAccount } from '../TempoAccount.js'
+
+/**
+ * Returns the signed-in user's Tempo Account for the app, with its `realm`: the account that the
+ * user selected for the app in the account step, or else the oldest in the app's realms. Returns
+ * `undefined` when the user has no account in those realms. For a user with none, the call sends
+ * `POST /v1/account`, which creates a Privy-owned one in the app's first realm when that realm has a
+ * Privy app.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = await Actions.account.get(auth)
+ * // { address: '0x…', owner: 'webAuthn', realm: { id: 'default', name: 'Tempo' } }
+ * ```
+ */
+export async function get(auth: Auth): Promise<get.ReturnType> {
+  const listed = await Api.json<{
+    tempo: readonly Api.TempoAccountResponse[]
+  }>(
+    await (auth.fetch ?? fetch)(
+      new URL(
+        `/v1/account?${new URLSearchParams({ client_id: auth.clientId })}`,
+        auth.url,
+      ),
+      { credentials: 'include' },
+    ),
+  )
+  const tempo = await (async () => {
+    if (listed.tempo.length > 0) return listed.tempo
+    // Creation is a JSON write, which a page on another site cannot send.
+    const created = await Api.json<{
+      tempo: readonly Api.TempoAccountResponse[]
+    }>(
+      await (auth.fetch ?? fetch)(new URL('/v1/account', auth.url), {
+        body: JSON.stringify({ client_id: auth.clientId }),
+        credentials: 'include',
+        headers: { 'content-type': 'application/json' },
+        method: 'POST',
+      }),
+    )
+    return created.tempo
+  })()
+  const [account] = tempo
+  if (!account) return undefined
+  return Api.tempoAccount(account)
+}
+
+export declare namespace get {
+  /** The user's Tempo Account for the app, or `undefined` when the user has none in its realms. */
+  type ReturnType = TempoAccount | undefined
+}

package/src/client/actions/device.ts

@@ -0,0 +1,151 @@
+/**
+ * Signs a CLI in through the device grant, which the user approves from any browser.
+ * @module
+ */
+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 AccessKey from '../internal/accessKey.js'
+import * as Api from '../internal/api.js'
+import { keyAuthorization } from '../internal/request.js'
+import type * as Key from '../Key.js'
+import type { Permissions } from '../Permissions.js'
+
+/**
+ * Starts the device grant for a CLI: the user approves `userCode` at `verificationUri` from any
+ * browser, and `wait` resolves once they do. The instance's `clientId` names the device app that
+ * the CLI signs in to, such as `tempo-cli`, whose realms the sign-in uses.
+ *
+ * @example
+ * ```ts
+ * const auth = Auth.create({ clientId: 'tempo-cli' })
+ * const device = await Actions.device.authorize(auth)
+ * console.log(`Open ${device.verificationUriComplete}`)
+ * const authorization = await device.wait()
+ * ```
+ */
+export async function authorize<const chainId extends number = number>(
+  auth: Auth,
+  options: authorize.Options<chainId> = {},
+): Promise<authorize.ReturnType<chainId>> {
+  const key = await AccessKey.resolve(options.accessKey)
+  const code = await Api.json<{
+    device_code: string
+    expires_in: number
+    interval: number
+    user_code: string
+    verification_uri: string
+    verification_uri_complete: string
+  }>(
+    await Api.post(auth, '/v1/device/authorize', {
+      json: {
+        ...(options.challenge === undefined
+          ? {}
+          : { challenge: options.challenge }),
+        // The instance's app is the device app that the CLI signs in to, such as `tempo-cli`.
+        client_id: auth.clientId,
+        device: options.device ?? hostname(),
+        key_authorization: keyAuthorization(auth, {
+          accessKey: key.accessKey,
+          permissions: options.permissions,
+        }),
+      },
+    }),
+  )
+
+  /** Polls until the user approves or denies the code, or it expires. */
+  async function wait(): Promise<Authorization<chainId>> {
+    let interval = code.interval
+    const deadline = Date.now() + code.expires_in * 1000
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, interval * 1000))
+      const response = await Api.post(auth, '/v1/device/token', {
+        json: { client_id: auth.clientId, device_code: code.device_code },
+      })
+      const body = (await response.json()) as
+        | (Api.TokenResponse & {
+            account: Key.Key['account']
+            key_authorization: KeyAuthorization.Rpc
+          })
+        | Api.ErrorBody
+      if ('access_token' in body)
+        return Api.authorization<chainId>(
+          {
+            account: body.account,
+            key_authorization: body.key_authorization,
+            tokens: Api.tokens(body),
+          },
+          key,
+        )
+      // RFC 8628 requires a client that receives `slow_down` to add 5 seconds to its interval.
+      if (body.error === 'slow_down') interval += 5
+      else if (body.error !== 'authorization_pending')
+        throw Api.error(body, { status: response.status })
+    }
+    throw new RequestError({
+      code: 'expired_token',
+      message: 'Device code expired. Request a new code.',
+      status: 400,
+    })
+  }
+
+  return {
+    expiresIn: code.expires_in,
+    userCode: code.user_code,
+    verificationUri: code.verification_uri,
+    verificationUriComplete: code.verification_uri_complete,
+    wait,
+  }
+}
+
+export declare namespace authorize {
+  type Options<chainId extends number = number> = {
+    /**
+     * 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.
+     */
+    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
+    /**
+     * The name the approval page shows. Defaults to the machine's hostname in Node, Bun, and Deno,
+     * and to `Unknown device` elsewhere.
+     */
+    device?: string | undefined
+    /** What the CLI's key may do. The approval page shows it beside the device, and the headless ceiling fills what it leaves out. */
+    permissions?: Permissions<chainId> | undefined
+  }
+
+  type ReturnType<chainId extends number = number> = {
+    /** Seconds until the code expires. */
+    expiresIn: number
+    /** The code the user confirms in the browser. */
+    userCode: string
+    /** Where the user enters the code. */
+    verificationUri: string
+    /** Where the user approves the code, with it already filled in. */
+    verificationUriComplete: string
+    /** Resolves with the authorization once the user approves. */
+    wait: () => Promise<Authorization<chainId>>
+  }
+}
+
+/** The part of Node's `process` that {@link hostname} reads. Bun and Deno provide it too. */
+type Process = {
+  getBuiltinModule?: (id: 'node:os') => { hostname: () => string } | undefined
+}
+
+/**
+ * The machine's hostname, within the 64 characters Tempo ID accepts. `getBuiltinModule` loads
+ * `node:os` without an import, which browser and React Native bundlers would fail to resolve.
+ */
+function hostname() {
+  const process = Reflect.get(globalThis, 'process') as Process | undefined
+  const name = process?.getBuiltinModule?.('node:os')?.hostname().trim()
+  return name ? name.slice(0, 64) : 'Unknown device'
+}

package/src/client/actions/email.ts

@@ -0,0 +1,141 @@
+/**
+ * Signs the user in with a code emailed to them, from the app's own sign-in form.
+ * @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'
+
+/**
+ * Emails the user a sign-in code. The response is the same for every address.
+ *
+ * @example
+ * ```ts
+ * await Actions.email.sendCode(auth, { email: 'user@example.com' })
+ * ```
+ */
+export async function sendCode(
+  auth: Auth,
+  options: sendCode.Options,
+): Promise<void> {
+  await Api.json(await Api.post(auth, '/v1/auth/code', { json: options }))
+}
+
+export declare namespace sendCode {
+  type Options = {
+    /** The user's email address. */
+    email: string
+  }
+}
+
+/**
+ * Signs the user in with the code they were emailed, then authorizes the app for the signed-in user.
+ * Only a first-party app authorizes this way. A sign-in with a key creates the user's first Tempo
+ * Account with `POST /v1/account`, then sends `POST /v1/authorize`. The key acts for the account
+ * `accessKey` names, or the app's selected account, or the user's oldest. With `key: false`, the
+ * call returns the tokens and the user alone.
+ *
+ * A refusal after the code verified throws a `RequestError` whose `signedIn` is `true`, since the
+ * user is signed in. A passkey-owned account throws `webauthn_required`, and
+ * `Actions.redirect.start` then authorizes the key on Tempo ID's pages.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.email.signIn(auth, { code, email })
+ * ```
+ */
+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 { code, email, getFn, link } = 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()
+  // The link's passkey signs again, so a page left at the email step links nothing for the next
+  // person, who cannot sign with it.
+  const assertion = await (async () => {
+    if (!link) return undefined
+    const requested = await Api.json<{
+      options: Types.CredentialRequestOptions<true>
+    }>(
+      await Api.post(auth, '/v1/auth/passkey/options', {
+        json: { client_id: auth.clientId, link },
+      }),
+    )
+    const deserialized = Authentication.deserializeOptions(requested.options)
+    return 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 { user } = await Api.json<{ user: { id: string } }>(
+    await Api.post(auth, '/v1/auth/code/verify', {
+      json: { code, email, ...(link ? { assertion, link } : {}) },
+    }),
+  )
+
+  // `key` decides both the type and the runtime value of the result.
+  return (await Headless.authorize(auth, {
+    ...options,
+    userId: 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 6-digit code the user was emailed. */
+    code: string
+    /** The address the code was sent to. */
+    email: string
+    /**
+     * Runs the WebAuthn ceremony of the passkey that `link` names in place of
+     * `navigator.credentials.get`, as for `Actions.passkey.signIn`. Unused without `link`.
+     */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /**
+     * The `link` from `Actions.passkey.signIn`'s email step, which links that wallet.tempo passkey
+     * to the user. The call first runs a ceremony of that passkey, whose assertion Tempo ID requires
+     * with the link.
+     */
+    link?: string | 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 authorization, or the tokens and the user alone with `key: false`. A `boolean` `key`
+   * returns either.
+   */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > = key extends false
+    ? Omit<Authorization<chainId>, 'account' | 'key'>
+    : Authorization<chainId>
+}

package/src/client/actions/oauth.ts

@@ -0,0 +1,182 @@
+/**
+ * Calls Tempo ID's standard OAuth endpoints for tokens an app already holds: introspection, the
+ * user's claims, and the signing keys that verify every token.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+import type { User } from '../User.js'
+
+/**
+ * Checks whether a token is still active at the issuer (RFC 7662). An API verifies access tokens
+ * locally against {@link jwks}, and calls this only where a revoked session must stop working at
+ * once. The instance's client secret authenticates the request, so only a backend calls it.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.oauth.introspect(auth, { token: accessToken })
+ * if (!result.active) return c.json({ error: 'Sign in again.' }, 401)
+ * ```
+ */
+export async function introspect(
+  auth: Auth,
+  options: introspect.Options,
+): Promise<introspect.ReturnType> {
+  const { token, tokenTypeHint } = options
+  const body = await Api.json<{
+    active: boolean
+    client_id?: string | undefined
+    exp?: number | undefined
+    iat?: number | undefined
+    scope?: string | undefined
+    sub?: string | undefined
+  }>(
+    await (auth.fetch ?? fetch)(new URL('/oauth2/introspect', auth.url), {
+      body: new URLSearchParams({
+        client_id: auth.clientId,
+        ...(auth.clientSecret ? { client_secret: auth.clientSecret } : {}),
+        token,
+        ...(tokenTypeHint ? { token_type_hint: tokenTypeHint } : {}),
+      }),
+      method: 'POST',
+    }),
+  )
+  // An inactive token carries no other members (RFC 7662 §2.2).
+  if (!body.active) return { active: false }
+  return {
+    active: true,
+    clientId: body.client_id,
+    expiresAt: body.exp === undefined ? undefined : body.exp * 1000,
+    issuedAt: body.iat === undefined ? undefined : body.iat * 1000,
+    scope: body.scope,
+    userId: body.sub,
+  }
+}
+
+export declare namespace introspect {
+  type Options = {
+    /** The access token or refresh token to check. */
+    token: string
+    /** The kind of token, which speeds up the issuer's lookup. */
+    tokenTypeHint?: 'access_token' | 'refresh_token' | undefined
+  }
+
+  /** Whether the token is active, and the issuer's claims about an active one. */
+  type ReturnType =
+    | {
+        /** The token is expired, revoked, or was never issued. */
+        active: false
+      }
+    | {
+        /** The token is active. */
+        active: true
+        /** The app the token was issued to. */
+        clientId: string | undefined
+        /** When the token expires, in milliseconds. */
+        expiresAt: number | undefined
+        /** When the token was issued, in milliseconds. */
+        issuedAt: number | undefined
+        /** The scopes the token carries, space-separated. */
+        scope: string | undefined
+        /** The user the token names, the `sub` of every token. */
+        userId: string | undefined
+      }
+}
+
+/**
+ * Returns the issuer's JSON Web Key Set, whose keys verify every Tempo ID token. An API passes Tempo
+ * ID's `/oauth2/jwks` URL to a JWT library that caches the set and fetches it again for an unknown
+ * `kid`, such as jose's `createRemoteJWKSet`. An API that caches the set itself also fetches it again
+ * for an unknown `kid`, at most once in a cooldown, since a key rotation signs new tokens with a new
+ * key.
+ *
+ * @example
+ * ```ts
+ * import { createLocalJWKSet, errors, jwtVerify } from 'jose'
+ *
+ * let keys = createLocalJWKSet(await Actions.oauth.jwks(auth))
+ * let fetchedAt = Date.now()
+ * let refetch: Promise<void> | undefined
+ *
+ * async function verify(accessToken: string) {
+ *   try {
+ *     return await jwtVerify(accessToken, keys, { audience, issuer })
+ *   } catch (error) {
+ *     if (!(error instanceof errors.JWKSNoMatchingKey)) throw error
+ *     // A rotation adds a key. Concurrent failures share one fetch, and the cooldown bounds the
+ *     // fetches that forged `kid` values cause.
+ *     if (!refetch) {
+ *       if (Date.now() - fetchedAt < 30_000) throw error
+ *       fetchedAt = Date.now()
+ *       refetch = Actions.oauth
+ *         .jwks(auth)
+ *         .then((set) => {
+ *           keys = createLocalJWKSet(set)
+ *         })
+ *         .finally(() => {
+ *           refetch = undefined
+ *         })
+ *     }
+ *     await refetch
+ *     return await jwtVerify(accessToken, keys, { audience, issuer })
+ *   }
+ * }
+ *
+ * const { payload } = await verify(accessToken)
+ * // Every app's token carries the same audience, so an API also allows each app by `client_id`.
+ * if (!allowedClientIds.includes(String(payload.client_id))) throw forbidden()
+ * ```
+ */
+export async function jwks(auth: Auth): Promise<jwks.ReturnType> {
+  return Api.json<jwks.ReturnType>(
+    await (auth.fetch ?? fetch)(new URL('/oauth2/jwks', auth.url)),
+  )
+}
+
+export declare namespace jwks {
+  /** The key set, in RFC 7517's format, which JWT libraries read as is. */
+  type ReturnType = {
+    /** The issuer's signing keys. */
+    keys: JsonWebKey[]
+  }
+}
+
+/**
+ * Returns the user an access token names, from the issuer's UserInfo endpoint (OIDC Core §5.3).
+ * Access tokens carry no email, so an API that needs it calls this once per user.
+ *
+ * @example
+ * ```ts
+ * const user = await Actions.oauth.userInfo(auth, { accessToken })
+ * // { email: 'user@example.com', id: 'user_…' }
+ * ```
+ */
+export async function userInfo(
+  auth: Auth,
+  options: userInfo.Options,
+): Promise<User> {
+  const response = await (auth.fetch ?? fetch)(
+    new URL('/oauth2/userinfo', auth.url),
+    { headers: { authorization: `Bearer ${options.accessToken}` } },
+  )
+  // RFC 6750 §3 names a rejected bearer token `invalid_token`. The issuer's 401 body uses its own
+  // code, or none, so the refusal always carries the standard one.
+  if (response.status === 401)
+    throw Api.error(
+      {
+        error: 'invalid_token',
+        error_description:
+          'Invalid or expired access token. Refresh the tokens, or sign in again.',
+      },
+      { status: 401 },
+    )
+  const claims = await Api.json<{ email: string; sub: string }>(response)
+  return { email: claims.email, id: claims.sub }
+}
+
+export declare namespace userInfo {
+  type Options = {
+    /** The access token, from any sign-in or refresh. */
+    accessToken: string
+  }
+}