fast-uri 4.1.4 → 4.2.0

package/README.md

@@ -99,6 +99,7 @@ fast-uri supports inserting custom [scheme](https://en.wikipedia.org/wiki/URI_sc
 *	wss \[[RFC 6455](https://www.ietf.org/rfc/rfc6455.txt)\]
 *	urn \[[RFC 2141](https://www.ietf.org/rfc/rfc2141.txt)\]
 *	urn:uuid \[[RFC 4122](https://www.ietf.org/rfc/rfc4122.txt)\]
+*	mailto \[[RFC 6068](https://www.rfc-editor.org/rfc/rfc6068)\]
 
 
 ## Benchmarks

package/SECURITY.md

@@ -15,38 +15,87 @@ Reports based solely on comparing or mixing parsers that follow these different
 standards are out of scope. Applications must use the same parsing and
 normalization rules for both security decisions and subsequent URI use.
 
+A WHATWG comparison may be useful supporting evidence, but a parser difference
+is not by itself a vulnerability. A report remains in scope when it independently
+demonstrates a defect in `fast-uri`'s RFC or documented behavior for a supported
+scheme and a concrete security impact when the application uses `fast-uri`
+consistently. An exploit that requires validating with `fast-uri` and then
+passing the original, unmodified input to a parser with different rules is an
+application parser-confusion issue.
+
 Reports are assessed based on reproducibility, documented supported usage, and
 concrete security impact—not merely on whether they mention WHATWG URL
-behavior. Reports demonstrating a parsing or normalization flaw in a supported
-scheme remain eligible for evaluation.
+behavior.
 
 ## Threat model
 
 `fast-uri`'s threat model extends the
 [Node.js threat model](https://github.com/nodejs/node/blob/main/SECURITY.md#the-nodejs-threat-model).
 
-**Trusted:** Application code, parser options, configuration, and the runtime
-environment.
+**Trusted:** Application code, structured component objects constructed or
+modified by application code and passed directly to `serialize()`, parser
+options, configuration, and the runtime environment.
 
 **Untrusted:** URI and IRI strings passed to the package's public APIs.
 
+## Vulnerability classification
+
+A report is treated as a vulnerability when it demonstrates all of the
+following:
+
+1. Attacker-controlled input reaches a public API through documented,
+   supported usage.
+2. `fast-uri` violates an applicable RFC or its documented API contract.
+3. The defect creates a concrete confidentiality, integrity, or availability
+   impact in a realistic supported use case.
+4. The impact does not depend solely on application misuse, an unsupported
+   scheme, a different parser interpreting the original input, or another
+   package's behavior.
+
+A reproducible bug can still merit a normal issue and fix without meeting the
+security-vulnerability threshold.
+
 ### Examples of vulnerabilities
 
-- RFC 3986 parsing or normalization flaws that bypass security controls
-- Denial of service through malformed input
-- Inconsistent parsing or normalization between `fast-uri` APIs
+- `parse()`, `normalize()`, or `resolve()` changes an attacker-controlled
+  authority within `fast-uri`, and the report demonstrates a host security
+  control being bypassed using that output
+- `equal()` aliases distinct URIs under the rules of a supported scheme, and
+  the report demonstrates an authorization, signature, or cache boundary being
+  bypassed
+- One public API call on a reasonably sized malformed URI causes
+  disproportionate CPU or memory consumption, with reproducible availability
+  impact
+- Parsing or normalization turns component data into a structural delimiter
+  and the report demonstrates a security-control bypass in documented usage
+
+### Denial-of-service reports
+
+A synchronous exception, parse error, or non-idempotent result is not by itself
+a denial-of-service vulnerability. A report must demonstrate disproportionate
+resource consumption in a public API call, or loss of availability in a
+supported deployment despite normal exception handling. An application that
+terminates on an uncaught exception, or repeatedly normalizes until reaching a
+fixpoint, does not establish a package vulnerability by itself.
 
 ### Examples of non-vulnerabilities
 
 The following are **not** considered vulnerabilities in `fast-uri`:
 
-- **Different URL standards:** Differences between RFC 3986 behavior and
-  WHATWG URL behavior, including differences exposed by mixing parsers that
-  implement those standards
-- **Unsupported scheme semantics:** Scheme-specific behavior for schemes that
-  `fast-uri` does not document as supported
+- **Different URL standards:** `fast-uri` returns one host, but an application
+  passes the original input to WHATWG `URL`, `fetch`, or another parser that
+  applies different recovery, whitespace, or legacy-IP rules
+- **Unsupported scheme semantics:** Behavior specific to schemes such as
+  `ftp` or `file`, which `fast-uri` does not document as supported
+- **Correctness without security impact:** Non-idempotent normalization,
+  surprising equality, truncation, re-encoding, or malformed-input handling
+  without a demonstrated security boundary or availability impact
+- **Caller-created resource use:** An application repeatedly parses or
+  normalizes a value, or fails to catch a synchronous exception
+- **Trusted structured input:** Boundary characters supplied in a component
+  object that application code constructs and passes to `serialize()`
 - **Application code vulnerabilities:** Security flaws in code that consumes
-  `fast-uri` output
+  `fast-uri` output contrary to its documented contract
 - **Configuration mistakes:** Security issues caused by incorrect parser
   options or application configuration
 - **Missing security features:** Application-level protections that are not

package/index.js

@@ -89,6 +89,22 @@ function resolve (baseURI, relativeURI, options) {
   return serialize(resolved, schemelessOptions)
 }
 
+/**
+ * Copies a host component together with its parse-time zone identifier (if
+ * any), so downstream recomposition does not re-derive an IPv6 zone from the
+ * ambiguous single-"%" component form. The zone is validated on use by
+ * `recomposeAuthority` rather than blindly trusted.
+ *
+ * @param {import('./types/index').URIComponent} target
+ * @param {import('./types/index').URIComponent} source
+ */
+function copyHost (target, source) {
+  target.host = source.host
+  if (source.ipv6Zone !== undefined) {
+    target.ipv6Zone = source.ipv6Zone
+  }
+}
+
 /**
  * @param {import ('./types/index').URIComponent} base
  * @param {import ('./types/index').URIComponent} relative
@@ -109,7 +125,7 @@ function resolveComponent (base, relative, options, skipNormalization) {
     target.scheme = relative.scheme
     // target.authority = relative.authority;
     target.userinfo = relative.userinfo
-    target.host = relative.host
+    copyHost(target, relative)
     target.port = relative.port
     target.path = removeDotSegments(relative.path || '')
     target.query = relative.query
@@ -117,7 +133,7 @@ function resolveComponent (base, relative, options, skipNormalization) {
     if (relative.userinfo !== undefined || relative.host !== undefined || relative.port !== undefined) {
       // target.authority = relative.authority;
       target.userinfo = relative.userinfo
-      target.host = relative.host
+      copyHost(target, relative)
       target.port = relative.port
       target.path = removeDotSegments(relative.path || '')
       target.query = relative.query
@@ -146,7 +162,7 @@ function resolveComponent (base, relative, options, skipNormalization) {
       }
       // target.authority = base.authority;
       target.userinfo = base.userinfo
-      target.host = base.host
+      copyHost(target, base)
       target.port = base.port
     }
     target.scheme = base.scheme
@@ -178,6 +194,7 @@ function equal (uriA, uriB, options) {
 function serialize (cmpts, opts) {
   const component = {
     host: cmpts.host,
+    ipv6Zone: cmpts.ipv6Zone,
     scheme: cmpts.scheme,
     userinfo: cmpts.userinfo,
     port: cmpts.port,
@@ -506,6 +523,16 @@ function parseWithStatus (uri, opts) {
         malformedIPLiteral = hasIPLiteralBracket && (!bracketedIPLiteral || ipv6result.error === true)
         parsed.host = isIP ? ipv6result.host : ipv6result.host.toLowerCase()
 
+        if (isIP && ipv6result.isIPV6 === true && parsed.host.indexOf('%') !== -1) {
+          // Persist the zone identifier so recomposition never has to re-derive
+          // it from the ambiguous single-"%" component form, which misreads a
+          // zone that begins with "25" as a %25 separator. It is validated on
+          // use during recomposition, so a host reassigned after parse or an
+          // input zone that does not describe the host is ignored. Only zoned
+          // literals are ambiguous; plain IPv6 addresses round-trip without it.
+          parsed.ipv6Zone = parsed.host.slice(parsed.host.indexOf('%') + 1)
+        }
+
         if (malformedIPLiteral) {
           parsed.error = parsed.error || 'URI host is malformed.'
           malformedAuthorityOrPort = true
@@ -537,13 +564,17 @@ function parseWithStatus (uri, opts) {
       malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP)
     }
 
-    if (!schemeHandler || (schemeHandler && !schemeHandler.skipNormalize)) {
-      if (uri.indexOf('%') !== -1) {
-        if (parsed.host !== undefined && !malformedIPLiteral) {
-          const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true)
-          parsed.host = reescapeHostDelimiters(host, isIP)
-        }
+    if (uri.indexOf('%') !== -1 && parsed.host !== undefined && !malformedIPLiteral) {
+      let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true)
+      if (!isIP) {
+        // Fold reg-name case after decoding unreserved octets. The second
+        // pass only restores uppercase hex in escapes that remain encoded.
+        host = normalizePercentEncoding(host.toLowerCase())
       }
+      parsed.host = reescapeHostDelimiters(host, isIP)
+    }
+
+    if (!schemeHandler || (schemeHandler && !schemeHandler.skipNormalize)) {
       if (parsed.path) {
         parsed.path = normalizePathEncoding(parsed.path)
       }

package/lib/schemes.js

@@ -495,23 +495,24 @@ function mailtoParse (component, options) {
         mailtoComponent.error = mailtoComponent.error || 'URI mailto has malformed header fields.'
         continue
       }
-      const name = eqIdx === -1 ? token : token.slice(0, eqIdx)
+      const name = decodeHex(eqIdx === -1 ? token : token.slice(0, eqIdx))
+      const normalizedName = name.toLowerCase()
       const value = eqIdx === -1 ? '' : token.slice(eqIdx + 1)
-      if (name === 'to') {
+      if (normalizedName === 'to') {
         const addrs = value.split(',')
         for (let j = 0; j < addrs.length; j++) to.push(addrs[j])
         continue
       }
-      if (name === 'subject') {
+      if (normalizedName === 'subject') {
         mailtoComponent.subject = decodeHex(value)
         continue
       }
-      if (name === 'body') {
+      if (normalizedName === 'body') {
         mailtoComponent.body = decodeHex(value)
         continue
       }
       if (headers === null) headers = /** @type {Record<string,string>} */ (Object.create(null))
-      headers[decodeHex(name)] = decodeHex(value)
+      headers[name] = decodeHex(value)
     }
     if (headers !== null) mailtoComponent.headers = headers
   }
@@ -536,6 +537,18 @@ function mailtoParse (component, options) {
   return mailtoComponent
 }
 
+/**
+ * Encodes a decoded mailto header name. Unlike `encodeWithAllow`, a percent
+ * sign is always data here, even when followed by two hex digits. Preserving
+ * such a sequence as an existing escape would decode the name again on the
+ * next parse and could turn a generic header into `to`, `subject`, or `body`.
+ * @param {string} name
+ * @returns {string}
+ */
+function mailtoEncodeHeaderName (name) {
+  return encodeWithAllow(name.replace(/%/gu, '%25'), HFNAME)
+}
+
 /**
  * @param {import('../types/index').URIComponent} component
  * @param {import('../types/index').Options} options
@@ -544,6 +557,31 @@ function mailtoParse (component, options) {
 function mailtoSerialize (component, options) {
   const mailtoComponent = component
   const to = Array.isArray(mailtoComponent.to) ? mailtoComponent.to.slice() : []
+  const sourceHeaders = mailtoComponent.headers && typeof mailtoComponent.headers === 'object'
+    ? Object.assign(Object.create(null), mailtoComponent.headers)
+    : Object.create(null)
+  const headers = Object.create(null)
+
+  // Header field names are case-insensitive. Canonicalize the fields with
+  // dedicated component properties so callers cannot smuggle a second spelling
+  // through `headers`. As during parsing, all `to` fields are accumulated;
+  // repeated subject/body fields use the last value.
+  for (const name in sourceHeaders) {
+    const normalizedName = name.toLowerCase()
+    if (normalizedName === 'to') {
+      const addrs = String(sourceHeaders[name]).split(',')
+      for (let i = 0; i < addrs.length; i++) to.push(addrs[i])
+    } else if (normalizedName === 'subject' || normalizedName === 'body') {
+      headers[normalizedName] = sourceHeaders[name]
+    } else {
+      headers[name] = sourceHeaders[name]
+    }
+  }
+
+  if (mailtoComponent.subject !== undefined) headers.subject = mailtoComponent.subject
+  if (mailtoComponent.body !== undefined) headers.body = mailtoComponent.body
+  mailtoComponent.headers = headers
+
   if (to.length) {
     for (let i = 0; i < to.length; i++) {
       const addr = String(to[i])
@@ -570,21 +608,13 @@ function mailtoSerialize (component, options) {
     mailtoComponent.path = undefined
   }
 
-  const headers = mailtoComponent.headers && typeof mailtoComponent.headers === 'object'
-    ? Object.assign(Object.create(null), mailtoComponent.headers)
-    : Object.create(null)
-
-  if (mailtoComponent.subject) headers.subject = mailtoComponent.subject
-  if (mailtoComponent.body) headers.body = mailtoComponent.body
-  mailtoComponent.headers = headers
-
-  // `headers` has a null prototype and was filled via Object.assign, so every
-  // enumerable key is an own property and no hasOwnProperty guard is needed.
+  // `headers` has a null prototype, so every enumerable key is an own property
+  // and no hasOwnProperty guard is needed.
   let query = ''
   let count = 0
   for (const name in headers) {
     if (count++ !== 0) query += '&'
-    query += encodeWithAllow(name, HFNAME) + '=' + encodeWithAllow(String(headers[name]), HFNAME)
+    query += mailtoEncodeHeaderName(name) + '=' + encodeWithAllow(String(headers[name]), HFNAME)
   }
 
   if (count !== 0) {

package/lib/utils.js

@@ -740,6 +740,37 @@ function escapePreservingEscapes (input) {
   return output
 }
 
+/**
+ * Rebuilds the bracketed form of a zoned IPv6 authority from the current
+ * `component.host` and its zone identifier (`component.ipv6Zone`), but only
+ * when they are consistent and describe a real zoned IPv6 literal that
+ * normalizes back to `component.host`. This validates the zone on use, so a
+ * caller-supplied `ipv6Zone` that does not match the host (or a host
+ * reassigned after `parse`) is never trusted and recomposition falls back to
+ * the normal path.
+ *
+ * @param {import('../types/index').URIComponent} component
+ * @returns {string|undefined}
+ */
+function recomposeZonedIPv6Host (component) {
+  const zone = component.ipv6Zone
+  // Without an ipv6Zone the single-"%" host form is genuinely ambiguous when
+  // the zone begins with "25", so we fall through to the best-effort heuristic
+  // (which matches the pre-existing behavior for hand-built components that do
+  // not carry a zone).
+  if (zone === undefined) return undefined
+  const host = component.host
+  const separator = host.indexOf('%')
+  if (separator === -1) return undefined
+  const address = host.slice(0, separator)
+  const escaped = address + '%25' + zone
+  const derived = normalizeIPv6('[' + escaped + ']')
+  if (derived.isIPV6 === true && derived.host === host) {
+    return '[' + escaped + ']'
+  }
+  return undefined
+}
+
 /**
  * @param {import('../types/index').URIComponent} component
  * @returns {string|undefined}
@@ -755,17 +786,30 @@ function recomposeAuthority (component) {
   if (component.host !== undefined) {
     let host = component.host
     if (!isIPv4(host)) {
-      let ipV6res = normalizeIPv6(host)
-      if (ipV6res.isIPV6 !== true && ipV6res.isIPVFuture !== true) {
-        // Decode only unreserved bytes, once. In particular, keep %25 encoded
-        // so it cannot introduce a second escape during recomposition.
-        host = normalizePercentEncoding(host, true)
-        ipV6res = normalizeIPv6(host)
-      }
-      if (ipV6res.isIPV6 === true || ipV6res.isIPVFuture === true) {
-        host = `[${ipV6res.escapedHost}]`
+      // A parse-time zone identifier is authoritative only while it still
+      // describes the current host. Re-deriving an IPv6 zone from the
+      // single-"%" component form is ambiguous when the zone begins with
+      // "25": it is misread as a %25 separator, rewriting e.g. zone
+      // "25eth0" into "eth0" (or destroying a zone of just "25"). A
+      // validated zone keeps parse, normalize, serialize and equal in
+      // agreement.
+      const zonedHost = recomposeZonedIPv6Host(component)
+      if (zonedHost !== undefined) {
+        host = zonedHost
       } else {
-        host = reescapeHostDelimiters(host, false)
+        let ipV6res = normalizeIPv6(host)
+        if (ipV6res.isIPV6 !== true && ipV6res.isIPVFuture !== true) {
+          // Decode only unreserved bytes, once. In particular, keep %25
+          // encoded so it cannot introduce a second escape during
+          // recomposition.
+          host = normalizePercentEncoding(host, true)
+          ipV6res = normalizeIPv6(host)
+        }
+        if (ipV6res.isIPV6 === true || ipV6res.isIPVFuture === true) {
+          host = `[${ipV6res.escapedHost}]`
+        } else {
+          host = reescapeHostDelimiters(host, false)
+        }
       }
     }
     uriTokens.push(host)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fast-uri",
   "description": "Dependency-free RFC 3986 URI toolbox",
-  "version": "4.1.4",
+  "version": "4.2.0",
   "main": "index.js",
   "type": "commonjs",
   "types": "types/index.d.ts",

package/test/fixtures/uri-js-parse.json

@@ -43,6 +43,7 @@
     "//[2001:db8::7%en0]",
     {
       "host": "2001:db8::7%en0",
+      "ipv6Zone": "en0",
       "path": "",
       "reference": "relative"
     }

package/test/ipv6-validation.test.js

@@ -119,6 +119,136 @@ test('IPv6 zone identifiers are validated correctly', (t) => {
   t.end()
 })
 
+test('zoned IPv6 hosts beginning with "25" round-trip through parse/normalize/serialize/equal', (t) => {
+  const cases = [
+    // zones beginning with "25" (once ambiguous with a %25 separator)
+    ['http://[fe80::1%2525]/', 'fe80::1%25', 'http://[fe80::1%2525]/'],
+    ['http://[fe80::1%2525eth0]/', 'fe80::1%25eth0', 'http://[fe80::1%2525eth0]/'],
+    ['http://[fe80::1%2525en1]/', 'fe80::1%25en1', 'http://[fe80::1%2525en1]/'],
+    // zones that do not begin with "25" must stay idempotent
+    ['http://[fe80::1%25eth0]/', 'fe80::1%eth0', 'http://[fe80::1%25eth0]/'],
+    ['http://[fe80::a%en1]/', 'fe80::a%en1', 'http://[fe80::a%25en1]/'],
+    ['http://[fe80::a%25eth%2D0]/', 'fe80::a%eth%2D0', 'http://[fe80::a%25eth%2D0]/']
+  ]
+
+  for (const [input, host, normalized] of cases) {
+    const parsed = fastURI.parse(input)
+    t.equal(parsed.error, undefined, `${input} parses without error`)
+    t.equal(parsed.host, host, `${input} exposes the expected host`)
+    t.equal(fastURI.normalize(input), normalized, `${input} normalizes to the canonical form`)
+    t.equal(fastURI.serialize(parsed), normalized, `${input} serializes to the canonical form`)
+    const reparsed = fastURI.parse(normalized)
+    t.equal(reparsed.error, undefined, `${input} canonical output reparses without error`)
+    t.equal(reparsed.host, host, `${input} parse-after-normalize is stable`)
+  }
+
+  // distinct zones must not be conflated by equal
+  t.equal(
+    fastURI.equal('http://[fe80::1%2525eth0]/', 'http://[fe80::1%25eth0]/'),
+    false,
+    'equal distinguishes zones "25eth0" and "eth0"'
+  )
+  t.equal(
+    fastURI.equal('http://[fe80::1%2525]/', 'http://[fe80::1%25eth0]/'),
+    false,
+    'equal distinguishes zones "25" and "eth0"'
+  )
+  // the same zone still compares equal
+  t.equal(
+    fastURI.equal('http://[fe80::1%2525eth0]/', 'http://[fe80::1%2525eth0]/'),
+    true,
+    'an identical zoned authority is equal'
+  )
+  t.equal(
+    fastURI.equal('http://[fe80::1%2525]/', 'http://[fe80::1%2525]/'),
+    true,
+    'zone "25" equals itself'
+  )
+
+  // resolve must preserve the zone too
+  t.equal(
+    fastURI.resolve('http://example.com/', 'http://[fe80::1%2525eth0]/path'),
+    'http://[fe80::1%2525eth0]/path',
+    'resolve preserves a zone beginning with "25"'
+  )
+  t.equal(
+    fastURI.resolve('http://[fe80::1%2525eth0]/', 'child'),
+    'http://[fe80::1%2525eth0]/child',
+    'resolve preserves a zoned base'
+  )
+
+  t.end()
+})
+
+test('serialize only trusts the parse-derived IPv6 zone while the host is unchanged', (t) => {
+  // Reassigning `host` after parse must take effect for serialize.
+  const parsed = fastURI.parse('http://[::1]/admin')
+  parsed.host = 'example.com'
+  t.equal(
+    fastURI.serialize(parsed),
+    'http://example.com/admin',
+    'a host reassigned after parse wins over the stale zone'
+  )
+
+  // A caller-supplied `ipv6Zone` that does not match `host` must be ignored.
+  const forged = fastURI.serialize({
+    scheme: 'http',
+    host: 'fe80::1%25en1',
+    ipv6Zone: 'eth0',
+    path: '/'
+  })
+  t.equal(forged, 'http://[fe80::1%25en1]/', 'a mismatched ipv6Zone is ignored')
+  t.equal(fastURI.parse(forged).host, 'fe80::1%en1', 'mismatched ipv6Zone cannot redirect the parsed host')
+
+  // A caller-supplied `ipv6Zone` on a non-zoned host must be ignored too.
+  const noZone = fastURI.serialize({
+    scheme: 'http',
+    host: 'good.example',
+    ipv6Zone: 'eth0',
+    path: '/'
+  })
+  t.equal(noZone, 'http://good.example/', 'ipv6Zone on a non-zoned host is ignored')
+
+  // Reassigning a zoned host to a different zone must recompute, not reuse.
+  const zoned = fastURI.parse('http://[fe80::1%2525eth0]/')
+  zoned.host = 'fe80::1%25en1'
+  t.equal(
+    fastURI.serialize(zoned),
+    'http://[fe80::1%25en1]/',
+    'rewriting the zone recomposes from the new host'
+  )
+
+  // A consistent caller-supplied zone is honored (explicit disambiguation).
+  const disambiguated = fastURI.serialize({
+    scheme: 'http',
+    host: 'fe80::1%25eth0',
+    ipv6Zone: '25eth0',
+    path: '/'
+  })
+  t.equal(
+    disambiguated,
+    'http://[fe80::1%2525eth0]/',
+    'a consistent ipv6Zone disambiguates the component host'
+  )
+
+  // Without ipv6Zone, an ambiguous single-"%" host falls back to the
+  // best-effort heuristic (documented behavior for hand-built components).
+  t.equal(
+    fastURI.serialize({ host: 'fe80::1%25eth0' }),
+    '//[fe80::1%25eth0]',
+    'an ambiguous host without ipv6Zone uses the best-effort heuristic'
+  )
+
+  // Mutating the host must not poison resolve either.
+  t.equal(
+    fastURI.resolve('http://example.com/', 'http://[fe80::1%2525eth0]/path'),
+    'http://[fe80::1%2525eth0]/path',
+    'resolve preserves the parse-derived zone'
+  )
+
+  t.end()
+})
+
 test('hosts with unbalanced or misplaced IP-literal brackets are rejected', (t) => {
   const malformed = [
     'http://[fe80',

package/test/mailto-field-name-security.test.js

@@ -0,0 +1,151 @@
+'use strict'
+
+const test = require('tape')
+const fastURI = require('..')
+
+function encodeCharacter (value, index, lowercaseHex) {
+  let hex = value.charCodeAt(index).toString(16)
+  if (!lowercaseHex) hex = hex.toUpperCase()
+  return value.slice(0, index) + '%' + hex + value.slice(index + 1)
+}
+
+function mailtoState (component) {
+  return {
+    to: component.to,
+    subject: component.subject,
+    body: component.body,
+    headers: component.headers && { ...component.headers }
+  }
+}
+
+test('mailto parsing classifies decoded, case-insensitive reserved field names', (t) => {
+  const cases = [
+    { name: 'to', value: 'attacker@evil.test', property: 'to' },
+    { name: 'subject', value: 'injected subject', property: 'subject' },
+    { name: 'body', value: 'injected body', property: 'body' }
+  ]
+
+  for (const entry of cases) {
+    const variants = new Set([entry.name.toUpperCase()])
+    for (let i = 0; i < entry.name.length; i++) {
+      variants.add(encodeCharacter(entry.name, i, false))
+      variants.add(encodeCharacter(entry.name, i, true))
+    }
+
+    for (const name of variants) {
+      const parsed = fastURI.parse(`mailto:alice@example.test?${name}=${entry.value}`)
+      if (entry.property === 'to') {
+        t.deepEqual(parsed.to, ['alice@example.test', entry.value], name + ' is classified as a recipient')
+      } else {
+        t.equal(parsed[entry.property], entry.value, name + ' is classified as ' + entry.property)
+      }
+      t.equal(parsed.headers, undefined, name + ' is not exposed as a generic header')
+
+      const reparsed = fastURI.parse(fastURI.serialize(parsed))
+      t.deepEqual(mailtoState(reparsed), mailtoState(parsed), name + ' keeps its meaning after a roundtrip')
+    }
+  }
+
+  t.end()
+})
+
+test('mailto generic field names are decoded exactly once across roundtrips', (t) => {
+  const cases = [
+    ['%2574o', '%74o'],
+    ['%2573ubject', '%73ubject'],
+    ['%2562ody', '%62ody'],
+    ['x%2520y', 'x%20y'],
+    ['%26to', '&to'],
+    ['%25GGto', '%GGto']
+  ]
+
+  for (const [encodedName, decodedName] of cases) {
+    let serialized = `mailto:alice@example.test?${encodedName}=value`
+    for (let round = 0; round < 3; round++) {
+      const parsed = fastURI.parse(serialized)
+      t.deepEqual({ ...parsed.headers }, { [decodedName]: 'value' }, encodedName + ' stays generic in round ' + round)
+      t.deepEqual(parsed.to, ['alice@example.test'], encodedName + ' does not add a recipient in round ' + round)
+      t.equal(parsed.subject, undefined, encodedName + ' does not set a subject in round ' + round)
+      t.equal(parsed.body, undefined, encodedName + ' does not set a body in round ' + round)
+      serialized = fastURI.serialize(parsed)
+    }
+    t.equal(serialized, `mailto:alice@example.test?${encodedName}=value`, encodedName + ' serializes idempotently')
+  }
+
+  t.equal(
+    fastURI.serialize({ scheme: 'mailto', to: ['alice@example.test'], headers: { '%74o': 'value' } }),
+    'mailto:alice@example.test?%2574o=value',
+    'a percent sequence in a decoded component key is encoded as data'
+  )
+  t.end()
+})
+
+test('mailto serialization canonicalizes reserved generic header names', (t) => {
+  const serialized = fastURI.serialize({
+    scheme: 'mailto',
+    to: ['alice@example.test'],
+    subject: 'safe subject',
+    body: 'safe body',
+    headers: {
+      TO: 'attacker@evil.test',
+      Subject: 'hidden subject',
+      BODY: 'hidden body',
+      cc: 'copy@example.test'
+    }
+  })
+
+  t.equal(
+    serialized,
+    'mailto:alice@example.test,attacker@evil.test?subject=safe%20subject&body=safe%20body&cc=copy@example.test',
+    'dedicated properties override header variants and all recipients are visible in the path'
+  )
+
+  const parsed = fastURI.parse(serialized)
+  t.deepEqual(parsed.to, ['alice@example.test', 'attacker@evil.test'], 'canonical recipients are classified consistently')
+  t.equal(parsed.subject, 'safe subject', 'the dedicated subject wins')
+  t.equal(parsed.body, 'safe body', 'the dedicated body wins')
+  t.deepEqual({ ...parsed.headers }, { cc: 'copy@example.test' }, 'only generic headers remain generic')
+
+  const empty = fastURI.serialize({
+    scheme: 'mailto',
+    to: ['alice@example.test'],
+    subject: '',
+    body: '',
+    headers: { Subject: 'hidden subject', BODY: 'hidden body' }
+  })
+  t.equal(empty, 'mailto:alice@example.test?subject=&body=', 'explicit empty properties override header variants')
+  const emptyParsed = fastURI.parse(empty)
+  t.equal(emptyParsed.subject, '', 'an empty subject round-trips')
+  t.equal(emptyParsed.body, '', 'an empty body round-trips')
+  t.end()
+})
+
+test('mailto duplicate reserved fields have deterministic parsing semantics', (t) => {
+  const parsed = fastURI.parse(
+    'mailto:alice@example.test?subject=first&%53UBJECT=last&body=first&%42ODY=last&to=one@example.test&%54O=two@example.test'
+  )
+
+  t.equal(parsed.subject, 'last', 'the last subject wins')
+  t.equal(parsed.body, 'last', 'the last body wins')
+  t.deepEqual(
+    parsed.to,
+    ['alice@example.test', 'one@example.test', 'two@example.test'],
+    'all recipient fields are accumulated'
+  )
+  t.equal(parsed.headers, undefined, 'no reserved spelling remains generic')
+  t.end()
+})
+
+test('encoded reserved field names expose decoded control characters immediately', (t) => {
+  const input = 'mailto:alice@example.test?%73ubject=hello%0D%0Aworld'
+  const parsed = fastURI.parse(input)
+
+  t.equal(parsed.subject, 'hello\r\nworld', 'the first parse exposes CRLF in the dedicated property')
+  t.equal(parsed.headers, undefined, 'the subject is not hidden as a generic header')
+  t.equal(
+    fastURI.parse(fastURI.serialize(parsed)).subject,
+    parsed.subject,
+    'the decoded subject remains stable after a roundtrip'
+  )
+  t.end()
+})

package/test/security-normalization.test.js

@@ -126,6 +126,44 @@ test('hostname normalization decodes only current unreserved escapes', (t) => {
   t.end()
 })
 
+test('scheme-relative hostname normalization folds decoded ASCII case', (t) => {
+  const encodedHost = '//%41.com'
+  const normalizedHost = fastURI.normalize(encodedHost)
+  const encodedMetadata = '//%4Detadata.internal/private'
+  const literalMetadata = '//metadata.internal/private'
+
+  t.equal(fastURI.parse(encodedHost).host, 'a.com', 'parse folds an encoded uppercase host letter')
+  t.equal(normalizedHost, '//a.com', 'normalize emits a lowercase host')
+  t.equal(fastURI.normalize(normalizedHost), normalizedHost, 'host normalization is idempotent')
+  t.equal(fastURI.equal(encodedHost, '//a.com'), true, 'encoded and literal host spellings compare equal')
+  t.equal(fastURI.equal(encodedMetadata, literalMetadata), true, 'encoded metadata host compares equal')
+  t.equal(
+    fastURI.resolve('x://trusted.example/', encodedMetadata),
+    fastURI.resolve('x://trusted.example/', literalMetadata),
+    'encoded and literal metadata hosts resolve identically'
+  )
+  t.equal(
+    fastURI.normalize('//example.com%2fpath'),
+    '//example.com%2Fpath',
+    'reserved host escapes remain encoded with uppercase hex'
+  )
+  t.equal(fastURI.normalize('//%2541.com'), '//%2541.com', 'nested host escapes are not decoded twice')
+  t.equal(fastURI.equal('//User@%41.com/path', '//user@a.com/path'), false, 'userinfo remains case-sensitive')
+  t.equal(fastURI.equal('//%41.com/Path', '//a.com/path'), false, 'path remains case-sensitive')
+  t.equal(fastURI.equal('//%41.com/?Token=Value', '//a.com/?token=value'), false, 'query remains case-sensitive')
+  t.end()
+})
+
+test('host normalization applies to schemes that skip path normalization', (t) => {
+  const encodedHost = 'mailto://%41.com'
+  const literalHost = 'mailto://a.com'
+
+  t.equal(fastURI.parse(encodedHost).host, fastURI.parse(literalHost).host, 'parse results have consistent hosts')
+  t.equal(fastURI.normalize(encodedHost), fastURI.normalize(literalHost), 'normalize results are consistent')
+  t.equal(fastURI.equal(encodedHost, literalHost), true, 'encoded and literal hosts compare equal')
+  t.end()
+})
+
 test('host conversion failures are not treated as comparable URLs', (t) => {
   const malformedHost = 'http://trusted.test%2540evil.test/'
 

package/types/index.d.ts

@@ -5,6 +5,22 @@ declare namespace fastUri {
     scheme?: string;
     userinfo?: string;
     host?: string;
+    /**
+     * Zone identifier of a zoned IPv6 host, e.g. `"eth0"` or `"25eth0"`. Set by
+     * `parse` for a bracketed IPv6 literal so `serialize`/`normalize` can
+     * reproduce the exact zone without re-deriving it from the ambiguous
+     * single-`%` form. It is validated on use, so a value that does not match
+     * `host` (for example after `host` is reassigned) is ignored.
+     *
+     * When building a component object by hand, set `ipv6Zone` to disambiguate
+     * a single-`%` host whose zone is ambiguous (a zone beginning with `25`
+     * is re-read as a `%25` separator). Without it, `serialize` falls back to
+     * a best-effort heuristic and may reinterpret such a zone, e.g. `{ host:
+     * "fe80::1%25eth0" }` serializes to `[fe80::1%25eth0]` (zone `eth0`), while
+     * `{ host: "fe80::1%25eth0", ipv6Zone: "25eth0" }` serializes to
+     * `[fe80::1%2525eth0]` (zone `25eth0`).
+     */
+    ipv6Zone?: string;
     port?: number | string;
     path?: string;
     query?: string;