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.

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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
new file mode 100644
index 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"
+ );
+}