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}