@tempoxyz/id 0.0.1 → 0.0.2

package/src/api/account.ts

@@ -52,7 +52,7 @@ namespace schema {
     export const query = z.object({
       chain: Chain.schema.optional().meta({
         description:
-          'The chain whose balance each account carries: `mainnet`, `testnet`, or another chain that the deployment lists. Without it, the accounts carry no balance.',
+          "The chain to read each account's balance on, such as `mainnet` or `testnet`. Without it, the response carries no balances.",
         examples: ['testnet'],
       }),
       client_id: z
@@ -62,7 +62,7 @@ namespace schema {
         .optional()
         .meta({
           description:
-            "The app's client ID, whose realms select the accounts. A browser page from an origin that none of the app's redirect URIs has receives the `default` realm, as does a request without one.",
+            "The app whose realms select the accounts. Without it, or from a page outside the app's redirect URI origins, the `default` realm.",
           examples: ['client_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
         }),
     })
@@ -75,20 +75,19 @@ namespace schema {
         }),
         id: z.string().meta({
           description:
-            "The user's ID, which is the `sub` of every token Tempo ID issues for the user.",
+            "The user's ID, which is the `sub` claim of the user's tokens.",
           examples: ['user_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
         }),
         name: z
           .string()
           .nullable()
           .meta({
-            description:
-              "The user's name, or `null` for a user who signed up without one.",
+            description: "The user's name, or `null` if the user has none.",
             examples: ['Ada Lovelace'],
           }),
         passkeys: z.boolean().meta({
           description:
-            "Whether the realms the request reaches hold passkeys that sign in at Tempo ID's origin. Without `client_id`, the `default` realm's, where `POST /v1/account/passkey/options` registers a passkey.",
+            'Whether the realms of the request accept passkeys that sign in on Tempo ID.',
           examples: [true],
         }),
         tempo: z
@@ -96,14 +95,14 @@ namespace schema {
             TempoAccount.schema.tempoAccount.extend({
               balance: Balance.schema.balance.nullable().optional().meta({
                 description:
-                  "The USD value of the account's verified holdings on the chain that `chain` names, or absent without `chain`. `null` when the chain has no Tempo API URL, or the read fails or takes longer than 3 seconds.",
+                  "The USD value of the account's verified tokens on `chain`. Absent without `chain`, and `null` if the balance cannot be read.",
               }),
             }),
           )
           .readonly()
           .meta({
             description:
-              "The user's Tempo Accounts in the realms the request reaches: the account that the user selected for the app first, then oldest first.",
+              "The user's Tempo Accounts: the account that the user selected for the app first, then oldest first.",
           }),
       })
       .meta({ id: 'Account' })
@@ -125,30 +124,29 @@ namespace schema {
           publicKey: z
             .object({
               attestation: z.literal('none').meta({
-                description:
-                  'Tempo ID requests no attestation statement from the authenticator.',
+                description: 'Requests no attestation from the authenticator.',
               }),
               authenticatorSelection: z
                 .object({
                   requireResidentKey: z.literal(true).meta({
                     description:
-                      'The passkey must be discoverable, so it signs in without an email.',
+                      'Requires a discoverable passkey, which signs in without an email.',
                   }),
                   residentKey: z.literal('required').meta({
                     description:
-                      'The passkey must be discoverable, so it signs in without an email.',
+                      'Requires a discoverable passkey, which signs in without an email.',
                   }),
                   userVerification: z.literal('required').meta({
                     description:
-                      'Every passkey registration requires user verification.',
+                      'Requires user verification, such as a biometric or PIN.',
                   }),
                 })
                 .meta({
-                  description: 'The authenticator that the passkey requires.',
+                  description: 'The requirements for the authenticator.',
                 }),
               challenge: z.templateLiteral(['0x', z.string()]).meta({
                 description:
-                  'The single-use challenge, as hex. It expires after 5 minutes, and only the same user spends it.',
+                  'The single-use challenge, as hex, which expires after 5 minutes.',
                 examples: [
                   '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
                 ],
@@ -166,13 +164,13 @@ namespace schema {
                       }),
                     })
                     .meta({
-                      description: 'A passkey that the user holds already.',
+                      description: 'A passkey that the user already has.',
                     }),
                 )
                 .optional()
                 .meta({
                   description:
-                    "The user's passkeys of the relying party, which an authenticator that holds one of them refuses to replace. Absent for a user with none.",
+                    "The user's existing passkeys, which the authenticator does not register again. Absent if the user has none.",
                 }),
               pubKeyCredParams: z
                 .array(
@@ -187,12 +185,11 @@ namespace schema {
                     })
                     .meta({
                       description:
-                        'The only key type that a Tempo Account accepts.',
+                        'A P-256 key, the only key type that a Tempo Account accepts.',
                     }),
                 )
                 .meta({
-                  description:
-                    'The key types the passkey may use: P-256 alone, which a Tempo Account verifies.',
+                  description: 'The key types that the passkey can use.',
                 }),
               rp: z
                 .object({
@@ -201,21 +198,21 @@ namespace schema {
                     examples: ['tempo.xyz'],
                   }),
                   name: z.string().meta({
-                    description: "The `default` realm's display name.",
+                    description: 'The display name of the `default` realm.',
                     examples: ['Tempo'],
                   }),
                 })
-                .meta({ description: 'The relying party.' }),
+                .meta({ description: 'The relying party of the passkey.' }),
               user: z
                 .object({
                   displayName: z.string().meta({
                     description:
-                      "The user's name, or the email address for a user without one.",
+                      "The user's name, or the email address if the user has none.",
                     examples: ['Ada Lovelace'],
                   }),
                   id: z.string().meta({
                     description:
-                      'A random user handle for this passkey, base64url, so a new passkey never replaces another in the authenticator.',
+                      'A random user handle, base64url. A new handle for each passkey stops the authenticator from replacing another passkey.',
                     examples: ['3q2-7wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'],
                   }),
                   name: z.email().meta({
@@ -225,16 +222,16 @@ namespace schema {
                 })
                 .meta({
                   description:
-                    'The user, as the authenticator labels the passkey.',
+                    'The user that the authenticator shows with the passkey.',
                 }),
             })
             .meta({
               description:
-                'The `PublicKeyCredentialCreationOptions`, serialized with the challenge as hex.',
+                'The `PublicKeyCredentialCreationOptions`, with the challenge as hex.',
             }),
         })
         .meta({
-          description: 'The options for `navigator.credentials.create()`.',
+          description: 'The argument for `navigator.credentials.create()`.',
         }),
     })
   }
@@ -268,11 +265,11 @@ namespace schema {
                     )
                     .meta({
                       description:
-                        'The new passkey, the only one the browser offers.',
+                        'The new passkey, which is the only passkey that the browser offers.',
                     }),
                   challenge: z.templateLiteral(['0x', z.string()]).meta({
                     description:
-                      'The single-use proof challenge, as hex. It expires after 5 minutes, and only the same user spends it.',
+                      'The single-use challenge, as hex, which expires after 5 minutes.',
                     examples: [
                       '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
                     ],
@@ -283,25 +280,25 @@ namespace schema {
                   }),
                   userVerification: z.literal('required').meta({
                     description:
-                      'Every passkey signature requires user verification.',
+                      'Requires user verification, such as a biometric or PIN.',
                   }),
                 })
                 .meta({
                   description:
-                    'The `PublicKeyCredentialRequestOptions`, serialized with the challenge as hex.',
+                    'The `PublicKeyCredentialRequestOptions`, with the challenge as hex.',
                 }),
             })
             .meta({
-              description: 'The options for `navigator.credentials.get()`.',
+              description: 'The argument for `navigator.credentials.get()`.',
             }),
           type: z.literal('passkey').meta({
             description:
-              'Sign the options with the new passkey, then send the assertion to `POST /v1/account/passkey/verify`.',
+              'Sign the challenge with the new passkey, then send the assertion to `POST /v1/account/passkey/verify`.',
           }),
         })
         .meta({
           description:
-            "The next step: the new passkey's signature, which proves that the authenticator holds its private key.",
+            'The next step: a signature of the new passkey, which proves that the authenticator holds its private key.',
         }),
     })
   }
@@ -310,21 +307,20 @@ namespace schema {
     export const json = z.object({
       account: address.optional().meta({
         description:
-          "A configurable Tempo Account that the user's cloud wallet owns in the `default` realm, which the passkey joins as a second owner on `chain`. Absent, the passkey owns an account of its own.",
+          'A configurable Tempo Account of the user, which the passkey joins as a second owner. Without it, the passkey owns a new account.',
         examples: ['0x7a3f9c2b1e5d8a4f6c0b3e7d9a2f5c8b1e4d7a0f'],
       }),
       assertion: Passkey.schema.assertion,
       chain: Chain.schema.optional().meta({
         description:
-          "The chain whose accounts are configurable, where `account` is, and whose address of the passkey's own account the response returns. Without it, the first such chain for `account`, and the passkey's own address otherwise.",
+          'The chain with configurable accounts where the passkey joins `account`. Defaults to the first such chain.',
         examples: ['local'],
       }),
     })
 
     export const response = z.object({
       address: z.string().meta({
-        description:
-          "The address of the Tempo Account that the passkey owns: `account`, or the passkey's own account on `chain`.",
+        description: 'The address of the Tempo Account that the passkey owns.',
         examples: ['0x7a3f9c2b1e5d8a4f6c0b3e7d9a2f5c8b1e4d7a0f'],
       }),
       id: Passkey.schema.credentialId.meta({
@@ -340,12 +336,12 @@ namespace schema {
     export const response = z.object({
       passkeys: z.boolean().meta({
         description:
-          "Whether a passkey sign-in for the app runs on the page that sends the request, at a relying party of the app's realms. `false` without `client_id`, or for Tempo ID's own page.",
+          "Whether passkey sign-in for the app works on the page that sends the request. `false` without `client_id`, or on Tempo ID's own page.",
         examples: [true],
       }),
       realms: z.array(TempoAccount.schema.realm).readonly().meta({
         description:
-          "The realms the app reaches, never empty. The first holds a user's first account.",
+          "The app's realms, in order. A user's first account is in the first realm.",
       }),
     })
   }
@@ -362,20 +358,20 @@ namespace schema {
           }),
         configurable: z.boolean().meta({
           description:
-            'Whether Tempo Accounts can be upgraded to configurable accounts (TIP-1107) on the chain, as the deployment sets.',
+            'Whether Tempo Accounts on the chain are configurable (TIP-1107).',
           examples: [false],
         }),
         name: Chain.schema.meta({
-          description: 'The name that the `chain` parameter carries.',
+          description: 'The value of the `chain` parameter.',
           examples: ['testnet'],
         }),
       })
-      .meta({ description: 'A chain that a page can select.' })
+      .meta({ description: 'A chain.' })
 
     export const response = z.object({
       chains: z.array(entry).readonly().meta({
         description:
-          "The chains in order: `mainnet`, `testnet`, then the deployment's listed chains.",
+          'The chains: `mainnet`, `testnet`, then the chains that the deployment adds.',
       }),
     })
   }
@@ -392,12 +388,12 @@ namespace schema {
                 examples: [true],
               }),
             })
-            .meta({ description: 'A chain that a page can select.' }),
+            .meta({ description: 'A chain.' }),
         )
         .readonly()
         .meta({
           description:
-            "The chains in order: `mainnet`, `testnet`, then the deployment's listed chains.",
+            'The chains: `mainnet`, `testnet`, then the chains that the deployment adds.',
         }),
     })
   }
@@ -422,7 +418,7 @@ namespace schema {
                   examples: [1337],
                 }),
               name: Chain.schema.meta({
-                description: 'The name that the `chain` parameter carries.',
+                description: 'The value of the `chain` parameter.',
                 examples: ['local'],
               }),
               node: z.enum(['down', 'up']).meta({
@@ -446,14 +442,13 @@ namespace schema {
       address: z
         .templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]{40}$/)])
         .meta({
-          description:
-            "The Tempo Account that receives the tokens, one of the user's accounts in the `default` realm.",
+          description: "The user's Tempo Account that receives the tokens.",
           examples: ['0x7a3f9c2b1e5d8a4f6c0b3e7d9a2f5c8b1e4d7a0f'],
           pattern: '^0x[0-9a-fA-F]{40}$',
         }),
       chain: Chain.schema.meta({
         description:
-          'The test chain whose faucet drips the tokens: `testnet`, or a name that `GET /i/chains` lists. Tempo mainnet has no faucet.',
+          'The test chain whose faucet sends the tokens. Tempo mainnet has no faucet.',
         examples: ['testnet'],
       }),
     })
@@ -470,8 +465,7 @@ namespace schema {
         )
         .readonly()
         .meta({
-          description:
-            'The hashes of the transfers, one for each token that the faucet drips, each one landed.',
+          description: 'The hashes of the transfers, one for each token.',
           examples: [
             [
               '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
@@ -486,12 +480,12 @@ namespace schema {
       .object({
         account: address.optional().meta({
           description:
-            "One of the user's Tempo Accounts in the app's realms on `chain`, which a linked wallet.tempo passkey owns and the upgrade makes configurable. Absent with `credentialId`.",
+            'The Tempo Account to upgrade, which a wallet.tempo passkey of the user owns. Absent with `credentialId`.',
           examples: ['0x7a3f9c2b1e5d8a4f6c0b3e7d9a2f5c8b1e4d7a0f'],
         }),
         chain: Chain.schema.optional().meta({
           description:
-            'The chain whose accounts are configurable, where the upgrade runs. Defaults to the first such chain that the deployment names.',
+            'The chain with configurable accounts where the upgrade runs. Defaults to the first such chain.',
           examples: ['local'],
         }),
         client_id: z
@@ -501,12 +495,12 @@ namespace schema {
           .optional()
           .meta({
             description:
-              'The app whose realms hold the account. Without it, the `default` realm.',
+              'The app whose realms hold the account. Defaults to the `default` realm.',
             examples: ['client_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
           }),
         credentialId: Passkey.schema.credentialId.optional().meta({
           description:
-            "A wallet.tempo passkey of the user's email that has not linked to the user yet, as `GET /i/account/passkeys` lists it. Its assertion over the upgrade links it. Absent with `account`. Only Tempo ID's own page sends it.",
+            "A wallet.tempo passkey of the user's email that is not linked yet, which the upgrade links. Absent with `account`.",
           examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
         }),
         key: z
@@ -520,7 +514,7 @@ namespace schema {
               })
               .meta({
                 description:
-                  "The access key's raw signature over `step.key.digest`, as a serialized signature envelope.",
+                  "The access key's signature of `step.key.digest`, as a serialized signature envelope.",
                 examples: [
                   '0x997c61aa10e2330c076d6ba7abca1e71703a8f039291db103a62e085c9b2cf0d3f7e31ec9028229acc83093fbb722fa700fd6e4ea15d584df1bf384eb0051e0d1c',
                 ],
@@ -529,11 +523,11 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The access key's signature of its registration, on the repeated request of a step with `key`.",
+              "The access key's signature of its registration, for a step with `key`.",
           }),
         key_authorization: KeyAuthorization.schema.rpc.optional().meta({
           description:
-            "A key that the passkey signed as the account's own key, such as with `skip_upgrade`, on the first request. The chain registers it before the upgrade, so it keeps working after. Its chain is the upgrade's when `chain` is absent.",
+            'A key that the passkey signed before the upgrade, such as with `skip_upgrade`. Tempo ID registers it first, so it keeps working after the upgrade.',
         }),
         passkey: z
           .object({
@@ -542,7 +536,7 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The passkey step's result: the passkey's assertion over the step's challenge. Absent on the first request.",
+              "The passkey's assertion over the step's challenge. Absent on the first request.",
           }),
       })
       .refine(
@@ -585,11 +579,11 @@ namespace schema {
                         )
                         .meta({
                           description:
-                            "The account's passkey, the only one the browser offers.",
+                            "The account's passkey, which is the only passkey that the browser offers.",
                         }),
                       challenge: z.templateLiteral(['0x', z.string()]).meta({
                         description:
-                          'The digest of the transaction that installs the configuration, as hex. It expires after 5 minutes, and only the same user spends it.',
+                          'The digest of the upgrade transaction, as hex, which expires after 5 minutes.',
                         examples: [
                           '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
                         ],
@@ -600,22 +594,23 @@ namespace schema {
                       }),
                       userVerification: z.literal('required').meta({
                         description:
-                          'Every passkey signature requires user verification.',
+                          'Requires user verification, such as a biometric or PIN.',
                       }),
                     })
                     .meta({
                       description:
-                        'The `PublicKeyCredentialRequestOptions`, serialized with the challenge as hex.',
+                        'The `PublicKeyCredentialRequestOptions`, with the challenge as hex.',
                     }),
                 })
                 .meta({
-                  description: 'The options for `navigator.credentials.get()`.',
+                  description:
+                    'The argument for `navigator.credentials.get()`.',
                 }),
               key: z
                 .object({
                   digest: z.templateLiteral(['0x', z.string()]).meta({
                     description:
-                      'The digest of the transaction that registers the key, which the access key signs raw. Tempo ID sponsors the transaction.',
+                      "The digest of the key's registration transaction, for the access key to sign. Tempo ID pays its fee.",
                     examples: [
                       '0x3c8a5e1f0b7d2c946a1e8f3b5d7c9a2e4f6b8d0c1e3a5f7b9d2c4e6a8f0b1d3c',
                     ],
@@ -624,16 +619,16 @@ namespace schema {
                 .optional()
                 .meta({
                   description:
-                    "The key's registration, for a request with `key_authorization` whose key the chain does not hold yet. Repeat the request with `key.signature` too.",
+                    "The key's registration, if `key_authorization` names a key that the chain does not hold yet. Repeat the request with `key.signature`.",
                 }),
               type: z.literal('passkey').meta({
                 description:
-                  'Sign the options with the passkey, then repeat the request with `passkey.assertion`.',
+                  'Sign the challenge with the passkey, then repeat the request with `passkey.assertion`.',
               }),
             })
             .meta({
               description:
-                "The next step: the passkey's signature of the transaction, since only the passkey signs for the account.",
+                "The next step: the passkey's signature of the upgrade transaction.",
             }),
         })
         .meta({ description: 'The passkey step.' }),
@@ -647,8 +642,7 @@ namespace schema {
           z
             .object({
               address: address.meta({
-                description:
-                  "The address of the passkey's Tempo Account, which its public key derives.",
+                description: "The address of the passkey's Tempo Account.",
                 examples: ['0x7a3f9c2b1e5d8a4f6c0b3e7d9a2f5c8b1e4d7a0f'],
               }),
               credentialId: Passkey.schema.credentialId.meta({
@@ -661,7 +655,7 @@ namespace schema {
         .readonly()
         .meta({
           description:
-            "The passkeys that wallet.tempo stores for the user's email and that link to no user yet, oldest first. Empty without the wallet service.",
+            "The wallet.tempo passkeys of the user's email that are not linked yet, oldest first.",
         }),
     })
   }
@@ -670,7 +664,7 @@ namespace schema {
     export const query = z.object({
       chain: Chain.schema.meta({
         description:
-          'The chain to list upgrades on, such as the chain that the sign-in page shows. A chain whose accounts are not configurable lists none.',
+          'The chain to list upgrades on. A chain without configurable accounts lists none.',
         examples: ['t14'],
       }),
     })
@@ -716,8 +710,7 @@ namespace schema {
         )
         .readonly()
         .meta({
-          description:
-            'The upgrades, linked accounts first, in the order of the chains. Empty without a chain whose accounts are configurable.',
+          description: 'The upgrades, linked accounts first.',
         }),
     })
   }
@@ -735,7 +728,7 @@ export const account = new Hono<Env>()
     '/v1/account',
     OpenApi.describeRoute({
       description:
-        'Reads the signed-in user and their Tempo Accounts in the realms of the app that `client_id` names, or of the `default` realm. The account that the user selected for the app comes first, then the oldest.',
+        'Returns the signed-in user and their Tempo Accounts in the realms of the `client_id` app, or of the `default` realm.',
       responses: OpenApi.responses({
         errors: [
           ...OpenApi.validate.errors,
@@ -858,7 +851,7 @@ export const account = new Hono<Env>()
     '/v1/account',
     OpenApi.describeRoute({
       description:
-        'Returns the signed-in user and their Tempo Accounts, as `GET /v1/account` does. For a user with no account or passkey, it also creates a Privy-owned account in the first realm, when that realm has a Privy app. The JSON body needs a CORS preflight, which Tempo ID grants only to the origins of first-party apps.',
+        'Returns the signed-in user and their Tempo Accounts, as `GET /v1/account` does, and first creates a Tempo Account for a user who has none. Only the pages of first-party apps can send it.',
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -988,7 +981,7 @@ export const account = new Hono<Env>()
     '/v1/account/passkey/options',
     OpenApi.describeRoute({
       description:
-        "Issues a single-use registration challenge for the signed-in user, and returns creation options for a passkey of the `default` realm. Requires a sign-in within the last 10 minutes and fewer than 10 passkeys. Only Tempo ID's own page sends the request.",
+        "Passkey registration, step 1 of 3: returns the options for `navigator.credentials.create()`. Requires a sign-in within the last 10 minutes, on Tempo ID's own page or the page of a first-party app with the `tempo-id:sign` scope.",
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -999,6 +992,7 @@ export const account = new Hono<Env>()
           Passkey.LimitError,
           Passkey.NotPermittedError,
           Passkey.ReauthenticationRequiredError,
+          Passkey.RegisterNotPermittedError,
         ],
         success: {
           description: 'The creation options.',
@@ -1010,9 +1004,18 @@ export const account = new Hono<Env>()
     }),
     OpenApi.validate('json', schema.passkeyOptions.json),
     async (c) => {
-      // The ceremony runs at Tempo ID's origin, so only its own page registers a passkey.
-      if (Cors.appOrigin(c))
+      // The ceremony runs at Tempo ID's origin, or at a first-party app's page, which the challenge
+      // stores. `Cors.firstParty` refuses any other page's write before the route runs.
+      const page = Cors.appOrigin(c)
+      if (page && !c.var.firstParty?.length)
         return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+      // A registered passkey signs in as the user, so an app's page registers one only for an app
+      // that the deployment trusts with its own challenges.
+      if (page && !c.var.firstParty?.some((app) => app.sign))
+        return ErrorResponse.json(
+          c,
+          new Passkey.RegisterNotPermittedError({ origin: page }),
+        )
 
       const session = await Timing.measure(c, Session.get(c), 'Session.get')
       if (!session)
@@ -1062,14 +1065,26 @@ export const account = new Hono<Env>()
         }),
         'Realm.withDefaults',
       )
-      const relyingParty = Passkey.relyingParty(realms, { origin: env.URL })
+      // The relying party must cover the page beside Tempo ID, so the page shares a site with Tempo
+      // ID, and the browser sends the session cookie on the page's requests.
+      const relyingParty = Passkey.relyingParty(realms, {
+        origin: env.URL,
+        page,
+      })
       const realm = realms.find((entry) => entry.id === relyingParty?.realmId)
       if (!relyingParty || !realm)
-        return ErrorResponse.json(c, new Passkey.NotPermittedError())
+        return ErrorResponse.json(
+          c,
+          new Passkey.NotPermittedError({ origin: page }),
+        )
 
       const challenge = await Timing.measure(
         c,
-        Passkey.requestRegistration(db, { rpId: relyingParty.rpId, userId }),
+        Passkey.requestRegistration(db, {
+          origin: page,
+          rpId: relyingParty.rpId,
+          userId,
+        }),
         'Passkey.requestRegistration',
       )
       const excluded = held.flatMap((key) =>
@@ -1102,7 +1117,7 @@ export const account = new Hono<Env>()
     '/v1/account/passkey',
     OpenApi.describeRoute({
       description:
-        "Verifies a new passkey's credential over a challenge from `POST /v1/account/passkey/options`, and returns a proof challenge for the passkey to sign. The attestation carries no signature, so only `POST /v1/account/passkey/verify` stores the passkey. Requires a sign-in within the last 10 minutes. Only Tempo ID's own page sends the request.",
+        'Passkey registration, step 2 of 3: verifies the credential from `navigator.credentials.create()`, and returns a challenge for the new passkey to sign. The signature proves that the authenticator holds the private key.',
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -1113,6 +1128,7 @@ export const account = new Hono<Env>()
           ErrorResponse.CrossSiteRequestError,
           Passkey.LimitError,
           Passkey.ReauthenticationRequiredError,
+          Passkey.RegisterNotPermittedError,
           Passkey.WebAuthnRejectedError,
         ],
         success: {
@@ -1125,8 +1141,16 @@ export const account = new Hono<Env>()
     }),
     OpenApi.validate('json', schema.passkey.json),
     async (c) => {
-      if (Cors.appOrigin(c))
+      const page = Cors.appOrigin(c)
+      if (page && !c.var.firstParty?.length)
         return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+      // A registered passkey signs in as the user, so an app's page registers one only for an app
+      // that the deployment trusts with its own challenges.
+      if (page && !c.var.firstParty?.some((app) => app.sign))
+        return ErrorResponse.json(
+          c,
+          new Passkey.RegisterNotPermittedError({ origin: page }),
+        )
 
       const session = await Timing.measure(c, Session.get(c), 'Session.get')
       if (!session)
@@ -1157,13 +1181,15 @@ export const account = new Hono<Env>()
         }),
         'Passkey.takeRegistration',
       )
-      const verified = challenge
-        ? Passkey.verifyRegistration(credential, {
-            challenge: challenge.challenge,
-            origin: new URL(env.URL).origin,
-            rpId: challenge.rpId,
-          })
-        : undefined
+      // A challenge serves only the page that requested it, and the browser must report that page.
+      const verified =
+        challenge && challenge.origin === page
+          ? Passkey.verifyRegistration(credential, {
+              challenge: challenge.challenge,
+              origin: challenge.origin ?? new URL(env.URL).origin,
+              rpId: challenge.rpId,
+            })
+          : undefined
       if (!challenge || !verified)
         return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
 
@@ -1209,6 +1235,7 @@ export const account = new Hono<Env>()
         c,
         Passkey.requestProof(db, {
           credential: verified,
+          origin: challenge.origin,
           rpId: challenge.rpId,
           userId,
         }),
@@ -1230,7 +1257,7 @@ export const account = new Hono<Env>()
     '/v1/account/passkey/verify',
     OpenApi.describeRoute({
       description:
-        "Registers a passkey for the signed-in user with its assertion over the proof challenge. The passkey owns its own Tempo Account in the `default` realm, or joins `account` as a second owner. Requires a sign-in within the last 10 minutes. Only Tempo ID's own page sends the request.",
+        "Passkey registration, step 3 of 3: verifies the new passkey's assertion from `navigator.credentials.get()`, and stores the passkey. The passkey owns a new Tempo Account, or joins `account` as a second owner.",
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -1244,6 +1271,7 @@ export const account = new Hono<Env>()
           ErrorResponse.CrossSiteRequestError,
           Passkey.LimitError,
           Passkey.ReauthenticationRequiredError,
+          Passkey.RegisterNotPermittedError,
           Passkey.WebAuthnRejectedError,
         ],
         success: {
@@ -1256,8 +1284,16 @@ export const account = new Hono<Env>()
     }),
     OpenApi.validate('json', schema.passkeyVerify.json),
     async (c) => {
-      if (Cors.appOrigin(c))
+      const page = Cors.appOrigin(c)
+      if (page && !c.var.firstParty?.length)
         return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+      // A registered passkey signs in as the user, so an app's page registers one only for an app
+      // that the deployment trusts with its own challenges.
+      if (page && !c.var.firstParty?.some((app) => app.sign))
+        return ErrorResponse.json(
+          c,
+          new Passkey.RegisterNotPermittedError({ origin: page }),
+        )
 
       const session = await Timing.measure(c, Session.get(c), 'Session.get')
       if (!session)
@@ -1291,10 +1327,11 @@ export const account = new Hono<Env>()
       // Only the attested public key verifies the proof, so the user holds its private key.
       if (
         !proof ||
+        proof.origin !== page ||
         assertion.id !== proof.id ||
         !Passkey.verify(assertion, {
           challenge: proof.challenge,
-          origin: new URL(env.URL).origin,
+          origin: proof.origin ?? new URL(env.URL).origin,
           publicKey: proof.publicKey,
           rpId: proof.rpId,
         })
@@ -1399,7 +1436,7 @@ export const account = new Hono<Env>()
     '/v1/realms',
     OpenApi.describeRoute({
       description:
-        'Lists the realms of the app that `client_id` names, in order, and whether its passkey sign-in runs on the page that sends the request. An app without realms reaches the `default` realm alone.',
+        'Lists the realms of the `client_id` app, and whether passkey sign-in works on the page that sends the request.',
       responses: OpenApi.responses({
         errors: [...OpenApi.validate.errors],
         success: {
@@ -1459,7 +1496,7 @@ export const account = new Hono<Env>()
     '/v1/chains',
     OpenApi.describeRoute({
       description:
-        'Lists the chains that the `chain` parameter selects, each with its chain ID: `mainnet`, `testnet`, then the chains that the deployment lists.',
+        'Lists the chains that the `chain` parameter accepts, with their chain IDs.',
       responses: OpenApi.responses({
         success: {
           description: 'The chains.',
@@ -1474,7 +1511,7 @@ export const account = new Hono<Env>()
     '/i/chains',
     OpenApi.describeRoute({
       description:
-        "Lists the chains that the `chain` parameter of `GET /v1/account` and `POST /v1/account` selects, as `GET /v1/chains` does, each with whether its faucet funds accounts. Internal: only Tempo ID's own pages send the request, so the public document leaves it out.",
+        "Lists the chains, as `GET /v1/chains` does, with whether each has a faucet. Internal to Tempo ID's own pages.",
       // Internal routes stay out of `/openapi.json` and `/docs`.
       hide: true,
       responses: OpenApi.responses({
@@ -1504,7 +1541,7 @@ export const account = new Hono<Env>()
     '/i/chains/status',
     OpenApi.describeRoute({
       description:
-        "Returns whether the node and the Tempo API of each chain that the deployment lists respond, apart from `mainnet` and `testnet`. A probe that fails or takes longer than a second reads as `down`, and a status can be up to 2 seconds old. Internal: only Tempo ID's own page sends the request, so the public document leaves it out.",
+        "Returns whether the node and the Tempo API of each added chain respond. Internal to Tempo ID's own pages.",
       // Internal routes stay out of `/openapi.json` and `/docs`.
       hide: true,
       responses: OpenApi.responses({
@@ -1555,7 +1592,7 @@ export const account = new Hono<Env>()
     '/i/account/fund',
     OpenApi.describeRoute({
       description:
-        "Funds one of the signed-in user's Tempo Accounts in the `default` realm from the faucet of the test chain that `chain` names, and waits until each transfer lands. Tempo mainnet has no faucet. Internal: only Tempo ID's own page sends the request, so the public document leaves it out.",
+        "Funds one of the user's Tempo Accounts from the faucet of a test chain, and waits for the transfers. Internal to Tempo ID's own pages.",
       // Internal routes stay out of `/openapi.json` and `/docs`.
       hide: true,
       responses: OpenApi.responses({
@@ -1670,7 +1707,7 @@ export const account = new Hono<Env>()
     '/v1/account/upgrade',
     OpenApi.describeRoute({
       description:
-        "Upgrades a wallet.tempo passkey's Tempo Account of the signed-in user in place to a configurable account (TIP-1113), on a chain whose accounts are configurable. The account keeps its address, and the passkey stays its only owner. The first request returns the passkey step, and the repeat with `passkey.assertion` sends the upgrade. With `key_authorization`, Tempo ID first registers that key, sponsored, so it keeps working. Requires a sign-in within the last 10 minutes.",
+        "Upgrades a wallet.tempo passkey's Tempo Account to a configurable account (TIP-1113) at the same address. The first request returns a passkey step, and the repeat with `passkey.assertion` sends the upgrade.",
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -1884,7 +1921,7 @@ export const account = new Hono<Env>()
     '/i/account/passkeys',
     OpenApi.describeRoute({
       description:
-        "Lists the wallet.tempo passkeys of the signed-in user's email that link to no user yet, which `POST /v1/account/upgrade` takes as `credentialId`. The sign-in proved the email, so the list reveals nothing to another person. Counts against the user's `ACCOUNT_LIMIT`. Refuses a cross-site navigation with `cross_site_request`. Internal: only Tempo ID's own page sends the request, so the public document leaves it out.",
+        "Lists the wallet.tempo passkeys of the user's email that are not linked yet, for `POST /v1/account/upgrade`. Internal to Tempo ID's own pages.",
       // Internal routes stay out of `/openapi.json` and `/docs`.
       hide: true,
       responses: OpenApi.responses({
@@ -1942,7 +1979,7 @@ export const account = new Hono<Env>()
     '/i/account/upgrades',
     OpenApi.describeRoute({
       description:
-        "Lists the upgrades that wait for the signed-in user on `chain`, which the sign-in page offers, when `CONFIGURABLE_ACCOUNTS` names it. Each linked wallet.tempo passkey's account without a configuration on the chain comes first. For a user who holds no account, each wallet.tempo passkey of the email that links to no user follows. `POST /v1/account/upgrade` takes either. Reads stored rows and wallet.tempo, never a chain. Counts against the user's `ACCOUNT_LIMIT`. Refuses a cross-site navigation with `cross_site_request`. Internal: only Tempo ID's own page sends the request, so the public document leaves it out.",
+        "Lists the user's pending upgrades on `chain`, for `POST /v1/account/upgrade`. Internal to Tempo ID's own pages.",
       // Internal routes stay out of `/openapi.json` and `/docs`.
       hide: true,
       responses: OpenApi.responses({