fast-uri 4.2.2 → 4.2.3

package/.github/workflows/release.yml

@@ -11,6 +11,14 @@ on:
           - 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: {}
 
@@ -19,6 +27,8 @@ jobs:
     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@b1a11bce713bc857e52b2231fec3c89071ad3135
+    uses: fastify/workflows/.github/workflows/reusable-release.yml@b0a2ab2d8259b6bd574b804cd6874bbd75c3577c
     with:
       semver: ${{ inputs.semver }}
+      preid: ${{ inputs.preid }}
+      dist-tag: ${{ startsWith(inputs.semver, 'pre') && 'next' || 'latest' }}

package/README.md

@@ -15,12 +15,18 @@ All of the above functions can accept an additional options argument that is an
 
 Malformed authorities, out-of-range ports, and raw leading or trailing C0 controls or spaces (U+0000–U+0020) are reported through the parsed component's `error` field. `normalize()` leaves these malformed string inputs unchanged, and `equal()` returns `false`. `resolve()` rejects them in either input and rejects HTTP(S) results with an empty host. Percent-encoded and interior component data remain valid.
 
+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.
 
@@ -80,6 +86,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, encodeHost, isIPv4, nonSimpleDomain } = require('./lib/utils')
+const { normalizeIPv6, removeDotSegments, removeDotSegmentsRelative, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, encodeHost, isIPv4, nonSimpleDomain } = require('./lib/utils')
 const { SCHEMES, getSchemeHandler } = 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
 }
 
 /**
@@ -88,6 +96,12 @@ function resolve (baseURI, relativeURI, options) {
   }
   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
@@ -167,14 +181,17 @@ function resolveComponent (base, relative, options, skipNormalization) {
         if (relative.path[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
       }
@@ -235,7 +252,7 @@ function serialize (cmpts, opts) {
   const uriTokens = []
 
   if (component.scheme) {
-    component.scheme = decodeValidScheme(component.scheme)
+    component.scheme = validateScheme(component.scheme)
   }
 
   // find scheme handler
@@ -245,7 +262,11 @@ function serialize (cmpts, opts) {
   if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options)
 
   const hasAuthority = component.userinfo !== undefined || component.host !== undefined || component.port !== undefined
-  const pathNoScheme = !options.skipEscape && component.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 = (component.scheme === undefined || options.reference === 'suffix') && !hasAuthority
+  const pathNoScheme = !options.skipEscape && schemelessReference
 
   if (component.path !== undefined) {
     if (!options.skipEscape) {
@@ -257,7 +278,7 @@ function serialize (cmpts, opts) {
 
   if (options.reference !== 'suffix' && component.scheme) {
     // Scheme handlers may replace the scheme during serialization.
-    component.scheme = decodeValidScheme(component.scheme)
+    component.scheme = validateScheme(component.scheme)
     uriTokens.push(component.scheme, ':')
   }
 
@@ -278,13 +299,18 @@ function serialize (cmpts, opts) {
     let s = component.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)
     }
 
@@ -404,6 +430,11 @@ function canonicalizeHost (parsed, options, schemeHandler, isIP) {
     parsed.host[0] === '[' &&
     parsed.host[parsed.host.length - 1] === ']'
 
+  if (hasForbiddenDomainHost(parsed, options, schemeHandler, isIP)) {
+    parsed.error = parsed.error || MALFORMED_HOST_ERROR
+    return true
+  }
+
   if (
     !options.unicodeSupport &&
     (!schemeHandler || !schemeHandler.unicodeSupport) &&
@@ -414,17 +445,63 @@ function canonicalizeHost (parsed, options, schemeHandler, isIP) {
     !bracketedIPLiteral &&
     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 !== ''
+}
+
 /**
  * @param {string} uri
  * @param {import('./types/index').Options} [opts]
@@ -517,9 +594,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
@@ -563,7 +639,7 @@ function parseWithStatus (uri, opts) {
         }
 
         if (malformedIPLiteral) {
-          parsed.error = parsed.error || 'URI host is malformed.'
+          parsed.error = parsed.error || MALFORMED_HOST_ERROR
           malformedAuthorityOrPort = true
         }
       } else {

package/lib/utils.js

@@ -352,6 +352,57 @@ function removeDotSegments (path) {
   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('/')
+}
+
 /**
  * Encodes a host according to the RFC 3986 host grammar. Valid IP literals
  * have already been checked by `normalizeIPv6`, so their address separators
@@ -857,6 +908,7 @@ module.exports = {
   encodeFragment,
   escapePreservingEscapes,
   removeDotSegments,
+  removeDotSegmentsRelative,
   isIPv4,
   isUUID,
   normalizeIPv6,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fast-uri",
   "description": "Dependency-free RFC 3986 URI toolbox",
-  "version": "4.2.2",
+  "version": "4.2.3",
   "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,152 @@
+'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 normalization preserves relative path meaning', (t) => {
+  const options = { reference: 'suffix', scheme: 'x' }
+  for (const [input, expected] of [
+    ['a/../b', 'b'],
+    ['x/..', './'],
+    ['a/../a:b', './a:b']
+  ]) {
+    t.equal(fastURI.normalize(input, options), expected, `${input} -> ${expected}`)
+  }
+  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,15 +47,39 @@ 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'
   )
 
   const mailto = fastURI.parse('ma%69lto:user@example.org')
-  t.deepEqual(mailto.to, ['user@example.org'], 'mailto parsing runs after decoding the scheme')
+  t.equal(mailto.to, undefined, 'mailto parsing does not run for an encoded scheme')
+  t.equal(mailto.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()
 })
 
@@ -93,11 +122,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' }),