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.oauth;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.encoding.EncodingException;
021import com.revetsec.internal.encoding.StrictUtf8;
022import com.revetsec.jose.JwsSigner;
023import java.util.Arrays;
024import java.util.Optional;
025import javax.annotation.concurrent.ThreadSafe;
026import javax.annotation.concurrent.NotThreadSafe;
027import org.jspecify.annotations.NonNull;
028import org.jspecify.annotations.Nullable;
029import static java.util.Objects.requireNonNull;
030
031/**
032 * Immutable signer and protected-header identifiers selected together for one assertion. At least one identifier
033 * is required. The private key and identifiers never appear in string rendering; arrays are defensively copied.
034 * @author <a href="https://www.revetkn.com">Mark Allen</a>
035 * @since 1.0.0
036 */
037@ThreadSafe
038public final class ClientAssertionSigningKey {
039        private final @NonNull JwsSigner signer;
040        private final @Nullable String keyId;
041        private final byte @Nullable [] thumbprint;
042
043        private ClientAssertionSigningKey(@NonNull Builder builder) {
044                this.signer = builder.signer;
045                this.keyId = builder.keyId;
046                this.thumbprint = builder.thumbprint == null ? null : builder.thumbprint.clone();
047        }
048        /**
049         * Starts a snapshot builder. A key ID or certificate digest must also be supplied.
050         * @param signer the required signer
051         * @return the builder
052         * @since 1.0.0
053         */
054        @CheckReturnValue
055        public static @NonNull Builder withSigner(@NonNull JwsSigner signer) { return new Builder(signer); }
056        /**
057         * Returns the optional key identifier.
058         * @return identifier when configured
059         * @since 1.0.0
060         */
061        public @NonNull Optional<@NonNull String> getKeyId() { return Optional.ofNullable(this.keyId); }
062        /**
063         * Returns a copy of the optional SHA-256 certificate digest.
064         * @return digest when configured
065         * @since 1.0.0
066         */
067        public @NonNull Optional<byte @NonNull []> getCertificateSha256Thumbprint() {
068                return this.thumbprint == null ? Optional.empty() : Optional.of(this.thumbprint.clone());
069        }
070        @NonNull JwsSigner signer() { return this.signer; }
071        /**
072         * Redacts the key and identifiers.
073         * @return redacted description
074         * @since 1.0.0
075         */
076        @Override public @NonNull String toString() { return "ClientAssertionSigningKey{key=<redacted>}"; }
077
078        /**
079         * Configures one immutable signing snapshot without provider or signing calls.
080         * @author <a href="https://www.revetkn.com">Mark Allen</a>
081         * @since 1.0.0
082         */
083        @NotThreadSafe @CheckReturnValue
084        public static final class Builder {
085                private final @NonNull JwsSigner signer;
086                private @Nullable String keyId;
087                private byte @Nullable [] thumbprint;
088                private Builder(@NonNull JwsSigner signer) { this.signer = requireNonNull(signer); }
089                /**
090                 * Replaces the optional key identifier. Text must contain 1–256 UTF-16 code units and valid Unicode.
091                 * @param value identifier, or null to clear
092                 * @return this builder
093                 * @since 1.0.0
094                 */
095                public @NonNull Builder keyId(@Nullable String value) {
096                        if (value != null) {
097                                if (value.isEmpty() || value.length() > 256) throw new IllegalArgumentException("The assertion key identifier is invalid.");
098                                try { Arrays.fill(StrictUtf8.encode(value), (byte) 0); }
099                                catch (EncodingException invalid) { throw new IllegalArgumentException("The assertion key identifier is invalid."); }
100                        }
101                        this.keyId = value; return this;
102                }
103                /**
104                 * Replaces the optional SHA-256 certificate digest with a defensive copy.
105                 * @param value exactly 32 bytes, or null to clear
106                 * @return this builder
107                 * @since 1.0.0
108                 */
109                public @NonNull Builder certificateSha256Thumbprint(byte @Nullable [] value) {
110                        if (value != null && value.length != 32) throw new IllegalArgumentException("The assertion certificate digest must contain 32 bytes.");
111                        this.thumbprint = value == null ? null : value.clone(); return this;
112                }
113                /**
114                 * Builds an immutable snapshot without signing or I/O.
115                 * @return the snapshot
116                 * @since 1.0.0
117                 */
118                public @NonNull ClientAssertionSigningKey build() {
119                        if (this.keyId == null && this.thumbprint == null) throw new IllegalStateException("An assertion key identifier or certificate digest is required.");
120                        return new ClientAssertionSigningKey(this);
121                }
122                /**
123                 * Redacts configured keys and identifiers.
124                 * @return redacted description
125                 * @since 1.0.0
126                 */
127                @Override public @NonNull String toString() { return "ClientAssertionSigningKey.Builder{key=<redacted>}"; }
128        }
129}