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
fix(server): stop printing the admin key on first boot (#1633)
xerj-org286e72abbcee
diff --git a/docs/recipes/production-deployment.md b/docs/recipes/production-deployment.mdindex 8782951f3..9bfa1c8b4 100644--- a/docs/recipes/production-deployment.md+++ b/docs/recipes/production-deployment.md@@ -59,18 +59,14 @@ Boot it:xerj --config /etc/xerj/xerj.toml```-On first start the admin key is printed **once** (illustrative — yours is a-random 64-hex-character value):+On first start the admin key is written **once** to `<data_dir>/admin.key`+(mode 0600). The banner names that path and does not print the key:```-╔══════════════════════════════════════════════════╗-║ First-run: admin API key auto-generated ║-║ ║-║ <64 random hex chars> ║-║ ║-║ Keep this secret. Written to: ║-║ /var/lib/xerj/admin.key ║-╚══════════════════════════════════════════════════╝+First-run: admin API key auto-generated.+The key is not printed here. Read it from (owner-only, mode 0600):+/var/lib/xerj/admin.key+Keep that file secret. Clients send it as `Authorization: ApiKey $(cat /var/lib/xerj/admin.key)`.```…followed by the deployment-posture banner (verbatim from a real TLS+auth boot;@@ -104,10 +100,10 @@ this build — provide them at the layers described in### How auth behaves* **On by default.** `[auth] enabled` defaults to `true`. Leave `admin_api_key`- empty and XERJ generates a 64-hex-character key on first run, writes it to- `<data_dir>/admin.key` with `0600` permissions, and prints it once. Or set- `admin_api_key` yourself (then no file is written — protect the config file- with `chmod 600`).+ empty and XERJ generates a 64-hex-character key on first run and writes it to+ `<data_dir>/admin.key` with `0600` permissions. The startup notice prints the+ path, not the key. Or set `admin_api_key` yourself (then no file is written —+ protect the config file with `chmod 600`).* **One key, full access.** Every request must carry the key; there is **noRBAC** — any authenticated caller can read and write every index. Both headerschemes work:diff --git a/engine/README.md b/engine/README.mdindex 8829704a3..3dade6255 100644--- a/engine/README.md+++ b/engine/README.md@@ -103,8 +103,9 @@ enabled = false # NOT the default — the default is true`auth.enabled` defaults to **true**; `enabled = false` above is an explicitopt-out, appropriate only for a trusted private network or local development.Leave it out (or set it to `true`) and the server mints an admin key on first-boot, prints it, and writes it to `<data_dir>/admin.key`. Every client then has-to send it — including `xerj autoindex`, which never reads the key out of+boot and writes it to `<data_dir>/admin.key` (mode 0600). The key is not+printed: the first-run notice names that path. Every client then has to send+it — including `xerj autoindex`, which never reads the key out of`xerj.toml`; give it `--api-key` or `XERJ_API_KEY`:```bashdiff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rsindex 61d6b7381..96dc074b0 100644--- a/engine/crates/xerj-server/src/main.rs+++ b/engine/crates/xerj-server/src/main.rs@@ -960,28 +960,46 @@ fn ensure_admin_key(cfg: &mut Config) -> Result<()> {let raw: Vec<u8> = (0..32).map(|_| rand::random::<u8>()).collect();let key: String = raw.iter().map(|b| format!("{b:02x}")).collect();- println!();- println!("╔══════════════════════════════════════════════════╗");- println!("║ First-run: admin API key auto-generated ║");- println!("║ ║");- println!("║ {:<48} ║", key);- println!("║ ║");- println!("║ Keep this secret. Written to: ║");- println!("║ {:<48} ║", format!("{}/admin.key", cfg.server.data_dir));- println!("╚══════════════════════════════════════════════════╝");- println!();-- if std::fs::create_dir_all(data_dir).is_ok() {+ // Persist before announcing. The notice names the path and never the+ // secret: stdout is what agents capture, and a first-run banner that+ // prints the key lands in those logs (field report 2026-10-17).+ if let Err(e) = std::fs::create_dir_all(data_dir).and_then(|_| {// 0600 — this file IS the admin credential (RC4 W2 #21).- if let Err(e) = write_secret_file(&key_path, key.as_bytes()) {- warn!("could not persist admin.key: {e}");- }+ write_secret_file(&key_path, key.as_bytes())+ }) {+ warn!(+ "could not persist admin key to {}: {e}. The key was not printed. \+ Fix the data directory and restart so a key can be written.",+ key_path.display()+ );+ } else {+ println!("{}", first_run_admin_key_notice(&key, &key_path));}cfg.auth.admin_api_key = key;Ok(())}+/// Text printed once, when an admin key is minted.+///+/// `key` is accepted so a test can prove the rendered text does not contain+/// it. The function refuses to return a notice that includes the secret.+fn first_run_admin_key_notice(key: &str, key_path: &Path) -> String {+ let path = key_path.display().to_string();+ let notice = format!(+ "\n\+ First-run: admin API key auto-generated.\n\+ The key is not printed here. Read it from (owner-only, mode 0600):\n\+ {path}\n\+ Keep that file secret. Clients send it as `Authorization: ApiKey $(cat {path})`.\n"+ );+ assert!(+ !key.is_empty() && !notice.contains(key),+ "first-run notice must not contain the admin key"+ );+ notice+}+// ─────────────────────────────────────────────────────────────────────────────// TLS auto-generation// ─────────────────────────────────────────────────────────────────────────────@@ -3758,6 +3776,68 @@ mod server_correctness_tests {assert_eq!(mode, 0o600, "rewritten secret must be tightened to 0600");assert_eq!(std::fs::read(&stale).unwrap(), b"new");}++ /// The first-run banner used to print the 64-hex admin key on stdout.+ /// Agents that capture server output then hold the credential. The notice+ /// names the file and nothing else that is the key.+ #[test]+ fn first_run_notice_names_the_key_file_and_not_the_key() {+ let key = "ab".repeat(32);+ assert_eq!(key.len(), 64);+ let path = Path::new("/var/lib/xerj/admin.key");+ let notice = first_run_admin_key_notice(&key, path);+ assert!(+ !notice.contains(&key),+ "notice leaked the admin key:\n{notice}"+ );+ assert!(notice.contains(path.to_str().unwrap()), "{notice}");+ assert!(+ notice.contains("not printed"),+ "notice must say the key is withheld: {notice}"+ );+ assert!(+ notice.split_whitespace().all(|word| {+ let bare = word.trim_matches(|c: char| !c.is_ascii_hexdigit());+ !(bare.len() >= 64 && bare.bytes().all(|b| b.is_ascii_hexdigit()))+ }),+ "notice contains a 64-hex token:\n{notice}"+ );+ }++ /// A fresh data dir gets a 0600 admin.key, and a second call reuses it+ /// instead of minting another. The in-memory key matches the file.+ #[test]+ fn ensure_admin_key_writes_the_file_and_reuses_it() {+ let dir = TempDir::new().unwrap();+ let mut cfg = Config::default();+ cfg.auth.enabled = true;+ cfg.auth.admin_api_key.clear();+ cfg.server.data_dir = dir.path().to_str().unwrap().to_string();++ ensure_admin_key(&mut cfg).unwrap();+ let written = std::fs::read_to_string(dir.path().join("admin.key")).unwrap();+ assert_eq!(written, cfg.auth.admin_api_key);+ assert_eq!(written.len(), 64);+ assert!(written.bytes().all(|b| b.is_ascii_hexdigit()));+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ let mode = std::fs::metadata(dir.path().join("admin.key"))+ .unwrap()+ .permissions()+ .mode()+ & 0o777;+ assert_eq!(mode, 0o600, "admin.key must be 0600, got {mode:o}");+ }++ let first = cfg.auth.admin_api_key.clone();+ cfg.auth.admin_api_key.clear();+ ensure_admin_key(&mut cfg).unwrap();+ assert_eq!(+ cfg.auth.admin_api_key, first,+ "a restart must reuse admin.key"+ );+ }}#[cfg(test)]