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(security): reserve the `superuser`/`unscoped` labels, drop unverifiable key records
xerj-orgd33a468a6a8b
diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.mdindex a30f35e41..1f2860552 100644--- a/docs/SECURITY_MODEL.md+++ b/docs/SECURITY_MODEL.md@@ -274,6 +274,20 @@ secret under that record's salt and compares digests in constant timeon boot — hashed, and the file rewritten without the plaintext — before theserver accepts a request.+Exactly two on-disk shapes are credentials: a `secret_hash` that decodes (the+post-#201 form, and the winner whenever both are present), and a non-empty+`secret` with no `secret_hash` at all (the pre-#201 form, which is what+migration is for). Every other record is **dropped on load with an error** —+including one whose `secret_hash` carries the `$ssha256$` tag but does not+decode, from a hand edit or an encoding a later build wrote. Nothing could ever+authenticate as such a record, so restoring it and listing it through+`GET /_security/api_key` would be a lie about which credentials exist. The+discriminator is `secret_hash::is_usable_hash`, a full decode rather than a tag+check, and both the load path and `verify_secret` use that one function so they+cannot disagree about what counts as a credential. The drop is in memory: the+file is only rewritten when something migrated, so a dropped record normally+stays on disk for inspection.+The hash is deliberately *fast*, not a password hash. The secret is two v4UUIDs of CSPRNG output (244 bits), never chosen or reused by a human, so anoffline guessing attack is not the threat; a per-request Argon2/scrypt would@@ -301,12 +315,33 @@ would be true. Before #201 this endpoint answered `superuser` for every caller.One deliberate divergence from ES: ES reports `roles: []` for an API-key calland expects the client to read `GET /_security/api_key` for the descriptors.xerj reports the names instead, because it has no named-role store to point at.-The divergence is additive and never over-states a key's reach.++Because those names are caller-chosen free text, `superuser` and `unscoped` —+the two labels xerj assigns on its own authority — are **not mintable from a+`role_descriptors` key**. A descriptor named `superuser` is reported as+`api_key_role:superuser` (`es_compat.rs`, `reported_role_label`), so a key+confined to `logs-*` by that descriptor cannot be handed back a `roles` array+that reads as the superuser. Without that guard the divergence would re-open+the exact drift this endpoint was fixed for: one `POST /_security/api_key` with+the right descriptor name and `_authenticate` says `{"roles":["superuser"]}`+for a read-only key. With it, the divergence is additive and no key is+described as holding more than it holds. The guarantee is specifically that no+caller-chosen name yields `superuser` or `unscoped`; the qualified form is not+itself reserved, so a descriptor literally named `api_key_role:superuser` comes+back verbatim — that collides with another caller's name, not with a label xerj+assigns.`POST /_security/user/_has_privileges` is **not** fixed: it still answers `true`to every privilege named in the request, which is wrong for a scoped key. Treatit as a stub, not as an authorization oracle.+Neither are the Kibana user-profile routes (`POST /_security/profile/_activate`,+`GET /_security/profile/{uid}`): they return one fixed built-in profile whose+`user.roles` is `["superuser"]` for every caller, because xerj has a single+owner identity and these exist to get Kibana's bootstrap past a 404. They+describe that owner, not the credential that called them. `_authenticate` is+the endpoint that answers "who am I".+### Privileges that exist but are not decided`Privilege` (`rbac.rs:34-49`) has seven variants. Only three of them are everdiff --git a/engine/crates/xerj-api/src/es_compat.rs b/engine/crates/xerj-api/src/es_compat.rsindex a4065f68e..c7e148ed4 100644--- a/engine/crates/xerj-api/src/es_compat.rs+++ b/engine/crates/xerj-api/src/es_compat.rs@@ -25970,6 +25970,13 @@ pub async fn xpack_usage(State(state): State<AppState>) -> impl IntoResponse {/// caller that only checks for `"superuser"` behaves identically, and no key/// is described as holding more than it holds.///+/// That last sentence is only true because of [`reported_role_label`]: a+/// `role_descriptors` key is caller-chosen free text, so without a guard+/// `POST /_security/api_key {"role_descriptors":{"superuser":{"indices":+/// [{"names":["logs-*"],...}]}}}` would make this endpoint answer+/// `{"roles":["superuser"]}` for a key confined to `logs-*` — the exact drift+/// this handler exists to remove, re-entered through a name.+////// Deliberately *not* fixed here: `POST /_security/user/_has_privileges` still/// answers `true` to everything (see its own handler). Reporting honest roles/// beside a lying privilege oracle is an improvement, not a completion.@@ -25988,8 +25995,14 @@ pub async fn security_authenticate(// `indices` entries becomes three internal `Role`s named `r[0]`,// `r[1]`, `r[2]` (`rbac::roles_from_role_descriptors`), and reporting// that encoding back would describe roles the caller never named.+ // Names that collide with a label xerj assigns itself are qualified+ // first — see `reported_role_label`.Principal::Scoped { key_id, roles } => (- dedup_in_order(roles.iter().map(|r| r.descriptor_name())),+ dedup_in_order(+ roles+ .iter()+ .map(|r| reported_role_label(r.descriptor_name())),+ ),Some((key_id.clone(), key_name(&state, key_id))),),// A key minted without usable `role_descriptors`. Reporting `[]` would@@ -26061,16 +26074,61 @@ fn key_name(state: &AppState, key_id: &str) -> String {/// repeats. Role lists here are single digits long, so the linear `contains`/// is cheaper than a set and keeps the output deterministic — a response that/// reordered its own roles between calls would be a nuisance to diff.-fn dedup_in_order<'a>(items: impl Iterator<Item = &'a str>) -> Vec<String> {+fn dedup_in_order<'a>(items: impl Iterator<Item = std::borrow::Cow<'a, str>>) -> Vec<String> {let mut out: Vec<String> = Vec::new();for item in items {- if !out.iter().any(|seen| seen == item) {- out.push(item.to_string());+ if !out.iter().any(|seen| seen.as_str() == item.as_ref()) {+ out.push(item.into_owned());}}out}+/// Labels `security_authenticate` assigns on xerj's own authority, and which+/// therefore mean something in every response: `superuser` is the admin+/// credential (or open mode), `unscoped` is a key minted without usable+/// `role_descriptors`. Keep in step with the match arms above — these are+/// exactly the strings those arms emit.+const XERJ_ASSIGNED_ROLE_LABELS: [&str; 2] = ["superuser", "unscoped"];++/// Prefix applied to a caller-chosen descriptor name that collides with one of+/// [`XERJ_ASSIGNED_ROLE_LABELS`].+const QUALIFIED_DESCRIPTOR_PREFIX: &str = "api_key_role:";++/// What a scoped key's `role_descriptors` name is reported as in `roles`.+///+/// A descriptor name is free text the caller chose at mint time, and `roles`+/// is read by clients as an authorization summary. Reporting it verbatim lets+/// a caller name a descriptor `superuser`, be confined to `logs-*` by that+/// very descriptor, and then be told by `GET /_security/_authenticate` that it+/// holds `["superuser"]` — the "you are more privileged than you are" drift+/// issue #201 removes, re-entered through a name. So the two labels xerj+/// assigns on its own authority are not mintable from caller input: a+/// descriptor named `superuser` or `unscoped` is reported qualified, as+/// `api_key_role:superuser`, which is still the name the caller wrote (nothing+/// is hidden) but can no longer be mistaken for the label xerj hands out.+///+/// Elasticsearch never has this problem because it reports `roles: []` for an+/// API-key call at all (`ApiKeyService.java:1641`) while keeping `superuser`+/// in a platform-owned store a caller cannot write into+/// (`ReservedRolesStore.java:188`, both APPROACH-ONLY reads — AGPL/Elastic, no+/// code taken). xerj answers the more useful question instead, so it has to+/// own the namespace explicitly; this is that ownership.+///+/// The guarantee is precisely "no caller-chosen name yields a label from+/// [`XERJ_ASSIGNED_ROLE_LABELS`]". It is *not* that the qualified form is+/// itself reserved: a caller may name a descriptor `api_key_role:superuser`+/// and get it back verbatim. That collides with another caller-chosen name,+/// not with a label xerj assigns, so it cannot make a key look like the+/// superuser.+fn reported_role_label(descriptor_name: &str) -> std::borrow::Cow<'_, str> {+ if XERJ_ASSIGNED_ROLE_LABELS.contains(&descriptor_name) {+ std::borrow::Cow::Owned(format!("{QUALIFIED_DESCRIPTOR_PREFIX}{descriptor_name}"))+ } else {+ std::borrow::Cow::Borrowed(descriptor_name)+ }+}+// ─────────────────────────────────────────────────────────────────────────────// GET/POST /_security/user/_has_privileges// GET/POST /_security/user/{user}/_has_privilegesdiff --git a/engine/crates/xerj-api/tests/api_key_secrets_are_hashed_at_rest.rs b/engine/crates/xerj-api/tests/api_key_secrets_are_hashed_at_rest.rsindex d14a38167..bcb3d8546 100644--- a/engine/crates/xerj-api/tests/api_key_secrets_are_hashed_at_rest.rs+++ b/engine/crates/xerj-api/tests/api_key_secrets_are_hashed_at_rest.rs@@ -300,6 +300,56 @@ async fn authenticate_describes_the_credential_that_called_it() {assert_eq!(me["authentication_type"], "api_key");}+/// A `role_descriptors` key is caller-chosen free text, and `_authenticate`+/// reports those names in `roles` — so nothing may stop a caller from *naming*+/// a descriptor `superuser` and being handed `{"roles":["superuser"]}` back for+/// a key confined to `logs-*`. That is the same "you are more privileged than+/// you are" drift #201 exists to remove, re-entered through a name.+///+/// `superuser` and `unscoped` are the two labels xerj assigns itself in this+/// field; a caller-chosen descriptor must never be able to produce either.+#[tokio::test]+async fn a_descriptor_name_cannot_forge_a_xerj_assigned_role_label() {+ let dir = tempfile::tempdir().expect("tempdir");+ let state = state_over(dir.path().to_str().unwrap());+ let app = build_es_compat_router(state);++ for forged in ["superuser", "unscoped"] {+ let (_id, _secret, auth) = mint(+ &app,+ &format!(+ r#"{{"name":"pretender-{forged}","role_descriptors":{{"{forged}":{{"indices":[+ {{"names":["logs-*"],"privileges":["read"]}}]}}}}}}"#+ ),+ )+ .await;++ let (status, me) = send(&app, "GET", "/_security/_authenticate", &auth, "").await;+ assert_eq!(status, StatusCode::OK);+ let roles = me["roles"].as_array().expect("roles array");+ assert!(+ !roles.iter().any(|r| r == forged),+ "a key confined to logs-* reported the reserved label {forged:?}: {me}"+ );++ // The grant itself is unaffected — this is about what the key is+ // *told* it holds, not about narrowing what it holds. A read inside+ // the granted pattern still works; one outside it is still refused.+ let (status, body) = send(&app, "GET", "/logs-app/_search", &auth, "").await;+ assert_ne!(+ status,+ StatusCode::FORBIDDEN,+ "the logs-* grant must survive the label fix: {body}"+ );+ let (status, body) = send(&app, "GET", "/.xerj-memory-alice/_search", &auth, "").await;+ assert_eq!(+ status,+ StatusCode::FORBIDDEN,+ "a logs-* key must not reach the reserved namespace: {body}"+ );+ }+}+/// `GET /_security/api_key` must describe a key with the descriptor names the/// caller minted it with. It used to key `role_descriptors` by the internal/// per-entry role name, so one `reader` descriptor over two index sets came@@ -355,6 +405,67 @@ async fn listing_a_key_reports_the_descriptors_it_was_minted_with() {);}+/// A record that carries a `secret_hash` which is *present but not a hash*+/// (truncated by a half-written file, mangled by a hand edit, written by a+/// future scheme this build does not know) can never authenticate: every+/// verifier in `secret_hash.rs` denies what it cannot decode. Keeping such a+/// record would list it through `GET /_security/api_key` as a live credential+/// that nothing can ever use — the accept-then-ignore shape issue #204 tracks,+/// and exactly what the empty-hash case is already dropped to avoid.+///+/// The discriminator is `secret_hash::is_usable_hash`, not `is_empty`.+#[tokio::test]+async fn an_unusable_secret_hash_is_dropped_not_listed_as_live() {+ for (case, stored) in [+ ("empty", ""),+ ("truncated", "$ssha256$truncated"),+ ("wrong-scheme", "$argon2id$v=19$m=1,t=1,p=1$c2FsdA$aGFzaA"),+ ("bare-plaintext-leftover", "not-a-hash-at-all"),+ ] {+ let dir = tempfile::tempdir().expect("tempdir");+ let id = "99999999-8888-7777-6666-555555555555";+ std::fs::write(+ dir.path().join("api_keys.json"),+ format!(+ r#"{{"{id}":{{"name":"bricked-{case}","secret_hash":"{stored}",+ "creation_ms":1753600000000,"expiration_ms":null,+ "invalidated":false}}}}"#+ ),+ )+ .expect("seed store");++ let state = state_over(dir.path().to_str().unwrap());+ let app = build_es_compat_router(state);++ let (status, body) = send(&app, "GET", "/_security/api_key", &admin(), "").await;+ assert_eq!(status, StatusCode::OK, "{body}");+ assert_eq!(+ body["api_keys"].as_array().map(Vec::len),+ Some(0),+ "[{case}] a record that can never authenticate was listed as a live key: {body}"+ );++ // And it must not authenticate either — including with the stored+ // string presented as if it were the secret.+ for presented in [stored, "anything"] {+ let encoded = b64(&format!("{id}:{presented}"));+ let (status, _) = send(+ &app,+ "GET",+ "/_cluster/health",+ &format!("ApiKey {encoded}"),+ "",+ )+ .await;+ assert_eq!(+ status,+ StatusCode::UNAUTHORIZED,+ "[{case}] a record with an unusable hash authenticated"+ );+ }+ }+}+// ─────────────────────────────────────────────────────────────────────────────// 3. The audit chain must outlive the process// ─────────────────────────────────────────────────────────────────────────────diff --git a/engine/crates/xerj-engine/src/engine.rs b/engine/crates/xerj-engine/src/engine.rsindex 14a4758f0..0e37f45f5 100644--- a/engine/crates/xerj-engine/src/engine.rs+++ b/engine/crates/xerj-engine/src/engine.rs@@ -206,9 +206,12 @@ pub struct ApiKeyRecord {////// `#[serde(default)]` so a pre-#201 `api_keys.json` — which has `secret`/// and no `secret_hash` — still deserializes; [`Engine::load_persisted_api_keys`]- /// then migrates it. An empty value here means "not migrated yet", and a- /// record that reaches the auth path with one cannot authenticate (see- /// [`ApiKeyRecord::verify_secret`]).+ /// then migrates it. Anything here that+ /// [`crate::secret_hash::is_usable_hash`] rejects — empty (never migrated), or+ /// present but unparseable (truncated write, hand edit, a scheme this+ /// build does not know) — means "no usable credential": the load path+ /// drops such a record and [`ApiKeyRecord::verify_secret`] denies it if+ /// one ever reaches the auth path anyway.#[serde(default)]secret_hash: String,/// Pre-#201 plaintext secret, read only so it can be migrated away.@@ -278,12 +281,15 @@ impl ApiKeyRecord {/// Does `presented` match this record's secret?///- /// Fail-closed on a record that was never migrated (empty `secret_hash`):+ /// Fail-closed on a record that carries no usable hash — never migrated+ /// (empty), or present but not one of our encodings./// [`Engine::load_persisted_api_keys`] drops those before they can reach- /// here, but if one ever did, "no stored hash" must mean "no", never- /// "yes".+ /// here, but if one ever did, "no usable stored hash" must mean "no",+ /// never "yes". [`crate::secret_hash::is_usable_hash`] is the discriminator,+ /// the same one the load path uses, so the two cannot disagree about what+ /// counts as a credential.pub fn verify_secret(&self, presented: &str) -> bool {- if self.secret_hash.is_empty() {+ if !crate::secret_hash::is_usable_hash(&self.secret_hash) {return false;}crate::secret_hash::verify_secret(presented, &self.secret_hash)@@ -295,21 +301,48 @@ impl ApiKeyRecord {/// `Err(())` means the record carries no usable credential in either form/// and must be dropped rather than kept as a key that silently never/// authenticates.+ ///+ /// "Usable credential" is [`crate::secret_hash::is_usable_hash`], which is+ /// a full decode — **not** `!secret_hash.is_empty()`, and not a check of+ /// the `$ssha256$` tag either. A `secret_hash` that carries the tag but+ /// does not decode (`"$ssha256$truncated"` from a hand edit, a scheme a+ /// future build writes and this one cannot read) is denied by every+ /// verifier, so a record holding only that can never authenticate.+ /// Restoring it would leave a key `GET /_security/api_key` lists as live+ /// while nothing can ever use it — the accept-then-ignore shape issue #204+ /// tracks, and exactly what dropping the empty case already avoids. Only+ /// the two shapes that really are credentials survive:+ ///+ /// * a `secret_hash` that decodes — the post-#201 shape, and the winner+ /// whenever both forms are present;+ /// * a non-empty `secret` and **no** `secret_hash` at all — the exact+ /// pre-#201 shape, which is what migration is for.+ ///+ /// Anything else is dropped rather than repaired. A record carrying both a+ /// plaintext and a hash-shaped value that does not decode is a store+ /// nobody can explain; deriving a live credential from the half of it that+ /// #201 exists to delete is the fail-open reading of an ambiguous record,+ /// and this is a credential path.+ ///+ /// The drop is in memory. `load_persisted_api_keys` only rewrites the file+ /// when something migrated, so a dropped record normally stays on disk for+ /// the operator to inspect after the error log points at it.fn migrate_from_plaintext(&mut self) -> std::result::Result<bool, ()> {- match self.legacy_plaintext_secret.take() {- // Both forms present: a half-written or hand-edited file. The hash- // wins and the plaintext is discarded — dropping it is the whole- // point, and re-deriving from plaintext could silently swap the- // credential the record authenticates.- Some(_) if !self.secret_hash.is_empty() => Ok(true),- Some(plain) if !plain.is_empty() => {+ let plaintext = self.legacy_plaintext_secret.take();+ if crate::secret_hash::is_usable_hash(&self.secret_hash) {+ // The hash is the credential. A leftover plaintext beside it is+ // discarded — dropping it is the whole point, and re-deriving from+ // it could silently swap which secret the record authenticates.+ // `Some` means the file still held plaintext, so it must be+ // rewritten.+ return Ok(plaintext.is_some());+ }+ match plaintext {+ Some(plain) if !plain.is_empty() && self.secret_hash.is_empty() => {self.secret_hash = crate::secret_hash::hash_secret(&plain);Ok(true)}- // No plaintext, and no (or empty) hash: nothing to authenticate- // against, in either direction.- _ if self.secret_hash.is_empty() => Err(()),- _ => Ok(false),+ _ => Err(()),}}}@@ -1153,14 +1186,18 @@ impl Engine {/// records are hashed here and the file is rewritten **during boot**,/// before the server accepts a request, so an upgraded node stops leaking/// on first start rather than on first key rotation. The migration is- /// one-way and needs no flag day: [`crate::secret_hash::is_hashed`]- /// distinguishes the two forms, and an already-migrated store is untouched.+ /// one-way and needs no flag day: [`crate::secret_hash::is_usable_hash`]+ /// is the discriminator ([`ApiKeyRecord::migrate_from_plaintext`] calls+ /// it), so a store whose hashes decode is untouched, and only the exact+ /// pre-#201 shape — a `secret` and no `secret_hash` at all — is migrated.///- /// A record with neither a hash nor a plaintext secret is **dropped with an+ /// A record that is neither of those two shapes is **dropped with an/// error**, not kept: keeping it would leave an entry that `GET/// /_security/api_key` lists as a live credential while nothing can ever/// authenticate as it — precisely the accept-then-ignore behaviour that- /// issue #204 tracks.+ /// issue #204 tracks. Since "usable" is a full decode, a `secret_hash`+ /// that is present but unparseable is dropped exactly like an absent one;+ /// both are equally unauthenticatable.fn load_persisted_api_keys(&self) {let path = self.api_keys_path();let Ok(bytes) = std::fs::read(&path) else {@@ -1184,9 +1221,12 @@ impl Engine {dropped += 1;error!(key_id = %id,- "api_keys.json record has neither a hashed nor a plaintext \- secret — dropping it; nothing could ever authenticate as \- this key and listing it would be a lie"+ "api_keys.json record is not a credential this build can \+ use: its secret_hash does not decode (absent, truncated, \+ or an encoding this build does not know) and it is not \+ the pre-#201 plaintext shape either — dropping it; \+ nothing could ever authenticate as this key and listing \+ it would be a lie");}}@@ -2416,3 +2456,115 @@ mod snapshot_path_security_tests {assert!(err2.to_string().contains(".."), "unexpected error: {err2}");}}++#[cfg(test)]+mod api_key_record_migration_tests {+ use super::ApiKeyRecord;++ /// A record as it comes off disk, before the load path touches it.+ fn loaded(secret_hash: &str, plaintext: Option<&str>) -> ApiKeyRecord {+ ApiKeyRecord {+ name: "loaded".to_string(),+ secret_hash: secret_hash.to_string(),+ legacy_plaintext_secret: plaintext.map(str::to_string),+ creation_ms: 1_753_600_000_000,+ expiration_ms: None,+ invalidated: false,+ invalidation_ms: None,+ roles: Vec::new(),+ }+ }++ /// The discriminator is `is_usable_hash`, not `is_empty` and not a check+ /// of the `$ssha256$` tag: a `secret_hash` that does not decode can never+ /// verify against anything, so a record carrying only that is as unusable+ /// as one carrying nothing and must be dropped, not restored as a live+ /// key. Three of these carry the tag — a prefix test would call them+ /// migrated and keep them.+ #[test]+ fn an_unparseable_hash_with_no_plaintext_is_dropped() {+ for stored in [+ "",+ "$ssha256$",+ "$ssha256$truncated",+ "$ssha256$deadbeef$cafe",+ "$argon2id$v=19$m=1,t=1,p=1$c2FsdA$aGFzaA",+ "left-over-plaintext",+ ] {+ for plaintext in [None, Some("")] {+ let mut rec = loaded(stored, plaintext);+ assert_eq!(+ rec.migrate_from_plaintext(),+ Err(()),+ "{stored:?} + {plaintext:?} must be dropped, not restored"+ );+ }+ }+ }++ /// A plaintext beside a hash-shaped value that does not decode is a store+ /// nobody can explain — not the pre-#201 shape (that has no `secret_hash`+ /// at all), and not a migrated one. Deriving a live credential from the+ /// half of it #201 exists to delete is the fail-open reading, so the+ /// record is dropped instead.+ #[test]+ fn a_plaintext_beside_an_unparseable_hash_is_dropped_not_repaired() {+ for stored in [+ "$ssha256$truncated",+ "$argon2id$v=19$m=1,t=1,p=1$c2FsdA$aGFzaA",+ "left-over-plaintext",+ ] {+ let mut rec = loaded(stored, Some("the-plaintext"));+ assert_eq!(+ rec.migrate_from_plaintext(),+ Err(()),+ "{stored:?} + a plaintext is ambiguous and must be dropped"+ );+ }+ }++ /// A usable hash still wins over a leftover plaintext, and the plaintext is+ /// discarded — re-deriving there could silently swap which secret the+ /// record authenticates.+ #[test]+ fn a_usable_hash_wins_over_a_leftover_plaintext() {+ let hash = crate::secret_hash::hash_secret("hashed-secret");+ let mut rec = loaded(&hash, Some("stale-plaintext"));+ assert_eq!(rec.migrate_from_plaintext(), Ok(true));+ assert_eq!(rec.secret_hash, hash);+ assert!(rec.legacy_plaintext_secret.is_none());+ assert!(rec.verify_secret("hashed-secret"));+ assert!(!rec.verify_secret("stale-plaintext"));+ }++ /// An already-migrated record is left alone and reports no rewrite.+ #[test]+ fn an_already_hashed_record_is_untouched() {+ let hash = crate::secret_hash::hash_secret("s");+ let mut rec = loaded(&hash, None);+ assert_eq!(rec.migrate_from_plaintext(), Ok(false));+ assert_eq!(rec.secret_hash, hash);+ }++ /// The pre-#201 shape: plaintext only.+ #[test]+ fn a_pre_201_plaintext_record_is_hashed() {+ let mut rec = loaded("", Some("legacy-secret"));+ assert_eq!(rec.migrate_from_plaintext(), Ok(true));+ assert!(crate::secret_hash::is_usable_hash(&rec.secret_hash));+ assert!(rec.verify_secret("legacy-secret"));+ }++ /// Even if one reached the auth path unmigrated, an unusable hash denies.+ #[test]+ fn verify_secret_denies_an_unusable_hash() {+ for stored in ["", "$ssha256$truncated", "plaintext-secret"] {+ let rec = loaded(stored, None);+ assert!(+ !rec.verify_secret(stored),+ "{stored:?} must not verify against itself"+ );+ assert!(!rec.verify_secret("anything"));+ }+ }+}diff --git a/engine/crates/xerj-engine/src/secret_hash.rs b/engine/crates/xerj-engine/src/secret_hash.rsindex 9c716f60a..ea8360712 100644--- a/engine/crates/xerj-engine/src/secret_hash.rs+++ b/engine/crates/xerj-engine/src/secret_hash.rs@@ -36,8 +36,10 @@//!//! `$ssha256$<32 hex salt chars>$<64 hex digest chars>` — self-describing, so//! a future algorithm can be added without a migration flag day and old-//! records keep verifying. [`is_hashed`] is the discriminator that tells a-//! stored hash apart from a pre-#201 plaintext secret.+//! records keep verifying. [`is_usable_hash`] is the discriminator the load+//! path uses to tell a credential this build can actually check apart from a+//! pre-#201 plaintext secret — or from a corrupt record that can never+//! authenticate at all.use sha2::{Digest, Sha256};@@ -73,15 +75,22 @@ pub fn verify_secret(presented: &str, stored: &str) -> bool {constant_time_eq(&digest(&salt, presented), &expected)}-/// Does `stored` look like one of our hash encodings (as opposed to a-/// pre-#201 plaintext secret)?+/// Is `stored` a hash this build can actually verify a secret against?///-/// Used by the load path to decide whether a persisted record needs-/// migrating. It only inspects the scheme tag: a value that starts with the-/// tag but is malformed is still *not* plaintext, and must not be re-hashed-/// as if it were a secret.-pub fn is_hashed(stored: &str) -> bool {- stored.starts_with(SSHA256_PREFIX)+/// The discriminator the load path uses+/// (`Engine::load_persisted_api_keys` → `ApiKeyRecord::migrate_from_plaintext`)+/// and the same one `ApiKeyRecord::verify_secret` fails closed on, so the two+/// cannot disagree about what counts as a credential.+///+/// It is a **full parse**, not a scheme-tag check, and that distinction is+/// load-bearing: `"$ssha256$truncated"` carries the tag but decodes to+/// nothing, so [`verify_secret`] denies it against every input. A prefix test+/// would call that record "already hashed" and restore it — leaving a key+/// that `GET /_security/api_key` lists as live while nothing can ever+/// authenticate as it, which is exactly the accept-then-ignore shape issue+/// #204 tracks. "Tagged" is not "usable"; only "decodes" is.+pub fn is_usable_hash(stored: &str) -> bool {+ decode(stored).is_some()}// ── internals ────────────────────────────────────────────────────────────────@@ -158,7 +167,7 @@ mod tests {#[test]fn round_trips() {let stored = hash_secret("s3cr3t");- assert!(is_hashed(&stored));+ assert!(is_usable_hash(&stored));assert!(verify_secret("s3cr3t", &stored));assert!(!verify_secret("s3cr3T", &stored));assert!(!verify_secret("", &stored));@@ -196,8 +205,16 @@ mod tests {!verify_secret("plaintext-secret", stored),"unrecognised stored form {stored:?} must not verify");+ // The two must agree exactly: anything that can never verify is+ // also not a usable hash, so the load path drops it instead of+ // restoring a key nothing can authenticate as. Three of these+ // carry the `$ssha256$` tag, which is why "usable" is a full+ // decode and not a prefix test.+ assert!(+ !is_usable_hash(stored),+ "{stored:?} can never verify, so it must not count as a usable hash"+ );}- assert!(!is_hashed("plaintext-secret"));}/// A record whose digest hex is valid but whose salt is wrong must fail —