fast-uri 2.4.6 → 2.4.8

package/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release the package
+
+on:
+  workflow_dispatch:
+    inputs:
+      semver:
+        description: 'Release bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - prepatch
+          - preminor
+          - premajor
+          - prerelease
+      preid:
+        description: 'Prerelease identifier (e.g. rc), used by the pre* bump types'
+        required: false
+        type: string
+
+permissions: {}
+
+jobs:
+  release:
+    permissions:
+      id-token: write # required for npm provenance via OIDC
+      contents: write # required to push the release commit and the tag
+    uses: fastify/workflows/.github/workflows/reusable-release.yml@b0a2ab2d8259b6bd574b804cd6874bbd75c3577c
+    with:
+      semver: ${{ inputs.semver }}
+      preid: ${{ inputs.preid }}
+      dist-tag: ${{ startsWith(inputs.semver, 'pre') && 'two-next' || 'two' }}
+      make-latest: false

package/README.md

@@ -17,12 +17,18 @@ All of the above functions can accept an additional options argument that is an
 
 Malformed authorities and out-of-range ports are reported through the parsed component's `error` field. `normalize()` leaves malformed string inputs unchanged, and `equal()` returns `false` when either string input is malformed.
 
+Schemes are never percent-decoded. RFC 3986 does not allow percent-encoding in a scheme, so an input such as `%6Aavascript:alert(1)` is reported as malformed (`error: 'URI scheme is malformed.'`) instead of being parsed as `javascript:`. `normalize()` leaves it unchanged, `equal()` returns `false`, and `resolve()` and `serialize()` throw.
+
+For schemes with domain hosts (`http`, `https`, `ws`, `wss`, or any scheme with the `domainHost` option), a host containing an ASCII character that RFC 3986 does not allow in a reg-name (for example `@`, TAB, LF, CR, space, `"`, `<`, `>`, `^`, `` ` ``, `{`, `|`, `}`) is reported as malformed (`error: 'URI host is malformed.'`). It is never passed through a WHATWG URL parser that could treat `@` as a delimiter or strip whitespace. `normalize()` leaves such input unchanged, `equal()` returns `false`, and `resolve()` throws.
+
 *	`scheme` (string)
 	Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior.
 
 *	`reference` (string)
 	If set to `"suffix"`, it indicates that the URI is in the suffix format and the parser will use the option's `scheme` property to determine the URI's scheme.
 
+	A suffix reference is written without its scheme and without the `//` authority marker (RFC 3986 section 4.5). Such a reference is inherently ambiguous: an authority component cannot always be distinguished from a path. When the input carries an authority of the form `host:port` (for example `//javascript:80/x`) or a userinfo containing a colon, the serialized suffix output can begin with text that reparses as a URI scheme (for example `javascript:80/x`). Do not treat suffix output as a trusted absolute URL, and do not render it or use it in a scheme allowlist without first validating it with `parse()`. If you need an unambiguous result, use the default (non-suffix) serialization.
+
 *	`tolerant` (boolean, false)
 	If set to `true`, the parser will relax URI resolving rules.
 
@@ -82,6 +88,8 @@ uri.normalize('http://example.com/a%2Fb')
 
 Reserved path escapes such as `%2F` and `%2E` are preserved as path data during normalization and comparison.
 
+Dot segments in relative references are removed without changing what the reference resolves to: leading `..` segments that cannot be collapsed are kept, a relative path is never turned into a root-relative one, and a first-segment colon exposed by the removal is kept behind a leading `./` so the reference is not reparsed as a scheme (`a/../b` → `b`, `../x` → `../x`, `x/..` → `./`, `a/../a:b` → `./a:b`).
+
 ### Equal
 
 ```js

package/index.js

@@ -1,21 +1,29 @@
 'use strict'
 
-const { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require('./lib/utils')
+const { normalizeIPv6, removeDotSegments, removeDotSegmentsRelative, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require('./lib/utils')
 const SCHEMES = require('./lib/schemes')
 
 const VALID_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/u
 const MALFORMED_SCHEME_ERROR = 'URI scheme is malformed.'
+const MALFORMED_HOST_ERROR = 'URI host is malformed.'
+// ASCII characters outside the RFC 3986 reg-name set (unreserved, sub-delims
+// and "%" for pct-encoded): C0 controls, space, DEL, and "#/:<>?@[\]^`{|}.
+const FORBIDDEN_DOMAIN_HOST_CHARACTER = /[\0-\x20"#/:<>?@[\\\]^`{|}\x7F]/u
 
 /**
+ * RFC 3986 section 3.1 does not allow percent-encoding in a scheme, so the
+ * scheme is validated as-is and never decoded. Decoding would let inert input
+ * such as `%6Aavascript:` become a live `javascript:` scheme.
+ *
  * @param {string} scheme
  * @returns {string}
  */
-function decodeValidScheme (scheme) {
-  const decodedScheme = unescape(String(scheme))
-  if (!VALID_SCHEME.test(decodedScheme)) {
+function validateScheme (scheme) {
+  const stringScheme = String(scheme)
+  if (!VALID_SCHEME.test(stringScheme)) {
     throw new TypeError(MALFORMED_SCHEME_ERROR)
   }
-  return decodedScheme
+  return stringScheme
 }
 
 function normalize (uri, options) {
@@ -64,6 +72,12 @@ function resolve (baseURI, relativeURI, options) {
   const resolvedHost = resolved.host
   const resolvedHostIsIP = resolvedHost !== undefined && resolvedHost !== '' &&
     (isIPv4(resolvedHost) || normalizeIPv6(resolvedHost).isIPV6)
+  // Inputs are parsed scheme-neutrally, so delimiters and controls in a domain
+  // host are only detected here, once the final scheme is known. They always
+  // fail closed, including in percent-encoded hosts.
+  if (hasForbiddenDomainHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP)) {
+    throw new Error(MALFORMED_HOST_ERROR)
+  }
   canonicalizeHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP)
   // Percent escapes in an ASCII reg-name are encoded data. The WHATWG hostname
   // parser can reject them even though fast-uri preserves them safely as RFC
@@ -112,14 +126,17 @@ function resolveComponents (base, relative, options, skipNormalization) {
         if (relative.path.charAt(0) === '/') {
           target.path = removeDotSegments(relative.path)
         } else {
-          if ((base.userinfo !== undefined || base.host !== undefined || base.port !== undefined) && !base.path) {
+          const baseHasAuthority = base.userinfo !== undefined || base.host !== undefined || base.port !== undefined
+          if (baseHasAuthority && !base.path) {
             target.path = '/' + relative.path
           } else if (!base.path) {
             target.path = relative.path
           } else {
             target.path = base.path.slice(0, base.path.lastIndexOf('/') + 1) + relative.path
           }
-          target.path = removeDotSegments(target.path)
+          target.path = base.scheme === undefined && !baseHasAuthority && target.path[0] !== '/'
+            ? removeDotSegmentsRelative(target.path)
+            : removeDotSegments(target.path)
         }
         target.query = relative.query
       }
@@ -164,7 +181,7 @@ function serialize (cmpts, opts) {
   const uriTokens = []
 
   if (components.scheme) {
-    components.scheme = decodeValidScheme(components.scheme)
+    components.scheme = validateScheme(components.scheme)
   }
 
   // find scheme handler
@@ -174,7 +191,11 @@ function serialize (cmpts, opts) {
   if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(components, options)
 
   const hasAuthority = components.userinfo !== undefined || components.host !== undefined || components.port !== undefined
-  const pathNoScheme = !options.skipEscape && components.scheme === undefined && !hasAuthority
+  // A reference with no emitted scheme is path-noscheme: a bare ':' in its
+  // first path segment would reparse as a scheme (RFC 3986 3.3/4.2). Enforced
+  // under skipEscape too (resolve()), so the reapply below gates on this flag.
+  const schemelessReference = (components.scheme === undefined || options.reference === 'suffix') && !hasAuthority
+  const pathNoScheme = !options.skipEscape && schemelessReference
 
   if (components.path !== undefined) {
     if (!options.skipEscape) {
@@ -186,7 +207,7 @@ function serialize (cmpts, opts) {
 
   if (options.reference !== 'suffix' && components.scheme) {
     // Scheme handlers may replace the scheme during serialization.
-    components.scheme = decodeValidScheme(components.scheme)
+    components.scheme = validateScheme(components.scheme)
     uriTokens.push(components.scheme)
     uriTokens.push(':')
   }
@@ -207,13 +228,18 @@ function serialize (cmpts, opts) {
     let s = components.path
 
     if (!options.absolutePath && (!schemeHandler || !schemeHandler.absolutePath)) {
-      s = removeDotSegments(s)
+      // A relative-path reference keeps its unresolvable leading ".." segments
+      // and must never become root-relative (RFC 3986 section 5.2.4 applies to
+      // merged target paths, not to the reference itself).
+      s = schemelessReference && s[0] !== '/'
+        ? removeDotSegmentsRelative(s)
+        : removeDotSegments(s)
     }
 
     // Dot-segment removal can expose a colon that was not originally in the
     // first segment (for example, "./a:b"). Reapply path-noscheme encoding so
     // the serialized relative reference cannot be reparsed as a URI scheme.
-    if (pathNoScheme) {
+    if (schemelessReference) {
       s = serializePathEncoding(s, true)
     }
 
@@ -279,6 +305,11 @@ function getParseError (parsed, matches) {
  * @returns {boolean} whether host conversion failed
  */
 function canonicalizeHost (parsed, options, schemeHandler, isIP) {
+  if (hasForbiddenDomainHost(parsed, options, schemeHandler, isIP)) {
+    parsed.error = parsed.error || MALFORMED_HOST_ERROR
+    return true
+  }
+
   if (
     !options.unicodeSupport &&
     (!schemeHandler || !schemeHandler.unicodeSupport) &&
@@ -288,16 +319,62 @@ function canonicalizeHost (parsed, options, schemeHandler, isIP) {
     isIP === false &&
     nonSimpleDomain(parsed.host)
   ) {
+    let url
     try {
-      parsed.host = new URL('http://' + parsed.host).hostname
+      url = new URL('http://' + parsed.host)
     } catch (e) {
       parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e
       return true
     }
+    // The WHATWG parser must have read the whole input as a host. Anything
+    // else means it found a delimiter fast-uri did not, so its hostname would
+    // describe a different authority.
+    if (!isHostOnlyURL(url)) {
+      parsed.error = parsed.error || MALFORMED_HOST_ERROR
+      return true
+    }
+    parsed.host = url.hostname
   }
   return false
 }
 
+/**
+ * Whether a domain host contains an ASCII character that RFC 3986 does not
+ * allow in a reg-name (unreserved, sub-delims, or pct-encoded). Such a host is
+ * rejected instead of being handed to the WHATWG URL parser, which would treat
+ * "@" as a userinfo delimiter (silently dropping the data before it) and strip
+ * TAB, LF, and CR. Non-ASCII characters remain allowed for IDNs.
+ *
+ * @param {import('./types/index').URIComponent} parsed
+ * @param {import('./types/index').Options} options
+ * @param {{ domainHost?: boolean }|undefined} schemeHandler
+ * @param {boolean} isIP
+ * @returns {boolean}
+ */
+function hasForbiddenDomainHost (parsed, options, schemeHandler, isIP) {
+  return Boolean(
+    parsed.host &&
+    isIP === false &&
+    !isIPLiteral(parsed.host) &&
+    (options.domainHost || (schemeHandler && schemeHandler.domainHost)) &&
+    FORBIDDEN_DOMAIN_HOST_CHARACTER.test(parsed.host)
+  )
+}
+
+/**
+ * @param {URL} url
+ * @returns {boolean}
+ */
+function isHostOnlyURL (url) {
+  return url.username === '' &&
+    url.password === '' &&
+    url.port === '' &&
+    url.pathname === '/' &&
+    url.search === '' &&
+    url.hash === '' &&
+    url.hostname !== ''
+}
+
 function hasMalformedPercentEncoding (component) {
   if (component === undefined) return false
 
@@ -339,6 +416,18 @@ function hasMalformedComponentPercentEncoding (matches) {
     hasMalformedPercentEncoding(matches[8])
 }
 
+function hasSuffixAuthority (uri) {
+  const authorityEnd = uri.search(/[/?#]/)
+  const authority = authorityEnd === -1 ? uri : uri.slice(0, authorityEnd)
+  const at = authority.lastIndexOf('@')
+  const hostPort = authority.slice(at + 1)
+
+  if (hostPort[0] === '[') return true
+
+  const colon = hostPort.lastIndexOf(':')
+  return colon === -1 || /^\d*$/u.test(hostPort.slice(colon + 1))
+}
+
 function parseWithStatus (uri, opts) {
   const options = Object.assign({}, opts)
   const parsed = {
@@ -357,7 +446,17 @@ function parseWithStatus (uri, opts) {
   let malformedIPLiteral = false
   let malformedScheme = false
   let isIP = false
-  if (options.reference === 'suffix') uri = (options.scheme ? options.scheme + ':' : '') + '//' + uri
+  if (options.reference === 'suffix') {
+    if (options.scheme) {
+      // v2 suffix references traditionally omit both the scheme and the "//"
+      // authority marker. Preserve that interpretation for valid authorities,
+      // but treat a non-numeric host-port suffix as a path. Otherwise inputs
+      // such as "javascript:alert(1)" are emitted as live schemes.
+      uri = options.scheme + (hasSuffixAuthority(uri) ? '://' : ':') + uri
+    } else {
+      uri = '//' + uri
+    }
+  }
 
   // A literal backslash (U+005C) is not a valid RFC 3986 URI character and is
   // not an authority delimiter. Reject it in the authority rather than
@@ -407,9 +506,8 @@ function parseWithStatus (uri, opts) {
     parsed.fragment = matches[8]
 
     if (parsed.scheme !== undefined) {
-      const decodedScheme = unescape(parsed.scheme)
-      if (VALID_SCHEME.test(decodedScheme)) {
-        parsed.scheme = decodedScheme.toLowerCase()
+      if (VALID_SCHEME.test(parsed.scheme)) {
+        parsed.scheme = parsed.scheme.toLowerCase()
       } else {
         parsed.error = parsed.error || MALFORMED_SCHEME_ERROR
         malformedScheme = true
@@ -443,7 +541,7 @@ function parseWithStatus (uri, opts) {
         parsed.host = isIP ? ipv6result.host : ipv6result.host.toLowerCase()
 
         if (malformedIPLiteral) {
-          parsed.error = parsed.error || 'URI host is malformed.'
+          parsed.error = parsed.error || MALFORMED_HOST_ERROR
           malformedAuthorityOrPort = true
         }
       } else {
@@ -473,11 +571,21 @@ function parseWithStatus (uri, opts) {
       malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP)
     }
 
-    if (!schemeHandler || (schemeHandler && !schemeHandler.skipNormalize)) {
-      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())
       }
+      // Resolution parses both inputs with the internal `null` scheme before
+      // the effective scheme is known. Preserve raw host characters for that
+      // intermediate step so the final scheme can reject forbidden domain host
+      // characters; the resolved host is re-escaped when it is serialized.
+      parsed.host = isIP || options.scheme !== 'null' ? reescapeHostDelimiters(host, isIP) : host
+    }
+
+    if (!schemeHandler || (schemeHandler && !schemeHandler.skipNormalize)) {
       if (parsed.path !== undefined && parsed.path.length) {
         parsed.path = normalizePathEncoding(parsed.path)
       }

package/lib/utils.js

@@ -233,6 +233,57 @@ function removeDotSegments (input) {
   return output.join('')
 }
 
+/**
+ * Removes dot segments from the path of a relative reference (a path that does
+ * not start with "/") without changing what it resolves to against any base.
+ * Unlike `removeDotSegments`, leading ".." segments that cannot be collapsed
+ * are kept, the result never becomes root-relative, and a result that would be
+ * empty or start with an empty segment is prefixed with "." (an empty path
+ * means "same document" and a leading "//" would introduce an authority).
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+function removeDotSegmentsRelative (path) {
+  if (path === '' || path[0] === '/') {
+    return removeDotSegments(path)
+  }
+
+  const segments = path.split('/')
+  const last = segments.length - 1
+  /** @type {string[]} */
+  const output = []
+  let trailingDirectory = false
+
+  for (let i = 0; i <= last; i++) {
+    const segment = segments[i]
+    if (segment === '.' || segment === '..') {
+      if (segment === '..') {
+        if (output.length !== 0 && output[output.length - 1] !== '..') {
+          output.pop()
+        } else {
+          output.push('..')
+        }
+      }
+      trailingDirectory = i === last
+    } else {
+      output.push(segment)
+    }
+  }
+
+  if (trailingDirectory && output[output.length - 1] !== '..') {
+    output.push('')
+  }
+  if (output.length === 0 || output[0] === '' || output[0].includes(':')) {
+    // An empty path, a leading empty segment ("//"), or a first segment
+    // containing ":" (which would be mistaken for a scheme, RFC 3986 section
+    // 4.2) must stay behind a "." segment so the reference keeps its meaning.
+    output.unshift('.')
+  }
+
+  return output.join('/')
+}
+
 /**
  * Re-escape RFC 3986 gen-delims that must not appear literally in the host.
  * After the URI regex parses, these characters cannot be literal in the host
@@ -657,6 +708,7 @@ module.exports = {
   encodeFragment,
   escapePreservingEscapes,
   removeDotSegments,
+  removeDotSegmentsRelative,
   isIPv4,
   normalizeIPv6,
   stringArrayToHexStripped,

package/package.json

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

package/test/host-delimiter-security.test.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const test = require('tape')
+const fastURI = require('..')
+
+const MALFORMED_HOST_ERROR = 'URI host is malformed.'
+
+const domainHostSchemes = ['http', 'https', 'ws', 'wss']
+
+// Hosts containing ASCII characters that RFC 3986 does not allow in a
+// reg-name. Handing them to the WHATWG URL parser would read "@" as a userinfo
+// delimiter (dropping the data before it) and strip TAB, LF and CR.
+const forbiddenHosts = [
+  'b@evil.example',
+  'ev\til.example',
+  'ev\nil.example',
+  'ev\ril.example',
+  'ev\r\nil.example',
+  'a b.example',
+  'a"b.example',
+  'a<b.example',
+  'a>b.example',
+  'a^b.example',
+  'a`b.example',
+  'a{b.example',
+  'a|b.example',
+  'a}b.example',
+  'a\u007Fb.example',
+  'a\u0000b.example'
+]
+
+test('domain hosts with forbidden ASCII characters fail closed', (t) => {
+  for (const scheme of domainHostSchemes) {
+    for (const host of forbiddenHosts) {
+      const uri = `${scheme}://user@${host}/path`
+      const label = JSON.stringify(uri)
+
+      const parsed = fastURI.parse(uri)
+      t.equal(parsed.error, MALFORMED_HOST_ERROR, `${label} reports a malformed host`)
+      t.notEqual(parsed.host, 'evil.example', `${label} does not report a truncated host`)
+
+      t.equal(fastURI.normalize(uri), uri, `${label} normalizes to itself`)
+      t.equal(fastURI.normalize(uri, { unicodeSupport: true }), uri, `${label} normalizes to itself with unicodeSupport`)
+      t.equal(fastURI.equal(uri, uri), false, `${label} is not comparable`)
+      t.equal(fastURI.equal(uri, `${scheme}://user@evil.example/path`), false, `${label} does not alias the stripped host`)
+
+      t.throws(
+        () => fastURI.resolve(`${scheme}://trusted.example/`, `//user@${host}/path`),
+        /URI host is malformed\./,
+        `${label} is rejected by resolve`
+      )
+    }
+  }
+  t.end()
+})
+
+test('a second "@" cannot move the authority to a different host', (t) => {
+  const uri = 'http://a@b@evil.example/'
+  const parsed = fastURI.parse(uri)
+  t.equal(parsed.userinfo, 'a')
+  t.notEqual(parsed.host, 'evil.example', 'host is not silently truncated')
+  t.equal(parsed.error, MALFORMED_HOST_ERROR)
+  t.equal(fastURI.normalize(uri), uri)
+
+  t.throws(
+    () => fastURI.resolve('http://trusted.example/', '//a@b%41@evil.example/p'),
+    /URI host is malformed\./,
+    'percent-encoded data does not bypass the check in resolve'
+  )
+  t.end()
+})
+
+test('the domainHost option applies the same rules to other schemes', (t) => {
+  const parsed = fastURI.parse('foo://a@b@evil.example/', { domainHost: true })
+  t.equal(parsed.error, MALFORMED_HOST_ERROR)
+  t.end()
+})
+
+test('valid domain hosts are unaffected', (t) => {
+  t.equal(fastURI.normalize('http://Example.COM/'), 'http://example.com/')
+  t.equal(fastURI.normalize('http://%65xample.com/'), 'http://example.com/')
+  t.equal(fastURI.normalize('http://bücher.de/'), 'http://xn--bcher-kva.de/')
+  t.equal(fastURI.normalize('http://bücher.de/', { unicodeSupport: true }), 'http://bücher.de/')
+  t.equal(fastURI.parse("http://a!$&'()*+,;=b.example/").error, undefined, 'sub-delims are allowed')
+  t.equal(fastURI.parse('http://user:pass@example.com:8080/').host, 'example.com')
+  t.equal(fastURI.resolve('http://trusted.example/', '//user@example.com/p'), 'http://user@example.com/p')
+  t.end()
+})
+
+test('schemes without domain hosts keep encoding reg-name data', (t) => {
+  t.equal(fastURI.normalize('foo://a@b@evil.example/'), 'foo://a@b%40evil.example/')
+  t.equal(fastURI.resolve('foo://x/', '//a@b@evil.example/p'), 'foo://a@b%40evil.example/p')
+  t.end()
+})

package/test/relative-normalization-security.test.js

@@ -0,0 +1,157 @@
+'use strict'
+
+const test = require('tape')
+const fastURI = require('..')
+
+const ABSOLUTE_BASES = [
+  'http://h/p/q/r',
+  'http://h/',
+  'foo://h/a/b/',
+  'http://h/p/q/'
+]
+
+const RELATIVE_BASES = ['', 'base', 'relative/base']
+
+test('normalize keeps the meaning of relative-path references', (t) => {
+  const cases = [
+    ['a/../b', 'b'],
+    ['x/..', './'],
+    ['../x', '../x'],
+    ['./../x', '../x'],
+    ['a/b/../../..', '..'],
+    ['a/./b', 'a/b'],
+    ['a/b/..', 'a/'],
+    ['.', './'],
+    ['..', '..'],
+    ['../', '../'],
+    ['../../a/./b/../c', '../../a/c'],
+    ['a//..', 'a/'],
+    ['a/../b?q#f', 'b?q#f']
+  ]
+  for (const [input, expected] of cases) {
+    t.equal(fastURI.normalize(input), expected, `${input} -> ${expected}`)
+  }
+  t.end()
+})
+
+test('normalize never turns a relative-path reference into a root or network path', (t) => {
+  t.equal(fastURI.normalize('.//x'), './/x', 'leading empty segment is kept behind "."')
+  t.equal(fastURI.normalize('a/..//x'), './/x', 'collapsed prefix does not expose "//"')
+  t.equal(fastURI.parse(fastURI.normalize('a/..//x')).host, undefined, 'no authority is introduced')
+  t.equal(fastURI.normalize('./a:b'), './a:b', 'first-segment colon is kept behind a "." segment (RFC 3986 section 4.2)')
+  t.equal(fastURI.parse(fastURI.normalize('./a:b')).scheme, undefined, 'no scheme is introduced')
+  t.end()
+})
+
+test('normalize keeps the existing behavior for root-relative and absolute paths', (t) => {
+  t.equal(fastURI.normalize('/a/../b'), '/b')
+  t.equal(fastURI.normalize('/../x'), '/x')
+  t.equal(fastURI.normalize('http://h/a/../../b'), 'http://h/b')
+  t.end()
+})
+
+test('equal does not alias relative references with different targets', (t) => {
+  t.equal(fastURI.equal('../x', 'x'), false)
+  t.equal(fastURI.equal('a/../b', '/b'), false)
+  t.equal(fastURI.equal('x/..', '/'), false)
+  t.equal(fastURI.equal('a/../b', 'b'), true)
+  t.end()
+})
+
+test('resolving a normalized relative reference matches resolving the original', (t) => {
+  for (const base of [...ABSOLUTE_BASES, ...RELATIVE_BASES]) {
+    for (const ref of ['a/../b', 'x/..', '../x', './../x', 'a/b/../../..', '.', '..', './/x']) {
+      t.equal(
+        fastURI.resolve(base, fastURI.normalize(ref)),
+        fastURI.resolve(base, ref),
+        `${base} + ${ref}`
+      )
+    }
+  }
+  t.equal(fastURI.resolve('http://h/p/q/r', fastURI.normalize('a/../b')), 'http://h/p/q/b')
+  t.equal(fastURI.resolve('http://h/p/q/r', fastURI.normalize('../x')), 'http://h/p/x')
+  t.end()
+})
+
+test('property: normalization of relative references is resolution-preserving and idempotent', (t) => {
+  const segments = ['a', 'b', '.', '..', '', 'a:b']
+  // Deterministic linear congruential generator so failures are reproducible.
+  let seed = 0x5ec02
+  const next = (n) => {
+    seed = (seed * 1103515245 + 12345) % 2147483648
+    return Math.floor((seed / 2147483648) * n)
+  }
+
+  let failures = 0
+  let checked = 0
+  for (let i = 0; i < 4000; i++) {
+    const length = 1 + next(6)
+    const parts = []
+    for (let j = 0; j < length; j++) parts.push(segments[next(segments.length)])
+    const ref = parts.join('/')
+    // Only relative-path references: empty refs, refs starting with "/", and
+    // refs whose first segment contains ":" are not affected by this change.
+    if (ref === '' || ref[0] === '/' || fastURI.parse(ref).scheme !== undefined) continue
+
+    checked++
+    const normalized = fastURI.normalize(ref)
+    if (fastURI.normalize(normalized) !== normalized) {
+      failures++
+      t.fail(`not idempotent: ${ref} -> ${normalized} -> ${fastURI.normalize(normalized)}`)
+    }
+    for (const base of ABSOLUTE_BASES) {
+      const expected = fastURI.resolve(base, ref)
+      const actual = fastURI.resolve(base, normalized)
+      if (actual !== expected) {
+        failures++
+        t.fail(`${base} + ${ref}: normalized ${normalized} resolves to ${actual}, expected ${expected}`)
+      }
+    }
+  }
+
+  t.ok(checked > 1000, `checked ${checked} relative references`)
+  t.equal(failures, 0, 'no relative reference changed meaning')
+  t.end()
+})
+
+test('suffix parsing preserves v2 authority semantics', (t) => {
+  const options = { reference: 'suffix', scheme: 'http' }
+  for (const [input, expected] of [
+    ['example.com/path', { host: 'example.com', path: '/path' }],
+    ['example.com:8080/path', { host: 'example.com', port: 8080, path: '/path' }],
+    ['user:pass@example.com/path', { userinfo: 'user:pass', host: 'example.com', path: '/path' }]
+  ]) {
+    const parsed = fastURI.parse(input, options)
+    for (const [key, value] of Object.entries(expected)) {
+      t.equal(parsed[key], value, `${input} preserves ${key}`)
+    }
+    t.equal(fastURI.normalize(input, options), input, `${input} normalizes unchanged`)
+    t.equal(fastURI.serialize(parsed, options), input, `${input} round-trips`)
+  }
+  t.end()
+})
+
+test('normalize does not promote a colon-first relative reference to a scheme (skipEscape)', (t) => {
+  // RFC 3986 section 4.2: a first path segment containing ":" must stay
+  // protected by a leading "./", or it is mistaken for a scheme. Collapsing
+  // the protecting dot segment must not expose the colon. The default path
+  // escapes the colon; with skipEscape the colon is emitted raw and the
+  // reference is reparsed as absolute (scheme "a"), changing its meaning.
+  const colonRefs = ['./a:b', 'a/../a:b']
+  for (const ref of colonRefs) {
+    const normalized = fastURI.normalize(ref, { skipEscape: true })
+    t.equal(
+      fastURI.parse(normalized).scheme,
+      undefined,
+      `${ref} -> ${normalized} must not introduce a scheme`
+    )
+    for (const base of ABSOLUTE_BASES) {
+      t.equal(
+        fastURI.resolve(base, normalized, { skipEscape: true }),
+        fastURI.resolve(base, ref, { skipEscape: true }),
+        `${base} + ${ref}: normalized ${normalized} must resolve the same`
+      )
+    }
+  }
+  t.end()
+})

package/test/reserved-path-normalization.test.js

@@ -77,13 +77,13 @@ test('serialize uses the RFC 3986 path character set without opening escapes', (
   )
   t.equal(
     fastURI.serialize({ path: './a:b/c:d' }),
-    'a%3Ab/c:d',
-    'escapes a first-segment colon exposed by dot-segment removal'
+    './a:b/c:d',
+    'a first-segment colon exposed by dot-segment removal is kept behind a "." segment'
   )
   t.equal(
     fastURI.normalize('./a:b'),
-    'a%3Ab',
-    'normalization keeps a relative path from becoming a scheme'
+    './a:b',
+    'normalization keeps a relative path from becoming a scheme without re-encoding the colon'
   )
   t.equal(
     fastURI.serialize({ path: '/Kſ' }),
@@ -107,3 +107,31 @@ test('equal distinguishes escaped reserved path data from literal syntax', (t) =
   )
   t.end()
 })
+
+// A suffix reference never emits its scheme token, so it is a scheme-less
+// (path-noscheme) reference: a bare ':' in its first path segment must be
+// escaped, or the serialized output reparses as an absolute URI with a scheme.
+// @see https://github.com/fastify/fast-uri/security/advisories/GHSA-333x-w4r6-6crp
+test('suffix reference escapes a first-segment colon instead of emitting a scheme', (t) => {
+  const dangerous = /^(?:javascript|data|vbscript):/i
+  const options = { reference: 'suffix', scheme: 'x' }
+
+  for (const input of ['javascript:alert(1)', '%6Aavascript:alert(1)', 'data:text/html,x', 'vbscript:msgbox(1)']) {
+    t.notOk(dangerous.test(fastURI.normalize(input, options)), `${input} normalizes to an inert reference`)
+  }
+
+  t.equal(
+    fastURI.normalize('javascript:alert(1)', options),
+    'javascript%3Aalert(1)',
+    'escapes the leading-segment colon to %3A'
+  )
+  t.notOk(
+    dangerous.test(fastURI.resolve('https://a.example/base/', '%6Aavascript:alert(1)', { reference: 'suffix' })),
+    'resolve in suffix mode does not emit a live scheme'
+  )
+
+  // legitimate suffix usage is unchanged
+  t.equal(fastURI.normalize('path/to/file', options), 'path/to/file', 'plain path unchanged')
+  t.equal(fastURI.normalize('a/b:c', options), 'a/b:c', 'colon in a later segment stays literal')
+  t.end()
+})

package/test/scheme-validation.test.js

@@ -15,7 +15,15 @@ const malformedSchemes = [
   'foo_bar:value',
   'éxample:value',
   'Kttp://example.com/',
-  'ſcheme:value'
+  'ſcheme:value',
+  // RFC 3986 section 3.1 does not allow percent-encoding in a scheme.
+  '%4Aavascript:alert(1)',
+  '%6aavascript:alert(1)',
+  'foo%2Bbar:value',
+  '%u006Aavascript:1',
+  'ht%74ps://example.com/',
+  'ma%69lto:user@example.org',
+  '%64ata:text/html,x'
 ]
 
 test('parse validates the decoded scheme against RFC 3986', (t) => {
@@ -23,10 +31,7 @@ test('parse validates the decoded scheme against RFC 3986', (t) => {
     ['a:value', 'a'],
     ['HTTP://example.com/', 'http'],
     ['a1+.-:value', 'a1+.-'],
-    ['%4Aavascript:alert(1)', 'javascript'],
-    ['foo%2Bbar:value', 'foo+bar'],
-    ['%u006Aavascript:1', 'javascript'],
-    ['ht%74ps://example.com/', 'https']
+    ['foo+bar:value', 'foo+bar']
   ]
 
   for (const [uri, scheme] of validSchemes) {
@@ -42,17 +47,41 @@ test('parse validates the decoded scheme against RFC 3986', (t) => {
   t.end()
 })
 
-test('decoded schemes select their scheme handlers', (t) => {
+test('percent-encoded schemes do not select scheme handlers', (t) => {
   t.equal(
     fastURI.normalize('ht%74ps://example.com:443'),
-    'https://example.com/',
-    'HTTP normalization runs after decoding the scheme'
+    'ht%74ps://example.com:443',
+    'HTTP normalization does not run for an encoded scheme'
   )
 
-  // 3.x has no mailto scheme handler (added in v4); use the ws handler to
-  // verify that a percent-encoded scheme still selects its scheme handler
-  const ws = fastURI.parse('we%62socket://example.com/')
-  t.equal(ws.scheme, 'websocket', 'ws parsing runs after decoding the scheme')
+  // 2.x has no mailto scheme handler (added in v3); use the ws handler to
+  // verify that a percent-encoded scheme does not select a scheme handler
+  const ws = fastURI.parse('w%73://example.com/?q')
+  t.equal(ws.resourceName, undefined, 'ws parsing does not run for an encoded scheme')
+  t.equal(ws.error, MALFORMED_SCHEME_ERROR)
+  t.end()
+})
+
+test('normalization cannot synthesize a scheme from encoded input', (t) => {
+  const inputs = [
+    '%6Aavascript:alert(1)',
+    '%4A%41%56%41%53%43%52%49%50%54:alert(1)',
+    '%u006Aavascript:alert(1)',
+    'j%61vascript:alert(1)',
+    '%64ata:text/html,<script>alert(1)</script>',
+    'vb%73cript:msgbox(1)'
+  ]
+
+  for (const uri of inputs) {
+    const parsed = fastURI.parse(uri)
+    t.equal(parsed.error, MALFORMED_SCHEME_ERROR, uri + ' is malformed')
+    t.notOk(/^(?:javascript|data|vbscript):/i.test(String(parsed.scheme) + ':'), uri + ' parsed scheme is not decoded')
+    t.equal(fastURI.normalize(uri), uri, uri + ' normalizes to itself')
+    t.equal(fastURI.equal(uri, uri), false, uri + ' is not comparable')
+    t.throws(() => fastURI.resolve('https://example.com/app/', uri), /URI scheme is malformed\./, uri + ' is rejected by resolve')
+  }
+
+  t.equal(fastURI.equal('%68ttp://a/', 'http://a/'), false, 'encoded scheme does not alias a plain scheme')
   t.end()
 })
 
@@ -95,11 +124,21 @@ test('resolve rejects malformed decoded schemes in either input', (t) => {
   t.end()
 })
 
-test('serialize validates decoded component schemes', (t) => {
+test('serialize validates component schemes without decoding them', (t) => {
   t.equal(
-    fastURI.serialize({ scheme: 'foo%2Bbar', path: 'value' }),
+    fastURI.serialize({ scheme: 'foo+bar', path: 'value' }),
     'foo+bar:value',
-    'valid decoded scheme is serialized'
+    'valid scheme is serialized'
+  )
+  t.throws(
+    () => fastURI.serialize({ scheme: 'foo%2Bbar', path: 'value' }),
+    /URI scheme is malformed\./,
+    'percent-encoded scheme is rejected'
+  )
+  t.throws(
+    () => fastURI.serialize({ scheme: '%6Aavascript', path: 'alert(1)' }),
+    /URI scheme is malformed\./,
+    'encoded scheme cannot serialize as javascript:'
   )
   t.throws(
     () => fastURI.serialize({ scheme: '//evil.example', path: '/pwn' }),

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/'