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.jose;
018
019import com.revetsec.internal.jose.VerifiedJwt;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022
023import javax.annotation.concurrent.Immutable;
024import java.util.Optional;
025
026import static java.util.Objects.requireNonNull;
027
028/**
029 * A JWT that {@link JwtValidator#validateResult(String)} accepted: its signature verified with a trusted key, and its type,
030 * issuer, audience, lifetime and required claims passed. Only a validator creates one, so holding a {@code Jwt} means
031 * the token was validated.
032 * <p>
033 * The token is a bearer credential. {@link #toCompactSerialization()} returns it as received, for code that must
034 * forward it; {@link #toString()} shows only the algorithm. Instances compare by reference, never by content.
035 *
036 * @author <a href="https://www.revetkn.com">Mark Allen</a>
037 * @since 1.0.0
038 */
039@Immutable
040public final class Jwt {
041        @NonNull
042        private final JwsAlgorithm algorithm;
043        @Nullable
044        private final String keyId;
045        @Nullable
046        private final String type;
047        @NonNull
048        private final JwtClaims claims;
049        @NonNull
050        private final String compactSerialization;
051
052        private Jwt(@NonNull JwsAlgorithm algorithm,
053                                                        @Nullable String keyId,
054                                                        @Nullable String type,
055                                                        @NonNull JwtClaims claims,
056                                                        @NonNull String compactSerialization) {
057                this.algorithm = algorithm;
058                this.keyId = keyId;
059                this.type = type;
060                this.claims = claims;
061                this.compactSerialization = compactSerialization;
062        }
063
064        /**
065         * Returns the public view of a JWT that passed every check. Only the validators call this.
066         *
067         * @param verifiedJwt the verified JWT
068         * @return the public view
069         */
070        @NonNull
071        static Jwt fromVerifiedJwt(@NonNull VerifiedJwt verifiedJwt) {
072                requireNonNull(verifiedJwt);
073                return new Jwt(verifiedJwt.algorithm(), verifiedJwt.keyId(), verifiedJwt.type(),
074                                JwtClaims.fromRegisteredClaims(verifiedJwt.claims()), verifiedJwt.compactSerialization());
075        }
076
077        /**
078         * Returns the algorithm the token was signed with ({@code alg}).
079         *
080         * @return the algorithm
081         * @since 1.0.0
082         */
083        @NonNull
084        public JwsAlgorithm getAlgorithm() {
085                return this.algorithm;
086        }
087
088        /**
089         * Returns the header's key ID ({@code kid}), which named the key that verified the token.
090         *
091         * @return the key ID, or empty if the header has none
092         * @since 1.0.0
093         */
094        @NonNull
095        public Optional<@NonNull String> getKeyId() {
096                return Optional.ofNullable(this.keyId);
097        }
098
099        /**
100         * Returns the header's type ({@code typ}) exactly as received, before the comparison that folds case and implies
101         * {@code application/}.
102         *
103         * @return the type, or empty if the header has none
104         * @since 1.0.0
105         */
106        @NonNull
107        public Optional<@NonNull String> getType() {
108                return Optional.ofNullable(this.type);
109        }
110
111        /**
112         * Returns the token's claims.
113         *
114         * @return the claims
115         * @since 1.0.0
116         */
117        @NonNull
118        public JwtClaims getClaims() {
119                return this.claims;
120        }
121
122        /**
123         * Returns the token exactly as it was received: a bearer credential, so treat it as a secret.
124         *
125         * @return the compact serialization
126         * @since 1.0.0
127         */
128        @NonNull
129        public String toCompactSerialization() {
130                return this.compactSerialization;
131        }
132
133        /**
134         * Describes the token by its algorithm only.
135         *
136         * @return the description, without the token or its claims
137         * @since 1.0.0
138         */
139        @Override
140        @NonNull
141        public String toString() {
142                return getClass().getSimpleName() + "{algorithm=" + this.algorithm.getWireValue() + "}";
143        }
144}