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.RegisteredClaims;
020import com.revetsec.json.JsonObject;
021import com.revetsec.json.JsonValue;
022import org.jspecify.annotations.NonNull;
023
024import javax.annotation.concurrent.Immutable;
025import java.time.Instant;
026import java.util.List;
027import java.util.Optional;
028import java.util.Set;
029
030import static java.util.Objects.requireNonNull;
031
032/**
033 * The claims of a validated JWT (RFC 7519 section 4). Only a validator creates them, after the token's signature
034 * and claims passed.
035 * <p>
036 * The registered claims were checked for their types before this object existed: {@code iss}, {@code sub} and
037 * {@code jti} are strings, {@code aud} is a string or a non-empty array of strings, and {@code exp}, {@code nbf} and
038 * {@code iat} are NumericDates. So every getter is total: it returns the claim or reports it absent, and never
039 * throws. {@link #getClaim(String)} and {@link #toJsonObject()} give every other claim as JSON.
040 * <p>
041 * Claims can carry personal data, so {@link #toString()} shows none of them. Instances compare by reference, never
042 * by content.
043 *
044 * @author <a href="https://www.revetkn.com">Mark Allen</a>
045 * @since 1.0.0
046 */
047@Immutable
048public final class JwtClaims {
049        @NonNull
050        private final RegisteredClaims claims;
051
052        private JwtClaims(@NonNull RegisteredClaims claims) {
053                this.claims = claims;
054        }
055
056        /**
057         * Returns the public view of claims that passed every check. Only the validators call this.
058         *
059         * @param registeredClaims the checked claims
060         * @return the public view
061         */
062        @NonNull
063        static JwtClaims fromRegisteredClaims(@NonNull RegisteredClaims registeredClaims) {
064                return new JwtClaims(requireNonNull(registeredClaims));
065        }
066
067        /**
068         * Returns the issuer ({@code iss}).
069         *
070         * @return the issuer, or empty if absent
071         * @since 1.0.0
072         */
073        @NonNull
074        public Optional<@NonNull String> getIssuer() {
075                return Optional.ofNullable(this.claims.issuer());
076        }
077
078        /**
079         * Returns the subject ({@code sub}).
080         *
081         * @return the subject, or empty if absent
082         * @since 1.0.0
083         */
084        @NonNull
085        public Optional<@NonNull String> getSubject() {
086                return Optional.ofNullable(this.claims.subject());
087        }
088
089        /**
090         * Returns the audiences ({@code aud}).
091         *
092         * @return an unmodifiable list: one element for a string {@code aud}, the array's elements in order, or empty if
093         * absent
094         * @since 1.0.0
095         */
096        @NonNull
097        public List<@NonNull String> getAudiences() {
098                return this.claims.audiences();
099        }
100
101        /**
102         * Returns the expiration time ({@code exp}).
103         *
104         * @return the instant, or empty if absent
105         * @since 1.0.0
106         */
107        @NonNull
108        public Optional<@NonNull Instant> getExpiresAt() {
109                return Optional.ofNullable(this.claims.expiresAt());
110        }
111
112        /**
113         * Returns the issue time ({@code iat}).
114         *
115         * @return the instant, or empty if absent
116         * @since 1.0.0
117         */
118        @NonNull
119        public Optional<@NonNull Instant> getIssuedAt() {
120                return Optional.ofNullable(this.claims.issuedAt());
121        }
122
123        /**
124         * Returns the time before which the token is not valid ({@code nbf}).
125         *
126         * @return the instant, or empty if absent
127         * @since 1.0.0
128         */
129        @NonNull
130        public Optional<@NonNull Instant> getNotBefore() {
131                return Optional.ofNullable(this.claims.notBefore());
132        }
133
134        /**
135         * Returns the JWT ID ({@code jti}).
136         *
137         * @return the JWT ID, or empty if absent
138         * @since 1.0.0
139         */
140        @NonNull
141        public Optional<@NonNull String> getJwtId() {
142                return Optional.ofNullable(this.claims.jwtId());
143        }
144
145        /**
146         * Returns a claim's JSON value, registered or not.
147         *
148         * @param name the claim name, compared exactly
149         * @return the value, which may be JSON {@code null}, or empty if there is no such claim
150         * @throws NullPointerException if {@code name} is {@code null}
151         * @since 1.0.0
152         */
153        @NonNull
154        public Optional<@NonNull JsonValue> getClaim(@NonNull String name) {
155                return this.claims.claims().find(requireNonNull(name));
156        }
157
158        /**
159         * Returns the names of every claim.
160         *
161         * @return an unmodifiable set, in the order the claims appear in the token
162         * @since 1.0.0
163         */
164        @NonNull
165        public Set<@NonNull String> getClaimNames() {
166                return this.claims.claims().getMembers().keySet();
167        }
168
169        /**
170         * Returns every claim as a JSON object: the claims set as received, which can carry personal data.
171         *
172         * @return the claims set
173         * @since 1.0.0
174         */
175        @NonNull
176        public JsonObject toJsonObject() {
177                return this.claims.claims();
178        }
179
180        /**
181         * Describes this object without any claim.
182         *
183         * @return a fully redacted description
184         * @since 1.0.0
185         */
186        @Override
187        @NonNull
188        public String toString() {
189                return getClass().getSimpleName() + "{<redacted>}";
190        }
191}