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}