@tempoxyz/auth 0.0.0-pr-67.sha-d4901e4 → 0.0.0-pr-63.sha-1b5c8c2

package/README.md

@@ -1,294 +1,88 @@
 # @tempoxyz/auth
 
-Sign users in to Tempo through Tempo Auth, and get back their tokens for Tempo APIs and a [viem](https://viem.sh) access key account on their Tempo Account.
+Signs users in to Tempo through [Tempo Auth](../../docs/README.md), and returns their tokens for Tempo APIs and a [Viem](https://viem.sh) access key account on their Tempo Account.
 
-Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `accessToken`.
+## Overview
 
 ```ts
 import { Actions, Auth } from '@tempoxyz/auth'
 import { createClient, Expiry, Scopes } from 'viem/tempo'
-import { tempo, tempoTestnet } 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_…' })
+const client = createClient()
+const ousd = Tokens.ousd(client.chain.id).address
 
-const auth = Auth.create({
-  chainId: tempoTestnet.id,
-  clientId: 'client_…',
-  url: 'https://auth.tempo.xyz',
-})
-const client = createClient({
-  chain: tempoTestnet,
-  feeToken: ousd,
-})
+// 1. Email the user a sign-in code.
+await Actions.email.sendCode(auth, { email: 'user@example.com' })
 
-const authorization = await Actions.authorize(auth, {
+// 2. Sign in with the code, and authorize an access key.
+const result = await Actions.email.signIn(auth, {
+  code: '123456',
+  email: 'user@example.com',
   permissions: {
     expiry: Expiry.days(1),
     limits: [{ limit: 10_000_000n, token: ousd }],
     scopes: [Scopes.tip20(ousd).transfer()],
   },
 })
+if ('step' in result) throw new Error('This address signs in through SSO.')
 
+// 3. Call a Tempo API with the session cookie…
+await fetch('https://api.example/me', { credentials: 'include' })
+
+// …or call the Tempo chain with the access key, through Viem.
 await client.token.transferSync({
-  account: authorization!.account,
+  account: result.account,
   amount: 10_000n,
   to: '0x…',
   token: ousd,
 })
 ```
 
-## Install
-
-```bash
-pnpm add @tempoxyz/auth viem
-```
-
-## Before you start
-
-- **Register the app.** Create a WorkOS Connect app in the Tempo Issuer environment, and register every redirect URI it uses. Its `client_id` is the `clientId` that `Auth.create` takes. An app with a backend also receives a client secret.
-- **Allow the app's origin.** Tempo Auth allows the origins of every first-party Connect app's `http(s)` redirect URIs, within about three minutes of a change. A mobile app has no origin, and registers its custom scheme as its redirect URI instead.
-
-The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli` app.
-
-## Access keys
-
-Each sign-in creates a key for the app and requests that Tempo Auth authorize it on the user's Tempo Account. The optional `permissions` option specifies what the key may do, with viem's `Expiry` and `Scopes` helpers. Tempo Auth fills every field it leaves out with the headless ceiling:
-
-| Field     | Meaning                                                                                                     |
-| --------- | ----------------------------------------------------------------------------------------------------------- |
-| `chainId` | The chain the key acts on. Defaults to the instance's `chainId`                                             |
-| `expiry`  | When the key expires, in Unix seconds, such as `Expiry.days(1)`. Defaults to a year                         |
-| `limits`  | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]`. Defaults to about $1,000 of each token the `scopes` call, or of OUSD |
-| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`. Defaults to transfers of each token the key limits |
-
-In a browser, the key is a non-extractable WebCrypto P256 key, so no script can read its private key. A CLI, a native app, or a backend uses a secp256k1 key, which it stores as a string.
-
-To authorize a key the app already holds, pass it as `accessKey`, a viem account. The library never reads its private key. Its `access` names the Tempo Account, which defaults to the user's first:
-
-```ts
-const accessKey = Account.fromWebCryptoP256(keyPair, { access: tempoAccount })
-await Actions.authorize(auth, { accessKey })
-```
-
-Flows without a Tempo Auth page (`authorize`, `email.signIn`) must stay within Tempo Auth's ceiling: about $1,000 per token, for at most a year. [Permissions](../../docs/permissions.md) explains the defaults and the bounds on each flow. Flows with a page (`redirect.start`, `redirect.createUrl`, `device.authorize`) show the limits to the user, who approves them, so they may go beyond it.
-
-The returned `account` attaches the key's authorization to its first transaction, which registers the key on chain.
-
-## Flows
-
-### Your own sign-in UI
-
-For a browser app that renders its own email form. The page calls Tempo Auth with the user's Tempo Auth session, so it works across every app on the same site.
-
-```ts
-// A user already signed in to Tempo Auth, from any app, needs no form.
-const authorization = await Actions.authorize(auth)
-
-// Otherwise, sign in with an emailed code.
-await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { code, email })
-
-// An address that requires SSO continues at its connection, and returns to this page.
-if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
-```
-
-To offer OAuth providers such as Google, list the ones Tempo Auth enables and send the browser to one. It returns to the current page signed in, where `authorize` finishes.
-
-```ts
-const providers = await Actions.provider.list(auth) // [{ id: 'google', name: 'Google' }]
-Actions.provider.signIn(auth, { provider: 'google' })
-```
-
-### Tempo Auth's pages
-
-For a browser app without its own sign-in UI. The browser leaves for Tempo Auth's sign-in page, which shows the key's limits, and returns with a code.
-
-```ts
-await Actions.redirect.start(auth)
-
-// On the page the browser returns to, and on every load:
-const authorization = await Actions.redirect.complete(auth)
-```
-
-`redirect.start` keeps its state, with the new key, in IndexedDB until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere. An app that supplies `accessKey` passes it to `redirect.complete` too.
-
-### A mobile app
-
-For a React Native or Expo app. It calls the same actions as a browser app, with no `Origin`, and opens Tempo Auth's pages in the system browser, which returns to the app's custom scheme. Import `react-native-get-random-values` first, since keys need `crypto.getRandomValues`.
-
-```ts
-import * as WebBrowser from 'expo-web-browser'
-
-const auth = Auth.create({
-  clientId: 'client_…',
-  redirectUri: 'my-app://callback',
-  url: 'https://auth.tempo.xyz',
-})
-
-// Your own sign-in UI, as in a browser.
-await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { code, email })
-
-// Or Tempo Auth's pages, which also offer Google and SSO.
-const { pending, url } = await Actions.redirect.createUrl(auth)
-const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
-if (session.type === 'success')
-  authorization = await Actions.redirect.handleCallback(auth, {
-    pending,
-    url: session.url,
-  })
-```
-
-Keep the authorization in the device's secure store, as [Keep a sign-in](#keep-a-sign-in) describes.
+Every sign-in returns the same `Authorization`: the user, the tokens for Tempo APIs, and the access key, as data in `key` and as a Viem account in `account`. A browser calls Tempo APIs with its session cookie, so its script never handles the access token.
 
-### A backend
+## Usage with Viem
 
-For an app whose server holds a client secret. The server builds the URL, keeps the pending state until the callback, and redeems the code itself.
+`tempoAuth` extends a Viem client with the same actions as `client.auth`. It reads the chain from the client, and each sign-in sets the client's account, so the client sends with the access key.
 
 ```ts
-const auth = Auth.create({ clientId, clientSecret, url })
-
-// GET /auth/start
-const { pending, url } = await Actions.redirect.createUrl(auth, {
-  redirectUri: 'https://app.example/auth/callback',
-})
-// Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
-
-// GET /auth/callback
-const authorization = await Actions.redirect.handleCallback(auth, {
-  pending,
-  url: request.url,
-})
-```
-
-### A CLI
-
-For a command-line tool. The user approves a code in any browser, and the CLI waits.
+import { Auth, tempoAuth } from '@tempoxyz/auth'
+import { createClient, Expiry, Scopes } from 'viem/tempo'
+import * as Tokens from 'viem/tokens'
 
-```ts
-const device = await Actions.device.authorize(auth, {
-  device: os.hostname(),
-})
-console.log(
-  `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
+const client = createClient({ account: Auth.account() }).extend(
+  tempoAuth({ clientId: 'client_…' }),
 )
-const authorization = await device.wait()
-```
-
-## More Tempo Accounts
-
-A user starts with one Tempo Account and can have more. Add one, then name it in the `access` of the key the app authorizes:
-
-```ts
-const tempoAccount = await Actions.tempoAccount.create(auth)
-const accounts = await Actions.tempoAccount.list(auth) // the default first
+const ousd = Tokens.ousd(client.chain.id).address
 
-await Actions.authorize(auth, {
-  accessKey: Account.fromWebCryptoP256(keyPair, {
-    access: tempoAccount.address,
-  }),
+// 1. Sign in, and authorize an access key, which becomes the client's account.
+await client.auth.email.signIn({
+  code: '123456',
+  email: 'user@example.com',
+  permissions: {
+    expiry: Expiry.days(1),
+    limits: [{ limit: 10_000_000n, token: ousd }],
+    scopes: [Scopes.tip20(ousd).transfer()],
+  },
 })
-```
-
-## Keep a sign-in
-
-`Authorization.key` is the app's key as data: the Tempo Account, the signed authorization, and the key the library created. Store it with the tokens, and rebuild the account later with `Key.toAccount`.
-
-- **Browser:** the key is a `CryptoKey` pair, which IndexedDB stores without exporting it.
-- **Elsewhere:** the key is a secp256k1 private key, as JSON. Store it as securely as a session.
-- **Supplied key:** the key holds no material. Pass the `accessKey` again, as `Key.toAccount(saved.key, { accessKey })`.
-
-```ts
-import { Actions, Key } from '@tempoxyz/auth'
-
-if (Key.expired(saved.key)) signInAgain()
 
-const account = Key.toAccount(saved.key)
-const tokens = await Actions.refresh(auth, {
-  refreshToken: saved.refreshToken,
+// 2. Send a transaction with the access key.
+await client.token.transferSync({
+  amount: 10_000n,
+  to: '0x…',
+  token: ousd,
 })
 ```
 
-Refresh tokens rotate, so save the new tokens over the old ones after each refresh, such as `{ ...saved, ...tokens }`.
-
-## Errors
-
-A request Tempo Auth refuses throws `Auth.RequestError`. It carries the OAuth error code as `code`, and `message` states the fault and its fix. `reason`, `field`, and `meta` let an app branch on the refusal and read the values it compared. [Errors](../../docs/errors.md) lists every `reason`.
-
-```ts
-try {
-  await Actions.authorize(auth, { permissions })
-} catch (error) {
-  if (error instanceof Auth.RequestError && error.reason === 'limit_exceeds_maximum')
-    showMaximum(error.meta?.maximum) // in base units
-}
-```
-
-## Reference
-
-### `Auth.create(options)`
-
-| Option         | Meaning                                                                                         |
-| -------------- | ----------------------------------------------------------------------------------------------- |
-| `clientId`     | The app's Connect client ID. Required                                                           |
-| `chainId`      | The chain the app's keys act on, such as `tempoTestnet.id`. Defaults to Tempo mainnet           |
-| `url`          | Where Tempo Auth runs, such as `https://auth.tempo.xyz`. Required                               |
-| `clientSecret` | The app's client secret. Only a backend holds one                                               |
-| `redirectUri`  | Where Tempo Auth redirects back to. Defaults to the page's origin                               |
-| `scope`        | Scopes beyond `openid` and `email`, which every instance includes. Defaults to `offline_access` |
-| `storage`      | Where `redirect.start` keeps its state, without serializing it. Defaults to IndexedDB           |
-| `fetch`        | Calls Tempo Auth. Defaults to the global `fetch`                                                |
-
-The actions call version 1 of Tempo Auth's JSON API, under `/v1`. [API versions](../../docs/versioning.md) describes versions and compatibility.
-
-### `Actions`
-
-Each sign-in flow has its own namespace. The actions every flow shares sit at the top level. Every action that creates a key also takes optional `accessKey` and `permissions`.
-
-| Action                                                   | Returns                                                                    |
-| -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `authorize(auth)`                                        | An `Authorization` for a user already signed in, or `undefined`            |
-| `refresh(auth, { refreshToken })`                        | New `Tokens`                                                               |
-| `signOut(auth)`                                          | Nothing. The user's Tempo Auth session ends                                |
-| `device.authorize(auth, { device })`                     | The code to show and a `wait()` that resolves with an `Authorization`      |
-| `email.sendCode(auth, { email })`                        | Nothing. Tempo Auth emails a code                                          |
-| `email.signIn(auth, { code, email })`                    | An `Authorization`, or the `step` the address requires first               |
-| `provider.list(auth)`                                    | The OAuth providers Tempo Auth offers, as `{ id, name }`                   |
-| `provider.signIn(auth, { provider } \| { url })`         | Nothing. The browser leaves for the provider or SSO connection             |
-| `redirect.complete(auth, { accessKey })`                 | The `Authorization` when the page is a redirect's callback, or `undefined` |
-| `redirect.createUrl(auth, { redirectUri })`              | The `url` to send the browser to, and the `pending` state to keep          |
-| `redirect.handleCallback(auth, { pending, url })`        | The `Authorization` for a redirect's callback                              |
-| `redirect.start(auth)`                                   | Nothing. The browser leaves for Tempo Auth's pages                         |
-| `tempoAccount.create(auth)`                              | Another Tempo Account for the signed-in user                               |
-| `tempoAccount.list(auth)`                                | The signed-in user's Tempo Accounts, the default first                     |
-
-### `Authorization`
-
-| Field          | Meaning                                                                          |
-| -------------- | -------------------------------------------------------------------------------- |
-| `account`      | The user's Tempo Account, as a viem account that signs with the app's access key |
-| `key`          | The same key as data, for `Key.toAccount`                                        |
-| `accessToken`  | The Bearer token Tempo APIs accept                                               |
-| `expiresAt`    | When the access token expires, in milliseconds                                   |
-| `idToken`      | Optional: the OIDC ID token, which names the user                                |
-| `refreshToken` | Optional: exchanges for new tokens through `refresh`. It rotates each time       |
-| `user`         | The user's `email` and `id`, the `sub` of every token                            |
-
-### Types
-
-Each type an action takes or returns lives in its own module, exported beside `Actions`: `Authorization`, `Key`, `Pending`, `Permissions`, `Provider`, `Step`, `Storage`, `TempoAccount`, `Tokens`, and `User`. Each module's `from` builds a value of its type:
-
-```ts
-import { Permissions } from '@tempoxyz/auth'
+## Install
 
-const permissions = Permissions.from({ expiry: Expiry.days(1), limits, scopes })
+```bash
+pnpm add @tempoxyz/auth viem
 ```
 
-### `Key`
+## Documentation
 
-| Function                        | Returns                                                                         |
-| ------------------------------- | ------------------------------------------------------------------------------- |
-| `toAccount(key, { accessKey })` | The key as a viem access key account. `accessKey` is for a key the app supplied |
-| `expired(key)`                  | Whether the key's authorization has expired                                     |
+- [Guides](docs/guides/README.md): each sign-in flow, access keys, sessions, errors, and Viem.
+- [API reference](docs/api/README.md): every action, function, and type.
+- [Tempo Auth](../../docs/README.md): the service the package calls, over HTTP.

package/dist/Actions.d.ts

@@ -1,6 +1,7 @@
 /**
  * Tempo Auth's actions. Each takes an instance from `Auth.create`. Each sign-in flow has its own
- * namespace, and the actions every flow shares sit at the top level.
+ * 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';
@@ -10,6 +11,7 @@ import type { Permissions } from './Permissions.ts';
 import type { Tokens } from './Tokens.ts';
 export * as device from './actions/device.ts';
 export * as email from './actions/email.ts';
+export * as oauth from './actions/oauth.ts';
 export * as provider from './actions/provider.ts';
 export * as redirect from './actions/redirect.ts';
 export * as tempoAccount from './actions/tempoAccount.ts';
@@ -24,19 +26,19 @@ export * as tempoAccount from './actions/tempoAccount.ts';
  * if (!authorization) showSignIn()
  * ```
  */
-export declare function authorize(auth: Auth, options?: authorize.Options): Promise<authorize.ReturnType>;
+export declare function authorize<const chainId extends number = number>(auth: Auth, options?: authorize.Options<chainId>): Promise<authorize.ReturnType<chainId>>;
 export declare namespace authorize {
-    type Options = {
+    type Options<chainId extends number = number> = {
         /**
-         * The key to authorize, as a viem account. Its `access` names the Tempo Account, which
+         * The key to authorize, as a Viem account. Its `access` names the Tempo Account, which
          * defaults to the user's first. Defaults to a new key.
          */
         accessKey?: Account.Account | undefined;
         /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        permissions?: Permissions<chainId> | undefined;
     };
     /** The authorization, or `undefined` without a session. */
-    type ReturnType = Authorization | undefined;
+    type ReturnType<chainId extends number = number> = Authorization<chainId> | undefined;
 }
 /**
  * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.

package/dist/Actions.js

@@ -3,6 +3,7 @@ import * as Api from './internal/api.js';
 import { request } from './internal/request.js';
 export * as device from './actions/device.js';
 export * as email from './actions/email.js';
+export * as oauth from './actions/oauth.js';
 export * as provider from './actions/provider.js';
 export * as redirect from './actions/redirect.js';
 export * as tempoAccount from './actions/tempoAccount.js';

package/dist/Auth.d.ts

@@ -1,4 +1,41 @@
+/**
+ * A Tempo Auth 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/auth'
+ * 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 * as AccountState from './internal/account.ts';
 import type { Storage } from './Storage.ts';
+/**
+ * The account of a client extended with `tempoAuth`: 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 `tempoAuth` extension reads. */
+    readonly [AccountState.key]: AccountState.State;
+};
 /** A Tempo Auth instance, which every action takes. */
 export type Auth = {
     /** The chain the app's keys act on, unless an action's `permissions` names another. */
@@ -51,23 +88,52 @@ export declare namespace RequestError {
     /** Each refusal's stable name. `docs/errors.md` explains each one. */
     type Reason = 'already_decided' | 'approval_pending' | 'body_too_large' | 'cross_site_request' | 'device_code_expired' | 'duplicate_limit' | 'empty_limits' | 'empty_scopes' | 'expiry_exceeds_maximum' | 'expiry_passed' | 'foreign_account' | 'foreign_origin' | 'invalid_chain' | 'invalid_code' | 'invalid_expiry' | 'invalid_field' | 'invalid_origin' | 'invalid_public_key' | 'limit_exceeds_maximum' | 'malformed_body' | 'missing_code_challenge' | 'missing_key' | 'missing_recipients' | 'periodic_limit' | 'polling_too_fast' | 'rate_limited' | 'rejected' | 'request_denied' | 'scope_without_limit' | 'session_required' | 'unexpected' | 'unknown_code' | 'unknown_endpoint' | 'unsupported_call' | 'unsupported_step' | 'unsupported_token' | 'upstream_unavailable' | 'webauthn_rejected';
 }
+/** A client's {@link Account} read before a sign-in set it, or after sign-out emptied it. */
+export declare class SignedOutError extends Error {
+    readonly name = "Auth.SignedOutError";
+    constructor();
+}
+/**
+ * Creates the account of a client extended with `tempoAuth`. 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(tempoAuth({ clientId: 'client_…' }))
+ * ```
+ */
+export declare function account(): Account;
 /**
  * Creates a Tempo Auth instance.
  *
  * @example
  * ```ts
- * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
+ * const auth = Auth.create({ clientId: 'client_…' })
  * ```
  */
 export declare function create(options: create.Options): Auth;
 export declare namespace create {
-    type Options = Omit<Auth, 'chainId' | 'scope'> & {
-        /** The chain the app's keys act on, such as `tempoTestnet.id`. Defaults to Tempo mainnet. */
+    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 Auth's development deployment, `https://auth.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 Auth runs. Defaults to `https://auth.tempo.xyz`, or `https://auth.tehq.dev` with `dev`. */
+        url?: string | undefined;
     };
 }

package/dist/Auth.js

@@ -1,34 +1,5 @@
-/**
- * A Tempo Auth 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/auth'
- * import { Expiry, Scopes } from 'viem/tempo'
- * import { tempo, tempoTestnet } from 'viem/tempo/chains'
- * import * as Tokens from 'viem/tokens'
- *
- * const ousd = Tokens.ousd(tempo.id).address
- *
- * const auth = Auth.create({
- *   chainId: tempoTestnet.id,
- *   clientId: 'client_…',
- *   url: 'https://auth.tempo.xyz',
- * })
- *
- * 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 { tempo } from 'viem/tempo/chains';
+import { tempo, tempoTestnet } from 'viem/tempo/chains';
+import * as AccountState from './internal/account.js';
 /** A request Tempo Auth refused, with its status and message. */
 export class RequestError extends Error {
     name = 'Auth.RequestError';
@@ -54,20 +25,75 @@ export class RequestError extends Error {
         this.uri = options.uri;
     }
 }
+/** A client's {@link Account} read before a sign-in set it, or after sign-out emptied it. */
+export class SignedOutError extends Error {
+    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 `tempoAuth`. 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(tempoAuth({ clientId: 'client_…' }))
+ * ```
+ */
+export function account() {
+    const state = { account: undefined };
+    // Viem reads a client's account only when an action runs, through property reads, `in` checks,
+    // and spreads, so each trap reads through to the account 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;
+}
 /**
  * Creates a Tempo Auth instance.
  *
  * @example
  * ```ts
- * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
+ * const auth = Auth.create({ clientId: 'client_…' })
  * ```
  */
 export function create(options) {
+    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 = (options.scope ?? 'offline_access').split(' ').filter(Boolean);
+    const scopes = scope.split(' ').filter(Boolean);
     return {
-        ...options,
-        chainId: options.chainId ?? tempo.id,
+        ...rest,
+        chainId: chainId ?? (dev ? tempoTestnet.id : tempo.id),
         scope: [...new Set(['openid', 'email', ...scopes])].join(' '),
+        url: url ?? (dev ? urls.dev : urls.production),
     };
 }
+/** Where Tempo Auth runs unless `create` receives a `url`. */
+const urls = {
+    dev: 'https://auth.tehq.dev',
+    production: 'https://auth.tempo.xyz',
+};

package/dist/Authorization.d.ts

@@ -5,12 +5,15 @@
 import type * as Key from './Key.ts';
 import type { Tokens } from './Tokens.ts';
 import type { User } from './User.ts';
-/** What every sign-in returns: the app's tokens for Tempo APIs, with its access key and the user. */
-export type Authorization = Tokens & {
-    /** The user's Tempo Account, as a viem account that signs with the app's access key. */
+/**
+ * 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;
+    key: Key.Key<chainId>;
     /** The signed-in user, from the ID token. */
     user: User;
 };
@@ -22,4 +25,4 @@ export type Authorization = Tokens & {
  * const authorization = Authorization.from({ ...saved, account: Key.toAccount(saved.key) })
  * ```
  */
-export declare function from(value: Authorization): Authorization;
+export declare function from<chainId extends number = number>(value: Authorization<chainId>): Authorization<chainId>;