@tempoxyz/id 0.0.1 → 0.0.2

package/src/internal/Passkey.ts

@@ -17,7 +17,7 @@ import { Address, Base64, Hash, Hex, P256, PublicKey } from 'ox'
 import { Authentication, Registration } from 'webauthx/server'
 import { z } from 'zod'
 import * as Schema from '../app/db/schema.js'
-import type * as Apps from './Apps.js'
+import * as Apps from './Apps.js'
 import * as Authorize from './Authorize.js'
 import * as ErrorResponse from './ErrorResponse.js'
 import * as KeyAuthorization from './KeyAuthorization.js'
@@ -57,8 +57,8 @@ export class LinkExpiredError extends ErrorResponse.define(
 }
 
 /**
- * A passkey sign-in names an app, or reaches a realm, that holds no passkeys for Tempo ID, or no
- * passkeys whose relying party covers the app's page.
+ * A passkey sign-in or registration names an app, or reaches a realm, that holds no passkeys for
+ * Tempo ID, or no passkeys whose relying party covers the app's page.
  */
 export class NotPermittedError extends ErrorResponse.define(
   'passkey_not_permitted',
@@ -79,6 +79,12 @@ export class NotPermittedError extends ErrorResponse.define(
             error_description: `Passkey not permitted: the app ${clientId} holds no passkeys. Sign in with an emailed code.`,
             meta: { client_id: clientId },
           }
+        // A registration names no app, only the page that runs it.
+        if (origin)
+          return {
+            error_description: `Passkey not permitted: no realm holds passkeys for ${origin}. Serve the page on the domain of the relying party, or one of its subdomains.`,
+            meta: { origin },
+          }
         return {
           error_description:
             'Passkey not permitted: no realm holds passkeys for this sign-in. Sign in with an emailed code.',
@@ -113,6 +119,32 @@ export class ReauthenticationRequiredError extends ErrorResponse.define(
   }
 }
 
+/**
+ * A passkey registration comes from an app's page, and no app at the page's origin holds the
+ * `tempo-id:sign` scope. A registered passkey signs in as the user, so only an app that the
+ * deployment trusts with its own challenges registers one.
+ */
+export class RegisterNotPermittedError extends ErrorResponse.define(
+  'passkey_register_not_permitted',
+) {
+  override readonly name = 'Passkey.RegisterNotPermittedError'
+
+  constructor(options: RegisterNotPermittedError.Options) {
+    const { origin } = options
+    super({
+      error_description: `Passkey registration not permitted: no app at ${origin} holds the \`${Apps.signScope}\` scope. Register the passkey on Tempo ID, or grant the app the scope.`,
+      meta: { origin, scope: Apps.signScope },
+    })
+  }
+}
+
+export declare namespace RegisterNotPermittedError {
+  type Options = {
+    /** The origin of the app's page that sent the request. */
+    origin: string
+  }
+}
+
 /**
  * A passkey ceremony failed: its challenge is unknown, spent, or expired, or the response does not
  * verify. One refusal covers every case, so it reveals neither which check failed nor whether a
@@ -186,6 +218,10 @@ export type ProofChallenge = {
   challenge: Hex.Hex
   /** The credential ID of the new passkey, base64url. */
   id: string
+  /**
+   * The origin of the app's page that the ceremony runs at, or `undefined` for Tempo ID's own page.
+   */
+  origin: string | undefined
   /** The public key that the attestation holds, which the proof must verify against. */
   publicKey: Hex.Hex
   /** The relying party of the `default` realm, which the new passkey belongs to. */
@@ -196,6 +232,10 @@ export type ProofChallenge = {
 export type RegistrationChallenge = {
   /** The challenge, as hex. */
   challenge: Hex.Hex
+  /**
+   * The origin of the app's page that the ceremony runs at, or `undefined` for Tempo ID's own page.
+   */
+  origin: string | undefined
   /** The relying party of the `default` realm, which the new passkey must belong to. */
   rpId: string
 }
@@ -311,7 +351,7 @@ export namespace schema {
             .optional()
             .meta({
               description:
-                'The character offset of `"challenge"` in `clientDataJSON`. Absent, verification searches for it.',
+                'The character offset of `"challenge"` in `clientDataJSON`. Absent to search for it.',
               examples: [23],
             }),
           clientDataJSON: z
@@ -331,7 +371,7 @@ export namespace schema {
             .optional()
             .meta({
               description:
-                'The character offset of `"type"` in `clientDataJSON`. Absent, verification searches for it.',
+                'The character offset of `"type"` in `clientDataJSON`. Absent to search for it.',
               examples: [1],
             }),
           userVerificationRequired: z
@@ -339,13 +379,12 @@ export namespace schema {
             .optional()
             .meta({
               description:
-                'Whether the client required user verification. Verification ignores it and always requires user verification.',
+                'Whether the client required user verification. Ignored, since Tempo ID always requires it.',
               examples: [true],
             }),
         })
         .meta({
-          description:
-            'The signed data that verification reads with `signature`, decoded from the browser response.',
+          description: "The signed data, decoded from the browser's response.",
         }),
       raw: z
         .object({
@@ -355,7 +394,7 @@ export namespace schema {
             .default(null)
             .meta({
               description:
-                'How the authenticator attaches to the client, such as `platform` or `cross-platform`. Defaults to `null` when the browser reports none.',
+                'How the authenticator connects, such as `platform` or `cross-platform`, or `null`.',
               examples: ['platform'],
             }),
           id: base64url.meta({
@@ -379,7 +418,7 @@ export namespace schema {
             })
             .meta({
               description:
-                "The authenticator's response. Verification keeps only `clientDataJSON` and drops other fields.",
+                "The authenticator's response, of which Tempo ID reads only `clientDataJSON`.",
             }),
           type: z.string().meta({
             description: 'The credential type.',
@@ -399,7 +438,8 @@ export namespace schema {
       }),
     })
     .meta({
-      description: 'The assertion, serialized as `webauthx/client` returns it.',
+      description:
+        'The result of `navigator.credentials.get()`, as `webauthx/client` serializes it.',
       id: 'PasskeyAssertion',
     })
 
@@ -433,7 +473,7 @@ export namespace schema {
         .templateLiteral(['0x', z.string().regex(/^04[0-9a-fA-F]{128}$/)])
         .meta({
           description:
-            "The new passkey's uncompressed P256 public key, as hex. Verification reads the key from `attestationObject` and ignores this copy.",
+            "The new passkey's uncompressed P256 public key, as hex. Ignored, since Tempo ID reads the key from `attestationObject`.",
           examples: [
             '0x04f6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c6c3f1e0a9b7d24f58e1c3a6b9d0f2e4a7c5b8d1e3f6a9c2b4d7e0f1a3c5b8d',
           ],
@@ -446,7 +486,7 @@ export namespace schema {
             .default(null)
             .meta({
               description:
-                'How the authenticator attaches to the client, such as `platform` or `cross-platform`. Defaults to `null` when the browser reports none.',
+                'How the authenticator connects, such as `platform` or `cross-platform`, or `null`.',
               examples: ['platform'],
             }),
           id: base64url.max(1364).meta({
@@ -471,7 +511,7 @@ export namespace schema {
             })
             .meta({
               description:
-                "The authenticator's response. Verification keeps only `clientDataJSON`, and reads the top-level `attestationObject`.",
+                "The authenticator's response, of which Tempo ID reads only `clientDataJSON`.",
             }),
           type: z
             .string()
@@ -488,7 +528,7 @@ export namespace schema {
     })
     .meta({
       description:
-        'The new passkey, serialized as `webauthx/client` returns it.',
+        'The result of `navigator.credentials.create()`, as `webauthx/client` serializes it.',
       id: 'PasskeyCredential',
     })
 
@@ -510,12 +550,16 @@ export namespace schema {
   /** A proof challenge's `verification` value. */
   export const proof = z.object({
     id: z.string(),
+    // A challenge without an origin runs at Tempo ID's own page.
+    origin: z.string().optional(),
     publicKey: hex,
     rpId: z.string(),
   })
 
   /** A registration challenge's `verification` value. */
   export const registration = z.object({
+    // A challenge without an origin runs at Tempo ID's own page.
+    origin: z.string().optional(),
     rpId: z.string(),
   })
 
@@ -558,11 +602,11 @@ export 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 key authorization's digest, as hex. It is single-use, and expires after 5 minutes.",
+                      "The key authorization's digest, as hex, which expires after 5 minutes.",
                     examples: [
                       '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
                     ],
@@ -574,30 +618,29 @@ export 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 passkey, then repeat the approval 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 over the key authorization's digest.",
+            "The next step: the passkey's signature of the key authorization.",
         }),
     })
     .meta({
-      description:
-        'An approval that continues when the passkey signs the key authorization.',
+      description: 'An approval that waits for the passkey to sign the key.',
       id: 'PasskeyStep',
     })
 
@@ -609,24 +652,24 @@ export namespace schema {
         .int()
         .meta({
           description:
-            "The key's expiry in Unix seconds. The repeated request sends it as `key_authorization.expiry`, so the digest stays the same.",
+            "The key's expiry, in Unix seconds. Send it as `key_authorization.expiry` in the repeat, so the digest stays the same.",
           examples: [1791869364],
         }),
       step: step.shape.step
         .extend({
           type: z.literal('passkey').meta({
             description:
-              'Sign the options with the passkey on the page, then repeat `POST /v1/authorize` with `passkey: { assertion }`.',
+              'Sign the challenge with the passkey, then repeat `POST /v1/authorize` with `passkey: { assertion }`.',
           }),
         })
         .meta({
           description:
-            "The next step: the passkey's signature over the key authorization's digest.",
+            "The next step: the passkey's signature of the key authorization.",
         }),
     })
     .meta({
       description:
-        "A headless authorization that continues when the passkey that owns the account signs the key authorization on the app's page.",
+        "A headless authorization that waits for the account's passkey to sign the key.",
       id: 'HeadlessPasskeyStep',
     })
 
@@ -1167,7 +1210,7 @@ export async function requestProof(
   db: Realm.Database,
   options: requestProof.Options,
 ) {
-  const { credential, rpId, userId } = options
+  const { credential, origin, rpId, userId } = options
   const challenge = Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32)))
   await db.insert(Schema.verification).values({
     expiresAt: new Date(Date.now() + lifetime * 1000),
@@ -1177,7 +1220,7 @@ export async function requestProof(
       prefix: proofPrefix,
       userId,
     }),
-    value: JSON.stringify(schema.proof.parse({ ...credential, rpId })),
+    value: JSON.stringify(schema.proof.parse({ ...credential, origin, rpId })),
   })
   return challenge
 }
@@ -1191,6 +1234,11 @@ export declare namespace requestProof {
       /** The uncompressed P256 public key that the attestation holds, hex. */
       publicKey: Hex.Hex
     }
+    /**
+     * The origin of the app's page that the ceremony runs at. Absent for Tempo ID's own page. Only
+     * an assertion that reports it, from a request that page sends, spends the challenge.
+     */
+    origin?: string | undefined
     /** The relying party of the `default` realm, which the new passkey belongs to. */
     rpId: string
     /** The signed-in user's ID. */
@@ -1215,13 +1263,23 @@ export async function requestRegistration(
       prefix: registrationPrefix,
       userId: options.userId,
     }),
-    value: JSON.stringify(schema.registration.parse({ rpId: options.rpId })),
+    value: JSON.stringify(
+      schema.registration.parse({
+        origin: options.origin,
+        rpId: options.rpId,
+      }),
+    ),
   })
   return challenge
 }
 
 export declare namespace requestRegistration {
   type Options = {
+    /**
+     * The origin of the app's page that the ceremony runs at. Absent for Tempo ID's own page. Only
+     * a credential that reports it, from a request that page sends, spends the challenge.
+     */
+    origin?: string | undefined
     /** The relying party of the `default` realm, which the new passkey must belong to. */
     rpId: string
     /** The signed-in user's ID. */
@@ -1487,7 +1545,14 @@ export async function takeProof(
     .returning({ value: Schema.verification.value })
   if (!row) return undefined
 
-  return { ...schema.proof.parse(JSON.parse(row.value)), challenge }
+  const value = schema.proof.parse(JSON.parse(row.value))
+  return {
+    challenge,
+    id: value.id,
+    origin: value.origin,
+    publicKey: value.publicKey,
+    rpId: value.rpId,
+  }
 }
 
 export declare namespace takeProof {
@@ -1540,7 +1605,7 @@ export async function takeRegistration(
   if (!row) return undefined
 
   const value = schema.registration.parse(JSON.parse(row.value))
-  return { challenge, rpId: value.rpId }
+  return { challenge, origin: value.origin, rpId: value.rpId }
 }
 
 export declare namespace takeRegistration {
@@ -1896,7 +1961,7 @@ export declare namespace verifyRegistration {
   type Options = {
     /** The registration challenge that Tempo ID issued, as hex. */
     challenge: Hex.Hex
-    /** The origin the ceremony must report: Tempo ID's own. */
+    /** The origin the ceremony must report: Tempo ID's own, or the app's page that the challenge names. */
     origin: string
     /** The relying party ID the challenge was issued for. */
     rpId: string

package/src/internal/Privy.ts

@@ -10,8 +10,10 @@ import { createViemAccount } from '@privy-io/node/viem'
 import { createMiddleware } from 'hono/factory'
 import { Base64 } from 'ox'
 import { Account } from 'viem/tempo'
+import { z } from 'zod'
 import type { Env } from './Env.js'
 import * as ErrorResponse from './ErrorResponse.js'
+import * as Log from './Log.js'
 import * as Timing from './Timing.js'
 
 /** No `PRIVY_JWT_PRIVATE_KEY` is set, so Tempo ID cannot sign as a Privy wallet. */
@@ -28,6 +30,20 @@ export class SigningKeyMissingError extends Error {
 /** How long a token for Privy lasts, in seconds: long enough for one signing request. */
 const tokenLifetime = 60
 
+/** The name of the Cache API cache that holds users' Privy wallets, as {@link cachedWallets} reads them. */
+const walletCache = 'privy-wallets'
+
+/** Zod schemas for the wallets that {@link cachedWallets} stores. */
+namespace schema {
+  export const wallets = z.array(
+    z.object({
+      address: z.templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]{40}$/)]),
+      createdAt: z.coerce.date(),
+      id: z.string().min(1),
+    }),
+  )
+}
+
 /** A realm's Privy app, which holds the owner wallets of the realm's Privy-owned accounts. */
 export type App = {
   /** The Privy app ID. */
@@ -68,6 +84,101 @@ export type Wallet = {
   id: string
 }
 
+/**
+ * Returns the user's Privy wallets in `app`, as {@link listWallets} does, from the data center's
+ * cache when a read in the last `maxAge` seconds stored them. A read from Privy that finds a wallet
+ * stores its result, so a later wallet that Privy creates elsewhere appears within `maxAge`. A user
+ * without a wallet is never stored, so a first wallet appears in the next read. The cache holds each wallet's address, ID, and creation time, never the
+ * app secret. Without the Cache API, as in the CLI, every call reads Privy.
+ */
+export async function cachedWallets(
+  c: Context,
+  options: cachedWallets.Options,
+): Promise<readonly Wallet[]> {
+  if (typeof caches === 'undefined') return await listWallets(c, options)
+  const key = cacheKey(options)
+  const { warn = Log.warn } = options
+
+  // The cache only saves reads of Privy, so a failure of it falls back to Privy.
+  const cached = await (async () => {
+    try {
+      const cache = await Timing.measure(
+        c,
+        caches.open(walletCache),
+        'cache.privyWallets.open',
+      )
+      const hit = await Timing.measure(
+        c,
+        cache.match(key),
+        'cache.privyWallets.match',
+      )
+      if (!hit) return { cache, wallets: undefined }
+      const parsed = schema.wallets.safeParse(
+        await Timing.measure(c, hit.json(), 'cache.privyWallets.read'),
+      )
+      return { cache, wallets: parsed.success ? parsed.data : undefined }
+    } catch (error) {
+      warn({
+        error,
+        message:
+          'A read of the cached Privy wallets failed, so Privy was read.',
+      })
+      return undefined
+    }
+  })()
+  if (cached?.wallets) return cached.wallets
+
+  const wallets = await listWallets(c, options)
+  // A user without a wallet stays uncached, so the read after Tempo ID creates their first wallet,
+  // the only wallet that Tempo ID creates, asks Privy again. A read in flight during the creation
+  // thus stores no stale empty list.
+  if (wallets.length === 0 || !cached) return wallets
+  const stored = Timing.measure(
+    c,
+    cached.cache
+      .put(
+        key,
+        new Response(JSON.stringify(wallets), {
+          headers: {
+            'cache-control': `max-age=${options.maxAge}`,
+            'content-type': 'application/json',
+          },
+        }),
+      )
+      .catch((error: unknown) => {
+        warn({
+          error,
+          message: 'A store of the Privy wallets in the cache failed.',
+        })
+      }),
+    'cache.privyWallets.put',
+  )
+  // The store only serves later reads, so with `waitUntil` the wallets return before it settles.
+  if (options.waitUntil) options.waitUntil(stored)
+  else await stored
+  return wallets
+}
+
+export namespace cachedWallets {
+  export type Options = listWallets.Options & {
+    /** How old, in seconds, a cached read may be. */
+    maxAge: number
+    /**
+     * Keeps the store in the cache alive after the response, such as `c.executionCtx.waitUntil`,
+     * so the wallets return before it settles. Absent, the call waits for the store.
+     */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+    /**
+     * Logs a failure of the cache with the request's details, such as `Log.warn` with the request's
+     * context. Defaults to `Log.warn` without them.
+     */
+    warn?: ((options: Log.Options) => void) | undefined
+  }
+
+  /** The refusals `cachedWallets` throws, which `ErrorResponse.handle` responds with: Privy's failures. */
+  export const errors = listWallets.errors
+}
+
 /**
  * Records that the request created the user with `userId`, so the request reads no Privy user for
  * them from Privy. Privy keys each user by the user's ID, and no Privy app holds a new ID before
@@ -463,6 +574,23 @@ function inProgress(error: unknown) {
   )
 }
 
+/**
+ * Returns the Cache API key of the wallets of the user with `userId` in `app`. The key names the app
+ * by its ID alone, never its secret, on a host that serves nothing.
+ */
+function cacheKey(options: cacheKey.Options) {
+  return `https://privy-wallets.tempo-id.invalid/${encodeURIComponent(options.app.appId)}/${encodeURIComponent(options.userId)}`
+}
+
+declare namespace cacheKey {
+  type Options = {
+    /** The Privy app that holds the user. */
+    app: App
+    /** The user's ID. */
+    userId: string
+  }
+}
+
 /**
  * Returns the key of the user with `userId` in `app`, in the request's {@link Users}. Without `app`,
  * the key marks a user that the request created.