@tempoxyz/auth 0.0.0-pr-22.sha-291bbcb → 0.0.0-pr-25.sha-5404a24

package/README.md

@@ -10,6 +10,7 @@ import { Addresses, createClient, Expiry, Scopes } from 'viem/tempo'
 import { tempoTestnet } from 'viem/tempo/chains'
 
 const auth = Auth.create({
+  chainId: tempoTestnet.id,
   clientId: 'client_…',
   url: 'https://auth.tempo.xyz',
 })
@@ -19,8 +20,7 @@ const client = createClient({
 })
 
 const authorization = await Actions.authorize(auth, {
-  accessKey: {
-    chainId: tempoTestnet.id,
+  permissions: {
     expiry: Expiry.days(1),
     limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
@@ -50,15 +50,23 @@ The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli`
 
 ## Access keys
 
-Each sign-in creates a key for the app and asks Tempo Auth to authorize it on the user's Tempo Account. The `accessKey` option says what the key may do, with viem's `Expiry` and `Scopes` helpers:
+Each sign-in creates a key for the app and asks Tempo Auth to authorize it on the user's Tempo Account. The `permissions` option says what the key may do, with viem's `Expiry` and `Scopes` helpers:
 
-| Field     | Meaning                                                                                       |
-| --------- | --------------------------------------------------------------------------------------------- |
-| `account` | Optional: which of the user's Tempo Accounts, from `tempoAccount.list`. Defaults to the first |
-| `chainId` | The chain the key acts on, such as `tempoTestnet.id`                                          |
-| `expiry`  | When the key expires, in Unix seconds, such as `Expiry.days(1)`                               |
-| `limits`  | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]`                 |
-| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`                        |
+| Field     | Meaning                                                                       |
+| --------- | ----------------------------------------------------------------------------- |
+| `chainId` | Optional: 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)`               |
+| `limits`  | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]` |
+| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`        |
+
+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 gets 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 sees 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, permissions })
+```
 
 Flows without a Tempo Auth page (`authorize`, `email.signIn`) must stay within Tempo Auth's ceiling, about $1,000 per token. 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.
 
@@ -72,11 +80,11 @@ For a browser app that renders its own email form. The page calls Tempo Auth wit
 
 ```ts
 // A user already signed in to Tempo Auth, from any app, needs no form.
-const authorization = await Actions.authorize(auth, { accessKey })
+const authorization = await Actions.authorize(auth, { permissions })
 
 // Otherwise, sign in with an emailed code.
 await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { accessKey, code, email })
+const result = await Actions.email.signIn(auth, { code, email, permissions })
 
 // 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 })
@@ -94,13 +102,13 @@ Actions.provider.signIn(auth, { provider: 'google' })
 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, { accessKey })
+await Actions.redirect.start(auth, { permissions })
 
 // On the page the browser returns to, and on every load:
 const authorization = await Actions.redirect.complete(auth)
 ```
 
-`redirect.start` keeps its state in session storage until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere.
+`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
 
@@ -117,11 +125,11 @@ const auth = Auth.create({
 
 // Your own sign-in UI, as in a browser.
 await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { accessKey, code, email })
+const result = await Actions.email.signIn(auth, { code, email, permissions })
 
 // Or Tempo Auth's pages, which also offer Google and SSO.
 const { pending, url } = await Actions.redirect.createUrl(auth, {
-  accessKey,
+  permissions,
 })
 const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
 if (session.type === 'success')
@@ -142,7 +150,7 @@ const auth = Auth.create({ clientId, clientSecret, url })
 
 // GET /auth/start
 const { pending, url } = await Actions.redirect.createUrl(auth, {
-  accessKey,
+  permissions,
   redirectUri: 'https://app.example/auth/callback',
 })
 // Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
@@ -160,8 +168,8 @@ For a command-line tool. The user approves a code in any browser, and the CLI wa
 
 ```ts
 const device = await Actions.device.authorize(auth, {
-  accessKey,
   device: os.hostname(),
+  permissions,
 })
 console.log(
   `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
@@ -171,20 +179,27 @@ 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 an access key's `account`:
+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
 
 await Actions.authorize(auth, {
-  accessKey: { ...accessKey, account: tempoAccount.address },
+  accessKey: Account.fromWebCryptoP256(keyPair, {
+    access: tempoAccount.address,
+  }),
+  permissions,
 })
 ```
 
 ## Keep a sign-in
 
-`Authorization.key` is the app's key as JSON: the Tempo Account, the signed authorization, and the private key. Store it with the tokens, as securely as a session, and rebuild the account later with `Key.toAccount`.
+`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'
@@ -205,7 +220,7 @@ A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `
 
 ```ts
 try {
-  await Actions.email.signIn(auth, { accessKey, code, email })
+  await Actions.email.signIn(auth, { code, email, permissions })
 } catch (error) {
   if (error instanceof Auth.RequestError && error.status === 401)
     showWrongCode()
@@ -219,49 +234,60 @@ try {
 | 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. Defaults to session storage                             |
+| `storage`      | Where `redirect.start` keeps its state, without serializing it. Defaults to IndexedDB           |
 | `fetch`        | Calls Tempo Auth. Defaults to the global `fetch`                                                |
 
 ### `Actions`
 
-Each sign-in flow has its own namespace. The actions every flow shares sit at the top level.
-
-| Action                                                 | Returns                                                                    |
-| ------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `authorize(auth, { accessKey })`                       | 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, { accessKey, 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, { accessKey, 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)`                              | The `Authorization` when the page is a redirect's callback, or `undefined` |
-| `redirect.createUrl(auth, { accessKey, 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, { accessKey })`                  | 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                     |
+Each sign-in flow has its own namespace. The actions every flow shares sit at the top level. Every action that takes `permissions` also takes an optional `accessKey`.
+
+| Action                                                   | Returns                                                                    |
+| -------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `authorize(auth, { permissions })`                       | 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, permissions })`        | 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, permissions })`       | 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, { permissions, 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, { permissions })`                  | 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 JSON, for `Key.toAccount`                                        |
+| `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'
+
+const permissions = Permissions.from({ expiry: Expiry.days(1), limits, scopes })
+```
+
 ### `Key`
 
-| Function         | Returns                                     |
-| ---------------- | ------------------------------------------- |
-| `toAccount(key)` | The key as a viem access key account        |
-| `expired(key)`   | Whether the key's authorization has expired |
+| 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                                     |

package/dist/Actions.d.ts

@@ -1,4 +1,13 @@
-import type { AccessKey, Auth, Authorization, Tokens } from './Auth.ts';
+/**
+ * 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.
+ * @module
+ */
+import type { Account } from 'viem/tempo';
+import type { Auth } from './Auth.ts';
+import type { Authorization } from './Authorization.ts';
+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 provider from './actions/provider.ts';
@@ -11,15 +20,20 @@ export * as tempoAccount from './actions/tempoAccount.ts';
  *
  * @example
  * ```ts
- * const authorization = await Actions.authorize(auth, { accessKey })
+ * const authorization = await Actions.authorize(auth, { permissions })
  * if (!authorization) showSignIn()
  * ```
  */
 export declare function authorize(auth: Auth, options: authorize.Options): Promise<authorize.ReturnType>;
 export declare namespace authorize {
     type Options = {
-        /** What the app's key may do. It must fit the headless ceiling. */
-        accessKey: AccessKey;
+        /**
+         * 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. */
+        permissions: Permissions;
     };
     /** The authorization, or `undefined` without a session. */
     type ReturnType = Authorization | undefined;

package/dist/Actions.js

@@ -1,9 +1,4 @@
-/**
- * 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.
- * @module
- */
-import { Secp256k1 } from 'viem/tempo';
+import * as AccessKey from './internal/accessKey.js';
 import * as Api from './internal/api.js';
 import { request } from './internal/request.js';
 export * as device from './actions/device.js';
@@ -18,7 +13,7 @@ export * as tempoAccount from './actions/tempoAccount.js';
  *
  * @example
  * ```ts
- * const authorization = await Actions.authorize(auth, { accessKey })
+ * const authorization = await Actions.authorize(auth, { permissions })
  * if (!authorization) showSignIn()
  * ```
  */
@@ -29,15 +24,16 @@ export async function authorize(auth, options) {
     }));
     if (!session.user)
         return undefined;
-    const privateKey = Secp256k1.randomPrivateKey();
+    const key = await AccessKey.resolve(options.accessKey);
     const response = await Api.post(auth, '/api/authorize', {
-        json: request(auth, { ...options, privateKey }),
+        json: request(auth, {
+            accessKey: key.accessKey,
+            permissions: options.permissions,
+        }),
     });
     if (response.status === 401)
         return undefined;
-    return Api.authorization(await Api.json(response), {
-        privateKey,
-    });
+    return Api.authorization(await Api.json(response), key);
 }
 /**
  * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.

package/dist/Auth.d.ts

@@ -1,32 +1,8 @@
-/**
- * A Tempo Auth instance, and the types its actions take and return. Create one with
- * {@link create}, then pass it to each action in `Actions`. Every sign-in returns an
- * {@link Authorization}: the user's tokens and a viem access key account.
- *
- * @example
- * ```ts
- * import { Actions, Auth } from '@tempoxyz/auth'
- * import { Addresses, Expiry, Scopes } from 'viem/tempo'
- * import { tempoTestnet } from 'viem/tempo/chains'
- *
- * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
- *
- * const authorization = await Actions.authorize(auth, {
- *   accessKey: {
- *     chainId: tempoTestnet.id,
- *     expiry: Expiry.days(1),
- *     limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
- *     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
- *   },
- * })
- * ```
- * @module
- */
-import type { Hex } from 'ox';
-import type { KeyAuthorization } from 'ox/tempo';
-import type * as Key from './Key.ts';
+import type { Storage } from './Storage.ts';
 /** 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. */
+    chainId: number;
     /** The app's Connect client ID. */
     clientId: string;
     /** The app's client secret. Only a backend holds one. */
@@ -37,72 +13,14 @@ export type Auth = {
     redirectUri?: string | undefined;
     /** The scopes the app's tokens carry. */
     scope: string;
-    /** Where a redirect sign-in keeps its state until Tempo Auth redirects back. */
-    storage?: Pick<Storage, 'getItem' | 'removeItem' | 'setItem'> | undefined;
+    /**
+     * Where `Actions.redirect.start` keeps its state until Tempo Auth redirects back. It must keep
+     * objects as they are, since a browser key is a `CryptoKey`. Defaults to IndexedDB.
+     */
+    storage?: Storage | undefined;
     /** Where Tempo Auth runs, such as `https://auth.tempo.xyz`. */
     url: string;
 };
-/** What an app's access key may do, as viem's `accessKey.signAuthorization` takes it. */
-export type AccessKey = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scopes'> & {
-    /** The user's Tempo Account the key acts for, from `Actions.tempoAccount.list`. Defaults to their first. */
-    account?: `0x${string}` | undefined;
-    /** The chain the key acts on, such as `tempoTestnet.id`. */
-    chainId: number;
-    /** Unix seconds. viem's `Expiry` builds one, such as `Expiry.days(1)`. */
-    expiry: number;
-};
-/** One of the user's Tempo Accounts. */
-export type TempoAccount = {
-    /** The account's address, the same on every Tempo chain. */
-    address: `0x${string}`;
-};
-/** 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. */
-    account: ReturnType<typeof Key.toAccount>;
-    /** The same key as JSON, for apps that store it and rebuild it with `Key.toAccount`. */
-    key: Key.Key;
-    /** The signed-in user, from the ID token. */
-    user: User;
-};
-/** The app's tokens for Tempo APIs. */
-export type Tokens = {
-    /** The Bearer token Tempo APIs accept. */
-    accessToken: string;
-    /** When the access token expires, in milliseconds. */
-    expiresAt: number;
-    /** The OIDC ID token, which names the user. A refresh may omit it. */
-    idToken?: string | undefined;
-    /** Exchanges for new tokens through `Actions.refresh`. It rotates on every refresh. */
-    refreshToken?: string | undefined;
-};
-/** The signed-in user. */
-export type User = {
-    /** The user's verified email address. */
-    email: string;
-    /** The user's ID, the `sub` of every token. */
-    id: string;
-};
-/** An OAuth provider's short name, as `Actions.provider.list` lists them. */
-export type Provider = 'apple' | 'bitbucket' | 'github' | 'gitlab' | 'google' | 'intuit' | 'linkedin' | 'microsoft' | 'salesforce' | 'slack' | 'xero';
-/** A step a sign-in needs before it finishes, such as the SSO connection an address requires. */
-export type Step = {
-    /** The kind of step. */
-    type: 'sso';
-    /** Where `Actions.provider.signIn` sends the browser to take the step. */
-    url: string;
-};
-/** A sign-in redirect in progress: what the app keeps until Tempo Auth redirects back. */
-export type Pending = {
-    /** The app's new access key, which the callback authorizes. */
-    privateKey: Hex.Hex;
-    /** Where Tempo Auth redirects back to, which the code exchange repeats. */
-    redirectUri: string;
-    /** The value the callback must echo, so a forged callback is refused. */
-    state: string;
-    /** The PKCE verifier that redeems the code. */
-    verifier: string;
-};
 /** A request Tempo Auth refused, with its status and message. */
 export declare class RequestError extends Error {
     readonly name = "Auth.RequestError";
@@ -123,7 +41,9 @@ export declare class RequestError extends Error {
  */
 export declare function create(options: create.Options): Auth;
 export declare namespace create {
-    type Options = Omit<Auth, 'scope'> & {
+    type Options = Omit<Auth, 'chainId' | 'scope'> & {
+        /** The chain the app's keys act on, such as `tempoTestnet.id`. Defaults to Tempo mainnet. */
+        chainId?: number | undefined;
         /**
          * Scopes the app's tokens carry beyond `openid` and `email`, which every instance includes.
          * Defaults to `offline_access`, for a refresh token.

package/dist/Auth.js

@@ -1,3 +1,31 @@
+/**
+ * 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 { Addresses, Expiry, Scopes } from 'viem/tempo'
+ * import { tempoTestnet } from 'viem/tempo/chains'
+ *
+ * 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: Addresses.pathUsd }],
+ *     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+ *   },
+ * })
+ * ```
+ * @module
+ */
+import { tempo } from 'viem/tempo/chains';
 /** A request Tempo Auth refused, with its status and message. */
 export class RequestError extends Error {
     name = 'Auth.RequestError';
@@ -21,6 +49,7 @@ export function create(options) {
     const scopes = (options.scope ?? 'offline_access').split(' ').filter(Boolean);
     return {
         ...options,
+        chainId: options.chainId ?? tempo.id,
         scope: [...new Set(['openid', 'email', ...scopes])].join(' '),
     };
 }

package/dist/Authorization.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.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. */
+    account: ReturnType<typeof Key.toAccount>;
+    /** The same key as data, for apps that store it and rebuild it with `Key.toAccount`. */
+    key: Key.Key;
+    /** 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 declare function from(value: Authorization): Authorization;

package/dist/Authorization.js

@@ -0,0 +1,11 @@
+/**
+ * Instantiates a {@link Authorization}.
+ *
+ * @example
+ * ```ts
+ * const authorization = Authorization.from({ ...saved, account: Key.toAccount(saved.key) })
+ * ```
+ */
+export function from(value) {
+    return value;
+}

package/dist/Key.d.ts

@@ -1,20 +1,36 @@
 /**
- * An app's access key on a user's Tempo Account, as the app stores it: the key, the account it
- * acts for, and the authorization Tempo Auth signed for it.
+ * An app's access key on a user's Tempo Account, as the app stores it: the account it acts for,
+ * the authorization Tempo Auth signed for it, and the key material the library generated.
  * @module
  */
-import type { Address, Hex } from 'ox';
+import { type Address, type Hex, type WebCryptoP256 } from 'ox';
 import { KeyAuthorization } from 'ox/tempo';
+import type { OneOf } from 'viem';
 import { Account } from 'viem/tempo';
-/** A stored access key. It is JSON, so servers and CLIs can keep it in a cookie or a file. */
+/**
+ * A stored access key. A browser key is a non-extractable WebCrypto key pair, which IndexedDB
+ * keeps without exporting. Elsewhere it is a secp256k1 private key, as JSON for a cookie or a file.
+ * A key the app supplied as `accessKey` carries no material.
+ */
 export type Key = {
     /** The Tempo Account the key acts for. */
     account: Address.Address;
     /** The signed authorization, in the node's RPC format. */
     keyAuthorization: KeyAuthorization.Rpc;
-    /** The access key's private key. Keep it as secret as a session. */
+} & Material;
+/** The key material the library generated for a sign-in. */
+export type Material = OneOf<{
+    /** A non-extractable WebCrypto P256 key pair, in a browser. */
+    keyPair: WebCryptoP256.createKeyPair.ReturnType;
+} | {
+    /** A secp256k1 private key, outside a browser. Keep it as secret as a session. */
     privateKey: Hex.Hex;
-};
+} | {}>;
+/** A key the app supplied as `accessKey`, which `toAccount` needs to rebuild its account. */
+export declare class AccessKeyRequiredError extends Error {
+    readonly name = "Key.AccessKeyRequiredError";
+    constructor();
+}
 /**
  * Whether the key's authorization has expired, so a new sign-in must authorize a new key.
  *
@@ -24,9 +40,19 @@ export type Key = {
  * ```
  */
 export declare function expired(key: Key): boolean;
+/**
+ * Instantiates a {@link Key}.
+ *
+ * @example
+ * ```ts
+ * const key = Key.from(JSON.parse(saved).key)
+ * ```
+ */
+export declare function from(value: Key): Key;
 /**
  * Returns the key as a viem access key account acting for its Tempo Account. viem attaches the
- * authorization to transactions until the chain registers the key.
+ * authorization to transactions until the chain registers the key. A key the app supplied signs
+ * with that `accessKey`. Throws {@link AccessKeyRequiredError} when neither holds key material.
  *
  * @example
  * ```ts
@@ -36,4 +62,10 @@ export declare function expired(key: Key): boolean;
  * await client.token.transferSync({ account, amount, to, token })
  * ```
  */
-export declare function toAccount(key: Key): Account.AccessKeyAccount;
+export declare function toAccount(key: Key, options?: toAccount.Options): Account.AccessKeyAccount;
+export declare namespace toAccount {
+    type Options = {
+        /** The key the app supplied to the sign-in, for a key that carries no material. */
+        accessKey?: Account.Account | undefined;
+    };
+}