[external API] Add created time to webhook secret views (#8100)

When a webhook secret is created, it is assigned a UUID. In the API,
secrets are always referenced by UUIDs, and do not have names. This is
fine for programmatic access to secrets, such as when a receiver
implementation adds or rotates its secrets automatically. However, it's
less useful for a human user creating or deleting secrets in the UI, as
they would have to keep the various UUIDs straight, which can be
challenging. See discussion in #8083.

While we _could_ add names to the secret resource so that human users
can identify them more easily, this is not ideal either. Secrets, unlike
other resouces, are basically fungible: the only thing a user would
really ever do with them is rotate them, and they have no real semantic
meaning beyond being "the old secret" or "the new secret". Therefore,
giving them names basically just forces the user to come up with a
unique string like "secret1" and "secret2" and so on, which is a bit
unfortunate.

Instead, we should display the creation timestamps of secrets in the UI.
This way, users need not come up with unique names for every secret, but
they can distinguish them beyond their UUID, and the timestamp
communicates the one thing about webhook secrets that the user will
actually care about: is it "the old one" or "the new one"?

This branch updates the external API view for webhook secrets to add a
`time_created` field. The view type itself is renamed from
`WebhookSecretId` to just `WebhookSecret`, since it now contains more
than an ID.

Fixes #8083

Author: hawkw

nexus/db-model/src/webhook_rx.rs

@@ -41,12 +41,7 @@ impl TryFrom<WebhookReceiverConfig> for views::WebhookReceiver {
     fn try_from(
         WebhookReceiverConfig { rx, secrets, subscriptions }: WebhookReceiverConfig,
     ) -> Result<views::WebhookReceiver, Self::Error> {
-        let secrets = secrets
-            .iter()
-            .map(|WebhookSecret { identity, .. }| views::WebhookSecretId {
-                id: identity.id.into_untyped_uuid(),
-            })
-            .collect();
+        let secrets = secrets.iter().map(views::WebhookSecret::from).collect();
         let subscriptions = subscriptions
             .into_iter()
             .map(shared::WebhookSubscription::try_from)
@@ -156,9 +151,18 @@ impl WebhookSecret {
     }
 }
 
-impl From<WebhookSecret> for views::WebhookSecretId {
+impl From<&'_ WebhookSecret> for views::WebhookSecret {
+    fn from(secret: &WebhookSecret) -> Self {
+        Self {
+            id: secret.identity.id.into_untyped_uuid(),
+            time_created: secret.identity.time_created,
+        }
+    }
+}
+
+impl From<WebhookSecret> for views::WebhookSecret {
     fn from(secret: WebhookSecret) -> Self {
-        Self { id: secret.identity.id.into_untyped_uuid() }
+        Self::from(&secret)
     }
 }
 

nexus/external-api/src/lib.rs

@@ -3690,7 +3690,7 @@ pub trait NexusExternalApi {
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::WebhookReceiverSelector>,
         params: TypedBody<params::WebhookSecretCreate>,
-    ) -> Result<HttpResponseCreated<views::WebhookSecretId>, HttpError>;
+    ) -> Result<HttpResponseCreated<views::WebhookSecret>, HttpError>;
 
     /// Remove secret from webhook receiver
     #[endpoint {

nexus/src/app/webhook.rs

@@ -464,21 +464,21 @@ impl Nexus {
         opctx: &OpContext,
         rx: lookup::WebhookReceiver<'_>,
         secret: String,
-    ) -> Result<views::WebhookSecretId, Error> {
+    ) -> Result<views::WebhookSecret, Error> {
         let (authz_rx,) = rx.lookup_for(authz::Action::CreateChild).await?;
         let secret = WebhookSecret::new(authz_rx.id(), secret);
-        let WebhookSecret { identity, .. } = self
+        let secret = self
             .datastore()
             .webhook_rx_secret_create(opctx, &authz_rx, secret)
             .await?;
-        let secret_id = identity.id;
         slog::info!(
             &opctx.log,
             "added secret to webhook receiver";
             "rx_id" => ?authz_rx.id(),
-            "secret_id" => ?secret_id,
+            "secret_id" => ?secret.identity.id,
+            "time_created"=> %secret.identity.time_created,
         );
-        Ok(views::WebhookSecretId { id: secret_id.into_untyped_uuid() })
+        Ok(secret.into())
     }
 
     pub async fn webhook_receiver_secret_delete(

nexus/src/external_api/http_entrypoints.rs

@@ -8089,7 +8089,7 @@ impl NexusExternalApi for NexusExternalApiImpl {
         rqctx: RequestContext<Self::Context>,
         query_params: Query<params::WebhookReceiverSelector>,
         params: TypedBody<params::WebhookSecretCreate>,
-    ) -> Result<HttpResponseCreated<views::WebhookSecretId>, HttpError> {
+    ) -> Result<HttpResponseCreated<views::WebhookSecret>, HttpError> {
         let apictx = rqctx.context();
         let handler = async {
             let nexus = &apictx.context.nexus;

nexus/tests/integration_tests/webhooks.rs

@@ -191,10 +191,10 @@ async fn secret_add(
     ctx: &ControlPlaneTestContext,
     webhook_id: WebhookReceiverUuid,
     params: &params::WebhookSecretCreate,
-) -> views::WebhookSecretId {
+) -> views::WebhookSecret {
     resource_helpers::object_create::<
         params::WebhookSecretCreate,
-        views::WebhookSecretId,
+        views::WebhookSecret,
     >(
         &ctx.external_client,
         &format!("{SECRETS_BASE_PATH}/?receiver={webhook_id}"),

nexus/types/src/external_api/views.rs

@@ -1079,7 +1079,7 @@ pub struct WebhookReceiver {
     pub endpoint: Url,
     // A list containing the IDs of the secret keys used to sign payloads sent
     // to this receiver.
-    pub secrets: Vec<WebhookSecretId>,
+    pub secrets: Vec<WebhookSecret>,
     /// The list of event classes to which this receiver is subscribed.
     pub subscriptions: Vec<shared::WebhookSubscription>,
 }
@@ -1093,13 +1093,21 @@ pub struct WebhookSubscriptionCreated {
 /// A list of the IDs of secrets associated with a webhook.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct WebhookSecrets {
-    pub secrets: Vec<WebhookSecretId>,
+    pub secrets: Vec<WebhookSecret>,
 }
 
-/// The public ID of a secret key assigned to a webhook.
+/// A view of a shared secret key assigned to a webhook receiver.
+///
+/// Once a secret is created, the value of the secret is not available in the
+/// API, as it must remain secret. Instead, secrets are referenced by their
+/// unique IDs assigned when they are created.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, PartialEq)]
-pub struct WebhookSecretId {
+pub struct WebhookSecret {
+    /// The public unique ID of the secret.
     pub id: Uuid,
+
+    /// The UTC timestamp at which this secret was created.
+    pub time_created: DateTime<Utc>,
 }
 
 /// A delivery of a webhook event.

openapi/nexus.json

@@ -12692,7 +12692,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/WebhookSecretId"
+                  "$ref": "#/components/schemas/WebhookSecret"
                 }
               }
             }
@@ -25949,7 +25949,7 @@
           "secrets": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/WebhookSecretId"
+              "$ref": "#/components/schemas/WebhookSecret"
             }
           },
           "subscriptions": {
@@ -26026,29 +26026,36 @@
           }
         }
       },
-      "WebhookSecretCreate": {
+      "WebhookSecret": {
+        "description": "A view of a shared secret key assigned to a webhook receiver.\n\nOnce a secret is created, the value of the secret is not available in the API, as it must remain secret. Instead, secrets are referenced by their unique IDs assigned when they are created.",
         "type": "object",
         "properties": {
-          "secret": {
-            "description": "The value of the shared secret key.",
-            "type": "string"
+          "id": {
+            "description": "The public unique ID of the secret.",
+            "type": "string",
+            "format": "uuid"
+          },
+          "time_created": {
+            "description": "The UTC timestamp at which this secret was created.",
+            "type": "string",
+            "format": "date-time"
           }
         },
         "required": [
-          "secret"
+          "id",
+          "time_created"
         ]
       },
-      "WebhookSecretId": {
-        "description": "The public ID of a secret key assigned to a webhook.",
+      "WebhookSecretCreate": {
         "type": "object",
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid"
+          "secret": {
+            "description": "The value of the shared secret key.",
+            "type": "string"
           }
         },
         "required": [
-          "id"
+          "secret"
         ]
       },
       "WebhookSecrets": {
@@ -26058,7 +26065,7 @@
           "secrets": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/WebhookSecretId"
+              "$ref": "#/components/schemas/WebhookSecret"
             }
           }
         },