added some comments and renamed refreshIdentity method param to input instead of oken

Author: sunnywu

src/main/java/com/uid2/operator/model/IdentityResponse.java

@@ -9,9 +9,12 @@
 // jsonified
 public class IdentityResponse {
     public static IdentityResponse OptOutIdentityResponse = new IdentityResponse("", null, "", Instant.EPOCH, Instant.EPOCH, Instant.EPOCH);
+
+    //aka UID token
     private final String advertisingToken;
     private final TokenVersion advertisingTokenVersion;
     private final String refreshToken;
+    // when the advertising token/uid token expires
     private final Instant identityExpires;
     private final Instant refreshExpires;
     private final Instant refreshFrom;

src/main/java/com/uid2/operator/model/userIdentity/FirstLevelHashIdentity.java

@@ -21,6 +21,7 @@ public FirstLevelHashIdentity(IdentityScope identityScope, IdentityType identity
         this.establishedAt = establishedAt;
     }
 
+    // explicitly not checking establishedAt - this is only for making sure the first level hash matches a new input
     public boolean matches(FirstLevelHashIdentity that) {
         return this.identityScope.equals(that.identityScope) &&
                 this.identityType.equals(that.identityType) &&

src/main/java/com/uid2/operator/service/EncryptedTokenEncoder.java

@@ -57,6 +57,7 @@ private byte[] encodeIntoAdvertisingTokenV3(AdvertisingTokenInput t, KeysetKey m
         sitePayload.appendInt(t.privacyBits.getAsInt());
         sitePayload.appendLong(t.establishedAt.toEpochMilli());
         // this is the refreshedAt field in the spec - but effectively it is the time this advertising token is generated
+        // this is a redundant field as it is stored in master payload again, can consider dropping this field in future token version
         sitePayload.appendLong(t.createdAt.toEpochMilli());
         sitePayload.appendBytes(t.rawUidIdentity.rawUid); // 32 or 33 bytes
 

src/main/java/com/uid2/operator/service/IUIDOperatorService.java

@@ -14,7 +14,7 @@ public interface IUIDOperatorService {
 
     IdentityResponse generateIdentity(IdentityRequest request);
 
-    RefreshResponse refreshIdentity(RefreshTokenInput refreshTokenInput);
+    RefreshResponse refreshIdentity(RefreshTokenInput input);
 
     RawUidResponse mapIdentity(MapRequest request);
 

src/main/java/com/uid2/operator/service/UIDOperatorService.java

@@ -120,34 +120,34 @@ public IdentityResponse generateIdentity(IdentityRequest request) {
     }
 
     @Override
-    public RefreshResponse refreshIdentity(RefreshTokenInput token) {
+    public RefreshResponse refreshIdentity(RefreshTokenInput input) {
         // should not be possible as different scopes should be using different keys, but just in case
-        if (token.firstLevelHashIdentity.identityScope != this.identityScope) {
+        if (input.firstLevelHashIdentity.identityScope != this.identityScope) {
             return RefreshResponse.Invalid;
         }
 
-        if (token.firstLevelHashIdentity.establishedAt.isBefore(RefreshCutoff)) {
+        if (input.firstLevelHashIdentity.establishedAt.isBefore(RefreshCutoff)) {
             return RefreshResponse.Deprecated;
         }
 
         final Instant now = clock.instant();
 
-        if (token.expiresAt.isBefore(now)) {
+        if (input.expiresAt.isBefore(now)) {
             return RefreshResponse.Expired;
         }
 
-        final boolean isCstg = token.privacyBits.isClientSideTokenGenerated();
+        final boolean isCstg = input.privacyBits.isClientSideTokenGenerated();
 
         try {
-            final GlobalOptoutResult logoutEntry = getGlobalOptOutResult(token.firstLevelHashIdentity, true);
+            final GlobalOptoutResult logoutEntry = getGlobalOptOutResult(input.firstLevelHashIdentity, true);
             final boolean optedOut = logoutEntry.isOptedOut();
 
-            final Duration durationSinceLastRefresh = Duration.between(token.createdAt, now);
+            final Duration durationSinceLastRefresh = Duration.between(input.createdAt, now);
 
             if (!optedOut) {
-                IdentityResponse identityResponse = this.generateIdentity(token.sourcePublisher,
-                        token.firstLevelHashIdentity,
-                        token.privacyBits);
+                IdentityResponse identityResponse = this.generateIdentity(input.sourcePublisher,
+                        input.firstLevelHashIdentity,
+                        input.privacyBits);
 
                 return RefreshResponse.createRefreshedResponse(identityResponse, durationSinceLastRefresh, isCstg);
             } else {