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 com.google.errorprone.annotations.CheckReturnValue;
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024import java.util.LinkedHashMap;
025import java.util.List;
026import java.util.Map;
027
028import static java.util.Objects.requireNonNull;
029
030/** Coherent active and retained pepper keys for one operation. A key remains available until all
031 * passwords using its ID have been rehashed or reset.
032 * @since 1.0.0 */
033@Immutable
034public final class PasswordPepperSnapshot {
035    private final @NonNull PasswordPepperKey activeKey;
036    private final @NonNull Map<@NonNull String, @NonNull PasswordPepperKey> keys;
037
038    private PasswordPepperSnapshot(@NonNull PasswordPepperKey activeKey,
039            @NonNull Map<@NonNull String, @NonNull PasswordPepperKey> keys) {
040        this.activeKey = activeKey;
041        this.keys = Map.copyOf(keys);
042    }
043
044    /** Starts a snapshot with the key used for new hashes.
045     * @param activeKey active key
046     * @return builder for retained keys
047     * @since 1.0.0 */
048    public static @NonNull Builder withActiveKey(@NonNull PasswordPepperKey activeKey) {
049        return new Builder(requireNonNull(activeKey));
050    }
051
052    /** Returns the key ID used for new hashes.
053     * @return active non-secret key ID
054     * @since 1.0.0 */
055    public @NonNull String getActiveKeyId() { return activeKey.getKeyId(); }
056
057    @NonNull PasswordPepperKey activeKey() { return activeKey; }
058    @Nullable PasswordPepperKey keyForId(@NonNull String keyId) { return keys.get(keyId); }
059
060    /** @return a fixed redacted description
061     * @since 1.0.0 */
062    @Override public @NonNull String toString() { return "PasswordPepperSnapshot{<redacted>}"; }
063
064    /** Snapshot construction; keys are never exposed by iteration.
065     * @since 1.0.0 */
066    @NotThreadSafe
067    @CheckReturnValue
068    public static final class Builder {
069        private final @NonNull PasswordPepperKey activeKey;
070        private final @NonNull Map<@NonNull String, @NonNull PasswordPepperKey> keys = new LinkedHashMap<>();
071
072        private Builder(@NonNull PasswordPepperKey activeKey) {
073            this.activeKey = activeKey;
074            keys.put(activeKey.getKeyId(), activeKey);
075        }
076
077        /** Replaces the complete set of prior verification-only keys. The input is copied before
078         * assignment; invalid lists leave the previous builder state unchanged.
079         * @param retainedKeys at most 15 keys with distinct IDs, or null to retain none
080         * @return this builder
081         * @since 1.0.0 */
082        public @NonNull Builder retainedKeys(@Nullable List<@NonNull PasswordPepperKey> retainedKeys) {
083            Map<String, PasswordPepperKey> next = new LinkedHashMap<>();
084            next.put(activeKey.getKeyId(), activeKey);
085            if (retainedKeys != null) {
086                if (retainedKeys.size() > 15) throw new IllegalArgumentException("Too many retained pepper keys");
087                for (PasswordPepperKey key : retainedKeys) {
088                    requireNonNull(key);
089                    if (next.putIfAbsent(key.getKeyId(), key) != null)
090                        throw new IllegalArgumentException("Duplicate pepper key ID");
091                }
092            }
093            keys.clear();
094            keys.putAll(next);
095            return this;
096        }
097
098        /** Builds a coherent snapshot of the active and retained keys.
099         * @return immutable snapshot
100         * @since 1.0.0 */
101        public @NonNull PasswordPepperSnapshot build() { return new PasswordPepperSnapshot(activeKey, keys); }
102    }
103}