@tempoxyz/auth 0.0.0-pr-19.sha-2c8fa8e → 0.0.0-pr-22.sha-291bbcb

package/README.md

@@ -52,15 +52,15 @@ The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli`
 
 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:
 
-| Field     | Meaning                                                                                      |
-| --------- | -------------------------------------------------------------------------------------------- |
-| `account` | Optional: which of the user's Tempo Accounts, from `getTempoAccounts`. Defaults to the first |
-| `chainId` | The chain the key acts on, such as `tempoTestnet.id`                                         |
-| `expiry`  | When the key expires, in Unix seconds, such as `Expiry.days(1)`                              |
-| `limits`  | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]`                |
-| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`                       |
+| Field     | Meaning                                                                                       |
+| --------- | --------------------------------------------------------------------------------------------- |
+| `account` | Optional: which of the user's Tempo Accounts, from `tempoAccount.list`. Defaults to the first |
+| `chainId` | The chain the key acts on, such as `tempoTestnet.id`                                          |
+| `expiry`  | When the key expires, in Unix seconds, such as `Expiry.days(1)`                               |
+| `limits`  | One-time spending limits per token, such as `[{ limit: 10_000_000n, token }]`                 |
+| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`                        |
 
-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.
+Flows without a Tempo Auth page (`authorize`, `email.signIn`) must stay within Tempo Auth's ceiling, about $1,000 per token. 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.
 
 The returned `account` attaches the key's authorization to its first transaction, which registers the key on chain.
 
@@ -75,18 +75,18 @@ For a browser app that renders its own email form. The page calls Tempo Auth wit
 const authorization = await Actions.authorize(auth, { accessKey })
 
 // Otherwise, sign in with an emailed code.
-await Actions.sendCode(auth, { email })
-const result = await Actions.verifyCode(auth, { accessKey, code, email })
+await Actions.email.sendCode(auth, { email })
+const result = await Actions.email.signIn(auth, { accessKey, code, email })
 
 // An address that requires SSO continues at its connection, and returns to this page.
-if ('step' in result) Actions.signIn(auth, { url: result.step.url })
+if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
 ```
 
 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.
 
 ```ts
-const providers = await Actions.getProviders(auth) // [{ id: 'google', name: 'Google' }]
-Actions.signIn(auth, { provider: 'google' })
+const providers = await Actions.provider.list(auth) // [{ id: 'google', name: 'Google' }]
+Actions.provider.signIn(auth, { provider: 'google' })
 ```
 
 ### Tempo Auth's pages
@@ -94,13 +94,13 @@ Actions.signIn(auth, { provider: 'google' })
 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.
 
 ```ts
-await Actions.redirect(auth, { accessKey })
+await Actions.redirect.start(auth, { accessKey })
 
 // On the page the browser returns to, and on every load:
-const authorization = await Actions.handleRedirect(auth)
+const authorization = await Actions.redirect.complete(auth)
 ```
 
-`redirect` keeps its state in session storage until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere.
+`redirect.start` keeps its state in session storage until the browser returns. Pass `storage` to `Auth.create` to keep it elsewhere.
 
 ### A mobile app
 
@@ -116,16 +116,16 @@ const auth = Auth.create({
 })
 
 // Your own sign-in UI, as in a browser.
-await Actions.sendCode(auth, { email })
-const result = await Actions.verifyCode(auth, { accessKey, code, email })
+await Actions.email.sendCode(auth, { email })
+const result = await Actions.email.signIn(auth, { accessKey, code, email })
 
 // Or Tempo Auth's pages, which also offer Google and SSO.
-const { pending, url } = await Actions.createAuthorizationUrl(auth, {
+const { pending, url } = await Actions.redirect.createUrl(auth, {
   accessKey,
 })
 const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
 if (session.type === 'success')
-  authorization = await Actions.handleCallback(auth, {
+  authorization = await Actions.redirect.handleCallback(auth, {
     pending,
     url: session.url,
   })
@@ -141,14 +141,14 @@ For an app whose server holds a client secret. The server builds the URL, keeps
 const auth = Auth.create({ clientId, clientSecret, url })
 
 // GET /auth/start
-const { pending, url } = await Actions.createAuthorizationUrl(auth, {
+const { pending, url } = await Actions.redirect.createUrl(auth, {
   accessKey,
   redirectUri: 'https://app.example/auth/callback',
 })
 // Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
 
 // GET /auth/callback
-const authorization = await Actions.handleCallback(auth, {
+const authorization = await Actions.redirect.handleCallback(auth, {
   pending,
   url: request.url,
 })
@@ -159,7 +159,7 @@ const authorization = await Actions.handleCallback(auth, {
 For a command-line tool. The user approves a code in any browser, and the CLI waits.
 
 ```ts
-const device = await Actions.authorizeDevice(auth, {
+const device = await Actions.device.authorize(auth, {
   accessKey,
   device: os.hostname(),
 })
@@ -174,8 +174,8 @@ const authorization = await device.wait()
 A user starts with one Tempo Account and can have more. Add one, then name it in an access key's `account`:
 
 ```ts
-const tempoAccount = await Actions.createTempoAccount(auth)
-const accounts = await Actions.getTempoAccounts(auth) // the default first
+const tempoAccount = await Actions.tempoAccount.create(auth)
+const accounts = await Actions.tempoAccount.list(auth) // the default first
 
 await Actions.authorize(auth, {
   accessKey: { ...accessKey, account: tempoAccount.address },
@@ -205,7 +205,7 @@ A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `
 
 ```ts
 try {
-  await Actions.verifyCode(auth, { accessKey, code, email })
+  await Actions.email.signIn(auth, { accessKey, code, email })
 } catch (error) {
   if (error instanceof Auth.RequestError && error.status === 401)
     showWrongCode()
@@ -223,27 +223,29 @@ try {
 | `clientSecret` | The app's client secret. Only a backend holds one                                               |
 | `redirectUri`  | Where Tempo Auth redirects back to. Defaults to the page's origin                               |
 | `scope`        | Scopes beyond `openid` and `email`, which every instance includes. Defaults to `offline_access` |
-| `storage`      | Where `redirect` keeps its state. Defaults to session storage                                   |
+| `storage`      | Where `redirect.start` keeps its state. Defaults to session storage                             |
 | `fetch`        | Calls Tempo Auth. Defaults to the global `fetch`                                                |
 
 ### `Actions`
 
-| Action                                                     | Returns                                                                    |
-| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `authorize(auth, { accessKey })`                           | An `Authorization` for a user already signed in, or `undefined`            |
-| `authorizeDevice(auth, { accessKey, device })`             | The code to show and a `wait()` that resolves with an `Authorization`      |
-| `createAuthorizationUrl(auth, { accessKey, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep          |
-| `createTempoAccount(auth)`                                 | Another Tempo Account for the signed-in user                               |
-| `getProviders(auth)`                                       | The OAuth providers Tempo Auth offers, as `{ id, name }`                   |
-| `getTempoAccounts(auth)`                                   | The signed-in user's Tempo Accounts, the default first                     |
-| `handleCallback(auth, { pending, url })`                   | The `Authorization` for a redirect's callback                              |
-| `handleRedirect(auth)`                                     | The `Authorization` when the page is a redirect's callback, or `undefined` |
-| `redirect(auth, { accessKey })`                            | Nothing. The browser leaves for Tempo Auth's pages                         |
-| `refresh(auth, { refreshToken })`                          | New `Tokens`                                                               |
-| `sendCode(auth, { email })`                                | Nothing. Tempo Auth emails a code                                          |
-| `signIn(auth, { provider } \| { url })`                    | Nothing. The browser leaves for the provider or SSO connection             |
-| `signOut(auth)`                                            | Nothing. The user's Tempo Auth session ends                                |
-| `verifyCode(auth, { accessKey, code, email })`             | An `Authorization`, or the `step` the address requires first               |
+Each sign-in flow has its own namespace. The actions every flow shares sit at the top level.
+
+| Action                                                 | Returns                                                                    |
+| ------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `authorize(auth, { accessKey })`                       | An `Authorization` for a user already signed in, or `undefined`            |
+| `refresh(auth, { refreshToken })`                      | New `Tokens`                                                               |
+| `signOut(auth)`                                        | Nothing. The user's Tempo Auth session ends                                |
+| `device.authorize(auth, { accessKey, device })`        | The code to show and a `wait()` that resolves with an `Authorization`      |
+| `email.sendCode(auth, { email })`                      | Nothing. Tempo Auth emails a code                                          |
+| `email.signIn(auth, { accessKey, code, email })`       | An `Authorization`, or the `step` the address requires first               |
+| `provider.list(auth)`                                  | The OAuth providers Tempo Auth offers, as `{ id, name }`                   |
+| `provider.signIn(auth, { provider } \| { url })`       | Nothing. The browser leaves for the provider or SSO connection             |
+| `redirect.complete(auth)`                              | The `Authorization` when the page is a redirect's callback, or `undefined` |
+| `redirect.createUrl(auth, { accessKey, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep          |
+| `redirect.handleCallback(auth, { pending, url })`      | The `Authorization` for a redirect's callback                              |
+| `redirect.start(auth, { accessKey })`                  | Nothing. The browser leaves for Tempo Auth's pages                         |
+| `tempoAccount.create(auth)`                            | Another Tempo Account for the signed-in user                               |
+| `tempoAccount.list(auth)`                              | The signed-in user's Tempo Accounts, the default first                     |
 
 ### `Authorization`
 

package/dist/Actions.d.ts

@@ -1,4 +1,9 @@
-import { type AccessKey, type Auth, type Authorization, type Pending, type Provider, type Step, type TempoAccount, type Tokens } from './Auth.ts';
+import type { AccessKey, Auth, Authorization, Tokens } from './Auth.ts';
+export * as device from './actions/device.ts';
+export * as email from './actions/email.ts';
+export * as provider from './actions/provider.ts';
+export * as redirect from './actions/redirect.ts';
+export * as tempoAccount from './actions/tempoAccount.ts';
 /**
  * Authorizes the app for a user already signed in to Tempo Auth, from any app. Returns
  * `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
@@ -19,168 +24,6 @@ export declare namespace authorize {
     /** The authorization, or `undefined` without a session. */
     type ReturnType = Authorization | undefined;
 }
-/**
- * Starts the device grant for a CLI: the user approves `userCode` at `verificationUri` from any
- * browser, and `wait` resolves once they do.
- *
- * @example
- * ```ts
- * const device = await Actions.authorizeDevice(auth, { accessKey, device: Os.hostname() })
- * console.log(`Open ${device.verificationUriComplete}`)
- * const authorization = await device.wait()
- * ```
- */
-export declare function authorizeDevice(auth: Auth, options: authorizeDevice.Options): Promise<authorizeDevice.ReturnType>;
-export declare namespace authorizeDevice {
-    type Options = {
-        /** What the CLI's key may do. The approval page shows it beside the device. */
-        accessKey: AccessKey;
-        /** The name the approval page shows, such as the machine's hostname. */
-        device: string;
-    };
-    type ReturnType = {
-        /** Seconds until the code expires. */
-        expiresIn: number;
-        /** The code the user confirms in the browser. */
-        userCode: string;
-        /** Where the user enters the code. */
-        verificationUri: string;
-        /** Where the user approves the code, with it already filled in. */
-        verificationUriComplete: string;
-        /** Resolves with the authorization once the user approves. */
-        wait: () => Promise<Authorization>;
-    };
-}
-/**
- * Returns the URL that signs the user in on Tempo Auth's pages and redirects back with a code,
- * and the {@link Pending} state to keep until then, such as in a sealed cookie.
- * {@link handleCallback} redeems the code for the tokens and the key authorization.
- *
- * @example
- * ```ts
- * const { pending, url } = await Actions.createAuthorizationUrl(auth, {
- *   accessKey,
- *   redirectUri: 'https://app.example/auth/callback',
- * })
- * await seal(c, 'oauth', pending)
- * return c.redirect(url)
- * ```
- */
-export declare function createAuthorizationUrl(auth: Auth, options: createAuthorizationUrl.Options): Promise<createAuthorizationUrl.ReturnType>;
-export declare namespace createAuthorizationUrl {
-    type Options = {
-        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
-        accessKey: AccessKey;
-        /** Where Tempo Auth redirects back to. Defaults to the instance's `redirectUri`. */
-        redirectUri?: string | undefined;
-    };
-    type ReturnType = {
-        /** What to keep until the callback, such as in a sealed cookie. */
-        pending: Pending;
-        /** Where to send the browser. */
-        url: string;
-    };
-}
-/**
- * Creates another Tempo Account for the signed-in user, and returns it. Pass its `address` as an
- * access key's `account` to authorize keys on it.
- *
- * @example
- * ```ts
- * const tempoAccount = await Actions.createTempoAccount(auth)
- * await Actions.authorize(auth, {
- *   accessKey: { ...accessKey, account: tempoAccount.address },
- * })
- * ```
- */
-export declare function createTempoAccount(auth: Auth): Promise<createTempoAccount.ReturnType>;
-export declare namespace createTempoAccount {
-    /** The new account. */
-    type ReturnType = TempoAccount;
-}
-/**
- * Lists the OAuth providers Tempo Auth offers, for an app that shows its own sign-in buttons.
- *
- * @example
- * ```ts
- * const providers = await Actions.getProviders(auth)
- * // [{ id: 'google', name: 'Google' }]
- * ```
- */
-export declare function getProviders(auth: Auth): Promise<getProviders.ReturnType>;
-export declare namespace getProviders {
-    type ReturnType = readonly {
-        /** The provider's short name, which `signIn` takes. */
-        id: Provider;
-        /** The name to show, such as `Google`. */
-        name: string;
-    }[];
-}
-/**
- * Lists the signed-in user's Tempo Accounts, their default first.
- *
- * @example
- * ```ts
- * const [account, ...others] = await Actions.getTempoAccounts(auth)
- * ```
- */
-export declare function getTempoAccounts(auth: Auth): Promise<getTempoAccounts.ReturnType>;
-export declare namespace getTempoAccounts {
-    /** The user's accounts, their default first. */
-    type ReturnType = readonly TempoAccount[];
-}
-/**
- * Finishes a sign-in redirect: checks its state, and redeems the code with the PKCE verifier (and
- * the client secret, for a backend) for the tokens and the key authorization.
- *
- * @example
- * ```ts
- * const authorization = await Actions.handleCallback(auth, {
- *   pending: await unseal(c, 'oauth'),
- *   url: c.req.url,
- * })
- * ```
- */
-export declare function handleCallback(auth: Auth, options: handleCallback.Options): Promise<Authorization>;
-export declare namespace handleCallback {
-    type Options = {
-        /** What `createAuthorizationUrl` returned to keep. */
-        pending: Pending;
-        /** The callback URL Tempo Auth redirected to. */
-        url: string | URL;
-    };
-}
-/**
- * Finishes a {@link redirect} when the page loads with Tempo Auth's callback, and returns
- * `undefined` otherwise. The code is redeemed once, however often the page calls this.
- *
- * @example
- * ```ts
- * const authorization =
- *   (await Actions.handleRedirect(auth)) ??
- *   (await Actions.authorize(auth, { accessKey }))
- * ```
- */
-export declare function handleRedirect(auth: Auth): Promise<handleRedirect.ReturnType>;
-export declare namespace handleRedirect {
-    /** The authorization, or `undefined` when the page is not a redirect's callback. */
-    type ReturnType = Authorization | undefined;
-}
-/**
- * Sends the browser to Tempo Auth's pages to sign in, keeping the redirect's state in `storage`.
- *
- * @example
- * ```ts
- * await Actions.redirect(auth, { accessKey })
- * ```
- */
-export declare function redirect(auth: Auth, options: redirect.Options): Promise<void>;
-export declare namespace redirect {
-    type Options = {
-        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
-        accessKey: AccessKey;
-    };
-}
 /**
  * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.
  *
@@ -198,43 +41,6 @@ export declare namespace refresh {
         refreshToken: string;
     };
 }
-/**
- * Emails the user a sign-in code. The response is the same for every address.
- *
- * @example
- * ```ts
- * await Actions.sendCode(auth, { email: 'user@example.com' })
- * ```
- */
-export declare function sendCode(auth: Auth, options: sendCode.Options): Promise<void>;
-export declare namespace sendCode {
-    type Options = {
-        /** The user's email address. */
-        email: string;
-    };
-}
-/**
- * Sends the browser to an OAuth provider, or to the SSO connection a {@link Step} names, and back to
- * `returnTo` signed in to Tempo Auth. The app then calls {@link authorize}.
- *
- * @example
- * ```ts
- * Actions.signIn(auth, { provider: 'google' })
- * ```
- */
-export declare function signIn(auth: Auth, options: signIn.Options): void;
-export declare namespace signIn {
-    type Options = ({
-        /** The OAuth provider to sign in with, from `getProviders`. */
-        provider: Provider;
-    } | {
-        /** The URL of a `Step`, such as the SSO connection an address requires. */
-        url: string;
-    }) & {
-        /** Where to return. Defaults to the current page. It must be on an internal origin. */
-        returnTo?: string | undefined;
-    };
-}
 /**
  * Ends the user's Tempo Auth session, which signs them out of every app that relies on it.
  *
@@ -244,28 +50,3 @@ export declare namespace signIn {
  * ```
  */
 export declare function signOut(auth: Auth): Promise<void>;
-/**
- * Signs the user in with the code they were emailed, and authorizes the app in the same call.
- * Returns a {@link Step} when the address requires SSO, which {@link signIn} continues.
- *
- * @example
- * ```ts
- * const result = await Actions.verifyCode(auth, { accessKey, code, email })
- * if ('step' in result) Actions.signIn(auth, { url: result.step.url })
- * ```
- */
-export declare function verifyCode(auth: Auth, options: verifyCode.Options): Promise<verifyCode.ReturnType>;
-export declare namespace verifyCode {
-    type Options = {
-        /** What the app's key may do. It must fit the headless ceiling. */
-        accessKey: AccessKey;
-        /** The 6-digit code the user was emailed. */
-        code: string;
-        /** The address the code was sent to. */
-        email: string;
-    };
-    /** The authorization, or the step the address requires first. */
-    type ReturnType = Authorization | {
-        step: Step;
-    };
-}