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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +217 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,217 @@
1
+ # @tempoxyz/auth
2
+
3
+ Sign people 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.
4
+
5
+ Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `tokens.accessToken`.
6
+
7
+ ```ts
8
+ import { Actions, Auth } from '@tempoxyz/auth'
9
+ import { Addresses, createClient, Expiry, Scopes } from 'viem/tempo'
10
+ import { tempoTestnet } from 'viem/tempo/chains'
11
+
12
+ const auth = Auth.create({
13
+ clientId: 'client_…',
14
+ url: 'https://auth.tempo.xyz',
15
+ })
16
+ const client = createClient({
17
+ chain: tempoTestnet,
18
+ feeToken: Addresses.pathUsd,
19
+ })
20
+
21
+ const authorization = await Actions.authorize(auth, {
22
+ accessKey: {
23
+ chainId: tempoTestnet.id,
24
+ expiry: Expiry.days(1),
25
+ limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
26
+ scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
27
+ },
28
+ })
29
+
30
+ await client.token.transferSync({
31
+ account: authorization!.account,
32
+ amount: 10_000n,
33
+ to: '0x…',
34
+ token: Addresses.pathUsd,
35
+ })
36
+ ```
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ pnpm add @tempoxyz/auth viem
42
+ ```
43
+
44
+ viem is a peer dependency.
45
+
46
+ ## Before you start
47
+
48
+ - **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.
49
+ - **Allow the app's origin.** Apps that call Tempo Auth from their own page need their origin in Tempo Auth's `INTERNAL_ORIGINS`.
50
+
51
+ The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli` app.
52
+
53
+ ## Access keys
54
+
55
+ Each sign-in creates a key for the app and asks Tempo Auth to authorize it on the person's Tempo Account. The `accessKey` option says what the key may do, with viem's `Expiry` and `Scopes` helpers:
56
+
57
+ | Field | Meaning |
58
+ | --------- | ----------------------------------------------------------------------------- |
59
+ | `chainId` | The chain the key acts on, such as `tempoTestnet.id` |
60
+ | `expiry` | When the key expires, in Unix seconds, such as `Expiry.days(1)` |
61
+ | `limits` | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]` |
62
+ | `scopes` | The calls the key may make, such as `[Scopes.tip20(token).transfer()]` |
63
+
64
+ 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 person, who approves them, so they may go beyond it.
65
+
66
+ The returned `account` attaches the key's authorization to its first transaction, which registers the key on chain.
67
+
68
+ ## Flows
69
+
70
+ ### Your own sign-in UI
71
+
72
+ For a browser app that renders its own email form. The page calls Tempo Auth with the person's Tempo Auth session, so it works across every app on the same site.
73
+
74
+ ```ts
75
+ // A person already signed in to Tempo Auth, from any app, needs no form.
76
+ const authorization = await Actions.authorize(auth, { accessKey })
77
+
78
+ // Otherwise, sign in with an emailed code.
79
+ await Actions.sendCode(auth, { email })
80
+ const result = await Actions.verifyCode(auth, { accessKey, code, email })
81
+
82
+ // An address that requires SSO continues at its connection, and returns to this page.
83
+ if ('step' in result) Actions.signIn(auth, { url: result.step.url })
84
+ ```
85
+
86
+ 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.
87
+
88
+ ```ts
89
+ const providers = await Actions.getProviders(auth) // [{ id: 'google', name: 'Google' }]
90
+ Actions.signIn(auth, { provider: 'google' })
91
+ ```
92
+
93
+ ### Tempo Auth's pages
94
+
95
+ 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.
96
+
97
+ ```ts
98
+ await Actions.redirect(auth, { accessKey })
99
+
100
+ // On the page the browser returns to, and on every load:
101
+ const authorization = await Actions.handleRedirect(auth)
102
+ ```
103
+
104
+ `redirect` keeps its state in session storage until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere.
105
+
106
+ ### A backend
107
+
108
+ 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.
109
+
110
+ ```ts
111
+ const auth = Auth.create({ clientId, clientSecret, url })
112
+
113
+ // GET /auth/start
114
+ const { pending, url } = await Actions.createAuthorizationUrl(auth, {
115
+ accessKey,
116
+ redirectUri: 'https://app.example/auth/callback',
117
+ })
118
+ // Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
119
+
120
+ // GET /auth/callback
121
+ const authorization = await Actions.handleCallback(auth, {
122
+ pending,
123
+ url: request.url,
124
+ })
125
+ ```
126
+
127
+ ### A CLI
128
+
129
+ For a command-line tool. The person approves a code in any browser, and the CLI waits.
130
+
131
+ ```ts
132
+ const device = await Actions.authorizeDevice(auth, {
133
+ accessKey,
134
+ device: os.hostname(),
135
+ })
136
+ console.log(
137
+ `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
138
+ )
139
+ const authorization = await device.wait()
140
+ ```
141
+
142
+ ## Keep a sign-in
143
+
144
+ `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`.
145
+
146
+ ```ts
147
+ import { Actions, Key } from '@tempoxyz/auth'
148
+
149
+ if (Key.expired(saved.key)) signInAgain()
150
+
151
+ const account = Key.toAccount(saved.key)
152
+ const tokens = await Actions.refresh(auth, {
153
+ refreshToken: saved.tokens.refreshToken,
154
+ })
155
+ ```
156
+
157
+ Refresh tokens rotate, so store the new `tokens` after each refresh.
158
+
159
+ ## Errors
160
+
161
+ A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `message`.
162
+
163
+ ```ts
164
+ try {
165
+ await Actions.verifyCode(auth, { accessKey, code, email })
166
+ } catch (error) {
167
+ if (error instanceof Auth.RequestError && error.status === 401)
168
+ showWrongCode()
169
+ }
170
+ ```
171
+
172
+ ## Reference
173
+
174
+ ### `Auth.create(options)`
175
+
176
+ | Option | Meaning |
177
+ | -------------- | ----------------------------------------------------------------------------------------------- |
178
+ | `clientId` | The app's Connect client ID. Required |
179
+ | `url` | Where Tempo Auth runs, such as `https://auth.tempo.xyz`. Required |
180
+ | `clientSecret` | The app's client secret. Only a backend holds one |
181
+ | `redirectUri` | Where Tempo Auth redirects back to. Defaults to the page's origin |
182
+ | `scope` | Scopes beyond `openid` and `email`, which every instance includes. Defaults to `offline_access` |
183
+ | `storage` | Where `redirect` keeps its state. Defaults to session storage |
184
+ | `fetch` | Calls Tempo Auth. Defaults to the global `fetch` |
185
+
186
+ ### `Actions`
187
+
188
+ | Action | Returns |
189
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
190
+ | `authorize(auth, { accessKey })` | An `Authorization` for a person already signed in, or `undefined` |
191
+ | `authorizeDevice(auth, { accessKey, device })` | The code to show and a `wait()` that resolves with an `Authorization` |
192
+ | `createAuthorizationUrl(auth, { accessKey, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep |
193
+ | `getProviders(auth)` | The OAuth providers Tempo Auth offers, as `{ id, name }` |
194
+ | `handleCallback(auth, { pending, url })` | The `Authorization` for a redirect's callback |
195
+ | `handleRedirect(auth)` | The `Authorization` when the page is a redirect's callback, or `undefined` |
196
+ | `redirect(auth, { accessKey })` | Nothing. The browser leaves for Tempo Auth's pages |
197
+ | `refresh(auth, { refreshToken })` | New `Tokens` |
198
+ | `sendCode(auth, { email })` | Nothing. Tempo Auth emails a code |
199
+ | `signIn(auth, { provider } \| { url })` | Nothing. The browser leaves for the provider or SSO connection |
200
+ | `signOut(auth)` | Nothing. The person's Tempo Auth session ends |
201
+ | `verifyCode(auth, { accessKey, code, email })` | An `Authorization`, or the `step` the address requires first |
202
+
203
+ ### `Authorization`
204
+
205
+ | Field | Meaning |
206
+ | --------- | --------------------------------------------------------------------------------- |
207
+ | `account` | The app's key as a viem access key account, acting for the person's Tempo Account |
208
+ | `key` | The same key as JSON, for `Key.toAccount` |
209
+ | `tokens` | `accessToken`, `expiresAt`, and the optional `idToken` and `refreshToken` |
210
+ | `user` | The person's `email` and `id`, the `sub` of every token |
211
+
212
+ ### `Key`
213
+
214
+ | Function | Returns |
215
+ | ---------------- | ------------------------------------------- |
216
+ | `toAccount(key)` | The key as a viem access key account |
217
+ | `expired(key)` | Whether the key's authorization has expired |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/auth",
3
- "version": "0.0.0-pr-6.sha-17bb901",
3
+ "version": "0.0.0-pr-6.sha-b989a0e",
4
4
  "description": "Signs people in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
5
5
  "type": "module",
6
6
  "exports": {