@tempoxyz/auth 0.0.0-pr-87.sha-a624ff8 → 0.0.0-pr-87.sha-bc40370

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
@@ -42,39 +42,6 @@ await client.token.transferSync({
42
42
 
43
43
  Every sign-in returns the same `Authorization`: the user, the tokens for Tempo APIs, and the access key, as data in `key` and as a Viem account in `account`. A browser calls Tempo APIs with its session cookie, so its script never handles the access token.
44
44
 
45
- ## Usage with Viem
46
-
47
- `tempoAuth` extends a Viem client with the same actions as `client.auth`. It reads the chain from the client, and each sign-in sets the client's account, so the client sends with the access key.
48
-
49
- ```ts
50
- import { Auth, tempoAuth } from '@tempoxyz/auth'
51
- import { createClient, Expiry, Scopes } from 'viem/tempo'
52
- import * as Tokens from 'viem/tokens'
53
-
54
- const client = createClient({ account: Auth.account() }).extend(
55
- tempoAuth({ clientId: 'client_…' }),
56
- )
57
- const ousd = Tokens.ousd(client.chain.id).address
58
-
59
- // 1. Sign in, and authorize an access key, which becomes the client's account.
60
- await client.auth.email.signIn({
61
- code: '123456',
62
- email: 'user@example.com',
63
- permissions: {
64
- expiry: Expiry.days(1),
65
- limits: [{ limit: 10_000_000n, token: ousd }],
66
- scopes: [Scopes.tip20(ousd).transfer()],
67
- },
68
- })
69
-
70
- // 2. Send a transaction with the access key.
71
- await client.token.transferSync({
72
- amount: 10_000n,
73
- to: '0x…',
74
- token: ousd,
75
- })
76
- ```
77
-
78
45
  ## Install
79
46
 
80
47
  ```bash
@@ -84,5 +51,6 @@ pnpm add @tempoxyz/auth viem
84
51
  ## Documentation
85
52
 
86
53
  - [Guides](docs/guides/README.md): each sign-in flow, access keys, sessions, errors, and Viem.
54
+ - [Viem](docs/guides/viem.md): `tempoAuth`, which extends a Viem client with the same actions as `client.auth`.
87
55
  - [API reference](docs/api/README.md): every action, function, and type.
88
56
  - [Tempo Auth](../../docs/README.md): the service the package calls, over HTTP.
package/dist/Auth.js CHANGED
@@ -48,7 +48,7 @@ export class SignedOutError extends Error {
48
48
  export function account() {
49
49
  const state = { account: undefined };
50
50
  // Viem reads a client's account only when an action runs, through property reads, `in` checks,
51
- // and spreads, so each trap reads through to the account the latest sign-in set.
51
+ // and spreads. Each trap reads through to the account that the latest sign-in set.
52
52
  const proxy = new Proxy({}, {
53
53
  get(_, key) {
54
54
  if (key === AccountState.key)
@@ -73,7 +73,10 @@ export declare namespace tempoAuth {
73
73
  account: {
74
74
  /** `Actions.account.get`. */
75
75
  get: () => Promise<Actions.account.get.ReturnType>;
76
- /** `Actions.account.select`. */
76
+ /**
77
+ * `Actions.account.select`, which empties the client's account until the app authorizes
78
+ * the selected one.
79
+ */
77
80
  select: (options: Actions.account.select.Options) => Promise<void>;
78
81
  };
79
82
  /**
package/dist/Decorator.js CHANGED
@@ -51,23 +51,23 @@ export function tempoAuth(options) {
51
51
  throw new AccountRequiredError();
52
52
  const auth = Auth.create({ ...options, chainId: client.chain.id });
53
53
  // Counts changes to the client's account. Each sign-in applies its result only when no other
54
- // sign-in or sign-out completed after it began, so a stale result never replaces a newer one,
54
+ // sign-in or sign-out completed after it began. A stale result never replaces a newer one,
55
55
  // and a sign-in still pending at sign-out never signs the client back in.
56
56
  let version = 0;
57
- // The version the latest sign-out produced, while no change has followed it.
57
+ // The version that the latest sign-out produced, until another change follows it.
58
58
  let signedOut;
59
59
  /**
60
60
  * Begins an operation that changes the client's account. `apply` applies its result: the
61
61
  * account to sign with, or `undefined` to stop signing. `check` accepts a result that changes
62
62
  * no account, such as a step. Applying an account, or checking a step, that a newer change
63
- * overtook throws {@link SupersededError}, so the caller never holds a result the client's
64
- * newer state contradicts. `fail` rethrows the operation's error, or throws `SupersededError`
63
+ * overtook throws {@link SupersededError}. The caller never holds a result that the
64
+ * client's newer state contradicts. `fail` rethrows the operation's error, or throws `SupersededError`
65
65
  * when a newer change overtook it, so the caller never acts on a stale refusal. A sign-in
66
66
  * refused after its code or passkey verified already set a server session, which `fail` ends.
67
67
  */
68
68
  const begin = () => {
69
69
  const started = version;
70
- // A sign-in that finishes after sign-out may have set a new server session, so it ends that
70
+ // A sign-in that finishes after sign-out can set a new server session, so it ends that
71
71
  // session again, unless a newer change already followed the sign-out.
72
72
  const superseded = async () => {
73
73
  if (signedOut === version)
@@ -100,7 +100,13 @@ export function tempoAuth(options) {
100
100
  auth: {
101
101
  account: {
102
102
  get: () => Actions.account.get(auth),
103
- select: (options) => Actions.account.select(auth, options),
103
+ // The client stops signing as the previous account, which the app reauthorizes for the
104
+ // selected one.
105
+ async select(options) {
106
+ const change = begin();
107
+ await Actions.account.select(auth, options).catch(change.fail);
108
+ await change.apply(undefined);
109
+ },
104
110
  },
105
111
  async authorize(options = {}) {
106
112
  const change = begin();
@@ -130,9 +136,12 @@ export function tempoAuth(options) {
130
136
  const result = await Actions.email
131
137
  .signIn(auth, options)
132
138
  .catch(change.fail);
133
- // An account step follows a sign-in as another user, who has not chosen an account yet.
134
- if ('step' in result && result.step.type === 'account')
139
+ // An account step follows a sign-in as another user, who has not chosen an account yet. A
140
+ // newer change, such as sign-out, overtaking it ends the session the step set.
141
+ if ('step' in result && result.step.type === 'account') {
142
+ await change.check();
135
143
  await change.apply(undefined);
144
+ }
136
145
  else if ('step' in result)
137
146
  await change.check();
138
147
  else
@@ -152,9 +161,12 @@ export function tempoAuth(options) {
152
161
  const result = await Actions.passkey
153
162
  .signIn(auth, options)
154
163
  .catch(change.fail);
155
- // An account step follows a sign-in as another user, who has not chosen an account yet.
156
- if ('step' in result && result.step.type === 'account')
164
+ // An account step follows a sign-in as another user, who has not chosen an account yet. A
165
+ // newer change, such as sign-out, overtaking it ends the session the step set.
166
+ if ('step' in result && result.step.type === 'account') {
167
+ await change.check();
157
168
  await change.apply(undefined);
169
+ }
158
170
  else if ('step' in result)
159
171
  await change.check();
160
172
  else
@@ -173,7 +185,7 @@ export function tempoAuth(options) {
173
185
  async complete(options = {}) {
174
186
  const change = begin();
175
187
  const authorization = await Actions.redirect.complete(auth, options);
176
- // `undefined` means the page is not a callback, which says nothing about the session.
188
+ // `undefined` means the page is not a callback, which shows nothing about the session.
177
189
  if (authorization)
178
190
  await change.apply(authorization.account);
179
191
  return authorization;
package/dist/Key.d.ts CHANGED
@@ -34,7 +34,7 @@ export declare class AccessKeyRequiredError extends Error {
34
34
  constructor();
35
35
  }
36
36
  /**
37
- * Whether the key's authorization has expired, so a new sign-in must authorize a new key.
37
+ * Whether the key's authorization is expired, so a new sign-in must authorize a new key.
38
38
  *
39
39
  * @example
40
40
  * ```ts
package/dist/Key.js CHANGED
@@ -14,7 +14,7 @@ export class AccessKeyRequiredError extends Error {
14
14
  }
15
15
  }
16
16
  /**
17
- * Whether the key's authorization has expired, so a new sign-in must authorize a new key.
17
+ * Whether the key's authorization is expired, so a new sign-in must authorize a new key.
18
18
  *
19
19
  * @example
20
20
  * ```ts
@@ -45,8 +45,8 @@ export async function signIn(auth, options) {
45
45
  },
46
46
  }));
47
47
  // A refusal throws above, which keeps the key for a retry with a new code. Tempo Auth already took
48
- // the parked request, so a failed removal keeps the stale key, which the next email step replaces,
49
- // rather than discard the authorization.
48
+ // the parked request. A failed removal keeps the stale key, which the next email step
49
+ // replaces, rather than discard the authorization.
50
50
  if (kept && link)
51
51
  await Link.release(auth, { link }).catch(() => undefined);
52
52
  if ('step' in body) {
@@ -12,16 +12,19 @@ import type { Permissions } from '../Permissions.ts';
12
12
  import type { Step } from '../Step.ts';
13
13
  /**
14
14
  * Signs the user in with a passkey, and authorizes the app in the same call. On a page, the
15
- * passkey's one assertion also signs the app's key when that passkey owns the Tempo Account, since
16
- * the ceremony's challenge is the key's digest. A native app, which sends no `Origin`, signs in
17
- * with a random challenge and authorizes as a headless sign-in does. Returns the email step for a
18
- * wallet.tempo passkey whose account has no email: the app signs the user in with
19
- * `Actions.email.signIn`, passing the step's `link`, which links the passkey, and the same
20
- * `accessKey`, `challenge`, and `permissions`. A `signed` step's assertion already signed the key,
21
- * which that call returns without another tap, so a new key waits in the instance's `storage`.
22
- * Throws a `RequestError` with reason `webauthn_required` when another passkey owns
23
- * the account, which signs only on Tempo Auth's pages, where `Actions.redirect.start` authorizes it
24
- * for the signed-in user.
15
+ * passkey's one assertion also signs the app's key when that passkey owns the Tempo Account. This
16
+ * works because the ceremony's challenge is the key's digest. A native app, which sends no
17
+ * `Origin`, signs in with a random challenge and authorizes as a headless sign-in does.
18
+ *
19
+ * Returns the email step for a wallet.tempo passkey whose account has no email. The app then signs
20
+ * the user in with `Actions.email.signIn`. That call takes the step's `link`, which links the
21
+ * passkey, and the same `accessKey`, `challenge`, and `permissions`. A `signed` step's assertion
22
+ * already signed the key, which that call returns without another tap, so a new key waits in the
23
+ * instance's `storage`.
24
+ *
25
+ * Throws a `RequestError` with reason `webauthn_required` when another passkey owns the account.
26
+ * That passkey signs only on Tempo Auth's pages, where `Actions.redirect.start` authorizes it for
27
+ * the signed-in user.
25
28
  *
26
29
  * @example
27
30
  * ```ts
@@ -54,7 +57,7 @@ export declare namespace signIn {
54
57
  * Runs the WebAuthn ceremony in place of `navigator.credentials.get`, such as a native passkey
55
58
  * module. Its assertion must report a web origin on the relying party's domain that the app
56
59
  * registered, so an Android app's facet origin is refused. A native app's session stays in its
57
- * own `fetch`, so after `webauthn_required` it authorizes the key through
60
+ * own `fetch`. After `webauthn_required`, the app authorizes the key through
58
61
  * `Actions.redirect.createUrl` in the system browser, where the user signs in again.
59
62
  */
60
63
  getFn?: Authentication.sign.Options['getFn'] | undefined;
@@ -11,16 +11,19 @@ import * as Link from '../internal/link.js';
11
11
  import { request } from '../internal/request.js';
12
12
  /**
13
13
  * Signs the user in with a passkey, and authorizes the app in the same call. On a page, the
14
- * passkey's one assertion also signs the app's key when that passkey owns the Tempo Account, since
15
- * the ceremony's challenge is the key's digest. A native app, which sends no `Origin`, signs in
16
- * with a random challenge and authorizes as a headless sign-in does. Returns the email step for a
17
- * wallet.tempo passkey whose account has no email: the app signs the user in with
18
- * `Actions.email.signIn`, passing the step's `link`, which links the passkey, and the same
19
- * `accessKey`, `challenge`, and `permissions`. A `signed` step's assertion already signed the key,
20
- * which that call returns without another tap, so a new key waits in the instance's `storage`.
21
- * Throws a `RequestError` with reason `webauthn_required` when another passkey owns
22
- * the account, which signs only on Tempo Auth's pages, where `Actions.redirect.start` authorizes it
23
- * for the signed-in user.
14
+ * passkey's one assertion also signs the app's key when that passkey owns the Tempo Account. This
15
+ * works because the ceremony's challenge is the key's digest. A native app, which sends no
16
+ * `Origin`, signs in with a random challenge and authorizes as a headless sign-in does.
17
+ *
18
+ * Returns the email step for a wallet.tempo passkey whose account has no email. The app then signs
19
+ * the user in with `Actions.email.signIn`. That call takes the step's `link`, which links the
20
+ * passkey, and the same `accessKey`, `challenge`, and `permissions`. A `signed` step's assertion
21
+ * already signed the key, which that call returns without another tap, so a new key waits in the
22
+ * instance's `storage`.
23
+ *
24
+ * Throws a `RequestError` with reason `webauthn_required` when another passkey owns the account.
25
+ * That passkey signs only on Tempo Auth's pages, where `Actions.redirect.start` authorizes it for
26
+ * the signed-in user.
24
27
  *
25
28
  * @example
26
29
  * ```ts
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Signs the user in on Tempo Auth's pages, which redirect back with a code. `start` and `complete`
3
- * keep the redirect's state in `storage` for a browser app. `createUrl` and `handleCallback` hand
3
+ * keep the redirect's state in `storage` for a browser app. `createUrl` and `handleCallback` leave
4
4
  * it to the app to keep, for a backend or a native app.
5
5
  * @module
6
6
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/auth",
3
- "version": "0.0.0-pr-87.sha-a624ff8",
3
+ "version": "0.0.0-pr-87.sha-bc40370",
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": {