@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.
- package/README.md +28 -263
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,29 +1,30 @@
|
|
|
1
1
|
# @tempoxyz/auth
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
const ousd = Tokens.ousd(
|
|
12
|
+
const client = createClient()
|
|
13
|
+
const ousd = Tokens.ousd(client.chain.id).address
|
|
15
14
|
|
|
16
15
|
const auth = Auth.create({
|
|
17
|
-
chainId:
|
|
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
|
-
|
|
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
|
-
|
|
35
|
-
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
47
|
+
Every sign-in returns the same `Authorization`. Its `account` sends transactions through viem, and its `accessToken` calls Tempo APIs.
|
|
145
48
|
|
|
146
|
-
|
|
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
|
-
|
|
51
|
+
```bash
|
|
52
|
+
pnpm add @tempoxyz/auth viem
|
|
287
53
|
```
|
|
288
54
|
|
|
289
|
-
|
|
55
|
+
## Documentation
|
|
290
56
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
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-
|
|
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": {
|