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}