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.servlet.jakarta; 018 019import com.revetsec.oauth.AuthorizationResponse; 020import com.revetsec.oauth.AuthorizationResponseParseResult; 021import com.revetsec.oauth.OAuthException; 022 023import org.jspecify.annotations.NonNull; 024 025import javax.annotation.concurrent.Immutable; 026 027import static java.util.Objects.requireNonNull; 028 029/** 030 * The outcome of materializing and parsing a raw, unverified OAuth browser callback. A successful parse grants no identity; 031 * the configured OAuth or OpenID Connect client must complete the browser-bound transaction. 032 * <p> 033 * Only the producing operation constructs these outcomes. Value accessors exist only on the variant that 034 * owns a value, and diagnostic text contains no callback data. Later releases may add variants; 035 * consuming switches should include a rejecting default branch. 036 * 037 * @author <a href="https://www.revetkn.com">Mark Allen</a> 038 * @since 1.0.0 039 */ 040@Immutable 041public abstract sealed class ServletOAuthCallbackResult 042 permits ServletOAuthCallbackResult.Succeeded, ServletOAuthCallbackResult.Rejected, ServletOAuthCallbackResult.TooLarge { 043 ServletOAuthCallbackResult() { } 044 045 static @NonNull ServletOAuthCallbackResult fromResponse(@NonNull AuthorizationResponse response) { 046 return new Succeeded(requireNonNull(response)); 047 } 048 049 static @NonNull ServletOAuthCallbackResult fromRejected() { 050 return new Rejected(); 051 } 052 053 static @NonNull ServletOAuthCallbackResult fromTooLarge() { 054 return new TooLarge(); 055 } 056 057 static @NonNull ServletOAuthCallbackResult fromParseResult(@NonNull AuthorizationResponseParseResult result) { 058 if (requireNonNull(result) instanceof AuthorizationResponseParseResult.Succeeded success) 059 return fromResponse(success.getResponse()); 060 return fromRejected(); 061 } 062 063 /** 064 * Returns the outcome kind without callback data. 065 * @return redacted description 066 * @since 1.0.0 067 */ 068 @Override 069 public final @NonNull String toString() { 070 return "ServletOAuthCallbackResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; 071 } 072 073 /** 074 * A syntactically parsed callback that remains unverified until transaction completion. 075 * @author <a href="https://www.revetkn.com">Mark Allen</a> 076 * @since 1.0.0 077 */ 078 @Immutable 079 public static final class Succeeded extends ServletOAuthCallbackResult { 080 private final @NonNull AuthorizationResponse response; 081 private Succeeded(@NonNull AuthorizationResponse response) { this.response = response; } 082 083 /** 084 * Returns the raw, unverified callback. It grants no identity or permission. 085 * @return the parsed callback 086 * @since 1.0.0 087 */ 088 public @NonNull AuthorizationResponse getResponse() { return this.response; } 089 } 090 091 /** 092 * A callback rejected for an unsupported method or malformed, duplicate, oversized or split-channel input. 093 * @author <a href="https://www.revetkn.com">Mark Allen</a> 094 * @since 1.0.0 095 */ 096 @Immutable 097 public static final class Rejected extends ServletOAuthCallbackResult { 098 private Rejected() { } 099 100 /** 101 * Returns a fixed reason without attacker-controlled callback data. 102 * @return malformed callback reason 103 * @since 1.0.0 104 */ 105 public OAuthException.@NonNull Reason getReason() { return OAuthException.Reason.CALLBACK_MALFORMED; } 106 } 107 /** 108 * The transport discarded an oversized request body or its bounded read observed overflow. 109 * No callback is available and no pending authorization state may be consumed. 110 * @author <a href="https://www.revetkn.com">Mark Allen</a> 111 * @since 1.0.0 112 */ 113 @Immutable 114 public static final class TooLarge extends ServletOAuthCallbackResult { 115 private TooLarge() { } 116 } 117 118}