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}