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 org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.Immutable;
023import java.time.Instant;
024import java.util.Optional;
025
026import static java.util.Objects.requireNonNull;
027
028/**
029 * A raw access token returned by an AS. It is not a verified identity or a validated resource-server token. The
030 * value is secret and appears only through explicit accessors.
031 *
032 * @author <a href="https://www.revetkn.com">Mark Allen</a>
033 * @since 1.0.0
034 */
035@Immutable
036public final class AccessToken {
037        private final @NonNull String value;
038        private final @NonNull String tokenType;
039        private final @Nullable Instant expiresAt;
040
041        AccessToken(@NonNull String value, @NonNull String tokenType, @Nullable Instant expiresAt) {
042                if (requireNonNull(value).isEmpty() || requireNonNull(tokenType).isEmpty())
043                        throw new IllegalArgumentException("An access token and type must not be empty.");
044                this.value = value;
045                this.tokenType = tokenType;
046                this.expiresAt = expiresAt;
047        }
048
049        /**
050         * Explicitly releases the secret token value.
051         *
052         * @return the token value
053         * @since 1.0.0
054         */
055        public @NonNull String getValue() { return this.value; }
056
057        /**
058         * Returns the AS's token type, with its original case.
059         *
060         * @return token type
061         * @since 1.0.0
062         */
063        public @NonNull String getTokenType() { return this.tokenType; }
064
065        /**
066         * Reports whether the authorization server named the Bearer token type, ignoring ASCII case.
067         * This does not mean the token value is safe to place in a header.
068         *
069         * @return whether the token type is Bearer
070         * @since 1.0.0
071         */
072        public @NonNull Boolean isBearer() { return this.tokenType.equalsIgnoreCase("Bearer"); }
073
074        /**
075         * Returns the request-start-anchored expiry when the AS supplied one.
076         *
077         * @return expiry
078         * @since 1.0.0
079         */
080        public @NonNull Optional<@NonNull Instant> getExpiresAt() { return Optional.ofNullable(this.expiresAt); }
081
082        /**
083         * Returns a Bearer Authorization header. Non-Bearer types and values outside RFC 6750's b64token grammar are
084         * refused, including whitespace and line breaks.
085         *
086         * @return the header value
087         * @since 1.0.0
088         */
089        public @NonNull String getAuthorizationHeaderValue() {
090                if (!isBearer() || !isSafeBearerToken(this.value))
091                        throw new IllegalStateException("This token cannot be sent as a Bearer Authorization header.");
092                return "Bearer " + this.value;
093        }
094
095        private static boolean isSafeBearerToken(@NonNull String value) {
096                int index = 0;
097                while (index < value.length()) {
098                        char c = value.charAt(index);
099                        if ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')
100                                        || c == '-' || c == '.' || c == '_' || c == '~' || c == '+' || c == '/')
101                                index++;
102                        else
103                                break;
104                }
105                if (index == 0) return false;
106                while (index < value.length() && value.charAt(index) == '=') index++;
107                return index == value.length();
108        }
109
110        /**
111         * Redacts the token.
112         *
113         * @return a redacted description
114         * @since 1.0.0
115         */
116        @Override
117        public @NonNull String toString() { return "AccessToken{value=<redacted>}"; }
118}