feat(databases run): child ApiClient consumes HOTDATA_DATABASE_TOKEN + refreshes near expiry

Author: pthurlow

src/api.rs

@@ -50,20 +50,33 @@ impl ApiClient {
 
         // Auth source precedence:
         //
-        // 1. `HOTDATA_SANDBOX_TOKEN` env var — a `sandbox run` child
+        // 1. `HOTDATA_DATABASE_TOKEN` env var — a `databases run` child
+        //    is executing with the parent's credentials scrubbed and a
+        //    database-scoped JWT injected. Refresh in-memory via
+        //    `HOTDATA_DATABASE_REFRESH_TOKEN` near expiry; never write
+        //    to disk (the child's FS may not be writable).
+        // 2. `HOTDATA_SANDBOX_TOKEN` env var — a `sandbox run` child
         //    is executing with the parent's credentials scrubbed.
         //    Refresh in-memory via `HOTDATA_SANDBOX_REFRESH_TOKEN` if
         //    the JWT is close to expiry; never write to disk (the
         //    child's FS may not be writable).
-        // 2. `~/.hotdata/sandbox_session.json` — the user ran
+        // 3. `~/.hotdata/sandbox_session.json` — the user ran
         //    `hotdata sandbox set <id>` (or `sandbox new` / `sandbox
         //    run` in the parent shell). The sandbox JWT is the active
         //    bearer for *every* command until `sandbox set` (with no
         //    id) clears the file.
-        // 3. `~/.hotdata/session.json` + optional api_key fallback —
+        // 4. `~/.hotdata/session.json` + optional api_key fallback —
         //    normal user-scoped CLI session.
         let api_url = profile_config.api_url.to_string();
-        let access_token = if std::env::var("HOTDATA_SANDBOX_TOKEN").is_ok() {
+        let access_token = if std::env::var("HOTDATA_DATABASE_TOKEN").is_ok() {
+            match crate::database_session::refresh_from_env(&api_url) {
+                Some(t) => t,
+                None => {
+                    eprintln!("{}", "error: HOTDATA_DATABASE_TOKEN is empty".red());
+                    std::process::exit(1);
+                }
+            }
+        } else if std::env::var("HOTDATA_SANDBOX_TOKEN").is_ok() {
             match crate::sandbox_session::refresh_from_env(&api_url) {
                 Some(t) => t,
                 None => {
@@ -118,7 +131,9 @@ impl ApiClient {
                 }
                 profile_config.sandbox
             }),
-            database_id: workspace_id.and_then(|ws| crate::config::load_current_database("default", ws)),
+            database_id: std::env::var("HOTDATA_DATABASE").ok().or_else(|| {
+                workspace_id.and_then(|ws| crate::config::load_current_database("default", ws))
+            }),
         }
     }
 

src/database_session.rs

@@ -16,13 +16,7 @@ use std::io::Write;
 use std::path::PathBuf;
 use std::time::{SystemTime, UNIX_EPOCH};
 
-// The refresh path below (REFRESH_LEEWAY_SECONDS, now_unix, MintResponse,
-// redact, refresh, session_from_response) mirrors sandbox_session.rs and is
-// covered by tests, but has no production caller yet: it's reserved for when
-// a child of `databases run` re-mints an expiring HOTDATA_DATABASE_TOKEN
-// (the child-side ApiClient consumption is not wired up yet). Annotated
-// #[allow(dead_code)] until that lands so the build stays warning-clean.
-#[allow(dead_code)]
+/// Refresh ahead of expiry to avoid racing it.
 const REFRESH_LEEWAY_SECONDS: u64 = 60;
 
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
@@ -74,15 +68,13 @@ pub fn clear() {
     }
 }
 
-#[allow(dead_code)] // Part of the reserved refresh path (see REFRESH_LEEWAY_SECONDS).
 fn now_unix() -> u64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .map(|d| d.as_secs())
         .unwrap_or(0)
 }
 
-#[allow(dead_code)] // Part of the reserved refresh path (see REFRESH_LEEWAY_SECONDS).
 #[derive(Deserialize)]
 pub(crate) struct MintResponse {
     token: String,
@@ -92,15 +84,13 @@ pub(crate) struct MintResponse {
     refresh_expires_in: u64,
 }
 
-#[allow(dead_code)] // Part of the reserved refresh path (see REFRESH_LEEWAY_SECONDS).
 fn redact(s: &str) -> String {
     util::mask_credential(s)
 }
 
 /// Trade a refresh token for a fresh database JWT (no rotation). Same
 /// endpoint as the new-mint path: `POST /v1/auth/database` with
 /// grant_type=refresh_token.
-#[allow(dead_code)] // Part of the reserved refresh path (see REFRESH_LEEWAY_SECONDS).
 pub fn refresh(api_url: &str, refresh_token: &str) -> Result<DatabaseSession, String> {
     let url = format!("{}/auth/database", api_url.trim_end_matches('/'));
     let body = serde_json::json!({
@@ -135,7 +125,6 @@ pub fn refresh(api_url: &str, refresh_token: &str) -> Result<DatabaseSession, St
 /// to). For refresh, `workspace_id` is left blank — the caller fills it
 /// from the prior session, since the database-id ↔ workspace mapping is
 /// invariant across refreshes.
-#[allow(dead_code)] // Part of the reserved refresh path (see REFRESH_LEEWAY_SECONDS).
 pub(crate) fn session_from_response(resp: MintResponse, workspace_id: String) -> DatabaseSession {
     let now = now_unix();
     DatabaseSession {
@@ -148,6 +137,81 @@ pub(crate) fn session_from_response(resp: MintResponse, workspace_id: String) ->
     }
 }
 
+/// Decode a JWT's payload (without verifying the signature) and pull
+/// out the named string claim. Returns `None` if the token is
+/// unparseable or the claim is missing.
+fn jwt_string_claim(token: &str, claim: &str) -> Option<String> {
+    use base64::Engine;
+    let parts: Vec<&str> = token.split('.').collect();
+    if parts.len() < 2 {
+        return None;
+    }
+    let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(parts[1].as_bytes())
+        .ok()?;
+    let value: serde_json::Value = serde_json::from_slice(&payload).ok()?;
+    value.get(claim).and_then(|v| v.as_str()).map(String::from)
+}
+
+/// Decode the `exp` claim out of a JWT without verifying the signature.
+/// Returns `None` if the token is unparseable; in that case the caller
+/// should treat it as expired (force-refresh or fail).
+fn jwt_exp(token: &str) -> Option<u64> {
+    use base64::Engine;
+    let parts: Vec<&str> = token.split('.').collect();
+    if parts.len() < 2 {
+        return None;
+    }
+    let payload = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(parts[1].as_bytes())
+        .ok()?;
+    let value: serde_json::Value = serde_json::from_slice(&payload).ok()?;
+    value.get("exp").and_then(|v| v.as_u64())
+}
+
+/// If `HOTDATA_DATABASE_TOKEN` is set in the environment, return
+/// `(token, database_id)` — the database id read from the JWT's
+/// `database` claim. Returns `None` if no env var is set, or if the
+/// token isn't a parseable JWT (in which case we can still use it as
+/// a bearer but can't identify the database).
+pub fn database_token_in_use() -> Option<(String, Option<String>)> {
+    let token = std::env::var("HOTDATA_DATABASE_TOKEN").ok()?;
+    if token.is_empty() {
+        return None;
+    }
+    let database_id = jwt_string_claim(&token, "database");
+    Some((token, database_id))
+}
+
+/// In-child equivalent of a parent-side `ensure_access_token`: operates
+/// on env vars only. Used by [`crate::api::ApiClient`] when the parent
+/// `databases run` already passed in `HOTDATA_DATABASE_TOKEN` and
+/// `HOTDATA_DATABASE_REFRESH_TOKEN`. The new tokens are *not* persisted
+/// to disk — the child may not have write access to the parent's
+/// config dir (sandboxed FS), and re-doing the refresh on the next
+/// invocation costs one HTTP call.
+///
+/// Falls back to the current `HOTDATA_DATABASE_TOKEN` value if a
+/// refresh isn't needed or fails.
+pub fn refresh_from_env(api_url: &str) -> Option<String> {
+    let current = std::env::var("HOTDATA_DATABASE_TOKEN").ok()?;
+    let needs_refresh = match jwt_exp(&current) {
+        Some(exp) => exp.saturating_sub(REFRESH_LEEWAY_SECONDS) <= now_unix(),
+        None => true,
+    };
+    if !needs_refresh {
+        return Some(current);
+    }
+    let rt = std::env::var("HOTDATA_DATABASE_REFRESH_TOKEN").ok()?;
+    if rt.is_empty() {
+        return Some(current);
+    }
+    match refresh(api_url, &rt) {
+        Ok(new_session) => Some(new_session.access_token),
+        Err(_) => Some(current),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/main.rs

@@ -136,6 +136,11 @@ extern "C" fn print_sandbox_footer() {
 
 extern "C" fn print_database_footer() {
     use crossterm::style::Stylize;
+    // Inside a `databases run` child the parent already announced the
+    // database at spawn; mirror sandbox's footer suppression.
+    if database_session::database_token_in_use().is_some() {
+        return;
+    }
     if let Some(ws_id) = ACTIVE_WORKSPACE_ID.get() {
         if let Some(id) = config::load_current_database("default", ws_id) {
             eprintln!(