@tempoxyz/id 0.0.1 → 0.0.2

package/src/api/authenticate.ts

@@ -71,8 +71,7 @@ namespace schema {
 
     export const response = z.object({
       sent: z.literal(true).meta({
-        description:
-          'The request is accepted. The value is the same for every address.',
+        description: 'Always `true`, so the response reveals no account.',
       }),
     })
   }
@@ -82,11 +81,11 @@ namespace schema {
       .object({
         assertion: Passkey.schema.assertion.optional().meta({
           description:
-            "The assertion of the email step's passkey, over a challenge from `POST /v1/auth/passkey/options` with `link`. Required with `link`, since only the person who holds the passkey can link it.",
+            "The passkey's assertion over options requested with the same `link`. Required with `link`, so only the passkey's holder can link it.",
         }),
         authorize: Authorize.schema.request.optional().meta({
           description:
-            "The app's headless authorization request, as `POST /v1/authorize` takes it, from a first-party app's page. The sign-in then authorizes the app in the same request, creates a first Tempo Account for a user who holds none, and returns the authorization. A refusal that depends only on the app and the request, such as a key over the headless ceiling, comes before the sign-in and leaves the code unspent. A refusal of the authorization server after the sign-in, such as for a scope that the app's registration lacks, spends the code. Not with `link` or `oauth_query`.",
+            "A headless authorization request, as `POST /v1/authorize` takes it, to authorize the app in the same request. Only from a first-party app's page, and not with `link` or `oauth_query`.",
         }),
         code: z
           .string()
@@ -103,12 +102,12 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The email step's `link`, which links the wallet.tempo passkey that asked for it to this user, with that passkey's `assertion`. An expired link refuses the sign-in with `passkey_link_expired`, and the code stays valid.",
+              "The `link` of the email step, which links its wallet.tempo passkey to this user. Send it with the passkey's `assertion`.",
             examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
           }),
         passkey: z.literal(true).optional().meta({
           description:
-            "With `authorize`, requests the passkey step for an account that a passkey owns, in place of `webauthn_required`. The response's `authorization` is then the step, which the page signs, and `POST /v1/authorize` with `passkey: { assertion }` signs the key.",
+            'With `authorize`, returns a passkey step for a passkey-owned account, in place of `webauthn_required`. Send its assertion to `POST /v1/authorize` to sign the key.',
         }),
         // The bound covers an authorization request's query, and limits what an unsigned query can
         // write, since the passkey challenge stores its client ID before the signature is checked.
@@ -118,7 +117,7 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The sign-in page's query string, which Better Auth signs when an app's authorization request sends the browser there. At most 8,192 characters.",
+              "The signed query string of the sign-in page, which names the app's pending authorization request.",
             examples: [
               'client_id=client_01JZ8Q6W3N1R5B4V7C2X9K0M3T&response_type=code&exp=1760000000&sig=Gx3kB0',
             ],
@@ -145,7 +144,7 @@ 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'],
         }),
       })
@@ -157,14 +156,14 @@ namespace schema {
         .optional()
         .meta({
           description:
-            "The app's headless authorization, for a sign-in that carried `authorize`, or a sign-in with key signature on the app's page whose options carried it. With `passkey`, the passkey step for a passkey-owned account. Absent for any other sign-in.",
+            "The app's authorization, for a sign-in with `authorize`, or a passkey step with `passkey`. Absent for any other sign-in.",
         }),
       redirect: z
         .url()
         .nullable()
         .meta({
           description:
-            "Where the browser continues: the app's `redirect_uri` with an authorization code, or `null` for a sign-in that no app waits on.",
+            "The URL to send the browser to next, such as the app's `redirect_uri` with a code. `null` if no app waits on the sign-in.",
           examples: [
             'https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA',
           ],
@@ -184,7 +183,7 @@ namespace schema {
       .object({
         authorize: Authorize.schema.request.optional().meta({
           description:
-            "The app's headless authorization request, as `POST /v1/authorize` takes it, from a first-party app's page. The challenge is then the digest of its key, so the passkey's one assertion signs the user in and signs the key, and `POST /v1/auth/passkey/verify` returns the authorization. Requires `client_id`, the same as its own.",
+            "A headless authorization request, as `POST /v1/authorize` takes it. The passkey's one assertion then signs the user in and signs the key, and requires the same `client_id`.",
         }),
         client_id: z
           .string()
@@ -193,7 +192,7 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The client ID of the first-party app whose page runs the ceremony, which selects the app's realms. Required from an app's page, whose `Origin` must be one of the app's redirect URI origins.",
+              "The first-party app whose page runs the sign-in. Required from an app's page, which must be on a redirect URI origin of the app.",
             examples: ['client_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
           }),
         credentialId: z
@@ -204,12 +203,12 @@ namespace schema {
           .optional()
           .meta({
             description:
-              'The credential ID, or up to 16 IDs, that the browser offers as `allowCredentials`, base64url. Defaults to every discoverable passkey of the relying party, as an empty list does.',
+              'Up to 16 credential IDs, base64url, that the browser offers. Defaults to every passkey of the relying party.',
             examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
           }),
         link: verify.json.shape.link.meta({
           description:
-            "The email step's `link`, which limits the options to that step's passkey, in place of `credentialId`. The emailed-code sign-in then sends the passkey's assertion with the `link`.",
+            'The `link` of the email step, which limits the options to its passkey. Send the assertion with `POST /v1/auth/code/verify`.',
           examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
         }),
         mediation: z
@@ -217,7 +216,7 @@ namespace schema {
           .optional()
           .meta({
             description:
-              'Returned in the options for `navigator.credentials.get()`, such as `conditional` for passkey autofill.',
+              'The `mediation` of the options, such as `conditional` for passkey autofill.',
             examples: ['conditional'],
           }),
         oauth_query: verify.json.shape.oauth_query,
@@ -227,7 +226,7 @@ namespace schema {
           .optional()
           .meta({
             description:
-              "The user code of the device grant that the sign-in returns to, ignored with `oauth_query` or `client_id`. A pending, unbound code selects its app's realms, and any other code selects the `default` realm.",
+              'The user code of the device grant that the sign-in continues, whose app selects the realm. Ignored with `oauth_query` or `client_id`.',
             examples: ['WDJB-MJHT'],
           }),
       })
@@ -262,16 +261,18 @@ namespace schema {
                         description: 'The credential type.',
                       }),
                     })
-                    .meta({ description: 'A passkey the browser offers.' }),
+                    .meta({
+                      description: 'A passkey that the browser offers.',
+                    }),
                 )
                 .optional()
                 .meta({
                   description:
-                    'The passkeys the browser offers, from `credentialId`. Absent, it offers every discoverable passkey of the relying party.',
+                    'The passkeys that the browser offers. Absent to offer every passkey of the relying party.',
                 }),
               challenge: z.templateLiteral(['0x', z.string()]).meta({
                 description:
-                  'The single-use challenge, as hex. It expires after 5 minutes.',
+                  'The single-use challenge, as hex, which expires after 5 minutes.',
                 examples: [
                   '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
                 ],
@@ -282,16 +283,16 @@ namespace schema {
               }),
               userVerification: z.literal('required').meta({
                 description:
-                  'Every passkey sign-in 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()`.',
         }),
     })
   }
@@ -310,26 +311,25 @@ namespace schema {
             .object({
               link: z.string().meta({
                 description:
-                  'Send as `link` with the emailed-code sign-in, which links the passkey to that user.',
+                  'The value to send as `link` with the email sign-in, which links the passkey.',
                 examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
               }),
               signed: z.literal(false).meta({
-                description:
-                  'Whether the assertion already signed a key authorization. This route signs none.',
+                description: 'Always `false`, since this step signs no key.',
               }),
               type: z.literal('email').meta({
                 description:
-                  'Sign in with an emailed code, which links the passkey to that user.',
+                  'Sign in with an emailed code to link the passkey.',
               }),
             })
             .meta({
               description:
-                'The email step, for a wallet.tempo passkey whose account has no email.',
+                'The email step, for a wallet.tempo passkey without an email.',
             }),
         })
         .meta({
           description:
-            'A passkey sign-in that continues when the user verifies an email address.',
+            'A passkey sign-in that needs an email sign-in to finish.',
         }),
     ])
   }
@@ -350,8 +350,7 @@ namespace schema {
             .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'],
             }),
         })
@@ -392,15 +391,14 @@ namespace schema {
         .optional()
         .meta({
           description:
-            "The page that sign-in returns to, from the sign-in page's query. Only a path on the device page passes, and any other value reads as absent.",
+            'The page to return to after sign-in. Only a path on the device page is accepted.',
           examples: ['/device?code=WDJB-MJHT'],
         }),
     })
 
     export const response = z.object({
       passkeys: z.boolean().meta({
-        description:
-          "Whether one of the sign-in's realms holds passkeys that sign in at Tempo ID's origin, so the page offers passkey sign-in.",
+        description: 'Whether the page offers passkey sign-in.',
         examples: [true],
       }),
       app: z
@@ -408,7 +406,7 @@ namespace schema {
         .nullable()
         .meta({
           description:
-            'The display name of the app of the request in `oauth_query`, or its client ID without a name. `null` for a forged or expired query, or an unknown app.',
+            'The display name of the app in `oauth_query`, or its client ID if it has none. `null` for an invalid query or an unknown app.',
           examples: ['Tempo Cash'],
         }),
       host: z
@@ -416,14 +414,14 @@ namespace schema {
         .nullable()
         .meta({
           description:
-            "The host of a third-party app's client ID, which the page shows beside its name, or `null` for a registered app or without an app.",
+            "The host of a third-party app's client ID, which the page shows beside its name. `null` for a registered app.",
           examples: ['app.example'],
         }),
       request: z
         .object({
           app: z.string().meta({
             description:
-              "The app's display name, or its client ID without one.",
+              "The app's display name, or its client ID if it has none.",
             examples: ['Tempo Cash'],
           }),
           key: KeyAuthorization.schema.description,
@@ -431,14 +429,14 @@ namespace schema {
         .nullable()
         .meta({
           description:
-            'The app and the key of the signed authorization request in `oauth_query`, which the sign-in grants. `null` when the sign-in grants no key, such as for an invalid query or a third-party app.',
+            'The app and the key that the request in `oauth_query` grants on sign-in. `null` if the sign-in grants no key.',
         }),
       return_to: z
         .string()
         .nullable()
         .meta({
           description:
-            'The page that sign-in returns to, a path on the device page, or `null` for the account.',
+            'The page to return to after sign-in, or `null` for the account page.',
           examples: ['/device?code=WDJB-MJHT'],
         }),
       user_code: z
@@ -446,12 +444,12 @@ namespace schema {
         .nullable()
         .meta({
           description:
-            'The user code of the device page that sign-in returns to, or `null` without one.',
+            'The user code of the device page to return to, or `null`.',
           examples: ['WDJBMJHT'],
         }),
       verified: z.boolean().meta({
         description:
-          'Whether `app` is a registered app, whose name the page marks as verified. `false` for a third-party app, which names itself in its metadata document, and without an app.',
+          'Whether `app` is a registered app, which the page marks as verified. `false` for a third-party app.',
         examples: [true],
       }),
     })
@@ -520,7 +518,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/code',
     OpenApi.describeRoute({
       description:
-        'Emails a sign-in code. The response is the same for every address, so it reveals no account.',
+        'Email sign-in, step 1 of 2: emails a sign-in code. The response is the same for every address, so it reveals no account.',
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -531,8 +529,7 @@ export const authenticate = new Hono<Env>()
           ErrorResponse.UpstreamUnavailableError,
         ],
         success: {
-          description:
-            'The response for every address: the email service accepted the code, or does not deliver to the address.',
+          description: 'The same response for every address.',
           schema: schema.code.response,
         },
       }),
@@ -608,7 +605,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/code/verify',
     OpenApi.describeRoute({
       description:
-        'Signs in with an emailed code, and sets the session cookie. For a user with no Tempo Account in the first realm of the app that `oauth_query` names, or in the `default` realm, it creates one when that realm creates accounts. A failed creation leaves the user signed in, and the next sign-in or `POST /v1/account` creates the account. With `authorize`, it also authorizes the app as `POST /v1/authorize` does, and a refusal after the sign-in carries `Tempo-Id-Signed-In: true`.',
+        'Email sign-in, step 2 of 2: verifies the code, sets the session cookie, and creates a Tempo Account for a user who has none. With `authorize`, it also authorizes the app, as `POST /v1/authorize` does.',
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -881,7 +878,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/passkey/options',
     OpenApi.describeRoute({
       description:
-        "Issues a single-use challenge, and returns request options for the passkeys of the first realm whose relying party covers Tempo ID's origin, and also the page's origin from an app's page. The realms are those of the app that `oauth_query`, `client_id`, or `user_code` names, or the `default` realm. With `link`, that realm must be the `default` realm at the link's relying party.",
+        'Passkey sign-in, step 1 of 2: returns the options for `navigator.credentials.get()`. The app that `oauth_query`, `client_id`, or `user_code` names selects the relying party.',
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -1117,7 +1114,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/passkey/verify',
     OpenApi.describeRoute({
       description:
-        'Signs in with a passkey assertion over a challenge from `POST /v1/auth/passkey/options`, and sets the session cookie. For a user with no Tempo Account in the first realm of the app that `oauth_query` names, or in the `default` realm, it creates one when that realm creates accounts. A failed creation leaves the user signed in, and the next sign-in or `POST /v1/account` creates the account.',
+        "Passkey sign-in, step 2 of 2: verifies the passkey's assertion, sets the session cookie, and creates a Tempo Account for a user who has none.",
       responses: OpenApi.responses({
         errors: [
           ...BodyLimit.errors,
@@ -1132,7 +1129,7 @@ export const authenticate = new Hono<Env>()
         ],
         success: {
           description:
-            'The signed-in user, with the authorization of a sign-in with key signature, or the email step for a wallet.tempo passkey without an email.',
+            'The signed-in user and any authorization, or the email step for a wallet.tempo passkey without an email.',
           schema: schema.passkeyVerify.response,
         },
       }),
@@ -1405,7 +1402,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/logout',
     OpenApi.describeRoute({
       description:
-        'Signs out: ends the session, revokes the access and refresh tokens that apps received through it, and clears its cookie.',
+        'Signs out: ends the session, revokes the tokens that apps received through it, and clears the cookie.',
       responses: OpenApi.responses({
         errors: [...BodyLimit.errors, ErrorResponse.CrossSiteRequestError],
         success: {
@@ -1431,7 +1428,7 @@ export const authenticate = new Hono<Env>()
   .get(
     '/v1/auth/session',
     OpenApi.describeRoute({
-      description: 'Reads the signed-in user, or `null` without a session.',
+      description: 'Returns the signed-in user, or `null` without a session.',
       responses: OpenApi.responses({
         success: {
           description: 'The session.',
@@ -1461,7 +1458,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/assets',
     OpenApi.describeRoute({
       description:
-        "Lists the sign-in page's scripts and style sheets, which a page on Tempo ID's site prefetches before it redirects. Browsers partition their caches by site, so a page on another site gains nothing.",
+        "Lists the sign-in page's scripts and style sheets, which a page on Tempo ID's site can prefetch before it redirects to sign-in.",
       responses: OpenApi.responses({
         success: {
           description: 'The assets.',
@@ -1485,7 +1482,7 @@ export const authenticate = new Hono<Env>()
     '/v1/auth/methods',
     OpenApi.describeRoute({
       description:
-        'Reads the sign-in methods that the sign-in page offers, the key that `oauth_query` grants, and the page that sign-in returns to. The app of `oauth_query`, or of a pending, unbound device code in `return_to`, selects the realms. The read binds nothing, and counts against the sign-in limit of the IP address.',
+        'Returns what the sign-in page shows: the sign-in methods, any key that `oauth_query` requests, and the page that sign-in returns to.',
       responses: OpenApi.responses({
         errors: [...OpenApi.validate.errors],
         success: {