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
feat(console-auth): API tokens issue/list/revoke + Bearer auth
xerj-org7bdee832e48b
diff --git a/engine/crates/xerj-console-api/src/auth/mod.rs b/engine/crates/xerj-console-api/src/auth/mod.rsindex c05238972..d1b75a0cc 100644--- a/engine/crates/xerj-console-api/src/auth/mod.rs+++ b/engine/crates/xerj-console-api/src/auth/mod.rs@@ -13,6 +13,7 @@ pub mod passkey;pub mod rate_limit;pub mod sessions;pub mod store;+pub mod tokens;pub mod webauthn_setup;pub use sessions::{AuthSession, OptionalAuthSession};diff --git a/engine/crates/xerj-console-api/src/auth/sessions.rs b/engine/crates/xerj-console-api/src/auth/sessions.rsindex 8018444e1..2a9b2cd31 100644--- a/engine/crates/xerj-console-api/src/auth/sessions.rs+++ b/engine/crates/xerj-console-api/src/auth/sessions.rs@@ -30,6 +30,7 @@ use sha2::Sha256;use subtle::ConstantTimeEq;use crate::auth::store;+use crate::bootstrap::sha256_hex;use crate::error::{ConsoleApiError, ConsoleResult};use crate::state::ConsoleState;use crate::time::{epoch_ms_to_iso, now_epoch_ms, now_iso, parse_iso};@@ -138,6 +139,14 @@ impl FromRequestParts<ConsoleState> for AuthSession {parts: &mut Parts,state: &ConsoleState,) -> Result<Self, Self::Rejection> {+ // API clients authenticate with `Authorization: Bearer <token>`;+ // browsers with a signed session cookie. Bearer wins when present so+ // a token-carrying request is never silently downgraded to the+ // (absent) cookie path.+ if let Some(token) = bearer_token(&parts.headers) {+ return authenticate_bearer(state, &token).await;+ }+let jar = CookieJar::from_headers(&parts.headers);let cookie = jar.get(COOKIE_NAME)@@ -182,6 +191,59 @@ impl FromRequestParts<ConsoleState> for AuthSession {}}+// ─────────────────────────────────────────────────────────────────────────────+// Bearer (API token) authentication+// ─────────────────────────────────────────────────────────────────────────────++/// Pull the secret out of an `Authorization: Bearer <secret>` header.+/// Returns `None` when the header is absent, is not a bearer scheme, or+/// carries an empty value — the caller then falls back to the cookie path.+fn bearer_token(headers: &axum::http::HeaderMap) -> Option<String> {+ let raw = headers+ .get(axum::http::header::AUTHORIZATION)?+ .to_str()+ .ok()?;+ let rest = raw+ .strip_prefix("Bearer ")+ .or_else(|| raw.strip_prefix("bearer "))?;+ let trimmed = rest.trim();+ if trimmed.is_empty() {+ None+ } else {+ Some(trimmed.to_string())+ }+}++/// Authenticate a presented API token: hash it, look up a non-revoked+/// `ApiToken` row (see `auth::tokens`), and resolve its owner. Failure+/// semantics mirror the cookie path — every mismatch is a flat 401 that+/// never reveals which check failed.+async fn authenticate_bearer(+ state: &ConsoleState,+ presented: &str,+) -> Result<AuthSession, ConsoleApiError> {+ let hash = sha256_hex(presented.as_bytes());+ let token = store::get_api_token(&state.engine, &hash)+ .await?+ .ok_or_else(|| ConsoleApiError::Unauthorized("invalid api token".into()))?;+ if token.revoked_at.is_some() {+ return Err(ConsoleApiError::Unauthorized("api token revoked".into()));+ }+ let user = store::get_user(&state.engine, &token.user_id)+ .await?+ .ok_or_else(|| ConsoleApiError::Unauthorized("api token user gone".into()))?;+ if user.status != store::UserStatus::Active {+ return Err(ConsoleApiError::Unauthorized("user disabled".into()));+ }+ // `session_id` is opaque to callers; for a token-authenticated request+ // it is the token id (= hash). The cookie-only `logout` handler would+ // just no-op against `.xerj_sessions` for such an id.+ Ok(AuthSession {+ session_id: token.id,+ user,+ })+}+/// Allow `Option<AuthSession>` extractors for endpoints that work/// signed-in *or* signed-out (e.g. `/me` returns 401 explicitly rather/// than relying on the rejection so the SPA can branch on it).diff --git a/engine/crates/xerj-console-api/src/auth/tokens.rs b/engine/crates/xerj-console-api/src/auth/tokens.rsnew file mode 100644index 000000000..30455ea66--- /dev/null+++ b/engine/crates/xerj-console-api/src/auth/tokens.rs@@ -0,0 +1,180 @@+//! API tokens — issue / list / revoke.+//!+//! `POST /auth/api-tokens { name, scopes? }` mints a random 32-byte+//! URL-safe secret, persists only `sha256(secret)` (as the doc `_id`) plus+//! metadata, and returns the plaintext **once**. The secret is never logged+//! and cannot be recovered afterward — the same store convention as magic+//! links (`bootstrap.rs`).+//!+//! `GET /auth/api-tokens` lists the caller's tokens as metadata only+//! (id = the hash, name, scopes, timestamps); it never returns a plaintext.+//!+//! `DELETE /auth/api-tokens/:id` revokes one of the caller's tokens. It is+//! idempotent and returns 404 when the id is not the caller's / does not+//! exist, so we never confirm the existence of another user's token id.+//!+//! Bearer authentication lives in `sessions.rs`: it hashes a presented+//! `Authorization: Bearer <secret>` and looks up the non-revoked row minted+//! here, then authenticates as the token's owner.++use axum::{extract::State, response::Response, Json};+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};+use rand::RngCore;+use serde::{Deserialize, Serialize};+use serde_json::json;++use crate::auth::{audit, sessions::AuthSession, store};+use crate::bootstrap::sha256_hex;+use crate::error::{ConsoleApiError, ConsoleResult};+use crate::indices;+use crate::response::{no_content, ok};+use crate::state::ConsoleState;+use crate::time::now_iso;++/// Secret length in bytes. 32 bytes of CSPRNG output → 43-char URL-safe+/// base64 (no padding), matching the magic-link token shape.+const TOKEN_BYTES: usize = 32;++// ─────────────────────────────────────────────────────────────────────────────+// Issue+// ─────────────────────────────────────────────────────────────────────────────++#[derive(Debug, Deserialize)]+pub struct CreateBody {+ #[serde(default)]+ pub name: String,+ #[serde(default)]+ pub scopes: Vec<String>,+}++#[derive(Debug, Serialize)]+pub struct CreatedToken {+ /// The plaintext secret — returned exactly once, never persisted or+ /// logged. Treat like a password.+ pub token: String,+ /// The token's stable identifier (= `sha256(secret)` hex). Safe to+ /// show/store; this is what `DELETE /auth/api-tokens/:id` takes.+ pub id: String,+ pub name: String,+ pub scopes: Vec<String>,+ pub created_at: String,+}++pub async fn create(+ State(state): State<ConsoleState>,+ sess: AuthSession,+ Json(body): Json<CreateBody>,+) -> ConsoleResult<Response> {+ let name = body.name.trim().to_string();+ if name.is_empty() {+ return Err(ConsoleApiError::BadRequest("missing token name".into()));+ }++ // Random secret. URL-safe base64, no padding — same shape as magic+ // links so it survives a copy-paste into an `Authorization` header.+ let mut bytes = [0u8; TOKEN_BYTES];+ rand::thread_rng().fill_bytes(&mut bytes);+ let secret = URL_SAFE_NO_PAD.encode(bytes);+ let hash = sha256_hex(secret.as_bytes());++ let now = now_iso();+ let token = store::ApiToken {+ id: hash.clone(),+ user_id: sess.user.id.clone(),+ name: name.clone(),+ scopes: body.scopes.clone(),+ created_at: now.clone(),+ last_used_at: None,+ revoked_at: None,+ };+ store::put_api_token(&state.engine, &token).await?;++ audit::record(+ &state.engine,+ &sess.user.id,+ "api-token-issued",+ indices::API_TOKENS,+ Some(&hash),+ None,+ Some(json!({ "name": name.clone() })),+ )+ .await;++ Ok(ok(+ CreatedToken {+ token: secret,+ id: hash,+ name,+ scopes: token.scopes,+ created_at: now,+ },+ None,+ ))+}++// ─────────────────────────────────────────────────────────────────────────────+// List+// ─────────────────────────────────────────────────────────────────────────────++#[derive(Debug, Serialize)]+pub struct TokenListItem {+ /// Stable id (= `sha256(secret)` hex). Never the plaintext secret.+ pub id: String,+ pub name: String,+ pub scopes: Vec<String>,+ pub created_at: String,+ pub last_used_at: Option<String>,+ pub revoked_at: Option<String>,+}++pub async fn list(State(state): State<ConsoleState>, sess: AuthSession) -> ConsoleResult<Response> {+ let tokens = store::list_api_tokens_for_user(&state.engine, &sess.user.id).await?;+ let items: Vec<TokenListItem> = tokens+ .into_iter()+ .map(|t| TokenListItem {+ id: t.id,+ name: t.name,+ scopes: t.scopes,+ created_at: t.created_at,+ last_used_at: t.last_used_at,+ revoked_at: t.revoked_at,+ })+ .collect();+ Ok(ok(json!({ "tokens": items }), None))+}++// ─────────────────────────────────────────────────────────────────────────────+// Revoke+// ─────────────────────────────────────────────────────────────────────────────++pub async fn revoke(+ State(state): State<ConsoleState>,+ sess: AuthSession,+ axum::extract::Path(id): axum::extract::Path<String>,+) -> ConsoleResult<Response> {+ // Look the token up by id (= hash). A token that does not exist, or one+ // owned by a different user, both return 404 — we never confirm the+ // existence of another user's token id.+ let mut token = match store::get_api_token(&state.engine, &id).await? {+ Some(t) if t.user_id == sess.user.id => t,+ _ => return Err(ConsoleApiError::NotFound("api token".into())),+ };++ // Idempotent: revoking an already-revoked token is a no-op success.+ if token.revoked_at.is_none() {+ token.revoked_at = Some(now_iso());+ store::put_api_token(&state.engine, &token).await?;+ audit::record(+ &state.engine,+ &sess.user.id,+ "api-token-revoked",+ indices::API_TOKENS,+ Some(&token.id),+ None,+ None,+ )+ .await;+ }++ Ok(no_content())+}diff --git a/engine/crates/xerj-console-api/src/router.rs b/engine/crates/xerj-console-api/src/router.rsindex 2ba0a82cc..a3278c996 100644--- a/engine/crates/xerj-console-api/src/router.rs+++ b/engine/crates/xerj-console-api/src/router.rs@@ -82,6 +82,14 @@ pub fn xerj_console_router(state: ConsoleState) -> Router {"/_xerj-console/api/v1/auth/passkeys/:id",delete(auth::me::delete_passkey),)+ .route(+ "/_xerj-console/api/v1/auth/api-tokens",+ get(auth::tokens::list).post(auth::tokens::create),+ )+ .route(+ "/_xerj-console/api/v1/auth/api-tokens/:id",+ delete(auth::tokens::revoke),+ ).route("/_xerj-console/api/v1/prefs",get(prefs::get).put(prefs::put),@@ -141,6 +149,8 @@ pub fn known_routes() -> &'static [&'static str] {"/_xerj-console/api/v1/me","/_xerj-console/api/v1/auth/passkeys","/_xerj-console/api/v1/auth/passkeys/:id",+ "/_xerj-console/api/v1/auth/api-tokens",+ "/_xerj-console/api/v1/auth/api-tokens/:id","/_xerj-console/api/v1/prefs","/_xerj-console/api/v1/dashboards","/_xerj-console/api/v1/dashboards/:id",diff --git a/engine/crates/xerj-console-api/tests/api_tokens_flow.rs b/engine/crates/xerj-console-api/tests/api_tokens_flow.rsnew file mode 100644index 000000000..5c94d12af--- /dev/null+++ b/engine/crates/xerj-console-api/tests/api_tokens_flow.rs@@ -0,0 +1,223 @@+//! End-to-end test for the API-token surface (issue / list / revoke) and+//! `Authorization: Bearer` authentication.+//!+//! WebAuthn can't be driven from a pure-Rust test (no browser+//! authenticator), so instead of walking the passkey enrolment flow we+//! seed an active user directly and mint a signed session cookie with the+//! same `sessions::mint_session` the login handler uses. That cookie+//! authenticates the issue/list/revoke calls; the minted token then+//! authenticates a protected endpoint over Bearer.+//!+//! Proven here:+//! - `POST /auth/api-tokens` returns the plaintext secret exactly once.+//! - `GET /auth/api-tokens` lists only the hash/metadata — no plaintext.+//! - the plaintext used as `Authorization: Bearer` authenticates `/me`.+//! - `DELETE /auth/api-tokens/:id` revokes it → the same Bearer call 401s.+//! - issuing a token without a session is rejected (401).++use axum::{body::Body, http::Request, Router};+use http_body_util::BodyExt;+use serde_json::{json, Value};+use tempfile::TempDir;+use tower::ServiceExt;+use xerj_common::config::Config;+use xerj_console_api::auth::{sessions, store};+use xerj_console_api::{state::ClusterMode, xerj_console_router, ConsoleState};+use xerj_engine::Engine;++async fn boot() -> (Engine, ConsoleState, Router, TempDir) {+ let dir = TempDir::new().unwrap();+ let mut cfg = Config::default();+ cfg.server.data_dir = dir.path().to_str().unwrap().to_string();+ let engine = Engine::new(cfg).expect("engine");+ let outcome = xerj_console_api::bootstrap::run(&engine, dir.path(), "http://localhost:9200")+ .await+ .expect("bootstrap");+ let state = ConsoleState::new(+ engine.clone(),+ "local".into(),+ outcome.master_key,+ ClusterMode::Standalone,+ );+ let router = xerj_console_router(state.clone());+ (engine, state, router, dir)+}++async fn body_json(resp: axum::response::Response) -> (axum::http::StatusCode, Value) {+ let status = resp.status();+ let bytes = resp.into_body().collect().await.unwrap().to_bytes();+ let v = if bytes.is_empty() {+ Value::Null+ } else {+ serde_json::from_slice(&bytes).unwrap_or(Value::Null)+ };+ (status, v)+}++/// Seed an active user + a signed session cookie for it. Returns the+/// `Cookie:` header value the session-protected endpoints accept.+async fn seed_user_and_cookie(engine: &Engine, state: &ConsoleState) -> (String, String) {+ let user = store::User {+ id: "u-token-test".into(),+ email: "[email protected]".into(),+ display_name: "Owner".into(),+ role: "owner".into(),+ status: store::UserStatus::Active,+ created_at: "2026-01-01T00:00:00.000Z".into(),+ last_seen_at: None,+ };+ store::upsert_user(engine, &user).await.unwrap();++ let (_sess, signed) = sessions::mint_session(state, &user.id, "passkey", None, None)+ .await+ .unwrap();+ (user.id, format!("{}={}", sessions::COOKIE_NAME, signed))+}++#[tokio::test]+async fn api_token_issue_list_bearer_and_revoke() {+ let (engine, state, router, _dir) = boot().await;+ let (user_id, cookie) = seed_user_and_cookie(&engine, &state).await;++ // ── Issue ──────────────────────────────────────────────────────────+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/_xerj-console/api/v1/auth/api-tokens")+ .header("content-type", "application/json")+ .header("cookie", &cookie)+ .body(Body::from(+ json!({ "name": "ci-token", "scopes": ["read"] }).to_string(),+ ))+ .unwrap(),+ )+ .await+ .unwrap();+ let (status, body) = body_json(resp).await;+ assert_eq!(status, 200, "issue must succeed: {body}");+ let plaintext = body["data"]["token"].as_str().unwrap().to_string();+ let token_id = body["data"]["id"].as_str().unwrap().to_string();+ assert!(+ plaintext.len() >= 40,+ "secret should be 32 bytes url-safe b64"+ );+ assert_ne!(plaintext, token_id, "id must be the hash, not the secret");+ assert_eq!(body["data"]["name"], "ci-token");++ // ── List: metadata only, never the plaintext ───────────────────────+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/_xerj-console/api/v1/auth/api-tokens")+ .header("cookie", &cookie)+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ let (status, body) = body_json(resp).await;+ assert_eq!(status, 200, "list must succeed: {body}");+ let tokens = body["data"]["tokens"].as_array().unwrap();+ assert_eq!(tokens.len(), 1, "exactly one token: {body}");+ assert_eq!(tokens[0]["id"], token_id);+ assert!(+ !body.to_string().contains(&plaintext),+ "plaintext secret leaked into the list response"+ );++ // ── Bearer auth on a protected endpoint → 200 ──────────────────────+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/_xerj-console/api/v1/me")+ .header("authorization", format!("Bearer {plaintext}"))+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ let (status, body) = body_json(resp).await;+ assert_eq!(status, 200, "bearer auth must authenticate: {body}");+ assert_eq!(body["data"]["user"]["id"], user_id);++ // ── Revoke ─────────────────────────────────────────────────────────+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("DELETE")+ .uri(format!("/_xerj-console/api/v1/auth/api-tokens/{token_id}"))+ .header("cookie", &cookie)+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), 204, "revoke must return 204");++ // ── Same Bearer call now 401s ──────────────────────────────────────+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/_xerj-console/api/v1/me")+ .header("authorization", format!("Bearer {plaintext}"))+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(+ resp.status(),+ 401,+ "a revoked token must no longer authenticate"+ );+}++#[tokio::test]+async fn api_token_issue_requires_a_session() {+ let (_engine, _state, router, _dir) = boot().await;++ // No cookie, no bearer → the AuthSession extractor rejects with 401.+ let resp = router+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/_xerj-console/api/v1/auth/api-tokens")+ .header("content-type", "application/json")+ .body(Body::from(json!({ "name": "x" }).to_string()))+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), 401, "issuing a token needs authentication");+}++#[tokio::test]+async fn bogus_bearer_token_is_rejected() {+ let (_engine, _state, router, _dir) = boot().await;++ let resp = router+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/_xerj-console/api/v1/me")+ .header("authorization", "Bearer not-a-real-token")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(+ resp.status(),+ 401,+ "unknown bearer token must not authenticate"+ );+}