mppx 0.3.11 → 0.3.13

package/src/client/internal/Fetch.ts

@@ -2,6 +2,15 @@ import * as Challenge from '../../Challenge.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 
+// We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
+// even across multiple module instances/bundles. This lets restore() avoid clobbering
+// an unrelated fetch installed by user code or another library.
+const MPPX_FETCH_WRAPPER = Symbol.for('mppx.fetch.wrapper')
+
+type WrappedFetch = typeof globalThis.fetch & {
+  [MPPX_FETCH_WRAPPER]?: typeof globalThis.fetch
+}
+
 let originalFetch: typeof globalThis.fetch | undefined
 
 /**
@@ -29,13 +38,20 @@ export function from<const methods extends readonly Method.AnyClient[]>(
   config: from.Config<methods>,
 ): from.Fetch<methods> {
   const { fetch = globalThis.fetch, methods, onChallenge } = config
+  // Always operate on the true underlying fetch to avoid wrapper-on-wrapper stacking,
+  // which can duplicate retries and make restore semantics fragile.
+  const baseFetch = unwrapFetch(fetch)
 
-  return async (input, init) => {
-    const { context, ...fetchInit } = init ?? {}
-    const response = await fetch(input, fetchInit)
+  const wrappedFetch = async (input: RequestInfo | URL, init?: from.RequestInit<methods>) => {
+    // Pass init through untouched to preserve object identity for non-402 responses.
+    const response = await baseFetch(input, init)
 
     if (response.status !== 402) return response
 
+    // Only extract context for payment handling after confirming 402.
+    const context = (init as Record<string, unknown> | undefined)?.context
+    const { context: _, ...fetchInit } = (init ?? {}) as Record<string, unknown>
+
     const challenge = Challenge.fromResponse(response)
 
     const mi = methods.find((m) => m.name === challenge.method && m.intent === challenge.intent)
@@ -51,22 +67,25 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         })
       : undefined
     const credential = onChallengeCredential ?? (await resolveCredential(challenge, mi, context))
+    validateCredentialHeaderValue(credential)
 
-    return fetch(input, {
+    return baseFetch(input, {
       ...fetchInit,
-      headers: {
-        ...fetchInit.headers,
-        Authorization: credential,
-      },
+      headers: withAuthorizationHeader(fetchInit.headers, credential),
     })
   }
+
+  // Record the wrapped target so future polyfill() / restore() calls can detect origin
+  // and safely unwrap only mppx-installed wrappers.
+  ;(wrappedFetch as WrappedFetch)[MPPX_FETCH_WRAPPER] = baseFetch
+  return wrappedFetch as from.Fetch<methods>
 }
 
 /** Union of all context types from all methods that have context schemas. */
 type AnyContextFor<methods extends readonly Method.AnyClient[]> = {
-  [K in keyof methods]: methods[K] extends Method.Client<any, infer contextSchema>
-    ? contextSchema extends z.ZodMiniType
-      ? z.input<contextSchema>
+  [K in keyof methods]: NonNullable<methods[K]['context']> extends infer ctx
+    ? ctx extends z.ZodMiniType
+      ? z.input<ctx>
       : undefined
     : undefined
 }[number]
@@ -123,8 +142,14 @@ export declare namespace from {
 export function polyfill<const methods extends readonly Method.AnyClient[]>(
   config: polyfill.Config<methods>,
 ): void {
-  originalFetch = globalThis.fetch
-  globalThis.fetch = from(config) as typeof globalThis.fetch
+  // Defensive guard for runtimes/tests where fetch might be non-configurable.
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'fetch')
+  if (!descriptor || (!descriptor.writable && !descriptor.set)) {
+    throw new Error('globalThis.fetch is not writable')
+  }
+
+  if (!originalFetch) originalFetch = globalThis.fetch
+  globalThis.fetch = from({ ...config, fetch: globalThis.fetch }) as typeof globalThis.fetch
 }
 
 export declare namespace polyfill {
@@ -147,12 +172,62 @@ export declare namespace polyfill {
  * ```
  */
 export function restore(): void {
-  if (originalFetch) {
+  // Only restore if the current fetch is still an mppx wrapper.
+  // If app code replaced fetch after polyfill(), we must not overwrite it.
+  if (originalFetch && isWrappedFetch(globalThis.fetch)) {
     globalThis.fetch = originalFetch
     originalFetch = undefined
   }
 }
 
+/** @internal Normalizes headers to a plain object for spreading. */
+function normalizeHeaders(headers: unknown): Record<string, string> {
+  if (!headers) return {}
+  if (headers instanceof Headers) {
+    const result: Record<string, string> = {}
+    headers.forEach((value, key) => {
+      result[key] = value
+    })
+    return result
+  }
+  if (Array.isArray(headers)) return Object.fromEntries(headers)
+  return headers as Record<string, string>
+}
+
+/** @internal */
+function withAuthorizationHeader(headers: unknown, credential: string): Record<string, string> {
+  const normalized = normalizeHeaders(headers)
+  // Remove any existing Authorization header regardless of casing to avoid
+  // duplicate/conflicting credentials on retry.
+  for (const key of Object.keys(normalized)) {
+    if (key.toLowerCase() === 'authorization') delete normalized[key]
+  }
+  normalized.Authorization = credential
+  return normalized
+}
+
+/** @internal */
+function unwrapFetch(fetch: typeof globalThis.fetch): typeof globalThis.fetch {
+  let current = fetch as WrappedFetch
+  while (current[MPPX_FETCH_WRAPPER]) {
+    current = current[MPPX_FETCH_WRAPPER] as WrappedFetch
+  }
+  return current as typeof globalThis.fetch
+}
+
+/** @internal */
+function isWrappedFetch(fetch: typeof globalThis.fetch): fetch is WrappedFetch {
+  return Boolean((fetch as WrappedFetch)[MPPX_FETCH_WRAPPER])
+}
+
+/** @internal */
+function validateCredentialHeaderValue(credential: string): void {
+  if (!credential.trim()) throw new Error('Credential header value must be non-empty')
+  if (credential.includes('\r') || credential.includes('\n')) {
+    throw new Error('Credential header value contains illegal newline characters')
+  }
+}
+
 /** @internal */
 async function resolveCredential(
   challenge: Challenge.Challenge,

package/src/internal/constantTimeEqual.ts

@@ -1,8 +1,10 @@
-import { createHash, timingSafeEqual } from 'node:crypto'
+import { Hash, Hex } from 'ox'
 
 /** Constant-time string comparison to prevent timing attacks. */
 export function constantTimeEqual(a: string, b: string): boolean {
-  const hashA = createHash('sha256').update(a).digest()
-  const hashB = createHash('sha256').update(b).digest()
-  return timingSafeEqual(hashA, hashB)
+  const hashA = Hash.sha256(Hex.fromString(a))
+  const hashB = Hash.sha256(Hex.fromString(b))
+  let result = 0
+  for (let i = 0; i < hashA.length; i++) result |= hashA.charCodeAt(i) ^ hashB.charCodeAt(i)
+  return result === 0
 }

package/src/tempo/client/Charge.ts

@@ -1,4 +1,5 @@
 import type * as Hex from 'ox/Hex'
+import type { Address } from 'viem'
 import { prepareTransactionRequest, signTransaction } from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Actions } from 'viem/tempo'
@@ -8,6 +9,7 @@ import * as Account from '../../viem/Account.js'
 import * as Client from '../../viem/Client.js'
 import * as z from '../../zod.js'
 import * as Attribution from '../Attribution.js'
+import * as AutoSwap from '../internal/auto-swap.js'
 import * as defaults from '../internal/defaults.js'
 import * as Methods from '../Methods.js'
 
@@ -36,6 +38,7 @@ export function charge(parameters: charge.Parameters = {}) {
   return Method.toClient(Methods.charge, {
     context: z.object({
       account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
+      autoSwap: z.optional(z.custom<charge.AutoSwap>()),
     }),
 
     async createCredential({ challenge, context }) {
@@ -44,22 +47,41 @@ export function charge(parameters: charge.Parameters = {}) {
       const account = getAccount(client, context)
 
       const { request } = challenge
-      const { amount, currency, recipient, methodDetails } = request
+      const { amount, methodDetails } = request
+      const currency = request.currency as Address
+      const recipient = request.recipient as Address
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
         : Attribution.encode({ serverId: challenge.realm, clientId })
 
+      const transferCall = Actions.token.transfer.call({
+        amount: BigInt(amount),
+        memo,
+        to: recipient,
+        token: currency,
+      })
+
+      const autoSwap = AutoSwap.resolve(
+        context?.autoSwap ?? parameters.autoSwap,
+        AutoSwap.defaultCurrencies,
+      )
+
+      const swapCalls = autoSwap
+        ? await AutoSwap.findCalls(client, {
+            account: account.address,
+            amountOut: BigInt(amount),
+            tokenOut: currency,
+            tokenIn: autoSwap.tokenIn,
+            slippage: autoSwap.slippage,
+          })
+        : undefined
+
+      const calls = [...(swapCalls ?? []), transferCall]
+
       const prepared = await prepareTransactionRequest(client, {
         account,
-        calls: [
-          Actions.token.transfer.call({
-            amount: BigInt(amount),
-            memo,
-            to: recipient as Hex.Hex,
-            token: currency as Hex.Hex,
-          }),
-        ],
+        calls,
         ...(methodDetails?.feePayer && { feePayer: true }),
         nonceKey: 'expiring',
       } as never)
@@ -77,7 +99,16 @@ export function charge(parameters: charge.Parameters = {}) {
 }
 
 export declare namespace charge {
+  type AutoSwap = AutoSwap.resolve.Value
+
   type Parameters = {
+    /**
+     * Automatically swap from a fallback currency (pathUsd, USDC.e) via the
+     * Tempo DEX when the user lacks sufficient balance of the target currency.
+     *
+     * @default false
+     */
+    autoSwap?: AutoSwap | undefined
     /** Client identifier used to derive the client fingerprint in attribution memos. */
     clientId?: string | undefined
   } & Account.getResolver.Parameters &

package/src/tempo/internal/auto-swap.test.ts

@@ -0,0 +1,113 @@
+import type { Address } from 'viem'
+import { describe, expect, test } from 'vitest'
+import { defaultCurrencies, InsufficientFundsError, resolve } from './auto-swap.js'
+
+describe('defaultCurrencies', () => {
+  test('default', () => {
+    expect(defaultCurrencies).toMatchInlineSnapshot(`
+      [
+        "0x20c0000000000000000000000000000000000000",
+        "0x20C000000000000000000000b9537d11c60E8b50",
+      ]
+    `)
+  })
+})
+
+describe('resolve', () => {
+  const defaults = defaultCurrencies
+
+  test('returns false for undefined', () => {
+    expect(resolve(undefined, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('returns false for false', () => {
+    expect(resolve(false, defaults)).toMatchInlineSnapshot(`false`)
+  })
+
+  test('true resolves to defaults with 1% slippage', () => {
+    expect(resolve(true, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('empty options resolves to defaults with 1% slippage', () => {
+    expect(resolve({}, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom slippage', () => {
+    expect(resolve({ slippage: 5 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 5,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn prepends to defaults', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn deduplicates against defaults', () => {
+    expect(resolve({ tokenIn: [defaults[0]!] }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 1,
+        "tokenIn": [
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+
+  test('custom tokenIn + custom slippage', () => {
+    const custom = '0x0000000000000000000000000000000000000099' as Address
+    expect(resolve({ tokenIn: [custom], slippage: 3 }, defaults)).toMatchInlineSnapshot(`
+      {
+        "slippage": 3,
+        "tokenIn": [
+          "0x0000000000000000000000000000000000000099",
+          "0x20c0000000000000000000000000000000000000",
+          "0x20C000000000000000000000b9537d11c60E8b50",
+        ],
+      }
+    `)
+  })
+})
+
+describe('InsufficientFundsError', () => {
+  test('default', () => {
+    const error = new InsufficientFundsError({
+      currency: '0x0000000000000000000000000000000000000001',
+    })
+    expect(error).toMatchInlineSnapshot(
+      `[InsufficientFundsError: Insufficient funds: no balance in 0x0000000000000000000000000000000000000001 and no viable swap route from fallback currencies.]`,
+    )
+  })
+})

package/src/tempo/internal/auto-swap.ts

@@ -0,0 +1,141 @@
+import type { Address, Client } from 'viem'
+import { isAddressEqual } from 'viem'
+import { readContract } from 'viem/actions'
+import { Actions, Addresses } from 'viem/tempo'
+import * as defaults from './defaults.js'
+
+/** Basis-point denominator (100% = 10 000 bps). */
+const bps = 10_000n
+
+/** Default fallback currencies for auto-swap, in priority order. */
+export const defaultCurrencies: readonly Address[] = [
+  defaults.tokens.pathUsd as Address,
+  defaults.tokens.usdc as Address,
+]
+
+/**
+ * Finds the optimal swap calls to acquire `amountOut` of `tokenOut`,
+ * returning an approve + buy call sequence if a viable route is found.
+ *
+ * Returns `undefined` if the account already holds enough of `tokenOut`
+ * or no viable swap route exists from the given input tokens.
+ */
+export async function findCalls(
+  client: Client,
+  parameters: findCalls.Parameters,
+): Promise<findCalls.ReturnType> {
+  const { account, amountOut, tokenOut, tokenIn, slippage } = parameters
+
+  const candidates = tokenIn.filter((t) => !isAddressEqual(t, tokenOut))
+
+  const balanceResults = await Promise.allSettled([
+    readContract(client, Actions.token.getBalance.call({ account, token: tokenOut }) as never),
+    ...candidates.map((t) =>
+      readContract(client, Actions.token.getBalance.call({ account, token: t }) as never),
+    ),
+  ])
+
+  // If the account already has enough of the target token, no swap needed.
+  const targetBalance = balanceResults[0]!
+  if (targetBalance.status === 'fulfilled' && (targetBalance.value as bigint) >= amountOut)
+    return undefined
+
+  // Find first candidate with enough balance to cover a swap.
+  for (let i = 0; i < candidates.length; i++) {
+    const result = balanceResults[i + 1]!
+    if (result.status !== 'fulfilled') continue
+
+    const balance = result.value as bigint
+    if (balance <= 0n) continue
+
+    const tokenIn = candidates[i]!
+
+    try {
+      const quotedAmountIn = await Actions.dex.getBuyQuote(client as never, {
+        tokenIn,
+        tokenOut,
+        amountOut,
+      })
+
+      if (balance >= quotedAmountIn) {
+        const maxAmountIn =
+          quotedAmountIn + (quotedAmountIn * BigInt(Math.round(slippage * 100))) / bps
+        return [
+          Actions.token.approve.call({
+            token: tokenIn,
+            spender: Addresses.stablecoinDex,
+            amount: maxAmountIn,
+          }),
+          Actions.dex.buy.call({
+            tokenIn,
+            tokenOut,
+            amountOut,
+            maxAmountIn,
+          }),
+        ]
+      }
+    } catch {}
+  }
+
+  throw new InsufficientFundsError({ currency: tokenOut })
+}
+
+export declare namespace findCalls {
+  type Parameters = {
+    /** Address of the account to check balances for. */
+    account: Address
+    /** Amount of the target token needed. */
+    amountOut: bigint
+    /** Candidate input tokens to swap from, in priority order. */
+    tokenIn: readonly Address[]
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). */
+    slippage: number
+    /** Address of the target token to acquire. */
+    tokenOut: Address
+  }
+
+  /** `undefined` when no swap is needed (account has sufficient balance). */
+  type ReturnType = readonly object[] | undefined
+}
+
+/** Resolves an auto-swap configuration value into concrete currencies and slippage. */
+export function resolve(
+  value: resolve.Value | undefined,
+  defaultCurrencies: readonly Address[],
+): resolve.Resolved | false {
+  if (!value) return false
+  if (value === true) return { tokenIn: defaultCurrencies, slippage: 1 }
+  const tokenIn = value.tokenIn
+    ? [
+        ...value.tokenIn,
+        ...defaultCurrencies.filter((d) => !value.tokenIn!.some((c) => isAddressEqual(c, d))),
+      ]
+    : defaultCurrencies
+  return {
+    tokenIn,
+    slippage: value.slippage ?? 1,
+  }
+}
+
+export declare namespace resolve {
+  type Options = {
+    /** Fallback tokens to try swapping from, in priority order. */
+    tokenIn?: Address[] | undefined
+    /** Max slippage tolerance as a percentage (e.g. `1` = 1%). @default 1 */
+    slippage?: number | undefined
+  }
+
+  type Value = boolean | Options
+
+  type Resolved = { tokenIn: readonly Address[]; slippage: number }
+}
+
+export class InsufficientFundsError extends Error {
+  override readonly name = 'InsufficientFundsError'
+
+  constructor({ currency }: { currency: Address }) {
+    super(
+      `Insufficient funds: no balance in ${currency} and no viable swap route from fallback currencies.`,
+    )
+  }
+}