@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/actions/oauth.ts

@@ -0,0 +1,179 @@
+/**
+ * Calls Tempo ID's standard OAuth endpoints for tokens that an app holds.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+import type { User } from '../User.js'
+
+/**
+ * Checks whether a token is active (RFC 7662). Unlike local verification against {@link jwks}, it
+ * reports a revoked token inactive at once. The client secret authenticates the request, so only a
+ * backend calls it.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.oauth.introspect(auth, { token: accessToken })
+ * if (!result.active) return c.json({ error: 'Sign in again.' }, 401)
+ * ```
+ */
+export async function introspect(
+  auth: Auth,
+  options: introspect.Options,
+): Promise<introspect.ReturnType> {
+  const { token, tokenTypeHint } = options
+  const body = await Api.json<{
+    active: boolean
+    client_id?: string | undefined
+    exp?: number | undefined
+    iat?: number | undefined
+    scope?: string | undefined
+    sub?: string | undefined
+  }>(
+    await (auth.fetch ?? fetch)(new URL('/oauth2/introspect', auth.url), {
+      body: new URLSearchParams({
+        client_id: auth.clientId,
+        ...(auth.clientSecret ? { client_secret: auth.clientSecret } : {}),
+        token,
+        ...(tokenTypeHint ? { token_type_hint: tokenTypeHint } : {}),
+      }),
+      method: 'POST',
+    }),
+  )
+  // An inactive token carries no other members (RFC 7662 §2.2).
+  if (!body.active) return { active: false }
+  return {
+    active: true,
+    clientId: body.client_id,
+    expiresAt: body.exp === undefined ? undefined : body.exp * 1000,
+    issuedAt: body.iat === undefined ? undefined : body.iat * 1000,
+    scope: body.scope,
+    userId: body.sub,
+  }
+}
+
+export declare namespace introspect {
+  type Options = {
+    /** The access token or refresh token to check. */
+    token: string
+    /** The kind of token, which speeds up the lookup. */
+    tokenTypeHint?: 'access_token' | 'refresh_token' | undefined
+  }
+
+  /** Whether the token is active, with the issuer's claims about an active one. */
+  type ReturnType =
+    | {
+        /** The token is expired, revoked, or never issued. */
+        active: false
+      }
+    | {
+        /** The token is active. */
+        active: true
+        /** The app the token was issued to. */
+        clientId: string | undefined
+        /** When the token expires, in milliseconds. */
+        expiresAt: number | undefined
+        /** When the token was issued, in milliseconds. */
+        issuedAt: number | undefined
+        /** The token's scopes, space-separated. */
+        scope: string | undefined
+        /** The user that the token names, as its `sub`. */
+        userId: string | undefined
+      }
+}
+
+/**
+ * Returns the issuer's JSON Web Key Set, whose keys verify every Tempo ID token. A key rotation
+ * signs with a new key, so fetch the set again for an unknown `kid`, at most once in a cooldown.
+ * jose's `createRemoteJWKSet` does this from the `/oauth2/jwks` URL.
+ *
+ * @example
+ * ```ts
+ * import { createLocalJWKSet, errors, jwtVerify } from 'jose'
+ *
+ * let keys = createLocalJWKSet(await Actions.oauth.jwks(auth))
+ * let fetchedAt = Date.now()
+ * let refetch: Promise<void> | undefined
+ *
+ * async function verify(accessToken: string) {
+ *   try {
+ *     return await jwtVerify(accessToken, keys, { audience, issuer })
+ *   } catch (error) {
+ *     if (!(error instanceof errors.JWKSNoMatchingKey)) throw error
+ *     // Concurrent failures share one fetch. The cooldown bounds fetches for forged `kid` values.
+ *     if (!refetch) {
+ *       if (Date.now() - fetchedAt < 30_000) throw error
+ *       fetchedAt = Date.now()
+ *       refetch = Actions.oauth
+ *         .jwks(auth)
+ *         .then((set) => {
+ *           keys = createLocalJWKSet(set)
+ *         })
+ *         .finally(() => {
+ *           refetch = undefined
+ *         })
+ *     }
+ *     await refetch
+ *     return await jwtVerify(accessToken, keys, { audience, issuer })
+ *   }
+ * }
+ *
+ * const { payload } = await verify(accessToken)
+ * // Every app's token carries the same audience, so allow each app by its `client_id`.
+ * if (!allowedClientIds.includes(String(payload.client_id))) throw forbidden()
+ * ```
+ */
+export async function jwks(auth: Auth): Promise<jwks.ReturnType> {
+  return Api.json<jwks.ReturnType>(
+    await (auth.fetch ?? fetch)(new URL('/oauth2/jwks', auth.url)),
+  )
+}
+
+export declare namespace jwks {
+  /** The key set, in RFC 7517's format. */
+  type ReturnType = {
+    /** The issuer's signing keys. */
+    keys: JsonWebKey[]
+  }
+}
+
+/**
+ * Returns the user that an access token names, from the UserInfo endpoint (OIDC Core §5.3). Access
+ * tokens carry no email, so an API that needs it calls this once per user. Throws `invalid_token`
+ * for a rejected token.
+ *
+ * @example
+ * ```ts
+ * const user = await Actions.oauth.userInfo(auth, { accessToken })
+ * // { email: 'user@example.com', id: 'user_…' }
+ * ```
+ */
+export async function userInfo(
+  auth: Auth,
+  options: userInfo.Options,
+): Promise<User> {
+  const response = await (auth.fetch ?? fetch)(
+    new URL('/oauth2/userinfo', auth.url),
+    { headers: { authorization: `Bearer ${options.accessToken}` } },
+  )
+  // RFC 6750 §3 names a rejected bearer token `invalid_token`. The issuer's 401 body uses its own
+  // code, or none, so the refusal always carries the standard one.
+  if (response.status === 401)
+    throw Api.error(
+      {
+        error: 'invalid_token',
+        error_description:
+          'Invalid or expired access token. Refresh the tokens, or sign in again.',
+      },
+      { status: 401 },
+    )
+  const claims = await Api.json<{ email: string; sub: string }>(response)
+  return { email: claims.email, id: claims.sub }
+}
+
+export declare namespace userInfo {
+  type Options = {
+    /** An access token, from any sign-in or refresh. */
+    accessToken: string
+  }
+}

package/src/client/actions/passkey.ts

@@ -0,0 +1,333 @@
+/**
+ * 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.
+ * @module
+ */
+import { Authentication, type Types } from 'ox/webauthn'
+import type { Account } from 'viem/tempo'
+import { type Auth, ChallengeWithoutKeyError } from '../Auth.js'
+import type { Authorization } from '../Authorization.js'
+import type * as AccessKey from '../internal/accessKey.js'
+import * as Api from '../internal/api.js'
+import * as Headless from '../internal/headless.js'
+import type { Permissions } from '../Permissions.js'
+
+/**
+ * Returns whether a passkey sign-in for the app runs on this page, from `GET /v1/realms`: the page
+ * is on one of the app's redirect URI origins, and a realm's passkeys cover the page and Tempo ID.
+ * The handle of {@link prepare} requests options only where it returns `true`, so no options request
+ * fails. Returns `false` from a server that does not report it, and where the browser cannot read
+ * the response, such as on a page of no first-party app, which receives no CORS grant.
+ *
+ * @example
+ * ```ts
+ * if (await Actions.passkey.available(auth)) showPasskeyButton()
+ * ```
+ */
+export async function available(auth: Auth): Promise<boolean> {
+  const response = await (auth.fetch ?? fetch)(
+    new URL(
+      `/v1/realms?${new URLSearchParams({ client_id: auth.clientId })}`,
+      auth.url,
+    ),
+  ).catch(() => undefined)
+  // The browser refuses a response without a CORS grant, as to a page of no first-party app, where
+  // the options request would fail too.
+  if (!response) return false
+  const { passkeys } = await Api.json<{ passkeys?: boolean | undefined }>(
+    response,
+  )
+  return passkeys === true
+}
+
+/**
+ * How long a sign-in uses prepared options, in milliseconds: a minute short of the 5 minutes that
+ * their challenge lasts, so the challenge stays valid through the ceremony.
+ */
+const preparedLifetime = 4 * 60 * 1000
+
+/**
+ * Prepares a passkey sign-in before the user acts, such as when the sign-in form shows, and
+ * returns its handle. The handle checks {@link available}, and where it returns `true`, requests
+ * the sign-in's options and the key that it authorizes, so the handle's `signIn` starts the
+ * ceremony without a request. Create a new handle when the request options change.
+ *
+ * The handle owns its options. A sign-in uses them once, and requests new ones after 4 minutes.
+ * A ceremony that the user cancels leaves them unspent for the next sign-in. A sign-in that sends
+ * its assertion spends their challenge, so after a refusal the handle prepares new options.
+ *
+ * `prepare` never throws, and a failed request leaves no options. The handle's `signIn` then
+ * requests them, and throws what {@link signIn} throws.
+ *
+ * @example
+ * ```ts
+ * // Once the sign-in form shows:
+ * const passkey = Actions.passkey.prepare(auth, { permissions })
+ * if (await passkey.available) showPasskeyButton()
+ * // On the passkey button:
+ * const result = await passkey.signIn()
+ * ```
+ */
+export function prepare<
+  const chainId extends number = number,
+  const key extends boolean = true,
+>(
+  auth: Auth,
+  options: prepare.Options<chainId, key> = {},
+): prepare.ReturnType<chainId, key> {
+  const ready = available(auth).catch(() => false)
+  // Requests options only where passkeys sign in, so no request fails on a page without them.
+  const ahead = () =>
+    ready
+      .then((passkeys) =>
+        passkeys ? requestOptions(auth, options) : undefined,
+      )
+      .catch(() => undefined)
+  let pending: Promise<Prepared | undefined> | undefined = ahead()
+
+  return {
+    available: ready,
+    async signIn(signInOptions = {}) {
+      // Takes the options before the first await, so a sign-in that starts beside this one
+      // requests options of its own instead of the same challenge.
+      const taken = pending
+      pending = undefined
+      const entry = await taken
+      const prepared =
+        entry && entry.expiresAt > Date.now()
+          ? entry
+          : await requestOptions(auth, options)
+      const assertion = await sign(prepared, signInOptions).catch(
+        (error: unknown) => {
+          // The ceremony sent no assertion, so the challenge is unspent for the next sign-in.
+          pending ??= Promise.resolve(prepared)
+          throw error
+        },
+      )
+      return (await verify(auth, { assertion, prepared }).catch(
+        (error: unknown) => {
+          pending ??= ahead()
+          throw error
+        },
+      )) as signIn.ReturnType<chainId, key>
+    },
+  }
+}
+
+export declare namespace prepare {
+  type Options<chainId extends number = number, key extends boolean = true> = {
+    /**
+     * The key to authorize. Defaults to a new key. Its `access` names the Tempo Account, which
+     * defaults to the app's selected account, or the user's oldest.
+     */
+    accessKey?: Account.Account | undefined
+    /**
+     * A message whose EIP-191 hash the key authorization binds as its `witness`. Needs the
+     * `tempo-id:sign` scope and a key.
+     */
+    challenge?: ([key] extends [false] ? never : string) | undefined
+    /**
+     * The credential ID, or up to 16 IDs, that the browser offers. Each is unpadded base64url of 1
+     * to 1,023 bytes, or the call throws `invalid_field`. Defaults to every passkey.
+     */
+    credentialId?: readonly string[] | string | undefined
+    /** The browser's mediation, such as `conditional` for autofill. Defaults to its own. */
+    mediation?: 'conditional' | 'optional' | 'required' | 'silent' | undefined
+    /** Whether to authorize an access key and create a first Tempo Account. Defaults to `true`. */
+    key?: key | undefined
+    /** What the key may do, within the headless ceiling. */
+    permissions?: Permissions<chainId> | undefined
+  }
+
+  /** The prepared sign-in's handle. */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > = {
+    /** Whether a passkey sign-in runs on this page, as {@link available} returns. Never rejects. */
+    available: Promise<boolean>
+    /**
+     * Signs in as {@link signIn} does, with the handle's options. Requests new options if the
+     * handle holds none, or if they are older than 4 minutes.
+     */
+    signIn: (
+      options?: SignInOptions,
+    ) => Promise<signIn.ReturnType<chainId, key>>
+  }
+
+  /** The options of the handle's `signIn`. */
+  type SignInOptions = Pick<signIn.Options, 'getFn'>
+}
+
+/**
+ * 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.
+ *
+ * Returns an email step for a wallet.tempo passkey whose account has no email. Pass its `link` to
+ * `Actions.email.signIn`.
+ *
+ * A page off the app's redirect URI origins throws `invalid_origin`, and one that the realms'
+ * relying party does not cover throws `passkey_not_permitted`. A refusal after the passkey verified
+ * has `signedIn: true`. An account that another passkey owns throws `webauthn_required`, so
+ * authorize through `Actions.redirect.start`.
+ *
+ * A wallet.tempo passkey's account that waits for its upgrade signs the key as the passkey's own
+ * account, and `upgradeAvailable` is `true`. `Actions.account.upgrade` with the key then upgrades
+ * the account with one more prompt, after Tempo ID registers the key.
+ *
+ * It requests the sign-in's options when called. {@link prepare} requests them before the user
+ * acts instead.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.passkey.signIn(auth)
+ * if ('step' in result) showEmailForm()
+ * ```
+ */
+export async function signIn<
+  const chainId extends number = number,
+  const key extends boolean = true,
+>(
+  auth: Auth,
+  options: signIn.Options<chainId, key> = {},
+): Promise<signIn.ReturnType<chainId, key>> {
+  const prepared = await requestOptions(auth, options)
+  const assertion = await sign(prepared, options)
+  // `key` decides both the type and the runtime value of the result.
+  return (await verify(auth, { assertion, prepared })) as signIn.ReturnType<
+    chainId,
+    key
+  >
+}
+
+export declare namespace signIn {
+  type Options<
+    chainId extends number = number,
+    key extends boolean = true,
+  > = prepare.Options<chainId, key> & {
+    /**
+     * Runs the WebAuthn ceremony in place of `navigator.credentials.get`. Its assertion must report
+     * the page's origin, so Tempo ID refuses an Android facet origin.
+     */
+    getFn?: Authentication.sign.Options['getFn'] | undefined
+  }
+
+  /** The step of a wallet.tempo passkey without an email: an emailed code links it. */
+  type EmailStep = {
+    /** The `link` that `Actions.email.signIn` takes to link the passkey to its user. */
+    link: string
+    /** The kind of step. */
+    type: 'email'
+  }
+
+  /** The authorization, without its key for `key: false`, and whether its account can upgrade, or the email step. */
+  type ReturnType<
+    chainId extends number = number,
+    key extends boolean = true,
+  > =
+    | {
+        /** The authorization, without its key for `key: false`. */
+        authorization: key extends false
+          ? Omit<Authorization<chainId>, 'account' | 'key'>
+          : Authorization<chainId>
+        /**
+         * Whether the key's account is a wallet.tempo passkey's that waits for its upgrade on the
+         * key's chain. `Actions.account.upgrade` with the key upgrades it, and keeps the key.
+         */
+        upgradeAvailable: boolean
+      }
+    | {
+        /** The email step, which comes before the authorization. */
+        step: EmailStep
+      }
+}
+
+/** 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. */
+  authorize: Awaited<ReturnType<typeof Headless.prepare>>['authorize']
+  /** When a sign-in stops using the options, in milliseconds since the epoch. */
+  expiresAt: number
+  /** The key that the options authorize. Absent for `key: false`. */
+  key: AccessKey.resolve.ReturnType | undefined
+  /** The options of the WebAuthn ceremony, with Tempo ID's challenge. */
+  options: Types.CredentialRequestOptions
+  /** The request options, which the authorization reads once the passkey verifies. */
+  request: prepare.Options<number, boolean>
+}
+
+/**
+ * Requests the options of a passkey sign-in, and the key that they authorize.
+ * @throws {ChallengeWithoutKeyError} For a challenge with `key: false`, before any request.
+ */
+async function requestOptions(
+  auth: Auth,
+  options: prepare.Options<number, boolean>,
+): Promise<Prepared> {
+  const { credentialId, mediation } = options
+  // A challenge rides in the key, so a sign-in without one refuses it before it signs in.
+  if (options.key === false && options.challenge !== undefined)
+    throw new ChallengeWithoutKeyError()
+  // The options carry the authorization request, so the challenge is its key's digest.
+  const { authorize, key } = await Headless.prepare(auth, options)
+  // The challenge's lifetime starts at Tempo ID before the response arrives, so the options' does too.
+  const requestedAt = Date.now()
+  const requested = await Api.json<{
+    options: Types.CredentialRequestOptions<true>
+  }>(
+    await Api.post(auth, '/v1/auth/passkey/options', {
+      json: {
+        authorize,
+        // The app's realms decide the relying party, which must cover the page's origin.
+        client_id: auth.clientId,
+        ...(credentialId === undefined ? {} : { credentialId }),
+        ...(mediation === undefined ? {} : { mediation }),
+      },
+    }),
+  )
+  return {
+    authorize,
+    expiresAt: requestedAt + preparedLifetime,
+    key,
+    options: Authentication.deserializeOptions(requested.options),
+    request: options,
+  }
+}
+
+/** Runs the WebAuthn ceremony over the prepared options, and returns the serialized assertion. */
+async function sign(prepared: Prepared, options: prepare.SignInOptions) {
+  const { getFn } = options
+  return Authentication.serializeResponse(
+    await Authentication.sign(
+      // ox reads `getFn` beside request options at runtime, which its types admit only beside a challenge.
+      getFn ? ({ ...prepared.options, getFn } as never) : prepared.options,
+    ),
+  )
+}
+
+/** Sends the assertion, and returns the authorization, or the email step of a passkey without one. */
+async function verify(auth: Auth, options: verify.Options) {
+  const { assertion, prepared } = options
+  const body = await Headless.read<
+    | { authorization?: Api.Headless | undefined; user: { id: string } }
+    | { step: signIn.EmailStep }
+  >(await Api.post(auth, '/v1/auth/passkey/verify', { json: { assertion } }))
+  if ('step' in body)
+    return { step: { link: body.step.link, type: body.step.type } }
+  return await Headless.complete(auth, {
+    authorize: prepared.authorize,
+    body,
+    key: prepared.key,
+    request: prepared.request,
+  })
+}
+
+declare namespace verify {
+  type Options = {
+    /** The serialized assertion over the prepared options' challenge. */
+    assertion: ReturnType<typeof Authentication.serializeResponse>
+    /** The options that the assertion signed. */
+    prepared: Prepared
+  }
+}

package/src/client/actions/realm.ts

@@ -0,0 +1,37 @@
+/**
+ * Lists the realms that the app reaches.
+ * @module
+ */
+import type { Auth } from '../Auth.js'
+import * as Api from '../internal/api.js'
+
+/**
+ * Lists the realms that the app reaches, in its settings' order. The first holds a user's first
+ * account.
+ *
+ * @example
+ * ```ts
+ * const realms = await Actions.realm.list(auth)
+ * // [{ id: 'default', name: 'Tempo' }]
+ * ```
+ */
+export async function list(auth: Auth): Promise<list.ReturnType> {
+  const { realms } = await Api.json<{ realms: list.ReturnType }>(
+    await (auth.fetch ?? fetch)(
+      new URL(
+        `/v1/realms?${new URLSearchParams({ client_id: auth.clientId })}`,
+        auth.url,
+      ),
+    ),
+  )
+  return realms
+}
+
+export declare namespace list {
+  type ReturnType = readonly {
+    /** The realm ID, such as `default` or `tempo-cash`. */
+    id: string
+    /** The display name, such as `Tempo Cash`. */
+    name: string
+  }[]
+}