Skip to content

armgit / xerj

Public Imported from GitHub
0

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.

15.6 KB
Raw Blame
//! First-launch bootstrap.
//!
//! Two responsibilities:
//!
//! 1. **Master key.** Load (or generate-then-persist) a 32-byte secret used
//!    to HMAC session cookies, magic-link tokens, and connection-secret
//!    AEAD keys. Stored at `<data_dir>/.xerj_master_key` mode 0600, or
//!    overridden by the `XERJ_CONSOLE_KEY` env var (32 hex bytes).
//!
//! 2. **Bootstrap mode.** If `.xerj_users` has zero documents with
//!    `status = "active"`, mint a single-use 30-minute magic link with
//!    `purpose = "bootstrap"` and `role = "owner"`, store its sha256 in
//!    `.xerj_magic_links`, and print a bordered banner to stderr with
//!    the redeem URL the operator should open.
//!
//! Idempotent: if an active user already exists, this function is a no-op
//! beyond loading the master key.

use std::path::Path;

use rand::RngCore;
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use xerj_engine::Engine;

use crate::error::{ConsoleApiError, ConsoleResult};
use crate::indices;
use crate::time::{now_epoch_ms, now_iso};

/// Result of the bootstrap routine, returned to the server's main()
/// so it can fold the master key into `ConsoleState` and decide what to
/// print on stdout.
pub struct BootstrapOutcome {
    pub master_key: [u8; 32],
    /// `Some(url)` if a fresh bootstrap link was minted. The caller is
    /// responsible for printing this — `bootstrap_if_needed` does its
    /// own stderr banner already, but tests want the URL programmatically.
    pub magic_link: Option<String>,
}

/// Run the full first-launch routine. Idempotent on subsequent boots.
///
/// `bind_url` is the URL the operator should browse to (e.g.
/// `http://localhost:9200`). The full link the SPA receives is
/// `{bind_url}/_xerj-console/setup#token=…`.
pub async fn run(
    engine: &Engine,
    data_dir: &Path,
    bind_url: &str,
) -> ConsoleResult<BootstrapOutcome> {
    // Console bootstrap is a storage migration: it creates fourteen system
    // indices, writes a master key and publishes seeded dashboard segments.
    // Keep this guard inside the crate as well as at the server call site so a
    // future embedder cannot accidentally bypass the compatibility fence.
    if !engine.cluster_state_boot_status().is_writable() {
        return Err(ConsoleApiError::Internal(
            "cluster-state storage is unavailable; Console bootstrap requires a supported restart"
                .to_owned(),
        ));
    }
    let master_key = load_or_init_master_key(data_dir)?;

    indices::ensure_all(engine)?;

    // Materialise the built-in dashboards as editable backend data. Idempotent
    // and safe on every boot: creates any missing default, never clobbers an
    // operator's edits, and only re-syncs untouched defaults when the shipped
    // seed revision is bumped. See `crate::seed`.
    crate::seed::seed_default_dashboards(engine).await?;

    let magic_link = if has_any_active_user(engine).await? {
        None
    } else {
        let url = mint_bootstrap_link(engine, bind_url).await?;
        print_bootstrap_banner(&url);
        Some(url)
    };

    Ok(BootstrapOutcome {
        master_key,
        magic_link,
    })
}

// ─────────────────────────────────────────────────────────────────────────────
// Master key
// ─────────────────────────────────────────────────────────────────────────────

const MASTER_KEY_FILENAME: &str = ".xerj_master_key";
const MASTER_KEY_ENV: &str = "XERJ_CONSOLE_KEY";

fn load_or_init_master_key(data_dir: &Path) -> ConsoleResult<[u8; 32]> {
    // Env var wins — covers Kubernetes secret mounts.
    if let Ok(hex) = std::env::var(MASTER_KEY_ENV) {
        let bytes = hex_decode(hex.trim()).ok_or_else(|| {
            ConsoleApiError::Internal(format!("{MASTER_KEY_ENV}: not 64 hex chars"))
        })?;
        if bytes.len() != 32 {
            return Err(ConsoleApiError::Internal(format!(
                "{MASTER_KEY_ENV}: expected 32 bytes (64 hex), got {}",
                bytes.len()
            )));
        }
        let mut out = [0u8; 32];
        out.copy_from_slice(&bytes);
        return Ok(out);
    }

    let path = data_dir.join(MASTER_KEY_FILENAME);
    if path.exists() {
        let raw = std::fs::read_to_string(&path)?;
        let trimmed = raw.trim();
        let bytes = hex_decode(trimmed).ok_or_else(|| {
            ConsoleApiError::Internal(format!(
                "{}: not valid hex (corrupt? regenerate by deleting and restarting)",
                path.display()
            ))
        })?;
        if bytes.len() != 32 {
            return Err(ConsoleApiError::Internal(format!(
                "{}: expected 32 bytes (64 hex), got {}",
                path.display(),
                bytes.len()
            )));
        }
        let mut out = [0u8; 32];
        out.copy_from_slice(&bytes);
        return Ok(out);
    }

    // First boot: generate, persist with mode 0600.
    let mut key = [0u8; 32];
    rand::thread_rng().fill_bytes(&mut key);
    let hex = hex_encode(&key);
    std::fs::write(&path, &hex)?;
    set_owner_readable_only(&path)?;
    tracing::info!(path = %path.display(), "generated xerj-console master key");
    Ok(key)
}

#[cfg(unix)]
fn set_owner_readable_only(p: &Path) -> std::io::Result<()> {
    use std::os::unix::fs::PermissionsExt;
    let mut perm = std::fs::metadata(p)?.permissions();
    perm.set_mode(0o600);
    std::fs::set_permissions(p, perm)
}

#[cfg(not(unix))]
fn set_owner_readable_only(_p: &Path) -> std::io::Result<()> {
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────────
// "Any active user?" predicate
// ─────────────────────────────────────────────────────────────────────────────

async fn has_any_active_user(engine: &Engine) -> ConsoleResult<bool> {
    let idx = engine
        .get_index(indices::USERS)
        .map_err(|e| ConsoleApiError::Internal(format!("open {}: {e}", indices::USERS)))?;

    // Build a `term: { status: "active" }` search with size: 1. Cheap on
    // a tiny system index — we only care whether any doc matches.
    let body = json!({
        "query": { "term": { "status": "active" } },
        "size": 1,
        "track_total_hits": true
    });

    let req = xerj_query::parser::parse_request(&body)
        .map_err(|e| ConsoleApiError::Internal(format!("parse bootstrap probe: {e}")))?;

    let result = idx
        .search(&req)
        .await
        .map_err(|e| ConsoleApiError::Internal(format!("search {}: {e}", indices::USERS)))?;

    Ok(result.total.value > 0)
}

// ─────────────────────────────────────────────────────────────────────────────
// Magic link minting
// ─────────────────────────────────────────────────────────────────────────────

/// Format of the token the operator pastes into a browser. Random 32 bytes,
/// URL-safe base64 (no padding) — always 43 chars. We never log or store
/// the token in plaintext; only its sha256 lands in `.xerj_magic_links`.
const TOKEN_BYTES: usize = 32;
const BOOTSTRAP_TTL_MS: i64 = 30 * 60 * 1000; // 30 minutes

async fn mint_bootstrap_link(engine: &Engine, bind_url: &str) -> ConsoleResult<String> {
    let idx = engine
        .get_index(indices::MAGIC_LINKS)
        .map_err(|e| ConsoleApiError::Internal(format!("open {}: {e}", indices::MAGIC_LINKS)))?;

    let token = random_url_token();
    let token_hash = sha256_hex(token.as_bytes());

    let now_ms = now_epoch_ms();
    let expires_ms = now_ms + BOOTSTRAP_TTL_MS;

    let doc: Value = json!({
        "purpose":     "bootstrap",
        "role":        "owner",
        "user_id":     null,
        "email":       null,
        "created_by":  "system",
        "created_at":  now_iso(),
        "expires_at":  crate::time::epoch_ms_to_iso(expires_ms),
        "used_at":     null,
        "used_from_ip": null
    });

    idx.create_document(token_hash.clone(), doc)
        .await
        .map_err(|e| ConsoleApiError::Internal(format!("write magic link: {e}")))?;

    Ok(format!(
        "{}/_xerj-console/setup#token={}",
        bind_url.trim_end_matches('/'),
        token
    ))
}

/// Printed under the bootstrap link. Names the recovery that actually works:
/// while no active user exists, every boot re-mints and reprints a fresh link
/// (see `run` above) — and the shipped binary has no `admin` subcommand. An
/// earlier revision of this line suggested `xerj admin magic-link --role
/// owner`, which rc.95 rejects with `unknown argument: admin` (#1424).
const RENEWAL_HINT: &str = "Need a fresh link?  Restart this node: a new one is printed on boot.";

fn print_bootstrap_banner(url: &str) {
    let bar = "─".repeat(78);
    eprintln!();
    eprintln!("┌{bar}┐");
    eprintln!("│ {:<76} │", "XERJ CONSOLE  ·  first-launch setup");
    eprintln!("│ {:<76} │", "");
    eprintln!(
        "│ {:<76} │",
        "Open this link in your browser to claim the owner account by"
    );
    eprintln!(
        "│ {:<76} │",
        "enrolling a passkey.  Valid for 30 minutes.  Single use."
    );
    eprintln!("│ {:<76} │", "");
    // The URL can be longer than 76 chars; if so, print it on its own line.
    if url.len() <= 76 {
        eprintln!("│   {:<74} │", url);
    } else {
        eprintln!("├{bar}┤");
        eprintln!("  {url}");
        eprintln!("├{bar}┤");
    }
    eprintln!("│ {:<76} │", "");
    eprintln!("│ {:<76} │", RENEWAL_HINT);
    eprintln!("└{bar}┘");
    eprintln!();
}

// ─────────────────────────────────────────────────────────────────────────────
// Tiny crypto helpers (dependency-light hex + sha256 + url-safe base64).
// ─────────────────────────────────────────────────────────────────────────────

fn random_url_token() -> String {
    let mut bytes = [0u8; TOKEN_BYTES];
    rand::thread_rng().fill_bytes(&mut bytes);
    base64_url_encode(&bytes)
}

pub(crate) fn sha256_hex(input: &[u8]) -> String {
    let mut h = Sha256::new();
    h.update(input);
    hex_encode(&h.finalize())
}

fn hex_encode(bytes: &[u8]) -> String {
    let mut s = String::with_capacity(bytes.len() * 2);
    for b in bytes {
        s.push_str(&format!("{b:02x}"));
    }
    s
}

fn hex_decode(s: &str) -> Option<Vec<u8>> {
    if !s.len().is_multiple_of(2) {
        return None;
    }
    let mut out = Vec::with_capacity(s.len() / 2);
    let mut chars = s.chars();
    while let (Some(a), Some(b)) = (chars.next(), chars.next()) {
        let h = a.to_digit(16)?;
        let l = b.to_digit(16)?;
        out.push(((h << 4) | l) as u8);
    }
    Some(out)
}

fn base64_url_encode(bytes: &[u8]) -> String {
    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
    URL_SAFE_NO_PAD.encode(bytes)
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;
    use xerj_common::config::Config;

    fn engine_in(dir: &TempDir) -> Engine {
        let mut cfg = Config::default();
        cfg.server.data_dir = dir.path().to_str().unwrap().to_string();
        Engine::new(cfg).expect("engine init")
    }

    #[tokio::test]
    async fn fresh_data_dir_emits_magic_link() {
        let dir = TempDir::new().unwrap();
        let engine = engine_in(&dir);

        let outcome = run(&engine, dir.path(), "http://localhost:9200")
            .await
            .expect("bootstrap");

        assert!(outcome.magic_link.is_some(), "fresh boot must mint a link");
        let url = outcome.magic_link.unwrap();
        assert!(url.starts_with("http://localhost:9200/_xerj-console/setup#token="));
        assert!(dir.path().join(".xerj_master_key").exists());
    }

    #[tokio::test]
    async fn bootstrap_idempotent_with_active_user() {
        let dir = TempDir::new().unwrap();
        let engine = engine_in(&dir);

        // First boot mints a link.
        let _ = run(&engine, dir.path(), "http://x").await.unwrap();

        // Simulate the operator finishing enrolment by writing an active
        // user. Real flow goes through /auth/passkey/finish in phase 2.
        let users = engine.get_index(indices::USERS).unwrap();
        users
            .create_document(
                "u1".into(),
                json!({
                    "email": "[email protected]",
                    "role": "owner",
                    "status": "active",
                    "created_at": now_iso()
                }),
            )
            .await
            .unwrap();
        users.flush().await.unwrap();

        let outcome2 = run(&engine, dir.path(), "http://x").await.unwrap();
        assert!(
            outcome2.magic_link.is_none(),
            "second boot with an active user must not mint a new link"
        );
    }

    #[test]
    fn master_key_round_trip() {
        let dir = TempDir::new().unwrap();
        let k1 = load_or_init_master_key(dir.path()).unwrap();
        let k2 = load_or_init_master_key(dir.path()).unwrap();
        assert_eq!(k1, k2, "key must be stable across boots");
    }

    /// #1424: the banner must not name a command the shipped binary lacks.
    /// It used to suggest `xerj admin magic-link --role owner`; the CLI has no
    /// `admin` subcommand and rejects it with `unknown argument: admin`.
    /// The recovery it names instead is a restart — which the next test pins
    /// to actually mint a fresh link.
    #[test]
    fn renewal_hint_names_a_recovery_that_exists() {
        assert!(
            !RENEWAL_HINT.contains("admin"),
            "the hint must not name the nonexistent `xerj admin` subcommand: \
             {RENEWAL_HINT}"
        );
        assert!(
            RENEWAL_HINT.contains("Restart"),
            "the hint must name the real recovery (a restart re-mints a link): \
             {RENEWAL_HINT}"
        );
    }

    /// The banner's advice, exercised: before anyone claims the owner account,
    /// restarting the node mints ANOTHER printable link with a new token —
    /// which is what makes "restart" a genuine recovery for an expired link.
    #[tokio::test]
    async fn restart_without_an_active_user_mints_a_fresh_link() {
        let dir = TempDir::new().unwrap();
        let engine = engine_in(&dir);

        let first = run(&engine, dir.path(), "http://localhost:9200")
            .await
            .expect("first boot")
            .magic_link
            .expect("a fresh boot must mint a link");
        let second = run(&engine, dir.path(), "http://localhost:9200")
            .await
            .expect("restart before enrolment")
            .magic_link
            .expect("a restart before enrolment must mint another link");

        assert_ne!(first, second, "the fresh link must carry a new token");
        assert!(second.starts_with("http://localhost:9200/_xerj-console/setup#token="));
    }
}