feat(desktop): real-time voice dictation in composer

.env.example

@@ -51,6 +51,14 @@ RELAY_URL=ws://localhost:3000
 # (use `just web` for Vite HMR instead).
 # BUZZ_WEB_DIR=./web/dist
 
+# -----------------------------------------------------------------------------
+# Transcription (dictation)
+# -----------------------------------------------------------------------------
+# OpenAI API key for real-time voice transcription in the composer.
+# When absent, the dictation mic button is hidden.
+# BUZZ_OPENAI_API_KEY=sk-...
+# BUZZ_TRANSCRIPTION_MODEL=whisper-1
+
 # -----------------------------------------------------------------------------
 # Git (NIP-34 bare repositories)
 # -----------------------------------------------------------------------------

crates/buzz-relay/Cargo.toml

@@ -72,6 +72,7 @@ url             = { workspace = true }
 moka            = { workspace = true }
 metrics         = { workspace = true }
 metrics-exporter-prometheus = { workspace = true }
+reqwest         = { workspace = true }
 
 [features]
 dev = ["buzz-auth/dev"]

crates/buzz-relay/src/api/bridge.rs

@@ -25,7 +25,7 @@ use super::{api_error, internal_error, not_found};
 ///
 /// Returns the authenticated public key and an event ID for replay detection.
 /// For X-Pubkey dev mode, the event ID is a zero hash (no replay concern).
-fn verify_bridge_auth(
+pub(crate) fn verify_bridge_auth(
     headers: &HeaderMap,
     method: &str,
     url: &str,
@@ -76,7 +76,7 @@ fn verify_bridge_auth(
 /// `AppState`, not process-local memory. Any Redis/guard error fails closed:
 /// without the shared `SET NX EX` proof, a stateless worker cannot admit the
 /// NIP-98 request safely.
-async fn check_nip98_replay(
+pub(crate) async fn check_nip98_replay(
     state: &AppState,
     tenant: &TenantContext,
     event_id_bytes: [u8; 32],
@@ -135,7 +135,11 @@ async fn check_nip98_replay_with_guard(
 /// pass and the relay would proceed against the wrong tenant's auth context),
 /// and (b) reject every legitimate request whose community host isn't the
 /// single configured one. Substituting `tenant.host()` closes both directions.
-fn nip98_expected_url(config_relay_url: &str, tenant: &TenantContext, path: &str) -> String {
+pub(crate) fn nip98_expected_url(
+    config_relay_url: &str,
+    tenant: &TenantContext,
+    path: &str,
+) -> String {
     let scheme = if config_relay_url.trim_start().starts_with("wss://") {
         "https"
     } else {

crates/buzz-relay/src/api/mod.rs

@@ -1,10 +1,11 @@
-//! HTTP API — media, git, NIP-05, and the Nostr HTTP bridge.
+//! HTTP API — media, git, NIP-05, transcription, and the Nostr HTTP bridge.
 
 pub mod bridge;
 pub mod events;
 pub mod git;
 pub mod media;
 pub mod nip05;
+pub mod transcribe;
 
 // Re-export imeta helpers used by ingest pipeline.
 pub use crate::handlers::imeta::{validate_imeta_tags, verify_imeta_blobs};

crates/buzz-relay/src/api/transcribe.rs

@@ -0,0 +1,244 @@
+//! Transcription session endpoint — proxies OpenAI Realtime API client-secret minting.
+//!
+//! When `BUZZ_OPENAI_API_KEY` is configured, the relay can mint ephemeral client
+//! secrets for the OpenAI Realtime API. The desktop app uses these to establish a
+//! WebRTC connection for real-time speech-to-text dictation.
+//!
+//! Both endpoints require NIP-98 auth (same as `/events`, `/query`, `/count`).
+
+use std::sync::Arc;
+
+use axum::{
+    extract::State,
+    http::{HeaderMap, StatusCode},
+    response::Json,
+};
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::state::AppState;
+
+use super::api_error;
+
+const OPENAI_REALTIME_CLIENT_SECRETS_URL: &str =
+    "https://api.openai.com/v1/realtime/client_secrets";
+const DEFAULT_TRANSCRIPTION_MODEL: &str = "whisper-1";
+
+/// Response for `GET /transcribe/status`.
+#[derive(Serialize)]
+pub struct TranscribeStatus {
+    configured: bool,
+    model: String,
+}
+
+/// Response for `POST /transcribe/session`.
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TranscribeSession {
+    client_secret: String,
+    model: String,
+}
+
+/// `GET /transcribe/status` — check if transcription is configured.
+///
+/// Requires NIP-98 auth. Returns whether the relay has an OpenAI API key
+/// configured for real-time transcription.
+pub async fn transcribe_status(
+    State(state): State<Arc<AppState>>,
+    headers: HeaderMap,
+) -> Result<Json<TranscribeStatus>, (StatusCode, Json<Value>)> {
+    authenticate(&state, &headers, "/transcribe/status", "GET").await?;
+
+    Ok(Json(TranscribeStatus {
+        configured: state.config.openai_api_key.is_some(),
+        model: transcription_model(),
+    }))
+}
+
+/// `POST /transcribe/session` — create an ephemeral OpenAI Realtime session.
+///
+/// Requires NIP-98 auth. Returns a short-lived client secret that the frontend
+/// uses to establish a WebRTC connection directly with OpenAI for real-time
+/// transcription.
+pub async fn create_transcribe_session(
+    State(state): State<Arc<AppState>>,
+    headers: HeaderMap,
+) -> Result<Json<TranscribeSession>, (StatusCode, Json<Value>)> {
+    authenticate(&state, &headers, "/transcribe/session", "POST").await?;
+
+    let api_key = state.config.openai_api_key.as_deref().ok_or_else(|| {
+        api_error(
+            StatusCode::SERVICE_UNAVAILABLE,
+            "transcription is not configured on this relay",
+        )
+    })?;
+
+    let model = transcription_model();
+
+    let client = reqwest::Client::new();
+    let response = client
+        .post(OPENAI_REALTIME_CLIENT_SECRETS_URL)
+        .header("Authorization", format!("Bearer {api_key}"))
+        .header("Content-Type", "application/json")
+        .json(&serde_json::json!({
+            "session": {
+                "type": "transcription",
+                "audio": {
+                    "input": {
+                        "transcription": {
+                            "model": model,
+                        },
+                        "turn_detection": {
+                            "type": "server_vad",
+                        }
+                    }
+                }
+            }
+        }))
+        .timeout(std::time::Duration::from_secs(10))
+        .send()
+        .await
+        .map_err(|e| {
+            tracing::error!("OpenAI realtime session request failed: {e}");
+            api_error(
+                StatusCode::BAD_GATEWAY,
+                "failed to create transcription session",
+            )
+        })?;
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        tracing::error!("OpenAI realtime session error ({status}): {body}");
+        return Err(api_error(
+            StatusCode::BAD_GATEWAY,
+            "OpenAI rejected the transcription session request",
+        ));
+    }
+
+    let body: Value = response.json().await.map_err(|e| {
+        tracing::error!("OpenAI realtime session response parse error: {e}");
+        api_error(
+            StatusCode::BAD_GATEWAY,
+            "invalid response from transcription service",
+        )
+    })?;
+
+    let client_secret = extract_client_secret(&body).ok_or_else(|| {
+        tracing::error!("OpenAI realtime session response missing client_secret: {body}");
+        api_error(
+            StatusCode::BAD_GATEWAY,
+            "transcription service returned unexpected response",
+        )
+    })?;
+
+    Ok(Json(TranscribeSession {
+        client_secret,
+        model,
+    }))
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/// Authenticate the request using the same NIP-98 / X-Pubkey pattern as the
+/// bridge endpoints, plus replay detection and relay membership enforcement.
+async fn authenticate(
+    state: &AppState,
+    headers: &HeaderMap,
+    path: &str,
+    method: &str,
+) -> Result<(), (StatusCode, Json<Value>)> {
+    let raw_host = headers
+        .get("host")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("");
+    let tenant = crate::tenant::bind_community(&state.db, raw_host)
+        .await
+        .map_err(|_| {
+            api_error(
+                StatusCode::NOT_FOUND,
+                "relay: no community is configured for this host",
+            )
+        })?;
+
+    let url = super::bridge::nip98_expected_url(&state.config.relay_url, &tenant, path);
+    let (pubkey, event_id_bytes) = super::bridge::verify_bridge_auth(
+        headers,
+        method,
+        &url,
+        None,
+        state.config.require_auth_token,
+    )?;
+    super::bridge::check_nip98_replay(state, &tenant, event_id_bytes).await?;
+
+    // Enforce relay membership (with NIP-OA fallback via x-auth-tag header).
+    let pubkey_bytes = pubkey.to_bytes().to_vec();
+    let auth_tag = headers.get("x-auth-tag").and_then(|v| v.to_str().ok());
+    super::relay_members::enforce_relay_membership(
+        state,
+        tenant.community(),
+        &pubkey_bytes,
+        auth_tag,
+    )
+    .await?;
+
+    Ok(())
+}
+
+fn transcription_model() -> String {
+    std::env::var("BUZZ_TRANSCRIPTION_MODEL")
+        .ok()
+        .filter(|s| !s.is_empty())
+        .unwrap_or_else(|| DEFAULT_TRANSCRIPTION_MODEL.to_string())
+}
+
+fn extract_client_secret(value: &Value) -> Option<String> {
+    // Shape 1: { "client_secret": { "value": "..." } }
+    if let Some(cs) = value.get("client_secret") {
+        if let Some(v) = cs.get("value").and_then(|v| v.as_str()) {
+            return Some(v.to_string());
+        }
+        // Shape 2: { "client_secret": "..." }
+        if let Some(v) = cs.as_str() {
+            return Some(v.to_string());
+        }
+    }
+    // Shape 3: { "value": "..." }
+    value
+        .get("value")
+        .and_then(|v| v.as_str())
+        .map(String::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::extract_client_secret;
+    use serde_json::json;
+
+    #[test]
+    fn parses_nested_client_secret() {
+        let body = json!({ "client_secret": { "value": "sec_abc123", "expires_at": 9999 } });
+        assert_eq!(extract_client_secret(&body), Some("sec_abc123".to_string()));
+    }
+
+    #[test]
+    fn parses_direct_string_client_secret() {
+        let body = json!({ "client_secret": "sec_direct" });
+        assert_eq!(extract_client_secret(&body), Some("sec_direct".to_string()));
+    }
+
+    #[test]
+    fn parses_top_level_value() {
+        let body = json!({ "value": "sec_toplevel" });
+        assert_eq!(
+            extract_client_secret(&body),
+            Some("sec_toplevel".to_string())
+        );
+    }
+
+    #[test]
+    fn returns_none_for_missing_secret() {
+        let body = json!({ "id": "sess_123", "model": "gpt-4o" });
+        assert_eq!(extract_client_secret(&body), None);
+    }
+}

crates/buzz-relay/src/config.rs

@@ -152,6 +152,11 @@ pub struct Config {
     /// Used to authenticate internal policy endpoint requests.
     pub git_hook_hmac_secret: String,
 
+    /// Optional OpenAI API key for real-time transcription (dictation).
+    /// When absent, the `/transcribe/session` endpoint returns 503 and the
+    /// desktop mic button stays hidden.
+    pub openai_api_key: Option<String>,
+
     /// Optional path to the web UI `dist/` directory.
     /// When set, the relay serves the SPA from this directory for browser requests.
     /// When unset, no static file serving happens (relay behaves as before).
@@ -184,7 +189,7 @@ impl Config {
         let bind_addr = parse_bind_addr(&bind_addr_raw)?;
 
         let database_url = std::env::var("DATABASE_URL")
-            .unwrap_or_else(|_| "postgres://buzz:buzz_dev@localhost:5432/buzz".to_string());
+            .unwrap_or_else(|_| "postgres://buzz:buzz_dev@localhost:5432/buzz".to_string()); // sadscan:disable np.postgres.1
 
         let redis_url =
             std::env::var("REDIS_URL").unwrap_or_else(|_| "redis://localhost:6379".to_string());
@@ -380,6 +385,11 @@ impl Config {
                 let secret: [u8; 32] = rand::random();
                 hex::encode(secret)
             });
+        let openai_api_key = std::env::var("BUZZ_OPENAI_API_KEY")
+            .ok()
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty());
+
         // Web UI static file serving
         let web_dir = std::env::var("BUZZ_WEB_DIR")
             .ok()
@@ -440,6 +450,7 @@ impl Config {
             git_max_repos_per_pubkey,
             git_max_concurrent_ops,
             git_hook_hmac_secret,
+            openai_api_key,
             web_dir,
         })
     }

crates/buzz-relay/src/router.rs

@@ -62,6 +62,15 @@ pub fn build_router(state: Arc<AppState>) -> Router {
         .route("/count", post(api::bridge::count_events))
         // Webhook trigger (secret-authenticated, no NIP-98)
         .route("/hooks/{id}", post(api::bridge::workflow_webhook))
+        // Transcription (dictation) — proxies OpenAI Realtime client-secret minting
+        .route(
+            "/transcribe/status",
+            get(api::transcribe::transcribe_status),
+        )
+        .route(
+            "/transcribe/session",
+            post(api::transcribe::create_transcribe_session),
+        )
         // Huddle audio WebSocket route
         .route(
             "/huddle/{channel_id}/audio",
@@ -93,6 +102,7 @@ pub fn build_router(state: Arc<AppState>) -> Router {
                         || path.starts_with("/internal/")
                         || path.starts_with("/.well-known/")
                         || path.starts_with("/huddle/")
+                        || path.starts_with("/transcribe/")
                         || path == "/health"
                         || path == "/_liveness"
                         || path == "/_readiness"