@tempoxyz/auth 0.0.0-pr-61.sha-1a0da9d → 0.0.0-pr-62.sha-55672b2

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 +28 -263
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,30 @@
1
1
  # @tempoxyz/auth
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `accessToken`.
5
+ ## Overview
6
6
 
7
7
  ```ts
8
8
  import { Actions, Auth } from '@tempoxyz/auth'
9
9
  import { createClient, Expiry, Scopes } from 'viem/tempo'
10
- import { tempo, tempoTestnet } from 'viem/tempo/chains'
11
10
  import * as Tokens from 'viem/tokens'
12
11
 
13
- // OUSD has its mainnet address on every Tempo chain.
14
- const ousd = Tokens.ousd(tempo.id).address
12
+ const client = createClient()
13
+ const ousd = Tokens.ousd(client.chain.id).address
15
14
 
16
15
  const auth = Auth.create({
17
- chainId: tempoTestnet.id,
16
+ chainId: client.chain.id,
18
17
  clientId: 'client_…',
19
18
  url: 'https://auth.tempo.xyz',
20
19
  })
21
- const client = createClient({
22
- chain: tempoTestnet,
23
- feeToken: ousd,
24
- })
25
20
 
26
- const authorization = await Actions.authorize(auth, {
21
+ // 1. Email the user a sign-in code.
22
+ await Actions.email.sendCode(auth, { email: 'user@example.com' })
23
+
24
+ // 2. Sign in with the code, and authorize an access key.
25
+ const result = await Actions.email.signIn(auth, {
26
+ code: '123456',
27
+ email: 'user@example.com',
27
28
  permissions: {
28
29
  expiry: Expiry.days(1),
29
30
  limits: [{ limit: 10_000_000n, token: ousd }],
@@ -31,264 +32,28 @@ const authorization = await Actions.authorize(auth, {
31
32
  },
32
33
  })
33
34
 
34
- await client.token.transferSync({
35
- account: authorization!.account,
36
- amount: 10_000n,
37
- to: '0x…',
38
- token: ousd,
39
- })
40
- ```
41
-
42
- ## Install
43
-
44
- ```bash
45
- pnpm add @tempoxyz/auth viem
46
- ```
47
-
48
- ## Before you start
49
-
50
- - **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.
51
- - **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.
52
-
53
- The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli` app.
54
-
55
- ## Access keys
56
-
57
- 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:
58
-
59
- | Field | Meaning |
60
- | --------- | ----------------------------------------------------------------------------------------------------------- |
61
- | `chainId` | The chain the key acts on. Defaults to the instance's `chainId` |
62
- | `expiry` | When the key expires, in Unix seconds, such as `Expiry.days(1)`. Defaults to a year |
63
- | `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 |
64
- | `scopes` | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`. Defaults to transfers of each token the key limits |
65
-
66
- 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.
67
-
68
- 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:
69
-
70
- ```ts
71
- const accessKey = Account.fromWebCryptoP256(keyPair, { access: tempoAccount })
72
- await Actions.authorize(auth, { accessKey })
73
- ```
74
-
75
- 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.
76
-
77
- The returned `account` attaches the key's authorization to its first transaction, which registers the key on chain.
78
-
79
- ## Flows
80
-
81
- ### Your own sign-in UI
82
-
83
- 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.
84
-
85
- ```ts
86
- // A user already signed in to Tempo Auth, from any app, needs no form.
87
- const authorization = await Actions.authorize(auth)
88
-
89
- // Otherwise, sign in with an emailed code.
90
- await Actions.email.sendCode(auth, { email })
91
- const result = await Actions.email.signIn(auth, { code, email })
92
-
93
- // An address that requires SSO continues at its connection, and returns to this page.
35
+ // 3. Send a transaction with the access key. An address that requires SSO
36
+ // returns a `step` instead, which continues at its connection.
94
37
  if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
95
- ```
96
-
97
- 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.
98
-
99
- ```ts
100
- const providers = await Actions.provider.list(auth) // [{ id: 'google', name: 'Google' }]
101
- Actions.provider.signIn(auth, { provider: 'google' })
102
- ```
103
-
104
- ### Tempo Auth's pages
105
-
106
- 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.
107
-
108
- ```ts
109
- await Actions.redirect.start(auth)
110
-
111
- // On the page the browser returns to, and on every load:
112
- const authorization = await Actions.redirect.complete(auth)
113
- ```
114
-
115
- `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.
116
-
117
- ### A mobile app
118
-
119
- 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`.
120
-
121
- ```ts
122
- import * as WebBrowser from 'expo-web-browser'
123
-
124
- const auth = Auth.create({
125
- clientId: 'client_…',
126
- redirectUri: 'my-app://callback',
127
- url: 'https://auth.tempo.xyz',
128
- })
129
-
130
- // Your own sign-in UI, as in a browser.
131
- await Actions.email.sendCode(auth, { email })
132
- const result = await Actions.email.signIn(auth, { code, email })
133
-
134
- // Or Tempo Auth's pages, which also offer Google and SSO.
135
- const { pending, url } = await Actions.redirect.createUrl(auth)
136
- const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
137
- if (session.type === 'success')
138
- authorization = await Actions.redirect.handleCallback(auth, {
139
- pending,
140
- url: session.url,
38
+ else
39
+ await client.token.transferSync({
40
+ account: result.account,
41
+ amount: 10_000n,
42
+ to: '0x…',
43
+ token: ousd,
141
44
  })
142
45
  ```
143
46
 
144
- Keep the authorization in the device's secure store, as [Keep a sign-in](#keep-a-sign-in) describes.
47
+ Every sign-in returns the same `Authorization`. Its `account` sends transactions through viem, and its `accessToken` calls Tempo APIs.
145
48
 
146
- ### A backend
147
-
148
- 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.
149
-
150
- ```ts
151
- const auth = Auth.create({ clientId, clientSecret, url })
152
-
153
- // GET /auth/start
154
- const { pending, url } = await Actions.redirect.createUrl(auth, {
155
- redirectUri: 'https://app.example/auth/callback',
156
- })
157
- // Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
158
-
159
- // GET /auth/callback
160
- const authorization = await Actions.redirect.handleCallback(auth, {
161
- pending,
162
- url: request.url,
163
- })
164
- ```
165
-
166
- ### A CLI
167
-
168
- For a command-line tool. The user approves a code in any browser, and the CLI waits.
169
-
170
- ```ts
171
- const device = await Actions.device.authorize(auth, {
172
- device: os.hostname(),
173
- })
174
- console.log(
175
- `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
176
- )
177
- const authorization = await device.wait()
178
- ```
179
-
180
- ## More Tempo Accounts
181
-
182
- 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:
183
-
184
- ```ts
185
- const tempoAccount = await Actions.tempoAccount.create(auth)
186
- const accounts = await Actions.tempoAccount.list(auth) // the default first
187
-
188
- await Actions.authorize(auth, {
189
- accessKey: Account.fromWebCryptoP256(keyPair, {
190
- access: tempoAccount.address,
191
- }),
192
- })
193
- ```
194
-
195
- ## Keep a sign-in
196
-
197
- `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`.
198
-
199
- - **Browser:** the key is a `CryptoKey` pair, which IndexedDB stores without exporting it.
200
- - **Elsewhere:** the key is a secp256k1 private key, as JSON. Store it as securely as a session.
201
- - **Supplied key:** the key holds no material. Pass the `accessKey` again, as `Key.toAccount(saved.key, { accessKey })`.
202
-
203
- ```ts
204
- import { Actions, Key } from '@tempoxyz/auth'
205
-
206
- if (Key.expired(saved.key)) signInAgain()
207
-
208
- const account = Key.toAccount(saved.key)
209
- const tokens = await Actions.refresh(auth, {
210
- refreshToken: saved.refreshToken,
211
- })
212
- ```
213
-
214
- Refresh tokens rotate, so save the new tokens over the old ones after each refresh, such as `{ ...saved, ...tokens }`.
215
-
216
- ## Errors
217
-
218
- 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`.
219
-
220
- ```ts
221
- try {
222
- await Actions.authorize(auth, { permissions })
223
- } catch (error) {
224
- if (error instanceof Auth.RequestError && error.reason === 'limit_exceeds_maximum')
225
- showMaximum(error.meta?.maximum) // in base units
226
- }
227
- ```
228
-
229
- ## Reference
230
-
231
- ### `Auth.create(options)`
232
-
233
- | Option | Meaning |
234
- | -------------- | ----------------------------------------------------------------------------------------------- |
235
- | `clientId` | The app's Connect client ID. Required |
236
- | `chainId` | The chain the app's keys act on, such as `tempoTestnet.id`. Defaults to Tempo mainnet |
237
- | `url` | Where Tempo Auth runs, such as `https://auth.tempo.xyz`. Required |
238
- | `clientSecret` | The app's client secret. Only a backend holds one |
239
- | `redirectUri` | Where Tempo Auth redirects back to. Defaults to the page's origin |
240
- | `scope` | Scopes beyond `openid` and `email`, which every instance includes. Defaults to `offline_access` |
241
- | `storage` | Where `redirect.start` keeps its state, without serializing it. Defaults to IndexedDB |
242
- | `fetch` | Calls Tempo Auth. Defaults to the global `fetch` |
243
-
244
- The actions call version 1 of Tempo Auth's JSON API, under `/v1`. [API versions](../../docs/versioning.md) describes versions and compatibility.
245
-
246
- ### `Actions`
247
-
248
- 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`.
249
-
250
- | Action | Returns |
251
- | -------------------------------------------------------- | -------------------------------------------------------------------------- |
252
- | `authorize(auth)` | An `Authorization` for a user already signed in, or `undefined` |
253
- | `refresh(auth, { refreshToken })` | New `Tokens` |
254
- | `signOut(auth)` | Nothing. The user's Tempo Auth session ends |
255
- | `device.authorize(auth, { device })` | The code to show and a `wait()` that resolves with an `Authorization` |
256
- | `email.sendCode(auth, { email })` | Nothing. Tempo Auth emails a code |
257
- | `email.signIn(auth, { code, email })` | An `Authorization`, or the `step` the address requires first |
258
- | `provider.list(auth)` | The OAuth providers Tempo Auth offers, as `{ id, name }` |
259
- | `provider.signIn(auth, { provider } \| { url })` | Nothing. The browser leaves for the provider or SSO connection |
260
- | `redirect.complete(auth, { accessKey })` | The `Authorization` when the page is a redirect's callback, or `undefined` |
261
- | `redirect.createUrl(auth, { redirectUri })` | The `url` to send the browser to, and the `pending` state to keep |
262
- | `redirect.handleCallback(auth, { pending, url })` | The `Authorization` for a redirect's callback |
263
- | `redirect.start(auth)` | Nothing. The browser leaves for Tempo Auth's pages |
264
- | `tempoAccount.create(auth)` | Another Tempo Account for the signed-in user |
265
- | `tempoAccount.list(auth)` | The signed-in user's Tempo Accounts, the default first |
266
-
267
- ### `Authorization`
268
-
269
- | Field | Meaning |
270
- | -------------- | -------------------------------------------------------------------------------- |
271
- | `account` | The user's Tempo Account, as a viem account that signs with the app's access key |
272
- | `key` | The same key as data, for `Key.toAccount` |
273
- | `accessToken` | The Bearer token Tempo APIs accept |
274
- | `expiresAt` | When the access token expires, in milliseconds |
275
- | `idToken` | Optional: the OIDC ID token, which names the user |
276
- | `refreshToken` | Optional: exchanges for new tokens through `refresh`. It rotates each time |
277
- | `user` | The user's `email` and `id`, the `sub` of every token |
278
-
279
- ### Types
280
-
281
- 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:
282
-
283
- ```ts
284
- import { Permissions } from '@tempoxyz/auth'
49
+ ## Install
285
50
 
286
- const permissions = Permissions.from({ expiry: Expiry.days(1), limits, scopes })
51
+ ```bash
52
+ pnpm add @tempoxyz/auth viem
287
53
  ```
288
54
 
289
- ### `Key`
55
+ ## Documentation
290
56
 
291
- | Function | Returns |
292
- | ------------------------------- | ------------------------------------------------------------------------------- |
293
- | `toAccount(key, { accessKey })` | The key as a viem access key account. `accessKey` is for a key the app supplied |
294
- | `expired(key)` | Whether the key's authorization has expired |
57
+ - [Guides](docs/guides/README.md): each sign-in flow, access keys, sessions, errors, and viem.
58
+ - [API reference](docs/api/README.md): every action, function, and type.
59
+ - [Tempo Auth](../../docs/README.md): the service the package calls, over HTTP.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/auth",
3
- "version": "0.0.0-pr-61.sha-1a0da9d",
3
+ "version": "0.0.0-pr-62.sha-55672b2",
4
4
  "description": "Signs users in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
5
5
  "type": "module",
6
6
  "exports": {