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.oauth;
018
019import org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022
023/**
024 * The outcome of parsing materialized Authorization headers. A present token is unverified and grants no permission.
025 * <p>
026 * Applications receive these outcomes from the corresponding operation; they cannot construct them.
027 * Value accessors exist only on the variant that owns a value. Diagnostic text contains no input or result data.
028 * A later release may add variants; consuming switches should include a rejecting default branch.
029 *
030 * @author <a href="https://www.revetkn.com">Mark Allen</a>
031 * @since 1.0.0
032 */
033@Immutable
034public abstract sealed class BearerTokenResult permits BearerTokenResult.Absent, BearerTokenResult.Present, BearerTokenResult.Malformed {
035        BearerTokenResult() { }
036
037        static @NonNull BearerTokenResult fromAbsent() {
038                return new Absent();
039        }
040
041        static @NonNull BearerTokenResult fromToken(@NonNull BearerToken token) {
042                return new Present(requireNonNull(token));
043        }
044
045        static @NonNull BearerTokenResult fromMalformed() {
046                return new Malformed();
047        }
048
049        /**
050         * Returns the outcome kind with all values redacted.
051         * @return redacted description
052         * @since 1.0.0
053         */
054        @Override
055        public final @NonNull String toString() {
056                return "BearerTokenResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
057        }
058
059        /**
060         * No Authorization header was supplied.
061         * @author <a href="https://www.revetkn.com">Mark Allen</a>
062         * @since 1.0.0
063         */
064        @Immutable
065        public static final class Absent extends BearerTokenResult {
066                private Absent() {  }
067        }
068
069        /**
070         * Exactly one header supplied a syntactically valid, unverified bearer credential.
071         * @author <a href="https://www.revetkn.com">Mark Allen</a>
072         * @since 1.0.0
073         */
074        @Immutable
075        public static final class Present extends BearerTokenResult {
076                private final @NonNull BearerToken token;
077                private Present(@NonNull BearerToken token) { this.token = token; }
078
079                /**
080                 * Returns the unverified credential; parsing establishes no identity.
081                 * @return token
082                 * @since 1.0.0
083                 */
084                public @NonNull BearerToken getToken() { return this.token; }
085        }
086
087        /**
088         * The supplied header values are malformed, duplicated or oversized.
089         * @author <a href="https://www.revetkn.com">Mark Allen</a>
090         * @since 1.0.0
091         */
092        @Immutable
093        public static final class Malformed extends BearerTokenResult {
094                private Malformed() {  }
095        }
096}