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.

fix(security): reserve the `superuser`/`unscoped` labels, drop unverifiable key records

xerj-orgd33a468a6a8b
diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md
index 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 time
on boot — hashed, and the file rewritten without the plaintext — before the
server 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 v4
UUIDs of CSPRNG output (244 bits), never chosen or reused by a human, so an
offline 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 call
and 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. Treat
it 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 ever
diff --git a/engine/crates/xerj-api/src/es_compat.rs b/engine/crates/xerj-api/src/es_compat.rs
index 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_privileges
diff --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.rs
index 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.rs
index 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.rs
index 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 —