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.VerificationKey;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022
023import javax.annotation.concurrent.Immutable;
024import java.util.Locale;
025import java.util.Objects;
026import java.util.Optional;
027
028import static java.util.Objects.requireNonNull;
029
030/**
031 * One usable public key from a {@link Jwks}: an RSA, EC (P-256, P-384 or P-521) or Ed25519 key that passed
032 * every rule for verifying JWS signatures (see {@link JwkSkipReason}).
033 * <p>
034 * Instances exist only for such keys, so there is no public factory: they come from
035 * {@link Jwks#getKeys()}. This class describes the key; it holds no private key material and exposes no
036 * JCA key.
037 * <p>
038 * <strong>Equality</strong> is by value: the RFC 7638 thumbprint, which identifies the key material, and the
039 * {@code kid}, {@code alg} and {@code use} members, and also the key's JWK {@code issuer} member, which this class does
040 * not expose but which decides the tokens the key may verify. {@link #toString()} shows the key ID with its control
041 * characters escaped, the key type, curve and algorithm, and the thumbprint.
042 *
043 * @author <a href="https://www.revetkn.com">Mark Allen</a>
044 * @since 1.0.0
045 */
046@Immutable
047public final class Jwk {
048        @NonNull
049        private final VerificationKey verificationKey;
050
051        private Jwk(@NonNull VerificationKey verificationKey) {
052                this.verificationKey = verificationKey;
053        }
054
055        /**
056         * Returns the public view of a key that {@code internal.jose} has parsed and checked.
057         *
058         * @param verificationKey the parsed key
059         * @return the public view
060         */
061        @NonNull
062        static Jwk fromVerificationKey(@NonNull VerificationKey verificationKey) {
063                return new Jwk(requireNonNull(verificationKey));
064        }
065
066        /**
067         * The parsed key behind this view.
068         */
069        @NonNull
070        VerificationKey verificationKey() {
071                return this.verificationKey;
072        }
073
074        /**
075         * Returns the key ID ({@code kid}, RFC 7517 section 4.5).
076         *
077         * @return the key ID, 1 to 256 characters, or empty if the key has none
078         * @since 1.0.0
079         */
080        @NonNull
081        public Optional<@NonNull String> getKeyId() {
082                return Optional.ofNullable(this.verificationKey.keyId());
083        }
084
085        /**
086         * Returns the key type ({@code kty}, RFC 7517 section 4.1).
087         *
088         * @return {@code RSA}, {@code EC} or {@code OKP}
089         * @since 1.0.0
090         */
091        @NonNull
092        public String getKeyType() {
093                return this.verificationKey.keyType();
094        }
095
096        /**
097         * Returns the curve ({@code crv}; RFC 7518 section 6.2.1.1, RFC 8037 section 2).
098         *
099         * @return {@code P-256}, {@code P-384}, {@code P-521} or {@code Ed25519}, or empty for an RSA key
100         * @since 1.0.0
101         */
102        @NonNull
103        public Optional<@NonNull String> getCurve() {
104                return Optional.ofNullable(this.verificationKey.curve());
105        }
106
107        /**
108         * Returns the algorithm the key is restricted to ({@code alg}, RFC 7517 section 4.4). A key with an algorithm
109         * verifies only that algorithm, except that {@link JwsAlgorithm#EDDSA} and {@link JwsAlgorithm#ED25519} verify
110         * each other; an RSA key without one verifies only while exactly one RSA algorithm is allowed.
111         *
112         * @return the algorithm, or empty if the key has none
113         * @since 1.0.0
114         */
115        @NonNull
116        public Optional<@NonNull JwsAlgorithm> getAlgorithm() {
117                return Optional.ofNullable(this.verificationKey.algorithm());
118        }
119
120        /**
121         * Returns the key's intended use ({@code use}, RFC 7517 section 4.2).
122         *
123         * @return {@code sig}, or empty if the key has no {@code use} member
124         * @since 1.0.0
125         */
126        @NonNull
127        public Optional<@NonNull String> getUse() {
128                return Optional.ofNullable(this.verificationKey.use());
129        }
130
131        /**
132         * Returns the key's RFC 7638 JWK thumbprint with SHA-256, which identifies the key material whatever its other
133         * members say.
134         *
135         * @return the thumbprint, in unpadded base64url (43 characters)
136         * @since 1.0.0
137         */
138        @NonNull
139        public String getThumbprintSha256() {
140                return this.verificationKey.thumbprintSha256();
141        }
142
143        /**
144         * Compares by value: the thumbprint, key ID, algorithm, use and the JWK {@code issuer} member.
145         *
146         * @param object the other object
147         * @return whether {@code object} is an equal key
148         * @since 1.0.0
149         */
150        @Override
151        public boolean equals(@Nullable Object object) {
152                if (this == object)
153                        return true;
154                if (!(object instanceof Jwk other))
155                        return false;
156
157                VerificationKey mine = this.verificationKey;
158                VerificationKey theirs = other.verificationKey;
159                return mine.thumbprintSha256().equals(theirs.thumbprintSha256()) && Objects.equals(mine.keyId(), theirs.keyId())
160                                && mine.algorithm() == theirs.algorithm() && Objects.equals(mine.use(), theirs.use())
161                                && Objects.equals(mine.issuer(), theirs.issuer());
162        }
163
164        /**
165         * Returns a hash of the thumbprint.
166         *
167         * @return the hash code
168         * @since 1.0.0
169         */
170        @Override
171        public int hashCode() {
172                return this.verificationKey.thumbprintSha256().hashCode();
173        }
174
175        /**
176         * Describes the key by its public facts. The key ID comes from the key set's author, so its control characters,
177         * quotation marks, backslashes and bidirectional formatting characters are escaped.
178         *
179         * @return the description
180         * @since 1.0.0
181         */
182        @Override
183        @NonNull
184        public String toString() {
185                VerificationKey key = this.verificationKey;
186                String keyId = key.keyId();
187                String curve = key.curve();
188                JwsAlgorithm algorithm = key.algorithm();
189
190                return getClass().getSimpleName() + "{" + (keyId == null ? "" : "kid=\"" + escape(keyId) + "\", ") + "kty="
191                                + key.keyType() + (curve == null ? "" : ", crv=" + curve)
192                                + (algorithm == null ? "" : ", alg=" + algorithm.getWireValue()) + ", thumbprint="
193                                + key.thumbprintSha256() + "}";
194        }
195
196        /**
197         * Escapes the characters that could forge or hide text in a log line as {@code \}{@code uXXXX}: C0 and C1
198         * controls, DEL, {@code "}, {@code \}, the line and paragraph separators, the bidirectional formatting characters
199         * and unpaired surrogates.
200         */
201        @NonNull
202        static String escape(@NonNull String value) {
203                StringBuilder escaped = new StringBuilder(value.length());
204
205                for (int index = 0; index < value.length(); ++index) {
206                        char character = value.charAt(index);
207                        boolean unpaired = (Character.isHighSurrogate(character) && (index + 1 >= value.length()
208                                        || !Character.isLowSurrogate(value.charAt(index + 1))))
209                                        || (Character.isLowSurrogate(character) && (index == 0
210                                        || !Character.isHighSurrogate(value.charAt(index - 1))));
211
212                        if (character < 0x20 || (character >= 0x7F && character <= 0x9F) || character == '"' || character == '\\'
213                                        || character == 0x2028 || character == 0x2029 || (character >= 0x202A && character <= 0x202E)
214                                        || (character >= 0x2066 && character <= 0x2069) || character == 0x200E || character == 0x200F
215                                        || character == 0x061C || unpaired)
216                                escaped.append(String.format(Locale.ROOT, "\\u%04X", (int) character));
217                        else
218                                escaped.append(character);
219                }
220
221                return escaped.toString();
222        }
223}