@tempoxyz/auth 0.0.0-pr-15.sha-cf4e7ec → 0.0.0-pr-17.sha-08e5136
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 +34 -15
- package/dist/Actions.d.ts +32 -2
- package/dist/Actions.js +32 -2
- package/dist/Auth.d.ts +11 -6
- package/dist/internal/request.d.ts +1 -0
- package/dist/internal/request.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
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.
|
|
4
4
|
|
|
5
|
-
Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `
|
|
5
|
+
Every sign-in returns the same `Authorization`. Send transactions with its `account` through viem, and call Tempo APIs with its `accessToken`.
|
|
6
6
|
|
|
7
7
|
```ts
|
|
8
8
|
import { Actions, Auth } from '@tempoxyz/auth'
|
|
@@ -52,12 +52,13 @@ The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli`
|
|
|
52
52
|
|
|
53
53
|
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:
|
|
54
54
|
|
|
55
|
-
| Field | Meaning
|
|
56
|
-
| --------- |
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
55
|
+
| Field | Meaning |
|
|
56
|
+
| --------- | -------------------------------------------------------------------------------------------- |
|
|
57
|
+
| `account` | Optional: which of the user's Tempo Accounts, from `getTempoAccounts`. Defaults to the first |
|
|
58
|
+
| `chainId` | The chain the key acts on, such as `tempoTestnet.id` |
|
|
59
|
+
| `expiry` | When the key expires, in Unix seconds, such as `Expiry.days(1)` |
|
|
60
|
+
| `limits` | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]` |
|
|
61
|
+
| `scopes` | The calls the key may make, such as `[Scopes.tip20(token).transfer()]` |
|
|
61
62
|
|
|
62
63
|
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.
|
|
63
64
|
|
|
@@ -168,6 +169,19 @@ console.log(
|
|
|
168
169
|
const authorization = await device.wait()
|
|
169
170
|
```
|
|
170
171
|
|
|
172
|
+
## More Tempo Accounts
|
|
173
|
+
|
|
174
|
+
A user starts with one Tempo Account and can have more. Add one, then name it in an access key's `account`:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
const tempoAccount = await Actions.createTempoAccount(auth)
|
|
178
|
+
const accounts = await Actions.getTempoAccounts(auth) // the default first
|
|
179
|
+
|
|
180
|
+
await Actions.authorize(auth, {
|
|
181
|
+
accessKey: { ...accessKey, account: tempoAccount.address },
|
|
182
|
+
})
|
|
183
|
+
```
|
|
184
|
+
|
|
171
185
|
## Keep a sign-in
|
|
172
186
|
|
|
173
187
|
`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`.
|
|
@@ -179,11 +193,11 @@ if (Key.expired(saved.key)) signInAgain()
|
|
|
179
193
|
|
|
180
194
|
const account = Key.toAccount(saved.key)
|
|
181
195
|
const tokens = await Actions.refresh(auth, {
|
|
182
|
-
refreshToken: saved.
|
|
196
|
+
refreshToken: saved.refreshToken,
|
|
183
197
|
})
|
|
184
198
|
```
|
|
185
199
|
|
|
186
|
-
Refresh tokens rotate, so
|
|
200
|
+
Refresh tokens rotate, so save the new tokens over the old ones after each refresh, such as `{ ...saved, ...tokens }`.
|
|
187
201
|
|
|
188
202
|
## Errors
|
|
189
203
|
|
|
@@ -219,7 +233,9 @@ try {
|
|
|
219
233
|
| `authorize(auth, { accessKey })` | An `Authorization` for a user already signed in, or `undefined` |
|
|
220
234
|
| `authorizeDevice(auth, { accessKey, device })` | The code to show and a `wait()` that resolves with an `Authorization` |
|
|
221
235
|
| `createAuthorizationUrl(auth, { accessKey, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep |
|
|
236
|
+
| `createTempoAccount(auth)` | Another Tempo Account for the signed-in user |
|
|
222
237
|
| `getProviders(auth)` | The OAuth providers Tempo Auth offers, as `{ id, name }` |
|
|
238
|
+
| `getTempoAccounts(auth)` | The signed-in user's Tempo Accounts, the default first |
|
|
223
239
|
| `handleCallback(auth, { pending, url })` | The `Authorization` for a redirect's callback |
|
|
224
240
|
| `handleRedirect(auth)` | The `Authorization` when the page is a redirect's callback, or `undefined` |
|
|
225
241
|
| `redirect(auth, { accessKey })` | Nothing. The browser leaves for Tempo Auth's pages |
|
|
@@ -231,12 +247,15 @@ try {
|
|
|
231
247
|
|
|
232
248
|
### `Authorization`
|
|
233
249
|
|
|
234
|
-
| Field
|
|
235
|
-
|
|
|
236
|
-
| `account`
|
|
237
|
-
| `key`
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
250
|
+
| Field | Meaning |
|
|
251
|
+
| -------------- | -------------------------------------------------------------------------------- |
|
|
252
|
+
| `account` | The user's Tempo Account, as a viem account that signs with the app's access key |
|
|
253
|
+
| `key` | The same key as JSON, for `Key.toAccount` |
|
|
254
|
+
| `accessToken` | The Bearer token Tempo APIs accept |
|
|
255
|
+
| `expiresAt` | When the access token expires, in milliseconds |
|
|
256
|
+
| `idToken` | Optional: the OIDC ID token, which names the user |
|
|
257
|
+
| `refreshToken` | Optional: exchanges for new tokens through `refresh`. It rotates each time |
|
|
258
|
+
| `user` | The user's `email` and `id`, the `sub` of every token |
|
|
240
259
|
|
|
241
260
|
### `Key`
|
|
242
261
|
|
package/dist/Actions.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type AccessKey, type Auth, type Authorization, type Pending, type Provider, type Step, type Tokens } from './Auth.ts';
|
|
1
|
+
import { type AccessKey, type Auth, type Authorization, type Pending, type Provider, type Step, type TempoAccount, type Tokens } from './Auth.ts';
|
|
2
2
|
/**
|
|
3
3
|
* Authorizes the app for a user already signed in to Tempo Auth, from any app. Returns
|
|
4
4
|
* `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
|
|
@@ -81,6 +81,23 @@ export declare namespace createAuthorizationUrl {
|
|
|
81
81
|
url: string;
|
|
82
82
|
};
|
|
83
83
|
}
|
|
84
|
+
/**
|
|
85
|
+
* Creates another Tempo Account for the signed-in user, and returns it. Pass its `address` as an
|
|
86
|
+
* access key's `account` to authorize keys on it.
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* ```ts
|
|
90
|
+
* const tempoAccount = await Actions.createTempoAccount(auth)
|
|
91
|
+
* await Actions.authorize(auth, {
|
|
92
|
+
* accessKey: { ...accessKey, account: tempoAccount.address },
|
|
93
|
+
* })
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
96
|
+
export declare function createTempoAccount(auth: Auth): Promise<createTempoAccount.ReturnType>;
|
|
97
|
+
export declare namespace createTempoAccount {
|
|
98
|
+
/** The new account. */
|
|
99
|
+
type ReturnType = TempoAccount;
|
|
100
|
+
}
|
|
84
101
|
/**
|
|
85
102
|
* Lists the OAuth providers Tempo Auth offers, for an app that shows its own sign-in buttons.
|
|
86
103
|
*
|
|
@@ -99,6 +116,19 @@ export declare namespace getProviders {
|
|
|
99
116
|
name: string;
|
|
100
117
|
}[];
|
|
101
118
|
}
|
|
119
|
+
/**
|
|
120
|
+
* Lists the signed-in user's Tempo Accounts, their default first.
|
|
121
|
+
*
|
|
122
|
+
* @example
|
|
123
|
+
* ```ts
|
|
124
|
+
* const [account, ...others] = await Actions.getTempoAccounts(auth)
|
|
125
|
+
* ```
|
|
126
|
+
*/
|
|
127
|
+
export declare function getTempoAccounts(auth: Auth): Promise<getTempoAccounts.ReturnType>;
|
|
128
|
+
export declare namespace getTempoAccounts {
|
|
129
|
+
/** The user's accounts, their default first. */
|
|
130
|
+
type ReturnType = readonly TempoAccount[];
|
|
131
|
+
}
|
|
102
132
|
/**
|
|
103
133
|
* Finishes a sign-in redirect: checks its state, redeems the code with the PKCE verifier (and the
|
|
104
134
|
* client secret, for a backend), and reads the key authorization from the callback URL.
|
|
@@ -157,7 +187,7 @@ export declare namespace redirect {
|
|
|
157
187
|
* @example
|
|
158
188
|
* ```ts
|
|
159
189
|
* const tokens = await Actions.refresh(auth, {
|
|
160
|
-
* refreshToken: saved.
|
|
190
|
+
* refreshToken: saved.refreshToken,
|
|
161
191
|
* })
|
|
162
192
|
* ```
|
|
163
193
|
*/
|
package/dist/Actions.js
CHANGED
|
@@ -127,6 +127,22 @@ export async function createAuthorizationUrl(auth, options) {
|
|
|
127
127
|
}).toString();
|
|
128
128
|
return { pending, url: url.href };
|
|
129
129
|
}
|
|
130
|
+
/**
|
|
131
|
+
* Creates another Tempo Account for the signed-in user, and returns it. Pass its `address` as an
|
|
132
|
+
* access key's `account` to authorize keys on it.
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```ts
|
|
136
|
+
* const tempoAccount = await Actions.createTempoAccount(auth)
|
|
137
|
+
* await Actions.authorize(auth, {
|
|
138
|
+
* accessKey: { ...accessKey, account: tempoAccount.address },
|
|
139
|
+
* })
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
export async function createTempoAccount(auth) {
|
|
143
|
+
const { address } = await json(await post(auth, '/api/account/tempo', { json: {} }));
|
|
144
|
+
return { address };
|
|
145
|
+
}
|
|
130
146
|
/**
|
|
131
147
|
* Lists the OAuth providers Tempo Auth offers, for an app that shows its own sign-in buttons.
|
|
132
148
|
*
|
|
@@ -140,6 +156,20 @@ export async function getProviders(auth) {
|
|
|
140
156
|
const { providers } = await json(await (auth.fetch ?? fetch)(new URL('/api/auth/providers', auth.url)));
|
|
141
157
|
return providers;
|
|
142
158
|
}
|
|
159
|
+
/**
|
|
160
|
+
* Lists the signed-in user's Tempo Accounts, their default first.
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* ```ts
|
|
164
|
+
* const [account, ...others] = await Actions.getTempoAccounts(auth)
|
|
165
|
+
* ```
|
|
166
|
+
*/
|
|
167
|
+
export async function getTempoAccounts(auth) {
|
|
168
|
+
const { tempo } = await json(await (auth.fetch ?? fetch)(new URL('/api/account', auth.url), {
|
|
169
|
+
credentials: 'include',
|
|
170
|
+
}));
|
|
171
|
+
return tempo.map(({ address }) => ({ address }));
|
|
172
|
+
}
|
|
143
173
|
/**
|
|
144
174
|
* Finishes a sign-in redirect: checks its state, redeems the code with the PKCE verifier (and the
|
|
145
175
|
* client secret, for a backend), and reads the key authorization from the callback URL.
|
|
@@ -223,7 +253,7 @@ export async function redirect(auth, options) {
|
|
|
223
253
|
* @example
|
|
224
254
|
* ```ts
|
|
225
255
|
* const tokens = await Actions.refresh(auth, {
|
|
226
|
-
* refreshToken: saved.
|
|
256
|
+
* refreshToken: saved.refreshToken,
|
|
227
257
|
* })
|
|
228
258
|
* ```
|
|
229
259
|
*/
|
|
@@ -314,9 +344,9 @@ function authorization(body, options) {
|
|
|
314
344
|
const tokens_ = 'accessToken' in body.tokens ? body.tokens : tokens(body.tokens);
|
|
315
345
|
const claims = JSON.parse(Base64.toString(tokens_.idToken.split('.')[1]));
|
|
316
346
|
return {
|
|
347
|
+
...tokens_,
|
|
317
348
|
account: Key.toAccount(key),
|
|
318
349
|
key,
|
|
319
|
-
tokens: tokens_,
|
|
320
350
|
user: { email: claims.email, id: claims.sub },
|
|
321
351
|
};
|
|
322
352
|
}
|
package/dist/Auth.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* A Tempo Auth instance, and the types its actions take and return. Create one with
|
|
3
3
|
* {@link create}, then pass it to each action in `Actions`. Every sign-in returns an
|
|
4
|
-
* {@link Authorization}: the user's tokens
|
|
4
|
+
* {@link Authorization}: the user's tokens and a viem access key account.
|
|
5
5
|
*
|
|
6
6
|
* @example
|
|
7
7
|
* ```ts
|
|
@@ -44,19 +44,24 @@ export type Auth = {
|
|
|
44
44
|
};
|
|
45
45
|
/** What an app's access key may do, as viem's `accessKey.signAuthorization` takes it. */
|
|
46
46
|
export type AccessKey = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scopes'> & {
|
|
47
|
+
/** The user's Tempo Account the key acts for, from `getTempoAccounts`. Defaults to their first. */
|
|
48
|
+
account?: `0x${string}` | undefined;
|
|
47
49
|
/** The chain the key acts on, such as `tempoTestnet.id`. */
|
|
48
50
|
chainId: number;
|
|
49
51
|
/** Unix seconds. viem's `Expiry` builds one, such as `Expiry.days(1)`. */
|
|
50
52
|
expiry: number;
|
|
51
53
|
};
|
|
52
|
-
/**
|
|
53
|
-
export type
|
|
54
|
-
/** The
|
|
54
|
+
/** One of the user's Tempo Accounts. */
|
|
55
|
+
export type TempoAccount = {
|
|
56
|
+
/** The account's address, the same on every Tempo chain. */
|
|
57
|
+
address: `0x${string}`;
|
|
58
|
+
};
|
|
59
|
+
/** What every sign-in returns: the app's tokens for Tempo APIs, with its access key and the user. */
|
|
60
|
+
export type Authorization = Tokens & {
|
|
61
|
+
/** The user's Tempo Account, as a viem account that signs with the app's access key. */
|
|
55
62
|
account: ReturnType<typeof Key.toAccount>;
|
|
56
63
|
/** The same key as JSON, for apps that store it and rebuild it with `Key.toAccount`. */
|
|
57
64
|
key: Key.Key;
|
|
58
|
-
/** The app's tokens for Tempo APIs. */
|
|
59
|
-
tokens: Tokens;
|
|
60
65
|
/** The signed-in user, from the ID token. */
|
|
61
66
|
user: User;
|
|
62
67
|
};
|
package/dist/internal/request.js
CHANGED
|
@@ -11,6 +11,7 @@ export function request(auth, options) {
|
|
|
11
11
|
return {
|
|
12
12
|
client_id: auth.clientId,
|
|
13
13
|
keyAuthorization: {
|
|
14
|
+
...(accessKey.account ? { account: accessKey.account } : {}),
|
|
14
15
|
address: Account.fromSecp256k1(privateKey).address,
|
|
15
16
|
chainId: Hex.fromNumber(accessKey.chainId),
|
|
16
17
|
expiry: accessKey.expiry,
|
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-17.sha-08e5136",
|
|
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": {
|