feat(agent-tunnel): admin-facing /jet/tunnel/enrollment-string endpoint

Adds the path that DVLS (and any other authenticated admin UI) uses to
bootstrap new agents: POST a JSON body → receive an
`devolutions-agent up --enrollment-string "dgw-enroll:v1:…"` command
ready to paste on the target machine.

- Gateway mints a one-time enrollment token stored server-side, then
  encodes `{ api_base_url, quic_endpoint, enrollment_token, name }`
  into a base64url payload prefixed with `dgw-enroll:v1:`. The agent
  decodes this string and posts the token as a Bearer on
  `/jet/tunnel/enroll`.
- The endpoint derives the QUIC endpoint from the caller-supplied
  api_base_url (operator knows the externally reachable host) falling
  back to conf.hostname. A running gateway cannot self-discover its
  externally reachable address — see `EnrollmentJwtClaims::jet_quic_endpoint`.

Adds two new canonical `AccessScope` variants that callers should
prefer for admin-tunnel operations:

- `AccessScope::AgentEnroll` (serde `gateway.agent.enroll`) — for
  minting enrollment strings and other write operations on the tunnel.
- `AccessScope::AgentRead` (serde `gateway.agent.read`) — for reading
  the connected agents list and status.

`AgentManagementWriteAccess` now accepts `AgentEnroll | ConfigWrite |
Wildcard`; `AgentManagementReadAccess` accepts `AgentRead |
DiagnosticsRead | ConfigWrite | Wildcard`. The broader existing scopes
are retained for back-compat with any caller that predates the
dedicated agent scopes.

Author: irvingoujAtDevolution

devolutions-gateway/src/api/tunnel.rs

@@ -1,6 +1,7 @@
 use axum::extract::{Path, State};
 use axum::http::HeaderMap;
 use axum::{Json, Router};
+use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 
 use crate::DgwState;
@@ -87,6 +88,7 @@ pub struct EnrollResponse {
 pub fn make_router<S>(state: DgwState) -> Router<S> {
     Router::new()
         .route("/enroll", axum::routing::post(enroll_agent))
+        .route("/enrollment-string", axum::routing::post(create_agent_enrollment_string))
         .route("/agents", axum::routing::get(list_agents))
         .route("/agents/{agent_id}", axum::routing::get(get_agent).delete(delete_agent))
         .with_state(state)
@@ -252,6 +254,111 @@ async fn delete_agent(
     Ok(axum::http::StatusCode::NO_CONTENT)
 }
 
+// ---------------------------------------------------------------------------
+// Enrollment string generation (one-time token for agent bootstrap).
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct AgentEnrollmentStringRequest {
+    /// Base URL for the gateway API (e.g. `https://gateway.example.com`).
+    api_base_url: String,
+    /// Optional QUIC host override. Defaults to the host extracted from
+    /// `api_base_url`, falling back to the gateway's configured hostname.
+    quic_host: Option<String>,
+    /// Optional agent name hint.
+    name: Option<String>,
+    /// Token lifetime in seconds (default: 3600).
+    lifetime: Option<u64>,
+}
+
+#[derive(Debug, Serialize)]
+pub(crate) struct AgentEnrollmentStringResponse {
+    enrollment_string: String,
+    enrollment_command: String,
+    quic_endpoint: String,
+    expires_at_unix: u64,
+}
+
+/// Generate a one-time enrollment string for agent bootstrap.
+///
+/// Accepts scope tokens with `AgentEnroll`, `ConfigWrite`, or `Wildcard` scope
+/// via [`AgentManagementWriteAccess`]. DVLS signs scope tokens with
+/// `AgentEnroll` specifically; other callers may use the broader
+/// `ConfigWrite` for back-compat.
+async fn create_agent_enrollment_string(
+    State(DgwState {
+        conf_handle,
+        agent_tunnel_handle,
+        ..
+    }): State<DgwState>,
+    _access: AgentManagementWriteAccess,
+    Json(req): Json<AgentEnrollmentStringRequest>,
+) -> Result<Json<AgentEnrollmentStringResponse>, HttpError> {
+    use base64::Engine as _;
+
+    let conf = conf_handle.get_conf();
+
+    let handle = agent_tunnel_handle
+        .as_ref()
+        .ok_or_else(|| HttpError::not_found().msg("agent tunnel not configured"))?;
+
+    let lifetime_secs = req.lifetime.unwrap_or(3600);
+
+    // Generate a one-time enrollment token stored server-side.
+    let enrollment_token = Uuid::new_v4().to_string();
+    handle
+        .enrollment_token_store()
+        .insert(enrollment_token.clone(), req.name.clone(), Some(lifetime_secs))
+        .await;
+
+    // Determine QUIC host: explicit override > extract from api_base_url > gateway hostname config.
+    // The gateway hostname config is often a container ID in Docker, so we prefer
+    // extracting the host from the api_base_url which the caller already knows is reachable.
+    let quic_host = match req.quic_host.as_deref().filter(|h| !h.is_empty()) {
+        Some(host) => host.to_owned(),
+        None => url::Url::parse(&req.api_base_url)
+            .ok()
+            .and_then(|u| u.host_str().map(ToOwned::to_owned))
+            .unwrap_or_else(|| conf.hostname.clone()),
+    };
+    let quic_endpoint = format!("{quic_host}:{}", conf.agent_tunnel.listen_port);
+
+    // Build the enrollment payload.
+    let payload = serde_json::json!({
+        "version": 1,
+        "api_base_url": req.api_base_url,
+        "quic_endpoint": quic_endpoint,
+        "enrollment_token": enrollment_token,
+        "name": req.name,
+    });
+
+    let payload_json = serde_json::to_string(&payload)
+        .map_err(HttpError::internal().with_msg("serialize enrollment payload").err())?;
+
+    let encoded = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(payload_json.as_bytes());
+    let enrollment_string = format!("dgw-enroll:v1:{encoded}");
+    let enrollment_command = format!("devolutions-agent up --enrollment-string \"{enrollment_string}\"");
+
+    let now_secs = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    let expires_at_unix = now_secs + lifetime_secs;
+
+    info!(
+        agent_name = ?req.name,
+        lifetime_secs,
+        "Generated agent enrollment string"
+    );
+
+    Ok(Json(AgentEnrollmentStringResponse {
+        enrollment_string,
+        enrollment_command,
+        quic_endpoint,
+        expires_at_unix,
+    }))
+}
+
 #[cfg(test)]
 mod tests {
     use picky::jose::jws::JwsAlg;

devolutions-gateway/src/extract.rs

@@ -424,11 +424,16 @@ where
             .map_err(HttpError::internal().err())?
             .0;
 
-        // DiagnosticsRead is accepted because DVLS maps its AgentRead scope
-        // to GatewayDiagnosticsRead, which serializes as "gateway.diagnostics.read".
+        // Accepted scopes:
+        // - AgentRead: the canonical scope for this endpoint (DVLS uses this).
+        // - DiagnosticsRead / ConfigWrite: back-compat for older callers that predate
+        //   the dedicated agent scopes; safe because both imply broader privileges.
         match claims {
             AccessTokenClaims::Scope(scope) => match scope.scope {
-                AccessScope::Wildcard | AccessScope::DiagnosticsRead | AccessScope::ConfigWrite => Ok(Self),
+                AccessScope::Wildcard
+                | AccessScope::AgentRead
+                | AccessScope::DiagnosticsRead
+                | AccessScope::ConfigWrite => Ok(Self),
                 _ => Err(HttpError::forbidden().msg("invalid scope for agent management read")),
             },
             _ => Err(HttpError::forbidden().msg("scope token required for agent management read")),
@@ -438,7 +443,7 @@ where
 
 /// Grants write access to agent management endpoints (e.g. enrollment, delete).
 ///
-/// Accepts scope tokens with `ConfigWrite` (or `Wildcard`) scope only.
+/// Accepts scope tokens with `AgentEnroll`, `ConfigWrite`, or `Wildcard` scope.
 #[derive(Clone, Copy)]
 pub struct AgentManagementWriteAccess;
 
@@ -454,9 +459,13 @@ where
             .map_err(HttpError::internal().err())?
             .0;
 
+        // Accepted scopes:
+        // - AgentEnroll: the canonical scope for this endpoint (DVLS uses this).
+        // - ConfigWrite: back-compat for older callers that predate the
+        //   dedicated agent scope.
         match claims {
             AccessTokenClaims::Scope(scope) => match scope.scope {
-                AccessScope::Wildcard | AccessScope::ConfigWrite => Ok(Self),
+                AccessScope::Wildcard | AccessScope::AgentEnroll | AccessScope::ConfigWrite => Ok(Self),
                 _ => Err(HttpError::forbidden().msg("invalid scope for agent management write")),
             },
             _ => Err(HttpError::forbidden().msg("scope token required for agent management write")),

devolutions-gateway/src/token.rs

@@ -474,6 +474,10 @@ pub enum AccessScope {
     NetMonitorDrain,
     #[serde(rename = "gateway.tunnel.enroll")]
     TunnelEnroll,
+    #[serde(rename = "gateway.agent.enroll")]
+    AgentEnroll,
+    #[serde(rename = "gateway.agent.read")]
+    AgentRead,
 }
 
 #[derive(Clone, Serialize, Deserialize)]