@tempoxyz/auth 0.0.0-pr-28.sha-72f7afa → 0.0.0-pr-31.sha-03ddfa6

package/README.md

@@ -6,12 +6,8 @@ Every sign-in returns the same `Authorization`. Send transactions with its `acco
 
 ```ts
 import { Actions, Auth } from '@tempoxyz/auth'
-import { createClient, Expiry, Scopes } from 'viem/tempo'
-import { tempo, tempoTestnet } from 'viem/tempo/chains'
-import * as Tokens from 'viem/tokens'
-
-// OUSD has its mainnet address on every Tempo chain.
-const ousd = Tokens.ousd(tempo.id).address
+import { Addresses, createClient, Expiry, Scopes } from 'viem/tempo'
+import { tempoTestnet } from 'viem/tempo/chains'
 
 const auth = Auth.create({
   chainId: tempoTestnet.id,
@@ -20,14 +16,14 @@ const auth = Auth.create({
 })
 const client = createClient({
   chain: tempoTestnet,
-  feeToken: ousd,
+  feeToken: Addresses.pathUsd,
 })
 
 const authorization = await Actions.authorize(auth, {
   permissions: {
     expiry: Expiry.days(1),
-    limits: [{ limit: 10_000_000n, token: ousd }],
-    scopes: [Scopes.tip20(ousd).transfer()],
+    limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
+    scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
   },
 })
 
@@ -35,7 +31,7 @@ await client.token.transferSync({
   account: authorization!.account,
   amount: 10_000n,
   to: '0x…',
-  token: ousd,
+  token: Addresses.pathUsd,
 })
 ```
 
@@ -54,14 +50,14 @@ The CLI device grant needs neither. It signs in as Tempo Auth's own `tempo-cli`
 
 ## Access keys
 
-Each sign-in creates a key for the app and asks Tempo Auth to authorize it on the user's Tempo Account. The optional `permissions` option says what the key may do, with viem's `Expiry` and `Scopes` helpers. Tempo Auth fills every field it leaves out with the headless ceiling:
+Each sign-in creates a key for the app and asks Tempo Auth to authorize it on the user's Tempo Account. The `permissions` option says what the key may do, with viem's `Expiry` and `Scopes` helpers:
 
-| Field     | Meaning                                                                                                     |
-| --------- | ----------------------------------------------------------------------------------------------------------- |
-| `chainId` | The chain the key acts on. Defaults to the instance's `chainId`                                             |
-| `expiry`  | When the key expires, in Unix seconds, such as `Expiry.days(1)`. Defaults to a year                         |
-| `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 |
-| `scopes`  | The calls the key may make, such as `[Scopes.tip20(token).transfer()]`. Defaults to transfers of each token the key limits |
+| Field     | Meaning                                                                       |
+| --------- | ----------------------------------------------------------------------------- |
+| `chainId` | Optional: the chain the key acts on. Defaults to the instance's `chainId`     |
+| `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()]`        |
 
 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 gets a secp256k1 key, which it stores as a string.
 
@@ -69,10 +65,10 @@ To authorize a key the app already holds, pass it as `accessKey`, a viem account
 
 ```ts
 const accessKey = Account.fromWebCryptoP256(keyPair, { access: tempoAccount })
-await Actions.authorize(auth, { accessKey })
+await Actions.authorize(auth, { accessKey, permissions })
 ```
 
-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.
+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.
 
@@ -84,11 +80,11 @@ For a browser app that renders its own email form. The page calls Tempo Auth wit
 
 ```ts
 // A user already signed in to Tempo Auth, from any app, needs no form.
-const authorization = await Actions.authorize(auth)
+const authorization = await Actions.authorize(auth, { permissions })
 
 // Otherwise, sign in with an emailed code.
 await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { code, email })
+const result = await Actions.email.signIn(auth, { code, email, permissions })
 
 // An address that requires SSO continues at its connection, and returns to this page.
 if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
@@ -106,7 +102,7 @@ Actions.provider.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.start(auth)
+await Actions.redirect.start(auth, { permissions })
 
 // On the page the browser returns to, and on every load:
 const authorization = await Actions.redirect.complete(auth)
@@ -129,10 +125,12 @@ const auth = Auth.create({
 
 // Your own sign-in UI, as in a browser.
 await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { code, email })
+const result = await Actions.email.signIn(auth, { code, email, permissions })
 
 // Or Tempo Auth's pages, which also offer Google and SSO.
-const { pending, url } = await Actions.redirect.createUrl(auth)
+const { pending, url } = await Actions.redirect.createUrl(auth, {
+  permissions,
+})
 const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
 if (session.type === 'success')
   authorization = await Actions.redirect.handleCallback(auth, {
@@ -152,6 +150,7 @@ const auth = Auth.create({ clientId, clientSecret, url })
 
 // GET /auth/start
 const { pending, url } = await Actions.redirect.createUrl(auth, {
+  permissions,
   redirectUri: 'https://app.example/auth/callback',
 })
 // Keep `pending` in an encrypted, HttpOnly cookie, then redirect to `url`.
@@ -170,6 +169,7 @@ For a command-line tool. The user approves a code in any browser, and the CLI wa
 ```ts
 const device = await Actions.device.authorize(auth, {
   device: os.hostname(),
+  permissions,
 })
 console.log(
   `Open ${device.verificationUriComplete} and confirm ${device.userCode}.`,
@@ -189,6 +189,7 @@ await Actions.authorize(auth, {
   accessKey: Account.fromWebCryptoP256(keyPair, {
     access: tempoAccount.address,
   }),
+  permissions,
 })
 ```
 
@@ -219,7 +220,7 @@ A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `
 
 ```ts
 try {
-  await Actions.email.signIn(auth, { code, email })
+  await Actions.email.signIn(auth, { code, email, permissions })
 } catch (error) {
   if (error instanceof Auth.RequestError && error.status === 401)
     showWrongCode()
@@ -243,22 +244,22 @@ try {
 
 ### `Actions`
 
-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`.
+Each sign-in flow has its own namespace. The actions every flow shares sit at the top level. Every action that takes `permissions` also takes an optional `accessKey`.
 
 | Action                                                   | Returns                                                                    |
 | -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `authorize(auth)`                                        | An `Authorization` for a user already signed in, or `undefined`            |
+| `authorize(auth, { permissions })`                       | 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, { device })`                     | The code to show and a `wait()` that resolves with an `Authorization`      |
+| `device.authorize(auth, { device, permissions })`        | 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, { code, email })`                    | An `Authorization`, or the `step` the address requires first               |
+| `email.signIn(auth, { code, email, permissions })`       | 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, { accessKey })`                 | The `Authorization` when the page is a redirect's callback, or `undefined` |
-| `redirect.createUrl(auth, { redirectUri })`              | The `url` to send the browser to, and the `pending` state to keep          |
+| `redirect.createUrl(auth, { permissions, 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)`                                   | Nothing. The browser leaves for Tempo Auth's pages                         |
+| `redirect.start(auth, { permissions })`                  | 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                     |
 

package/dist/Actions.d.ts

@@ -20,11 +20,11 @@ export * as tempoAccount from './actions/tempoAccount.ts';
  *
  * @example
  * ```ts
- * const authorization = await Actions.authorize(auth)
+ * const authorization = await Actions.authorize(auth, { permissions })
  * if (!authorization) showSignIn()
  * ```
  */
-export declare function authorize(auth: Auth, options?: authorize.Options): Promise<authorize.ReturnType>;
+export declare function authorize(auth: Auth, options: authorize.Options): Promise<authorize.ReturnType>;
 export declare namespace authorize {
     type Options = {
         /**
@@ -32,8 +32,8 @@ export declare namespace authorize {
          * defaults to the user's first. Defaults to a new key.
          */
         accessKey?: Account.Account | undefined;
-        /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        /** What the key may do. It must fit the headless ceiling. */
+        permissions: Permissions;
     };
     /** The authorization, or `undefined` without a session. */
     type ReturnType = Authorization | undefined;

package/dist/Actions.js

@@ -13,11 +13,11 @@ export * as tempoAccount from './actions/tempoAccount.js';
  *
  * @example
  * ```ts
- * const authorization = await Actions.authorize(auth)
+ * const authorization = await Actions.authorize(auth, { permissions })
  * if (!authorization) showSignIn()
  * ```
  */
-export async function authorize(auth, options = {}) {
+export async function authorize(auth, options) {
     // Checking the session first answers a visitor without one with no failed request.
     const session = await Api.json(await (auth.fetch ?? fetch)(new URL('/api/auth/session', auth.url), {
         credentials: 'include',

package/dist/Auth.js

@@ -6,11 +6,8 @@
  * @example
  * ```ts
  * import { Actions, Auth } from '@tempoxyz/auth'
- * import { Expiry, Scopes } from 'viem/tempo'
- * import { tempo, tempoTestnet } from 'viem/tempo/chains'
- * import * as Tokens from 'viem/tokens'
- *
- * const ousd = Tokens.ousd(tempo.id).address
+ * import { Addresses, Expiry, Scopes } from 'viem/tempo'
+ * import { tempoTestnet } from 'viem/tempo/chains'
  *
  * const auth = Auth.create({
  *   chainId: tempoTestnet.id,
@@ -21,8 +18,8 @@
  * const authorization = await Actions.authorize(auth, {
  *   permissions: {
  *     expiry: Expiry.days(1),
- *     limits: [{ limit: 10_000_000n, token: ousd }],
- *     scopes: [Scopes.tip20(ousd).transfer()],
+ *     limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
+ *     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
  *   },
  * })
  * ```

package/dist/Permissions.d.ts

@@ -3,19 +3,12 @@
  * @module
  */
 import type { KeyAuthorization } from 'ox/tempo';
-/**
- * What an app's access key may do, as viem's `accessKey.authorize` takes it. Tempo Auth fills what
- * it leaves out with the headless ceiling.
- */
-export type Permissions = {
+/** What an app's access key may do, as viem's `accessKey.authorize` takes it. */
+export type Permissions = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scopes'> & {
     /** The chain the key acts on, such as `tempoTestnet.id`. Defaults to the instance's `chainId`. */
     chainId?: number | undefined;
-    /** Unix seconds. viem's `Expiry` builds one, such as `Expiry.days(1)`. Defaults to a year from now. */
-    expiry?: number | undefined;
-    /** How much of each token the key may spend. Defaults to about $1,000 of each token it calls, or of OUSD. */
-    limits?: KeyAuthorization.KeyAuthorization['limits'];
-    /** The calls the key may make. Defaults to transfers of each token it limits. */
-    scopes?: KeyAuthorization.KeyAuthorization['scopes'];
+    /** Unix seconds. viem's `Expiry` builds one, such as `Expiry.days(1)`. */
+    expiry: number;
 };
 /**
  * Instantiates a {@link Permissions}.
@@ -24,8 +17,8 @@ export type Permissions = {
  * ```ts
  * const permissions = Permissions.from({
  *   expiry: Expiry.days(1),
- *   limits: [{ limit: 10_000_000n, token: ousd }],
- *   scopes: [Scopes.tip20(ousd).transfer()],
+ *   limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
+ *   scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
  * })
  * ```
  */

package/dist/Permissions.js

@@ -5,8 +5,8 @@
  * ```ts
  * const permissions = Permissions.from({
  *   expiry: Expiry.days(1),
- *   limits: [{ limit: 10_000_000n, token: ousd }],
- *   scopes: [Scopes.tip20(ousd).transfer()],
+ *   limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
+ *   scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
  * })
  * ```
  */

package/dist/actions/device.d.ts

@@ -8,7 +8,7 @@ import type { Permissions } from '../Permissions.ts';
  *
  * @example
  * ```ts
- * const device = await Actions.device.authorize(auth, { device: Os.hostname() })
+ * const device = await Actions.device.authorize(auth, { device: Os.hostname(), permissions })
  * console.log(`Open ${device.verificationUriComplete}`)
  * const authorization = await device.wait()
  * ```
@@ -23,8 +23,8 @@ export declare namespace authorize {
         accessKey?: Account.Account | undefined;
         /** The name the approval page shows, such as the machine's hostname. */
         device: string;
-        /** What the CLI's key may do. The approval page shows it beside the device, and the headless ceiling fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        /** What the CLI's key may do. The approval page shows it beside the device. */
+        permissions: Permissions;
     };
     type ReturnType = {
         /** Seconds until the code expires. */

package/dist/actions/device.js

@@ -8,7 +8,7 @@ import { request } from '../internal/request.js';
  *
  * @example
  * ```ts
- * const device = await Actions.device.authorize(auth, { device: Os.hostname() })
+ * const device = await Actions.device.authorize(auth, { device: Os.hostname(), permissions })
  * console.log(`Open ${device.verificationUriComplete}`)
  * const authorization = await device.wait()
  * ```

package/dist/actions/email.d.ts

@@ -28,7 +28,7 @@ export declare namespace sendCode {
  *
  * @example
  * ```ts
- * const result = await Actions.email.signIn(auth, { code, email })
+ * const result = await Actions.email.signIn(auth, { code, email, permissions })
  * if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
  * ```
  */
@@ -44,8 +44,8 @@ export declare namespace signIn {
         code: string;
         /** The address the code was sent to. */
         email: string;
-        /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        /** What the key may do. It must fit the headless ceiling. */
+        permissions: Permissions;
     };
     /** The authorization, or the step the address requires first. */
     type ReturnType = Authorization | {

package/dist/actions/email.js

@@ -18,7 +18,7 @@ export async function sendCode(auth, options) {
  *
  * @example
  * ```ts
- * const result = await Actions.email.signIn(auth, { code, email })
+ * const result = await Actions.email.signIn(auth, { code, email, permissions })
  * if ('step' in result) Actions.provider.signIn(auth, { url: result.step.url })
  * ```
  */

package/dist/actions/redirect.d.ts

@@ -11,7 +11,7 @@ import type { Permissions } from '../Permissions.ts';
  * ```ts
  * const authorization =
  *   (await Actions.redirect.complete(auth)) ??
- *   (await Actions.authorize(auth))
+ *   (await Actions.authorize(auth, { permissions }))
  * ```
  */
 export declare function complete(auth: Auth, options?: complete.Options): Promise<complete.ReturnType>;
@@ -31,13 +31,14 @@ export declare namespace complete {
  * @example
  * ```ts
  * const { pending, url } = await Actions.redirect.createUrl(auth, {
+ *   permissions,
  *   redirectUri: 'https://app.example/auth/callback',
  * })
  * await seal(c, 'oauth', pending)
  * return c.redirect(url)
  * ```
  */
-export declare function createUrl(auth: Auth, options?: createUrl.Options): Promise<createUrl.ReturnType>;
+export declare function createUrl(auth: Auth, options: createUrl.Options): Promise<createUrl.ReturnType>;
 export declare namespace createUrl {
     type Options = {
         /**
@@ -45,8 +46,8 @@ export declare namespace createUrl {
          * defaults to the user's first. Defaults to a new key, whose material `pending` keeps.
          */
         accessKey?: Account.Account | undefined;
-        /** What the key may do. Tempo Auth's pages show it, and the headless ceiling fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        /** What the key may do. Tempo Auth's pages show it, and the user approves it. */
+        permissions: Permissions;
         /** Where Tempo Auth redirects back to. Defaults to the instance's `redirectUri`. */
         redirectUri?: string | undefined;
     };
@@ -86,10 +87,10 @@ export declare namespace handleCallback {
  *
  * @example
  * ```ts
- * await Actions.redirect.start(auth)
+ * await Actions.redirect.start(auth, { permissions })
  * ```
  */
-export declare function start(auth: Auth, options?: start.Options): Promise<void>;
+export declare function start(auth: Auth, options: start.Options): Promise<void>;
 export declare namespace start {
     type Options = {
         /**
@@ -97,7 +98,7 @@ export declare namespace start {
          * key, which `storage` keeps until the browser returns.
          */
         accessKey?: Account.Account | undefined;
-        /** What the key may do. Tempo Auth's pages show it, and the headless ceiling fills what it leaves out. */
-        permissions?: Permissions | undefined;
+        /** What the key may do. Tempo Auth's pages show it, and the user approves it. */
+        permissions: Permissions;
     };
 }

package/dist/actions/redirect.js

@@ -19,7 +19,7 @@ import * as Pending from '../Pending.js';
  * ```ts
  * const authorization =
  *   (await Actions.redirect.complete(auth)) ??
- *   (await Actions.authorize(auth))
+ *   (await Actions.authorize(auth, { permissions }))
  * ```
  */
 export function complete(auth, options = {}) {
@@ -53,13 +53,14 @@ export function complete(auth, options = {}) {
  * @example
  * ```ts
  * const { pending, url } = await Actions.redirect.createUrl(auth, {
+ *   permissions,
  *   redirectUri: 'https://app.example/auth/callback',
  * })
  * await seal(c, 'oauth', pending)
  * return c.redirect(url)
  * ```
  */
-export async function createUrl(auth, options = {}) {
+export async function createUrl(auth, options) {
     const redirectUri = options.redirectUri ?? auth.redirectUri ?? `${window.location.origin}/`;
     const key = await AccessKey.resolve(options.accessKey);
     const pending = Pending.from({
@@ -128,10 +129,10 @@ export async function handleCallback(auth, options) {
  *
  * @example
  * ```ts
- * await Actions.redirect.start(auth)
+ * await Actions.redirect.start(auth, { permissions })
  * ```
  */
-export async function start(auth, options = {}) {
+export async function start(auth, options) {
     const { pending, url } = await createUrl(auth, options);
     await storage(auth).setItem(storageKey, pending);
     window.location.assign(url);

package/dist/internal/api.js

@@ -29,12 +29,9 @@ export function authorization(body, options) {
 export async function json(response) {
     // Some refusals, such as the CSRF check's, answer plain text.
     const body = (await response.json().catch(() => ({})));
-    // OAuth-style refusals, such as the device grant's, put the explanation beside a code.
     if (!response.ok)
         throw new RequestError({
-            message: body.error_description ??
-                body.error ??
-                `Request failed with status ${response.status}.`,
+            message: body.error ?? 'Something went wrong.',
             status: response.status,
         });
     return body;

package/dist/internal/request.d.ts

@@ -7,14 +7,14 @@ import type { Permissions } from '../Permissions.ts';
  */
 export declare function request(auth: Auth, options: {
     accessKey: Account.Account;
-    permissions?: Permissions | undefined;
+    permissions: Permissions;
 }): {
     client_id: string;
     keyAuthorization: {
         account?: `0x${string}`;
         address: `0x${string}`;
         chainId: `0x${string}`;
-        expiry: number | undefined;
+        expiry: number;
         keyType: "p256" | "secp256k1" | "webAuthn";
         limits: {
             limit: `0x${string}`;

package/dist/internal/request.js

@@ -9,7 +9,7 @@ import { Hex } from 'ox';
  * key account names its Tempo Account through `access`, and a plain key leaves it to Tempo Auth.
  */
 export function request(auth, options) {
-    const { accessKey, permissions = {} } = options;
+    const { accessKey, permissions } = options;
     return {
         client_id: auth.clientId,
         keyAuthorization: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempoxyz/auth",
-  "version": "0.0.0-pr-28.sha-72f7afa",
+  "version": "0.0.0-pr-31.sha-03ddfa6",
   "description": "Signs users in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
   "type": "module",
   "exports": {