mppx 0.3.12 → 0.3.14

package/src/Challenge.test.ts

@@ -250,12 +250,12 @@ describe('fromMethod', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       id: 'abc123',
       realm: 'api.example.com',
+      expires: '2025-01-06T12:00:00Z',
       request: {
         amount: '1',
         currency: '0x20c0000000000000000000000000000000000001',
         decimals: 6,
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
       },
     })
 
@@ -269,7 +269,6 @@ describe('fromMethod', () => {
         "request": {
           "amount": "1000000",
           "currency": "0x20c0000000000000000000000000000000000001",
-          "expires": "2025-01-06T12:00:00Z",
           "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
         },
       }
@@ -280,12 +279,12 @@ describe('fromMethod', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       id: 'abc123',
       realm: 'api.example.com',
+      expires: '2025-01-06T12:00:00Z',
       request: {
         amount: '1',
         currency: '0x20c0000000000000000000000000000000000001',
         decimals: 6,
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
         chainId: 42431,
         feePayer: true,
       },
@@ -301,7 +300,6 @@ describe('fromMethod', () => {
         "request": {
           "amount": "1000000",
           "currency": "0x20c0000000000000000000000000000000000001",
-          "expires": "2025-01-06T12:00:00Z",
           "methodDetails": {
             "chainId": 42431,
             "feePayer": true,
@@ -321,7 +319,6 @@ describe('fromMethod', () => {
         currency: '0x20c0000000000000000000000000000000000001',
         decimals: 6,
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
       },
       digest: 'sha-256=abc',
       expires: '2025-01-06T12:00:00Z',
@@ -334,12 +331,12 @@ describe('fromMethod', () => {
   test('behavior: creates challenge with HMAC-bound id via secretKey', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       realm: 'api.example.com',
+      expires: '2025-01-06T12:00:00Z',
       request: {
         amount: '1',
         currency: '0x20c0000000000000000000000000000000000001',
         decimals: 6,
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
       },
       secretKey: 'my-secret',
     })
@@ -358,7 +355,6 @@ describe('fromMethod', () => {
           amount: 123,
           currency: '0x20c0000000000000000000000000000000000001',
           recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-          expires: '2025-01-06T12:00:00Z',
         } as any,
       }),
     ).toThrow()
@@ -402,17 +398,18 @@ describe('serialize', () => {
 })
 
 describe('deserialize', () => {
-  test('behavior: deserializes WWW-Authenticate header', () => {
-    const original = Challenge.from({
+  const paymentHeader = Challenge.serialize(
+    Challenge.from({
       id: 'abc123',
       realm: 'api.example.com',
       method: 'tempo',
       intent: 'charge',
       request: { amount: '1000000', currency: 'USD' },
-    })
+    }),
+  )
 
-    const header = Challenge.serialize(original)
-    const challenge = Challenge.deserialize(header)
+  test('behavior: deserializes WWW-Authenticate header', () => {
+    const challenge = Challenge.deserialize(paymentHeader)
 
     expect(challenge).toMatchInlineSnapshot(`
       {
@@ -446,20 +443,100 @@ describe('deserialize', () => {
     expect(challenge?.expires).toBe('2025-01-06T12:00:00Z')
   })
 
-  test('error: throws for missing Payment scheme', () => {
-    expect(() => Challenge.deserialize('Bearer token')).toThrow('Missing Payment scheme.')
+  test.each([
+    { name: 'single Payment scheme', header: paymentHeader },
+    { name: 'Payment after another scheme', header: `Bearer realm="api", ${paymentHeader}` },
+    {
+      name: 'scheme token is case-insensitive',
+      header: paymentHeader.replace(/^Payment /, 'payment '),
+    },
+    {
+      name: 'quoted values in previous schemes do not interfere',
+      header: `Bearer error_description="retry with Payment challenge", ${paymentHeader}`,
+    },
+    {
+      name: 'parses Payment params before the next scheme token',
+      header: `${paymentHeader}, Bearer realm="fallback"`,
+    },
+  ])('behavior: extracts challenge for $name', ({ header }) => {
+    const challenge = Challenge.deserialize(header)
+
+    expect(challenge.id).toBe('abc123')
+    expect(challenge.method).toBe('tempo')
+    expect(challenge.intent).toBe('charge')
+  })
+
+  const request = /request="([^"]+)"/.exec(paymentHeader)?.[1]
+  if (!request) throw new Error('request missing from serialized challenge')
+
+  test.each([
+    {
+      name: 'escaped quotes',
+      headerValue: 'premium \\"access\\"',
+      expected: 'premium "access"',
+    },
+    {
+      name: 'escaped comma',
+      headerValue: 'tier\\,premium',
+      expected: 'tier,premium',
+    },
+    {
+      name: 'escaped backslash',
+      headerValue: 'path\\\\alpha',
+      expected: 'path\\alpha',
+    },
+  ])('behavior: deserializes $name in quoted-string values', ({ headerValue, expected }) => {
+    const header =
+      'Payment id="abc123", realm="api.example.com", method="tempo", intent="charge", request="' +
+      request +
+      `", description="${headerValue}"`
+
+    const challenge = Challenge.deserialize(header)
+    expect(challenge.description).toBe(expected)
+  })
+
+  test.each([
+    {
+      name: 'missing Payment scheme',
+      header: 'Bearer token',
+      error: 'Missing Payment scheme.',
+    },
+    {
+      name: 'duplicate parameters',
+      header: 'Payment id="a", realm="api", method="tempo", intent="charge", request="e30", id="b"',
+      error: 'Duplicate parameter: id',
+    },
+    {
+      name: 'unterminated quoted-string',
+      header:
+        'Payment id="a", realm="api", method="tempo", intent="charge", request="e30", description="oops',
+      error: 'Unterminated quoted-string.',
+    },
+    {
+      name: 'invalid method casing',
+      header: 'Payment id="a", realm="api", method="Tempo", intent="charge", request="e30"',
+      error: 'Invalid method: "Tempo". Must be lowercase per spec.',
+    },
+    {
+      name: 'malformed auth-param',
+      header:
+        'Payment id="a", realm="api", method="tempo", intent="charge", request="e30", ="value"',
+      error: 'Malformed auth-param.',
+    },
+  ])('error: throws for $name', ({ header, error }) => {
+    expect(() => Challenge.deserialize(header)).toThrow(error)
   })
 
   test('error: missing required fields', () => {
     expect(() => Challenge.deserialize('Payment realm="test"')).toThrow()
   })
 
-  test('error: throws for duplicate parameters', () => {
+  test('error: missing request parameter after valid Payment scheme', () => {
     expect(() =>
       Challenge.deserialize(
-        'Payment id="a", realm="api", method="tempo", intent="charge", request="e30", id="b"',
+        'Bearer realm="api", Payment id="a", realm="api", method="tempo", intent="charge"',
       ),
-    ).toThrow('Duplicate parameter: id')
+    ).toThrow('Missing request parameter.')
   })
 })
 
@@ -584,7 +661,6 @@ describe('opaque', () => {
         currency: '0x20c0000000000000000000000000000000000001',
         decimals: 6,
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
       },
       meta: { payment_intent: 'pi_3abc123XYZ' },
     })

package/src/Challenge.ts

@@ -125,7 +125,7 @@ export function from<
     secretKey,
   } = parameters
 
-  const expires = (parameters.expires ?? request.expires) as string
+  const expires = parameters.expires as string
   const id = secretKey
     ? computeId({ ...parameters, expires, ...(meta && { opaque: meta }) }, { secretKey })
     : (parameters as { id: string }).id
@@ -205,11 +205,11 @@ export declare namespace from {
  *   Methods.charge,
  *   {
  *     realm: 'api.example.com',
+ *     expires: '2025-01-06T12:00:00Z',
  *     request: {
  *       amount: '1000000',
  *       currency: '0x20c0000000000000000000000000000000000001',
  *       recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
- *       expires: '2025-01-06T12:00:00Z',
  *     },
  *   },
  *   { secretKey: 'my-secret' },
@@ -319,20 +319,10 @@ export function deserialize<const methods extends readonly Method.Method[] | und
   value: string,
   options?: from.Options<methods>,
 ): from.ReturnType<from.Parameters, methods> {
-  const prefixMatch = value.match(/^Payment\s+(.+)$/i)
-  if (!prefixMatch?.[1]) throw new Error('Missing Payment scheme.')
+  const params = extractPaymentAuthParams(value)
+  if (!params) throw new Error('Missing Payment scheme.')
 
-  const params = prefixMatch[1]
-  const result: Record<string, string> = {}
-
-  for (const match of params.matchAll(/(\w+)="([^"]+)"/g)) {
-    const key = match[1]
-    const value = match[2]
-    if (key && value) {
-      if (key in result) throw new Error(`Duplicate parameter: ${key}`)
-      result[key] = value
-    }
-  }
+  const result = parseAuthParams(params)
 
   const { request, opaque, ...rest } = result
   if (!request) throw new Error('Missing request parameter.')
@@ -349,6 +339,119 @@ export function deserialize<const methods extends readonly Method.Method[] | und
   )
 }
 
+/** @internal Extracts the `Payment` scheme from a WWW-Authenticate value that may contain multiple schemes. */
+function extractPaymentAuthParams(header: string): string | null {
+  const token = 'Payment'
+  let inQuotes = false
+  let escaped = false
+
+  for (let i = 0; i < header.length; i++) {
+    const char = header[i]
+
+    if (inQuotes) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inQuotes = false
+      continue
+    }
+
+    if (char === '"') {
+      inQuotes = true
+      continue
+    }
+
+    if (!startsWithSchemeToken(header, i, token)) continue
+
+    const prefix = header.slice(0, i)
+    if (prefix.trim() && !prefix.trimEnd().endsWith(',')) continue
+
+    let paramsStart = i + token.length
+    while (paramsStart < header.length && /\s/.test(header[paramsStart] ?? '')) paramsStart++
+    return header.slice(paramsStart)
+  }
+
+  return null
+}
+
+/** @internal Parses auth-params with support for escaped quoted-string values. */
+function parseAuthParams(input: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  let i = 0
+
+  while (i < input.length) {
+    while (i < input.length && /[\s,]/.test(input[i] ?? '')) i++
+    if (i >= input.length) break
+
+    const keyStart = i
+    while (i < input.length && /[A-Za-z0-9_-]/.test(input[i] ?? '')) i++
+    const key = input.slice(keyStart, i)
+    if (!key) throw new Error('Malformed auth-param.')
+
+    while (i < input.length && /\s/.test(input[i] ?? '')) i++
+
+    // If there is no '=' after a token, this is likely another auth scheme.
+    if (input[i] !== '=') break
+    i++
+
+    while (i < input.length && /\s/.test(input[i] ?? '')) i++
+
+    const [value, nextIndex] = readAuthParamValue(input, i)
+    i = nextIndex
+
+    if (key in result) throw new Error(`Duplicate parameter: ${key}`)
+    result[key] = value
+  }
+
+  return result
+}
+
+/** @internal */
+function readAuthParamValue(input: string, start: number): [value: string, nextIndex: number] {
+  if (input[start] === '"') return readQuotedAuthParamValue(input, start + 1)
+
+  let i = start
+  while (i < input.length && input[i] !== ',') i++
+  return [input.slice(start, i).trim(), i]
+}
+
+/** @internal */
+function readQuotedAuthParamValue(
+  input: string,
+  start: number,
+): [value: string, nextIndex: number] {
+  let i = start
+  let value = ''
+  let escaped = false
+
+  while (i < input.length) {
+    const char = input[i]!
+    i++
+
+    if (escaped) {
+      value += char
+      escaped = false
+      continue
+    }
+
+    if (char === '\\') {
+      escaped = true
+      continue
+    }
+
+    if (char === '"') return [value, i]
+    value += char
+  }
+
+  throw new Error('Unterminated quoted-string.')
+}
+
+/** @internal */
+function startsWithSchemeToken(value: string, index: number, token: string): boolean {
+  if (!value.slice(index).toLowerCase().startsWith(token.toLowerCase())) return false
+  const next = value[index + token.length]
+  return Boolean(next && /\s/.test(next))
+}
+
 /**
  * Extracts the challenge from a Headers object.
  *

package/src/PaymentRequest.test.ts

@@ -26,13 +26,11 @@ describe('fromMethod', () => {
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
       recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-      expires: '2025-01-06T12:00:00Z',
     })
     expect(request).toMatchInlineSnapshot(`
       {
         "amount": "1000000",
         "currency": "0x20c0000000000000000000000000000000000001",
-        "expires": "2025-01-06T12:00:00Z",
         "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
       }
     `)
@@ -44,14 +42,12 @@ describe('fromMethod', () => {
       currency: '0x20c0000000000000000000000000000000000001',
       decimals: 6,
       recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-      expires: '2025-01-06T12:00:00Z',
       chainId: 42431,
     })
     expect(request).toMatchInlineSnapshot(`
       {
         "amount": "1000000",
         "currency": "0x20c0000000000000000000000000000000000001",
-        "expires": "2025-01-06T12:00:00Z",
         "methodDetails": {
           "chainId": 42431,
         },
@@ -66,7 +62,6 @@ describe('fromMethod', () => {
         amount: 123,
         currency: '0x20c0000000000000000000000000000000000001',
         recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-        expires: '2025-01-06T12:00:00Z',
       } as any),
     ).toThrowErrorMatchingInlineSnapshot(`
       [$ZodError: [

package/src/client/Mppx.test.ts

@@ -82,12 +82,12 @@ describe('createCredential', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       realm,
       secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '1000',
         currency: '0x1234567890123456789012345678901234567890',
         decimals: 6,
         recipient: '0x1234567890123456789012345678901234567890',
-        expires: new Date(Date.now() + 60_000).toISOString(),
       },
     })
 
@@ -164,11 +164,11 @@ describe('createCredential', () => {
       realm,
       method: 'stripe',
       intent: 'charge',
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '2000',
         currency: '0xabcd',
         recipient: '0xefgh',
-        expires: new Date(Date.now() + 60_000).toISOString(),
       },
     })
 
@@ -195,12 +195,12 @@ describe('createCredential', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       realm,
       secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '1000',
         currency: '0x1234567890123456789012345678901234567890',
         decimals: 6,
         recipient: '0x1234567890123456789012345678901234567890',
-        expires: new Date(Date.now() + 60_000).toISOString(),
       },
     })
 
@@ -227,12 +227,12 @@ describe('createCredential', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       realm,
       secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '1000',
         currency: '0x1234567890123456789012345678901234567890',
         decimals: 6,
         recipient: '0x1234567890123456789012345678901234567890',
-        expires: new Date(Date.now() + 60_000).toISOString(),
       },
     })
 
@@ -258,12 +258,12 @@ describe('createCredential', () => {
     const challenge = Challenge.fromMethod(Methods.charge, {
       realm,
       secretKey,
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '1000',
         currency: '0x1234567890123456789012345678901234567890',
         decimals: 6,
         recipient: '0x1234567890123456789012345678901234567890',
-        expires: new Date(Date.now() + 60_000).toISOString(),
       },
     })
 

package/src/client/Transport.test.ts

@@ -9,12 +9,12 @@ const secretKey = 'test-secret-key'
 const challenge = Challenge.fromMethod(Methods.charge, {
   realm,
   secretKey,
+  expires: '2025-01-01T00:00:00.000Z',
   request: {
     amount: '0.001',
     currency: '0x20c0000000000000000000000000000000000001',
     decimals: 6,
     recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
-    expires: '2025-01-01T00:00:00.000Z',
   },
 })
 
@@ -60,14 +60,13 @@ describe('http', () => {
       expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
         {
           "expires": "2025-01-01T00:00:00.000Z",
-          "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
+          "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
           "intent": "charge",
           "method": "tempo",
           "realm": "api.example.com",
           "request": {
             "amount": "1000",
             "currency": "0x20c0000000000000000000000000000000000001",
-            "expires": "2025-01-01T00:00:00.000Z",
             "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
           },
         }
@@ -91,7 +90,7 @@ describe('http', () => {
       const headers = result.headers as Headers
 
       expect(headers.get('Authorization')).toMatchInlineSnapshot(
-        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiejhkVWk2MWxWaU9qNmN3aF9JU2JfNVg4bkJKRjJPalR5ZGNFYXA4d1gwbyIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKaGJXOTFiblFpT2lJeE1EQXdJaXdpWTNWeWNtVnVZM2tpT2lJd2VESXdZekF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREVpTENKbGVIQnBjbVZ6SWpvaU1qQXlOUzB3TVMwd01WUXdNRG93TURvd01DNHdNREJhSWl3aWNtVmphWEJwWlc1MElqb2lNSGczTkRKa016VkRZelkyTXpSRE1EVXpNamt5TldFellqZzBORUpqT1dVM05UazFaamhtUlRBd0luMCJ9LCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4YWJjMTIzIiwidHlwZSI6InRyYW5zYWN0aW9uIn19"`,
+        `"Payment eyJjaGFsbGVuZ2UiOnsiZXhwaXJlcyI6IjIwMjUtMDEtMDFUMDA6MDA6MDAuMDAwWiIsImlkIjoiMGhucnlTUkRxV2Z0dGxESUpwdXhWNG1Kc1JKSVM3ZDdSam51ZnVvbkpPRSIsImludGVudCI6ImNoYXJnZSIsIm1ldGhvZCI6InRlbXBvIiwicmVhbG0iOiJhcGkuZXhhbXBsZS5jb20iLCJyZXF1ZXN0IjoiZXlKaGJXOTFiblFpT2lJeE1EQXdJaXdpWTNWeWNtVnVZM2tpT2lJd2VESXdZekF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREF3TURBd01EQXdNREVpTENKeVpXTnBjR2xsYm5RaU9pSXdlRGMwTW1Rek5VTmpOall6TkVNd05UTXlPVEkxWVROaU9EUTBRbU01WlRjMU9UVm1PR1pGTURBaWZRIn0sInBheWxvYWQiOnsic2lnbmF0dXJlIjoiMHhhYmMxMjMiLCJ0eXBlIjoidHJhbnNhY3Rpb24ifX0"`,
       )
     })
 
@@ -182,14 +181,13 @@ describe('mcp', () => {
       expect(transport.getChallenge(response)).toMatchInlineSnapshot(`
         {
           "expires": "2025-01-01T00:00:00.000Z",
-          "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
+          "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
           "intent": "charge",
           "method": "tempo",
           "realm": "api.example.com",
           "request": {
             "amount": "1000",
             "currency": "0x20c0000000000000000000000000000000000001",
-            "expires": "2025-01-01T00:00:00.000Z",
             "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
           },
         }
@@ -239,14 +237,13 @@ describe('mcp', () => {
               "org.paymentauth/credential": {
                 "challenge": {
                   "expires": "2025-01-01T00:00:00.000Z",
-                  "id": "z8dUi61lViOj6cwh_ISb_5X8nBJF2OjTydcEap8wX0o",
+                  "id": "0hnrySRDqWfttlDIJpuxV4mJsRJIS7d7RjnufuonJOE",
                   "intent": "charge",
                   "method": "tempo",
                   "realm": "api.example.com",
                   "request": {
                     "amount": "1000",
                     "currency": "0x20c0000000000000000000000000000000000001",
-                    "expires": "2025-01-01T00:00:00.000Z",
                     "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
                   },
                 },

package/src/client/internal/Fetch.browser.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test, vi } from 'vitest'
+import * as Fetch from './Fetch.js'
+
+const noopMethod = {
+  name: 'test',
+  intent: 'test',
+  context: undefined,
+  createCredential: async () => 'credential',
+} as any
+
+function make402() {
+  const request = btoa(JSON.stringify({ amount: '1' }))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+  return new Response(null, {
+    status: 402,
+    headers: {
+      'WWW-Authenticate': `Payment id="abc", realm="test", method="test", intent="test", request="${request}"`,
+    },
+  })
+}
+
+/** Returns a fetch wrapper and the init captured from the 402 retry call. */
+function setup() {
+  const calls: (RequestInit | undefined)[] = []
+  let callCount = 0
+  const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+    calls.push(init)
+    callCount++
+    if (callCount === 1) return make402()
+    return new Response('OK', { status: 200 })
+  }
+  const fetch = Fetch.from({ fetch: mockFetch, methods: [noopMethod] })
+  return {
+    fetch,
+    /** Headers sent on the retry (second) request. */
+    retryHeaders: async (input: RequestInfo | URL, init?: RequestInit) => {
+      await fetch(input, init)
+      return (calls[1] as Record<string, unknown>)?.headers as Record<string, string>
+    },
+  }
+}
+
+describe('Fetch.from: browser header normalization', () => {
+  test('preserves Headers instance', async () => {
+    const { retryHeaders } = setup()
+    const h = await retryHeaders('https://example.com', {
+      headers: new Headers({ 'X-Custom': 'value', 'Content-Type': 'application/json' }),
+    })
+    expect(h['x-custom']).toBe('value')
+    expect(h['content-type']).toBe('application/json')
+    expect(h.Authorization).toBe('credential')
+  })
+
+  test('preserves header tuples', async () => {
+    const { retryHeaders } = setup()
+    const h = await retryHeaders('https://example.com', {
+      headers: [
+        ['X-Custom', 'value'],
+        ['Accept', 'application/json'],
+      ],
+    })
+    expect(h['X-Custom']).toBe('value')
+    expect(h.Accept).toBe('application/json')
+    expect(h.Authorization).toBe('credential')
+  })
+
+  test('replaces authorization case-insensitively', async () => {
+    const { retryHeaders } = setup()
+    const h = await retryHeaders('https://example.com', {
+      headers: { authorization: 'Bearer stale', 'X-Custom': 'value' },
+    })
+    expect(h.authorization).toBeUndefined()
+    expect(h.Authorization).toBe('credential')
+    expect(h['X-Custom']).toBe('value')
+  })
+
+  test('preserves plain object headers', async () => {
+    const { retryHeaders } = setup()
+    const h = await retryHeaders('https://example.com', { headers: { 'X-Custom': 'val' } })
+    expect(h['X-Custom']).toBe('val')
+    expect(h.Authorization).toBe('credential')
+  })
+
+  test('adds Authorization when no headers provided', async () => {
+    const { retryHeaders } = setup()
+    const h = await retryHeaders('https://example.com')
+    expect(h.Authorization).toBe('credential')
+  })
+})
+
+describe('Fetch.polyfill / restore: browser', () => {
+  test('restore is a no-op when polyfill was never called', () => {
+    const before = globalThis.fetch
+    Fetch.restore()
+    expect(globalThis.fetch).toBe(before)
+  })
+
+  test('restore reverts to original fetch', () => {
+    const original = globalThis.fetch
+    Fetch.polyfill({ methods: [noopMethod] })
+    expect(globalThis.fetch).not.toBe(original)
+    Fetch.restore()
+    expect(globalThis.fetch).toBe(original)
+  })
+
+  test('stacked polyfill calls preserve the true original', () => {
+    const original = globalThis.fetch
+    Fetch.polyfill({ methods: [noopMethod] })
+    Fetch.polyfill({ methods: [noopMethod] })
+    Fetch.restore()
+    expect(globalThis.fetch).toBe(original)
+  })
+
+  test('double restore does not clobber fetch', () => {
+    const original = globalThis.fetch
+    Fetch.polyfill({ methods: [noopMethod] })
+    Fetch.restore()
+    Fetch.restore()
+    expect(globalThis.fetch).toBe(original)
+  })
+
+  test('restore is a no-op when fetch was replaced externally', () => {
+    const original = globalThis.fetch
+    const external = vi.fn(
+      async () => new Response('external'),
+    ) as unknown as typeof globalThis.fetch
+    Fetch.polyfill({ methods: [noopMethod] })
+    globalThis.fetch = external
+    Fetch.restore()
+    expect(globalThis.fetch).toBe(external)
+    globalThis.fetch = original
+  })
+})