Add svr2 credentials to RegistrationLockFailure responses

Add an svr2 credential to 423 responses for:
  - PUT v2/accounts/number
  - POST v1/registration

Also add some openapi annotations to those endpoints

service/src/main/java/org/whispersystems/textsecuregcm/WhisperServerService.java

@@ -525,7 +525,7 @@ public class WhisperServerService extends Application<WhisperServerConfiguration
         config.getDynamoDbTables().getSubscriptions().getTableName(), dynamoDbAsyncClient);
 
     final RegistrationLockVerificationManager registrationLockVerificationManager = new RegistrationLockVerificationManager(
-        accountsManager, clientPresenceManager, backupCredentialsGenerator, registrationRecoveryPasswordsManager, pushNotificationManager, rateLimiters);
+        accountsManager, clientPresenceManager, backupCredentialsGenerator, svr2CredentialsGenerator, registrationRecoveryPasswordsManager, pushNotificationManager, rateLimiters);
     final PhoneVerificationTokenManager phoneVerificationTokenManager = new PhoneVerificationTokenManager(
         registrationServiceClient, registrationRecoveryPasswordsManager);
 

service/src/main/java/org/whispersystems/textsecuregcm/auth/RegistrationLockVerificationManager.java

@@ -8,13 +8,16 @@ package org.whispersystems.textsecuregcm.auth;
 import static org.whispersystems.textsecuregcm.metrics.MetricsUtil.name;
 
 import com.google.common.annotations.VisibleForTesting;
-import javax.annotation.Nullable;
-import javax.ws.rs.WebApplicationException;
-import javax.ws.rs.core.Response;
 import io.micrometer.core.instrument.DistributionSummary;
 import io.micrometer.core.instrument.Metrics;
 import io.micrometer.core.instrument.Tag;
 import io.micrometer.core.instrument.Tags;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import javax.annotation.Nullable;
+import javax.ws.rs.WebApplicationException;
+import javax.ws.rs.core.Response;
 import org.whispersystems.textsecuregcm.controllers.RateLimitExceededException;
 import org.whispersystems.textsecuregcm.entities.PhoneVerificationRequest;
 import org.whispersystems.textsecuregcm.entities.RegistrationLockFailure;
@@ -28,9 +31,6 @@ import org.whispersystems.textsecuregcm.storage.AccountsManager;
 import org.whispersystems.textsecuregcm.storage.Device;
 import org.whispersystems.textsecuregcm.storage.RegistrationRecoveryPasswordsManager;
 import org.whispersystems.textsecuregcm.util.Util;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.List;
 
 public class RegistrationLockVerificationManager {
   public enum Flow {
@@ -54,20 +54,23 @@ public class RegistrationLockVerificationManager {
 
   private final AccountsManager accounts;
   private final ClientPresenceManager clientPresenceManager;
-  private final ExternalServiceCredentialsGenerator backupServiceCredentialGenerator;
+  private final ExternalServiceCredentialsGenerator svr1CredentialGenerator;
+  private final ExternalServiceCredentialsGenerator svr2CredentialGenerator;
   private final RateLimiters rateLimiters;
   private final RegistrationRecoveryPasswordsManager registrationRecoveryPasswordsManager;
   private final PushNotificationManager pushNotificationManager;
 
   public RegistrationLockVerificationManager(
       final AccountsManager accounts, final ClientPresenceManager clientPresenceManager,
-      final ExternalServiceCredentialsGenerator backupServiceCredentialGenerator,
+      final ExternalServiceCredentialsGenerator svr1CredentialGenerator,
+      final ExternalServiceCredentialsGenerator svr2CredentialGenerator,
       final RegistrationRecoveryPasswordsManager registrationRecoveryPasswordsManager,
       final PushNotificationManager pushNotificationManager,
       final RateLimiters rateLimiters) {
     this.accounts = accounts;
     this.clientPresenceManager = clientPresenceManager;
-    this.backupServiceCredentialGenerator = backupServiceCredentialGenerator;
+    this.svr1CredentialGenerator = svr1CredentialGenerator;
+    this.svr2CredentialGenerator = svr2CredentialGenerator;
     this.registrationRecoveryPasswordsManager = registrationRecoveryPasswordsManager;
     this.pushNotificationManager = pushNotificationManager;
     this.rateLimiters = rateLimiters;
@@ -138,8 +141,8 @@ public class RegistrationLockVerificationManager {
       // Freezing the existing account credentials will definitively start the reglock timeout.
       // Until the timeout, the current reglock can still be supplied,
       // along with phone number verification, to restore access.
-      final ExternalServiceCredentials existingBackupCredentials =
-          backupServiceCredentialGenerator.generateForUuid(account.getUuid());
+      final ExternalServiceCredentials existingSvr1Credentials = svr1CredentialGenerator.generateForUuid(account.getUuid());
+      final ExternalServiceCredentials existingSvr2Credentials = svr2CredentialGenerator.generateForUuid(account.getUuid());
 
       final Account updatedAccount;
       if (!alreadyLocked) {
@@ -170,7 +173,8 @@ public class RegistrationLockVerificationManager {
 
       throw new WebApplicationException(Response.status(FAILURE_HTTP_STATUS)
           .entity(new RegistrationLockFailure(existingRegistrationLock.getTimeRemaining().toMillis(),
-              existingRegistrationLock.needsFailureCredentials() ? existingBackupCredentials : null))
+              existingRegistrationLock.needsFailureCredentials() ? existingSvr1Credentials : null,
+              existingRegistrationLock.needsFailureCredentials() ? existingSvr2Credentials : null))
           .build());
     }
 

service/src/main/java/org/whispersystems/textsecuregcm/controllers/AccountControllerV2.java

@@ -14,6 +14,9 @@ import io.micrometer.core.instrument.Metrics;
 import io.micrometer.core.instrument.Tag;
 import io.micrometer.core.instrument.Tags;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import java.time.Instant;
 import java.util.Optional;
@@ -39,8 +42,9 @@ import org.whispersystems.textsecuregcm.entities.AccountIdentityResponse;
 import org.whispersystems.textsecuregcm.entities.ChangeNumberRequest;
 import org.whispersystems.textsecuregcm.entities.MismatchedDevices;
 import org.whispersystems.textsecuregcm.entities.PhoneNumberDiscoverabilityRequest;
-import org.whispersystems.textsecuregcm.entities.PhoneVerificationRequest;
 import org.whispersystems.textsecuregcm.entities.PhoneNumberIdentityKeyDistributionRequest;
+import org.whispersystems.textsecuregcm.entities.PhoneVerificationRequest;
+import org.whispersystems.textsecuregcm.entities.RegistrationLockFailure;
 import org.whispersystems.textsecuregcm.entities.StaleDevices;
 import org.whispersystems.textsecuregcm.limits.RateLimiter;
 import org.whispersystems.textsecuregcm.limits.RateLimiters;
@@ -77,6 +81,16 @@ public class AccountControllerV2 {
   @Path("/number")
   @Consumes(MediaType.APPLICATION_JSON)
   @Produces(MediaType.APPLICATION_JSON)
+  @Operation(summary = "Change number", description = "Changes a phone number for an existing account.")
+  @ApiResponse(responseCode = "200", description = "The phone number associated with the authenticated account was changed successfully", useReturnTypeSchema = true)
+  @ApiResponse(responseCode = "403", description = "Verification failed for the provided Registration Recovery Password")
+  @ApiResponse(responseCode = "409", description = "Mismatched number of devices or device ids in 'devices to notify' list", content = @Content(schema = @Schema(implementation = MismatchedDevices.class)))
+  @ApiResponse(responseCode = "410", description = "Mismatched registration ids in 'devices to notify' list", content = @Content(schema = @Schema(implementation = StaleDevices.class)))
+  @ApiResponse(responseCode = "422", description = "The request did not pass validation")
+  @ApiResponse(responseCode = "423", content = @Content(schema = @Schema(implementation = RegistrationLockFailure.class)))
+  @ApiResponse(responseCode = "429", description = "Too many attempts", headers = @Header(
+      name = "Retry-After",
+      description = "If present, an positive integer indicating the number of seconds before a subsequent attempt could succeed"))
   public AccountIdentityResponse changeNumber(@Auth final AuthenticatedAccount authenticatedAccount,
       @NotNull @Valid final ChangeNumberRequest request, @HeaderParam(HttpHeaders.USER_AGENT) final String userAgent)
       throws RateLimitExceededException, InterruptedException {

service/src/main/java/org/whispersystems/textsecuregcm/controllers/RegistrationController.java

@@ -13,6 +13,11 @@ import io.micrometer.core.instrument.DistributionSummary;
 import io.micrometer.core.instrument.Metrics;
 import io.micrometer.core.instrument.Tag;
 import io.micrometer.core.instrument.Tags;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
@@ -34,6 +39,7 @@ import org.whispersystems.textsecuregcm.auth.PhoneVerificationTokenManager;
 import org.whispersystems.textsecuregcm.auth.RegistrationLockVerificationManager;
 import org.whispersystems.textsecuregcm.entities.AccountIdentityResponse;
 import org.whispersystems.textsecuregcm.entities.PhoneVerificationRequest;
+import org.whispersystems.textsecuregcm.entities.RegistrationLockFailure;
 import org.whispersystems.textsecuregcm.entities.RegistrationRequest;
 import org.whispersystems.textsecuregcm.limits.RateLimiter;
 import org.whispersystems.textsecuregcm.limits.RateLimiters;
@@ -78,6 +84,22 @@ public class RegistrationController {
   @POST
   @Consumes(MediaType.APPLICATION_JSON)
   @Produces(MediaType.APPLICATION_JSON)
+  @Operation(summary = "Registers an account",
+  description = """
+      Registers a new account or attempts to “re-register” an existing account. It is expected that a well-behaved client 
+      could make up to three consecutive calls to this API:
+      1. gets 423 from existing registration lock \n
+      2. gets 409 from device available for transfer \n
+      3. success \n
+      """)
+  @ApiResponse(responseCode = "200", description = "The phone number associated with the authenticated account was changed successfully", useReturnTypeSchema = true)
+  @ApiResponse(responseCode = "403", description = "Verification failed for the provided Registration Recovery Password")
+  @ApiResponse(responseCode = "409", description = "The caller has not explicitly elected to skip transferring data from another device, but a device transfer is technically possible")
+  @ApiResponse(responseCode = "422", description = "The request did not pass validation")
+  @ApiResponse(responseCode = "423", content = @Content(schema = @Schema(implementation = RegistrationLockFailure.class)))
+  @ApiResponse(responseCode = "429", description = "Too many attempts", headers = @Header(
+      name = "Retry-After",
+      description = "If present, an positive integer indicating the number of seconds before a subsequent attempt could succeed"))
   public AccountIdentityResponse register(
       @HeaderParam(HttpHeaders.AUTHORIZATION) @NotNull final BasicAuthorizationHeader authorizationHeader,
       @HeaderParam(HeaderUtils.X_SIGNAL_AGENT) final String signalAgent,

service/src/main/java/org/whispersystems/textsecuregcm/entities/MismatchedDevices.java

@@ -7,15 +7,18 @@ package org.whispersystems.textsecuregcm.entities;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.google.common.annotations.VisibleForTesting;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 import java.util.List;
 
 public class MismatchedDevices {
 
   @JsonProperty
+  @Schema(description = "Devices present on the account but absent in the request")
   public List<Long> missingDevices;
 
   @JsonProperty
+  @Schema(description = "Devices absent on the request but present in the account")
   public List<Long> extraDevices;
 
   @VisibleForTesting

service/src/main/java/org/whispersystems/textsecuregcm/entities/RegistrationLockFailure.java

@@ -5,8 +5,16 @@
 
 package org.whispersystems.textsecuregcm.entities;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.whispersystems.textsecuregcm.auth.ExternalServiceCredentials;
 
-public record RegistrationLockFailure(long timeRemaining, ExternalServiceCredentials backupCredentials) {
+@Schema(description = "A token provided to the client via a push payload")
 
+public record RegistrationLockFailure(
+    @Schema(description = "Time remaining in milliseconds before the existing registration lock expires")
+    long timeRemaining,
+    @Schema(description = "Credentials that can be used with SVR1")
+    ExternalServiceCredentials backupCredentials,
+    @Schema(description = "Credentials that can be used with SVR2")
+    ExternalServiceCredentials svr2Credentials) {
 }

service/src/main/java/org/whispersystems/textsecuregcm/entities/StaleDevices.java

@@ -6,12 +6,14 @@
 package org.whispersystems.textsecuregcm.entities;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 import java.util.List;
 
 public class StaleDevices {
 
   @JsonProperty
+  @Schema(description = "Devices that are no longer active")
   private List<Long> staleDevices;
 
   public StaleDevices() {}