feat: unify recommend anonymous runtime guest auth

- Route recommended runtime launches through shared runtime guest token handling
- Extend recommend-page anonymous play beyond jump-hop
- Add regression coverage for runtime guest launch clients
- Update docs to reflect the full anonymous-play matrix

server-rs/crates/api-server/src/jump_hop.rs

@@ -24,7 +24,7 @@ use std::{collections::BTreeMap, time::{SystemTime, UNIX_EPOCH}};
 
 use crate::{
     api_response::json_success_body,
-    auth::AuthenticatedAccessToken,
+    auth::{AuthenticatedAccessToken, RuntimePrincipal},
     http_error::AppError,
     generated_asset_sheets::{
         GeneratedAssetSheetPromptInput, build_generated_asset_sheet_prompt,
@@ -51,7 +51,6 @@ const JUMP_HOP_CREATION_PROVIDER: &str = "jump-hop-creation";
 const JUMP_HOP_RUNTIME_PROVIDER: &str = "jump-hop-runtime";
 const JUMP_HOP_TEMPLATE_ID: &str = "jump-hop";
 const JUMP_HOP_TEMPLATE_NAME: &str = "跳一跳";
-const JUMP_HOP_ANONYMOUS_RUNTIME_OWNER_ID: &str = "anonymous-runtime";
 const JUMP_HOP_RUNTIME_RUNS_ROUTE: &str = "/api/runtime/jump-hop/runs";
 
 pub async fn create_jump_hop_session(
@@ -231,15 +230,13 @@ pub async fn get_jump_hop_runtime_work(
 pub async fn start_jump_hop_run(
     State(state): State<AppState>,
     Extension(request_context): Extension<RequestContext>,
-    maybe_authenticated: Option<Extension<AuthenticatedAccessToken>>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<JumpHopStartRunRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = jump_hop_json(payload, &request_context, JUMP_HOP_RUNTIME_PROVIDER)?;
     ensure_non_empty(&request_context, &payload.profile_id, "profileId")?;
-    let authenticated = maybe_authenticated.as_ref().map(|Extension(authenticated)| authenticated);
-    let owner_user_id = authenticated
-        .map(|authenticated| authenticated.claims().user_id().to_string())
-        .unwrap_or_else(|| JUMP_HOP_ANONYMOUS_RUNTIME_OWNER_ID.to_string());
+    let owner_user_id = principal.subject().to_string();
+    let principal_kind = principal.kind().as_str();
     let run = state
         .spacetime_client()
         .start_jump_hop_run(payload, owner_user_id.clone())
@@ -256,7 +253,7 @@ pub async fn start_jump_hop_run(
         &state,
         &request_context,
         build_jump_hop_work_play_tracking_draft(
-            authenticated,
+            &principal,
             run.profile_id.clone(),
             JUMP_HOP_RUNTIME_RUNS_ROUTE,
         )
@@ -265,7 +262,7 @@ pub async fn start_jump_hop_run(
         .profile_id(run.profile_id.clone())
         .extra(json!({
             "runStatus": run.status,
-            "isAnonymous": maybe_authenticated.is_none(),
+            "principalKind": principal_kind,
         })),
     )
     .await;
@@ -280,15 +277,12 @@ pub async fn jump_hop_run_jump(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    maybe_authenticated: Option<Extension<AuthenticatedAccessToken>>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<JumpHopJumpRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &run_id, "runId")?;
     let Json(payload) = jump_hop_json(payload, &request_context, JUMP_HOP_RUNTIME_PROVIDER)?;
-    let owner_user_id = maybe_authenticated
-        .as_ref()
-        .map(|Extension(authenticated)| authenticated.claims().user_id().to_string())
-        .unwrap_or_else(|| JUMP_HOP_ANONYMOUS_RUNTIME_OWNER_ID.to_string());
+    let owner_user_id = principal.subject().to_string();
     let run = state
         .spacetime_client()
         .jump_hop_run_jump(run_id, owner_user_id, payload)
@@ -311,15 +305,12 @@ pub async fn restart_jump_hop_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    maybe_authenticated: Option<Extension<AuthenticatedAccessToken>>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<JumpHopRestartRunRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &run_id, "runId")?;
     let Json(payload) = jump_hop_json(payload, &request_context, JUMP_HOP_RUNTIME_PROVIDER)?;
-    let owner_user_id = maybe_authenticated
-        .as_ref()
-        .map(|Extension(authenticated)| authenticated.claims().user_id().to_string())
-        .unwrap_or_else(|| JUMP_HOP_ANONYMOUS_RUNTIME_OWNER_ID.to_string());
+    let owner_user_id = principal.subject().to_string();
     let run = state
         .spacetime_client()
         .restart_jump_hop_run(run_id, owner_user_id, payload)
@@ -711,16 +702,11 @@ async fn persist_jump_hop_generated_image_asset(
 }
 
 fn build_jump_hop_work_play_tracking_draft(
-    authenticated: Option<&AuthenticatedAccessToken>,
+    principal: &RuntimePrincipal,
     work_id: impl Into<String>,
     source_route: &'static str,
 ) -> WorkPlayTrackingDraft {
-    match authenticated {
-        Some(authenticated) => {
-            WorkPlayTrackingDraft::new("jump-hop", work_id, authenticated, source_route)
-        }
-        None => WorkPlayTrackingDraft::anonymous("jump-hop", work_id, source_route),
-    }
+    WorkPlayTrackingDraft::runtime_principal("jump-hop", work_id, principal, source_route)
 }