aitp-core 0.15.0

//! Unknown-member detection per RFC-AITP-0001 §7.
//!
//! §7 requires every schema-defined JSON object to reject members outside
//! its declared member set, while members *inside* a declared extension
//! namespace (e.g. `extensions`) are never inspected — the MUST-ignore half
//! of §7 is structural, not a policy choice made here.
//!
//! This module gives that rejection a name: [`check_members`] performs the
//! top-level member-set check directly against a [`serde_json::Value`], and
//! [`from_serde_error`] recovers the offending field name from a residual
//! `#[serde(deny_unknown_fields)]` failure raised by a *nested* closed
//! object (one this module never got a chance to check directly because it
//! lives inside a typed struct rather than a raw `Value`).
//!
//! A third function, [`reject_duplicate_keys`], guards the step that runs
//! *before* either of the above: every `parse_*_wire` entry point in this
//! workspace inspects a member set by first producing a
//! [`serde_json::Value`] from the wire bytes. `Value`'s object
//! representation is last-write-wins on a duplicate JSON key — by the time
//! a `Value` exists, RFC-AITP-0001 §5.4.5's duplicate-key rejection is
//! already impossible to perform. [`reject_duplicate_keys`] operates on the
//! raw bytes instead, before any `Value` is built. [`CheckedJson`] makes
//! that ordering structural: it is the only input type the `parse_*_wire`
//! functions accept, and it can only be built from raw text by a
//! constructor that runs [`reject_duplicate_keys`] first.

use std::collections::{BTreeSet, HashSet};

use serde::de::{DeserializeSeed, Deserializer, Error as DeError, MapAccess, SeqAccess, Visitor};

/// The offending member and the object it was found on.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("unknown field `{field}` in `{object}`")]
pub struct UnknownField {
    /// Name of the JSON member that was not in the object's declared
    /// member set.
    pub field: String,
    /// Name of the object the member was found on (for diagnostics only —
    /// not part of the wire format).
    pub object: &'static str,
}

/// Top-level member-set check (RFC-AITP-0001 §7).
///
/// `allowed` is the object's full schema-defined member set, INCLUDING the
/// extension-namespace key itself (e.g. `"extensions"`). Contents of that
/// namespace are never inspected — the MUST-ignore half of §7 is
/// structural here, not a policy: this function only ever looks at the
/// top-level keys of `value`.
///
/// Returns `Ok(())` if `value` is not a JSON object. "Not an object" is a
/// different defect, already owned by the existing typed deserialization
/// path, and must not be reclassified as `UNKNOWN_FIELD` here.
pub fn check_members(
    object: &'static str,
    value: &serde_json::Value,
    allowed: &[&str],
) -> Result<(), UnknownField> {
    let Some(map) = value.as_object() else {
        return Ok(());
    };
    let allowed: BTreeSet<&str> = allowed.iter().copied().collect();
    for key in map.keys() {
        if !allowed.contains(key.as_str()) {
            return Err(UnknownField {
                field: key.clone(),
                object,
            });
        }
    }
    Ok(())
}

/// Recover the offending field name from a residual serde
/// `deny_unknown_fields` failure raised by a NESTED closed object.
///
/// `serde`'s unknown-field error always begins with the literal prefix
/// `` unknown field `<name>` `` regardless of how many fields the target
/// struct declares (or none at all). This parses that prefix.
///
/// Returns `None` for anything else — a missing-field error, a type
/// mismatch, or (should serde's wording ever change) an unknown-field
/// error whose message no longer matches this shape. This is a documented
/// degradation path, never a gate: callers that get `None` here simply
/// fall back to their pre-existing error code, they never silently accept
/// the input.
pub fn from_serde_error(e: &serde_json::Error) -> Option<String> {
    let msg = e.to_string();
    let rest = msg.strip_prefix("unknown field `")?;
    let end = rest.find('`')?;
    Some(rest[..end].to_string())
}

/// Detects a duplicate key anywhere in a JSON document's object structure
/// (recursively, at every nesting level) directly from raw bytes/text —
/// deliberately BEFORE any `serde_json::Value` exists. `Value`'s map
/// representation is last-write-wins on a duplicate key (RFC-AITP-0001
/// §5.4.5 requires the opposite), so parsing to `Value` first — which
/// [`check_members`] and every `parse_*_wire` function in this workspace
/// must do to inspect a member set ahead of a typed deserialize — silently
/// forfeits serde-derive's usual automatic duplicate-field rejection.
/// Every entry point that begins a wire parse by producing a `Value` MUST
/// call this against the ORIGINAL bytes first.
///
/// Returns `Ok(())` when `bytes` is not a JSON object at all (a bare
/// scalar, array-of-scalars, etc.) — rejecting a non-object top level is a
/// different defect, owned by the caller's existing typed deserialize, not
/// this function's job. It also returns `Ok(())` for a malformed-but-not-
/// object top level such as a bare array, matching [`check_members`]'s own
/// "not an object is not this function's problem" contract; a genuine JSON
/// syntax error surfaces as `Err` with serde_json's own diagnostic text,
/// which every call site maps to the same malformed/parse-failure class it
/// already uses for a `Value` parse failure, so pre-empting that parse
/// with this check never changes behavior for non-duplicate-key input.
pub fn reject_duplicate_keys(bytes: &[u8]) -> Result<(), String> {
    let mut de = serde_json::Deserializer::from_slice(bytes);
    Deserializer::deserialize_any(&mut de, DuplicateKeyChecker).map_err(|e| e.to_string())
}

/// A JSON document parsed from raw wire bytes AFTER passing
/// [`reject_duplicate_keys`] (RFC-AITP-0001 §5.4.5).
///
/// Every `parse_*_wire` entry point in this workspace takes a
/// `&CheckedJson` rather than a bare [`serde_json::Value`]. A `Value` cannot
/// carry a duplicate key — its map representation keeps the last
/// occurrence — so the duplicate-key check can only be performed on the
/// original text. Making the wire parsers accept only this type means a
/// call site cannot reach them without having gone through that check:
/// the only constructors are [`CheckedJson::from_slice`] and
/// [`str::parse`] (via [`FromStr`](std::str::FromStr)), both of which run
/// [`reject_duplicate_keys`] on the raw input before building the `Value`.
///
/// There is deliberately no `From<Value>` constructor. Code that only
/// holds an in-memory `Value` (a test built with `json!`, a value that has
/// been edited) serializes it and parses the text, which keeps the
/// "parsed from text, checked" invariant honest.
///
/// Read access goes through [`Deref`](std::ops::Deref) /
/// [`CheckedJson::as_value`]; [`CheckedJson::member`] hands out a checked
/// sub-document (a sub-tree of a checked document is itself free of
/// duplicate keys, since the check is recursive).
#[derive(Debug, Clone, PartialEq)]
pub struct CheckedJson(serde_json::Value);

/// Error from constructing a [`CheckedJson`]: the input repeats an object
/// key somewhere (RFC-AITP-0001 §5.4.5) or is not valid JSON. The message
/// is serde_json's diagnostic; for a repeated key it begins
/// ``duplicate field `<key>` ``.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("{0}")]
pub struct CheckedJsonError(String);

impl CheckedJson {
    /// Parse `bytes` as JSON, rejecting a duplicate object key at any
    /// nesting level before the [`serde_json::Value`] is built.
    pub fn from_slice(bytes: &[u8]) -> Result<Self, CheckedJsonError> {
        reject_duplicate_keys(bytes).map_err(CheckedJsonError)?;
        serde_json::from_slice(bytes)
            .map(CheckedJson)
            .map_err(|e| CheckedJsonError(e.to_string()))
    }

    /// The parsed document.
    pub fn as_value(&self) -> &serde_json::Value {
        &self.0
    }

    /// Consume the wrapper, returning the parsed document.
    pub fn into_value(self) -> serde_json::Value {
        self.0
    }

    /// The member `key` of a top-level object, as its own checked
    /// document. `None` when `self` is not an object or has no such key.
    pub fn member(&self, key: &str) -> Option<CheckedJson> {
        self.0.get(key).cloned().map(CheckedJson)
    }
}

impl std::str::FromStr for CheckedJson {
    type Err = CheckedJsonError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::from_slice(s.as_bytes())
    }
}

impl std::ops::Deref for CheckedJson {
    type Target = serde_json::Value;

    fn deref(&self) -> &serde_json::Value {
        &self.0
    }
}

impl AsRef<serde_json::Value> for CheckedJson {
    fn as_ref(&self) -> &serde_json::Value {
        &self.0
    }
}

/// A `Visitor`/`DeserializeSeed` that walks a JSON document purely to
/// detect a duplicate object key, at any nesting level. It never collects
/// or returns any of the document's actual values — "look but don't
/// collect".
#[derive(Clone, Copy)]
struct DuplicateKeyChecker;

impl<'de> DeserializeSeed<'de> for DuplicateKeyChecker {
    type Value = ();

    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(self)
    }
}

impl<'de> Visitor<'de> for DuplicateKeyChecker {
    type Value = ();

    fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("any JSON value")
    }

    fn visit_map<A>(self, mut map: A) -> Result<(), A::Error>
    where
        A: MapAccess<'de>,
    {
        let mut seen: HashSet<String> = HashSet::new();
        while let Some(key) = map.next_key::<String>()? {
            if !seen.insert(key.clone()) {
                return Err(A::Error::custom(format!("duplicate field `{key}`")));
            }
            map.next_value_seed(DuplicateKeyChecker)?;
        }
        Ok(())
    }

    fn visit_seq<A>(self, mut seq: A) -> Result<(), A::Error>
    where
        A: SeqAccess<'de>,
    {
        while seq.next_element_seed(DuplicateKeyChecker)?.is_some() {}
        Ok(())
    }

    fn visit_bool<E>(self, _v: bool) -> Result<(), E> {
        Ok(())
    }

    fn visit_i64<E>(self, _v: i64) -> Result<(), E> {
        Ok(())
    }

    fn visit_i128<E>(self, _v: i128) -> Result<(), E> {
        Ok(())
    }

    fn visit_u64<E>(self, _v: u64) -> Result<(), E> {
        Ok(())
    }

    fn visit_u128<E>(self, _v: u128) -> Result<(), E> {
        Ok(())
    }

    fn visit_f64<E>(self, _v: f64) -> Result<(), E> {
        Ok(())
    }

    fn visit_str<E>(self, _v: &str) -> Result<(), E> {
        Ok(())
    }

    fn visit_bytes<E>(self, _v: &[u8]) -> Result<(), E> {
        Ok(())
    }

    fn visit_char<E>(self, _v: char) -> Result<(), E> {
        Ok(())
    }

    fn visit_none<E>(self) -> Result<(), E> {
        Ok(())
    }

    fn visit_some<D>(self, deserializer: D) -> Result<(), D::Error>
    where
        D: Deserializer<'de>,
    {
        deserializer.deserialize_any(self)
    }

    fn visit_unit<E>(self) -> Result<(), E> {
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde::Deserialize;
    use serde_json::json;

    // ---- check_members --------------------------------------------------

    #[test]
    fn allows_known_members_and_ignores_extension_namespace_contents() {
        let v = json!({"a": 1, "extensions": {"junk": 1}});
        assert_eq!(check_members("x", &v, &["a", "extensions"]), Ok(()));
    }

    #[test]
    fn rejects_a_member_outside_the_allowed_set() {
        let v = json!({"a": 1, "b": 2});
        let err = check_members("x", &v, &["a"]).unwrap_err();
        assert_eq!(err.field, "b");
        assert_eq!(err.object, "x");
    }

    #[test]
    fn does_not_recurse_into_the_extension_namespace() {
        // An arbitrary junk key nested inside `extensions` must never be
        // reported: contents of the namespace are never inspected.
        let v = json!({
            "extensions": {
                "junk_key_of_any_shape": {"deeply": {"nested": true}},
            }
        });
        assert_eq!(check_members("x", &v, &["extensions"]), Ok(()));
    }

    #[test]
    fn non_object_value_is_ok() {
        assert_eq!(check_members("x", &json!("a string"), &["a"]), Ok(()));
        assert_eq!(check_members("x", &json!(null), &["a"]), Ok(()));
        assert_eq!(check_members("x", &json!(42), &["a"]), Ok(()));
        assert_eq!(check_members("x", &json!([1, 2, 3]), &["a"]), Ok(()));
    }

    #[test]
    fn empty_object_with_no_allowed_members_is_ok() {
        assert_eq!(check_members("x", &json!({}), &[]), Ok(()));
    }

    // ---- from_serde_error -------------------------------------------------

    #[derive(Debug, Deserialize)]
    #[serde(deny_unknown_fields)]
    struct Closed {
        #[allow(dead_code)]
        a: i64,
    }

    #[test]
    fn recovers_field_name_from_unknown_field_error() {
        let err = serde_json::from_str::<Closed>(r#"{"a":1,"zzz":2}"#).unwrap_err();
        assert_eq!(from_serde_error(&err), Some("zzz".to_string()));
    }

    #[test]
    fn returns_none_for_missing_field_error() {
        let err = serde_json::from_str::<Closed>(r#"{}"#).unwrap_err();
        assert_eq!(from_serde_error(&err), None);
    }

    #[test]
    fn returns_none_for_type_mismatch_error() {
        let err = serde_json::from_str::<Closed>(r#"{"a":"not a number"}"#).unwrap_err();
        assert_eq!(from_serde_error(&err), None);
    }

    // ---- CheckedJson --------------------------------------------------------

    #[test]
    fn checked_json_rejects_a_duplicate_key_at_any_depth() {
        let err = CheckedJson::from_slice(br#"{"a":1,"a":2}"#).unwrap_err();
        assert!(err.to_string().contains("duplicate field `a`"), "{err}");
        let err = r#"{"x":{"b":1,"b":2}}"#.parse::<CheckedJson>().unwrap_err();
        assert!(err.to_string().contains("duplicate field `b`"), "{err}");
    }

    #[test]
    fn checked_json_rejects_invalid_json() {
        assert!(CheckedJson::from_slice(b"{not json").is_err());
    }

    #[test]
    fn checked_json_round_trips_a_clean_document() {
        let c: CheckedJson = r#"{"a":{"b":[1,2]}}"#.parse().unwrap();
        assert_eq!(c.as_value(), &json!({"a": {"b": [1, 2]}}));
        assert_eq!(c.member("a").unwrap().as_value(), &json!({"b": [1, 2]}));
        assert!(c.member("missing").is_none());
        assert_eq!(c["a"]["b"][0], 1);
        assert_eq!(c.into_value(), json!({"a": {"b": [1, 2]}}));
    }

    // ---- reject_duplicate_keys --------------------------------------------

    #[test]
    fn rejects_duplicate_key_at_top_level() {
        let bytes = br#"{"version":"aitp/0.2","version":"aitp/0.3"}"#;
        let err = reject_duplicate_keys(bytes).unwrap_err();
        assert!(err.contains("duplicate field `version`"), "got: {err}");
    }

    #[test]
    fn rejects_duplicate_key_in_nested_object() {
        let bytes = br#"{"a": {"x": 1, "x": 2}}"#;
        let err = reject_duplicate_keys(bytes).unwrap_err();
        assert!(err.contains("duplicate field `x`"), "got: {err}");
    }

    #[test]
    fn rejects_duplicate_key_in_object_nested_inside_array() {
        let bytes = br#"{"entries": [{"jti": "a"}, {"x":1,"x":2}]}"#;
        let err = reject_duplicate_keys(bytes).unwrap_err();
        assert!(err.contains("duplicate field `x`"), "got: {err}");
    }

    #[test]
    fn rejects_duplicate_key_several_levels_deep_inside_arrays_and_objects() {
        // entries[] -> object -> nested object -> duplicate.
        let bytes = br#"{"entries": [{"cnf": {"jkt": "a", "jkt": "b"}}]}"#;
        let err = reject_duplicate_keys(bytes).unwrap_err();
        assert!(err.contains("duplicate field `jkt`"), "got: {err}");
    }

    #[test]
    fn accepts_document_with_no_duplicates_at_any_level() {
        let bytes = br#"{
            "version": "aitp/0.2",
            "sender": {"agent_id": "aid:pubkey:abc"},
            "entries": [
                {"jti": "a", "cnf": {"jkt": "x"}},
                {"jti": "b", "cnf": {"jkt": "y"}}
            ],
            "extensions": {"com.example/foo": {"a": 1, "b": 2}}
        }"#;
        assert_eq!(reject_duplicate_keys(bytes), Ok(()));
    }

    #[test]
    fn bare_scalar_top_level_is_ok_not_this_functions_job() {
        assert_eq!(reject_duplicate_keys(b"42"), Ok(()));
        assert_eq!(reject_duplicate_keys(b"\"a string\""), Ok(()));
        assert_eq!(reject_duplicate_keys(b"null"), Ok(()));
        assert_eq!(reject_duplicate_keys(b"true"), Ok(()));
        assert_eq!(reject_duplicate_keys(b"[1,2,3]"), Ok(()));
    }

    #[test]
    fn malformed_non_duplicate_json_still_errs_but_not_as_a_duplicate() {
        // Not this function's headline job, but it must not panic, and
        // must not misreport a plain syntax error as a duplicate field.
        let err = reject_duplicate_keys(b"{not json").unwrap_err();
        assert!(!err.contains("duplicate field"), "got: {err}");
    }

    /// A real, deeply-nested signed fixture (session bundle: top-level
    /// object, `participants[]` array of objects) round-trips cleanly
    /// with no false positive.
    #[test]
    fn realistic_signed_fixture_has_no_false_positive() {
        let path = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .and_then(|p| p.parent())
            .expect("repo root")
            .join("tests/schemas/known-answer/signed-examples/session-bundle/kat-keypair-001-bundle.json");
        let bytes = std::fs::read(&path).unwrap_or_else(|e| {
            panic!("read {}: {e}", path.display());
        });
        assert_eq!(reject_duplicate_keys(&bytes), Ok(()));
    }
}