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.oauth.server;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.StoreAdmission;
021import com.revetsec.StoreTemporalCondition;
022import com.revetsec.internal.StoreTimeRules;
023import org.jspecify.annotations.NonNull;
024import org.jspecify.annotations.Nullable;
025import javax.annotation.concurrent.Immutable;
026import java.time.Instant;
027import java.util.List;
028import java.util.Optional;
029import static java.util.Objects.requireNonNull;
030
031/**
032 * Complete immutable issuer transaction, created only by the engine. Backends compare opaque versions exactly.
033 * Every changed key has a condition; absence means ABSENT, never any version. All conditions and mutations
034 * must linearize together. An empty mutation list is an authoritative status barrier.
035 * @author <a href="https://www.revetkn.com">Mark Allen</a>
036 *
037 * @since 1.0.0
038 */
039@Immutable
040@CheckReturnValue
041public final class OAuthStoreTransaction {
042 private final OAuthStoreTransaction.@NonNull Purpose purpose;
043 private final @NonNull StoreAdmission expectedAdmission;
044 private final @Nullable StoreTemporalCondition temporalCondition;
045 private final @NonNull List<OAuthStoreTransaction.@NonNull Condition> conditions;
046 private final @NonNull List<OAuthStoreTransaction.@NonNull Mutation> mutations;
047 private OAuthStoreTransaction(OAuthStoreTransaction.@NonNull Purpose purpose,
048   @NonNull StoreAdmission expectedAdmission, @Nullable StoreTemporalCondition temporalCondition,
049   @NonNull List<OAuthStoreTransaction.@NonNull Condition> conditions,
050   @NonNull List<OAuthStoreTransaction.@NonNull Mutation> mutations) {
051  this.purpose=purpose; this.expectedAdmission=expectedAdmission; this.temporalCondition=temporalCondition;
052  this.conditions = List.copyOf(conditions); this.mutations = List.copyOf(mutations);
053 }
054 static @NonNull OAuthStoreTransaction fromConditions(
055   OAuthStoreTransaction.@NonNull Purpose purpose, @NonNull StoreAdmission expectedAdmission,
056   @Nullable StoreTemporalCondition temporalCondition,
057   @NonNull List<OAuthStoreTransaction.@NonNull Condition> conditions,
058   @NonNull List<OAuthStoreTransaction.@NonNull Mutation> mutations) {
059  requireNonNull(purpose); requireNonNull(expectedAdmission); requireNonNull(conditions); requireNonNull(mutations);
060  if(purpose==Purpose.TIMED) {
061   if(temporalCondition==null || !StoreTimeRules.sameAdmission(expectedAdmission,temporalCondition.getAdmission())) throw OAuthStoreFormat.invalid();
062  } else if(temporalCondition!=null) throw OAuthStoreFormat.invalid();
063  if (conditions.isEmpty() || conditions.size() > 16 || mutations.size() > 8) throw OAuthStoreFormat.invalid();
064  var expected = new java.util.HashMap<OAuthStoreKey, Condition>();
065  String namespace=null;
066  for (Condition condition : conditions) {
067   requireNonNull(condition);
068   String scope=OAuthStoreFormat.namespace(condition.key);
069   if(namespace==null) namespace=scope; else if(!namespace.equals(scope)) throw OAuthStoreFormat.invalid();
070   if (expected.put(condition.key, condition) != null) throw OAuthStoreFormat.invalid();
071  }
072  var changed = new java.util.HashSet<OAuthStoreKey>();
073  for (Mutation mutation : mutations) {
074   requireNonNull(mutation); Condition condition = expected.get(mutation.key);
075   if (condition == null || !changed.add(mutation.key)
076     || (mutation.kind == Mutation.Kind.REMOVE && condition.version == null)
077     || (mutation.kind == Mutation.Kind.PUT && mutation.entry!=null && mutation.entry.getVersion().equals(condition.version))) throw OAuthStoreFormat.invalid();
078  }
079  if(purpose==Purpose.FENCE_ONLY) validateFence(conditions,mutations);
080  return new OAuthStoreTransaction(purpose,expectedAdmission,temporalCondition,conditions, mutations);
081 }
082 private static void validateFence(@NonNull List<OAuthStoreTransaction.@NonNull Condition> conditions,
083   @NonNull List<OAuthStoreTransaction.@NonNull Mutation> mutations) {
084  if(mutations.size()!=1) throw OAuthStoreFormat.invalid();
085  Mutation mutation=mutations.get(0);
086  if(mutation.kind!=Mutation.Kind.PUT || mutation.entry==null || !mutation.entry.getRetainUntil().equals(OAuthStoreFormat.PERMANENT)) throw OAuthStoreFormat.invalid();
087  boolean issuer=false,subject=false;
088  for(Condition condition:conditions) {
089   if(condition.version==null) throw OAuthStoreFormat.invalid();
090   if(condition.key.getKind()==OAuthStoreKey.Kind.ISSUER_STATE) issuer=true;
091   else if(condition.key.getKind()==OAuthStoreKey.Kind.SUBJECT_STATE && condition.key.equals(mutation.key)) subject=true;
092   else throw OAuthStoreFormat.invalid();
093  }
094  if(!issuer || (mutation.key.getKind()==OAuthStoreKey.Kind.ISSUER_STATE ? conditions.size()!=1
095    : mutation.key.getKind()!=OAuthStoreKey.Kind.SUBJECT_STATE || conditions.size()!=2 || !subject)) throw OAuthStoreFormat.invalid();
096 }
097 /** Returns TIMED or the narrow existing permanent-fence transition purpose.
098  * @return the purpose
099  * @since 1.0.0 */
100 public OAuthStoreTransaction.@NonNull Purpose getPurpose(){return this.purpose;}
101 /** Returns the admitted authority/recovery identities required by every condition.
102  * @return expected admission
103  * @since 1.0.0 */
104 public @NonNull StoreAdmission getExpectedAdmission(){return this.expectedAdmission;}
105 /** Returns the required TIMED condition, or empty only for FENCE_ONLY.
106  * @return the temporal condition
107  * @since 1.0.0 */
108 public @NonNull Optional<@NonNull StoreTemporalCondition> getTemporalCondition(){return Optional.ofNullable(this.temporalCondition);}
109 /** The two explicit transaction modes. FENCE_ONLY grants no generic clock-off write authority.
110  * @since 1.0.0 */
111 @Immutable
112 public enum Purpose {
113  /** Normal timed validation including initialization, issuance and maintenance. */
114  TIMED,
115  /** Exactly one existing permanent issuer/subject epoch advance; no temporal condition. */
116  FENCE_ONLY
117 }
118 /** Returns the complete immutable predicate set.
119 * @return all conditions
120 * @since 1.0.0 */
121 public @NonNull List<OAuthStoreTransaction.@NonNull Condition> getConditions() { return this.conditions; }
122 /** Returns the complete immutable write set, possibly empty.
123 * @return all mutations
124 * @since 1.0.0 */
125 public @NonNull List<OAuthStoreTransaction.@NonNull Mutation> getMutations() { return this.mutations; }
126 /** Redacts every predicate and mutation.
127 * @return a fixed description
128 * @since 1.0.0 */
129 @Override public @NonNull String toString() { return "OAuthStoreTransaction{transaction=<redacted>}"; }
130 /**
131  * An exact version or ABSENT predicate, engine-created and checked atomically with every other predicate.
132  * @author <a href="https://www.revetkn.com">Mark Allen</a>
133  * @since 1.0.0
134  */
135 @Immutable
136 @CheckReturnValue
137 public static final class Condition {
138  private final @NonNull OAuthStoreKey key;
139  private final @Nullable String version;
140  private Condition(@NonNull OAuthStoreKey key, @Nullable String version) {
141   this.key = requireNonNull(key); this.version = version;
142  }
143  static OAuthStoreTransaction.@NonNull Condition fromAbsent(@NonNull OAuthStoreKey key) {
144   return new Condition(key, null);
145  }
146  static OAuthStoreTransaction.@NonNull Condition fromVersion(@NonNull OAuthStoreKey key, @NonNull String version) {
147   OAuthStoreFormat.nonce(version); return new Condition(key, version);
148  }
149  /** Returns the conditioned key.
150 * @return the key
151 * @since 1.0.0 */
152  public @NonNull OAuthStoreKey getKey() { return this.key; }
153  /**
154   * Returns the exact expected version, or empty for ABSENT. Empty never means an unrestricted match.
155   * @return the version predicate
156   * @since 1.0.0
157   */
158  public @NonNull Optional<@NonNull String> getExpectedVersion() { return Optional.ofNullable(this.version); }
159  /** Redacts the predicate.
160 * @return a fixed description
161 * @since 1.0.0 */
162  @Override public @NonNull String toString() { return "Condition{predicate=<redacted>}"; }
163 }
164 /**
165  * An engine-created PUT or REMOVE; PUT carries its exact key-matched entry and REMOVE carries no entry.
166  * @author <a href="https://www.revetkn.com">Mark Allen</a>
167  * @since 1.0.0
168  */
169 @Immutable
170 @CheckReturnValue
171 public static final class Mutation {
172  private final @NonNull OAuthStoreKey key;
173  private final OAuthStoreTransaction.Mutation.@NonNull Kind kind;
174  private final @Nullable OAuthStoreEntry entry;
175  private Mutation(@NonNull OAuthStoreKey key, OAuthStoreTransaction.Mutation.@NonNull Kind kind,
176    @Nullable OAuthStoreEntry entry) { this.key = key; this.kind = kind; this.entry = entry; }
177  static OAuthStoreTransaction.@NonNull Mutation fromPut(@NonNull OAuthStoreEntry entry) {
178   requireNonNull(entry); return new Mutation(entry.getKey(), Kind.PUT, entry);
179  }
180  static OAuthStoreTransaction.@NonNull Mutation fromRemove(@NonNull OAuthStoreKey key) {
181   return new Mutation(requireNonNull(key), Kind.REMOVE, null);
182  }
183  /** Returns the changed key.
184 * @return the key
185 * @since 1.0.0 */
186  public @NonNull OAuthStoreKey getKey() { return this.key; }
187  /** Returns PUT or REMOVE.
188 * @return the mutation kind
189 * @since 1.0.0 */
190  public OAuthStoreTransaction.Mutation.@NonNull Kind getKind() { return this.kind; }
191  /** Returns the exact PUT entry or empty for REMOVE.
192 * @return the entry
193 * @since 1.0.0 */
194  public @NonNull Optional<@NonNull OAuthStoreEntry> getEntry() { return Optional.ofNullable(this.entry); }
195  /** Redacts the mutation.
196 * @return a fixed description
197 * @since 1.0.0 */
198  @Override public @NonNull String toString() { return "Mutation{change=<redacted>}"; }
199  /**
200   * The two mutation operations.
201   * @author <a href="https://www.revetkn.com">Mark Allen</a>
202   * @since 1.0.0
203   */
204  @Immutable
205  public enum Kind {
206   /** Store the supplied entry. */
207   PUT,
208   /** Remove the version-conditioned entry. */
209   REMOVE
210  }
211 }
212}