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

package/src/cli/commands/whoami.ts

@@ -0,0 +1,23 @@
+/**
+ * `tempo-id whoami`: shows the signed-in user's email and the Tempo Account of the stored access
+ * key, with the access token refreshed when it expires.
+ * @module
+ */
+import { Cli } from 'incur'
+import * as User from '../User.js'
+
+export default Cli.command({
+  description: 'Show the signed-in user and Tempo Account.',
+  env: User.env,
+  async run(c) {
+    const Session = await User.loadSession()
+    if (!Session) return c.error(User.missingPeers)
+
+    const user = await Session.whoami({
+      home: c.env.TEMPO_HOME,
+      url: c.env.TEMPO_ID_URL,
+    })
+    if (!user) return c.error(User.signedOut)
+    return user
+  },
+})

package/src/client/Actions.ts

@@ -0,0 +1,168 @@
+/**
+ * Tempo ID's actions. Each takes an instance from `Auth.create`. Each sign-in flow has its own
+ * namespace, `oauth` holds the standard OAuth endpoints for tokens an app holds, and the actions
+ * every flow shares sit at the top level.
+ * @module
+ */
+import type { Account } from 'viem/tempo'
+import { type Auth, ChallengeWithoutKeyError } from './Auth.js'
+import type { Authorization } from './Authorization.js'
+import * as AccessKey from './internal/accessKey.js'
+import * as Api from './internal/api.js'
+import { request } from './internal/request.js'
+import type { Permissions } from './Permissions.js'
+import type { Tokens } from './Tokens.js'
+
+export * as account from './actions/account.js'
+export * as device from './actions/device.js'
+export * as email from './actions/email.js'
+export * as oauth from './actions/oauth.js'
+export * as passkey from './actions/passkey.js'
+export * as provider from './actions/provider.js'
+export * as realm from './actions/realm.js'
+export * as redirect from './actions/redirect.js'
+
+/**
+ * Authorizes a first-party app, which skips consent, for a user already signed in to Tempo ID, with
+ * `POST /v1/authorize`, from a page on its redirect URI's origin. Any other app fails with
+ * `rejected`, and authorizes through a redirect. Returns `undefined` without a session, so the app
+ * shows sign-in. The key must fit Tempo ID's headless ceiling. An `account` that the call names
+ * becomes the app's account for its later requests. With `key: false`, the call returns the tokens
+ * and the user alone.
+ *
+ * A user who holds no Tempo Account in the app's realms receives `rejected`, since the call creates
+ * none. `Actions.account.get` creates the first one.
+ *
+ * Throws a `RequestError` with reason `webauthn_required` when a passkey owns the account, since a
+ * passkey signs a key only on a page that shows it. `Actions.redirect.start` then authorizes the
+ * key on Tempo ID's pages.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.authorize(auth)
+ * if (!authorization) showSignIn()
+ * ```
+ */
+export async function authorize<
+  const chainId extends number = number,
+  const key extends boolean = true,
+>(
+  auth: Auth,
+  options: authorize.Options<chainId, key> = {},
+): Promise<authorize.ReturnType<chainId, key>> {
+  // A challenge rides in the key, so a call without one refuses it before any request.
+  if (options.key === false && options.challenge !== undefined)
+    throw new ChallengeWithoutKeyError()
+
+  // Checking the session first avoids a failed request for a visitor without one.
+  const session = await Api.json<{ user: unknown }>(
+    await (auth.fetch ?? fetch)(new URL('/v1/auth/session', auth.url), {
+      credentials: 'include',
+    }),
+  )
+  if (!session.user) return undefined
+
+  const key =
+    options.key === false
+      ? undefined
+      : await AccessKey.resolve(options.accessKey)
+  const response = await Api.post(auth, '/v1/authorize', {
+    json: request(auth, {
+      accessKey: key?.accessKey,
+      account: options.account,
+      challenge: options.challenge,
+      permissions: options.permissions,
+    }),
+  })
+  // The session can end between the two requests.
+  if (response.status === 401) return undefined
+  const body = await Api.json<Api.Headless>(response)
+  // `key` decides both the type and the runtime value of the result.
+  return (
+    key ? Api.authorization(body, key) : Api.withoutKey(body)
+  ) as authorize.ReturnType<chainId, key>
+}
+
+export declare namespace authorize {
+  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
+    /**
+     * The address of the user's Tempo Account the key acts for, such as the one that
+     * `Actions.account.get` returns. Takes the place of `accessKey`'s `access`, and becomes
+     * the app's account for its later requests that name none.
+     */
+    account?: `0x${string}` | 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
+    /**
+     * Whether the call authorizes an access key. With `false`, it 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. `undefined` without a session.
+   */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > =
+    | (key extends false
+        ? Omit<Authorization<chainId>, 'account' | 'key'>
+        : Authorization<chainId>)
+    | undefined
+}
+
+/**
+ * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.
+ *
+ * @example
+ * ```ts
+ * const tokens = await Actions.refresh(auth, {
+ *   refreshToken: saved.refreshToken,
+ * })
+ * ```
+ */
+export async function refresh(
+  auth: Auth,
+  options: refresh.Options,
+): Promise<Tokens> {
+  return Api.tokens(
+    await Api.token(auth, {
+      grant_type: 'refresh_token',
+      refresh_token: options.refreshToken,
+    }),
+  )
+}
+
+export declare namespace refresh {
+  type Options = {
+    /** The latest refresh token. Each refresh rotates it. */
+    refreshToken: string
+  }
+}
+
+/**
+ * Ends the user's Tempo ID session, which signs them out of every app that relies on it.
+ *
+ * @example
+ * ```ts
+ * await Actions.signOut(auth)
+ * ```
+ */
+export async function signOut(auth: Auth): Promise<void> {
+  // A JSON body keeps the request out of Tempo ID's CSRF check for cross-site form posts.
+  await Api.json(await Api.post(auth, '/v1/auth/logout', { json: {} }))
+}

package/src/client/Auth.ts

@@ -0,0 +1,285 @@
+/**
+ * A Tempo ID instance, which every action takes. Create one with {@link create}, then pass it
+ * to each action in `Actions`. Every sign-in returns an `Authorization`: the user's tokens and a
+ * Viem access key account.
+ *
+ * @example
+ * ```ts
+ * import { Actions, Auth } from '@tempoxyz/id/client'
+ * import { Expiry, Scopes } from 'viem/tempo'
+ * import { tempo } from 'viem/tempo/chains'
+ * import * as Tokens from 'viem/tokens'
+ *
+ * // OUSD has its mainnet address on every Tempo chain.
+ * const ousd = Tokens.ousd(tempo.id).address
+ *
+ * const auth = Auth.create({ clientId: 'client_…', dev: true })
+ *
+ * const authorization = await Actions.authorize(auth, {
+ *   permissions: {
+ *     expiry: Expiry.days(1),
+ *     limits: [{ limit: 10_000_000n, token: ousd }],
+ *     scopes: [Scopes.tip20(ousd).transfer()],
+ *   },
+ * })
+ * ```
+ * @module
+ */
+import type { Account as ViemAccount } from 'viem/tempo'
+import { tempo, tempoTestnet } from 'viem/tempo/chains'
+import * as AccountState from './internal/account.js'
+import type { Storage } from './Storage.js'
+
+/**
+ * The account of a client extended with `tempoId`: an access key account that each sign-in sets
+ * and sign-out empties. Reading it while signed out throws {@link SignedOutError}.
+ */
+export type Account = ViemAccount.AccessKeyAccount & {
+  /** What the account signs as, which only the `tempoId` extension reads. */
+  readonly [AccountState.key]: AccountState.State
+}
+
+/** A Tempo ID instance, which every action takes. */
+export type Auth = {
+  /** The chain the app's keys act on, unless an action's `permissions` names another. */
+  chainId: number
+  /** The app's client ID, from its registration as an OAuth app in Tempo ID. */
+  clientId: string
+  /** The app's client secret. Only a backend holds one. */
+  clientSecret?: string | undefined
+  /** Calls Tempo ID. Defaults to the global `fetch`. */
+  fetch?: typeof globalThis.fetch | undefined
+  /** Where Tempo ID redirects back to. Defaults to the page's origin in a browser. */
+  redirectUri?: string | undefined
+  /** The scopes the app's tokens carry. */
+  scope: string
+  /**
+   * Where `Actions.redirect.start` keeps its state until Tempo ID redirects back. It must keep
+   * objects as they are, since a browser key is a `CryptoKey`. Defaults to IndexedDB.
+   */
+  storage?: Storage | undefined
+  /** Where Tempo ID runs, such as `https://id.tempo.xyz`. */
+  url: string
+}
+
+/** An action received a `challenge` with `key: false`, and a challenge rides in a key. */
+export class ChallengeWithoutKeyError extends Error {
+  override readonly name = 'Auth.ChallengeWithoutKeyError'
+
+  constructor() {
+    super(
+      'A challenge rides in the key authorization, so a sign-in with `key: false` takes none. Remove `challenge`, or request a key.',
+    )
+  }
+}
+
+/** A request Tempo ID refused, with its status and message. */
+export class RequestError extends Error {
+  override readonly name = 'Auth.RequestError'
+  /** The OAuth error code, such as `invalid_authorization_details`. */
+  readonly code: string
+  /** The request field at fault, as a dotted path. */
+  readonly field: string | undefined
+  /** The values the refusal compared, such as `limit` and `maximum`. Base units are decimal strings. */
+  readonly meta: Readonly<Record<string, number | string>> | undefined
+  /** A stable name for the refusal, to branch on. */
+  readonly reason: RequestError.Reason | undefined
+  /**
+   * Whether a sign-in's code or passkey verified before Tempo ID refused the authorization, so the
+   * user is signed in. `false` for every other refusal.
+   */
+  readonly signedIn: boolean
+  /** The HTTP status of Tempo ID's response, or 0 for a request that received none. */
+  readonly status: number
+  /** The page that explains the error. */
+  readonly uri: string | undefined
+
+  constructor(options: RequestError.Options) {
+    super(options.message, { cause: options.cause })
+    this.code = options.code
+    this.field = options.field
+    this.meta = options.meta
+    this.reason = options.reason
+    this.signedIn = options.signedIn ?? false
+    this.status = options.status
+    this.uri = options.uri
+  }
+}
+
+export declare namespace RequestError {
+  type Options = {
+    /** The error that caused this one, such as a network failure. */
+    cause?: unknown
+    /** The OAuth error code, such as `invalid_authorization_details`. */
+    code: string
+    /** The request field at fault, as a dotted path. */
+    field?: string | undefined
+    /** The fault and its fix, from `error_description`. */
+    message: string
+    /** The values the refusal compared, such as `limit` and `maximum`. Base units are decimal strings. */
+    meta?: Readonly<Record<string, number | string>> | undefined
+    /** A stable name for the refusal, to branch on. Absent from the issuer's own errors. */
+    reason?: Reason | undefined
+    /** Whether a sign-in's code or passkey verified before the refusal. Defaults to `false`. */
+    signedIn?: boolean | undefined
+    /** The HTTP status of Tempo ID's response. */
+    status: number
+    /** The page that explains the error, from `error_uri`. */
+    uri?: string | undefined
+  }
+
+  /** Each refusal's stable name. `docs/errors.md` explains each one. */
+  type Reason =
+    | 'already_decided'
+    | 'approval_pending'
+    | 'authorization_expired'
+    | 'body_too_large'
+    | 'challenge_not_permitted'
+    | 'cross_site_request'
+    | 'device_code_expired'
+    | 'duplicate_limit'
+    | 'duplicate_scope'
+    | 'empty_limits'
+    | 'empty_scopes'
+    | 'expiry_exceeds_maximum'
+    | 'expiry_passed'
+    | 'foreign_account'
+    | 'foreign_origin'
+    | 'invalid_chain'
+    | 'invalid_code'
+    | 'invalid_expiry'
+    | 'invalid_field'
+    | 'invalid_id_token_hint'
+    | 'invalid_origin'
+    | 'invalid_period'
+    | 'invalid_public_key'
+    | 'invalid_recipients'
+    | 'limit_exceeds_maximum'
+    | 'logout_not_permitted'
+    | 'malformed_body'
+    | 'missing_code_challenge'
+    | 'missing_key'
+    | 'missing_recipients'
+    | 'passkey_link_expired'
+    | 'passkey_not_permitted'
+    | 'post_logout_redirect_not_permitted'
+    | 'polling_too_fast'
+    | 'rate_limited'
+    | 'rejected'
+    | 'request_denied'
+    | 'return_to_not_permitted'
+    | 'scope_without_limit'
+    | 'session_changed'
+    | 'session_required'
+    | 'unexpected'
+    | 'unknown_code'
+    | 'unknown_endpoint'
+    | 'unknown_provider'
+    | 'unsupported_call'
+    | 'unsupported_token'
+    | 'upstream_unavailable'
+    | 'webauthn_rejected'
+    | 'webauthn_required'
+}
+
+/** A client's {@link Account} read before a sign-in set it, or after sign-out emptied it. */
+export class SignedOutError extends Error {
+  override readonly name = 'Auth.SignedOutError'
+
+  constructor() {
+    super(
+      "The client's account is signed out. Sign in through `client.auth` before sending.",
+    )
+  }
+}
+
+/**
+ * Creates the account of a client extended with `tempoId`. It holds no key until a sign-in sets
+ * it, and reading it before then throws {@link SignedOutError}, so a transaction fails before it
+ * reaches the node. Each client needs its own, since the account signs as one user.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({
+ *   account: Auth.account(),
+ *   chain: tempoTestnet,
+ * }).extend(tempoId({ clientId: 'client_…' }))
+ * ```
+ */
+export function account(): Account {
+  const state: AccountState.State = { account: undefined }
+  // Viem reads a client's account only when an action runs, through property reads, `in` checks,
+  // and spreads. Each trap reads through to the account that the latest sign-in set.
+  const proxy = new Proxy(
+    {},
+    {
+      get(_, key) {
+        if (key === AccountState.key) return state
+        if (state.account) return Reflect.get(state.account, key)
+        // Promise resolution, serialization, and inspection probe these, which must not throw.
+        if (typeof key === 'symbol' || key === 'then' || key === 'toJSON')
+          return undefined
+        throw new SignedOutError()
+      },
+      getOwnPropertyDescriptor(_, key) {
+        if (!state.account) return undefined
+        const descriptor = Reflect.getOwnPropertyDescriptor(state.account, key)
+        // A proxy may report a property its empty target lacks only as configurable.
+        return descriptor && { ...descriptor, configurable: true }
+      },
+      has: (_, key) =>
+        key === AccountState.key ||
+        (state.account !== undefined && Reflect.has(state.account, key)),
+      ownKeys: () => (state.account ? Reflect.ownKeys(state.account) : []),
+    },
+  )
+  return proxy as Account
+}
+
+/**
+ * Creates a Tempo ID instance.
+ *
+ * @example
+ * ```ts
+ * const auth = Auth.create({ clientId: 'client_…' })
+ * ```
+ */
+export function create(options: create.Options): Auth {
+  const { chainId, dev, scope = 'offline_access', url, ...rest } = options
+  // Every authorization reads the user from the ID token, which needs `openid` and `email`.
+  const scopes = scope.split(' ').filter(Boolean)
+  return {
+    ...rest,
+    chainId: chainId ?? (dev ? tempoTestnet.id : tempo.id),
+    scope: [...new Set(['openid', 'email', ...scopes])].join(' '),
+    url: url ?? (dev ? urls.dev : urls.production),
+  }
+}
+
+export declare namespace create {
+  type Options = Omit<Auth, 'chainId' | 'scope' | 'url'> & {
+    /**
+     * The chain the app's keys act on, such as `client.chain.id`. Defaults to Tempo mainnet, or to
+     * Tempo testnet with `dev`.
+     */
+    chainId?: number | undefined
+    /**
+     * Whether to use Tempo ID's development deployment, `https://id.tehq.dev`, with keys on
+     * Tempo testnet unless `chainId` names another chain. Defaults to `false`.
+     */
+    dev?: boolean | undefined
+    /**
+     * Scopes the app's tokens carry beyond `openid` and `email`, which every instance includes.
+     * Defaults to `offline_access`, for a refresh token.
+     */
+    scope?: string | undefined
+    /** Where Tempo ID runs. Defaults to `https://id.tempo.xyz`, or `https://id.tehq.dev` with `dev`. */
+    url?: string | undefined
+  }
+}
+
+/** Where Tempo ID runs unless `create` receives a `url`. */
+const urls = {
+  dev: 'https://id.tehq.dev',
+  production: 'https://id.tempo.xyz',
+} as const

package/src/client/Authorization.ts

@@ -0,0 +1,34 @@
+/**
+ * What every sign-in returns: the app's tokens for Tempo APIs, its access key, and the user.
+ * @module
+ */
+import type * as Key from './Key.js'
+import type { Tokens } from './Tokens.js'
+import type { User } from './User.js'
+
+/**
+ * What every sign-in returns: the app's tokens for Tempo APIs, with its access key and the user.
+ * `chainId` is the key's chain, as a literal type when the sign-in's `permissions` named one.
+ */
+export type Authorization<chainId extends number = number> = Tokens & {
+  /** The user's Tempo Account, as a Viem account that signs with the app's access key. */
+  account: ReturnType<typeof Key.toAccount>
+  /** The same key as data, for apps that store it and rebuild it with `Key.toAccount`. */
+  key: Key.Key<chainId>
+  /** The signed-in user, from the ID token. */
+  user: User
+}
+
+/**
+ * Instantiates a {@link Authorization}.
+ *
+ * @example
+ * ```ts
+ * const authorization = Authorization.from({ ...saved, account: Key.toAccount(saved.key) })
+ * ```
+ */
+export function from<chainId extends number = number>(
+  value: Authorization<chainId>,
+): Authorization<chainId> {
+  return value
+}