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.oidc;
018
019import org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022import com.revetsec.oauth.OAuthEndpointError;
023import com.revetsec.oauth.OAuthErrorResponseException;
024import com.revetsec.jose.JoseException;
025import org.jspecify.annotations.Nullable;
026import java.util.Optional;
027
028/**
029 * The result of an OIDC token refresh.
030 * Local validation and non-transient endpoint client errors return fixed rejections. Transport, metadata,
031 * malformed endpoint responses, transient endpoint failures and invalid HMAC configuration remain exceptions.
032 * Applications receive outcomes from the operation and cannot construct them. A later release may add variants;
033 * consuming switches should include a rejecting default branch.
034 * @author <a href="https://www.revetkn.com">Mark Allen</a>
035 * @since 1.0.0
036 */
037@Immutable
038public abstract sealed class OidcRefreshResult permits OidcRefreshResult.Succeeded, OidcRefreshResult.Rejected, OidcRefreshResult.RejectedEndpoint {
039        OidcRefreshResult() { }
040        static @NonNull OidcRefreshResult fromRefresh(@NonNull OidcRefresh value) { return new Succeeded(requireNonNull(value)); }
041        static @NonNull OidcRefreshResult fromRejection(@NonNull OidcValidationException failure) {
042                return new Rejected(failure.getReason(), failure.getJoseReason().orElse(null));
043        }
044        static @NonNull OidcRefreshResult fromEndpoint(@NonNull OAuthErrorResponseException failure) {
045                return new RejectedEndpoint(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus());
046        }
047        /**
048         * Returns the outcome kind with all values redacted.
049         * @return redacted description
050         * @since 1.0.0
051         */
052        @Override
053        public final @NonNull String toString() {
054                return "OidcRefreshResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
055        }
056        /**
057         * The refresh completed and any returned ID token passed continuity checks.
058         * @author <a href="https://www.revetkn.com">Mark Allen</a>
059         * @since 1.0.0
060         */
061        @Immutable
062        public static final class Succeeded extends OidcRefreshResult {
063                private final @NonNull OidcRefresh value;
064                private Succeeded(@NonNull OidcRefresh value) { this.value = requireNonNull(value); }
065                /**
066                 * Returns the value released after all operation checks passed.
067                 * @return checked value
068                 * @since 1.0.0
069                 */
070                public @NonNull OidcRefresh getRefresh() { return this.value; }
071        }
072        /**
073         * A local OIDC check rejected the operation. No identity, claim or token value is released.
074         * @author <a href="https://www.revetkn.com">Mark Allen</a>
075         * @since 1.0.0
076         */
077        @Immutable
078        public static final class Rejected extends OidcRefreshResult {
079                private final OidcValidationException.@NonNull Reason reason;
080                private final JoseException.@Nullable Reason joseReason;
081                private Rejected(OidcValidationException.@NonNull Reason reason, JoseException.@Nullable Reason joseReason) {
082                        this.reason = requireNonNull(reason); this.joseReason = joseReason;
083                }
084                /**
085                 * Returns the fixed OIDC rejection reason.
086                 * @return rejection reason
087                 * @since 1.0.0
088                 */
089                public OidcValidationException.@NonNull Reason getReason() { return this.reason; }
090                /**
091                 * Returns the fixed lower-layer reason when JOSE rejected the input.
092                 * @return optional JOSE reason
093                 * @since 1.0.0
094                 */
095                public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() {
096                        return Optional.ofNullable(this.joseReason);
097                }
098        }
099        /**
100         * The endpoint returned a non-transient client error. No response body or credential is retained.
101         * @author <a href="https://www.revetkn.com">Mark Allen</a>
102         * @since 1.0.0
103         */
104        @Immutable
105        public static final class RejectedEndpoint extends OidcRefreshResult {
106                private final @NonNull OAuthEndpointError error;
107                private final int status;
108                private RejectedEndpoint(@NonNull OAuthEndpointError error, int status) {
109                        this.error = requireNonNull(error); this.status = status;
110                }
111                /**
112                 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback.
113                 * @return fixed endpoint error
114                 * @since 1.0.0
115                 */
116                public @NonNull OAuthEndpointError getError() { return this.error; }
117                /**
118                 * Returns the endpoint's HTTP status.
119                 * @return endpoint status
120                 * @since 1.0.0
121                 */
122                public @NonNull Integer getStatus() { return this.status; }
123        }
124}