fast-uri 4.1.5 → 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

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.5",
+  "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/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;