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;
020
021import javax.annotation.concurrent.Immutable;
022
023import static java.util.Objects.requireNonNull;
024
025/**
026 * A secret refresh token. The caller retains it when a refresh response has no replacement, and atomically replaces
027 * it when one is returned. The token does not know its original grant scope; callers must request only a subset.
028 *
029 * @author <a href="https://www.revetkn.com">Mark Allen</a>
030 * @since 1.0.0
031 */
032@Immutable
033public final class RefreshToken {
034        private final @NonNull String value;
035
036        private RefreshToken(@NonNull String value) { this.value = value; }
037
038        /**
039         * Wraps a nonempty token value.
040         *
041         * @param value the secret
042         * @return the token
043         * @since 1.0.0
044         */
045        public static @NonNull RefreshToken fromValue(@NonNull String value) {
046                if (requireNonNull(value).isEmpty())
047                        throw new IllegalArgumentException("A refresh token must not be empty.");
048                return new RefreshToken(value);
049        }
050
051        /**
052         * Explicitly releases the secret value to the caller.
053         *
054         * @return the secret
055         * @since 1.0.0
056         */
057        public @NonNull String getValue() { return this.value; }
058
059        /**
060         * Redacts the token.
061         *
062         * @return a redacted description
063         * @since 1.0.0
064         */
065        @Override
066        public @NonNull String toString() { return "RefreshToken{value=<redacted>}"; }
067}