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}