Skip to main content

stateknot_core/
content.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Validated content values and security metadata for runtime boundaries.
5
6use std::{borrow::Borrow, collections::HashSet, fmt, str::FromStr};
7
8use language_tags::LanguageTag as ParsedLanguageTag;
9use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
10use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
11use thiserror::Error;
12
13use crate::{BoundedJson, SchemaReference};
14
15const KIBIBYTE: usize = 1024;
16const LANGUAGE_TAG_PATTERN: &str = "^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$";
17const SECURITY_LABEL_PATTERN: &str = "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$";
18
19/// A stable, case-normalized RFC 5646 language tag.
20///
21/// Parsing accepts well-formed language tags, grandfathered tags, and private
22/// use tags. `StateKnot` stores lowercase ASCII because RFC 5646 comparison is
23/// case-insensitive. It intentionally does not consult the mutable IANA
24/// Language Subtag Registry or apply registry-version-dependent preferred-value
25/// replacements, so durable data remains readable offline and over time.
26#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
27pub struct LanguageTag(Box<str>);
28
29impl LanguageTag {
30    /// Maximum encoded length in bytes.
31    pub const MAX_LEN: usize = 255;
32
33    /// Validates and constructs a language tag.
34    ///
35    /// # Errors
36    ///
37    /// Returns [`LanguageTagError`] when the input is empty, too long, not a
38    /// well-formed RFC 5646 language tag, or repeats a variant or extension
39    /// singleton.
40    pub fn new(value: impl AsRef<str>) -> Result<Self, LanguageTagError> {
41        let value = value.as_ref();
42        if value.is_empty() {
43            return Err(LanguageTagError::Empty);
44        }
45        if value.len() > Self::MAX_LEN {
46            return Err(LanguageTagError::TooLong {
47                max: Self::MAX_LEN,
48                actual: value.len(),
49            });
50        }
51
52        let parsed =
53            ParsedLanguageTag::parse(value).map_err(|_| LanguageTagError::InvalidSyntax)?;
54
55        let mut variants = HashSet::new();
56        if parsed
57            .variant_subtags()
58            .any(|variant| !variants.insert(variant))
59        {
60            return Err(LanguageTagError::DuplicateVariant);
61        }
62
63        let mut extensions = HashSet::new();
64        if parsed
65            .extension_subtags()
66            .any(|(singleton, _)| !extensions.insert(singleton))
67        {
68            return Err(LanguageTagError::DuplicateExtension);
69        }
70
71        Ok(Self(
72            parsed.into_string().to_ascii_lowercase().into_boxed_str(),
73        ))
74    }
75
76    /// Returns the stable lowercase wire representation.
77    #[must_use]
78    pub fn as_str(&self) -> &str {
79        &self.0
80    }
81}
82
83impl AsRef<str> for LanguageTag {
84    fn as_ref(&self) -> &str {
85        self.as_str()
86    }
87}
88
89impl Borrow<str> for LanguageTag {
90    fn borrow(&self) -> &str {
91        self.as_str()
92    }
93}
94
95impl fmt::Debug for LanguageTag {
96    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
97        formatter
98            .debug_tuple("LanguageTag")
99            .field(&self.as_str())
100            .finish()
101    }
102}
103
104impl fmt::Display for LanguageTag {
105    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
106        formatter.write_str(self.as_str())
107    }
108}
109
110impl FromStr for LanguageTag {
111    type Err = LanguageTagError;
112
113    fn from_str(value: &str) -> Result<Self, Self::Err> {
114        Self::new(value)
115    }
116}
117
118impl TryFrom<String> for LanguageTag {
119    type Error = LanguageTagError;
120
121    fn try_from(value: String) -> Result<Self, Self::Error> {
122        Self::new(value)
123    }
124}
125
126impl TryFrom<&str> for LanguageTag {
127    type Error = LanguageTagError;
128
129    fn try_from(value: &str) -> Result<Self, Self::Error> {
130        Self::new(value)
131    }
132}
133
134impl From<LanguageTag> for String {
135    fn from(value: LanguageTag) -> Self {
136        value.0.into()
137    }
138}
139
140impl Serialize for LanguageTag {
141    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
142    where
143        S: Serializer,
144    {
145        serializer.serialize_str(self.as_str())
146    }
147}
148
149impl<'de> Deserialize<'de> for LanguageTag {
150    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
151    where
152        D: Deserializer<'de>,
153    {
154        deserializer.deserialize_string(LanguageTagVisitor)
155    }
156}
157
158struct LanguageTagVisitor;
159
160impl de::Visitor<'_> for LanguageTagVisitor {
161    type Value = LanguageTag;
162
163    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
164        formatter.write_str("a bounded, well-formed RFC 5646 language tag")
165    }
166
167    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
168    where
169        E: de::Error,
170    {
171        LanguageTag::new(value).map_err(E::custom)
172    }
173
174    fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
175    where
176        E: de::Error,
177    {
178        LanguageTag::new(value).map_err(E::custom)
179    }
180}
181
182impl JsonSchema for LanguageTag {
183    fn schema_name() -> std::borrow::Cow<'static, str> {
184        "LanguageTag".into()
185    }
186
187    fn schema_id() -> std::borrow::Cow<'static, str> {
188        concat!(module_path!(), "::LanguageTag").into()
189    }
190
191    fn json_schema(_: &mut SchemaGenerator) -> Schema {
192        json_schema!({
193            "type": "string",
194            "minLength": 1,
195            "maxLength": 255,
196            "pattern": LANGUAGE_TAG_PATTERN,
197            "description": "A well-formed RFC 5646 language tag serialized in lowercase. Decoding accepts ASCII case variants; StateKnot also rejects duplicate variants and extension singletons at runtime without consulting the mutable IANA registry."
198        })
199    }
200
201    fn inline_schema() -> bool {
202        true
203    }
204}
205
206/// Validation failure for a [`LanguageTag`].
207#[derive(Clone, Debug, Eq, Error, PartialEq)]
208#[non_exhaustive]
209pub enum LanguageTagError {
210    /// The tag contained no bytes.
211    #[error("language tag must not be empty")]
212    Empty,
213
214    /// The tag exceeded [`LanguageTag::MAX_LEN`].
215    #[error("language tag is {actual} bytes; maximum is {max}")]
216    TooLong {
217        /// Maximum accepted byte length.
218        max: usize,
219        /// Observed byte length.
220        actual: usize,
221    },
222
223    /// The tag did not match the RFC 5646 well-formed grammar.
224    #[error("language tag is not well-formed RFC 5646 text")]
225    InvalidSyntax,
226
227    /// A variant subtag appeared more than once.
228    #[error("language tag contains a duplicate variant subtag")]
229    DuplicateVariant,
230
231    /// An extension singleton appeared more than once.
232    #[error("language tag contains a duplicate extension singleton")]
233    DuplicateExtension,
234}
235
236/// An opaque, bounded label interpreted only by an explicit policy engine.
237///
238/// Labels are case-sensitive and are never trimmed, normalized, ranked, or
239/// treated as an authorization grant by `stateknot-core`.
240#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
241pub struct SecurityLabel(Box<str>);
242
243impl SecurityLabel {
244    /// Maximum encoded length in bytes.
245    pub const MAX_LEN: usize = 128;
246
247    /// Validates and constructs an opaque security label.
248    ///
249    /// # Errors
250    ///
251    /// Returns [`SecurityLabelError`] when the value is empty, too long, does
252    /// not start with an ASCII alphanumeric byte, or contains a byte outside
253    /// the stable ASCII grammar.
254    pub fn new(value: impl Into<String>) -> Result<Self, SecurityLabelError> {
255        let value = value.into();
256        validate_security_label(&value)?;
257        Ok(Self(value.into_boxed_str()))
258    }
259
260    /// Returns the exact, case-sensitive policy label.
261    #[must_use]
262    pub fn as_str(&self) -> &str {
263        &self.0
264    }
265}
266
267impl AsRef<str> for SecurityLabel {
268    fn as_ref(&self) -> &str {
269        self.as_str()
270    }
271}
272
273impl Borrow<str> for SecurityLabel {
274    fn borrow(&self) -> &str {
275        self.as_str()
276    }
277}
278
279impl fmt::Debug for SecurityLabel {
280    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
281        formatter
282            .debug_tuple("SecurityLabel")
283            .field(&self.as_str())
284            .finish()
285    }
286}
287
288impl fmt::Display for SecurityLabel {
289    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
290        formatter.write_str(self.as_str())
291    }
292}
293
294impl FromStr for SecurityLabel {
295    type Err = SecurityLabelError;
296
297    fn from_str(value: &str) -> Result<Self, Self::Err> {
298        Self::new(value)
299    }
300}
301
302impl TryFrom<String> for SecurityLabel {
303    type Error = SecurityLabelError;
304
305    fn try_from(value: String) -> Result<Self, Self::Error> {
306        Self::new(value)
307    }
308}
309
310impl TryFrom<&str> for SecurityLabel {
311    type Error = SecurityLabelError;
312
313    fn try_from(value: &str) -> Result<Self, Self::Error> {
314        Self::new(value)
315    }
316}
317
318impl From<SecurityLabel> for String {
319    fn from(value: SecurityLabel) -> Self {
320        value.0.into()
321    }
322}
323
324impl Serialize for SecurityLabel {
325    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
326    where
327        S: Serializer,
328    {
329        serializer.serialize_str(self.as_str())
330    }
331}
332
333impl<'de> Deserialize<'de> for SecurityLabel {
334    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
335    where
336        D: Deserializer<'de>,
337    {
338        deserializer.deserialize_string(SecurityLabelVisitor)
339    }
340}
341
342struct SecurityLabelVisitor;
343
344impl de::Visitor<'_> for SecurityLabelVisitor {
345    type Value = SecurityLabel;
346
347    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
348        formatter.write_str("a bounded StateKnot security policy label")
349    }
350
351    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
352    where
353        E: de::Error,
354    {
355        SecurityLabel::new(value).map_err(E::custom)
356    }
357
358    fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
359    where
360        E: de::Error,
361    {
362        SecurityLabel::new(value).map_err(E::custom)
363    }
364}
365
366impl JsonSchema for SecurityLabel {
367    fn schema_name() -> std::borrow::Cow<'static, str> {
368        "SecurityLabel".into()
369    }
370
371    fn schema_id() -> std::borrow::Cow<'static, str> {
372        concat!(module_path!(), "::SecurityLabel").into()
373    }
374
375    fn json_schema(_: &mut SchemaGenerator) -> Schema {
376        json_schema!({
377            "type": "string",
378            "minLength": 1,
379            "maxLength": 128,
380            "pattern": SECURITY_LABEL_PATTERN,
381            "description": "An opaque, case-sensitive policy label; it conveys no authorization by itself."
382        })
383    }
384
385    fn inline_schema() -> bool {
386        true
387    }
388}
389
390/// Validation failure for a [`SecurityLabel`].
391#[derive(Clone, Debug, Eq, Error, PartialEq)]
392#[non_exhaustive]
393pub enum SecurityLabelError {
394    /// The label contained no bytes.
395    #[error("security label must not be empty")]
396    Empty,
397
398    /// The label exceeded [`SecurityLabel::MAX_LEN`].
399    #[error("security label is {actual} bytes; maximum is {max}")]
400    TooLong {
401        /// Maximum accepted byte length.
402        max: usize,
403        /// Observed byte length.
404        actual: usize,
405    },
406
407    /// The first byte was not an ASCII letter or digit.
408    #[error("security label must start with an ASCII letter or digit")]
409    InvalidStart,
410
411    /// A later byte did not belong to the stable ASCII grammar.
412    #[error("security label contains an invalid byte at offset {index}")]
413    InvalidByte {
414        /// Zero-based byte offset of the first invalid byte.
415        index: usize,
416    },
417}
418
419fn validate_security_label(value: &str) -> Result<(), SecurityLabelError> {
420    if value.is_empty() {
421        return Err(SecurityLabelError::Empty);
422    }
423    if value.len() > SecurityLabel::MAX_LEN {
424        return Err(SecurityLabelError::TooLong {
425            max: SecurityLabel::MAX_LEN,
426            actual: value.len(),
427        });
428    }
429
430    if !value.as_bytes()[0].is_ascii_alphanumeric() {
431        return Err(SecurityLabelError::InvalidStart);
432    }
433
434    if let Some((index, _)) = value.bytes().enumerate().skip(1).find(|(_, byte)| {
435        !byte.is_ascii_alphanumeric() && !matches!(byte, b'.' | b'_' | b':' | b'/' | b'-')
436    }) {
437        return Err(SecurityLabelError::InvalidByte { index });
438    }
439
440    Ok(())
441}
442
443/// The immediate domain source from which content entered `StateKnot`.
444///
445/// This is attribution metadata, not an identity or authorization decision.
446#[derive(
447    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
448)]
449#[non_exhaustive]
450#[serde(rename_all = "snake_case")]
451pub enum ContentSource {
452    /// Application-owned configuration or code.
453    Application,
454    /// Direct user input.
455    User,
456    /// Model-generated output.
457    Model,
458    /// Tool output or MCP-provided content.
459    Tool,
460    /// Content received from a remote agent, including A2A peers.
461    RemoteAgent,
462    /// Content resolved from a registered artifact.
463    Artifact,
464}
465
466/// An asserted content trust classification.
467///
468/// This field supports policy evaluation and audit. Deserializing
469/// [`ContentTrust::ApplicationControlled`] never grants authority and cannot by
470/// itself construct a trusted instruction; that requires an application-owned
471/// provenance and policy path outside this metadata type.
472#[derive(
473    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
474)]
475#[non_exhaustive]
476#[serde(rename_all = "snake_case")]
477pub enum ContentTrust {
478    /// The application asserts control over the content's authorship.
479    ApplicationControlled,
480    /// The content must be handled as untrusted data.
481    Untrusted,
482}
483
484/// The redaction transformation recorded for this representation.
485///
486/// `NotApplied` means no redaction transformation was recorded; it does not
487/// mean the content is non-sensitive or safe to log.
488#[derive(
489    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
490)]
491#[non_exhaustive]
492#[serde(rename_all = "snake_case")]
493pub enum RedactionState {
494    /// No redaction transformation was applied to this representation.
495    NotApplied,
496    /// Some policy-selected content was replaced or removed.
497    Partial,
498    /// The policy-selected sensitive content was fully replaced or removed.
499    Full,
500}
501
502/// Security and source metadata carried by each content value.
503///
504/// The fields are explicit so adapters cannot silently discard trust-boundary
505/// information. This object is an auditable claim only: it does not authorize
506/// execution, declassification, logging, or conversion into an instruction.
507#[derive(Clone, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
508#[serde(deny_unknown_fields)]
509pub struct ContentMetadata {
510    source: ContentSource,
511    trust: ContentTrust,
512    security_label: SecurityLabel,
513    redaction: RedactionState,
514}
515
516impl ContentMetadata {
517    /// Constructs metadata from explicit validated components.
518    #[must_use]
519    pub const fn new(
520        source: ContentSource,
521        trust: ContentTrust,
522        security_label: SecurityLabel,
523        redaction: RedactionState,
524    ) -> Self {
525        Self {
526            source,
527            trust,
528            security_label,
529            redaction,
530        }
531    }
532
533    /// Constructs the common untrusted, not-yet-redacted classification.
534    #[must_use]
535    pub const fn untrusted(source: ContentSource, security_label: SecurityLabel) -> Self {
536        Self::new(
537            source,
538            ContentTrust::Untrusted,
539            security_label,
540            RedactionState::NotApplied,
541        )
542    }
543
544    /// Returns the immediate content source.
545    #[must_use]
546    pub const fn source(&self) -> ContentSource {
547        self.source
548    }
549
550    /// Returns the asserted trust classification.
551    #[must_use]
552    pub const fn trust(&self) -> ContentTrust {
553        self.trust
554    }
555
556    /// Returns the opaque policy label.
557    #[must_use]
558    pub const fn security_label(&self) -> &SecurityLabel {
559        &self.security_label
560    }
561
562    /// Returns the redaction transformation state.
563    #[must_use]
564    pub const fn redaction(&self) -> RedactionState {
565        self.redaction
566    }
567}
568
569/// Validated, bounded UTF-8 text with mandatory security metadata.
570///
571/// Text is preserved byte-for-byte without trimming or Unicode normalization.
572/// `StateKnot` rejects C0/C1 controls other than tab, line feed, and carriage
573/// return, plus Unicode noncharacters. Multilingual text and bidi formatting
574/// characters remain valid data; renderers and logs must still escape untrusted
575/// content for their output context.
576#[derive(Clone, Eq, PartialEq, Serialize)]
577pub struct TextContent {
578    text: Box<str>,
579    #[serde(skip_serializing_if = "Option::is_none")]
580    language: Option<LanguageTag>,
581    metadata: ContentMetadata,
582}
583
584impl TextContent {
585    /// Maximum UTF-8 encoded text length in bytes.
586    pub const MAX_BYTES: usize = 256 * KIBIBYTE;
587
588    /// Validates borrowed text and copies it into an immutable value.
589    ///
590    /// # Errors
591    ///
592    /// Returns [`TextContentError`] when text is empty, exceeds the byte
593    /// ceiling, or contains a disallowed control or Unicode noncharacter.
594    pub fn new(
595        text: &str,
596        language: Option<LanguageTag>,
597        metadata: ContentMetadata,
598    ) -> Result<Self, TextContentError> {
599        validate_text(text)?;
600        Ok(Self {
601            text: text.into(),
602            language,
603            metadata,
604        })
605    }
606
607    /// Validates owned text without copying its bytes.
608    ///
609    /// # Errors
610    ///
611    /// Returns [`TextContentError`] when text is empty, exceeds the byte
612    /// ceiling, or contains a disallowed control or Unicode noncharacter.
613    pub fn from_string(
614        text: String,
615        language: Option<LanguageTag>,
616        metadata: ContentMetadata,
617    ) -> Result<Self, TextContentError> {
618        validate_text(&text)?;
619        Ok(Self {
620            text: text.into_boxed_str(),
621            language,
622            metadata,
623        })
624    }
625
626    /// Returns the exact validated UTF-8 text.
627    #[must_use]
628    pub fn text(&self) -> &str {
629        &self.text
630    }
631
632    /// Returns the optional stable language tag.
633    #[must_use]
634    pub const fn language(&self) -> Option<&LanguageTag> {
635        self.language.as_ref()
636    }
637
638    /// Returns the mandatory security metadata.
639    #[must_use]
640    pub const fn metadata(&self) -> &ContentMetadata {
641        &self.metadata
642    }
643
644    /// Consumes the value and returns its text allocation.
645    #[must_use]
646    pub fn into_text(self) -> String {
647        self.text.into()
648    }
649}
650
651impl fmt::Debug for TextContent {
652    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
653        formatter
654            .debug_struct("TextContent")
655            .field("text_bytes", &self.text.len())
656            .field("language", &self.language)
657            .field("metadata", &self.metadata)
658            .finish_non_exhaustive()
659    }
660}
661
662impl<'de> Deserialize<'de> for TextContent {
663    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
664    where
665        D: Deserializer<'de>,
666    {
667        #[derive(Deserialize)]
668        #[serde(deny_unknown_fields)]
669        struct Wire {
670            text: String,
671            language: Option<LanguageTag>,
672            metadata: ContentMetadata,
673        }
674
675        let wire = Wire::deserialize(deserializer)?;
676        Self::from_string(wire.text, wire.language, wire.metadata).map_err(de::Error::custom)
677    }
678}
679
680impl JsonSchema for TextContent {
681    fn schema_name() -> std::borrow::Cow<'static, str> {
682        "TextContent".into()
683    }
684
685    fn schema_id() -> std::borrow::Cow<'static, str> {
686        concat!(module_path!(), "::TextContent").into()
687    }
688
689    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
690        json_schema!({
691            "type": "object",
692            "properties": {
693                "text": {
694                    "type": "string",
695                    "minLength": 1,
696                    "maxLength": 262_144,
697                    "description": "Exact UTF-8 text. maxLength is a necessary code-point ceiling; StateKnot separately enforces the 262144-byte ceiling and rejects disallowed controls and Unicode noncharacters at runtime."
698                },
699                "language": generator.subschema_for::<LanguageTag>(),
700                "metadata": generator.subschema_for::<ContentMetadata>()
701            },
702            "required": ["text", "metadata"],
703            "additionalProperties": false
704        })
705    }
706}
707
708/// Validation failure for [`TextContent`].
709#[derive(Clone, Debug, Eq, Error, PartialEq)]
710#[non_exhaustive]
711pub enum TextContentError {
712    /// The text contained no bytes.
713    #[error("text content must not be empty")]
714    Empty,
715
716    /// The text exceeded [`TextContent::MAX_BYTES`].
717    #[error("text content is {actual} UTF-8 bytes; maximum is {max}")]
718    TooLong {
719        /// Maximum accepted UTF-8 byte length.
720        max: usize,
721        /// Observed UTF-8 byte length.
722        actual: usize,
723    },
724
725    /// A control or Unicode noncharacter was present.
726    #[error("text content contains a disallowed Unicode scalar at UTF-8 byte offset {byte_index}")]
727    DisallowedCodePoint {
728        /// Zero-based UTF-8 byte offset without disclosure of content.
729        byte_index: usize,
730    },
731}
732
733fn validate_text(text: &str) -> Result<(), TextContentError> {
734    if text.is_empty() {
735        return Err(TextContentError::Empty);
736    }
737    if text.len() > TextContent::MAX_BYTES {
738        return Err(TextContentError::TooLong {
739            max: TextContent::MAX_BYTES,
740            actual: text.len(),
741        });
742    }
743
744    if let Some((byte_index, _)) = text.char_indices().find(|(_, scalar)| {
745        (scalar.is_control() && !matches!(scalar, '\t' | '\n' | '\r'))
746            || is_unicode_noncharacter(*scalar)
747    }) {
748        return Err(TextContentError::DisallowedCodePoint { byte_index });
749    }
750
751    Ok(())
752}
753
754const fn is_unicode_noncharacter(value: char) -> bool {
755    let value = value as u32;
756    (value >= 0xfdd0 && value <= 0xfdef) || (value & 0xfffe) == 0xfffe
757}
758
759/// Structured content materialized under bounded JSON limits.
760///
761/// An optional [`SchemaReference`] binds the declared schema identity, version,
762/// and digest. Construction does not resolve a schema registry or execute JSON
763/// Schema validation; adapters must perform that explicit operation before a
764/// schema-dependent use.
765#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
766#[serde(deny_unknown_fields)]
767pub struct JsonContent {
768    value: BoundedJson,
769    #[serde(skip_serializing_if = "Option::is_none")]
770    schema: Option<SchemaReference>,
771    metadata: ContentMetadata,
772}
773
774impl JsonContent {
775    /// Constructs structured content from validated components.
776    #[must_use]
777    pub const fn new(
778        value: BoundedJson,
779        schema: Option<SchemaReference>,
780        metadata: ContentMetadata,
781    ) -> Self {
782        Self {
783            value,
784            schema,
785            metadata,
786        }
787    }
788
789    /// Returns the bounded JSON value.
790    #[must_use]
791    pub const fn value(&self) -> &BoundedJson {
792        &self.value
793    }
794
795    /// Returns the optional immutable schema binding.
796    #[must_use]
797    pub const fn schema(&self) -> Option<&SchemaReference> {
798        self.schema.as_ref()
799    }
800
801    /// Returns the mandatory security metadata.
802    #[must_use]
803    pub const fn metadata(&self) -> &ContentMetadata {
804        &self.metadata
805    }
806}
807
808#[cfg(test)]
809mod tests {
810    use super::*;
811    use crate::{Digest, SchemaId, Version};
812    use proptest::{collection, prelude::*};
813    use serde_json::{Value, from_value, json, to_value};
814
815    fn label() -> SecurityLabel {
816        "internal/pii".parse().unwrap()
817    }
818
819    fn untrusted_user_metadata() -> ContentMetadata {
820        ContentMetadata::untrusted(ContentSource::User, label())
821    }
822
823    fn schema_reference() -> SchemaReference {
824        SchemaReference::new(
825            "https://schemas.example.com/content/1.0.0"
826                .parse::<SchemaId>()
827                .unwrap(),
828            Version::new(1, 0, 0),
829            Digest::sha256(b"content schema"),
830        )
831    }
832
833    #[test]
834    fn language_tags_use_stable_case_insensitive_wire_text() {
835        for (input, expected) in [
836            ("en-US", "en-us"),
837            ("ZH-Hant-TW", "zh-hant-tw"),
838            ("i-KLINGON", "i-klingon"),
839            ("X-PRIVATE-42", "x-private-42"),
840        ] {
841            let tag = input.parse::<LanguageTag>().unwrap();
842            assert_eq!(tag.as_str(), expected);
843            assert_eq!(tag.to_string(), expected);
844            assert_eq!(to_value(&tag).unwrap(), Value::from(expected));
845        }
846
847        assert_eq!(
848            "en-us".parse::<LanguageTag>().unwrap(),
849            "EN-US".parse::<LanguageTag>().unwrap()
850        );
851
852        let mut private_subtags = vec!["aaaaaaaa"; 28];
853        private_subtags.push("a");
854        let maximum = format!("x-{}", private_subtags.join("-"));
855        assert_eq!(maximum.len(), LanguageTag::MAX_LEN);
856        assert_eq!(maximum.parse::<LanguageTag>().unwrap().as_str(), maximum);
857    }
858
859    #[test]
860    fn language_tags_reject_invalid_or_ambiguous_text() {
861        assert_eq!("".parse::<LanguageTag>(), Err(LanguageTagError::Empty));
862        assert_eq!(
863            "a".repeat(LanguageTag::MAX_LEN + 1).parse::<LanguageTag>(),
864            Err(LanguageTagError::TooLong {
865                max: LanguageTag::MAX_LEN,
866                actual: LanguageTag::MAX_LEN + 1,
867            })
868        );
869
870        for invalid in ["en_US", "en--US", "é", "x-", "*"] {
871            assert_eq!(
872                invalid.parse::<LanguageTag>(),
873                Err(LanguageTagError::InvalidSyntax),
874                "accepted {invalid:?}"
875            );
876        }
877
878        assert_eq!(
879            "sl-rozaj-ROZAJ".parse::<LanguageTag>(),
880            Err(LanguageTagError::DuplicateVariant)
881        );
882        assert_eq!(
883            "en-a-foo-A-bar".parse::<LanguageTag>(),
884            Err(LanguageTagError::DuplicateExtension)
885        );
886    }
887
888    #[test]
889    fn language_tag_serde_and_schema_revalidate_input() {
890        let tag = from_value::<LanguageTag>(json!("FR-ca")).unwrap();
891        assert_eq!(tag.as_str(), "fr-ca");
892        assert!(from_value::<LanguageTag>(json!(42)).is_err());
893        assert!(from_value::<LanguageTag>(json!("en_a")).is_err());
894
895        let schema = to_value(schemars::schema_for!(LanguageTag)).unwrap();
896        assert_eq!(schema["type"], "string");
897        assert_eq!(schema["minLength"], 1);
898        assert_eq!(schema["maxLength"], LanguageTag::MAX_LEN);
899        assert_eq!(schema["pattern"], LANGUAGE_TAG_PATTERN);
900    }
901
902    #[test]
903    fn security_labels_preserve_case_and_exact_spelling() {
904        for value in ["public", "Internal/PII", "tenant:42/restricted-v1", "A_b.c"] {
905            let label = value.parse::<SecurityLabel>().unwrap();
906            assert_eq!(label.as_str(), value);
907            assert_eq!(to_value(&label).unwrap(), Value::from(value));
908        }
909
910        assert_ne!(
911            "internal".parse::<SecurityLabel>().unwrap(),
912            "Internal".parse::<SecurityLabel>().unwrap()
913        );
914
915        let maximum = "a".repeat(SecurityLabel::MAX_LEN);
916        assert_eq!(maximum.parse::<SecurityLabel>().unwrap().as_str(), maximum);
917    }
918
919    #[test]
920    fn security_labels_reject_values_outside_the_opaque_grammar() {
921        assert_eq!("".parse::<SecurityLabel>(), Err(SecurityLabelError::Empty));
922        assert_eq!(
923            "a".repeat(SecurityLabel::MAX_LEN + 1)
924                .parse::<SecurityLabel>(),
925            Err(SecurityLabelError::TooLong {
926                max: SecurityLabel::MAX_LEN,
927                actual: SecurityLabel::MAX_LEN + 1,
928            })
929        );
930
931        for value in ["_internal", "-public", "/root", " PII"] {
932            assert_eq!(
933                value.parse::<SecurityLabel>(),
934                Err(SecurityLabelError::InvalidStart),
935                "accepted {value:?}"
936            );
937        }
938
939        for (value, index) in [("a b", 1), ("a\\b", 1), ("a?b", 1), ("a中", 1)] {
940            assert_eq!(
941                value.parse::<SecurityLabel>(),
942                Err(SecurityLabelError::InvalidByte { index }),
943                "accepted {value:?}"
944            );
945        }
946    }
947
948    #[test]
949    fn security_label_serde_and_schema_enforce_the_wire_contract() {
950        let label = from_value::<SecurityLabel>(json!("tenant:42/PII")).unwrap();
951        assert_eq!(label.as_str(), "tenant:42/PII");
952        assert!(from_value::<SecurityLabel>(json!(null)).is_err());
953        assert!(from_value::<SecurityLabel>(json!("bad label")).is_err());
954
955        let schema = to_value(schemars::schema_for!(SecurityLabel)).unwrap();
956        assert_eq!(schema["type"], "string");
957        assert_eq!(schema["minLength"], 1);
958        assert_eq!(schema["maxLength"], SecurityLabel::MAX_LEN);
959        assert_eq!(schema["pattern"], SECURITY_LABEL_PATTERN);
960    }
961
962    #[test]
963    fn content_security_metadata_has_exact_closed_wire_values() {
964        let metadata = ContentMetadata::new(
965            ContentSource::RemoteAgent,
966            ContentTrust::Untrusted,
967            label(),
968            RedactionState::Partial,
969        );
970        let expected = json!({
971            "source": "remote_agent",
972            "trust": "untrusted",
973            "security_label": "internal/pii",
974            "redaction": "partial"
975        });
976        assert_eq!(to_value(&metadata).unwrap(), expected);
977        assert_eq!(from_value::<ContentMetadata>(expected).unwrap(), metadata);
978
979        for invalid in [
980            json!({
981                "source": "remote_agent",
982                "trust": "trusted",
983                "security_label": "internal/pii",
984                "redaction": "partial"
985            }),
986            json!({
987                "source": "remote_agent",
988                "trust": "untrusted",
989                "security_label": "internal/pii",
990                "redaction": "partial",
991                "extra": true
992            }),
993        ] {
994            assert!(from_value::<ContentMetadata>(invalid).is_err());
995        }
996
997        let asserted = from_value::<ContentMetadata>(json!({
998            "source": "remote_agent",
999            "trust": "application_controlled",
1000            "security_label": "internal/pii",
1001            "redaction": "not_applied"
1002        }))
1003        .unwrap();
1004        assert_eq!(asserted.trust(), ContentTrust::ApplicationControlled);
1005
1006        let schema = to_value(schemars::schema_for!(ContentMetadata)).unwrap();
1007        assert_eq!(schema["type"], "object");
1008        assert_eq!(schema["additionalProperties"], false);
1009        assert_eq!(
1010            schema["required"],
1011            json!(["source", "trust", "security_label", "redaction"])
1012        );
1013    }
1014
1015    #[test]
1016    fn text_content_preserves_exact_unicode_without_normalization() {
1017        let composed = TextContent::new(
1018            "Café\n中文\tمرحبا",
1019            Some("FR-ca".parse().unwrap()),
1020            untrusted_user_metadata(),
1021        )
1022        .unwrap();
1023        assert_eq!(composed.text(), "Café\n中文\tمرحبا");
1024        assert_eq!(composed.language().unwrap().as_str(), "fr-ca");
1025
1026        let decomposed = TextContent::new("Cafe\u{301}", None, untrusted_user_metadata()).unwrap();
1027        let normalized = TextContent::new("Café", None, untrusted_user_metadata()).unwrap();
1028        assert_ne!(decomposed.text(), normalized.text());
1029    }
1030
1031    #[test]
1032    fn text_content_enforces_byte_and_scalar_limits() {
1033        assert_eq!(
1034            TextContent::new("", None, untrusted_user_metadata()),
1035            Err(TextContentError::Empty)
1036        );
1037
1038        let maximum = "a".repeat(TextContent::MAX_BYTES);
1039        assert!(TextContent::new(&maximum, None, untrusted_user_metadata()).is_ok());
1040        let too_long = format!("{maximum}a");
1041        assert_eq!(
1042            TextContent::new(&too_long, None, untrusted_user_metadata()),
1043            Err(TextContentError::TooLong {
1044                max: TextContent::MAX_BYTES,
1045                actual: TextContent::MAX_BYTES + 1,
1046            })
1047        );
1048
1049        let multi_byte_too_long = "界".repeat(TextContent::MAX_BYTES / 3 + 1);
1050        assert!(matches!(
1051            TextContent::new(&multi_byte_too_long, None, untrusted_user_metadata()),
1052            Err(TextContentError::TooLong { .. })
1053        ));
1054
1055        for (value, byte_index) in [
1056            ("a\0b", 1),
1057            ("a\u{1b}b", 1),
1058            ("a\u{7f}b", 1),
1059            ("a\u{80}b", 1),
1060            ("界\u{fdd0}", 3),
1061            ("a\u{fffe}", 1),
1062            ("a\u{10ffff}", 1),
1063        ] {
1064            assert_eq!(
1065                TextContent::new(value, None, untrusted_user_metadata()),
1066                Err(TextContentError::DisallowedCodePoint { byte_index }),
1067                "accepted {value:?}"
1068            );
1069        }
1070
1071        assert!(TextContent::new("a\tb\nc\rd", None, untrusted_user_metadata()).is_ok());
1072    }
1073
1074    #[test]
1075    fn text_content_rejects_every_c0_c1_control_and_unicode_noncharacter() {
1076        for code_point in (0_u32..=0x1f).chain(0x7f..=0x9f) {
1077            let scalar = char::from_u32(code_point).unwrap();
1078            let value = format!("a{scalar}b");
1079            let result = TextContent::new(&value, None, untrusted_user_metadata());
1080            if matches!(scalar, '\t' | '\n' | '\r') {
1081                assert!(result.is_ok(), "rejected allowed U+{code_point:04X}");
1082            } else {
1083                assert_eq!(
1084                    result,
1085                    Err(TextContentError::DisallowedCodePoint { byte_index: 1 }),
1086                    "accepted U+{code_point:04X}"
1087                );
1088            }
1089        }
1090
1091        let mut noncharacters: Vec<u32> = (0xfdd0..=0xfdef).collect();
1092        for plane in 0_u32..=0x10 {
1093            noncharacters.push(plane * 0x1_0000 + 0xfffe);
1094            noncharacters.push(plane * 0x1_0000 + 0xffff);
1095        }
1096
1097        for code_point in noncharacters {
1098            let scalar = char::from_u32(code_point).unwrap();
1099            let value = format!("a{scalar}");
1100            assert_eq!(
1101                TextContent::new(&value, None, untrusted_user_metadata()),
1102                Err(TextContentError::DisallowedCodePoint { byte_index: 1 }),
1103                "accepted U+{code_point:04X}"
1104            );
1105        }
1106    }
1107
1108    #[test]
1109    fn text_content_serde_revalidates_and_debug_redacts_text() {
1110        let expected = json!({
1111            "text": "secret-token-42",
1112            "language": "en-us",
1113            "metadata": {
1114                "source": "user",
1115                "trust": "untrusted",
1116                "security_label": "internal/pii",
1117                "redaction": "not_applied"
1118            }
1119        });
1120        let content = from_value::<TextContent>(expected.clone()).unwrap();
1121        assert_eq!(to_value(&content).unwrap(), expected);
1122
1123        let debug = format!("{content:?}");
1124        assert!(debug.contains("text_bytes: 15"));
1125        assert!(!debug.contains("secret-token-42"));
1126
1127        for invalid in [
1128            json!({
1129                "text": "bad\u{0}",
1130                "metadata": {
1131                    "source": "user",
1132                    "trust": "untrusted",
1133                    "security_label": "internal/pii",
1134                    "redaction": "not_applied"
1135                }
1136            }),
1137            json!({
1138                "text": "valid",
1139                "metadata": {
1140                    "source": "user",
1141                    "trust": "untrusted",
1142                    "security_label": "internal/pii",
1143                    "redaction": "not_applied"
1144                },
1145                "extra": true
1146            }),
1147        ] {
1148            assert!(from_value::<TextContent>(invalid).is_err());
1149        }
1150    }
1151
1152    #[test]
1153    fn text_content_schema_is_closed_and_documents_runtime_bounds() {
1154        let schema = to_value(schemars::schema_for!(TextContent)).unwrap();
1155        assert_eq!(schema["type"], "object");
1156        assert_eq!(schema["additionalProperties"], false);
1157        assert_eq!(schema["required"], json!(["text", "metadata"]));
1158        assert_eq!(schema["properties"]["text"]["minLength"], 1);
1159        assert_eq!(
1160            schema["properties"]["text"]["maxLength"],
1161            TextContent::MAX_BYTES
1162        );
1163        assert!(
1164            schema["properties"]["text"]["description"]
1165                .as_str()
1166                .unwrap()
1167                .contains("runtime")
1168        );
1169    }
1170
1171    #[test]
1172    fn json_content_round_trips_with_optional_schema_and_safe_debug() {
1173        let value =
1174            BoundedJson::from_str(r#"{"api_token_7391":"sensitive-payload-7391","count":2}"#)
1175                .unwrap();
1176        let content = JsonContent::new(
1177            value,
1178            Some(schema_reference()),
1179            ContentMetadata::untrusted(ContentSource::Tool, label()),
1180        );
1181        let encoded = to_value(&content).unwrap();
1182        assert_eq!(
1183            encoded["value"],
1184            json!({"api_token_7391": "sensitive-payload-7391", "count": 2})
1185        );
1186        assert!(encoded.get("schema").is_some());
1187        assert_eq!(from_value::<JsonContent>(encoded).unwrap(), content);
1188
1189        let debug = format!("{content:?}");
1190        assert!(debug.contains("compact_bytes"));
1191        assert!(!debug.contains("api_token_7391"));
1192        assert!(!debug.contains("sensitive-payload-7391"));
1193
1194        let without_schema = JsonContent::new(
1195            BoundedJson::from_str("true").unwrap(),
1196            None,
1197            untrusted_user_metadata(),
1198        );
1199        assert!(to_value(without_schema).unwrap().get("schema").is_none());
1200    }
1201
1202    #[test]
1203    fn json_content_wire_object_is_closed_and_bounded() {
1204        let metadata = json!({
1205            "source": "tool",
1206            "trust": "untrusted",
1207            "security_label": "internal/pii",
1208            "redaction": "not_applied"
1209        });
1210        assert!(
1211            from_value::<JsonContent>(json!({
1212                "value": true,
1213                "metadata": metadata,
1214                "extra": 1
1215            }))
1216            .is_err()
1217        );
1218
1219        let oversized = "x".repeat(crate::JsonLimits::DEFAULT.max_string_bytes() + 1);
1220        assert!(
1221            from_value::<JsonContent>(json!({
1222                "value": oversized,
1223                "metadata": {
1224                    "source": "tool",
1225                    "trust": "untrusted",
1226                    "security_label": "internal/pii",
1227                    "redaction": "not_applied"
1228                }
1229            }))
1230            .is_err()
1231        );
1232
1233        let schema = to_value(schemars::schema_for!(JsonContent)).unwrap();
1234        assert_eq!(schema["type"], "object");
1235        assert_eq!(schema["additionalProperties"], false);
1236        assert_eq!(schema["required"], json!(["value", "metadata"]));
1237    }
1238
1239    fn arbitrary_safe_text() -> impl Strategy<Value = String> {
1240        collection::vec(
1241            any::<char>().prop_filter("allowed text scalar", |scalar| {
1242                (!scalar.is_control() || matches!(scalar, '\t' | '\n' | '\r'))
1243                    && !is_unicode_noncharacter(*scalar)
1244            }),
1245            1..128,
1246        )
1247        .prop_map(|scalars| scalars.into_iter().collect())
1248    }
1249
1250    proptest! {
1251        #[test]
1252        fn valid_text_round_trips_without_unicode_or_byte_changes(text in arbitrary_safe_text()) {
1253            let content = TextContent::new(&text, None, untrusted_user_metadata()).unwrap();
1254            let encoded = to_value(&content).unwrap();
1255            let decoded = from_value::<TextContent>(encoded).unwrap();
1256
1257            prop_assert_eq!(decoded.text().as_bytes(), text.as_bytes());
1258            prop_assert_eq!(decoded, content);
1259        }
1260    }
1261}