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

package/src/client/internal/accessKey.ts

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

package/src/client/internal/account.ts

@@ -0,0 +1,15 @@
+/**
+ * The state behind `Auth.account()`: the access key account a sign-in set, which the account reads
+ * through to. The `tempoId` extension reads and writes it through {@link key}.
+ * @module
+ */
+import type { Account } from 'viem/tempo'
+
+/** The property that holds an `Auth.account()`'s state. Other accounts lack it. */
+export const key = Symbol('tempo-id.account')
+
+/** What an `Auth.account()` signs as. */
+export type State = {
+  /** The signed-in access key account, or `undefined` while signed out. */
+  account: Account.AccessKeyAccount | undefined
+}

package/src/client/internal/api.ts

@@ -0,0 +1,224 @@
+/**
+ * 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 what Tempo ID returned and the sign-in's key: the material the
+ * library generated, or the `accessKey` the app supplied. `chainId` is the chain the request named,
+ * which the key authorization repeats.
+ */
+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 when the request asked for a key. */
+  account?: Key.Key['account'] | undefined
+  /** The signed key authorization, in the node's RPC format, present when the request asked for a key. */
+  key_authorization?: KeyAuthorization.Rpc | undefined
+  /** The tokens the sign-in issued, as the token endpoint returns them or already read into `Tokens`. */
+  tokens: TokenResponse | Tokens
+}
+
+/** Reads a JSON response, and throws a {@link RequestError} for a refused request. */
+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
+}
+
+/** A {@link RequestError} from an OAuth error response, or from a refusal with no 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',
+  })
+}
+
+/** Calls Tempo ID's OAuth token endpoint with a standard OAuth form post, adding the client and any 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, the type of its owner, which the API lists first, and its realm. */
+export function tempoAccount(account: TempoAccountResponse): TempoAccount {
+  return {
+    address: account.address,
+    owner: account.config.owners[0].type,
+    realm: { id: account.realm.id, name: account.realm.name },
+  }
+}
+
+/** A Tempo Account as the API returns it, with the fields the package reads. */
+export type TempoAccountResponse = {
+  /** The account's address, the same on every Tempo chain. */
+  address: `0x${string}`
+  /** The account's configuration, whose owners the API lists in order. */
+  config: {
+    /** The account's owners, each with the kind of key that holds it, such as `privy` or `webAuthn`. */
+    owners: readonly [{ type: string }, ...{ type: string }[]]
+  }
+  /** The realm the account belongs to, with its display name. */
+  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
+  }
+}
+
+/** What Tempo ID's token endpoint returns. Redeeming a redirect's code adds its key authorization. */
+export type TokenResponse = {
+  /** The access token, which authorizes the app's requests to its APIs. */
+  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 with the code, 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`, which every sign-in returns. */
+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 that came after a sign-in's code or passkey verified as a {@link RequestError}
+ * marked `signedIn`, since the user is signed in. A failure without a response, such as a network
+ * error, has status 0 and the original error 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({
+    code: error.code,
+    field: error.field,
+    message: error.message,
+    meta: error.meta,
+    reason: error.reason,
+    signedIn: true,
+    status: error.status,
+    uri: error.uri,
+  })
+}
+
+/** Reads what Tempo ID returned for 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_) }
+}
+
+/** What an authorization without a key returns: the tokens and the user. */
+export type WithoutKey = Omit<Authorization, 'account' | 'key'>

package/src/client/internal/headless.ts

@@ -0,0 +1,77 @@
+/**
+ * Authorizes the app for the user whom a headless sign-in just signed in, for `Actions.email.signIn`
+ * and `Actions.passkey.signIn`.
+ * @module
+ */
+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'
+
+/**
+ * Sends `POST /v1/account`, which creates the user's first Tempo Account and returns the existing
+ * ones unchanged, then `POST /v1/authorize`. A sign-in without a key needs no account, so it sends
+ * the authorization alone. Each refusal is marked `signedIn`, since the user is signed in. An
+ * authorization for another user than `userId` throws `session_changed`, since another sign-in
+ * replaced the session in between.
+ */
+export async function authorize(
+  auth: Auth,
+  options: authorize.Options,
+): Promise<Authorization | Api.WithoutKey> {
+  const { challenge, 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 Api.post(auth, '/v1/authorize', {
+        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 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,
+      })
+    return authorization
+  } 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 the key's witness binds. */
+    challenge?: string | undefined
+    /** Whether the sign-in authorizes an access key. Defaults to `true`. */
+    key?: boolean | undefined
+    /** What the key may do. */
+    permissions?: Permissions | undefined
+    /** The ID of the user whom the sign-in verified. */
+    userId: string
+  }
+}

package/src/client/internal/indexedDb.ts

@@ -0,0 +1,44 @@
+/**
+ * The default `storage` in a browser: IndexedDB, which keeps a non-extractable `CryptoKey` without
+ * exporting it.
+ * @module
+ */
+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,71 @@
+/**
+ * Builds the authorization and key authorization requests the actions send, in Tempo ID's wire
+ * format. The root type check holds them to Tempo ID's routes.
+ * @module
+ */
+import { Hex } from 'ox'
+import type { Account } from 'viem/tempo'
+import type { Auth } from '../Auth.js'
+import type { Permissions } from '../Permissions.js'
+
+/**
+ * The authorization request, with the key authorization request when the sign-in requests a key, in
+ * Tempo ID's wire format.
+ */
+export function request(
+  auth: Auth,
+  options: {
+    /** The key to authorize. Without one, the request carries no key authorization. */
+    accessKey?: Account.Account | undefined
+    /** The user's Tempo Account the key acts for, in place of the one `accessKey` names. */
+    account?: `0x${string}` | undefined
+    /** A message 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,
+  }
+}
+
+/**
+ * The key authorization request, in Tempo ID's wire format. An access key account names its Tempo
+ * Account through `access`, and a plain key leaves it to Tempo ID.
+ */
+export function keyAuthorization(
+  auth: Auth,
+  options: {
+    /** The key to authorize. */
+    accessKey: Account.Account
+    /** The user's 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: the instance's `storage`, or IndexedDB.
+ * @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 the page's IndexedDB. Returns `undefined` outside a browser
+ * when the instance names no `storage`.
+ */
+export function get(auth: Auth) {
+  if (auth.storage) return auth.storage
+  if (typeof indexedDB === 'undefined') return undefined
+  return (indexedDb ??= IndexedDb.create())
+}

package/src/client.ts

@@ -0,0 +1,19 @@
+/**
+ * The client for apps that sign users in through Tempo ID. It returns Viem access key accounts on
+ * their Tempo Accounts, and imports nothing from the server code.
+ * @module
+ */
+export * as Actions from './client/Actions.js'
+export * as Auth from './client/Auth.js'
+export * as Authorization from './client/Authorization.js'
+export * as Decorator from './client/Decorator.js'
+export { tempoId } from './client/Decorator.js'
+export * as Key from './client/Key.js'
+export * as Pending from './client/Pending.js'
+export * as Permissions from './client/Permissions.js'
+export * as Provider from './client/Provider.js'
+export * as Step from './client/Step.js'
+export * as Storage from './client/Storage.js'
+export * as TempoAccount from './client/TempoAccount.js'
+export * as Tokens from './client/Tokens.js'
+export * as User from './client/User.js'

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Types that Tempo ID's client, server, and admin entry points share. The entry points arrive in the
+ * phases of `.agents/plans/rewrite.md`.
+ * @module
+ */
+export {}