//nefariousplan

Gate Before Canonicalize

A security check inspects an input for a forbidden form. A downstream subsystem canonicalizes the same input (URL decoding, path-parameter stripping, Unicode normalization, escape resolution) into that forbidden form. The check sees the wrapped representation; the action sees the unwrapped one. The fix is to canonicalize before checking, never after.

A security gate reads an input, inspects it for a forbidden form, and declares the input clean. A downstream subsystem reads the same input, runs it through a transformation the gate never applied, and acts on the result. The transformation is the sink's own canonicalization: a URL decode, a path-parameter strip, an IPv6 address unmap, a Unicode case fold, an escape resolution, a str_replace whose fragments happen to fuse into the forbidden form. The gate is looking at the wrapped bytes; the sink is operating on the unwrapped ones. The two never see the same string.

The violated assumption is that validating an input validates what the input will become. A canonicalizer installed between the gate and the sink breaks that assumption by manufacturing the forbidden form inside the trust boundary the gate was drawn around. The fix is structural: canonicalize before checking, not after. Any check that inspects a representation the sink will transform has already lost.

Mechanism

The shape is a three-step pipeline. Step one is a security predicate: a regex, a validate_file(), a filter_var($..., FILTER_VALIDATE_IP), a startsWith('/api/'), an includes('..'), an ACL lookup against a route grammar, a signed-prefix comparison. It inspects an input against a forbidden form (path traversal segments, private address ranges, dangerous HTML tags, out-of-scope paths, forbidden URL schemes). Step two is a canonicalization: url.PathUnescape, path.Clean, str_replace, PHP's urldecode, Go's net/netip.ParseAddr, Win32 LCMapStringEx, Node's fs.realpathSync, the kernel's getaddrinfo, marked.parse, Array.prototype.join, JavaScript's decodeURIComponent, Perl's ExifTool tag resolver, NTFS ADS separator handling. Step three is the dangerous sink that the canonicalized form reaches: locate_template, fs.rm, HTTPConnectionPool.connect, innerHTML, CreateFileW, fs.openat with truncate, a Kerberos ticket issuance, a proxied upstream fetch.

The three are usually written by different authors. Often they live in different files, sometimes in different processes or different machines. The predicate's author believes the forbidden form will reach their check unaltered. The canonicalizer's author is doing something the subsystem needs for its own correctness, not for security: a URL library lowercases the scheme because that is what URI normalization means; a kernel performs case-folded Unicode comparison because that is what Unicode equality means; an archive extractor resolves NTFS ADS separators because that is what NTFS semantics require; a template engine resolves CSS nesting because that is what the specification defines. Each transform is defensible in isolation. Composed with a gate that runs before the transform, they produce the forbidden form on the attacker's behalf.

The failure repeats across stacks because canonicalization is pervasive and gates are local. Any system that routes, parses, decodes, resolves, or normalizes before acting has at least one place where the canonical form differs from the wire form. Any gate that compares strings instead of structured semantic representations has a candidate gap. The catalog exhibits trace the same shape through HTTP routers (Atlassian's webresource Router inventing a :: to / rewrite that Tomcat does not speak, CVE-2026-21589; UniFi's auth gate reading x-original-uri while Nginx dispatched against the normalized $uri, CVE-2026-34910; Alfresco Share's regex denylist on ..;/ that Tomcat collapsed to ../, CVE-2026-26336), filesystem helpers (SillyTavern's /api/extensions/delete running the truthy check before sanitize-filename collapsed . to the empty string, CVE-2026-44650; WinRAR's file_name_check deleting trailing dots and spaces to manufacture the path traversal its component-start rule was supposed to catch, CVE-2025-6218), string manipulation (Visual Composer's str_replace('theme:', '') producing the ../../../ that validate_file had just approved, CVE-2026-12227; SiYuan's escapeAriaLabel running before a decodeURIComponent call that manufactured the angle brackets the encoder was supposed to prevent, CVE-2026-44588), SSRF validation (MLflow's webhook validator resolving a hostname via getaddrinfo only for requests.post to resolve it again against DNS-rebind-flipped authoritative records, CVE-2026-64849; Statamic's filter_var IPv6 range tables not classifying IPv4-mapped prefixes before PHP 8.3, CVE-2026-45660), reverse-proxy middlewares (s3-proxy's auth layer reading r.URL.RequestURI() while the handler read chi.URLParam + url.PathUnescape, CVE-2026-42882; Nitro's radix3 router keeping %2F opaque while the proxied upstream decoded, CVE-2026-44373; Traefik's StripPrefix running JoinPath on the stripped bytes to produce /admin from /api../admin, CVE-2026-48020), and off-URL grammars entirely (Microsoft's CompareStringW using NORM_IGNORECASE while lsass's SPN lookup used 0x31403's wider flag set to normalize enclosed-alphanumerics back to local-machine identity, CVE-2026-26128). The transform categories vary. The structural defect does not.

The pattern's distinguishing feature against Gate Narrower Than Sink is the presence of an intermediate transform. Gate-narrower-than-sink pairs two matchers describing the same bytes through different grammars: a brace counter against a CSS compiler, a startswith('SELECT') against a Trino SQL parser, a \s+ regex against an \s* regex. The matchers may see identical input; they simply recognize different sets. Gate-before-canonicalize requires a canonicalization step that produces the forbidden form only on the sink's side. The gap is a function call, not a grammar difference.

The structural fix is to canonicalize before checking. Apply the sink's transforms to the input, then run the predicate against the output. Spring's uriDecode exhibit at CVE-2025-41242 shows what happens when canonicalization is partial: the author truncated sixteen-bit Java chars into eight-bit bytes before the check and Jetty 12 finished the canonicalization afterwards, manufacturing the IIS escape .%u002e that Spring's pattern set did not cover. Partial canonicalization moves the gap; it does not close it. The costlier fix is a bouncer: refuse any input where the two parses would diverge, which s3-proxy, Nitro, Open WebUI, and UniFi all chose when unifying the parsers was architecturally infeasible. The gate and the sink stay disagreeing about strings nobody is allowed to send. The class signature is the same; only the implementation substrate rotates.

Exhibits

CVE-2026-42882: s3-proxy's Auth Reads One Path. Its Handler Reads Another. The Patch Adds a Bouncer.. CVE-2026-42882 is the Go-language exhibit of the pattern. s3-proxy's auth middleware glob-matches resource patterns against r.URL.RequestURI() (encoded). Its bucket handler reads chi.URLParam(req, "*") followed by url.PathUnescape (decoded). The same URL produces two different paths, and three distinct exploit techniques (a glob * that crosses / boundaries, %2F smuggling, and .. traversal under **) all live in the gap. The diagnostic move that distinguishes this exhibit from the Alfresco regex case and the Spring uriDecode case: the patch does not unify the two parses. It adds a third middleware that decodes the path, calls path.Clean, and rejects the request if a segment was lost. The auth layer and the storage layer still consume different representations; the fix gates the door so the disagreement can no longer be reached through known techniques. The pattern's class signature applied verbatim, with the structurally correct GHSA recommendation (r.URL.EscapedPath() in both layers) declined in favour of a guard.

CVE-2025-41242: Spring's `uriDecode` Wrote 16-Bit Chars Into an 8-Bit Sink. Jetty 12 Finished the Traversal.. Spring's StringUtils.uriDecode is the canonicaliser in two senses. It produces the string Spring's path-traversal gate then inspects, and it does so by truncating sixteen-bit Java chars into eight-bit bytes via ByteArrayOutputStream.write(int), manufacturing the IIS escape .%u002e out of 阮严灵丰丰甲来. Spring's gate runs isInvalidPath against that output and sees a token whose alphabet its pattern set does not cover. Jetty 12's URIUtil.encodePathSafeEncoding, which sits after the gate, recognises %uXXXX and finishes the canonicalisation that Spring's checks were never written to detect. Two parsers disagreed about what the bytes said. The check ran against the wrapped representation; the action ran against the unwrapped one.

CVE-2026-26336: Alfresco's Path Blacklist Has Never Blocked ..;/. Hyland Alfresco Share's resource controller runs a regex denylist (.*/\.\./WEB-INF/.*) against the URL Spring extracted from /share/page/resource/**. Tomcat then resolves the same path against the disk, treating ..; as .. because ; opens a path-parameter segment. The regex sees ..;/; the file system sees ../. CVE-2026-26336 is the read primitive that lives between those two parses. The pattern's class signature: any defense that string-inspects an input the next layer is going to canonicalize.

CVE-2026-34910: UniFi's Auth Gate Read The Raw URI. Nginx Routed The Normalized One.. CVE-2026-34910 is the catalog's first network-appliance exhibit of the pattern. UniFi OS Server's auth gate reads x-original-uri, the request URI Nginx populates from the wire (percent-encoded, traversal segments intact); its router dispatches against $uri, the same URI after Nginx's normalization passes (decoded, dot-segments resolved). The same request is two different strings. The gate's startsWith("/api/auth/validate-sso/") returns true for /api/auth/validate-sso/..%2f..%2f..%2fproxy/users/..., the router's location match runs against /proxy/users/... after %2f decode and .. resolution, and the SSO callback's auth exemption becomes a free pass to every authenticated upstream. Prior exhibits split the two parses across components (Tomcat vs Spring), middleware (s3-proxy auth vs handler), or machines (Nitro vs an upstream). UniFi splits them across the smallest possible boundary: two Nginx variables the same process populates from the same request, one before its own normalization and one after. The 5.0.8 patch is a $request_uri regex rejection of percent-encoded .. / %2f / %5c ahead of the gate, the textbook canonicalize-before-gate refactor declined in favor of a bouncer.

CVE-2026-40280: Gotenberg's Named Fix Adds the Case-Sensitive Regex. A Commit Four Days Later Replaces the Layer.. CVE-2026-40280 is the URL-scheme variant of the pattern. Gotenberg's default deny-list compiles ^https?://(10\.|...) with regexp2.MustCompile(pattern, 0), a case-sensitive byte-pattern match against the caller-supplied URL string. Go's net/url.Parse lowercases the scheme during parse, and net/http dials the lowercased form. HTTPS://169.254.169.254/ clears the gate as written; the dial reaches the IMDS endpoint as parsed. The pattern's class signature applied to URL schemes rather than paths: the check ran against the wrapped representation, the action ran against the unwrapped one. The post traces the 8.31.0 fix as the textbook canonicalize-before-gate refactor, parsed.Scheme = strings.ToLower(parsed.Scheme) is executed before the regex runs in the new decideOutbound function, while the deny-list regex itself stays case-sensitive in the source.

CVE-2025-6218: WinRAR's file_name_check Produced the Path Traversal It Was Supposed to Catch. CVE-2025-6218 is the pattern compressed onto a single stack frame. WinRAR's file_name_check holds both the path-traversal preservation logic (legitimate .. at component starts is explicitly kept) and the trailing-whitespace canonicalisation (deleting trailing dots and spaces from each component). The deletion produces the path traversal the function's discrimination logic was supposed to gate. The Alfresco regex case and the Spring uriDecode case split the parses across two components; the s3-proxy case splits them across two middleware layers. WinRAR collapses both onto one function and never re-reads its own output. The fix is the cheapest possible: change delete_char into in-place substitution, so the canonicalisation cannot manufacture forbidden forms by sliding adjacent characters into contact.

Boundaries

Not every gate/sink mismatch is this pattern. Gate Narrower Than Sink covers the case where two matchers inspect the same bytes with grammars that disagree: name.startsWith('on') against the HTML tokenizer's whitespace separator, a brace counter against a CSS compiler, a startswith('SELECT') against a Trino SQL parser, preg_replace with \s+ against an executor with \s*. The gap is a grammar difference; the matchers may both be reading the raw bytes. Gate-before-canonicalize requires a function call between the gate and the sink that produces the forbidden form from an input the gate approved. If you can remove the canonicalizer and the bypass goes away, it is this pattern. If you can prove both matchers see identical input and still disagree, it is Gate Narrower Than Sink.

Not every pre-transform-then-verify failure is this pattern. Canonicalize Before Verify is the signature-verification instance: the verifier runs a parser or re-encoder before the cryptographic hash, and the signature ends up attesting to the transformed form rather than the raw bytes downstream consumers act on. The crypto domain inverts the ordering problem. Canonicalization there must happen before the hash because the specification requires it (XMLDSIG canonicalizes <ds:SignedInfo> before signing); the bug is that different consumers run different canonicalizations and the signature covers the wrong bytes. Gate-before-canonicalize is the broader structural shape where a gate runs too early; canonicalize-before-verify is the crypto-specific case where the cryptographic operation itself is the gate and its transforms are part of the specification.

Not every parallel enforcement failure is this pattern. Parallel Implementation Gap covers the case where two modules implement the same capability and only one is gated: a REST handler that imports the auth check and a gRPC handler that was written separately and did not. There is no shared string that is canonicalized between them; each module has its own code path, its own developers, and its own missing check. Gate-before-canonicalize lives inside one logical request where the gate runs and the sink runs on the same input, with a canonicalizer between them. Parallel implementation gap lives across two logical requests where one of them is simply ungated.

Not every gate that reads the wrong field is this pattern. Validated Source, Not Destination and Predicate Stringifies The Object cover cases where the gate inspects a different variable from the one the sink consumes. The gate's representation is not a canonicalized form of the sink's input; the two inputs are different inputs. Gate-before-canonicalize requires the gate and the sink to read the same logical value, with the gap introduced by a transformation. If two separate request fields are involved, the mechanism is field selection, not canonicalization.

Defender playbook

Enumerate every transformation that runs between a gate and its sink. URL decoders, path cleaners, Unicode normalizers, address resolvers, string-replace helpers, trailing-character strippers, case folders, archive extractors with special separators, template renderers that emit new tokens, template engines that resolve CSS nesting. For each transform, write down the characters it can produce from inputs that lack those characters. Any transform whose output grammar is wider than its input grammar is a canonicalization that can manufacture the forbidden form. The audit output is a list of (gate, canonicalizer, sink) triples. For each triple, verify that the gate runs against the canonicalizer's output, not its input.

Move the gate to the canonical representation. If the sink runs urldecode on the string, run urldecode first and validate the decoded form. If the sink will lowercase the scheme, lowercase before the regex. If the sink will unmap ::ffff:127.0.0.1 into 127.0.0.1, unmap before the IP check. If the sink will resolve a hostname via getaddrinfo, resolve before the SSRF predicate and then dial the resolved address, not the original hostname. The predicate must consume the same bytes the sink will act on, not the bytes the user typed. Partial canonicalization is not a fix; it moves the gap one transform closer to the sink and leaves the class intact, as the Spring uriDecode exhibit demonstrates.

For architectures where unifying the two parses is infeasible (multiple processes, library canonicalizers you do not control, cross-language routing boundaries, kernel-level canonicalizers like Win32 LCMapStringEx), install a bouncer. The pattern as applied in s3-proxy, Nitro, UniFi, and Traefik: a third middleware ahead of both gate and sink that refuses any input whose pre-canonical and post-canonical forms differ in a security-relevant axis. The bouncer does not close the class; it denies the known bypass surface while a structural canonicalize-then-check patch is designed. Document the bouncer as a quarantine, not as the fix, so later refactors do not demote it.

Test the patch by constructing inputs whose pre-canonical and post-canonical forms differ at exactly one forbidden character. For URL gates: %2F, %2E, ..;, trailing ?, trailing #, IPv4-mapped IPv6, octal-and-hex IPv4 notation, mixed-case schemes. For filesystem gates: trailing dots and spaces, empty string, ., NTFS ADS : separator, Unicode normalization forms. For template and HTML gates: whitespace characters the HTML tokenizer accepts (tab, LF, FF, CR, NBSP), angle brackets manufactured by marked.parse or decodeURIComponent. A patch that rejects only one of the pre-canonical and post-canonical forms has moved the gap, not closed it. If the patch's own regression test asserts the bypass input is the expected output, as Traefik's StripPrefix test did for forty-two days, the gap shipped as the contract.

Kinship

Gate Narrower Than Sink. Nearest sibling. Both describe a gate and a sink that disagree about the input. Gate-narrower-than-sink splits the gap into a grammar difference: two matchers read the same bytes and recognize different sets. Gate-before-canonicalize splits the gap into a transformation: a canonicalization step between the gate and the sink produces the forbidden form on the sink's side. Many bugs live in the overlap, where a narrower gate grammar interacts with a sink's canonicalization of the input the gate was written to describe. When reviewing a candidate exhibit, ask whether removing the transformation closes the bypass. If yes, this pattern. If the matchers still disagree on identical input, the sibling.

Parallel Implementation Gap. Distant cousin. Parallel-implementation-gap also names a trust-boundary mismatch, but the split is across modules rather than across a transformation. Two parallel implementations share a client-facing contract and only one imports the check. Gate-before-canonicalize lives inside a single request where one gate did run. The two are confused in post-mortems because both produce a bypass path that evaded a check that exists.

Internal Only By Convention. Shared root in documentation-not-enforcement. Internal-only-by-convention is about a trust property carried by a field's name or framework label that the runtime does not enforce. Gate-before-canonicalize is about a canonicalization contract between gate and sink that is implicit in author intent and not expressed in code. Both fail because the invariant lives in the developer's head and not in the type system or the control flow.

The gate validates bytes nobody will act on.