@tempoxyz/id 0.0.1 → 0.0.2

package/src/api/oauth.ts

@@ -75,7 +75,7 @@ namespace schema {
         .optional()
         .meta({
           description:
-            "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+            "A message, such as a sign-in challenge, that the key authorization's `witness` binds (TIP-1053). Requires `key_authorization` and the `tempo-id:sign` scope.",
           examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
         }),
       client_id: z.string().meta({
@@ -95,7 +95,7 @@ namespace schema {
         .optional()
         .meta({
           description:
-            "A key authorization for the app's own key, as base64url JSON in the shape of `KeyAuthorizationRequest`. The approval page shows the key, and `/oauth2/token` returns it beside the tokens once approval signs it. A key that breaks a rule returns to the redirect URI with the refusal.",
+            "A `KeyAuthorizationRequest` for the app's own key, as base64url JSON. After approval, `/oauth2/token` returns the signed key with the tokens.",
           examples: [
             'eyJhZGRyZXNzIjoiMHg4MWMwZjIyYmQxNzNjMTE1ZDE4ZWVlYTBmNmEzOGU5MzVlY2Y1MmZiIn0',
           ],
@@ -145,7 +145,7 @@ namespace schema {
         }),
         url: z.string().meta({
           description:
-            'Where the browser goes next: the sign-in page, the consent page, or the redirect URI with a code.',
+            'The URL to send the browser to next: the sign-in page, the approval page, or the redirect URI with a code.',
           examples: [
             'https://app.example/callback?code=SplxlOBeZQQYbYS6WxSbIA',
           ],
@@ -310,7 +310,7 @@ namespace schema {
           }),
         key_authorization: KeyAuthorization.schema.rpc.optional().meta({
           description:
-            'The key authorization that the approval page or the device page signed, for the first redemption of a code or device code whose request carried `key_authorization`. Absent for every other code, a refresh, and a key that expired.',
+            'The signed key authorization, on the first redemption of a code whose request carried `key_authorization`. Absent otherwise.',
         }),
         refresh_token: z
           .string()
@@ -404,7 +404,7 @@ namespace schema {
         }),
       key_authorization: authorize.query.shape.key_authorization.meta({
         description:
-          "A key authorization for the app's own key, as base64url JSON in the shape of `KeyAuthorizationRequest`, from a public first-party app only. The device page shows it, approval signs it, and `/oauth2/token` returns it beside the tokens.",
+          "A `KeyAuthorizationRequest` for the app's own key, as base64url JSON, from a public first-party app only. After approval, `/oauth2/token` returns the signed key with the tokens.",
         examples: [
           'eyJhZGRyZXNzIjoiMHg4MWMwZjIyYmQxNzNjMTE1ZDE4ZWVlYTBmNmEzOGU5MzVlY2Y1MmZiIn0',
         ],
@@ -585,7 +585,7 @@ namespace schema {
         .optional()
         .meta({
           description:
-            'The sealed parameters of a form POST that carried no session cookie, which its 303 sends here. Absent otherwise.',
+            'The sealed parameters of a form POST that had no session cookie, from its 303 redirect.',
           examples: ['a3f1c2…'],
         }),
       id_token_hint: z
@@ -593,7 +593,7 @@ namespace schema {
         .optional()
         .meta({
           description:
-            'An ID token that Tempo ID issued to the app, even an expired one, which names the session to end. Required without `continuation`.',
+            'An ID token that Tempo ID issued to the app, which names the session to end. It may be expired, and is required without `continuation`.',
           examples: ['eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e30.c2lnbmF0dXJl'],
         }),
       post_logout_redirect_uri: z
@@ -617,8 +617,7 @@ namespace schema {
 
     export const response = z.object({
       signed_out: z.literal(true).meta({
-        description:
-          'The browser holds no session that the hint names, since it ended or never held one.',
+        description: 'The browser has no session that the hint names.',
       }),
     })
   }
@@ -703,7 +702,7 @@ const introspectRoute = {
 /** The description and responses of `GET` and `POST /oauth2/end-session` in the OpenAPI document. */
 const endSessionRoute = {
   description:
-    "Signs the browser out of the session that the app's ID token names, if the browser holds it, and revokes the tokens that apps received through it (OpenID Connect RP-Initiated Logout). Any other session stays signed in, and Tempo ID redirects the browser to the app's post-logout redirect URI.",
+    "Signs the browser out of the session that `id_token_hint` names, revokes its tokens, and redirects to the app's post-logout redirect URI (OpenID Connect RP-Initiated Logout).",
   responses: {
     302: {
       description:
@@ -713,7 +712,7 @@ const endSessionRoute = {
       errors: [...OpenApi.validate.errors, ...Logout.check.errors],
       success: {
         description:
-          'The browser is signed out of the session that the hint names, for a request without `post_logout_redirect_uri`.',
+          'The browser is signed out, for a request without `post_logout_redirect_uri`.',
         schema: schema.endSession.response,
       },
     }),
@@ -824,7 +823,7 @@ export const oauth = new Hono<Env>()
   .get(
     '/.well-known/openid-configuration',
     OpenApi.describeRoute({
-      description: "Reads the issuer's OpenID Connect discovery document.",
+      description: "Returns the issuer's OpenID Connect discovery document.",
       responses: OpenApi.responses({
         success: {
           description: 'The discovery document.',
@@ -838,7 +837,8 @@ export const oauth = new Hono<Env>()
   .get(
     '/.well-known/oauth-authorization-server',
     OpenApi.describeRoute({
-      description: "Reads the issuer's authorization server metadata.",
+      description:
+        "Returns the issuer's authorization server metadata (RFC 8414).",
       responses: OpenApi.responses({
         success: {
           description: 'The metadata.',
@@ -853,7 +853,7 @@ export const oauth = new Hono<Env>()
     '/oauth2/authorize',
     OpenApi.describeRoute({
       description:
-        'Starts an authorization. A signed-out browser receives the sign-in page, and a signed-in one the consent page or a redirect to the redirect URI with a code.',
+        'Redirect authorization, step 1 of 2: starts the authorization in the browser. Tempo ID shows the sign-in, account, and approval pages as needed, then redirects to `redirect_uri` with a code.',
       responses: {
         200: {
           content: {
@@ -863,7 +863,7 @@ export const oauth = new Hono<Env>()
             'text/html': { schema: { type: 'string' } },
           },
           description:
-            "The next step as JSON, for a request from a script. A browser navigation receives Tempo ID's page of the next step, such as the sign-in page or the error page.",
+            'The next step as JSON, for a request from a script. A browser navigation receives the page of the next step.',
         },
         302: {
           description:
@@ -904,7 +904,7 @@ export const oauth = new Hono<Env>()
     '/oauth2/token',
     OpenApi.describeRoute({
       description:
-        'Redeems an authorization code, a refresh token, a device code, or client credentials for tokens.',
+        'Exchanges an authorization code, refresh token, device code, or client credentials for tokens. It is the last step of the redirect authorization and of the device grant.',
       responses: {
         200: {
           content: {
@@ -995,7 +995,7 @@ export const oauth = new Hono<Env>()
     '/device/code',
     OpenApi.describeRoute({
       description:
-        'Starts the device grant (RFC 8628 §3.1). The user approves the user code on the device page, and the device then redeems the device code at `/oauth2/token`.',
+        'Device grant, step 1 of 4: returns a device code and a user code (RFC 8628). The user enters the user code on the device page, and the device polls `/oauth2/token`.',
       responses: {
         200: {
           content: {
@@ -1125,7 +1125,7 @@ export const oauth = new Hono<Env>()
     '/oauth2/introspect',
     OpenApi.describeRoute({
       description:
-        'Introspects a token (RFC 7662). The app authenticates with its client credentials, in the body or as HTTP Basic `Authorization`.',
+        'Returns whether a token is active, and its claims (RFC 7662). The app authenticates with its client credentials.',
       ...introspectRoute,
     }),
     OpenApi.input('form', schema.introspect.form),
@@ -1135,7 +1135,7 @@ export const oauth = new Hono<Env>()
     '/oauth2/revoke',
     OpenApi.describeRoute({
       description:
-        'Revokes an access or refresh token (RFC 7009). The app authenticates with its client credentials, in the body or as HTTP Basic `Authorization`.',
+        'Revokes an access or refresh token (RFC 7009). The app authenticates with its client credentials.',
       responses: {
         200: {
           content: {
@@ -1160,7 +1160,8 @@ export const oauth = new Hono<Env>()
   .get(
     '/oauth2/userinfo',
     OpenApi.describeRoute({
-      description: "Reads the token subject's claims (OIDC Core §5.3).",
+      description:
+        "Returns the claims of the access token's user (OIDC Core §5.3).",
       responses: {
         200: {
           content: {
@@ -1192,7 +1193,7 @@ export const oauth = new Hono<Env>()
         ...OpenApi.errors(BodyLimit.errors),
         303: {
           description:
-            'Continues a form POST without the session cookie as `GET /oauth2/end-session` with the sealed parameters in `continuation`, which the browser sends with the cookie.',
+            'Redirects a form POST without the session cookie to `GET /oauth2/end-session`, which the browser sends with the cookie.',
         },
       },
     }),
@@ -1203,7 +1204,7 @@ export const oauth = new Hono<Env>()
     '/oauth2/jwks',
     OpenApi.describeRoute({
       description:
-        "Reads the issuer's signing keys. A verifier may cache the response for 60 seconds, since a new key signs 5 minutes after its rotation.",
+        "Returns the issuer's signing keys. A verifier may cache the response for 60 seconds.",
       responses: OpenApi.responses({
         success: {
           description: 'The JSON Web Key Set.',

package/src/client/Auth.ts

@@ -158,6 +158,7 @@ export declare namespace RequestError {
     | 'passkey_limit'
     | 'passkey_link_expired'
     | 'passkey_not_permitted'
+    | 'passkey_register_not_permitted'
     | 'post_logout_redirect_not_permitted'
     | 'rate_limited'
     | 'reauthentication_required'

package/src/client/Decorator.ts

@@ -228,6 +228,7 @@ export function tempoId(options: tempoId.Options) {
                 passkeySignIn(() => prepared.signIn(signInOptions)),
             }
           },
+          register: (options = {}) => Actions.passkey.register(auth, options),
           signIn: (options = {}) =>
             passkeySignIn(() => Actions.passkey.signIn(auth, options)),
         },
@@ -360,7 +361,7 @@ export declare namespace tempoId {
         /** `Actions.oauth.userInfo`. */
         userInfo: (options: Actions.oauth.userInfo.Options) => Promise<User>
       }
-      /** Actions for sign-in with a passkey. */
+      /** Actions for sign-in with a passkey, and the registration of one. */
       passkey: {
         /** `Actions.passkey.available`. */
         available: () => Promise<boolean>
@@ -374,6 +375,10 @@ export declare namespace tempoId {
         >(
           options?: Actions.passkey.prepare.Options<id, key>,
         ) => Actions.passkey.prepare.ReturnType<id, key>
+        /** `Actions.passkey.register`, which leaves the client's account unchanged. */
+        register: (
+          options?: Actions.passkey.register.Options,
+        ) => Promise<Actions.passkey.register.ReturnType>
         /**
          * `Actions.passkey.signIn`, which sets the client's account as `auth.email.signIn` does,
          * unless it returns a step.

package/src/client/actions/passkey.ts

@@ -1,13 +1,20 @@
 /**
  * Signs the user in with a passkey from the app's own sign-in form, and authorizes the app's key.
  * The handle of {@link prepare} requests the sign-in's options before the user acts, so its sign-in
- * starts the ceremony without a request.
+ * starts the ceremony without a request. {@link register} adds a passkey for the signed-in user
+ * from the app's page.
  * @module
  */
-import { Authentication, type Types } from 'ox/webauthn'
+import {
+  Authentication,
+  Credential,
+  Registration,
+  type Types,
+} from 'ox/webauthn'
 import type { Account } from 'viem/tempo'
-import { type Auth, ChallengeWithoutKeyError } from '../Auth.js'
+import { type Auth, ChallengeWithoutKeyError, RequestError } from '../Auth.js'
 import type { Authorization } from '../Authorization.js'
+import type * as Key from '../Key.js'
 import type * as AccessKey from '../internal/accessKey.js'
 import * as Api from '../internal/api.js'
 import * as Headless from '../internal/headless.js'
@@ -160,6 +167,143 @@ export declare namespace prepare {
   type SignInOptions = Pick<signIn.Options, 'getFn'>
 }
 
+/**
+ * Registers a new passkey for the signed-in user from a first-party app's page, and returns its
+ * credential ID and the address of the Tempo Account that it owns. The passkey belongs to the
+ * `default` realm's relying party, which must cover the page and Tempo ID. It runs two ceremonies:
+ * the authenticator creates the passkey, then the new passkey signs a proof challenge, so call it
+ * from a click.
+ *
+ * With `key`, the key of a sign-in on a cloud wallet's configurable account, the passkey joins that
+ * account as a second owner on the key's chain, through an update that the cloud wallet signs. The
+ * key keeps working. On a chain whose accounts are not configurable, `key` sets nothing, and the
+ * passkey owns an account of its own. `account` and `chain` name the account and chain instead.
+ *
+ * Requires a sign-in within the last 10 minutes, or throws `reauthentication_required`. A user who
+ * holds 10 passkeys throws `passkey_limit`, and a page that the relying party does not cover throws
+ * `passkey_not_permitted`.
+ *
+ * @example
+ * ```ts
+ * const { authorization } = await Actions.email.signIn(auth, { code, email })
+ * const { address, id } = await Actions.passkey.register(auth, {
+ *   key: authorization.key,
+ * })
+ * ```
+ */
+export async function register(
+  auth: Auth,
+  options: register.Options = {},
+): Promise<register.ReturnType> {
+  const { createFn, getFn, key } = options
+  // The key's chain resolves beside the options request, so it adds no round trip. Only a chain
+  // whose accounts are configurable takes an owner, so on any other the passkey owns its own account.
+  const joined =
+    key && (options.account === undefined || options.chain === undefined)
+      ? configurableChain(auth, { chainId: key.chainId }).then((name) =>
+          name ? { account: key.account, chain: name } : undefined,
+        )
+      : undefined
+  // A registration that fails before the verify request reads no chain, so its failure stays silent.
+  joined?.catch(() => {})
+  const requested = await Api.json<{
+    options: Types.CredentialCreationOptions<true>
+  }>(await Api.post(auth, '/v1/account/passkey/options', { json: {} }))
+  const deserialized = Registration.deserializeOptions(requested.options)
+  const credential = Credential.serialize(
+    await Registration.create(
+      // ox reads `createFn` beside creation options at runtime, which its types admit only beside flat options.
+      createFn ? ({ ...deserialized, createFn } as never) : deserialized,
+    ),
+  )
+
+  const created = {
+    credentialId: credential.id,
+    rpId: requested.options.publicKey!.rp.id!,
+  }
+
+  // The attestation proves no private key, so the new passkey signs a proof challenge before
+  // Tempo ID stores it. A failure before the proof leaves the passkey unstored, so the
+  // authenticator drops it.
+  const assertion = await (async () => {
+    try {
+      const { step } = await Api.json<{
+        step: { options: Types.CredentialRequestOptions<true> }
+      }>(await Api.post(auth, '/v1/account/passkey', { json: { credential } }))
+      const proof = Authentication.deserializeOptions(step.options)
+      return Authentication.serializeResponse(
+        await Authentication.sign(
+          // ox reads `getFn` beside request options at runtime, which its types admit only beside a challenge.
+          getFn ? ({ ...proof, getFn } as never) : proof,
+        ),
+      )
+    } catch (error) {
+      forget(created)
+      throw error
+    }
+  })()
+
+  // A failed chain lookup comes before the verify request, so Tempo ID stored nothing.
+  const target = await joined?.catch((error: unknown) => {
+    forget(created)
+    throw error
+  })
+  const account = options.account ?? target?.account
+  const chain = options.chain ?? target?.chain
+  try {
+    const registered = await Api.json<register.ReturnType>(
+      await Api.post(auth, '/v1/account/passkey/verify', {
+        json: {
+          ...(account ? { account } : {}),
+          assertion,
+          ...(chain ? { chain } : {}),
+        },
+      }),
+    )
+    return { address: registered.address, id: registered.id }
+  } catch (error) {
+    // Any failure but a refusal can follow a stored passkey, so the authenticator keeps it.
+    if (refused(error)) forget(created)
+    throw error
+  }
+}
+
+export declare namespace register {
+  type Options = {
+    /**
+     * A configurable Tempo Account of the user's cloud wallet, which the passkey joins as a second
+     * owner on `chain`. Defaults to `key.account` on a chain whose accounts are configurable, else
+     * none, and the passkey owns an account of its own.
+     */
+    account?: `0x${string}` | undefined
+    /**
+     * The chain whose accounts are configurable, by its name in `GET /v1/chains`, such as
+     * `testnet`. It selects where `account` is, and the chain of the address that the call returns.
+     * Defaults to the chain of `key` when its accounts are configurable, else the first such chain
+     * for `account`, and the passkey's own address otherwise.
+     */
+    chain?: string | undefined
+    /** Runs the creation ceremony in place of `navigator.credentials.create`. */
+    createFn?: Registration.create.Options['createFn'] | undefined
+    /** Runs the proof ceremony in place of `navigator.credentials.get`. */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+    /**
+     * The key of a sign-in on the cloud wallet's account, such as `authorization.key`. On a chain
+     * whose accounts are configurable, it sets the default `account` and `chain`. Registration does
+     * not use the key otherwise.
+     */
+    key?: Pick<Key.Key, 'account' | 'chainId'> | undefined
+  }
+
+  /** The new passkey and the account that it owns. */
+  type ReturnType = {
+    /** The address of the Tempo Account that the passkey owns: `account`, or its own on `chain`. */
+    address: `0x${string}`
+    /** The credential ID of the passkey, base64url. */
+    id: string
+  }
+}
+
 /**
  * Signs the user in with a passkey, and authorizes a first-party app with the same assertion. The
  * key must fit the headless ceiling. A user without a Tempo Account receives one.
@@ -243,6 +387,56 @@ export declare namespace signIn {
       }
 }
 
+/**
+ * Returns the name of the chain with `chainId` in `GET /v1/chains` whose accounts are configurable,
+ * or `undefined` when the deployment flags no such chain.
+ */
+async function configurableChain(auth: Auth, options: { chainId: number }) {
+  const { chains } = await Api.json<{
+    chains: readonly { chainId: number; configurable: boolean; name: string }[]
+  }>(await (auth.fetch ?? fetch)(new URL('/v1/chains', auth.url)))
+  return chains.find(
+    (entry) => entry.chainId === options.chainId && entry.configurable,
+  )?.name
+}
+
+/**
+ * Signals the browser to drop the passkey `credentialId`, which Tempo ID did not store, where the
+ * browser supports the signal. The signal is best effort: a passkey that stays signs in nowhere.
+ */
+function forget(options: { credentialId: string; rpId: string }) {
+  if (typeof PublicKeyCredential === 'undefined') return
+  const signal = (
+    PublicKeyCredential as {
+      signalUnknownCredential?: (options: {
+        credentialId: string
+        rpId: string
+      }) => Promise<void>
+    }
+  ).signalUnknownCredential
+  // The registration's result does not depend on the signal, so its failure is ignored.
+  void signal
+    ?.call(PublicKeyCredential, {
+      credentialId: options.credentialId,
+      rpId: options.rpId,
+    })
+    .catch(() => {})
+}
+
+/**
+ * Returns whether Tempo ID refused a request with a 4xx and a `reason`, so it stored nothing. An
+ * owner change can return `config_conflict` or `rate_limited` after it stores the passkey.
+ */
+function refused(error: unknown) {
+  return (
+    error instanceof RequestError &&
+    error.reason !== undefined &&
+    error.reason !== 'config_conflict' &&
+    error.reason !== 'rate_limited' &&
+    error.status < 500
+  )
+}
+
 /** A passkey sign-in's options and the key that they authorize, which one sign-in uses. */
 type Prepared = {
   /** The authorization request that the options carry, which the passkey step repeats. */

package/src/internal/Apps.ts

@@ -359,7 +359,7 @@ const seeded = new Set<string>()
 
 /** Returns the Better Auth plugins that serve OAuth apps: the JWT plugin and the OAuth provider. */
 export function plugins(options: plugins.Options) {
-  const { accountStep, baseURL, cache, pendingKey } = options
+  const { accounts, accountStep, baseURL, cache, pendingKey } = options
   const fetch = options.metadataFetch ?? fetchMetadata()
   return [
     // `iss` is the configured origin, never the request's host. No client reads the session's JWT
@@ -395,9 +395,22 @@ export function plugins(options: plugins.Options) {
       // Every app may request the one resource.
       enforcePerClientResources: false,
       // A third-party app names its metadata document's URL or its origin as its client ID, and
-      // registers no row.
+      // registers no row. A registered app's access token names the user's accounts in the app's
+      // realms, read again on each grant, so a refresh lists an account that the user created since.
+      // A third-party app receives none, as `GET /v1/account` lists them only to registered apps.
       extensions: [
         {
+          claims: {
+            accessToken: async (input) => ({
+              tempo_accounts:
+                accounts && input.user && !thirdParty(input.client.clientId)
+                  ? await accounts({
+                      clientId: input.client.clientId,
+                      userId: input.user.id,
+                    })
+                  : [],
+            }),
+          },
           clientDiscovery: [discovery({ fetch }), originDiscovery({ fetch })],
         },
       ],
@@ -553,6 +566,17 @@ export function plugins(options: plugins.Options) {
 
 export declare namespace plugins {
   type Options = {
+    /**
+     * Returns every address of the user's Tempo Accounts in the app's realms, which each access
+     * token of a registered app names as `tempo_accounts`. A third-party app's tokens, and every
+     * token without this option, name an empty array.
+     */
+    accounts?:
+      | ((options: {
+          clientId: string
+          userId: string
+        }) => Promise<readonly string[]>)
+      | undefined
     /** Returns whether the app's authorization needs `/choose-account`. Absent, none does. */
     accountStep?:
       | ((options: {

package/src/internal/Auth.ts

@@ -109,6 +109,7 @@ export const sessionCookie = 'tempo-id-session'
 /** Returns the Better Auth options for `options`. */
 export function options(options: options.Options) {
   const {
+    accounts,
     accountStep,
     baseURL,
     cache,
@@ -191,6 +192,7 @@ export function options(options: options.Options) {
       }),
       Passkey.plugin(),
       ...Apps.plugins({
+        accounts,
         accountStep,
         baseURL,
         cache,
@@ -240,6 +242,8 @@ export function options(options: options.Options) {
 
 export declare namespace options {
   type Options = {
+    /** Lists the addresses of the user's accounts that each access token names. */
+    accounts?: Apps.plugins.Options['accounts']
     /** Decides whether an authorization needs the account step. */
     accountStep?: Apps.plugins.Options['accountStep']
     /** Tempo ID's origin, such as `https://id.tempo.xyz`. */

package/src/internal/Authorize.ts

@@ -43,7 +43,7 @@ export namespace schema {
     .object({
       access_token: z.string().meta({
         description:
-          "The access token, a JWT that Tempo ID signs. APIs verify it against Tempo ID's JSON Web Key Set.",
+          "The access token, a JWT that APIs verify against Tempo ID's JSON Web Key Set.",
         examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.c2lnbmF0dXJl'],
       }),
       expires_in: z.number().meta({
@@ -55,7 +55,7 @@ export namespace schema {
         .optional()
         .meta({
           description:
-            'The OIDC ID token, a JWT about the user. Absent when the request did not ask for the `openid` scope.',
+            'The OIDC ID token, a JWT about the user. Absent without the `openid` scope.',
           examples: ['eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJhcHAifQ.c2lnbmF0dXJl'],
         }),
       refresh_token: z
@@ -63,7 +63,7 @@ export namespace schema {
         .optional()
         .meta({
           description:
-            'The refresh token, which the app redeems at `/oauth2/token` for new tokens. Absent without the `offline_access` scope.',
+            'The refresh token, for new tokens at `/oauth2/token`. Absent without the `offline_access` scope.',
           examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
         }),
       token_type: z.string().meta({
@@ -81,7 +81,7 @@ export namespace schema {
     .optional()
     .meta({
       description:
-        "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+        "A message, such as a sign-in challenge, that the key authorization's `witness` binds (TIP-1053). Requires `key_authorization` and the `tempo-id:sign` scope.",
       examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
     })
 
@@ -103,7 +103,7 @@ export namespace schema {
         .optional()
         .meta({
           description:
-            "The S256 PKCE challenge of a verifier that the app's backend holds (RFC 7636). With one, the app receives a code, and without one, a public app receives tokens.",
+            "An S256 PKCE challenge (RFC 7636). With it, the response holds a code for the app's backend, and without it, tokens.",
           examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'],
         }),
       key_authorization: KeyAuthorization.schema.request,
@@ -115,7 +115,7 @@ export namespace schema {
         })
         .meta({
           description:
-            'A registered redirect URI of a web app, whose origin the page calls from.',
+            'A registered redirect URI of the app, on the origin of the page.',
           examples: ['https://app.example.com/callback'],
         }),
       scope: z
@@ -132,7 +132,7 @@ export namespace schema {
         .optional()
         .meta({
           description:
-            "Whether a wallet.tempo passkey's account that waits for its upgrade on the key's chain, where accounts are configurable, signs the key as the passkey's own account, in place of `upgrade_required`. It applies when a passkey signs in the same request, through a sign-in with key signature or `passkey`. The response then holds `upgrade_available`. The key stops working on that chain once the account upgrades, unless `POST /v1/account/upgrade` registers it first. Defaults to `false`.",
+            "Whether to sign the key before a pending upgrade of a wallet.tempo passkey's account, in place of `upgrade_required`. The key then stops working after the upgrade, unless the upgrade registers it.",
           examples: [true],
         }),
       state: z
@@ -141,8 +141,7 @@ export namespace schema {
         .max(256)
         .optional()
         .meta({
-          description:
-            'An opaque value that the response returns unchanged, to bind it to the request (RFC 6749 §4.1.1).',
+          description: 'An opaque value that the response returns unchanged.',
           examples: ['af0ifjsldkj'],
         }),
     })
@@ -193,7 +192,7 @@ export namespace schema {
         .optional()
         .meta({
           description:
-            "The authorization code, when the request sent a `code_challenge`. The app's backend redeems it at `/oauth2/token`.",
+            "The authorization code, if the request sent a `code_challenge`. The app's backend redeems it at `/oauth2/token`.",
           examples: ['Vb7mQ2xLkP9sTzR4'],
         }),
       key_authorization: KeyAuthorization.schema.rpc.optional(),
@@ -201,21 +200,20 @@ export namespace schema {
         .string()
         .optional()
         .meta({
-          description:
-            "The request's `state`, unchanged. Absent when the request sent none.",
+          description: "The request's `state`, unchanged.",
           examples: ['af0ifjsldkj'],
         }),
       tokens: tokens.optional().meta({
-        description: 'The tokens, when the request sent no `code_challenge`.',
+        description: 'The tokens, if the request sent no `code_challenge`.',
       }),
       upgrade_available: z.literal(true).optional().meta({
         description:
-          "Present when `skip_upgrade` signed the key as a wallet.tempo passkey's own account, whose upgrade waits on the key's chain. `POST /v1/account/upgrade` with the key registers it and upgrades the account.",
+          'Present if `skip_upgrade` signed the key before a pending upgrade. Send the key to `POST /v1/account/upgrade` to keep it working after the upgrade.',
       }),
     })
     .meta({
       description:
-        'An authorization: a code or tokens, with the signed key authorization when the request asks for one.',
+        'An authorization: a code or tokens, with any signed key authorization.',
       id: 'Authorization',
     })
 }

package/src/internal/ErrorResponse.ts

@@ -183,6 +183,12 @@ export const reasons = {
     error: 'unauthorized_client',
     status: 403,
   },
+  passkey_register_not_permitted: {
+    description:
+      "A passkey registration comes from an app's page, and no app at the page's origin holds the `tempo-id:sign` scope.",
+    error: 'unauthorized_client',
+    status: 403,
+  },
   not_configurable: {
     description:
       'The account is not configurable on the chain, so no owner can join it, or no passkey owns it, so it cannot upgrade.',
@@ -638,6 +644,10 @@ export namespace schema {
       error_description:
         'Passkey not permitted: the app client_01JZ8Q6W3N1R5B4V7C2X9K0M3T holds no passkeys. Sign in with an emailed code.',
     },
+    passkey_register_not_permitted: {
+      error_description:
+        'Passkey registration not permitted: no app at https://app.example.com holds the `tempo-id:sign` scope. Register the passkey on Tempo ID, or grant the app the scope.',
+    },
     not_configurable: {
       error_description:
         'Not configurable: 0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c is not a configurable account yet. Upgrade it with its passkey, then add the owner.',