acdp_server/registry/
lifecycle.rs

1//! Lifecycle endpoint request validation (ACDP 0.3, RFC-ACDP-0013 §6
2//! step 2) — the envelope layer for `POST /contexts/{ctx_id}/retract`
3//! and `POST /contexts/{ctx_id}/republish`.
4//!
5//! The request body is a CLOSED JSON object with exactly one member,
6//! `event`. A request that attempts to supply or alter **body content**
7//! through a lifecycle endpoint — a `body` member, or any envelope
8//! member named after a body field — MUST be rejected with the
9//! **`immutable_field`** wire code (HTTP 400), activated in 0.3.0 from
10//! the reservation held since v0.1.0 (RFC-ACDP-0007 §5, RFC-ACDP-0009
11//! §2.1): bodies are immutable, and lifecycle endpoints mutate registry
12//! state only. The distinct code exists so producers learn the
13//! *category* error, not a generic validation failure (fixture
14//! `lc-002`). Any other unknown envelope member is a plain
15//! `schema_violation` against the closed request shape.
16
17use acdp_primitives::error::AcdpError;
18use acdp_types::lifecycle::LifecycleEvent;
19
20/// The wire names of every [`Body`](acdp_types::body::Body) field
21/// (RFC-ACDP-0002 §3.1). An envelope member with one of these names is
22/// an attempt to modify immutable body content (`immutable_field`); the
23/// set matches the struct in `acdp-types/src/body.rs` — extend both
24/// together (the registry-assigned and integrity fields are included:
25/// none of them is writable through a lifecycle endpoint either).
26const BODY_FIELD_NAMES: &[&str] = &[
27    "body",
28    // Registry-assigned identity fields.
29    "ctx_id",
30    "lineage_id",
31    "origin_registry",
32    "created_at",
33    // Integrity fields.
34    "content_hash",
35    "signature",
36    // Producer-controlled fields.
37    "version",
38    "supersedes",
39    "agent_id",
40    "contributors",
41    "title",
42    "type",
43    "data_refs",
44    "derived_from",
45    "visibility",
46    "audience",
47    "acdp_version",
48    "description",
49    "summary",
50    "tags",
51    "domain",
52    "expires_at",
53    "data_period",
54    "metadata",
55    "schema_uri",
56    "anchors",
57    // RFC-ACDP-0021 §6.3.
58    "key_attestation",
59];
60
61/// Validate a raw lifecycle request body against the closed
62/// `{"event": {…}}` envelope (RFC-ACDP-0013 §6 step 2) and parse the
63/// event through the closed §4 schema.
64///
65/// Returns the parsed event together with the RAW event JSON — signature
66/// verification must hash the event exactly as received
67/// (`LifecycleEvent::preimage_hash_of_value`), never a re-serialization.
68///
69/// Errors:
70/// - [`AcdpError::ImmutableField`] — the envelope carries a `body`
71///   member or a member named after a body field (fixture `lc-002`
72///   scenarios A/B). Checked before the generic closed-shape rejection
73///   so the category error wins.
74/// - [`AcdpError::SchemaViolation`] — any other unknown envelope
75///   member, a missing/non-object `event`, or an event violating the
76///   closed §4 schema (including an unsigned producer event's later
77///   checks — see the server's endpoint pipeline).
78pub fn parse_lifecycle_request(
79    raw: &serde_json::Value,
80) -> Result<(LifecycleEvent, serde_json::Value), AcdpError> {
81    let map = raw.as_object().ok_or_else(|| {
82        AcdpError::SchemaViolation("lifecycle request body must be a JSON object".into())
83    })?;
84
85    for key in map.keys() {
86        if key == "event" {
87            continue;
88        }
89        if BODY_FIELD_NAMES.contains(&key.as_str()) {
90            return Err(AcdpError::ImmutableField(format!(
91                "lifecycle request member '{key}' attempts to supply or alter immutable \
92                 body content — bodies are immutable and lifecycle endpoints mutate \
93                 registry state only (RFC-ACDP-0013 §6 step 2)"
94            )));
95        }
96        return Err(AcdpError::SchemaViolation(format!(
97            "lifecycle request has unknown member '{key}' — the request body is a closed \
98             object with exactly one member, 'event' (RFC-ACDP-0013 §6)"
99        )));
100    }
101
102    let raw_event = map.get("event").ok_or_else(|| {
103        AcdpError::SchemaViolation(
104            "lifecycle request is missing the required 'event' member (RFC-ACDP-0013 §6)".into(),
105        )
106    })?;
107    let event = LifecycleEvent::from_value(raw_event)?;
108    Ok((event, raw_event.clone()))
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114    use serde_json::json;
115
116    fn valid_event() -> serde_json::Value {
117        json!({
118            "event_id": "018f6d0a-7b2e-4c4d-9e1f-3a5b7c9d1e2f",
119            "ctx_id": "acdp://registry.example.com/12345678-1234-4321-8123-123456781234",
120            "event_type": "retracted",
121            "occurred_at": "2026-07-04T09:15:42.000Z",
122            "actor": "did:web:agents.example.com:test-producer",
123            "reason": "underlying data source found to be fabricated",
124            "signature": {
125                "algorithm": "ed25519",
126                "key_id": "did:web:agents.example.com:test-producer#key-1",
127                "value": "AA=="
128            }
129        })
130    }
131
132    #[test]
133    fn valid_envelope_parses() {
134        let (event, raw) = parse_lifecycle_request(&json!({ "event": valid_event() })).unwrap();
135        assert_eq!(event.event_id, "018f6d0a-7b2e-4c4d-9e1f-3a5b7c9d1e2f");
136        assert_eq!(raw, valid_event());
137    }
138
139    /// lc-002 scenario A: a `body` member is the category error.
140    #[test]
141    fn body_member_is_immutable_field() {
142        let err = parse_lifecycle_request(&json!({
143            "event": valid_event(),
144            "body": { "title": "Corrected title" }
145        }))
146        .unwrap_err();
147        assert!(matches!(err, AcdpError::ImmutableField(_)), "got {err:?}");
148    }
149
150    /// lc-002 scenario B: a body-field-named member (here `summary`) is
151    /// the same category error — NOT a generic schema_violation.
152    #[test]
153    fn body_field_named_member_is_immutable_field() {
154        let err = parse_lifecycle_request(&json!({
155            "event": valid_event(),
156            "summary": "please update the summary too"
157        }))
158        .unwrap_err();
159        assert!(matches!(err, AcdpError::ImmutableField(_)), "got {err:?}");
160    }
161
162    /// `anchors` (RFC-ACDP-0016) is a `Body` field like any other — an
163    /// envelope member named `anchors` MUST be `immutable_field`, not a
164    /// generic `schema_violation`. Regression test: this field was added
165    /// to `Body` (PR #169) without being added to `BODY_FIELD_NAMES`.
166    #[test]
167    fn anchors_field_named_member_is_immutable_field() {
168        let err = parse_lifecycle_request(&json!({
169            "event": valid_event(),
170            "anchors": [{"scheme": "macp.commitment", "content_hash": "sha256:aa"}]
171        }))
172        .unwrap_err();
173        assert!(matches!(err, AcdpError::ImmutableField(_)), "got {err:?}");
174    }
175
176    /// An unknown member NOT naming body content is a plain
177    /// schema_violation against the closed envelope (lc-002 note).
178    #[test]
179    fn non_body_unknown_member_is_schema_violation() {
180        let err = parse_lifecycle_request(&json!({
181            "event": valid_event(),
182            "note": "hello"
183        }))
184        .unwrap_err();
185        assert!(matches!(err, AcdpError::SchemaViolation(_)), "got {err:?}");
186    }
187
188    #[test]
189    fn missing_event_member_rejected() {
190        let err = parse_lifecycle_request(&json!({})).unwrap_err();
191        assert!(matches!(err, AcdpError::SchemaViolation(_)));
192        let err = parse_lifecycle_request(&json!([1, 2])).unwrap_err();
193        assert!(matches!(err, AcdpError::SchemaViolation(_)));
194    }
195}
acdp_server/registry/lifecycle.rs

acdp_server/registry/
lifecycle.rs
