001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import com.revetsec.internal.HostClassifier; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023 024import javax.annotation.concurrent.Immutable; 025import javax.annotation.concurrent.NotThreadSafe; 026import java.net.URI; 027import java.util.LinkedHashSet; 028import java.util.List; 029import java.util.Locale; 030import java.util.Set; 031 032import static java.util.Objects.requireNonNull; 033 034/** 035 * Checks browser request metadata against exact configured origins. 036 * <p> 037 * Configure this immutable policy once, then pass it the HTTP method and every raw field occurrence for 038 * {@code Sec-Fetch-Site} and {@code Origin}. Safe methods are admitted. For other methods, 039 * {@code Sec-Fetch-Site: same-origin} and {@code Sec-Fetch-Site: none} are sufficient when {@code Origin} is absent, 040 * opaque or exactly configured, including when a no-referrer page sends {@code Origin: null}. A contradictory 041 * concrete origin rejects. Same-site, cross-site, absent and future syntactically valid fetch-site values require an 042 * exact configured origin. Duplicate or malformed fields reject. 043 * <p> 044 * This is a request-origin admission layer, not a complete CSRF defense. Keep application state or synchronizer 045 * tokens where the workflow requires them, validate the request's host at a trusted edge, and do not derive allowed 046 * origins from {@code Host} or {@code Forwarded}. 047 * 048 * @since 1.0.0 049 */ 050@Immutable 051@CheckReturnValue 052public final class BrowserRequestOriginPolicy { 053 private static final int MAXIMUM_ORIGIN_LENGTH = 2_048; 054 private static final int MAXIMUM_FETCH_SITE_LENGTH = 64; 055 056 private final @NonNull Set<@NonNull String> allowedOrigins; 057 private final boolean allowMissingMetadata; 058 059 private BrowserRequestOriginPolicy(@NonNull Builder builder) { 060 Set<String> origins = new LinkedHashSet<>(); 061 for (URI origin : builder.allowedOrigins) 062 origins.add(requireCanonicalOrigin(origin, builder.allowInsecureLoopback)); 063 if (origins.isEmpty()) 064 throw new IllegalArgumentException("At least one allowed browser origin is required"); 065 this.allowedOrigins = Set.copyOf(origins); 066 this.allowMissingMetadata = builder.allowMissingMetadata; 067 } 068 069 /** 070 * Starts a policy with an exact, complete allowed-origin set. 071 * <p> 072 * Origins must use their canonical ASCII serialization: lower-case {@code https} scheme and host, no user 073 * information, path, query or fragment, and no explicit default port. Plain {@code http} is rejected unless the 074 * development option is enabled, and then is limited to a loopback literal or exactly {@code localhost}. 075 * 076 * @param allowedOrigins exact allowed origins 077 * @return a new builder 078 * @throws NullPointerException if the set or an entry is {@code null} 079 * @since 1.0.0 080 */ 081 public static @NonNull Builder withAllowedOrigins(@NonNull Set<@NonNull URI> allowedOrigins) { 082 return new Builder(allowedOrigins); 083 } 084 085 /** 086 * Checks a request without retaining its metadata. 087 * <p> 088 * The two lists must preserve separate field occurrences. A list with more than one element rejects even if the 089 * values are identical. Safe methods ({@code GET}, {@code HEAD} and {@code OPTIONS}) are admitted before request 090 * metadata is inspected. Frameworks are responsible for supplying a valid HTTP method token. 091 * 092 * @param method HTTP method 093 * @param secFetchSiteHeaderValues every raw {@code Sec-Fetch-Site} field occurrence 094 * @param originHeaderValues every raw {@code Origin} field occurrence 095 * @return closed admission outcome 096 * @throws NullPointerException if an input, list entry or method is {@code null} 097 * @throws IllegalArgumentException if {@code method} is not a valid HTTP token 098 * @since 1.0.0 099 */ 100 public @NonNull BrowserRequestOriginResult checkResult(@NonNull String method, 101 @NonNull List<@NonNull String> secFetchSiteHeaderValues, 102 @NonNull List<@NonNull String> originHeaderValues) { 103 requireHttpToken(requireNonNull(method)); 104 requireEntries(secFetchSiteHeaderValues); 105 requireEntries(originHeaderValues); 106 if (method.equals("GET") || method.equals("HEAD") || method.equals("OPTIONS")) 107 return BrowserRequestOriginResult.allowed(BrowserRequestOriginResult.Basis.SAFE_METHOD); 108 if (secFetchSiteHeaderValues.size() > 1 || originHeaderValues.size() > 1) 109 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.MALFORMED); 110 111 @Nullable String fetchSite = secFetchSiteHeaderValues.isEmpty() ? null 112 : structuredToken(secFetchSiteHeaderValues.get(0)); 113 if (!secFetchSiteHeaderValues.isEmpty() && fetchSite == null) 114 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.MALFORMED); 115 116 @Nullable String origin = originHeaderValues.isEmpty() ? null : originHeaderValues.get(0); 117 OriginKind originKind = classifyOrigin(origin); 118 if (originKind == OriginKind.MALFORMED) 119 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.MALFORMED); 120 121 if ("same-origin".equals(fetchSite) || "none".equals(fetchSite)) { 122 if (originKind == OriginKind.UNTRUSTED) 123 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.UNTRUSTED_ORIGIN); 124 return BrowserRequestOriginResult.allowed("same-origin".equals(fetchSite) 125 ? BrowserRequestOriginResult.Basis.SAME_ORIGIN 126 : BrowserRequestOriginResult.Basis.USER_INITIATED); 127 } 128 if (originKind == OriginKind.CONFIGURED) 129 return BrowserRequestOriginResult.allowed(BrowserRequestOriginResult.Basis.CONFIGURED_ORIGIN); 130 if (originKind == OriginKind.NULL) 131 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.NULL_ORIGIN); 132 if (originKind == OriginKind.UNTRUSTED) 133 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.UNTRUSTED_ORIGIN); 134 if ("cross-site".equals(fetchSite)) 135 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.CROSS_SITE); 136 if ("same-site".equals(fetchSite)) 137 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.SAME_SITE); 138 if (fetchSite != null) 139 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.UNRECOGNIZED_FETCH_SITE); 140 if (this.allowMissingMetadata) 141 return BrowserRequestOriginResult.allowed( 142 BrowserRequestOriginResult.Basis.MISSING_METADATA_COMPATIBILITY); 143 return BrowserRequestOriginResult.rejected(BrowserRequestOriginResult.Reason.MISSING_METADATA); 144 } 145 146 /** 147 * Redacts the configured origins and options. 148 * 149 * @return a fixed description 150 * @since 1.0.0 151 */ 152 @Override 153 public @NonNull String toString() { 154 return "BrowserRequestOriginPolicy{configuration=<redacted>}"; 155 } 156 157 private @NonNull OriginKind classifyOrigin(@Nullable String origin) { 158 if (origin == null) 159 return OriginKind.ABSENT; 160 if (origin.equals("null")) 161 return OriginKind.NULL; 162 if (origin.length() > MAXIMUM_ORIGIN_LENGTH) 163 return OriginKind.MALFORMED; 164 final URI parsed; 165 try { 166 parsed = URI.create(origin); 167 } catch (IllegalArgumentException invalid) { 168 return OriginKind.MALFORMED; 169 } 170 @Nullable String canonical = canonicalOrigin(parsed); 171 if (canonical == null || !canonical.equals(origin)) 172 return OriginKind.MALFORMED; 173 return this.allowedOrigins.contains(canonical) ? OriginKind.CONFIGURED : OriginKind.UNTRUSTED; 174 } 175 176 private static @Nullable String structuredToken(@NonNull String raw) { 177 if (raw.length() > MAXIMUM_FETCH_SITE_LENGTH) 178 return null; 179 int first = 0; 180 int last = raw.length(); 181 while (first < last && (raw.charAt(first) == ' ' || raw.charAt(first) == '\t')) first++; 182 while (last > first && (raw.charAt(last - 1) == ' ' || raw.charAt(last - 1) == '\t')) last--; 183 if (first == last || !isTokenFirst(raw.charAt(first))) 184 return null; 185 for (int index = first + 1; index < last; index++) 186 if (!isTokenRest(raw.charAt(index))) return null; 187 return raw.substring(first, last); 188 } 189 190 private static boolean isTokenFirst(char character) { 191 return character == '*' || (character >= 'A' && character <= 'Z') 192 || (character >= 'a' && character <= 'z'); 193 } 194 195 private static boolean isTokenRest(char character) { 196 return isTokenFirst(character) || (character >= '0' && character <= '9') 197 || ":/!#$%&'*+-.^_`|~".indexOf(character) >= 0; 198 } 199 200 private static void requireEntries(@NonNull List<@NonNull String> values) { 201 requireNonNull(values); 202 for (String value : values) requireNonNull(value); 203 } 204 205 private static void requireHttpToken(@NonNull String method) { 206 if (method.isEmpty()) 207 throw new IllegalArgumentException("HTTP method must be a token"); 208 for (int index = 0; index < method.length(); index++) { 209 char character = method.charAt(index); 210 boolean token = (character >= '0' && character <= '9') || (character >= 'A' && character <= 'Z') 211 || (character >= 'a' && character <= 'z') || "!#$%&'*+-.^_`|~".indexOf(character) >= 0; 212 if (!token) throw new IllegalArgumentException("HTTP method must be a token"); 213 } 214 } 215 216 private static @NonNull String requireCanonicalOrigin(@NonNull URI origin, boolean allowInsecureLoopback) { 217 requireNonNull(origin); 218 @Nullable String canonical = canonicalOrigin(origin); 219 if (canonical == null || !canonical.equals(origin.toASCIIString())) 220 throw new IllegalArgumentException("Allowed browser origins must use canonical origin syntax"); 221 if (origin.getScheme().equals("http") 222 && (!allowInsecureLoopback || !HostClassifier.isPlainHttpLoopbackHost(requireNonNull(origin.getHost())))) 223 throw new IllegalArgumentException("Plain HTTP browser origins require the loopback development option"); 224 return canonical; 225 } 226 227 private static @Nullable String canonicalOrigin(@NonNull URI origin) { 228 @Nullable String scheme = origin.getScheme(); 229 @Nullable String host = origin.getHost(); 230 if (scheme == null || host == null || !(scheme.equals("https") || scheme.equals("http")) 231 || origin.getRawUserInfo() != null || origin.getRawQuery() != null || origin.getRawFragment() != null 232 || !origin.getRawPath().isEmpty() || origin.getPort() == 0 || origin.getPort() > 65_535) 233 return null; 234 final String renderedHost; 235 if (host.startsWith("[")) { 236 // URI.getHost() keeps IPv6 brackets. Browsers send the WHATWG serialization, so render that form. 237 byte @Nullable [] address = HostClassifier.parseLiteral(host); 238 if (address == null || address.length != 16) 239 return null; 240 renderedHost = "[" + serializeIpv6(address) + "]"; 241 } else { 242 renderedHost = host.toLowerCase(Locale.ROOT); 243 } 244 int port = origin.getPort(); 245 if ((port == 443 && scheme.equals("https")) || (port == 80 && scheme.equals("http"))) 246 port = -1; 247 return scheme + "://" + renderedHost + (port < 0 ? "" : ":" + port); 248 } 249 250 /** WHATWG URL IPv6 serializer: lower-case hex, first longest run of two or more zero pieces compressed. */ 251 private static @NonNull String serializeIpv6(byte @NonNull [] address) { 252 int[] pieces = new int[8]; 253 for (int index = 0; index < 8; index++) 254 pieces[index] = ((address[2 * index] & 0xff) << 8) | (address[2 * index + 1] & 0xff); 255 int compress = -1; 256 int longest = 1; 257 int start = 0; 258 while (start < 8) { 259 if (pieces[start] != 0) { start++; continue; } 260 int end = start; 261 while (end < 8 && pieces[end] == 0) end++; 262 if (end - start > longest) { compress = start; longest = end - start; } 263 start = end; 264 } 265 StringBuilder output = new StringBuilder(39); 266 int index = 0; 267 while (index < 8) { 268 if (index == compress) { 269 output.append(index == 0 ? "::" : ":"); 270 index += longest; 271 continue; 272 } 273 output.append(Integer.toHexString(pieces[index])); 274 if (index != 7) output.append(':'); 275 index++; 276 } 277 return output.toString(); 278 } 279 280 private enum OriginKind { ABSENT, NULL, CONFIGURED, UNTRUSTED, MALFORMED } 281 282 /** 283 * Mutable, non-thread-safe browser-origin policy configuration. 284 * 285 * @since 1.0.0 286 */ 287 @NotThreadSafe 288 @CheckReturnValue 289 public static final class Builder { 290 private @NonNull Set<@NonNull URI> allowedOrigins; 291 private boolean allowInsecureLoopback; 292 private boolean allowMissingMetadata; 293 294 private Builder(@NonNull Set<@NonNull URI> allowedOrigins) { 295 requireNonNull(allowedOrigins); 296 this.allowedOrigins = Set.copyOf(allowedOrigins); 297 } 298 299 /** 300 * Allows canonical plain-HTTP loopback origins for local development. It never allows plain HTTP to a 301 * non-loopback host. {@code null} restores the secure default. 302 * 303 * @param value whether to allow plain-HTTP loopback origins 304 * @return this builder 305 * @since 1.0.0 306 */ 307 public @NonNull Builder allowInsecureLoopback(@Nullable Boolean value) { 308 this.allowInsecureLoopback = Boolean.TRUE.equals(value); 309 return this; 310 } 311 312 /** 313 * Allows an unsafe-method request with neither metadata header. The resulting admission basis remains 314 * observable as {@link BrowserRequestOriginResult.Basis#MISSING_METADATA_COMPATIBILITY}. {@code null} 315 * restores the rejecting default. 316 * 317 * @param value whether to allow missing browser metadata 318 * @return this builder 319 * @since 1.0.0 320 */ 321 public @NonNull Builder allowMissingMetadata(@Nullable Boolean value) { 322 this.allowMissingMetadata = Boolean.TRUE.equals(value); 323 return this; 324 } 325 326 /** 327 * Builds the immutable policy. 328 * 329 * @return configured policy 330 * @since 1.0.0 331 */ 332 public @NonNull BrowserRequestOriginPolicy build() { 333 return new BrowserRequestOriginPolicy(this); 334 } 335 } 336}