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}