@tempoxyz/auth 0.0.0-pr-6.sha-17bb901 → 0.0.0-pr-6.sha-fe206c7

package/README.md

@@ -0,0 +1,217 @@
+# @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.
+
+Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `tokens.accessToken`.
+
+```ts
+import { Actions, Auth } from '@tempoxyz/auth'
+import { Addresses, createClient, Expiry, Scopes } from 'viem/tempo'
+import { tempoTestnet } from 'viem/tempo/chains'
+
+const auth = Auth.create({
+  clientId: 'client_…',
+  url: 'https://auth.tempo.xyz',
+})
+const client = createClient({
+  chain: tempoTestnet,
+  feeToken: Addresses.pathUsd,
+})
+
+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()],
+  },
+})
+
+await client.token.transferSync({
+  account: authorization!.account,
+  amount: 10_000n,
+  to: '0x…',
+  token: Addresses.pathUsd,
+})
+```
+
+## Install
+
+```bash
+pnpm add @tempoxyz/auth viem
+```
+
+viem is a peer dependency.
+
+## 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` you pass to `Auth.create`. An app with a backend also gets a client secret.
+- **Allow the app's origin.** Apps that call Tempo Auth from their own page need their origin in Tempo Auth's `INTERNAL_ORIGINS`.
+
+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 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:
+
+| Field     | Meaning                                                                       |
+| --------- | ----------------------------------------------------------------------------- |
+| `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()]`        |
+
+Flows without a Tempo Auth page (`authorize`, `verifyCode`) must stay within Tempo Auth's ceiling, about $1,000 per token. Flows with a page (`redirect`, `createAuthorizationUrl`, `authorizeDevice`) 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, { accessKey })
+
+// Otherwise, sign in with an emailed code.
+await Actions.sendCode(auth, { email })
+const result = await Actions.verifyCode(auth, { accessKey, code, email })
+
+// An address that requires SSO continues at its connection, and returns to this page.
+if ('step' in result) Actions.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.getProviders(auth) // [{ id: 'google', name: 'Google' }]
+Actions.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(auth, { accessKey })
+
+// On the page the browser returns to, and on every load:
+const authorization = await Actions.handleRedirect(auth)
+```
+
+`redirect` keeps its state in session storage until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere.
+
+### A backend
+
+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.
+
+```ts
+const auth = Auth.create({ clientId, clientSecret, url })
+
+// GET /auth/start
+const { pending, url } = await Actions.createAuthorizationUrl(auth, {
+  accessKey,
+  redirectUri: 'https://app.example/auth/callback',
+})
+// Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
+
+// GET /auth/callback
+const authorization = await Actions.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.
+
+```ts
+const device = await Actions.authorizeDevice(auth, {
+  accessKey,
+  device: os.hostname(),
+})
+console.log(
+  `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
+)
+const authorization = await device.wait()
+```
+
+## 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`.
+
+```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.tokens.refreshToken,
+})
+```
+
+Refresh tokens rotate, so store the new `tokens` after each refresh.
+
+## Errors
+
+A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `message`.
+
+```ts
+try {
+  await Actions.verifyCode(auth, { accessKey, code, email })
+} catch (error) {
+  if (error instanceof Auth.RequestError && error.status === 401)
+    showWrongCode()
+}
+```
+
+## Reference
+
+### `Auth.create(options)`
+
+| Option         | Meaning                                                                                         |
+| -------------- | ----------------------------------------------------------------------------------------------- |
+| `clientId`     | The app's Connect client ID. Required                                                           |
+| `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` keeps its state. Defaults to session storage                                   |
+| `fetch`        | Calls Tempo Auth. Defaults to the global `fetch`                                                |
+
+### `Actions`
+
+| Action                                                     | Returns                                                                    |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `authorize(auth, { accessKey })`                           | An `Authorization` for a user already signed in, or `undefined`            |
+| `authorizeDevice(auth, { accessKey, device })`             | The code to show and a `wait()` that resolves with an `Authorization`      |
+| `createAuthorizationUrl(auth, { accessKey, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep          |
+| `getProviders(auth)`                                       | The OAuth providers Tempo Auth offers, as `{ id, name }`                   |
+| `handleCallback(auth, { pending, url })`                   | The `Authorization` for a redirect's callback                              |
+| `handleRedirect(auth)`                                     | The `Authorization` when the page is a redirect's callback, or `undefined` |
+| `redirect(auth, { accessKey })`                            | Nothing. The browser leaves for Tempo Auth's pages                         |
+| `refresh(auth, { refreshToken })`                          | New `Tokens`                                                               |
+| `sendCode(auth, { email })`                                | Nothing. Tempo Auth emails a code                                          |
+| `signIn(auth, { provider } \| { url })`                    | Nothing. The browser leaves for the provider or SSO connection             |
+| `signOut(auth)`                                            | Nothing. The user's Tempo Auth session ends                                |
+| `verifyCode(auth, { accessKey, code, email })`             | An `Authorization`, or the `step` the address requires first               |
+
+### `Authorization`
+
+| Field     | Meaning                                                                         |
+| --------- | ------------------------------------------------------------------------------- |
+| `account` | The app's key as a viem access key account, acting for the user's Tempo Account |
+| `key`     | The same key as JSON, for `Key.toAccount`                                       |
+| `tokens`  | `accessToken`, `expiresAt`, and the optional `idToken` and `refreshToken`       |
+| `user`    | The user's `email` and `id`, the `sub` of every token                           |
+
+### `Key`
+
+| Function         | Returns                                     |
+| ---------------- | ------------------------------------------- |
+| `toAccount(key)` | The key as a viem access key account        |
+| `expired(key)`   | Whether the key's authorization has expired |

package/dist/Actions.d.ts

@@ -1,6 +1,6 @@
 import { type AccessKey, type Auth, type Authorization, type Pending, type Provider, type Step, type Tokens } from './Auth.ts';
 /**
- * Authorizes the app for a person already signed in to Tempo Auth, from any app. Returns
+ * Authorizes the app for a user already signed in to Tempo Auth, from any app. Returns
  * `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
  * ceiling.
  *
@@ -20,7 +20,7 @@ export declare namespace authorize {
     type ReturnType = Authorization | undefined;
 }
 /**
- * Starts the device grant for a CLI: the person approves `userCode` at `verificationUri` from any
+ * Starts the device grant for a CLI: the user approves `userCode` at `verificationUri` from any
  * browser, and `wait` resolves once they do.
  *
  * @example
@@ -41,18 +41,18 @@ export declare namespace authorizeDevice {
     type ReturnType = {
         /** Seconds until the code expires. */
         expiresIn: number;
-        /** The code the person confirms in the browser. */
+        /** The code the user confirms in the browser. */
         userCode: string;
-        /** Where the person enters the code. */
+        /** Where the user enters the code. */
         verificationUri: string;
-        /** Where the person approves the code, with it already filled in. */
+        /** Where the user approves the code, with it already filled in. */
         verificationUriComplete: string;
-        /** Resolves with the authorization once the person approves. */
+        /** Resolves with the authorization once the user approves. */
         wait: () => Promise<Authorization>;
     };
 }
 /**
- * Returns the URL that signs the person in on Tempo Auth's pages and redirects back with a code
+ * Returns the URL that signs the user in on Tempo Auth's pages and redirects back with a code
  * and the key authorization, and the {@link Pending} state to keep until then, such as in a
  * sealed cookie. {@link handleCallback} finishes it.
  *
@@ -69,7 +69,7 @@ export declare namespace authorizeDevice {
 export declare function createAuthorizationUrl(auth: Auth, options: createAuthorizationUrl.Options): Promise<createAuthorizationUrl.ReturnType>;
 export declare namespace createAuthorizationUrl {
     type Options = {
-        /** What the app's key may do. Tempo Auth's pages show it, and the person approves it. */
+        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
         accessKey: AccessKey;
         /** Where Tempo Auth redirects back to. Defaults to the instance's `redirectUri`. */
         redirectUri?: string | undefined;
@@ -147,7 +147,7 @@ export declare namespace handleRedirect {
 export declare function redirect(auth: Auth, options: redirect.Options): Promise<void>;
 export declare namespace redirect {
     type Options = {
-        /** What the app's key may do. Tempo Auth's pages show it, and the person approves it. */
+        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
         accessKey: AccessKey;
     };
 }
@@ -169,17 +169,17 @@ export declare namespace refresh {
     };
 }
 /**
- * Emails the person a sign-in code. The response is the same for every address.
+ * Emails the user a sign-in code. The response is the same for every address.
  *
  * @example
  * ```ts
- * await Actions.sendCode(auth, { email: 'person@example.com' })
+ * await Actions.sendCode(auth, { email: 'user@example.com' })
  * ```
  */
 export declare function sendCode(auth: Auth, options: sendCode.Options): Promise<void>;
 export declare namespace sendCode {
     type Options = {
-        /** The person's email address. */
+        /** The user's email address. */
         email: string;
     };
 }
@@ -206,7 +206,7 @@ export declare namespace signIn {
     };
 }
 /**
- * Ends the person's Tempo Auth session, which signs them out of every app that relies on it.
+ * Ends the user's Tempo Auth session, which signs them out of every app that relies on it.
  *
  * @example
  * ```ts
@@ -215,7 +215,7 @@ export declare namespace signIn {
  */
 export declare function signOut(auth: Auth): Promise<void>;
 /**
- * Signs the person in with the code they were emailed, and authorizes the app in the same call.
+ * Signs the user in with the code they were emailed, and authorizes the app in the same call.
  * Returns a {@link Step} when the address requires SSO, which {@link signIn} continues.
  *
  * @example
@@ -229,7 +229,7 @@ export declare namespace verifyCode {
     type Options = {
         /** What the app's key may do. It must fit the headless ceiling. */
         accessKey: AccessKey;
-        /** The 6-digit code the person was emailed. */
+        /** The 6-digit code the user was emailed. */
         code: string;
         /** The address the code was sent to. */
         email: string;

package/dist/Actions.js

@@ -8,7 +8,7 @@ import { RequestError, } from './Auth.js';
 import * as Key from './Key.js';
 import { request } from './internal/request.js';
 /**
- * Authorizes the app for a person already signed in to Tempo Auth, from any app. Returns
+ * Authorizes the app for a user already signed in to Tempo Auth, from any app. Returns
  * `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
  * ceiling.
  *
@@ -34,7 +34,7 @@ export async function authorize(auth, options) {
     return authorization(await json(response), { privateKey });
 }
 /**
- * Starts the device grant for a CLI: the person approves `userCode` at `verificationUri` from any
+ * Starts the device grant for a CLI: the user approves `userCode` at `verificationUri` from any
  * browser, and `wait` resolves once they do.
  *
  * @example
@@ -53,7 +53,7 @@ export async function authorizeDevice(auth, options) {
                 .keyAuthorization,
         },
     }));
-    /** Polls until the person approves or denies the code, or it expires. */
+    /** Polls until the user approves or denies the code, or it expires. */
     async function wait() {
         let interval = code.interval;
         const deadline = Date.now() + code.expires_in * 1000;
@@ -89,7 +89,7 @@ export async function authorizeDevice(auth, options) {
     };
 }
 /**
- * Returns the URL that signs the person in on Tempo Auth's pages and redirects back with a code
+ * Returns the URL that signs the user in on Tempo Auth's pages and redirects back with a code
  * and the key authorization, and the {@link Pending} state to keep until then, such as in a
  * sealed cookie. {@link handleCallback} finishes it.
  *
@@ -233,11 +233,11 @@ export function refresh(auth, options) {
     });
 }
 /**
- * Emails the person a sign-in code. The response is the same for every address.
+ * Emails the user a sign-in code. The response is the same for every address.
  *
  * @example
  * ```ts
- * await Actions.sendCode(auth, { email: 'person@example.com' })
+ * await Actions.sendCode(auth, { email: 'user@example.com' })
  * ```
  */
 export async function sendCode(auth, options) {
@@ -260,7 +260,7 @@ export function signIn(auth, options) {
     window.location.assign(url);
 }
 /**
- * Ends the person's Tempo Auth session, which signs them out of every app that relies on it.
+ * Ends the user's Tempo Auth session, which signs them out of every app that relies on it.
  *
  * @example
  * ```ts
@@ -272,7 +272,7 @@ export async function signOut(auth) {
     await json(await post(auth, '/api/auth/logout', { json: {} }));
 }
 /**
- * Signs the person in with the code they were emailed, and authorizes the app in the same call.
+ * Signs the user in with the code they were emailed, and authorizes the app in the same call.
  * Returns a {@link Step} when the address requires SSO, which {@link signIn} continues.
  *
  * @example

package/dist/Auth.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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 person's tokens, and a viem access key account.
+ * {@link Authorization}: the user's tokens, and a viem access key account.
  *
  * @example
  * ```ts
@@ -51,13 +51,13 @@ export type AccessKey = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scop
 };
 /** What every sign-in returns. */
 export type Authorization = {
-    /** The app's access key, as a viem account acting for the person's Tempo Account. */
+    /** The app's access key, as a viem account acting for the user's Tempo Account. */
     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 app's tokens for Tempo APIs. */
     tokens: Tokens;
-    /** The signed-in person, from the ID token. */
+    /** The signed-in user, from the ID token. */
     user: User;
 };
 /** The app's tokens for Tempo APIs. */
@@ -66,16 +66,16 @@ export type Tokens = {
     accessToken: string;
     /** When the access token expires, in milliseconds. */
     expiresAt: number;
-    /** The OIDC ID token, which names the person. A refresh may omit it. */
+    /** 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 person. */
+/** The signed-in user. */
 export type User = {
-    /** The person's verified email address. */
+    /** The user's verified email address. */
     email: string;
-    /** The person's ID, the `sub` of every token. */
+    /** The user's ID, the `sub` of every token. */
     id: string;
 };
 /** An OAuth provider's short name, as `Actions.getProviders` lists them. */

package/dist/Auth.js

@@ -17,7 +17,7 @@ export class RequestError extends Error {
  * ```
  */
 export function create(options) {
-    // Every authorization reads the person from the ID token, which needs `openid` and `email`.
+    // Every authorization reads the user from the ID token, which needs `openid` and `email`.
     const scopes = (options.scope ?? 'offline_access').split(' ').filter(Boolean);
     return {
         ...options,

package/dist/Key.d.ts

@@ -1,5 +1,5 @@
 /**
- * An app's access key on a person's Tempo Account, as the app stores it: the key, the account it
+ * 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.
  * @module
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tempoxyz/auth",
-  "version": "0.0.0-pr-6.sha-17bb901",
-  "description": "Signs people in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
+  "version": "0.0.0-pr-6.sha-fe206c7",
+  "description": "Signs users in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
   "type": "module",
   "exports": {
     ".": {