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}