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}