AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
//! Shared state for Xerj Console handlers.
//!
//! `ConsoleState` is `Clone` and lives behind `axum::extract::State`. The
//! types it wraps are individually responsible for their own concurrency
//! (the `Engine` is internally `Arc`-shared, the in-memory caches are
//! `Arc<DashMap<…>>` etc.). This struct is just the join.
use std::sync::Arc;
use dashmap::DashMap;
use xerj_common::net::TrustedProxies;
use xerj_engine::Engine;
use crate::client_ip::TrustedProxySource;
use crate::error::{ConsoleApiError, ConsoleResult};
use crate::time::now_epoch_ms;
/// Server start time, in epoch ms. Used by `/cluster/info` so the SPA can
/// show "node up since …" without a separate /uptime fetch.
#[derive(Debug, Clone, Copy)]
pub struct StartedAt(pub i64);
/// In-memory record of a WebAuthn challenge that the server issued but
/// the client has not yet completed. Indexed by an opaque challenge id
/// (random 32-byte url-safe base64) that the SPA echoes back on
/// `…/finish`. Auto-expires after 5 minutes; entries past their TTL
/// are pruned on every insert.
#[derive(Debug, Clone)]
pub struct PendingChallenge {
pub kind: ChallengeKind,
pub created_at_ms: i64,
}
#[derive(Debug, Clone)]
pub enum ChallengeKind {
/// `POST /auth/passkey/begin` — enrolling a new credential. We hold
/// the registration state plus the user_id we're enrolling for so
/// `…/finish` knows where to attach the credential.
PasskeyEnroll {
user_id: String,
state: webauthn_rs::prelude::PasskeyRegistration,
},
/// `POST /auth/login/begin` — proving an existing credential.
/// The `email` is null when we returned a fake challenge for an
/// unknown email (anti-enumeration).
Login {
email: Option<String>,
state: webauthn_rs::prelude::PasskeyAuthentication,
},
}
/// In-memory record of an enrollment session — issued when a user
/// redeems a magic link, consumed when they finish passkey enrollment.
/// Lives only in RAM (max 30 minutes), not persisted; if the server
/// restarts mid-bootstrap, the user re-redeems with a fresh link.
#[derive(Debug, Clone)]
pub struct EnrollmentSession {
pub session_id: String,
pub email: String,
pub user_id: String,
pub role: String,
pub created_at_ms: i64,
pub expires_at_ms: i64,
}
/// Coarse "is this node part of a RAFT cluster?" flag, set at startup
/// from `cfg.cluster.enabled` and never mutated. Phase 4 swaps this for
/// a live handle to the cluster runner so `/cluster/raft` can stream
/// real RAFT state; in phase 1 we only need the standalone-vs-raft
/// branch in `/cluster/info`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ClusterMode {
Standalone,
Raft,
}
/// WebAuthn Relying Party configuration. `rp_id` is the effective domain
/// (e.g. `"localhost"` for dev, `"xerj-console.example.com"` for prod) and
/// `rp_origin` is the URL the SPA was loaded from (e.g.
/// `"http://localhost:9200"`). Both must match between enrolment and
/// login or the browser refuses the assertion.
#[derive(Debug, Clone)]
pub struct RpConfig {
pub rp_id: String,
pub rp_origin: String,
pub rp_name: String,
}
impl Default for RpConfig {
fn default() -> Self {
Self {
rp_id: "localhost".to_string(),
rp_origin: "http://localhost:9200".to_string(),
rp_name: default_rp_name(),
}
}
}
fn default_rp_name() -> String {
"Xerj Console".to_string()
}
impl RpConfig {
/// Derive the relying party from the URL the console is actually
/// served on (in `xerj-server` that is the bound address plus the
/// *bound* ES-compat port, so ephemeral ports are already resolved —
/// issue #469).
///
/// * Loopback and unspecified hosts (`localhost`, `127.0.0.1`, `::1`,
/// `0.0.0.0`, `::`) all map to `rp_id = "localhost"` with the origin
/// rewritten to `<scheme>://localhost:<port>`. Browsers refuse an
/// IP-literal WebAuthn origin outright, so keeping the bind address
/// in the origin makes enrolment impossible on any port; and keeping
/// `rp_id` on `localhost` preserves credentials enrolled against the
/// historical hard-coded default (#935).
/// * A named host is used verbatim: `rp_id` = host, origin = the URL.
/// * A non-loopback IP literal is refused: a WebAuthn RP id must be a
/// registrable domain, so there is no honest configuration for
/// `http://192.168.0.5:9200`. Serve the console behind a named host
/// (reverse proxy) or bind loopback to use passkeys.
pub fn from_bind_url(bind_url: &str) -> ConsoleResult<Self> {
let url = webauthn_rs::prelude::Url::parse(bind_url).map_err(|e| {
ConsoleApiError::Internal(format!("console bind url `{bind_url}`: {e}"))
})?;
let Some(host) = url.host_str().map(|h| h.to_string()) else {
return Err(ConsoleApiError::Internal(format!(
"console bind url `{bind_url}` has no host"
)));
};
// `Url::host_str` keeps the brackets on an IPv6 literal
// (`http://[::1]:9550` → `"[::1]"`); a domain name can never contain
// one, so trimming them restores the parseable spelling.
let host = host
.trim_start_matches('[')
.trim_end_matches(']')
.to_string();
let port = url.port().map(|p| format!(":{p}")).unwrap_or_default();
if bind_host_is_local(&host) {
Ok(Self {
rp_id: "localhost".to_string(),
rp_origin: format!("{}://localhost{port}", url.scheme()),
rp_name: default_rp_name(),
})
} else if host.parse::<std::net::IpAddr>().is_ok() {
Err(ConsoleApiError::Internal(format!(
"cannot derive a WebAuthn relying party from `{bind_url}`: a relying-party id \
must be a domain, not the IP literal `{host}` — serve the console behind a \
named host or bind loopback to use passkeys"
)))
} else {
Ok(Self {
rp_id: host.clone(),
rp_origin: format!("{}://{host}{port}", url.scheme()),
rp_name: default_rp_name(),
})
}
}
}
/// Is this URL host the machine itself, in any of its spellings?
fn bind_host_is_local(host: &str) -> bool {
match host.parse::<std::net::IpAddr>() {
Ok(ip) => ip.is_loopback() || ip.is_unspecified(),
Err(_) => host.eq_ignore_ascii_case("localhost"),
}
}
/// The host a human should be sent to for the console, given the address
/// the node bound (`server.bind_address`).
///
/// Every loopback or unspecified bind becomes `localhost`: browsers refuse
/// an IP-literal WebAuthn origin, so a first-launch link printed as
/// `http://127.0.0.1:<port>/…` can never complete passkey enrolment even
/// when the relying party is derived correctly (#935). Any other address
/// keeps its spelling, IPv6 bracketed for a URL (`http://[fd00::1]:…`).
pub fn public_bind_host(bind_address: &str) -> String {
let raw = bind_address.trim();
match raw.parse::<std::net::IpAddr>() {
Ok(ip) if ip.is_loopback() || ip.is_unspecified() => "localhost".to_string(),
Ok(std::net::IpAddr::V6(v6)) => format!("[{v6}]"),
Ok(_) => raw.to_string(),
// `localhost` itself, and any name that slips past the server's
// IP-literal bind guard, keeps its spelling.
Err(_) => raw.to_string(),
}
}
/// Top-level state object shared into every Xerj Console handler.
#[derive(Clone)]
pub struct ConsoleState {
pub engine: Engine,
pub started_at: StartedAt,
pub node_id: Arc<String>,
pub cluster_mode: ClusterMode,
pub rp: Arc<RpConfig>,
/// Live WebAuthn challenges. `pending_challenges[challenge_b64u]
/// = PendingChallenge`. Capped at 1024 entries; stale entries are
/// pruned on every insert via `prune_pending_challenges`.
pub pending_challenges: Arc<DashMap<String, PendingChallenge>>,
/// Live enrollment sessions (post-magic-link, pre-passkey-finish).
pub enrollment_sessions: Arc<DashMap<String, EnrollmentSession>>,
/// Per-IP rate-limit counters for auth endpoints. Reset every minute
/// on first hit after the window. Map key is `"<ip>:<endpoint>"`.
pub auth_rate_counters: Arc<DashMap<String, RateWindow>>,
/// HMAC key used to sign session cookies (derived from the
/// `data_dir/.xerj_master_key` file or the `XERJ_CONSOLE_KEY`
/// env var; generated on first start and persisted).
pub master_key: Arc<[u8; 32]>,
/// Serializes magic-link redemption (#76 S5-3). The single-use check and
/// the `mark_magic_link_used` commit are separated by several awaits and
/// the store's mark-used is itself get→delete→create, so two concurrent
/// redeems of one token could both pass the used-check and both mint a
/// session. Holding this gate across the whole check→consume makes the
/// transition atomic. Redemptions are rare (enrollment/recovery), so a
/// single gate is cheaper than a per-token map and needs no cleanup.
pub redeem_gate: Arc<tokio::sync::Mutex<()>>,
/// Reverse proxies whose `X-Forwarded-For` / `X-Real-IP` we believe
/// (#76 S5-4). Empty by default — an unconfigured node derives client
/// identity from the socket peer only, so the auth rate limiter cannot be
/// side-stepped with a forged header. Populated from
/// `server.trusted_proxies` by `xerj-server` at startup.
pub trusted_proxies: Arc<TrustedProxies>,
}
#[derive(Debug, Clone, Copy)]
pub struct RateWindow {
pub count: u32,
pub window_start_ms: i64,
}
impl ConsoleState {
pub fn new(
engine: Engine,
node_id: String,
master_key: [u8; 32],
cluster_mode: ClusterMode,
) -> Self {
Self::new_with_rp(
engine,
node_id,
master_key,
cluster_mode,
RpConfig::default(),
)
}
pub fn new_with_rp(
engine: Engine,
node_id: String,
master_key: [u8; 32],
cluster_mode: ClusterMode,
rp: RpConfig,
) -> Self {
Self {
engine,
started_at: StartedAt(now_epoch_ms()),
node_id: Arc::new(node_id),
cluster_mode,
rp: Arc::new(rp),
pending_challenges: Arc::new(DashMap::new()),
enrollment_sessions: Arc::new(DashMap::new()),
auth_rate_counters: Arc::new(DashMap::new()),
master_key: Arc::new(master_key),
redeem_gate: Arc::new(tokio::sync::Mutex::new(())),
trusted_proxies: Arc::new(TrustedProxies::none()),
}
}
/// Declare the reverse proxies whose forwarding headers may be believed.
///
/// Builder-style so the safe default (trust nothing) is what you get
/// unless a caller opts in explicitly.
pub fn with_trusted_proxies(mut self, trusted: TrustedProxies) -> Self {
self.trusted_proxies = Arc::new(trusted);
self
}
}
impl TrustedProxySource for ConsoleState {
fn trusted_proxies(&self) -> &TrustedProxies {
&self.trusted_proxies
}
}
impl std::fmt::Debug for ConsoleState {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ConsoleState")
.field("node_id", &self.node_id)
.field("started_at", &self.started_at.0)
.field("pending_challenges", &self.pending_challenges.len())
.field("enrollment_sessions", &self.enrollment_sessions.len())
.finish_non_exhaustive()
}
}
#[cfg(test)]
mod rp_config_tests {
use super::*;
/// The default bind is `127.0.0.1` — before #935 this was exactly the
/// node that could not enrol on any port but 9200.
#[test]
fn loopback_ipv4_bind_maps_to_localhost_with_the_bound_port() {
let rp = RpConfig::from_bind_url("http://127.0.0.1:9550").unwrap();
assert_eq!(rp.rp_id, "localhost");
assert_eq!(rp.rp_origin, "http://localhost:9550");
}
#[test]
fn loopback_ipv6_bind_maps_to_localhost() {
let rp = RpConfig::from_bind_url("http://[::1]:9550").unwrap();
assert_eq!(rp.rp_id, "localhost");
assert_eq!(rp.rp_origin, "http://localhost:9550");
}
#[test]
fn localhost_name_and_unspecified_binds_map_to_localhost() {
let a = RpConfig::from_bind_url("http://localhost:9550").unwrap();
let b = RpConfig::from_bind_url("http://0.0.0.0:9200").unwrap();
let c = RpConfig::from_bind_url("http://[::]:9200").unwrap();
assert_eq!(
(a.rp_id.as_str(), a.rp_origin.as_str()),
("localhost", "http://localhost:9550")
);
assert_eq!(
(b.rp_id.as_str(), b.rp_origin.as_str()),
("localhost", "http://localhost:9200")
);
assert_eq!(
(c.rp_id.as_str(), c.rp_origin.as_str()),
("localhost", "http://localhost:9200")
);
}
#[test]
fn non_loopback_ip_bind_is_refused_with_the_address_named() {
let err = RpConfig::from_bind_url("http://192.168.1.5:9200").unwrap_err();
let msg = err.to_string();
assert!(
msg.contains("192.168.1.5"),
"the refusal must name the address so the operator can act: {msg}"
);
assert!(RpConfig::from_bind_url("http://[fd00::1]:9200").is_err());
}
#[test]
fn named_host_is_used_verbatim() {
let rp = RpConfig::from_bind_url("http://console.example.com:9200").unwrap();
assert_eq!(rp.rp_id, "console.example.com");
assert_eq!(rp.rp_origin, "http://console.example.com:9200");
}
#[test]
fn portless_url_keeps_a_portless_origin() {
let rp = RpConfig::from_bind_url("http://localhost").unwrap();
assert_eq!(rp.rp_id, "localhost");
assert_eq!(rp.rp_origin, "http://localhost");
}
#[test]
fn unparseable_url_is_refused() {
assert!(RpConfig::from_bind_url("not a url").is_err());
assert!(RpConfig::from_bind_url("http://").is_err());
}
#[test]
fn public_bind_host_normalises_every_loopback_spelling() {
assert_eq!(public_bind_host("127.0.0.1"), "localhost");
assert_eq!(public_bind_host("::1"), "localhost");
assert_eq!(public_bind_host("0.0.0.0"), "localhost");
assert_eq!(public_bind_host("::"), "localhost");
assert_eq!(public_bind_host("localhost"), "localhost");
}
#[test]
fn public_bind_host_keeps_non_loopback_addresses_bracketing_ipv6() {
assert_eq!(public_bind_host("192.168.1.5"), "192.168.1.5");
assert_eq!(public_bind_host("fd00::1"), "[fd00::1]");
}
}