key transparency: add distinguished key endpoint

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

@@ -11,34 +11,9 @@ import io.dropwizard.auth.Auth;
 import io.grpc.Status;
 import io.grpc.StatusRuntimeException;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
-import org.signal.keytransparency.client.MonitorKey;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.whispersystems.textsecuregcm.auth.AuthenticatedDevice;
-import org.whispersystems.textsecuregcm.entities.KeyTransparencyMonitorRequest;
-import org.whispersystems.textsecuregcm.entities.KeyTransparencyMonitorResponse;
-import org.whispersystems.textsecuregcm.entities.KeyTransparencySearchRequest;
-import org.whispersystems.textsecuregcm.entities.KeyTransparencySearchResponse;
-import org.whispersystems.textsecuregcm.keytransparency.KeyTransparencyServiceClient;
-import org.whispersystems.textsecuregcm.limits.RateLimitedByIp;
-import org.whispersystems.textsecuregcm.limits.RateLimiters;
-import org.whispersystems.textsecuregcm.util.ExceptionUtils;
-import org.whispersystems.websocket.auth.ReadOnly;
-
-import javax.validation.Valid;
-import javax.validation.constraints.NotNull;
-import javax.ws.rs.BadRequestException;
-import javax.ws.rs.ForbiddenException;
-import javax.ws.rs.NotFoundException;
-import javax.ws.rs.POST;
-import javax.ws.rs.Path;
-import javax.ws.rs.Produces;
-import javax.ws.rs.ServerErrorException;
-import javax.ws.rs.WebApplicationException;
-import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.Response;
 import java.nio.ByteBuffer;
 import java.nio.charset.StandardCharsets;
 import java.time.Duration;
@@ -48,6 +23,35 @@ import java.util.Optional;
 import java.util.concurrent.CancellationException;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Positive;
+import javax.ws.rs.BadRequestException;
+import javax.ws.rs.ForbiddenException;
+import javax.ws.rs.GET;
+import javax.ws.rs.NotFoundException;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.ServerErrorException;
+import javax.ws.rs.WebApplicationException;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.signal.keytransparency.client.MonitorKey;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.whispersystems.textsecuregcm.auth.AuthenticatedDevice;
+import org.whispersystems.textsecuregcm.entities.KeyTransparencyDistinguishedKeyResponse;
+import org.whispersystems.textsecuregcm.entities.KeyTransparencyMonitorRequest;
+import org.whispersystems.textsecuregcm.entities.KeyTransparencyMonitorResponse;
+import org.whispersystems.textsecuregcm.entities.KeyTransparencySearchRequest;
+import org.whispersystems.textsecuregcm.entities.KeyTransparencySearchResponse;
+import org.whispersystems.textsecuregcm.keytransparency.KeyTransparencyServiceClient;
+import org.whispersystems.textsecuregcm.limits.RateLimitedByIp;
+import org.whispersystems.textsecuregcm.limits.RateLimiters;
+import org.whispersystems.textsecuregcm.util.ExceptionUtils;
+import org.whispersystems.websocket.auth.ReadOnly;
 
 @Path("/v1/key-transparency")
 @Tag(name = "KeyTransparency")
@@ -76,9 +80,10 @@ public class KeyTransparencyController {
           """
   )
   @ApiResponse(responseCode = "200", description = "All search key lookups were successful", useReturnTypeSchema = true)
+  @ApiResponse(responseCode = "400", description = "Invalid request. See response for any available details.")
   @ApiResponse(responseCode = "403", description = "At least one search key lookup to value mapping was invalid")
   @ApiResponse(responseCode = "404", description = "At least one search key lookup did not find the key")
-  @ApiResponse(responseCode = "429", description = "Ratelimited")
+  @ApiResponse(responseCode = "429", description = "Rate-limited")
   @ApiResponse(responseCode = "422", description = "Invalid request format")
   @POST
   @Path("/search")
@@ -145,8 +150,9 @@ public class KeyTransparencyController {
           """
   )
   @ApiResponse(responseCode = "200", description = "All search keys exist in the log", useReturnTypeSchema = true)
+  @ApiResponse(responseCode = "400", description = "Invalid request. See response for any available details.")
   @ApiResponse(responseCode = "404", description = "At least one search key lookup did not find the key")
-  @ApiResponse(responseCode = "429", description = "Ratelimited")
+  @ApiResponse(responseCode = "429", description = "Rate-limited")
   @ApiResponse(responseCode = "422", description = "Invalid request format")
   @POST
   @Path("/monitor")
@@ -191,6 +197,44 @@ public class KeyTransparencyController {
     return null;
   }
 
+  @Operation(
+      summary = "Get the current value of the distinguished key",
+      description = """
+          Enforced unauthenticated endpoint. The response contains the distinguished tree head to prove consistency
+          against for future calls to `/search` and `/distinguished`.
+          """
+  )
+  @ApiResponse(responseCode = "200", description = "The `distinguished` search key exists in the log", useReturnTypeSchema = true)
+  @ApiResponse(responseCode = "400", description = "Invalid request. See response for any available details.")
+  @ApiResponse(responseCode = "422", description = "Invalid request format")
+  @ApiResponse(responseCode = "429", description = "Rate-limited")
+  @GET
+  @Path("/distinguished")
+  @RateLimitedByIp(RateLimiters.For.KEY_TRANSPARENCY_DISTINGUISHED_PER_IP)
+  @Produces(MediaType.APPLICATION_JSON)
+  public KeyTransparencyDistinguishedKeyResponse getDistinguishedKey(
+      @ReadOnly @Auth final Optional<AuthenticatedDevice> authenticatedAccount,
+
+      @Parameter(description = "The distinguished tree head size returned by a previously verified call")
+      @QueryParam("lastTreeHeadSize") @Valid final Optional<@Positive Long> lastTreeHeadSize) {
+
+    // Disallow clients from making authenticated requests to this endpoint
+    requireNotAuthenticated(authenticatedAccount);
+
+    try {
+      return keyTransparencyServiceClient.getDistinguishedKey(lastTreeHeadSize, KEY_TRANSPARENCY_RPC_TIMEOUT)
+          .thenApply(KeyTransparencyDistinguishedKeyResponse::new)
+          .join();
+    } catch (final CancellationException exception) {
+      LOGGER.error("Unexpected cancellation from key transparency service", exception);
+      throw new ServerErrorException(Response.Status.SERVICE_UNAVAILABLE, exception);
+    } catch (final CompletionException exception) {
+      handleKeyTransparencyServiceError(exception);
+    }
+    // This is unreachable
+    return null;
+  }
+
   private void handleKeyTransparencyServiceError(final CompletionException exception) {
     final Throwable unwrapped = ExceptionUtils.unwrap(exception);
 

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

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2024 Signal Messenger, LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+package org.whispersystems.textsecuregcm.entities;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.v3.oas.annotations.media.Schema;
+import javax.validation.constraints.NotNull;
+import org.whispersystems.textsecuregcm.util.ByteArrayAdapter;
+
+public record KeyTransparencyDistinguishedKeyResponse(
+    @NotNull
+    @JsonSerialize(using = ByteArrayAdapter.Serializing.class)
+    @JsonDeserialize(using = ByteArrayAdapter.Deserializing.class)
+    @Schema(description = "The response for the distinguished tree head encoded in standard un-padded base64")
+    byte[] distinguishedKeyResponse
+) {}

service/src/main/java/org/whispersystems/textsecuregcm/keytransparency/KeyTransparencyServiceClient.java

@@ -25,6 +25,7 @@ import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.Executor;
 import java.util.concurrent.TimeUnit;
 import org.signal.keytransparency.client.ConsistencyParameters;
+import org.signal.keytransparency.client.DistinguishedRequest;
 import org.signal.keytransparency.client.KeyTransparencyQueryServiceGrpc;
 import org.signal.keytransparency.client.MonitorKey;
 import org.signal.keytransparency.client.MonitorRequest;
@@ -153,6 +154,16 @@ public class KeyTransparencyServiceClient implements Managed {
         .thenApply(AbstractMessageLite::toByteArray);
   }
 
+  @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
+  public CompletableFuture<byte[]> getDistinguishedKey(final Optional<Long> lastTreeHeadSize, final Duration timeout) {
+    final DistinguishedRequest request = lastTreeHeadSize.map(
+            last -> DistinguishedRequest.newBuilder().setLast(last).build())
+        .orElseGet(DistinguishedRequest::getDefaultInstance);
+    return CompletableFutureUtil.toCompletableFuture(stub.withDeadline(toDeadline(timeout)).distinguished(request),
+            callbackExecutor)
+        .thenApply(AbstractMessageLite::toByteArray);
+  }
+
   private static Deadline toDeadline(final Duration timeout) {
     return Deadline.after(timeout.toMillis(), TimeUnit.MILLISECONDS);
   }

service/src/main/java/org/whispersystems/textsecuregcm/limits/RateLimiters.java

@@ -48,6 +48,8 @@ public class RateLimiters extends BaseRateLimiters<RateLimiters.For> {
     CREATE_CALL_LINK("createCallLink", false, new RateLimiterConfig(100, Duration.ofMinutes(15))),
     INBOUND_MESSAGE_BYTES("inboundMessageBytes", true, new RateLimiterConfig(128 * 1024 * 1024, Duration.ofNanos(500_000))),
     EXTERNAL_SERVICE_CREDENTIALS("externalServiceCredentials", true, new RateLimiterConfig(100, Duration.ofMinutes(15))),
+    KEY_TRANSPARENCY_DISTINGUISHED_PER_IP("keyTransparencyDistinguished", true,
+        new RateLimiterConfig(100, Duration.ofSeconds(15))),
     KEY_TRANSPARENCY_SEARCH_PER_IP("keyTransparencySearch", true, new RateLimiterConfig(100, Duration.ofSeconds(15))),
     KEY_TRANSPARENCY_MONITOR_PER_IP("keyTransparencyMonitor", true, new RateLimiterConfig(100, Duration.ofSeconds(15))),
     WAIT_FOR_LINKED_DEVICE("waitForLinkedDevice", true, new RateLimiterConfig(10, Duration.ofSeconds(30))),