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 org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.Immutable;
023
024import static java.util.Objects.requireNonNull;
025
026/**
027 * Closed outcome of a browser request-origin check.
028 * <p>
029 * An allowed result says which input admitted the request. A rejected result carries only a fixed reason; it never
030 * exposes a submitted origin. This policy result is one layer of request admission, not a complete CSRF defense.
031 *
032 * @since 1.0.0
033 */
034@Immutable
035@CheckReturnValue
036public abstract sealed class BrowserRequestOriginResult permits BrowserRequestOriginResult.Allowed,
037        BrowserRequestOriginResult.Rejected {
038    BrowserRequestOriginResult() { }
039
040    static @NonNull BrowserRequestOriginResult allowed(@NonNull Basis basis) {
041        return new Allowed(basis);
042    }
043
044    static @NonNull BrowserRequestOriginResult rejected(@NonNull Reason reason) {
045        return new Rejected(reason);
046    }
047
048    /**
049     * Redacts all request metadata.
050     *
051     * @return a fixed description
052     * @since 1.0.0
053     */
054    @Override
055    public final @NonNull String toString() {
056        return "BrowserRequestOriginResult{<redacted>}";
057    }
058
059    /**
060     * The input that admitted a request.
061     *
062     * @since 1.0.0
063     */
064    @Immutable
065    public enum Basis {
066        /** A safe HTTP method. */
067        SAFE_METHOD,
068        /** {@code Sec-Fetch-Site: same-origin}. */
069        SAME_ORIGIN,
070        /** {@code Sec-Fetch-Site: none}, normally a user-initiated navigation. */
071        USER_INITIATED,
072        /** An exact configured {@code Origin}. */
073        CONFIGURED_ORIGIN,
074        /** The explicit compatibility option for a request with neither metadata header. */
075        MISSING_METADATA_COMPATIBILITY
076    }
077
078    /**
079     * A fixed rejection reason.
080     *
081     * @since 1.0.0
082     */
083    @Immutable
084    public enum Reason {
085        /** Cross-site metadata had no exact configured origin. */
086        CROSS_SITE,
087        /** Same-site metadata had no exact configured origin. */
088        SAME_SITE,
089        /** An unrecognized {@code Sec-Fetch-Site} value had no exact configured origin. */
090        UNRECOGNIZED_FETCH_SITE,
091        /** A syntactically valid origin was not configured. */
092        UNTRUSTED_ORIGIN,
093        /** An opaque {@code Origin: null} could not be admitted. */
094        NULL_ORIGIN,
095        /** Neither request metadata header was present. */
096        MISSING_METADATA,
097        /** A header was duplicated or malformed. */
098        MALFORMED
099    }
100
101    /**
102     * An admitted request.
103     *
104     * @since 1.0.0
105     */
106    @Immutable
107    public static final class Allowed extends BrowserRequestOriginResult {
108        private final @NonNull Basis basis;
109
110        private Allowed(@NonNull Basis basis) {
111            this.basis = requireNonNull(basis);
112        }
113
114        /**
115         * Returns the input that admitted the request. This makes use of the missing-metadata compatibility option
116         * observable without logging submitted headers.
117         *
118         * @return admission basis
119         * @since 1.0.0
120         */
121        public @NonNull Basis getBasis() {
122            return this.basis;
123        }
124    }
125
126    /**
127     * A request rejected before application state changes.
128     *
129     * @since 1.0.0
130     */
131    @Immutable
132    public static final class Rejected extends BrowserRequestOriginResult {
133        private final @NonNull Reason reason;
134
135        private Rejected(@NonNull Reason reason) {
136            this.reason = requireNonNull(reason);
137        }
138
139        /**
140         * Returns the fixed rejection reason.
141         *
142         * @return rejection reason
143         * @since 1.0.0
144         */
145        public @NonNull Reason getReason() {
146            return this.reason;
147        }
148    }
149}