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.webauthn; 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/** Complete immutable authoritative read set, including explicit absences. 027 * @since 1.0.0 */ 028@javax.annotation.concurrent.Immutable 029@CheckReturnValue 030public final class WebAuthnStoreSnapshot { 031 private final @NonNull Map<@NonNull WebAuthnStoreKey, @NonNull WebAuthnStoreEntry> entries; 032 private final @NonNull StoreTimeObservation timeObservation; 033 034 private WebAuthnStoreSnapshot(@NonNull Map<@NonNull WebAuthnStoreKey, @NonNull WebAuthnStoreEntry> entries, 035 @NonNull StoreTimeObservation timeObservation) { 036 this.entries = Map.copyOf(entries); 037 this.timeObservation = timeObservation; 038 } 039 040 /** 041 * Constructs a complete snapshot. The engine also compares its requested keys with the returned 042 * snapshot keys, so a provider cannot represent a missing read as absence by omission. 043 * @param requestedKeys the exact requested set 044 * @param entries one explicit observation per requested key 045 * @param timeObservation the same coherent admission/time observation as the data 046 * @return a complete immutable snapshot 047 * @since 1.0.0 048 */ 049 public static @NonNull WebAuthnStoreSnapshot fromEntries( 050 @NonNull Set<@NonNull WebAuthnStoreKey> requestedKeys, 051 @NonNull Map<@NonNull WebAuthnStoreKey, @NonNull WebAuthnStoreEntry> entries, 052 @NonNull StoreTimeObservation timeObservation) { 053 Objects.requireNonNull(entries); Objects.requireNonNull(timeObservation); 054 validateRequestedKeys(requestedKeys); 055 if (!entries.keySet().equals(requestedKeys)) 056 throw new IllegalArgumentException("Incomplete store snapshot"); 057 return new WebAuthnStoreSnapshot(entries, timeObservation); 058 } 059 060 /** Returns the exact immutable key-to-observation map. 061 * @return every requested key and its observation 062 * @since 1.0.0 */ 063 public @NonNull Map<@NonNull WebAuthnStoreKey, @NonNull WebAuthnStoreEntry> getEntries() { 064 return this.entries; 065 } 066 067 /** Returns the explicit observation for a requested key; an unrequested key is invalid. 068 * @param key the requested key 069 * @return the authoritative observation 070 * @since 1.0.0 */ 071 public @NonNull WebAuthnStoreEntry getEntry(@NonNull WebAuthnStoreKey key) { 072 WebAuthnStoreEntry entry = this.entries.get(Objects.requireNonNull(key)); 073 if (entry == null) throw new IllegalArgumentException("Key not in snapshot"); 074 return entry; 075 } 076 077 /** Returns the admission/time envelope observed coherently with every entry. 078 * @return the authoritative time status 079 * @since 1.0.0 */ 080 public @NonNull StoreTimeObservation getTimeObservation() { return this.timeObservation; } 081 082 static void validateRequestedKeys(@NonNull Set<@NonNull WebAuthnStoreKey> keys) { 083 Objects.requireNonNull(keys); 084 if (keys.isEmpty() || keys.size() > 16) throw new IllegalArgumentException("Invalid WebAuthn read set"); 085 String scope = scopeOf(Objects.requireNonNull(keys.iterator().next())); 086 for (WebAuthnStoreKey key : keys) 087 if (!scope.equals(scopeOf(Objects.requireNonNull(key)))) throw new IllegalArgumentException("Mixed WebAuthn read scope"); 088 } 089 090 // Final key factories establish canonical storage grammar; scope comparison never decrypts a record. 091 static @NonNull String scopeOf(@NonNull WebAuthnStoreKey key) { 092 String[] pieces = key.getStorageKey().split(":", -1); 093 if (pieces.length != 5 || !pieces[0].equals("wa1") || !pieces[3].equals(key.getKind().name()) 094 || pieces[1].isEmpty() || pieces[2].isEmpty() || pieces[4].length() != 43) 095 throw new IllegalArgumentException("Invalid WebAuthn read scope"); 096 return pieces[1] + ':' + pieces[2]; 097 } 098 099 /** Redacts all keys and records. @since 1.0.0 */ 100 @Override public @NonNull String toString() { return "WebAuthnStoreSnapshot{entries=<redacted>}"; } 101}