@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/TempoAccount.ts

@@ -0,0 +1,55 @@
+/**
+ * One of a user's Tempo Accounts.
+ * @module
+ */
+/** One of the user's Tempo Accounts. */
+export type TempoAccount = {
+  /**
+   * The address on the request's chain. On a chain with configurable accounts (TIP-1107), an
+   * account that Tempo ID created has its configuration's address. Elsewhere, its owner key's.
+   */
+  address: `0x${string}`
+  /**
+   * Who signs the account's key authorizations: a Privy wallet (`privy`) or a development key
+   * (`secp256k1`), which Tempo ID signs with, or a passkey (`webAuthn`), which signs only on a
+   * Tempo ID page. An account with a cloud wallet among its owners names the cloud wallet. Treat
+   * another value as an owner that may refuse a key authorization.
+   */
+  owner: 'privy' | 'secp256k1' | 'webAuthn' | (string & {})
+  /** The owner keys. A configurable account can have several, such as a passkey and a Privy key. */
+  owners: readonly TempoAccount.Owner[]
+  /** The account's realm. An app reaches only the accounts of its realms. */
+  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
+  }
+}
+
+export declare namespace TempoAccount {
+  /** One owner key of a Tempo Account. */
+  type Owner = {
+    /** The owner key's address. */
+    address: `0x${string}`
+    /** Who holds the key, as for `TempoAccount.owner`. */
+    type: 'privy' | 'secp256k1' | 'webAuthn' | (string & {})
+  }
+}
+
+/**
+ * Instantiates a {@link TempoAccount}.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = TempoAccount.from({
+ *   address: '0x…',
+ *   owner: 'privy',
+ *   owners: [{ address: '0x…', type: '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`, and rotates on each 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 `sub` of every token, such as `user_…`. */
+  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,171 @@
+/**
+ * Reads the signed-in user's Tempo Account for the app, and upgrades a wallet.tempo passkey's
+ * account from the app's page.
+ * @module
+ */
+import { Authentication, type Types } from 'ox/webauthn'
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+import * as Key from '../Key.js'
+import type { TempoAccount } from '../TempoAccount.js'
+
+/**
+ * Returns the user's Tempo Account for the app: the selected one, or the oldest in the app's
+ * realms. For a user without one, it creates a Privy-owned account in the first realm, if that
+ * realm has a Privy app. With `chain`, the address is the account's on that chain.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = await Actions.account.get(auth)
+ * // { address: '0x…', owner: 'webAuthn', owners: [{ address: '0x…', type: 'webAuthn' }], realm: { id: 'default', name: 'Tempo' } }
+ * ```
+ */
+export async function get(
+  auth: Auth,
+  options: get.Options = {},
+): Promise<get.ReturnType> {
+  const { chain } = options
+  const listed = await Api.json<{
+    tempo: readonly Api.TempoAccountResponse[]
+  }>(
+    await (auth.fetch ?? fetch)(
+      new URL(
+        `/v1/account?${new URLSearchParams({
+          ...(chain ? { chain } : {}),
+          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({
+          ...(chain ? { chain } : {}),
+          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 {
+  type Options = {
+    /**
+     * The chain that the app acts on, by its name in `GET /v1/chains`, such as `testnet`. On a
+     * chain with configurable accounts, the address is the configuration's. Absent, the owner key's.
+     */
+    chain?: string | undefined
+  }
+
+  /** The account, or `undefined` when the user has none in the app's realms. */
+  type ReturnType = TempoAccount | undefined
+}
+
+/**
+ * Upgrades a wallet.tempo passkey's account in place to a configurable account (TIP-1113), on the
+ * chain of `key`, from a page that the passkey's relying party covers. The passkey signs once. With
+ * `key`, a key that signed as the passkey's own account, Tempo ID first registers the key through a
+ * transaction that its access key signs and Tempo ID sponsors, so the key keeps working after the
+ * upgrade. The account keeps its address, and the passkey stays its only owner. Call it when a
+ * sign-in or `Actions.authorize` returns `upgradeAvailable: true`.
+ *
+ * Requires a sign-in within the last 10 minutes. An account that is configurable already throws
+ * `owner_exists`.
+ *
+ * @example
+ * ```ts
+ * const { authorization, upgradeAvailable } = await Actions.email.signIn(auth, {
+ *   code,
+ *   email,
+ * })
+ * if (upgradeAvailable)
+ *   await Actions.account.upgrade(auth, { key: authorization.key })
+ * ```
+ */
+export async function upgrade(
+  auth: Auth,
+  options: upgrade.Options,
+): Promise<TempoAccount> {
+  const { chain, getFn, key } = options
+  const account = options.account ?? key?.account
+  // A key without material and without `accessKey` throws here, before the passkey's prompt.
+  const signer = key
+    ? Key.toAccount(key, { accessKey: options.accessKey })
+    : undefined
+  const json = {
+    account,
+    ...(chain ? { chain } : {}),
+    client_id: auth.clientId,
+    ...(key ? { key_authorization: key.keyAuthorization } : {}),
+  }
+  const first = await Api.json<
+    | { account: Api.TempoAccountResponse }
+    | {
+        step: {
+          key?: { digest: `0x${string}` } | undefined
+          options: Types.CredentialRequestOptions<true>
+        }
+      }
+  >(await Api.post(auth, '/v1/account/upgrade', { json }))
+  // An upgrade that the chain holds already returns the account without a step.
+  if ('account' in first) return Api.tempoAccount(first.account)
+
+  const { step } = first
+  const deserialized = Authentication.deserializeOptions(step.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,
+    ),
+  )
+  // The access key signs its registration raw, and Tempo ID wraps the signature for the account.
+  const signature =
+    step.key && signer
+      ? await signer.sign({ hash: step.key.digest, raw: true })
+      : undefined
+  const upgraded = await Api.json<{ account: Api.TempoAccountResponse }>(
+    await Api.post(auth, '/v1/account/upgrade', {
+      json: {
+        ...json,
+        ...(signature ? { key: { signature } } : {}),
+        passkey: { assertion },
+      },
+    }),
+  )
+  return Api.tempoAccount(upgraded.account)
+}
+
+export declare namespace upgrade {
+  type Options = {
+    /** The access key that the app supplied for `key`, when `key` carries no material. */
+    accessKey?: Key.toAccount.Options['accessKey']
+    /** The account to upgrade. Defaults to `key.account`. */
+    account?: `0x${string}` | undefined
+    /**
+     * The chain to upgrade on, by its name in `GET /v1/chains`, such as `testnet`. Defaults to the
+     * chain of `key`, or the first chain whose accounts are configurable.
+     */
+    chain?: string | undefined
+    /** Runs the WebAuthn ceremony in place of `navigator.credentials.get`. */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /**
+     * The key of an authorization with `upgradeAvailable: true`, which the chain registers before
+     * the upgrade. Without it, a key that the passkey signed as its own account stops working.
+     */
+    key?: Key.Key | undefined
+  }
+}

package/src/client/actions/device.ts

@@ -0,0 +1,166 @@
+/**
+ * Signs a CLI in through the device grant, which the user approves from any browser.
+ * @module
+ */
+import { Base64 } from 'ox'
+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 { Permissions } from '../Permissions.js'
+
+/**
+ * Starts the device grant for a CLI. The user approves `userCode` at `verificationUri`, and `wait`
+ * resolves with the authorization. The instance's `clientId` names the device app, 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)
+  // The device authorization request (RFC 8628 §3.1), with the key as base64url JSON.
+  const code = await Api.json<{
+    device_code: string
+    expires_in: number
+    interval: number
+    user_code: string
+    verification_uri: string
+    verification_uri_complete: string
+  }>(
+    await (auth.fetch ?? fetch)(new URL('/device/code', auth.url), {
+      body: new URLSearchParams({
+        ...(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: Base64.fromString(
+          JSON.stringify(
+            keyAuthorization(auth, {
+              accessKey: key.accessKey,
+              permissions: options.permissions,
+            }),
+          ),
+          { pad: false, url: true },
+        ),
+      }),
+      method: 'POST',
+    }),
+  )
+
+  /** 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 body = await Api.token(auth, {
+        device_code: code.device_code,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }).catch((error: unknown) => {
+        // RFC 8628 §3.5: the device polls again until the user decides, and adds 5 seconds to its
+        // interval on `slow_down`.
+        if (!(error instanceof RequestError)) throw error
+        if (error.code === 'slow_down') interval += 5
+        else if (error.code in messages)
+          throw new RequestError({
+            code: error.code,
+            message: messages[error.code as keyof typeof messages],
+            status: error.status,
+          })
+        else if (error.code !== 'authorization_pending') throw error
+        return undefined
+      })
+      if (!body) continue
+      return Api.authorization<chainId>(
+        {
+          account: body.account,
+          key_authorization: body.key_authorization,
+          tokens: Api.tokens(body),
+        },
+        key,
+      )
+    }
+    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. Defaults to a new key. Its `access` names the Tempo Account, which
+     * defaults to the one the user selects at sign-in, 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.
+     */
+    challenge?: string | undefined
+    /**
+     * The name that the approval page shows, up to 64 characters. Defaults to the hostname in Node,
+     * Bun, and Deno, or `Unknown device`.
+     */
+    device?: string | undefined
+    /** What the key may do. The user approves it, so it may exceed the headless ceiling. */
+    permissions?: Permissions<chainId> | undefined
+  }
+
+  type ReturnType<chainId extends number = number> = {
+    /** Seconds until the code expires. */
+    expiresIn: number
+    /** The code that the user confirms. */
+    userCode: string
+    /** Where the user enters the code. */
+    verificationUri: string
+    /** Where the user approves the code, with the code filled in. */
+    verificationUriComplete: string
+    /** Resolves with the authorization once the user approves, and throws on a denial or expiry. */
+    wait: () => Promise<Authorization<chainId>>
+  }
+}
+
+/** The message of each RFC 8628 error that ends the poll, as a CLI shows it. */
+const messages = {
+  access_denied: 'The user denied the request.',
+  expired_token: 'Device code expired. Request a new code.',
+} as const
+
+/** The part of Node's `process` that {@link hostname} reads, which Bun and Deno provide too. */
+type Process = {
+  getBuiltinModule?: (id: 'node:os') => { hostname: () => string } | undefined
+}
+
+/**
+ * Returns the hostname, within the 64 characters that Tempo ID accepts. `getBuiltinModule` avoids
+ * an import of `node:os`, which browser and React Native bundlers 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,164 @@
+/**
+ * Signs the user in with an emailed code, 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 an emailed code, and authorizes a first-party app in the same request. The
+ * key must fit the headless ceiling. A sign-in with a key creates the user's first Tempo Account.
+ *
+ * With `link`, the passkey of `Actions.passkey.signIn`'s email step signs again, and signs the key.
+ * In a browser, a passkey that owns the account signs the key on the page after the code.
+ *
+ * A refusal after the code verified has `signedIn: true`. Outside a browser, and without `getFn`,
+ * an account that a passkey owns throws `webauthn_required`. Another passkey's account, whose
+ * relying party does not cover the page, throws it too. Then authorize through
+ * `Actions.redirect.start`.
+ *
+ * A wallet.tempo passkey's account that waits for its upgrade signs the key as the passkey's own
+ * account, and `upgradeAvailable` is `true`. `Actions.account.upgrade` with the key then upgrades
+ * the account with one more prompt, after Tempo ID registers the key.
+ *
+ * @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 authorization request rides with the sign-in, so one request signs in, creates the first
+  // account, and signs the key. 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. Its options carry the authorization
+  // request, so the same assertion signs the key.
+  const prepared = await Headless.prepare(auth, options)
+  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: { authorize: prepared.authorize, 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 response = await Api.post(auth, '/v1/auth/code/verify', {
+    json: {
+      code,
+      email,
+      ...(link
+        ? { assertion, link }
+        : {
+            authorize: prepared.authorize,
+            // A passkey that owns the account signs the key on this page, in place of a redirect.
+            ...(Headless.steps(prepared.authorize, { getFn })
+              ? { passkey: true }
+              : {}),
+          }),
+    },
+  })
+  // The sign-in authorizes in the same request, after the code signed the user in. `key` decides
+  // both the type and the runtime value of the result.
+  return (await Headless.complete(auth, {
+    body: await Headless.read<{
+      authorization?: Api.Headless | undefined
+      user: { id: string }
+    }>(response),
+    authorize: prepared.authorize,
+    key: prepared.key,
+    request: options,
+  })) as signIn.ReturnType<chainId, key>
+}
+
+export declare namespace signIn {
+  type Options<chainId extends number = number, key extends boolean = true> = {
+    /**
+     * The key to authorize. Defaults to a new key. Its `access` names the Tempo Account, which
+     * defaults to the app's selected account, 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 and a key.
+     */
+    challenge?: ([key] extends [false] ? never : string) | undefined
+    /** The 6-digit code that Tempo ID emailed. */
+    code: string
+    /** The address that received the code. */
+    email: string
+    /**
+     * Runs the ceremony of the passkey that `link` names, or of the passkey that owns the account,
+     * as for `Actions.passkey.signIn`. Defaults to `navigator.credentials.get`.
+     */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /**
+     * The `link` from `Actions.passkey.signIn`'s email step, which links that passkey to the user.
+     * The call first runs the passkey's ceremony.
+     */
+    link?: string | undefined
+    /** Whether to authorize an access key and create a first Tempo Account. Defaults to `true`. */
+    key?: key | undefined
+    /** What the key may do, within the headless ceiling. */
+    permissions?: Permissions<chainId> | undefined
+  }
+
+  /** The authorization, without its key for `key: false`, and whether its account can upgrade. */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > = {
+    /** The authorization, without its key for `key: false`. */
+    authorization: key extends false
+      ? Omit<Authorization<chainId>, 'account' | 'key'>
+      : Authorization<chainId>
+    /**
+     * Whether the key's account is a wallet.tempo passkey's that waits for its upgrade on the key's
+     * chain. `Actions.account.upgrade` with the key upgrades it, and keeps the key.
+     */
+    upgradeAvailable: boolean
+  }
+}