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.StoreTemporalCondition; 021import com.revetsec.StoreTimeObservation; 022import com.revetsec.internal.StoreTimeRules; 023import java.time.Instant; 024import java.util.HashSet; 025import java.util.List; 026import java.util.Optional; 027import java.util.Set; 028import org.jspecify.annotations.NonNull; 029import org.jspecify.annotations.Nullable; 030 031/** 032 * One immutable atomic compare-and-commit request. The complete snapshot is the predicate set: 033 * every observed version and every confirmed absence must still match. New versions must be 034 * unique across updates to prevent ABA. A condition-only write still checks the whole snapshot. 035 * @since 1.0.0 036 */ 037@javax.annotation.concurrent.Immutable 038@CheckReturnValue 039public final class WebAuthnStoreWrite { 040 private final @NonNull WebAuthnStoreSnapshot snapshot; 041 private final @NonNull List<WebAuthnStoreWrite.@NonNull Mutation> mutations; 042 private final @NonNull StoreTemporalCondition temporalCondition; 043 044 private WebAuthnStoreWrite(@NonNull WebAuthnStoreSnapshot snapshot, 045 @NonNull List<WebAuthnStoreWrite.@NonNull Mutation> mutations, 046 @NonNull StoreTemporalCondition temporalCondition) { 047 this.snapshot = snapshot; this.mutations = List.copyOf(mutations); 048 this.temporalCondition = temporalCondition; 049 } 050 051 /** 052 * Combines an exact snapshot with at most eight distinct mutations of its keys. Insertion 053 * requires confirmed absence; replacement and deletion require a present version. 054 * @param snapshot the complete predicate set 055 * @param mutations the bounded change set, possibly empty 056 * @param temporalCondition engine-created inclusive floor and optional exclusive expiry 057 * @return a validated atomic request 058 * @since 1.0.0 059 */ 060 public static @NonNull WebAuthnStoreWrite fromSnapshotAndMutations( 061 @NonNull WebAuthnStoreSnapshot snapshot, 062 @NonNull List<WebAuthnStoreWrite.@NonNull Mutation> mutations, 063 @NonNull StoreTemporalCondition temporalCondition) { 064 java.util.Objects.requireNonNull(snapshot); 065 java.util.Objects.requireNonNull(mutations); java.util.Objects.requireNonNull(temporalCondition); 066 if (!(snapshot.getTimeObservation() instanceof StoreTimeObservation.Healthy healthy) 067 || !StoreTimeRules.sameAdmission(healthy.getAdmission(), temporalCondition.getAdmission()) 068 || !healthy.getClockGeneration().equals(temporalCondition.getClockGeneration()) 069 || temporalCondition.getNotBeforeInclusive().isBefore(healthy.getObservedAt())) 070 throw new IllegalArgumentException("Inconsistent WebAuthn temporal condition"); 071 if (mutations.size() > 8) throw new IllegalArgumentException("Too many mutations"); 072 Set<WebAuthnStoreKey> changed = new HashSet<>(); 073 for (Mutation mutation : mutations) { 074 java.util.Objects.requireNonNull(mutation); 075 WebAuthnStoreEntry prior = snapshot.getEntry(mutation.key); 076 if (!changed.add(mutation.key) 077 || (mutation.kind == Mutation.Kind.INSERT && !(prior instanceof WebAuthnStoreEntry.Absent)) 078 || (mutation.kind != Mutation.Kind.INSERT && !(prior instanceof WebAuthnStoreEntry.Present))) 079 throw new IllegalArgumentException("Invalid store mutation"); 080 } 081 return new WebAuthnStoreWrite(snapshot, mutations, temporalCondition); 082 } 083 084 /** Returns every exact version or absence predicate. 085 * @return the read set 086 * @since 1.0.0 */ 087 public @NonNull WebAuthnStoreSnapshot getSnapshot() { return this.snapshot; } 088 089 /** Returns the immutable ordered mutation set. 090 * @return the mutations 091 * @since 1.0.0 */ 092 public @NonNull List<WebAuthnStoreWrite.@NonNull Mutation> getMutations() { return this.mutations; } 093 094 /** Returns the original admitted temporal predicate. 095 * @return the inclusive floor and optional exclusive expiry 096 * @since 1.0.0 */ 097 public @NonNull StoreTemporalCondition getTemporalCondition() { return this.temporalCondition; } 098 099 /** Redacts predicates and mutations. @since 1.0.0 */ 100 @Override public @NonNull String toString() { return "WebAuthnStoreWrite{write=<redacted>}"; } 101 102 /** A typed insertion, replacement or deletion of a key from the read set. 103 * @since 1.0.0 */ 104 @javax.annotation.concurrent.Immutable 105 public static final class Mutation { 106 private final @NonNull WebAuthnStoreKey key; 107 private final WebAuthnStoreWrite.Mutation.@NonNull Kind kind; 108 private final byte @Nullable [] sealedBytes; 109 private final @Nullable Instant expiresAt; 110 111 private Mutation(@NonNull WebAuthnStoreKey key, WebAuthnStoreWrite.Mutation.@NonNull Kind kind, 112 byte @Nullable [] sealedBytes, @Nullable Instant expiresAt) { 113 this.key = java.util.Objects.requireNonNull(key); 114 this.kind = kind; 115 this.sealedBytes = sealedBytes == null ? null : sealedBytes.clone(); 116 this.expiresAt = expiresAt; 117 } 118 119 /** Inserts a sealed record only if the read set confirms absence. 120 * @param key the absent key 121 * @param sealedBytes the new sealed record 122 * @return the insertion 123 * @since 1.0.0 */ 124 public static @NonNull Mutation insert(@NonNull WebAuthnStoreKey key, 125 byte @NonNull [] sealedBytes) { 126 validateSealedBytes(sealedBytes); 127 return new Mutation(key, Kind.INSERT, sealedBytes, null); 128 } 129 130 /** Inserts a ceremony with a store-visible reclamation deadline. Core also checks the 131 * authenticated expiry in the sealed record before accepting a completion. 132 * @param key the absent ceremony key 133 * @param sealedBytes the sealed ceremony 134 * @param expiresAt the deadline after which the store may remove the ceremony 135 * @return the insertion 136 * @since 1.0.0 */ 137 public static @NonNull Mutation insertExpiring(@NonNull WebAuthnStoreKey key, 138 byte @NonNull [] sealedBytes, @NonNull Instant expiresAt) { 139 requireCeremony(key, expiresAt); 140 validateSealedBytes(sealedBytes); 141 return new Mutation(key, Kind.INSERT, sealedBytes, expiresAt); 142 } 143 144 /** Replaces a versioned sealed record. 145 * @param key the versioned key 146 * @param sealedBytes the new sealed record 147 * @return the replacement 148 * @since 1.0.0 */ 149 public static @NonNull Mutation replace(@NonNull WebAuthnStoreKey key, 150 byte @NonNull [] sealedBytes) { 151 validateSealedBytes(sealedBytes); 152 return new Mutation(key, Kind.REPLACE, sealedBytes, null); 153 } 154 155 /** Replaces a ceremony while retaining its store-visible reclamation deadline. 156 * @param key the versioned ceremony key 157 * @param sealedBytes the new sealed ceremony 158 * @param expiresAt the deadline after which the store may remove the ceremony 159 * @return the replacement 160 * @since 1.0.0 */ 161 public static @NonNull Mutation replaceExpiring(@NonNull WebAuthnStoreKey key, 162 byte @NonNull [] sealedBytes, @NonNull Instant expiresAt) { 163 requireCeremony(key, expiresAt); 164 validateSealedBytes(sealedBytes); 165 return new Mutation(key, Kind.REPLACE, sealedBytes, expiresAt); 166 } 167 168 /** Deletes a versioned record. Retain a replay tombstone where protocol rules require it. 169 * @param key the versioned key 170 * @return the deletion 171 * @since 1.0.0 */ 172 public static @NonNull Mutation delete(@NonNull WebAuthnStoreKey key) { 173 return new Mutation(key, Kind.DELETE, null, null); 174 } 175 176 /** Returns the changed key. 177 * @return the key 178 * @since 1.0.0 */ 179 public @NonNull WebAuthnStoreKey getKey() { return this.key; } 180 181 /** Returns the mutation kind. 182 * @return the kind 183 * @since 1.0.0 */ 184 public WebAuthnStoreWrite.Mutation.@NonNull Kind getKind() { return this.kind; } 185 186 /** Returns a defensive copy of the sealed payload, or empty for deletion. 187 * @return the payload, if any 188 * @since 1.0.0 */ 189 public @NonNull Optional<byte @NonNull []> getSealedBytes() { 190 return this.sealedBytes == null ? Optional.empty() : Optional.of(this.sealedBytes.clone()); 191 } 192 193 /** Returns the ceremony reclamation deadline, if supplied. It is an exact projection of the 194 * authenticated expiry, not authority to delete during reads or a no-effect refusal. A successful 195 * mutating commit may reclaim an expired ceremony outside its predicate set after rechecking it 196 * against current healthy admitted time. Other record kinds are never reclaimed by this hint. 197 * @return the optional maintenance deadline 198 * @since 1.0.0 */ 199 public @NonNull Optional<@NonNull Instant> getExpiresAt() { return Optional.ofNullable(this.expiresAt); } 200 201 /** Redacts the key and payload. @since 1.0.0 */ 202 @Override public @NonNull String toString() { return "Mutation{change=<redacted>}"; } 203 204 private static void validateSealedBytes(byte @NonNull [] sealedBytes) { 205 if (sealedBytes.length == 0 || sealedBytes.length > 262144) 206 throw new IllegalArgumentException("Invalid sealed record length"); 207 } 208 209 private static void requireCeremony(@NonNull WebAuthnStoreKey key, @NonNull Instant expiresAt) { 210 java.util.Objects.requireNonNull(expiresAt); 211 if (java.util.Objects.requireNonNull(key).getKind() != WebAuthnStoreKey.Kind.CEREMONY) 212 throw new IllegalArgumentException("Only ceremonies may carry a reclamation deadline"); 213 } 214 215 /** The three atomic write operations. 216 * @since 1.0.0 */ 217 @javax.annotation.concurrent.Immutable 218 public enum Kind { 219 /** Insert after confirmed absence. */ INSERT, 220 /** Replace an exact version. */ REPLACE, 221 /** Delete an exact version. */ DELETE 222 } 223 } 224}