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.totp;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.StoreTimeObservation;
021import java.util.Map;
022import java.util.Objects;
023import java.util.Set;
024import org.jspecify.annotations.NonNull;
025
026/**
027 * Complete immutable authoritative observations within exactly one namespace and recovery epoch.
028 * @since 1.0.0
029 */
030@javax.annotation.concurrent.Immutable
031@CheckReturnValue
032public final class TotpStoreSnapshot {
033 private final @NonNull Map<@NonNull TotpStoreKey, @NonNull TotpStoreEntry> entries;
034 private final @NonNull StoreTimeObservation timeObservation;
035 private TotpStoreSnapshot(@NonNull Map<@NonNull TotpStoreKey, @NonNull TotpStoreEntry> entries,
036   @NonNull StoreTimeObservation timeObservation) {
037  this.entries = Map.copyOf(entries);
038  this.timeObservation = Objects.requireNonNull(timeObservation);
039 }
040 /**
041  * Constructs a complete, bounded snapshot with one explicit observation per requested address.
042  * @param requestedKeys the exact nonempty set of at most 16 keys in one scope
043  * @param entries the matching present or absent observations
044  * @param timeObservation the admitted time or time-only unavailability coherent with these entries
045  * @return the immutable snapshot
046  * @since 1.0.0
047  */
048 public static @NonNull TotpStoreSnapshot fromEntries(@NonNull Set<@NonNull TotpStoreKey> requestedKeys,
049   @NonNull Map<@NonNull TotpStoreKey, @NonNull TotpStoreEntry> entries,
050   @NonNull StoreTimeObservation timeObservation) {
051  Objects.requireNonNull(requestedKeys); Objects.requireNonNull(entries); Objects.requireNonNull(timeObservation);
052  if (requestedKeys.isEmpty() || requestedKeys.size() > 16 || !entries.keySet().equals(requestedKeys))
053   throw new IllegalArgumentException("Incomplete TOTP store snapshot");
054  TotpStoreKey first = Objects.requireNonNull(requestedKeys.iterator().next());
055  for (TotpStoreKey key : requestedKeys) {
056   Objects.requireNonNull(key);
057   if (!key.getCredentialNamespace().equals(first.getCredentialNamespace())
058     || !key.getRecoveryEpoch().equals(first.getRecoveryEpoch()))
059    throw new IllegalArgumentException("Mixed TOTP snapshot scope");
060   TotpStoreEntry entry = Objects.requireNonNull(entries.get(key));
061   if (entry instanceof TotpStoreEntry.Present present && !present.getRecord().getKey().equals(key))
062    throw new IllegalArgumentException("Mismatched TOTP record address");
063  }
064  return new TotpStoreSnapshot(entries, timeObservation);
065 }
066 /**
067  * Returns all immutable requested observations.
068  * @return the exact read set
069  * @since 1.0.0
070  */
071 public @NonNull Map<@NonNull TotpStoreKey, @NonNull TotpStoreEntry> getEntries() { return this.entries; }
072 /**
073  * Returns an observation; an unrequested address is invalid.
074  * @param key a requested address
075  * @return its explicit observation
076  * @since 1.0.0
077  */
078 public @NonNull TotpStoreEntry getEntry(@NonNull TotpStoreKey key) {
079  TotpStoreEntry entry = this.entries.get(Objects.requireNonNull(key));
080  if (entry == null) throw new IllegalArgumentException("Key not in TOTP snapshot");
081  return entry;
082 }
083 /**
084  * Returns the admitted time metadata from the same atomic snapshot as every entry.
085  * @return the coherent time observation
086  * @since 1.0.0
087  */
088 public @NonNull StoreTimeObservation getTimeObservation() { return this.timeObservation; }
089 /**
090  * Redacts all observations.
091  * @since 1.0.0
092  */
093 @Override public @NonNull String toString() { return "TotpStoreSnapshot{entries=<redacted>}"; }
094}