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 */
016package com.revetsec.password;
017
018import org.jspecify.annotations.NonNull;
019
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022
023/** An application-owned, 32-byte Argon2id secret-input key identified by a non-secret ID. Keep the
024 * key outside the password-hash database. The supplied array is copied and remains caller-owned.
025 * @since 1.0.0 */
026@Immutable
027public final class PasswordPepperKey {
028    private final @NonNull String keyId;
029    private final byte @NonNull [] key;
030
031    private PasswordPepperKey(@NonNull String keyId, byte @NonNull [] key) {
032        this.keyId = keyId;
033        this.key = key;
034    }
035
036    /** Constructs a pepper key from 32 cryptographically random bytes.
037     * @param keyId stable 1–64 character ASCII key ID
038     * @param keyBytes 32 secret bytes; borrowed only for this call and not modified
039     * @return a retained defensive copy
040     * @since 1.0.0 */
041    public static @NonNull PasswordPepperKey fromBytes(@NonNull String keyId, byte @NonNull [] keyBytes) {
042        requireNonNull(keyId); requireNonNull(keyBytes);
043        if (keyId.length() < 1 || keyId.length() > 64 || !keyId.chars().allMatch(ch ->
044                (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z')
045                        || (ch >= '0' && ch <= '9') || ch == '.' || ch == '_' || ch == '~' || ch == '-')) {
046            throw new IllegalArgumentException("Invalid pepper key ID");
047        }
048        if (keyBytes.length != 32) throw new IllegalArgumentException("Pepper key must be 32 bytes");
049        int difference = 0;
050        for (int i = 1; i < keyBytes.length; i++) difference |= keyBytes[0] ^ keyBytes[i];
051        if (difference == 0) throw new IllegalArgumentException("Uniform pepper key is not allowed");
052        return new PasswordPepperKey(keyId, keyBytes.clone());
053    }
054
055    /** Returns the identifier used to select this pepper key.
056     * @return non-secret key ID
057     * @since 1.0.0 */
058    public @NonNull String getKeyId() { return keyId; }
059
060    byte @NonNull [] copyKeyBytes() { return key.clone(); }
061
062    /** @return a fixed redacted description
063     * @since 1.0.0 */
064    @Override public @NonNull String toString() { return "PasswordPepperKey{<redacted>}"; }
065
066    // Intentionally identity-based: comparing key bytes is not a supported operation.
067}