tapimo 0.2.0 → 0.4.0

package/src/internal/Auth.ts

@@ -6,6 +6,7 @@ import { createMiddleware } from 'hono/factory'
 import { matchedRoutes } from 'hono/route'
 import type { MergePath, RouterRoute, Schema as core_Schema } from 'hono/types'
 import { findTargetHandler } from 'hono/utils/handler'
+import { decodeJwt } from 'jose'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
 import * as z from 'zod/mini'
@@ -15,6 +16,7 @@ import * as ApiKey from '../ApiKey.js'
 import * as ApiKeys from '../ApiKeys.js'
 import * as Db from '../db/Db.js'
 import type * as Store from './Store.js'
+import * as Invitations from '../db/tables/invitations.js'
 import * as Memberships from '../db/tables/memberships.js'
 import * as Metadata from '../apps/metadata.js'
 import * as OpenApi from './OpenApi.js'
@@ -46,6 +48,13 @@ export type Context = {
     | undefined
   /** MPP payment configuration. */
   mpp?: Mpp | undefined
+  /**
+   * Configured default anonymous public quota. Used as the throttle ceiling for
+   * sandbox keys without active billing on routes that expose no public lane
+   * (where the per-route `policy.public` is absent). Omit to fall back to the
+   * framework default.
+   */
+  publicRateLimit?: RateLimit.Limit | undefined
   /** Rate-limit store used by API handlers. */
   rateLimit?: RateLimit.Store | undefined
   /** Session lane resolution (the session surface's capability), or undefined when sessions are unmounted. */
@@ -465,6 +474,10 @@ export function middleware<
             resolve,
           },
         }),
+    // The throttle ceiling for sandbox keys without active billing, so
+    // API-key-only routes (no per-route `policy.public`) still fall back to the
+    // deployment's configured public quota.
+    publicRateLimit: defaults.public.rateLimit,
     ...(options.mpp === false
       ? {}
       : {
@@ -677,11 +690,19 @@ export function install(options: install.Options) {
   // mounted sub-app, and the public lane rate-limits challenge-store writes.
   const app = (() => {
     if (!options_session || !kv) return undefined
-    const { issuer, origin, ttl } =
+    const { issuer, origin, requireEmail, ttl } =
       (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {}
+    // Case-insensitive exact-match email-domain allowlist for new-user sign-ups.
+    const emailAllowlist = (
+      typeof options_session === 'object' ? options_session.emailAllowlist : undefined
+    )
+      ?.map((domain) => domain.trim().toLowerCase())
+      .filter(Boolean)
 
     const handler = Accounts.Handler.auth({
-      ...(issuer ? { identity: { issuer } } : {}),
+      ...(issuer || requireEmail
+        ? { identity: { ...(issuer ? { issuer } : {}), ...(requireEmail ? { required: true } : {}) } } // prettier-ignore
+        : {}),
       // Sign-in upserts the `users` row keyed by address.
       onAuthenticate: async ({ address }) => {
         await Users.upsertByAddress(Db.get(db), { address })
@@ -738,7 +759,41 @@ export function install(options: install.Options) {
     }
 
     const policy_public = policy({ public: true })
+    const policy_session = policy({ public: true, session: true })
     const describe = OpenApi.describeRoute({ hide: true })
+
+    // Sign-up gate: new addresses need an allowlisted identity email domain
+    // or a pending invitation; existing users pass. The claim decodes
+    // unverified; the mounted handler verifies the token before any session
+    // or user is created, so a forged claim never authenticates.
+    const gate_signup = createMiddleware<App.Environment>(async (c, next) => {
+      if (!emailAllowlist?.length) return next()
+      const { address, idToken } = (await c.req.json()) as z.output<typeof schema.verify.Body>
+      const database = Db.get(db)
+      const user = await Users.getByAddress(database, address)
+      if (!user) {
+        const email = (() => {
+          if (!idToken) return undefined
+          try {
+            const { email } = decodeJwt<{ email?: string }>(idToken)
+            return typeof email === 'string' ? email.toLowerCase() : undefined
+          } catch {
+            return undefined
+          }
+        })()
+        const allowed = await (async () => {
+          if (!email) return false
+          const at = email.lastIndexOf('@')
+          if (at > 0 && emailAllowlist.includes(email.slice(at + 1))) return true
+          // A pending invitation admits the email regardless of domain.
+          return (await Invitations.listByEmail(database, email)).length > 0
+        })()
+        if (!allowed)
+          return c.json({ error: 'sign-ups are restricted to approved email domains or invited emails' }, 403) // prettier-ignore
+      }
+      return next()
+    })
+
     const app = new Hono<App.Environment>()
       .use('/v1/auth/siwe', policy_public, describe)
       .use('/v1/auth/siwe/*', policy_public, describe)
@@ -779,6 +834,7 @@ export function install(options: install.Options) {
         code: 'body_invalid',
         message: 'Invalid request body',
       }),
+      gate_signup,
       OpenApi.describeRoute({
         description:
           'Verifies the signed challenge and establishes a session. Sets a session cookie by default; pass `returnToken` to receive a bearer token instead.',
@@ -796,8 +852,11 @@ export function install(options: install.Options) {
               },
             },
           },
-          400: handlerError('Invalid, expired, or mismatched challenge message.'),
+          400: handlerError('Invalid, expired, or mismatched challenge message; or a required identity token is missing.'), // prettier-ignore
           401: handlerError('Signature or identity verification failed.'),
+          ...(emailAllowlist?.length
+            ? { 403: handlerError('Sign-up rejected: the identity email is neither on an allowlisted domain nor pending an invitation.') } // prettier-ignore
+            : {}),
           409: handlerError('Challenge nonce already used or unknown.'),
           429: OpenApi.standardError(429, 'Rate limited.'),
           500: OpenApi.standardError(500, 'Internal server error.'),
@@ -808,7 +867,7 @@ export function install(options: install.Options) {
     )
     app.post(
       '/v1/auth/siwe/logout',
-      policy_public,
+      policy_session,
       OpenApi.describeRoute({
         description: 'Revokes the current session and clears the session cookie.',
         hide: false,
@@ -823,7 +882,7 @@ export function install(options: install.Options) {
       }),
     )
     return Object.assign(
-      // The tag joins the `Platform API` group at `platform()`'s chosen slot;
+      // The tag joins the `Management API` group at `management()`'s chosen slot;
       // group listings filter to defined tags, so it drops out when unmounted.
       Metadata.attach(app.route('/v1/auth/siwe', handler), {
         tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],
@@ -845,8 +904,8 @@ export declare namespace install {
   type Options = {
     auth:
       | (Omit<middleware.Options, 'session'> & {
-          /** Session sign-in surface: mounts `/v1/auth/siwe` (challenge/verify/logout) and enables the session lane. Pass true for defaults or a wallet config. Requires `kv`. */
-          session?: boolean | { wallet?: Wallet | undefined } | undefined
+          /** Session sign-in surface: mounts `/v1/auth/siwe` (challenge/verify/logout) and enables the session lane. Pass true for defaults or a config object. Requires `kv`. */
+          session?: Session | undefined
         })
       | false
       | undefined
@@ -856,12 +915,24 @@ export declare namespace install {
     kv: { store: Store.State } | undefined
   }
 
+  /** Session sign-in surface configuration: `true` for defaults, or a config object. */
+  type Session =
+    | boolean
+    | {
+        /** Restrict new-user sign-ups to verified emails on these domains (case-insensitive exact match); invited emails and existing users sign in unaffected. */
+        emailAllowlist?: readonly string[] | undefined
+        /** SIWE wallet sign-in configuration. */
+        wallet?: Wallet | undefined
+      }
+
   /** SIWE wallet sign-in configuration. */
   type Wallet = {
     /** Identity (verified email) issuer override; defaults to the Tempo wallet's production OIDC mount. */
     issuer?: string | undefined
     /** Pinned absolute origin for SIWE domain binding. Required off-Workers; on Workers the edge proxy headers are trusted by default. */
     origin?: string | undefined
+    /** Reject sign-ins that carry no valid identity token, so every session holds a verified email. */
+    requireEmail?: boolean | undefined
     /** Session and challenge TTL overrides, in seconds. */
     ttl?: { challenge?: number | undefined; session?: number | undefined } | undefined
   }
@@ -1199,84 +1270,98 @@ export function require<environment extends Environment = Environment>(
         })
       }
 
-      // Sandbox keys are restricted to non-mainnet chains. An explicit
-      // `chainId` of mainnet makes the key unusable for this request, so it is
-      // ignored and the request falls through to the public policy below (as if
-      // no key were presented). A request that omits `chainId` is steered to
-      // testnet so a sandbox key still "just works" without passing `?chainId`.
+      // Sandbox keys are testnet-only. A sandbox key that explicitly targets
+      // mainnet (`?chainId`) is rejected with a clear message rather than
+      // steered or downgraded to anonymous, so the caller learns their key does
+      // not cover mainnet. The no-`chainId` default (mainnet) is enforced by
+      // the data group's chain guard, which knows the route is chain-scoped;
+      // the relay resolves its chain from the request body and enforces the
+      // same rule in its sponsor validation.
       const explicitChain = explicitChainId(c)
-      const sandboxOnMainnet =
+
+      const principal = principalFromApiKey(apiKey)
+      c.set('principal', principal)
+
+      if (
         apiKey.environment === 'sandbox' &&
         explicitChain !== undefined &&
         Viem.isMainnet(explicitChain)
+      )
+        return jsonError(c, {
+          code: 'api_key_forbidden',
+          message: 'Sandbox API keys only support testnet. Pass a testnet `chainId`.',
+          status: 403,
+        })
 
-      if (!sandboxOnMainnet) {
-        if (
-          apiKey.environment === 'sandbox' &&
-          explicitChain === undefined &&
-          Viem.isMainnet((c.get('chainId' as never) as number | undefined) ?? Viem.defaultChainId)
-        )
-          // `chainId` lives on the app's `Variables`, not the narrower auth
-          // contract, so it is read/written through an untyped cast.
-          c.set('chainId' as never, Viem.chainId.testnet as never)
-
-        const principal = principalFromApiKey(apiKey)
-        c.set('principal', principal)
-        // Default-deny: routes with no API-key lane allow only the super admin.
-        // A valid key is authenticated but forbidden.
-        if (!policy.apiKey)
-          return jsonError(c, {
-            code: 'forbidden',
-            message: 'API key not permitted for this route',
-            status: 403,
-          })
-        const missing = apiKey.scopes.includes(Scope.wildcard)
-          ? []
-          : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
-        if (missing.length > 0)
-          return jsonError(c, {
-            code: 'api_key_forbidden',
-            message: 'API key missing required scope',
-            status: 403,
-          })
+      // Default-deny: routes with no API-key lane allow only the super admin.
+      // A valid key is authenticated but forbidden.
+      if (!policy.apiKey)
+        return jsonError(c, {
+          code: 'forbidden',
+          message: 'API key not permitted for this route',
+          status: 403,
+        })
+      const missing = apiKey.scopes.includes(Scope.wildcard)
+        ? []
+        : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
+      if (missing.length > 0)
+        return jsonError(c, {
+          code: 'api_key_forbidden',
+          message: 'API key missing required scope',
+          status: 403,
+        })
 
-        if (hasPayment)
-          return requirePayment(c, next, {
+      // Sandbox keys without active billing are throttled to the public quota.
+      // `billingActive` is snapshotted on the key record (stamped at mint,
+      // re-synced when billing changes), so this needs no billing read on the
+      // request path. Resolved before the paid lane so a payment credential
+      // can't buy past the throttle: sandbox is non-billable testnet.
+      const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true
+
+      if (hasPayment && !throttled)
+        return requirePayment(c, next, {
+          auth,
+          payment: { reason: 'api_key_over_quota', type: 'mpp' },
+          policy,
+          principal,
+        })
+
+      if (policy.apiKey) {
+        // A route consumes exactly one quota bucket: its single required scope,
+        // else `'*'` (zero scopes). Routes today require at most one scope; a
+        // future multi-scope route buckets against its first scope.
+        const scope = policy.apiKey.scopes[0] ?? Scope.wildcard
+        // A throttled sandbox key shares the key's bucket but at the public
+        // ceiling, so activating billing lifts the limit on the same counter.
+        const limit = throttled
+          ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { perMinute: 60 })
+          : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
+        const result = await consumeRateLimit(auth, {
+          key: `api_key:${apiKey.id}:scope:${scope}`,
+          limit,
+        })
+        if (result) {
+          setRateLimitHeaders(c, result)
+          // Surface the bucket so callers can correlate a 429 with the exhausted
+          // quota. Set before the over-quota branch so it rides the 429 (an MPP
+          // 402 challenge is owned by mppx and drops these headers — by design).
+          c.header('RateLimit-Scope', scope)
+        }
+        if (result && !result.allowed) {
+          // A throttled sandbox key gets a plain 429, never an MPP challenge —
+          // it must activate billing to lift the ceiling, not pay per request.
+          if (throttled) return rateLimitExceeded(c, result)
+          return requirePaymentOrRateLimit(c, next, {
             auth,
             payment: { reason: 'api_key_over_quota', type: 'mpp' },
             policy,
             principal,
+            rateLimit: result,
           })
-
-        if (policy.apiKey) {
-          // A route consumes exactly one quota bucket: its single required scope,
-          // else `'*'` (zero scopes). Routes today require at most one scope; a
-          // future multi-scope route buckets against its first scope.
-          const scope = policy.apiKey.scopes[0] ?? Scope.wildcard
-          const limit = resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
-          const result = await consumeRateLimit(auth, {
-            key: `api_key:${apiKey.id}:scope:${scope}`,
-            limit,
-          })
-          if (result) {
-            setRateLimitHeaders(c, result)
-            // Surface the bucket so callers can correlate a 429 with the exhausted
-            // quota. Set before the over-quota branch so it rides the 429 (an MPP
-            // 402 challenge is owned by mppx and drops these headers — by design).
-            c.header('RateLimit-Scope', scope)
-          }
-          if (result && !result.allowed)
-            return requirePaymentOrRateLimit(c, next, {
-              auth,
-              payment: { reason: 'api_key_over_quota', type: 'mpp' },
-              policy,
-              principal,
-              rateLimit: result,
-            })
         }
-
-        return next()
       }
+
+      return next()
     }
 
     // Cookie sessions carry no Authorization credential; resolve the session
@@ -1410,23 +1495,26 @@ function consumeRateLimit(
   // or a stall past `rateLimitConsumeTimeout` degrades to unenforced quota
   // instead of failing — or blocking — the request.
   return withTimeout(auth.rateLimit.consume(options), rateLimitConsumeTimeout).catch((error) => {
-    // A timeout or Cloudflare Durable Object overload is an expected
-    // degradation (a slow/hot counter backend), logged at warn so it stays out
-    // of error dashboards; an unexpected store throw is a genuine error.
-    if (error instanceof RateLimitTimeoutError || isDurableObjectOverload(error))
+    // A timeout or transient Durable Object fault is an expected degradation,
+    // logged at warn to stay out of error dashboards; an unexpected store
+    // throw is a genuine error.
+    if (error instanceof RateLimitTimeoutError || isDurableObjectFault(error))
       console.warn('[auth] rate-limit consume degraded; failing open', error)
     else console.error('[auth] rate-limit consume failed; failing open', error)
     return null
   })
 }
 
-function isDurableObjectOverload(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'overloaded' in error &&
-    (error as { overloaded?: unknown }).overloaded === true
-  )
+function isDurableObjectFault(error: unknown): boolean {
+  const { message, overloaded, retryable } = (error ?? {}) as {
+    message?: string | undefined
+    overloaded?: boolean | undefined
+    retryable?: boolean | undefined
+  }
+  if (overloaded === true || retryable === true) return true
+  // Cloudflare redacts internal Durable Object faults to "internal error;
+  // reference = <token>", with no marker property to detect them by.
+  return typeof message === 'string' && message.startsWith('internal error')
 }
 
 /**
@@ -1640,11 +1728,12 @@ function requirePaymentOrRateLimit<environment extends Environment>(
   options: RateLimitAccess,
 ) {
   if (isPaymentEnabled(options.auth, options.policy)) return requirePayment(c, next, options)
+  return rateLimitExceeded(c, options.rateLimit)
+}
 
-  c.header(
-    'Retry-After',
-    String(Math.max(options.rateLimit.reset - Math.ceil(Date.now() / 1_000), 1)),
-  )
+/** Emits a `429` with a `Retry-After` derived from the window reset. */
+function rateLimitExceeded(c: hono_Context, result: RateLimit.Result) {
+  c.header('Retry-After', String(Math.max(result.reset - Math.ceil(Date.now() / 1_000), 1)))
   return jsonError(c, {
     code: 'rate_limit_exceeded',
     message: 'Rate limit exceeded',

package/src/internal/Cache.ts

@@ -74,7 +74,7 @@ export function response<environment extends Env>(
   })
   const etag = hono_etag()
 
-  return async (c, next) => {
+  const middleware: MiddlewareHandler<environment> = async (c, next) => {
     const values = response.preservedHeaders.map((name) => [name, c.res.headers.get(name)] as const)
 
     // Honor the standard request `Cache-Control` directives (plus the HTTP/1.0
@@ -155,6 +155,10 @@ export function response<environment extends Env>(
     if (result instanceof Response) return res
     return undefined
   }
+
+  // `markCacheable` lets the edge layer pay its store lookup only on routes
+  // that mount this middleware; everything else skips the read.
+  return EdgeCache.markCacheable(middleware)
 }
 
 export declare namespace response {

package/src/internal/EdgeCache.test.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import { createMiddleware } from 'hono/factory'
 import * as EdgeCache from './EdgeCache.js'
 import type * as Store from './Store.js'
 
@@ -128,6 +129,18 @@ describe('middleware', () => {
     expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
+  test('skips the store lookup for routes that did not opt in', async () => {
+    const { app, store } = createApp()
+
+    await app.request('/uncached')
+    await app.request('/missing-route')
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+
+    // Marked routes still pay (and use) the lookup.
+    await app.request('/cached')
+    expect(store.gets).toMatchInlineSnapshot(`1`)
+  })
+
   test('answers conditional requests from a cached ETag with 304', async () => {
     const { app } = createApp()
 
@@ -172,13 +185,18 @@ type Environment = { Variables: EdgeCache.Variables }
 // In-memory `Store.Store` so the edge cache and origin cache share one shape.
 function memoryStore() {
   const map = new Map<string, string>()
+  let gets = 0
   return {
     async delete(key: string) {
       map.delete(key)
     },
     async get(key: string) {
+      gets++
       return map.get(key) ?? null
     },
+    get gets() {
+      return gets
+    },
     async list() {
       return { keys: [...map.keys()].map((name) => ({ name })) }
     },
@@ -189,7 +207,7 @@ function memoryStore() {
       return map.size
     },
     type: 'state',
-  } satisfies Store.Store & { readonly size: number }
+  } satisfies Store.Store & { readonly gets: number; readonly size: number }
 }
 
 function createApp(options: { store?: Store.Store | undefined } = {}) {
@@ -203,7 +221,12 @@ function createApp(options: { store?: Store.Store | undefined } = {}) {
     downstream++
     await next()
   })
-  app.get('/cached', (c) => {
+  // Routes publishing a policy mount a marked middleware, as `Cache.response`
+  // routes do; unmarked routes must skip the lookup entirely.
+  const cacheable = EdgeCache.markCacheable(
+    createMiddleware<Environment>(async (_c, next) => next()),
+  )
+  app.get('/cached', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     c.header('Age', '123')
     c.header('CF-Cache-Status', 'HIT')
@@ -212,11 +235,11 @@ function createApp(options: { store?: Store.Store | undefined } = {}) {
     c.header('RateLimit-Remaining', '9')
     return c.json({ ok: true })
   })
-  app.get('/error', (c) => {
+  app.get('/error', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     return c.json({ ok: false }, 500)
   })
-  app.get('/binary', (c) => {
+  app.get('/binary', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     // Bytes that are not valid UTF-8 (PNG signature) — corrupted if stored via
     // `.text()` instead of base64.

package/src/internal/EdgeCache.ts

@@ -1,4 +1,5 @@
-import type { Env, MiddlewareHandler } from 'hono'
+import type { Context, Env, MiddlewareHandler } from 'hono'
+import { matchedRoutes } from 'hono/route'
 import { Base64 } from 'ox'
 
 import type * as Store from './Store.js'
@@ -53,6 +54,10 @@ const volatileHeaders = [
  * is that cache hits bypass origin metering: they are not counted against
  * rate-limit quotas.
  *
+ * Lookups are equally scoped: only requests whose matched route carries the
+ * {@link markCacheable} marker (applied by `Cache.response`) pay the store
+ * read, so GETs to non-cacheable routes skip the round trip entirely.
+ *
  * The cache is a plain `Store.Store` — the same store the origin read cache uses
  * — holding the response serialized to a string under a URL key. It is a no-op
  * when no store is supplied.
@@ -68,8 +73,14 @@ export function middleware<environment extends Env>(
 ): MiddlewareHandler<environment> {
   return async (c, next) => {
     const { store } = options
+    // Pay the store lookup only when a matched handler is marked cacheable
+    // (mounted `Cache.response`); other GETs (authed management routes, docs,
+    // 404s) can never hit, so the read would be a wasted round trip.
     const eligible =
-      store !== undefined && c.req.method === 'GET' && !c.req.raw.headers.has('range')
+      store !== undefined &&
+      c.req.method === 'GET' &&
+      !c.req.raw.headers.has('range') &&
+      isCacheableRoute(c)
     const key = eligible ? cacheKey(c.req.url) : undefined
 
     // Honor the standard request `Cache-Control` directives so a caller can
@@ -104,16 +115,41 @@ export function middleware<environment extends Env>(
     if (c.res.headers.get('content-type')?.includes('text/event-stream')) return
 
     // Store a public, sanitized copy; the client still receives the original
-    // (private, metered) response for this miss.
-    const value = await serialize(c.res, policy)
-    const put = store.put(key, value, { ttl: policy.maxAge * 1_000 })
+    // (private, metered) response for this miss. Clone synchronously — the
+    // original body locks once it streams to the client — then serialize and
+    // write behind `waitUntil` so the miss response is not held open on the
+    // body read.
+    const copy = c.res.clone()
+    const persist = serialize(copy, policy).then((value) =>
+      store.put(key, value, { ttl: policy.maxAge * 1_000 }),
+    )
     const waitUntil = getWaitUntil(c)
-    if (waitUntil) waitUntil(put)
-    else await put.catch(() => {})
+    if (waitUntil) waitUntil(persist)
+    else await persist.catch(() => {})
     return
   }
 }
 
+// Marks handlers whose route publishes an edge-cache policy; the middleware
+// pays the store lookup only when a matched handler carries it.
+const cacheableSymbol = Symbol('tempoApi.edgeCacheable')
+
+/**
+ * Marks a route handler/middleware as publishing an edge-cache policy, so
+ * {@link middleware} looks its route up in the edge cache. `Cache.response`
+ * applies it; routes composed any other way never enter the shared cache.
+ */
+export function markCacheable<const handler extends (...args: never[]) => unknown>(
+  handler: handler,
+): handler {
+  return Object.assign(handler, { [cacheableSymbol]: true })
+}
+
+// True when any handler matched for this request is marked cacheable.
+function isCacheableRoute(c: Context): boolean {
+  return matchedRoutes(c).some((route) => cacheableSymbol in route.handler)
+}
+
 export declare namespace middleware {
   /** Options for the edge-cache middleware. */
   type Options = {
@@ -134,6 +170,8 @@ type Stored = {
   status: number
 }
 
+// Consumes `response` (callers pass a dedicated clone; the client streams the
+// original).
 async function serialize(response: Response, policy: Policy): Promise<string> {
   const headers = new Headers(response.headers)
   for (const name of volatileHeaders) headers.delete(name)
@@ -145,8 +183,8 @@ async function serialize(response: Response, policy: Policy): Promise<string> {
   const textual = isTextual(headers.get('content-type'))
   const stored: Stored = {
     body: textual
-      ? await response.clone().text()
-      : Base64.fromBytes(new Uint8Array(await response.clone().arrayBuffer())),
+      ? await response.text()
+      : Base64.fromBytes(new Uint8Array(await response.arrayBuffer())),
     ...(textual ? {} : { encoding: 'base64' as const }),
     headers: [...headers],
     status: response.status,

package/src/internal/Fees.test.ts

@@ -0,0 +1,32 @@
+import * as Fees from './Fees.js'
+
+describe('fromGas', () => {
+  test('behavior: scales attodollar gas math to token units with ceiling division', () => {
+    // 100k gas × 1e6 atto = 1e11 atto rounds up to one token unit.
+    expect(Fees.fromGas(100_000n, 1_000_000n)).toBe(1n)
+    // 1M gas × 5e11 atto = 5e17 atto = $0.50 exactly.
+    expect(Fees.fromGas(1_000_000n, 500_000_000_000n)).toBe(500_000n)
+    // Any remainder rounds up, mirroring `calc_gas_balance_spending`.
+    expect(Fees.fromGas(1n, 1_000_000_000_001n)).toBe(2n)
+    expect(Fees.fromGas(0n, 0n)).toBe(0n)
+  })
+})
+
+describe('maxOf', () => {
+  test('behavior: computes the signed cap from bigint or hex quantity fields', () => {
+    expect(Fees.maxOf({ gas: 1_000_000n, maxFeePerGas: 500_000_000_000n })).toBe(500_000n)
+    // Fills carry hex quantities: 0xf4240 = 1M gas, 0x746a528800 = 5e11 atto.
+    expect(Fees.maxOf({ gas: '0xf4240', maxFeePerGas: '0x746a528800' })).toBe(500_000n)
+    // Zero fields are computable (a zero cap), not absent.
+    expect(Fees.maxOf({ gas: 0n, maxFeePerGas: 0n })).toBe(0n)
+  })
+
+  test('behavior: yields undefined when either fee field is missing or unparseable', () => {
+    expect(Fees.maxOf({})).toBeUndefined()
+    expect(Fees.maxOf({ gas: 21_000n })).toBeUndefined()
+    expect(Fees.maxOf({ maxFeePerGas: 1_000_000n })).toBeUndefined()
+    // Decimal strings are not hex quantities; callers fail closed.
+    expect(Fees.maxOf({ gas: '21000', maxFeePerGas: 1_000_000n })).toBeUndefined()
+    expect(Fees.maxOf({ gas: null, maxFeePerGas: 1_000_000n })).toBeUndefined()
+  })
+})