@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 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 `tokens.accessToken`.
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
- | `chainId` | The chain the key acts on, such as `tempoTestnet.id` |
58
- | `expiry` | When the key expires, in Unix seconds, such as `Expiry.days(1)` |
59
- | `limits` | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]` |
60
- | `scopes` | The calls the key may make, such as `[Scopes.tip20(token).transfer()]` |
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.tokens.refreshToken,
196
+ refreshToken: saved.refreshToken,
183
197
  })
184
198
  ```
185
199
 
186
- Refresh tokens rotate, so store the new `tokens` after each refresh.
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 | Meaning |
235
- | --------- | ------------------------------------------------------------------------------- |
236
- | `account` | The app's key as a viem access key account, acting for the user's Tempo Account |
237
- | `key` | The same key as JSON, for `Key.toAccount` |
238
- | `tokens` | `accessToken`, `expiresAt`, and the optional `idToken` and `refreshToken` |
239
- | `user` | The user's `email` and `id`, the `sub` of every token |
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.tokens.refreshToken,
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.tokens.refreshToken,
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, and a viem access key account.
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
- /** What every sign-in returns. */
53
- export type Authorization = {
54
- /** The app's access key, as a viem account acting for the user's Tempo Account. */
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
  };
@@ -13,6 +13,7 @@ export declare function request(auth: Auth, options: {
13
13
  }): {
14
14
  client_id: string;
15
15
  keyAuthorization: {
16
+ account?: `0x${string}`;
16
17
  address: `0x${string}`;
17
18
  chainId: `0x${string}`;
18
19
  expiry: number;
@@ -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-15.sha-cf4e7ec",
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": {