@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Authorize.ts

@@ -0,0 +1,433 @@
+/**
+ * Authorization requests that carry a key authorization. A first-party web app's page authorizes
+ * headlessly, within the headless ceiling. Any other app authorizes through a redirect, whose
+ * `/authorize` query carries the key to the approval page.
+ * @module
+ */
+import { Base64 } from 'ox'
+import { z } from 'zod'
+import * as Apps from './Apps.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as KeyAuthorization from './KeyAuthorization.js'
+import * as Validation from './Validation.js'
+
+/** A headless request came from an origin that its redirect URI does not allow. */
+export class InvalidOriginError extends ErrorResponse.define('invalid_origin') {
+  override readonly name = 'Authorize.InvalidOriginError'
+}
+
+/** The request names no registered app or redirect URI, or the app may not authorize headlessly. */
+export class RejectedError extends ErrorResponse.define('rejected') {
+  override readonly name = 'Authorize.RejectedError'
+
+  constructor(options: RejectedError.Options = {}) {
+    super({
+      error_description:
+        options.description ??
+        "Authorization request rejected. Check `client_id`, `redirect_uri`, and `scope` against the app's registration.",
+    })
+  }
+}
+
+export declare namespace RejectedError {
+  type Options = {
+    /** Replaces the default `error_description`. */
+    description?: string | undefined
+  }
+}
+
+/** Zod schemas for headless authorization requests and their responses. */
+export namespace schema {
+  /** The tokens that a public app receives. */
+  export const tokens = z
+    .object({
+      access_token: z.string().meta({
+        description:
+          "The access token, a JWT that Tempo ID signs. APIs verify it against Tempo ID's JSON Web Key Set.",
+        examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.c2lnbmF0dXJl'],
+      }),
+      expires_in: z.number().meta({
+        description: 'Seconds until the access token expires.',
+        examples: [300],
+      }),
+      id_token: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The OIDC ID token, a JWT about the user. Absent when the request did not ask for the `openid` scope.',
+          examples: ['eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJhcHAifQ.c2lnbmF0dXJl'],
+        }),
+      refresh_token: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The refresh token, which the app redeems at `/oauth2/token` for new tokens. Absent without the `offline_access` scope.',
+          examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+        }),
+      token_type: z.string().meta({
+        description: 'The type of the access token (RFC 6749 §7.1).',
+        examples: ['Bearer'],
+      }),
+    })
+    .meta({ description: 'OAuth tokens for a public app.', id: 'Tokens' })
+
+  /** A message whose EIP-191 hash becomes a key authorization's witness. */
+  export const challenge = z
+    .string()
+    .min(1)
+    .max(1024)
+    .optional()
+    .meta({
+      description:
+        "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+      examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+    })
+
+  /** An app's headless authorization request. */
+  export const request = z
+    .object({
+      challenge,
+      client_id: z
+        .string()
+        .min(1)
+        .max(255)
+        .meta({
+          description: "The app's client ID.",
+          examples: ['Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK'],
+        }),
+      code_challenge: z
+        .string()
+        .regex(/^[\w-]{43}$/)
+        .optional()
+        .meta({
+          description:
+            "The S256 PKCE challenge of a verifier that the app's backend holds (RFC 7636). With one, the app receives a code, and without one, a public app receives tokens.",
+          examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'],
+        }),
+      key_authorization: KeyAuthorization.schema.request,
+      // Schemes that run script or read files are refused.
+      redirect_uri: z
+        .url({
+          protocol:
+            /^(?!(?:blob|data|file|javascript|vbscript)$)[a-z][a-z\d+.-]*$/,
+        })
+        .meta({
+          description:
+            'A registered redirect URI of a web app, whose origin the page calls from.',
+          examples: ['https://app.example.com/callback'],
+        }),
+      scope: z
+        .string()
+        .regex(/^[\w:.-]+( [\w:.-]+)*$/)
+        .max(256)
+        .optional()
+        .meta({
+          description: 'Space-separated OAuth scopes. Defaults to `openid`.',
+          examples: ['openid email offline_access'],
+        }),
+      skip_upgrade: z
+        .boolean()
+        .optional()
+        .meta({
+          description:
+            "Whether a wallet.tempo passkey's account that waits for its upgrade on the key's chain, where accounts are configurable, signs the key as the passkey's own account, in place of `upgrade_required`. It applies when a passkey signs in the same request, through a sign-in with key signature or `passkey`. The response then holds `upgrade_available`. The key stops working on that chain once the account upgrades, unless `POST /v1/account/upgrade` registers it first. Defaults to `false`.",
+          examples: [true],
+        }),
+      state: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .meta({
+          description:
+            'An opaque value that the response returns unchanged, to bind it to the request (RFC 6749 §4.1.1).',
+          examples: ['af0ifjsldkj'],
+        }),
+    })
+    .refine((request) => !request.challenge || request.key_authorization, {
+      message:
+        'A challenge requires `key_authorization`, whose witness binds it',
+      path: ['challenge'],
+    })
+    // The key carries the challenge as its witness, so the owner's signature binds it.
+    .transform((request) =>
+      request.key_authorization
+        ? {
+            ...request,
+            key_authorization: KeyAuthorization.bind(
+              request.key_authorization,
+              { challenge: request.challenge },
+            ),
+          }
+        : request,
+    )
+    .meta({
+      description: "An app's headless authorization request.",
+      id: 'AuthorizationRequest',
+    })
+
+  /** The key of a redirect's `/authorize` query, with its `challenge` bound as the witness. */
+  export const redirect = z
+    .object({ challenge, key_authorization: KeyAuthorization.schema.request })
+    .refine((request) => !request.challenge || request.key_authorization, {
+      message:
+        'A challenge requires `key_authorization`, whose witness binds it',
+      path: ['challenge'],
+    })
+    .transform((request) =>
+      request.key_authorization
+        ? KeyAuthorization.bind(request.key_authorization, {
+            challenge: request.challenge,
+          })
+        : undefined,
+    )
+
+  /** What a headless authorization returns: a code or tokens, with any signed key. */
+  export const response = z
+    .object({
+      account: KeyAuthorization.schema.account.optional(),
+      code: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The authorization code, when the request sent a `code_challenge`. The app's backend redeems it at `/oauth2/token`.",
+          examples: ['Vb7mQ2xLkP9sTzR4'],
+        }),
+      key_authorization: KeyAuthorization.schema.rpc.optional(),
+      state: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The request's `state`, unchanged. Absent when the request sent none.",
+          examples: ['af0ifjsldkj'],
+        }),
+      tokens: tokens.optional().meta({
+        description: 'The tokens, when the request sent no `code_challenge`.',
+      }),
+      upgrade_available: z.literal(true).optional().meta({
+        description:
+          "Present when `skip_upgrade` signed the key as a wallet.tempo passkey's own account, whose upgrade waits on the key's chain. `POST /v1/account/upgrade` with the key registers it and upgrades the account.",
+      }),
+    })
+    .meta({
+      description:
+        'An authorization: a code or tokens, with the signed key authorization when the request asks for one.',
+      id: 'Authorization',
+    })
+}
+
+/** An app's headless authorization request. */
+export type Request = z.output<typeof schema.request>
+
+/**
+ * Returns why Tempo ID refuses a headless `request`, or `undefined`. The request must meet each rule:
+ *
+ * - The app is a registered first-party web app, and its page calls from the redirect URI's origin.
+ * - A key comes from an app without a client secret, and fits the headless ceiling. A challenge
+ *   needs `tempo-id:sign`.
+ */
+export function check(
+  request: Request,
+  options: check.Options,
+): ErrorResponse.Instance<typeof check.errors> | undefined {
+  const { app, origin } = options
+  if (!app || !app.redirectUris.includes(request.redirect_uri))
+    return new RejectedError()
+  // A public app proves nothing about its caller, so a program that impersonates it receives what
+  // the response carries. Only first-party apps authorize headlessly. A third-party app's code goes
+  // to its redirect URI, after the user approves the request.
+  if (!app.firstParty)
+    return new RejectedError({
+      description:
+        'Headless authorization refused: the app is not a first-party app. Send the user to `/oauth2/authorize`, and receive the code at the redirect URI.',
+    })
+
+  // A native app's request proves no app, since any program can send one, with or without its
+  // redirect URI's `Origin`. Its code goes to its redirect URI, through an authentication sheet.
+  if (app.type === 'native')
+    return new RejectedError({
+      description:
+        "Headless authorization refused: a native app's request does not prove which app sends it. Open `/oauth2/authorize` in an authentication sheet, and receive the code at the redirect URI.",
+    })
+
+  // A browser sets `Origin` itself, so a page calls from its redirect URI's origin.
+  const redirectUri = new URL(request.redirect_uri)
+  if (origin !== redirectUri.origin)
+    return new InvalidOriginError({
+      error_description: `Invalid \`Origin\`: ${origin ?? 'none'}. Requests for this redirect URI must come from ${redirectUri.origin}.`,
+      field: 'Origin',
+      meta: { expected: redirectUri.origin, ...(origin ? { origin } : {}) },
+    })
+
+  const key = request.key_authorization
+  if (!key) return undefined
+  // A confidential app proves itself only with its secret, which a page never holds, and the code
+  // redemption that checks it returns no key.
+  if (app.secret)
+    return new RejectedError({
+      description:
+        'Key authorization refused: the app holds a client secret, which a headless request does not prove. Authorize the key through a redirect or the device grant.',
+    })
+  return (
+    KeyAuthorization.checkHeadless(key, { sign: app.sign }) ??
+    KeyAuthorization.checkChallenge({ app, clientId: request.client_id, key })
+  )
+}
+
+export namespace check {
+  export type Options = {
+    /** The app that `client_id` names, if any. */
+    app:
+      | Pick<
+          Apps.App,
+          'firstParty' | 'redirectUris' | 'secret' | 'sign' | 'type'
+        >
+      | undefined
+    /** The request's `Origin`, if any. */
+    origin: string | undefined
+  }
+
+  /** The refusals `check` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.checkHeadless.errors,
+    ...KeyAuthorization.checkChallenge.errors,
+    InvalidOriginError,
+    RejectedError,
+  ] as const
+}
+
+/**
+ * Returns why Tempo ID refuses `key` in a redirect's authorization request, or `undefined`. The
+ * approval page shows the key, so the headless ceiling does not apply. The request needs a PKCE
+ * challenge, whose verifier receives the key.
+ */
+export function checkKey(
+  options: checkKey.Options,
+): ErrorResponse.Instance<typeof checkKey.errors> | undefined {
+  const { app, clientId, codeChallenge, key, query } = options
+  if (!codeChallenge)
+    return new RejectedError({
+      description:
+        'Key authorization refused: the request names no `code_challenge`, whose verifier receives the key. Send an S256 `code_challenge`.',
+    })
+  // `key` already holds the defaults, so the check reads the key as the query carries it.
+  const explicit = Apps.thirdParty(clientId)
+    ? KeyAuthorization.checkExplicit(
+        decode(query.get('key_authorization') ?? ''),
+      )
+    : undefined
+  return (
+    explicit ??
+    KeyAuthorization.check(key) ??
+    KeyAuthorization.checkChallenge({ app, clientId, key })
+  )
+}
+
+export namespace checkKey {
+  export type Options = {
+    /** The app that `clientId` names, if any. */
+    app: Pick<Apps.App, 'sign'> | undefined
+    /** The requesting app's client ID. */
+    clientId: string
+    /** The request's `code_challenge`, if any. */
+    codeChallenge: string | null | undefined
+    /** The key that the request carries. */
+    key: KeyAuthorization.Key
+    /** The request's parameters, with the key as the app sent it. */
+    query: URLSearchParams
+  }
+
+  /** The refusals `checkKey` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.check.errors,
+    ...KeyAuthorization.checkExplicit.errors,
+    ...KeyAuthorization.checkChallenge.errors,
+    RejectedError,
+  ] as const
+}
+
+/**
+ * Returns the key of a redirect's `query`, with its `challenge` bound as the witness, or `undefined`
+ * without one. Returns `Validation.InvalidFieldError` for an invalid key or a repeated parameter, so
+ * a page cannot show one value and approve another.
+ */
+export function fromQuery(
+  query: URLSearchParams,
+): KeyAuthorization.Key | Validation.InvalidFieldError | undefined {
+  const repeated = keyParameters.find((name) => query.getAll(name).length > 1)
+  if (repeated)
+    return new Validation.InvalidFieldError({
+      issues: [
+        {
+          message: 'Repeated parameter. Send it once',
+          path: [repeated],
+        },
+      ],
+    })
+
+  const encoded = query.get('key_authorization')
+  const parsed = schema.redirect.safeParse({
+    challenge: query.get('challenge') ?? undefined,
+    key_authorization: encoded === null ? undefined : decode(encoded),
+  })
+  if (!parsed.success)
+    return new Validation.InvalidFieldError({ issues: parsed.error.issues })
+  return parsed.data
+}
+
+/**
+ * Returns `parameters` with `consent` added to `prompt` when they carry `key_authorization`, so the
+ * approval page shows the key. A first-party app's key without an expiry gains the default, so
+ * approval signs the expiry that the page shows.
+ */
+export function prepare(parameters: URLSearchParams) {
+  if (!parameters.has('key_authorization')) return parameters
+
+  const prepared = new URLSearchParams(parameters)
+  const prompt = new Set(
+    (prepared.get('prompt') ?? '').split(' ').filter(Boolean),
+  )
+  prompt.add('consent')
+  prepared.set('prompt', [...prompt].join(' '))
+
+  // A repeated key stays as it is, so the page refuses it.
+  const [encoded, ...rest] = prepared.getAll('key_authorization')
+  const key = encoded && !rest.length ? decode(encoded) : undefined
+  if (
+    !Apps.thirdParty(prepared.get('client_id') ?? '') &&
+    typeof key === 'object' &&
+    key !== null &&
+    !Array.isArray(key) &&
+    !('expiry' in key)
+  )
+    prepared.set(
+      'key_authorization',
+      Base64.fromString(
+        JSON.stringify({
+          ...key,
+          expiry: Math.floor(Date.now() / 1000) + KeyAuthorization.lifetime,
+        }),
+        base64url,
+      ),
+    )
+  return prepared
+}
+
+/** Unpadded URL-safe Base64, as the client encodes `key_authorization`. */
+const base64url = { pad: false, url: true } as const
+
+/** The query parameters that carry a redirect's key. */
+const keyParameters = ['challenge', 'key_authorization'] as const
+
+/** Decodes base64url JSON, or returns `null`, which fails validation. */
+function decode(value: string): unknown {
+  try {
+    return JSON.parse(Base64.toString(value))
+  } catch {
+    return null
+  }
+}

package/src/internal/Balance.ts

@@ -0,0 +1,144 @@
+/**
+ * The balance of a Tempo Account: the USD value of its verified TIP-20 holdings, from the Tempo API
+ * that `TEMPO_API_URLS` lists for each chain.
+ * @module
+ */
+import type { Context } from 'hono'
+import { z } from 'zod'
+import type { Env } from './Env.js'
+import * as Log from './Log.js'
+import * as Timing from './Timing.js'
+
+/** The Tempo API refused the valuation, or failed. */
+export class RequestError extends Error {
+  override readonly name = 'Balance.RequestError'
+
+  constructor(options: RequestError.Options) {
+    super(`The Tempo API responded with ${options.status}.`)
+  }
+}
+
+export declare namespace RequestError {
+  type Options = {
+    /** The response's HTTP status. */
+    status: number
+  }
+}
+
+/** Milliseconds that a read waits for the API before it fails. */
+const timeout = 3_000
+
+export namespace schema {
+  /** A balance, as the API returns it. */
+  export const balance = z
+    .object({
+      amount: z.string().meta({
+        description: 'The value in USD, as a decimal string.',
+        examples: ['12.5'],
+      }),
+      currency: z
+        .literal('USD')
+        .meta({ description: 'The currency of `amount`.' }),
+    })
+    .meta({
+      description: "The value of an account's verified token holdings, in USD.",
+      id: 'Balance',
+    })
+
+  /** The part of the Tempo API's `AddressValuation` that the balance reads. */
+  export const valuation = z.object({
+    amount: z.string().regex(/^\d+(\.\d+)?$/),
+    currency: z.literal('USD'),
+  })
+}
+
+/**
+ * Returns the USD balance of `address` on the chain with `chainId`, from the Tempo API at `apiUrl`.
+ *
+ * @throws {RequestError} When the API refuses the request or fails.
+ */
+export async function get(options: get.Options): Promise<get.ReturnType> {
+  // The API can sit under a path, such as behind a gateway, which a root-relative URL would drop.
+  const url = new URL(options.apiUrl)
+  url.pathname = `${url.pathname.replace(/\/$/, '')}/v1/addresses/${options.address}/valuation`
+  url.searchParams.set('chainId', String(options.chainId))
+  url.searchParams.set('currency', 'USD')
+  // The entry's URL holds the key in its user name and password, such as `tempo:sk:…`, which the
+  // URL splits at the first colon. The API reads the key from a header, since a query can reach logs.
+  const key = [url.username, url.password]
+    .filter(Boolean)
+    .map(decodeURIComponent)
+    .join(':')
+  url.username = ''
+  url.password = ''
+
+  const response = await fetch(url, {
+    headers: key ? { 'tempo-api-key': key } : {},
+    signal: AbortSignal.timeout(timeout),
+  })
+  if (!response.ok) {
+    await response.body?.cancel()
+    throw new RequestError({ status: response.status })
+  }
+
+  const valuation = schema.valuation.parse(await response.json())
+  return { amount: valuation.amount, currency: 'USD' }
+}
+
+export declare namespace get {
+  type Options = {
+    /** The account's address. */
+    address: `0x${string}`
+    /** The Tempo API's URL, with its key, if any, as the user name and password. */
+    apiUrl: string
+    /** The ID of the chain to read. */
+    chainId: number
+  }
+
+  type ReturnType = {
+    /** A decimal string, such as `12.5`. */
+    amount: string
+    /** Always `USD`. */
+    currency: 'USD'
+  }
+}
+
+/**
+ * Returns the balance of each account in `accounts`, in order, as {@link get} reads it. A failed
+ * read logs, and returns `null`. Without `apiUrl`, every balance is `null`.
+ */
+export function list(c: Context<Env>, options: list.Options) {
+  const { accounts, apiUrl, chainId } = options
+  if (!apiUrl) return Promise.resolve(accounts.map(() => null))
+
+  return Promise.all(
+    accounts.map((account) =>
+      Timing.measure(
+        c,
+        get({ address: account.address, apiUrl, chainId }),
+        'tempoApi.valuation.get',
+      ).catch((error: unknown) => {
+        Log.warn(c, {
+          error,
+          fields: { chainId },
+          message: 'A balance failed to load.',
+        })
+        return null
+      }),
+    ),
+  )
+}
+
+export declare namespace list {
+  type Options = {
+    /** The accounts to read. */
+    accounts: readonly {
+      /** The account's address. */
+      address: `0x${string}`
+    }[]
+    /** The chain's Tempo API URL, or `undefined` when `TEMPO_API_URLS` lists none. */
+    apiUrl: string | undefined
+    /** The ID of the chain to read. */
+    chainId: number
+  }
+}

package/src/internal/BodyLimit.ts

@@ -0,0 +1,31 @@
+/**
+ * Caps request bodies before a validator or route reads them. The largest real body, a key that
+ * limits every Tempo token, is under 20 KB.
+ * @module
+ */
+import { bodyLimit } from 'hono/body-limit'
+import * as ErrorResponse from './ErrorResponse.js'
+
+/** The request body exceeds {@link maxSize}. */
+export class BodyTooLargeError extends ErrorResponse.define('body_too_large') {
+  override readonly name = 'BodyLimit.BodyTooLargeError'
+
+  constructor() {
+    super({
+      error_description: `Invalid request body: exceeds the ${maxSize}-byte maximum. Send a body of ${maxSize} bytes or fewer.`,
+      meta: { maximum: maxSize },
+    })
+  }
+}
+
+/** The refusals {@link middleware} returns. */
+export const errors = [BodyTooLargeError] as const
+
+/** The largest body the API reads, in bytes. */
+export const maxSize = 64 * 1024
+
+/** Refuses a body over {@link maxSize} with `body_too_large`, by its length or streamed bytes. */
+export const middleware = bodyLimit({
+  maxSize,
+  onError: (c) => ErrorResponse.json(c, new BodyTooLargeError()),
+})