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}