mj_controller/
server.rs

1//! Daemon-owned, phone-oriented control surface for Hel.
2//!
3//! The server deliberately owns no controller business logic. It publishes a
4//! redacted projection of controller state and forwards validated, typed
5//! actions through a channel supplied by the controller.
6
7use std::collections::BTreeMap;
8use std::convert::Infallible;
9use std::net::SocketAddr;
10use std::path::{Component, PathBuf};
11use std::sync::{Arc, Mutex};
12use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
13
14use anyhow::{Context, Result as AnyResult};
15use axum::body::{Body, Bytes, to_bytes};
16use axum::extract::{DefaultBodyLimit, Path, Query, Request, State};
17use axum::http::header::{
18    CACHE_CONTROL, CONTENT_SECURITY_POLICY as CONTENT_SECURITY_POLICY_HEADER, CONTENT_TYPE, COOKIE,
19    HeaderValue, LOCATION, REFERRER_POLICY, SET_COOKIE, X_CONTENT_TYPE_OPTIONS,
20};
21use axum::http::{HeaderMap, Response, StatusCode};
22use axum::middleware::Next;
23use axum::response::IntoResponse;
24use axum::response::sse::{Event, KeepAlive, Sse};
25use axum::routing::{get, post, put};
26use axum::{Json, Router};
27use base64::Engine as _;
28use hmac::{Hmac, KeyInit, Mac};
29use serde::{Deserialize, Serialize};
30use sha2::Sha256;
31use tokio::sync::Semaphore;
32use tokio::sync::{mpsc, watch};
33use tokio_stream::wrappers::ReceiverStream;
34use tokio_util::sync::CancellationToken;
35
36use mj_core::attachment::{AttachmentRef, AttachmentStore, MAX_IMAGE_BYTES, MAX_IMAGES};
37use mj_core::config::{Config, TargetTemplate, project_history_host, validate_id};
38use mj_core::elicitation::{ElicitationRequest, ElicitationResponse, MAX_ELICITATION_BYTES};
39use mj_core::path_completion::{CompletionHost, CompletionKind, PathCompletion};
40use mj_core::refusal::{Refusal, RefusalKind};
41use mj_core::state::{
42    MoveOperation, MovePhase, MovePreparation, MoveSelection, MoveSessionRequest,
43    ProjectSourceIdentity, SessionResourceAllocation, SessionState, SessionTransitionKind,
44    State as AppState,
45};
46
47use crate::targets::AdditionalMount;
48
49use crate::dictation::{
50    DictationError, DictationOperation, DictationRequest, DictationResponse, MAX_AUDIO_BYTES,
51    validate_wav,
52};
53use crate::image::optimize_image;
54
55pub mod api;
56
57pub use api::{
58    ApiFailure, ApiSession, PromptRequest, PromptResponse, SessionListResponse,
59    StartSessionRequest, StartSessionResponse, SubagentBackend, WaitOutcome, WaitRequest,
60    WaitResponse, api_token_path, load_or_create_api_token, map_stop_reason, resolve_wait,
61};
62
63pub use mj_client::web::{
64    BrowserDiffStat, BrowserTranscript, BrowserTranscriptEntry, WebListenerProcess,
65    WebViewerAccess, WebViewerRecovery,
66};
67
68// Keep all control surfaces on the same queue vocabulary. The resume flow
69// used to define a private copy here, which made a move request impossible to
70// pass through the web and daemon boundaries without lossy conversion.
71pub use mj_core::state::ResumeQueueDisposition;
72
73/// Select the process-wide rustls provider before any TLS configuration is built.
74///
75/// Dependency feature unification can enable both rustls providers. Rustls
76/// deliberately refuses to guess in that case, so each executable that links
77/// the controller installs the ring provider at process startup. A provider
78/// installed even earlier is already sufficient and remains in place.
79pub fn install_rustls_crypto_provider() {
80    let _ = rustls::crypto::ring::default_provider().install_default();
81}
82
83pub const COOKIE_NAME: &str = "hel_viewer_session";
84const DEFAULT_SESSION_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
85const EPHEMERAL_SESSION_TTL: Duration = Duration::from_secs(24 * 60 * 60);
86const MAX_BODY_BYTES: usize = 128 * 1024;
87const MAX_CODE_FAILURES: u32 = 5;
88const CODE_LOCKOUT_BASE: Duration = Duration::from_secs(30);
89const CODE_LOCKOUT_CAP: Duration = Duration::from_secs(60 * 60);
90const MAX_TITLE_CHARS: usize = 120;
91const MAX_PROMPT_CHARS: usize = 64 * 1024;
92/// How many repositories one dirty-worktree acknowledgement may name. A bundle
93/// with more repositories than this than has bigger problems than the phone.
94const MAX_DIRTY_ACKNOWLEDGEMENTS: usize = 32;
95/// The largest draft a phone may store. A composer is for a prompt, and a
96/// prompt this size has other problems; the bound exists so one viewer cannot
97/// fill the daemon's database with text it never sent.
98const MAX_DRAFT_BYTES: usize = 64 * 1024;
99/// How many prompt-history matches one search returns. Public because the
100/// controller loop performs the search and must use the same bound the phone
101/// was promised.
102pub const MAX_HISTORY_MATCHES: usize = 40;
103/// Image prompts need far more room than any other phone request. Browser
104/// uploads are base64-encoded, so two ordinary photographs already exceed the
105/// general body limit even when each one fits it. The larger bound therefore
106/// stays scoped to the action route that carries prompts.
107const MAX_PROMPT_BODY_BYTES: usize = 32 * 1024 * 1024;
108/// A browser uploads one source image at a time. The image optimizer has its
109/// own decoded-allocation bound; this is the HTTP envelope bound before that
110/// work starts.
111const MAX_ATTACHMENT_UPLOAD_BYTES: usize = 64 * 1024 * 1024;
112/// Keep two browser uploads/transcriptions in flight. The permit is acquired
113/// before reading the request body, so an overloaded client is rejected
114/// without accepting megabytes that cannot be processed yet.
115const MAX_CONCURRENT_DICTATIONS: usize = 2;
116/// Keep this in sync with the prompt admission bound and the browser composer.
117pub const MAX_PROMPT_IMAGES: usize = MAX_IMAGES;
118const COOKIE_KEY_BYTES: usize = 32;
119const COOKIE_KEY_FILE: &str = "phone-cookie-key";
120
121/// How long stored viewer state outlives its last use.
122///
123/// It matches the session cookie's own lifetime: state keyed to an identity
124/// that can no longer authenticate has nothing left to belong to.
125pub const fn default_session_ttl() -> Duration {
126    DEFAULT_SESSION_TTL
127}
128
129pub fn cookie_key_path() -> PathBuf {
130    mj_core::config::data_dir().join(COOKIE_KEY_FILE)
131}
132
133/// Load the phone cookie signing key, creating it on first use.
134///
135/// Session cookies are stateless, so this file is the only thing that keeps a
136/// signed-in phone signed in across daemon restarts. Deleting it is
137/// therefore the explicit sign-everyone-out gesture: the next start writes a
138/// new key and every outstanding cookie stops validating. A missing file is
139/// ordinary first use; an unreadable or too-short one is replaced loudly,
140/// because refusing to start would be a worse answer than asking phones to
141/// enter the viewer code again.
142pub fn load_or_create_cookie_key(path: &std::path::Path) -> AnyResult<Vec<u8>> {
143    match std::fs::read(path) {
144        Ok(key) if key.len() >= COOKIE_KEY_BYTES => return Ok(key),
145        Ok(key) => tracing::warn!(
146            path = %path.display(),
147            bytes = key.len(),
148            "phone cookie key is shorter than {COOKIE_KEY_BYTES} bytes; generating a new key signs every phone out"
149        ),
150        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
151        Err(error) => tracing::warn!(
152            path = %path.display(),
153            "could not read the phone cookie key ({error}); generating a new key signs every phone out"
154        ),
155    }
156    let key = generate_cookie_key()?;
157    mj_core::config::atomic_write(path, &key)
158        .with_context(|| format!("persist Mjolnir phone cookie key {}", path.display()))?;
159    Ok(key.to_vec())
160}
161
162/// Options for the daemon's phone service.
163///
164/// `ServerOptions::new` generates both the six-digit viewer code and an
165/// ephemeral cookie key. A caller that wants cookies to survive server
166/// restarts installs a persisted key with `set_cookie_key`, which
167/// `load_or_create_cookie_key` reads from its private Hel data directory. The
168/// key and viewer code are intentionally omitted from `Debug` output.
169#[derive(Clone)]
170pub struct ServerOptions {
171    pub bind: SocketAddr,
172    pub snapshot_rx: watch::Receiver<ViewerSnapshot>,
173    pub conversation_rx: watch::Receiver<BTreeMap<String, BrowserTranscript>>,
174    pub action_tx: mpsc::Sender<ControllerRequest>,
175    pub bundle_tx: mpsc::Sender<BundleRequest>,
176    pub receipt_tx: mpsc::Sender<ReadReceiptRequest>,
177    pub preflight_tx: mpsc::Sender<PreflightRequest>,
178    pub move_preparation_tx: mpsc::Sender<MovePreparationRequest>,
179    pub client_state_tx: mpsc::Sender<ClientStateRequest>,
180    pub dictation_tx: mpsc::Sender<DictationRequest>,
181    /// Dedicated bounded path for stopping one live background task. This is
182    /// deliberately separate from [`ControllerAction`]: stopping a provider
183    /// task does not occupy the controller's action admission slot.
184    background_task_stop_tx: mpsc::Sender<BackgroundTaskStopRequest>,
185    pub shutdown: CancellationToken,
186    pub session_ttl: Duration,
187    /// Keep this enabled for direct HTTPS or an HTTPS reverse proxy. It may be
188    /// disabled only for an explicitly trusted HTTP development endpoint.
189    pub secure_cookie: bool,
190    tls_config: Option<axum_server::tls_rustls::RustlsConfig>,
191    viewer_code: String,
192    login_token: String,
193    cookie_key: Vec<u8>,
194    api_token: String,
195    subagent: Option<Arc<dyn api::SubagentBackend>>,
196}
197
198/// Typed request channels served by the authenticated HTTP surface.
199pub struct ServerRequests {
200    pub action_tx: mpsc::Sender<ControllerRequest>,
201    pub bundle_tx: mpsc::Sender<BundleRequest>,
202    pub receipt_tx: mpsc::Sender<ReadReceiptRequest>,
203    pub preflight_tx: mpsc::Sender<PreflightRequest>,
204    pub move_preparation_tx: mpsc::Sender<MovePreparationRequest>,
205    pub client_state_tx: mpsc::Sender<ClientStateRequest>,
206    pub dictation_tx: mpsc::Sender<DictationRequest>,
207}
208
209impl ServerOptions {
210    pub fn new(
211        bind: SocketAddr,
212        snapshot_rx: watch::Receiver<ViewerSnapshot>,
213        conversation_rx: watch::Receiver<BTreeMap<String, BrowserTranscript>>,
214        requests: ServerRequests,
215    ) -> AnyResult<Self> {
216        Ok(Self {
217            bind,
218            snapshot_rx,
219            conversation_rx,
220            action_tx: requests.action_tx,
221            bundle_tx: requests.bundle_tx,
222            receipt_tx: requests.receipt_tx,
223            preflight_tx: requests.preflight_tx,
224            move_preparation_tx: requests.move_preparation_tx,
225            client_state_tx: requests.client_state_tx,
226            dictation_tx: requests.dictation_tx,
227            background_task_stop_tx: mpsc::channel(1).0,
228            shutdown: CancellationToken::new(),
229            session_ttl: DEFAULT_SESSION_TTL,
230            secure_cookie: true,
231            tls_config: None,
232            viewer_code: generate_viewer_code()?,
233            login_token: generate_login_token()?,
234            cookie_key: generate_cookie_key()?.to_vec(),
235            // An empty token authenticates nothing: the daemon installs the
236            // persisted one, and a server without it serves the viewer only.
237            api_token: String::new(),
238            subagent: None,
239        })
240    }
241
242    pub fn viewer_code(&self) -> &str {
243        &self.viewer_code
244    }
245
246    pub fn login_token(&self) -> &str {
247        &self.login_token
248    }
249
250    /// Serve HTTPS directly using the supplied Rustls configuration. Hel's
251    /// CLI can load its persisted certificate (including a Tailscale-issued
252    /// certificate) and pass it here without coupling this module to disk.
253    pub fn set_tls_config(&mut self, config: axum_server::tls_rustls::RustlsConfig) {
254        self.tls_config = Some(config);
255        self.secure_cookie = true;
256    }
257
258    /// Install a persisted signing key. Rotating this value signs every phone
259    /// out without maintaining a server-side session database.
260    pub fn set_cookie_key(&mut self, key: Vec<u8>) -> AnyResult<()> {
261        anyhow::ensure!(
262            key.len() >= COOKIE_KEY_BYTES,
263            "cookie signing key must be at least {COOKIE_KEY_BYTES} bytes"
264        );
265        self.cookie_key = key;
266        Ok(())
267    }
268
269    /// Install the controller's bounded background-task stop path.
270    pub fn set_background_task_stop_tx(&mut self, tx: mpsc::Sender<BackgroundTaskStopRequest>) {
271        self.background_task_stop_tx = tx;
272    }
273
274    /// Install the persisted bearer token for the `/api/v1` routes. Rotating
275    /// it revokes every client that still holds the old one.
276    pub fn set_api_token(&mut self, token: String) {
277        self.api_token = token;
278    }
279
280    /// Install the daemon-side backend the `/api/v1` routes drive sessions
281    /// through. Without it those routes answer 503.
282    pub fn set_subagent_backend(&mut self, backend: Arc<dyn api::SubagentBackend>) {
283        self.subagent = Some(backend);
284    }
285
286    #[cfg(test)]
287    fn with_test_credentials(mut self, code: &str, key: &[u8]) -> Self {
288        self.viewer_code = code.to_string();
289        self.login_token = "test-login-token".into();
290        self.cookie_key = key.to_vec();
291        self.secure_cookie = false;
292        self.api_token = "test-api-token".into();
293        self
294    }
295}
296
297/// Run the phone server until its shutdown token is cancelled.
298///
299/// This binds only the requested listener. It does not daemonize, provision a
300/// target, or keep sessions alive: controller availability is required, just
301/// like MJ's explicit remote-viewer model.
302pub async fn run_server(options: ServerOptions) -> AnyResult<()> {
303    let listener = tokio::net::TcpListener::bind(options.bind)
304        .await
305        .with_context(|| format!("bind web viewer to {}", options.bind))?;
306    run_server_on_listener(options, listener).await
307}
308
309/// Serve a reserved socket so readiness and advertised ports reflect a real listener.
310pub async fn run_server_on_listener(
311    options: ServerOptions,
312    listener: tokio::net::TcpListener,
313) -> AnyResult<()> {
314    let mut options = options;
315    let bind = listener.local_addr().context("read web viewer address")?;
316    let shutdown = options.shutdown.clone();
317    let viewer_code = options.viewer_code.clone();
318    let tls_config = options.tls_config.take();
319    let app = router(options);
320    println!("Mjolnir viewer code: {viewer_code}");
321    let listener = listener.into_std().context("prepare web viewer listener")?;
322    let handle = axum_server::Handle::new();
323    let shutdown_handle = handle.clone();
324    let serve = async move {
325        if let Some(tls_config) = tls_config {
326            axum_server::from_tcp_rustls(listener, tls_config)
327                .handle(handle)
328                .serve(app.into_make_service())
329                .await
330        } else {
331            axum_server::from_tcp(listener)
332                .handle(handle)
333                .serve(app.into_make_service())
334                .await
335        }
336    };
337    tokio::pin!(serve);
338    tokio::select! {
339        result = &mut serve => result,
340        _ = shutdown.cancelled() => {
341            shutdown_handle.graceful_shutdown(Some(Duration::from_secs(2)));
342            serve.await
343        }
344    }
345    .with_context(|| format!("serve web viewer on {bind}"))
346}
347
348mod viewer_types;
349pub use viewer_types::*;
350mod actions;
351pub use actions::*;
352mod routes;
353use routes::*;
354mod handlers;
355use handlers::*;
356mod validation;
357use validation::*;
358mod errors;
359use errors::*;
360mod auth;
361pub use auth::*;
362mod assets;
363use assets::*;
364mod config_view;
365pub use config_view::*;
366
367#[cfg(test)]
368mod tests;
mj_controller/server.rs

mj_controller/
server.rs
