@tempoxyz/auth 0.0.0-pr-34.sha-cbbdadc → 0.0.0-pr-36.sha-2b0babd

package/README.md

@@ -6,8 +6,12 @@ Every sign-in returns the same `Authorization`. Send transactions with its `acco
 
 ```ts
 import { Actions, Auth } from '@tempoxyz/auth'
-import { Addresses, createClient, Expiry, Scopes } from 'viem/tempo'
-import { tempoTestnet } from 'viem/tempo/chains'
+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
 
 const auth = Auth.create({
   chainId: tempoTestnet.id,
@@ -16,14 +20,14 @@ const auth = Auth.create({
 })
 const client = createClient({
   chain: tempoTestnet,
-  feeToken: Addresses.pathUsd,
+  feeToken: ousd,
 })
 
 const authorization = await Actions.authorize(auth, {
   permissions: {
     expiry: Expiry.days(1),
-    limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
-    scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+    limits: [{ limit: 10_000_000n, token: ousd }],
+    scopes: [Scopes.tip20(ousd).transfer()],
   },
 })
 
@@ -31,7 +35,7 @@ await client.token.transferSync({
   account: authorization!.account,
   amount: 10_000n,
   to: '0x…',
-  token: Addresses.pathUsd,
+  token: ousd,
 })
 ```
 
@@ -50,14 +54,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 `permissions` option says what the key may do, with viem's `Expiry` and `Scopes` helpers:
+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:
 
-| 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()]`        |
+| 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 |
 
 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.
 
@@ -65,10 +69,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, permissions })
+await Actions.authorize(auth, { accessKey })
 ```
 
-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.
+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.
 
 The returned `account` attaches the key's authorization to its first transaction, which registers the key on chain.
 
@@ -80,11 +84,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, { permissions })
+const authorization = await Actions.authorize(auth)
 
 // Otherwise, sign in with an emailed code.
 await Actions.email.sendCode(auth, { email })
-const result = await Actions.email.signIn(auth, { code, email, permissions })
+const result = await Actions.email.signIn(auth, { code, email })
 
 // 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 })
@@ -102,7 +106,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, { permissions })
+await Actions.redirect.start(auth)
 
 // On the page the browser returns to, and on every load:
 const authorization = await Actions.redirect.complete(auth)
@@ -125,12 +129,10 @@ 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, permissions })
+const result = await Actions.email.signIn(auth, { code, email })
 
 // Or Tempo Auth's pages, which also offer Google and SSO.
-const { pending, url } = await Actions.redirect.createUrl(auth, {
-  permissions,
-})
+const { pending, url } = await Actions.redirect.createUrl(auth)
 const session = await WebBrowser.openAuthSessionAsync(url, auth.redirectUri)
 if (session.type === 'success')
   authorization = await Actions.redirect.handleCallback(auth, {
@@ -150,7 +152,6 @@ 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`.
@@ -169,7 +170,6 @@ 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,7 +189,6 @@ await Actions.authorize(auth, {
   accessKey: Account.fromWebCryptoP256(keyPair, {
     access: tempoAccount.address,
   }),
-  permissions,
 })
 ```
 
@@ -216,14 +215,14 @@ Refresh tokens rotate, so save the new tokens over the old ones after each refre
 
 ## Errors
 
-A request Tempo Auth refuses throws `Auth.RequestError`, with its `status` and `message`.
+A request Tempo Auth refuses throws `Auth.RequestError`. It carries the OAuth error code as `code`, and `message` says what went wrong and how to fix it. `reason`, `field`, and `meta` let an app branch on the refusal and read the values it compared. [Errors](../../docs/errors.md) lists every `reason`.
 
 ```ts
 try {
-  await Actions.email.signIn(auth, { code, email, permissions })
+  await Actions.authorize(auth, { permissions })
 } catch (error) {
-  if (error instanceof Auth.RequestError && error.status === 401)
-    showWrongCode()
+  if (error instanceof Auth.RequestError && error.reason === 'limit_exceeds_maximum')
+    showMaximum(error.meta?.maximum) // in base units
 }
 ```
 
@@ -244,22 +243,22 @@ try {
 
 ### `Actions`
 
-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`.
+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`.
 
 | Action                                                   | Returns                                                                    |
 | -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `authorize(auth, { permissions })`                       | An `Authorization` for a user already signed in, or `undefined`            |
+| `authorize(auth)`                                        | 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, permissions })`        | The code to show and a `wait()` that resolves with an `Authorization`      |
+| `device.authorize(auth, { 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, { code, email, permissions })`       | An `Authorization`, or the `step` the address requires first               |
+| `email.signIn(auth, { 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, { accessKey })`                 | The `Authorization` when the page is a redirect's callback, or `undefined` |
-| `redirect.createUrl(auth, { permissions, redirectUri })` | The `url` to send the browser to, and the `pending` state to keep          |
+| `redirect.createUrl(auth, { 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, { permissions })`                  | Nothing. The browser leaves for Tempo Auth's pages                         |
+| `redirect.start(auth)`                                   | 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, { permissions })
+ * const authorization = await Actions.authorize(auth)
  * 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. */
-        permissions: Permissions;
+        /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
+        permissions?: Permissions | undefined;
     };
     /** 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, { permissions })
+ * const authorization = await Actions.authorize(auth)
  * 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.d.ts

@@ -24,12 +24,32 @@ export type Auth = {
 /** A request Tempo Auth refused, with its status and message. */
 export declare class RequestError extends Error {
     readonly name = "Auth.RequestError";
+    /** The OAuth error code, such as `invalid_authorization_details`. */
+    readonly code: string;
+    /** The request field at fault, as a dotted path. */
+    readonly field: string | undefined;
+    /** The values the refusal compared, such as `limit` and `maximum`. Base units are decimal strings. */
+    readonly meta: Readonly<Record<string, number | string>> | undefined;
+    /** A stable name for the refusal, to branch on. */
+    readonly reason: RequestError.Reason | undefined;
     /** The HTTP status Tempo Auth answered. */
     readonly status: number;
-    constructor(options: {
+    /** The page that explains the error. */
+    readonly uri: string | undefined;
+    constructor(options: RequestError.Options);
+}
+export declare namespace RequestError {
+    type Options = {
+        code: string;
+        field?: string | undefined;
         message: string;
+        meta?: Readonly<Record<string, number | string>> | undefined;
+        reason?: Reason | undefined;
         status: number;
-    });
+        uri?: string | undefined;
+    };
+    /** Each refusal's stable name. `docs/errors.md` explains each one. */
+    type Reason = 'already_decided' | 'approval_pending' | 'cross_site_request' | 'device_code_expired' | 'duplicate_limit' | 'empty_limits' | 'empty_scopes' | 'expiry_exceeds_maximum' | 'expiry_passed' | 'foreign_account' | 'foreign_origin' | 'invalid_chain' | 'invalid_code' | 'invalid_expiry' | 'invalid_field' | 'invalid_origin' | 'invalid_public_key' | 'limit_exceeds_maximum' | 'malformed_body' | 'missing_code_challenge' | 'missing_key' | 'missing_recipients' | 'periodic_limit' | 'polling_too_fast' | 'rejected' | 'request_denied' | 'scope_without_limit' | 'session_required' | 'unexpected' | 'unknown_code' | 'unknown_endpoint' | 'unsupported_call' | 'unsupported_step' | 'unsupported_token';
 }
 /**
  * Creates a Tempo Auth instance.

package/dist/Auth.js

@@ -6,8 +6,11 @@
  * @example
  * ```ts
  * import { Actions, Auth } from '@tempoxyz/auth'
- * import { Addresses, Expiry, Scopes } from 'viem/tempo'
- * import { tempoTestnet } from 'viem/tempo/chains'
+ * 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
  *
  * const auth = Auth.create({
  *   chainId: tempoTestnet.id,
@@ -18,8 +21,8 @@
  * const authorization = await Actions.authorize(auth, {
  *   permissions: {
  *     expiry: Expiry.days(1),
- *     limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
- *     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+ *     limits: [{ limit: 10_000_000n, token: ousd }],
+ *     scopes: [Scopes.tip20(ousd).transfer()],
  *   },
  * })
  * ```
@@ -29,11 +32,26 @@ import { tempo } from 'viem/tempo/chains';
 /** A request Tempo Auth refused, with its status and message. */
 export class RequestError extends Error {
     name = 'Auth.RequestError';
+    /** The OAuth error code, such as `invalid_authorization_details`. */
+    code;
+    /** The request field at fault, as a dotted path. */
+    field;
+    /** The values the refusal compared, such as `limit` and `maximum`. Base units are decimal strings. */
+    meta;
+    /** A stable name for the refusal, to branch on. */
+    reason;
     /** The HTTP status Tempo Auth answered. */
     status;
+    /** The page that explains the error. */
+    uri;
     constructor(options) {
         super(options.message);
+        this.code = options.code;
+        this.field = options.field;
+        this.meta = options.meta;
+        this.reason = options.reason;
         this.status = options.status;
+        this.uri = options.uri;
     }
 }
 /**

package/dist/Permissions.d.ts

@@ -3,12 +3,19 @@
  * @module
  */
 import type { KeyAuthorization } from 'ox/tempo';
-/** What an app's access key may do, as viem's `accessKey.authorize` takes it. */
-export type Permissions = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scopes'> & {
+/**
+ * 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 = {
     /** 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)`. */
-    expiry: number;
+    /** 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'];
 };
 /**
  * Instantiates a {@link Permissions}.
@@ -17,8 +24,8 @@ export type Permissions = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'sc
  * ```ts
  * const permissions = Permissions.from({
  *   expiry: Expiry.days(1),
- *   limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
- *   scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+ *   limits: [{ limit: 10_000_000n, token: ousd }],
+ *   scopes: [Scopes.tip20(ousd).transfer()],
  * })
  * ```
  */

package/dist/Permissions.js

@@ -5,8 +5,8 @@
  * ```ts
  * const permissions = Permissions.from({
  *   expiry: Expiry.days(1),
- *   limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
- *   scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+ *   limits: [{ limit: 10_000_000n, token: ousd }],
+ *   scopes: [Scopes.tip20(ousd).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(), permissions })
+ * const device = await Actions.device.authorize(auth, { device: Os.hostname() })
  * 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. */
-        permissions: Permissions;
+        /** 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;
     };
     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(), permissions })
+ * const device = await Actions.device.authorize(auth, { device: Os.hostname() })
  * console.log(`Open ${device.verificationUriComplete}`)
  * const authorization = await device.wait()
  * ```
@@ -44,12 +44,13 @@ export async function authorize(auth, options) {
             if (body.error === 'slow_down')
                 interval += 5;
             else if (body.error !== 'authorization_pending')
-                throw new RequestError({
-                    message: `Sign-in failed: ${body.error}.`,
-                    status: response.status,
-                });
+                throw Api.error(body, { status: response.status });
         }
-        throw new RequestError({ message: 'The code expired.', status: 400 });
+        throw new RequestError({
+            code: 'expired_token',
+            message: 'Device code expired. Request a new code.',
+            status: 400,
+        });
     }
     return {
         expiresIn: code.expires_in,

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, permissions })
+ * const result = await Actions.email.signIn(auth, { code, email })
  * 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. */
-        permissions: Permissions;
+        /** What the key may do. It must fit the headless ceiling, which fills what it leaves out. */
+        permissions?: Permissions | undefined;
     };
     /** 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, permissions })
+ * const result = await Actions.email.signIn(auth, { code, email })
  * 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, { permissions }))
+ *   (await Actions.authorize(auth))
  * ```
  */
 export declare function complete(auth: Auth, options?: complete.Options): Promise<complete.ReturnType>;
@@ -31,14 +31,13 @@ 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 = {
         /**
@@ -46,8 +45,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 user approves it. */
-        permissions: Permissions;
+        /** What the key may do. Tempo Auth's pages show it, and the headless ceiling fills what it leaves out. */
+        permissions?: Permissions | undefined;
         /** Where Tempo Auth redirects back to. Defaults to the instance's `redirectUri`. */
         redirectUri?: string | undefined;
     };
@@ -87,10 +86,10 @@ export declare namespace handleCallback {
  *
  * @example
  * ```ts
- * await Actions.redirect.start(auth, { permissions })
+ * await Actions.redirect.start(auth)
  * ```
  */
-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 = {
         /**
@@ -98,7 +97,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 user approves it. */
-        permissions: Permissions;
+        /** What the key may do. Tempo Auth's pages show it, and the headless ceiling fills what it leaves out. */
+        permissions?: Permissions | undefined;
     };
 }

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, { permissions }))
+ *   (await Actions.authorize(auth))
  * ```
  */
 export function complete(auth, options = {}) {
@@ -53,14 +53,13 @@ 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({
@@ -101,9 +100,19 @@ export async function handleCallback(auth, options) {
     const { redirectUri, state, verifier, ...material } = options.pending;
     const params = new URL(options.url).searchParams;
     const code = params.get('code');
-    if (!code || params.get('state') !== state)
+    if (!code)
         throw new RequestError({
-            message: 'Sign-in failed. Start again.',
+            code: params.get('error') ?? 'invalid_request',
+            field: 'code',
+            message: params.get('error_description') ??
+                'Missing `code` in the callback URL. Start sign-in again.',
+            status: 400,
+        });
+    if (params.get('state') !== state)
+        throw new RequestError({
+            code: 'invalid_request',
+            field: 'state',
+            message: 'Invalid `state` in the callback URL. Start sign-in again from this app.',
             status: 400,
         });
     const body = await Api.token(auth, {
@@ -114,7 +123,8 @@ export async function handleCallback(auth, options) {
     });
     if (!body.account || !body.key_authorization)
         throw new RequestError({
-            message: 'Sign-in failed. Start again.',
+            code: 'invalid_grant',
+            message: 'Missing key authorization in the token response. The code was already redeemed, or did not request a key. Start sign-in again.',
             status: 400,
         });
     return Api.authorization({
@@ -129,10 +139,10 @@ export async function handleCallback(auth, options) {
  *
  * @example
  * ```ts
- * await Actions.redirect.start(auth, { permissions })
+ * await Actions.redirect.start(auth)
  * ```
  */
-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.d.ts

@@ -1,6 +1,6 @@
 import type { KeyAuthorization } from 'ox/tempo';
 import type { Account } from 'viem/tempo';
-import { type Auth } from '../Auth.ts';
+import { type Auth, RequestError } from '../Auth.ts';
 import type { Authorization } from '../Authorization.ts';
 import * as Key from '../Key.ts';
 import type { Tokens } from '../Tokens.ts';
@@ -20,6 +20,19 @@ export type Headless = {
 };
 /** Reads a JSON response, and throws a {@link RequestError} for a refused request. */
 export declare function json<value = unknown>(response: Response): Promise<value>;
+/** An OAuth error response, with Tempo Auth's extension members. */
+export type ErrorBody = {
+    error: string;
+    error_description?: string | undefined;
+    error_uri?: string | undefined;
+    field?: string | undefined;
+    meta?: Readonly<Record<string, number | string>> | undefined;
+    reason?: RequestError.Reason | undefined;
+};
+/** A {@link RequestError} from an OAuth error response, or from a refusal with no body. */
+export declare function error(body: Partial<ErrorBody>, options: {
+    status: number;
+}): RequestError;
 /** Posts JSON to Tempo Auth's API with the session cookie. */
 export declare function post(auth: Auth, path: string, options: {
     json?: unknown;

package/dist/internal/api.js

@@ -30,12 +30,23 @@ export async function json(response) {
     // Some refusals, such as the CSRF check's, answer plain text.
     const body = (await response.json().catch(() => ({})));
     if (!response.ok)
-        throw new RequestError({
-            message: body.error ?? 'Something went wrong.',
-            status: response.status,
-        });
+        throw error(body, { status: response.status });
     return body;
 }
+/** A {@link RequestError} from an OAuth error response, or from a refusal with no body. */
+export function error(body, options) {
+    return new RequestError({
+        code: body.error ?? 'server_error',
+        field: body.field,
+        message: body.error_description ??
+            body.error ??
+            `Request failed with status ${options.status}.`,
+        meta: body.meta,
+        reason: body.reason,
+        status: options.status,
+        uri: body.error_uri,
+    });
+}
 /** Posts JSON to Tempo Auth's API with the session cookie. */
 export function post(auth, path, options) {
     return (auth.fetch ?? fetch)(new URL(path, auth.url), {

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;
+    permissions?: Permissions | undefined;
 }): {
     client_id: string;
     keyAuthorization: {
         account?: `0x${string}`;
         address: `0x${string}`;
         chainId: `0x${string}`;
-        expiry: number;
+        expiry: number | undefined;
         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-34.sha-cbbdadc",
+  "version": "0.0.0-pr-36.sha-2b0babd",
   "description": "Signs users in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
   "type": "module",
   "exports": {