Skip to main content

ratify_protocol/v2/reference/
device_state.rs

1//! Complete security state of a single-device offline primary (SPEC-v2
2//! §7.13), TEST ONLY. Mirrors Go `v2reference/device_state.go`.
3//!
4//! [`DevicePrimaryTestOnly`] groups every durable security record the
5//! primary holds: the claim store with its release records, stream
6//! sequences, rate counters and receipt log ([`Store`]), its anchored
7//! `SecurityJournalV2` store, its challenge issuance records, and its replay
8//! epoch. Its complete-state digest is a labelled SHA-384 over a versioned
9//! canonical projection of all of them. Once bound to a device component,
10//! every durable change in any of these stores is anchored in the component
11//! before it takes effect; a change the component refuses is undone.
12//!
13//! Every record is projected in the normative record encoding of SPEC-v2
14//! §7.13, so the digest is reproducible across implementations and
15//! upgrades; `testvectors/v2/device-state.json` pins it byte for byte.
16
17use std::sync::{Arc, Mutex, MutexGuard};
18
19use base64::{engine::general_purpose::STANDARD, Engine as _};
20use serde_json::{json, Value};
21use sha2::{Digest, Sha384};
22
23use super::challenges::TestOnlyChallengeIssuanceStore;
24use super::journal::JournalStore;
25use super::offline_device::DeviceComponentTestOnly;
26use super::store::{ClaimRecord, ClaimState, Store, StoreAnchor, StoreState};
27use crate::v2::challenge_issuance::V2ChallengeIssuanceStore;
28use crate::v2::claim_store::{V2ChallengeClaim, V2StoreError};
29use crate::v2::context::V2Context;
30use crate::v2::errors::{V2Error, V2ErrorClass, V2Result};
31use crate::v2::evaluation_progress::V2EvaluationProgress;
32use crate::v2::journal::{
33    SecurityJournalHeadV2, SecurityJournalStoreErrorV2, SecurityJournalStoreV2, SecurityJournalV2,
34};
35use crate::v2::json::canonical_json_v2;
36use crate::v2::preflight::ExpectedChallengeV2;
37
38/// The domain label of the complete-state digest.
39const DEVICE_STATE_LABEL: &str = "ratify/device-complete-state/v2";
40/// The projection version.
41const DEVICE_STATE_VERSION: i64 = 1;
42
43/// The member digests of a [`Store`]'s durable state (Go
44/// `storeStateTestOnly`).
45#[derive(Debug, Clone, Default, PartialEq, Eq)]
46pub(crate) struct StoreDigests {
47    claims: String,
48    streams: String,
49    rate_counters: String,
50    receipt_log: String,
51}
52
53fn sha384_hex(b: &[u8]) -> String {
54    hex::encode(Sha384::digest(b))
55}
56
57fn canonical(v: &Value) -> V2Result<Vec<u8>> {
58    let body = serde_json::to_vec(v).map_err(|e| V2Error::plain(format!("v2reference: projection: {e}")))?;
59    canonical_json_v2(&body)
60}
61
62/// Padded base64 of a held byte string, or `null` when none is held.
63fn bytes_or_null(b: &[u8]) -> Value {
64    if b.is_empty() {
65        Value::Null
66    } else {
67        Value::String(STANDARD.encode(b))
68    }
69}
70
71/// Unlabelled lowercase hex SHA-384 of exact stored bytes, or `null` when
72/// none are stored.
73fn sha384_or_null(b: &[u8]) -> Value {
74    if b.is_empty() {
75        Value::Null
76    } else {
77        Value::String(sha384_hex(b))
78    }
79}
80
81/// The sealed claim object of §7.13.
82fn sealed_claim_projection(c: &V2ChallengeClaim) -> Value {
83    let evaluators: Vec<Value> = c
84        .constraint_evaluators
85        .iter()
86        .map(|e| json!({"profile_digest": e.profile_digest, "type": e.kind}))
87        .collect();
88    let rate_batch: Vec<Value> = c
89        .rate_batch
90        .iter()
91        .map(|r| json!({"cert_id": r.cert_id, "issuer_id": r.issuer_id, "limit": r.limit, "window_s": r.window_s}))
92        .collect();
93    let policy = if c.context_policy_digest.is_empty() {
94        Value::Null
95    } else {
96        Value::String(c.context_policy_digest.clone())
97    };
98    json!({
99        "agent_id": c.agent_id,
100        "bundle_hash": c.bundle_hash,
101        "challenge_digest": c.challenge_digest,
102        "claim_id": c.claim_id,
103        "clock_skew_seconds": c.clock_skew_seconds,
104        "constraint_evaluators": evaluators,
105        "context_policy_digest": policy,
106        "expires_at": c.expires_at,
107        "issued_at": c.issued_at,
108        "issuer_ids": c.issuer_ids,
109        "max_age_seconds": c.max_age_seconds,
110        "namespace": c.namespace,
111        "proof_digest": c.proof_digest,
112        "rate_batch": rate_batch,
113        "replay_epoch": c.replay_epoch,
114        "required_scope": c.required_scope,
115        "requires_rate": c.requires_rate,
116        "stream_id": bytes_or_null(c.stream_id.as_deref().unwrap_or_default()),
117        "stream_seq": c.stream_seq,
118        "verifier_id": c.verifier_id,
119    })
120}
121
122/// The evaluation progress object of §7.5 with its five members.
123fn progress_projection(p: &V2EvaluationProgress) -> Value {
124    let evidence: Vec<Value> = p
125        .status_evidence
126        .iter()
127        .map(|e| {
128            json!({
129                "digest": e.digest,
130                "issuer_id": e.issuer_id,
131                "object_type_code": e.object_type,
132                "sequence": e.sequence,
133                "status_key_id": e.status_key_id,
134            })
135        })
136        .collect();
137    json!({
138        "context_assessment": p.context_assessment,
139        "context_policy_digest": p.context_policy_digest,
140        "status_assessment": p.status_assessment,
141        "status_evidence_digests": evidence,
142        "trust_assessment": p.trust_assessment,
143    })
144}
145
146fn claim_projection(id: &str, r: &ClaimRecord) -> Value {
147    let release = r.release.as_ref().map(|rel| {
148        let reason = (!rel.reason.is_empty()).then_some(rel.reason.as_str());
149        json!({"ack_timestamp": rel.ack_timestamp, "claim_id": rel.claim_id, "entry_hash": STANDARD.encode(&rel.entry_hash),
150            "outcome": rel.outcome.as_str(), "reason": reason})
151    });
152    let state = match r.state {
153        ClaimState::Evaluating => "evaluating",
154        ClaimState::Terminal => "terminal",
155    };
156    json!({
157        "abandoned": r.abandoned,
158        "allow_horizon": r.allow_horizon,
159        "claim": sealed_claim_projection(&r.claim),
160        "claim_id": id,
161        "claimed_at": r.claimed_at,
162        "finalized_at": r.finalized_at,
163        "lease_expires_at": r.lease_expires_at,
164        "log_sequence": r.outbox_index.map(|i| i as i64 + 1),
165        "owner_digest": STANDARD.encode(r.owner_digest),
166        "progress": progress_projection(&r.progress),
167        "receipt_body_sha384": sha384_or_null(&r.receipt_body),
168        "release": release,
169        "state": state,
170        "terminal_sha384": sha384_or_null(&r.terminal),
171    })
172}
173
174fn issuance_projection(e: &ExpectedChallengeV2) -> Value {
175    let agent_key = e.expected_agent_public_key.as_ref().map(|k| {
176        json!({"ed25519": STANDARD.encode(&k.ed25519), "ml_dsa_65": STANDARD.encode(&k.ml_dsa_65)})
177    });
178    let policy = e.context_policy.as_ref().map(|p| {
179        json!({
180            "expected_session_context": bytes_or_null(&p.expected_session_context()),
181            "profile": p.profile(),
182            "require_bound": p.require_bound(),
183            "required_fields": p.required_fields(),
184            "version": 1,
185        })
186    });
187    json!({
188        "context_policy": policy,
189        "expected_agent_id": e.expected_agent_id,
190        "expected_agent_pub_key": agent_key,
191        "expected_receiver_id": e.expected_receiver_id,
192        "expected_session_context": bytes_or_null(e.expected_session_context.as_deref().unwrap_or_default()),
193        "expires_at": e.expires_at,
194        "issued_at": e.issued_at,
195        "replay_epoch": e.replay_epoch,
196        "value": STANDARD.encode(&e.value),
197        "verifier_id": e.verifier_id,
198        "verifier_namespace": e.verifier_namespace,
199    })
200}
201
202/// The RatifyCanonicalJSON of the store's projection members.
203pub(crate) struct StoreMembers {
204    pub(crate) claims: Vec<u8>,
205    pub(crate) streams: Vec<u8>,
206    pub(crate) rate_counters: Vec<u8>,
207    pub(crate) receipt_log: Vec<u8>,
208}
209
210/// Go `storeMembersLocked`: every claim in every state (evaluating,
211/// terminal, interrupted, abandoned) with its sealed values and release
212/// record, every stream sequence, every rate counter, and the receipt log
213/// with its outbox, in the §7.13 record encodings. Checkpoint
214/// acknowledgements and clock readings are excluded.
215pub(crate) fn store_members(s: &StoreState) -> V2Result<StoreMembers> {
216    // BTreeMap iteration yields each collection in its §7.13 sort order:
217    // strings compare by UTF-8 bytes, byte strings by unsigned bytes.
218    let claims: Vec<Value> = s.claims.iter().map(|(id, r)| claim_projection(id, r)).collect();
219    let streams: Vec<Value> = s
220        .streams
221        .iter()
222        .map(|((namespace, agent_id, stream_id), seq)| {
223            json!({"agent_id": agent_id, "last_sequence": seq, "namespace": namespace, "stream_id": STANDARD.encode(stream_id)})
224        })
225        .collect();
226    let rates: Vec<Value> = s
227        .rate_commits
228        .iter()
229        .map(|((issuer, cert, window), commits)| {
230            json!({"cert_id": cert, "commits": commits, "issuer_id": issuer, "window_s": window})
231        })
232        .collect();
233    let entries: Vec<Value> = s
234        .outbox
235        .iter()
236        .enumerate()
237        .map(|(i, e)| {
238            json!({
239                "body_sha384": sha384_hex(&e.body),
240                "claim_id": e.claim_id,
241                "entry_hash": bytes_or_null(&e.digest),
242                "sequence": i + 1,
243            })
244        })
245        .collect();
246    Ok(StoreMembers {
247        claims: canonical(&Value::Array(claims))?,
248        streams: canonical(&Value::Array(streams))?,
249        rate_counters: canonical(&Value::Array(rates))?,
250        receipt_log: canonical(&json!({"entries": entries, "frozen": s.log_frozen, "log_id": s.log_id}))?,
251    })
252}
253
254/// Go `stateDigestsLocked`: the digests of the store members.
255pub(crate) fn store_state_digests(s: &StoreState) -> V2Result<StoreDigests> {
256    let m = store_members(s)?;
257    Ok(StoreDigests {
258        claims: sha384_hex(&m.claims),
259        streams: sha384_hex(&m.streams),
260        rate_counters: sha384_hex(&m.rate_counters),
261        receipt_log: sha384_hex(&m.receipt_log),
262    })
263}
264
265/// Go `issuanceMemberLocked`: the RatifyCanonicalJSON of the
266/// `issuance_records` member, sorted by (verifier_namespace, replay_epoch,
267/// value).
268fn issuance_member(issuance: &TestOnlyChallengeIssuanceStore) -> V2Result<Vec<u8>> {
269    let mut records: Vec<ExpectedChallengeV2> = issuance.records().into_values().collect();
270    records.sort_by(|a, b| {
271        a.verifier_namespace
272            .as_bytes()
273            .cmp(b.verifier_namespace.as_bytes())
274            .then(a.replay_epoch.cmp(&b.replay_epoch))
275            .then(a.value.cmp(&b.value))
276    });
277    canonical(&Value::Array(records.iter().map(issuance_projection).collect()))
278}
279
280/// Go `completeStateDigest`: the labelled SHA-384 of the projection bytes.
281fn complete_state_digest(projection: &[u8]) -> Vec<u8> {
282    let mut h = Sha384::new();
283    h.update(DEVICE_STATE_LABEL.as_bytes());
284    h.update([0u8]);
285    h.update(projection);
286    h.finalize().to_vec()
287}
288
289/// The anchor lock's state: the bound component and the store member
290/// digests of the last anchored state.
291pub(crate) struct AnchorState {
292    pub(crate) component: Option<Arc<DeviceComponentTestOnly>>,
293    pub(crate) last_store: StoreDigests,
294}
295
296/// What the primary and its sub-stores share: the anchor lock (Go
297/// `DevicePrimaryTestOnly.mu`), the journal and issuance records, the log
298/// ID, and the replay epoch.
299pub(crate) struct PrimaryShared {
300    replay_epoch: i64,
301    log_id: String,
302    journal: JournalStore,
303    issuance: TestOnlyChallengeIssuanceStore,
304    anchor: Mutex<AnchorState>,
305}
306
307impl PrimaryShared {
308    /// The anchor lock. Lock order: a sub-store's own lock, then this lock,
309    /// then the journal or issuance store lock and the component lock.
310    pub(crate) fn lock_anchor(&self) -> MutexGuard<'_, AnchorState> {
311        self.anchor.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
312    }
313
314    /// Go `projectionLocked`: the RatifyCanonicalJSON of the version 1
315    /// projection object.
316    fn projection(&self, store: &StoreDigests, issuance_digest: &str) -> V2Result<Vec<u8>> {
317        let (head, snapshot) = self.journal.anchored();
318        canonical(&json!({
319            "claims": store.claims,
320            "issuance_records": issuance_digest,
321            "log_id": self.log_id,
322            "rate_counters": store.rate_counters,
323            "receipt_log": store.receipt_log,
324            "replay_epoch": self.replay_epoch,
325            "security_journal": {"generation": head.generation, "snapshot_sha384": sha384_hex(&snapshot)},
326            "streams": store.streams,
327            "version": DEVICE_STATE_VERSION,
328        }))
329    }
330
331    /// Go `composeLocked`: the complete-state digest for the given store
332    /// member digests and the current journal and issuance records.
333    pub(crate) fn compose(&self, store: &StoreDigests) -> V2Result<Vec<u8>> {
334        let issuance = issuance_member(&self.issuance)?;
335        Ok(complete_state_digest(&self.projection(store, &sha384_hex(&issuance))?))
336    }
337
338    /// Go `CompleteStateDigestTestOnly`: recompute the digest from the
339    /// primary's current records.
340    pub(crate) fn complete_state_digest(&self, store: &Store) -> V2Result<Vec<u8>> {
341        let current = store_state_digests(&store.lock())?;
342        let _anchor = self.lock_anchor();
343        self.compose(&current)
344    }
345
346    /// Go `anchorStore`: the store hook, run with the store lock held.
347    fn anchor_store(&self, previous: &StoreState, next: &StoreState) -> Result<(), V2Error> {
348        let (previous, next) = (store_state_digests(previous)?, store_state_digests(next)?);
349        let mut anchor = self.lock_anchor();
350        let before = self.compose(&previous)?;
351        let after = self.compose(&next)?;
352        let component = anchor
353            .component
354            .clone()
355            .ok_or_else(|| V2Error::plain("v2reference: device primary is not bound"))?;
356        component
357            .anchor_state(&before, &after)
358            .map_err(|e| V2Error::plain(e.to_string()))?;
359        anchor.last_store = next;
360        Ok(())
361    }
362
363    /// Go `changeOther`: apply a journal or issuance change. With a bound
364    /// component the change is anchored before it takes effect and undone if
365    /// the component refuses it; `apply`'s own result is returned when
366    /// anchoring succeeds or nothing changed.
367    fn change_other<E>(
368        &self,
369        apply: impl FnOnce() -> Result<(), E>,
370        undo: impl FnOnce(),
371        unanchored: impl FnOnce(V2Error) -> E,
372    ) -> Result<(), E> {
373        let anchor = self.lock_anchor();
374        let Some(component) = anchor.component.clone() else {
375            return apply();
376        };
377        let before = match self.compose(&anchor.last_store) {
378            Ok(d) => d,
379            Err(e) => return Err(unanchored(e)),
380        };
381        let applied = apply();
382        let failure = match self.compose(&anchor.last_store) {
383            Err(e) => Some(e.message),
384            Ok(after) if after != before => component.anchor_state(&before, &after).err().map(|e| e.to_string()),
385            Ok(_) => None,
386        };
387        if let Some(message) = failure {
388            undo();
389            return Err(unanchored(V2Error::new(
390                V2ErrorClass::ClaimStoreUnavailable,
391                format!("v2reference: durable state change was not anchored: {message}"),
392            )));
393        }
394        applied
395    }
396}
397
398/// The primary of the single-device offline profile (Go
399/// `DevicePrimaryTestOnly`). TEST ONLY.
400pub struct DevicePrimaryTestOnly {
401    pub store: Arc<Store>,
402    pub journal: DeviceJournalTestOnly,
403    pub issuance: DeviceIssuanceTestOnly,
404    pub(crate) shared: Arc<PrimaryShared>,
405}
406
407impl std::fmt::Debug for DevicePrimaryTestOnly {
408    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
409        f.debug_struct("DevicePrimaryTestOnly")
410            .field("store", &self.store)
411            .field("replay_epoch", &self.shared.replay_epoch)
412            .finish_non_exhaustive()
413    }
414}
415
416impl DevicePrimaryTestOnly {
417    /// Go `NewDevicePrimaryTestOnly`: wrap `store` with an empty anchored
418    /// journal store and an empty issuance store, serving `replay_epoch`.
419    pub fn new(store: Arc<Store>, replay_epoch: i64) -> V2Result<Self> {
420        if replay_epoch < 0 {
421            return Err(V2Error::new(
422                V2ErrorClass::ConfigurationInvalid,
423                "v2reference: device primary needs a store and a non-negative replay epoch",
424            ));
425        }
426        let log_id = store.lock().log_id.clone();
427        Ok(Self::assemble(store, replay_epoch, log_id, JournalStore::new()?, TestOnlyChallengeIssuanceStore::new()))
428    }
429
430    fn assemble(
431        store: Arc<Store>,
432        replay_epoch: i64,
433        log_id: String,
434        journal: JournalStore,
435        issuance: TestOnlyChallengeIssuanceStore,
436    ) -> Self {
437        let shared = Arc::new(PrimaryShared {
438            replay_epoch,
439            log_id,
440            journal,
441            issuance,
442            anchor: Mutex::new(AnchorState {
443                component: None,
444                last_store: StoreDigests::default(),
445            }),
446        });
447        DevicePrimaryTestOnly {
448            store,
449            journal: DeviceJournalTestOnly {
450                shared: Arc::clone(&shared),
451            },
452            issuance: DeviceIssuanceTestOnly {
453                shared: Arc::clone(&shared),
454            },
455            shared,
456        }
457    }
458
459    /// Go `Clone`: copy the complete primary state, modelling a backup or
460    /// snapshot. The copy is not bound to any component.
461    pub fn clone_primary(&self) -> Self {
462        let (head, snapshot) = self.shared.journal.anchored();
463        let issuance = TestOnlyChallengeIssuanceStore::new();
464        issuance.set_records(self.shared.issuance.records());
465        Self::assemble(
466            Arc::new(self.store.clone_store()),
467            self.shared.replay_epoch,
468            self.shared.log_id.clone(),
469            JournalStore::from_anchored(head, snapshot),
470            issuance,
471        )
472    }
473
474    /// Go `bind`: attach the component and anchor every later durable
475    /// change in it.
476    pub(crate) fn bind(&self, component: Arc<DeviceComponentTestOnly>) -> V2Result<()> {
477        let current = store_state_digests(&self.store.lock())?;
478        {
479            let mut anchor = self.shared.lock_anchor();
480            anchor.component = Some(component);
481            anchor.last_store = current;
482        }
483        let shared = Arc::clone(&self.shared);
484        let hook: StoreAnchor = Arc::new(move |previous, next| shared.anchor_store(previous, next));
485        self.store.lock().anchor = Some(hook);
486        Ok(())
487    }
488
489    /// Go `CompleteStateDigestTestOnly`.
490    pub fn complete_state_digest_test_only(&self) -> V2Result<Vec<u8>> {
491        self.shared.complete_state_digest(&self.store)
492    }
493
494    /// The §7.13 projection of the primary's current records: the canonical
495    /// bytes of every member, the projection object, and the complete-state
496    /// digest.
497    pub fn projection_test_only(&self) -> V2Result<DeviceStateProjectionTestOnly> {
498        let members = store_members(&self.store.lock())?;
499        let issuance_records = issuance_member(&self.shared.issuance)?;
500        let digests = StoreDigests {
501            claims: sha384_hex(&members.claims),
502            streams: sha384_hex(&members.streams),
503            rate_counters: sha384_hex(&members.rate_counters),
504            receipt_log: sha384_hex(&members.receipt_log),
505        };
506        let projection = self.shared.projection(&digests, &sha384_hex(&issuance_records))?;
507        Ok(DeviceStateProjectionTestOnly {
508            claims: members.claims,
509            streams: members.streams,
510            rate_counters: members.rate_counters,
511            receipt_log: members.receipt_log,
512            issuance_records,
513            complete_state_digest: complete_state_digest(&projection),
514            projection,
515        })
516    }
517
518    /// A primary holding exactly the records of one `state` object of
519    /// `testvectors/v2/device-state.json` (the §7.13 record encodings, with
520    /// sealed bytes as `terminal_b64`, `receipt_body_b64`, `body_b64`, and
521    /// `snapshot_b64`).
522    pub fn from_records_test_only(state_json: &[u8]) -> V2Result<Self> {
523        load_records(state_json).map_err(|e| e.classify(V2ErrorClass::Malformed))
524    }
525}
526
527/// The canonical bytes of every §7.13 projection member, the projection
528/// object, and the complete-state digest of a primary. TEST ONLY.
529#[derive(Debug, Clone, PartialEq, Eq)]
530pub struct DeviceStateProjectionTestOnly {
531    pub claims: Vec<u8>,
532    pub streams: Vec<u8>,
533    pub rate_counters: Vec<u8>,
534    pub receipt_log: Vec<u8>,
535    pub issuance_records: Vec<u8>,
536    pub projection: Vec<u8>,
537    pub complete_state_digest: Vec<u8>,
538}
539
540fn field<'a>(v: &'a Value, key: &str) -> V2Result<&'a Value> {
541    v.get(key).ok_or_else(|| V2Error::plain(format!("v2reference: device state: missing {key:?}")))
542}
543
544fn text(v: &Value, key: &str) -> V2Result<String> {
545    field(v, key)?
546        .as_str()
547        .map(str::to_string)
548        .ok_or_else(|| V2Error::plain(format!("v2reference: device state: {key:?} is not a string")))
549}
550
551fn int(v: &Value, key: &str) -> V2Result<i64> {
552    field(v, key)?
553        .as_i64()
554        .ok_or_else(|| V2Error::plain(format!("v2reference: device state: {key:?} is not an integer")))
555}
556
557fn flag(v: &Value, key: &str) -> V2Result<bool> {
558    field(v, key)?
559        .as_bool()
560        .ok_or_else(|| V2Error::plain(format!("v2reference: device state: {key:?} is not a boolean")))
561}
562
563fn items<'a>(v: &'a Value, key: &str) -> V2Result<&'a Vec<Value>> {
564    field(v, key)?
565        .as_array()
566        .ok_or_else(|| V2Error::plain(format!("v2reference: device state: {key:?} is not an array")))
567}
568
569fn texts(v: &Value, key: &str) -> V2Result<Vec<String>> {
570    items(v, key)?
571        .iter()
572        .map(|x| x.as_str().map(str::to_string).ok_or_else(|| V2Error::plain("v2reference: device state: expected strings")))
573        .collect()
574}
575
576/// Base64 bytes, or empty for `null`.
577fn opt_bytes(v: &Value, key: &str) -> V2Result<Option<Vec<u8>>> {
578    match field(v, key)? {
579        Value::Null => Ok(None),
580        Value::String(s) => STANDARD
581            .decode(s)
582            .map(Some)
583            .map_err(|_| V2Error::plain(format!("v2reference: device state: {key:?} is not base64"))),
584        _ => Err(V2Error::plain(format!("v2reference: device state: {key:?} is not base64 or null"))),
585    }
586}
587
588fn bytes(v: &Value, key: &str) -> V2Result<Vec<u8>> {
589    Ok(opt_bytes(v, key)?.unwrap_or_default())
590}
591
592fn load_records(state_json: &[u8]) -> V2Result<DevicePrimaryTestOnly> {
593    use crate::v2::claim_store::V2ChallengeClaim;
594    use crate::v2::context_policy::V2ContextPolicy;
595    use crate::v2::evaluator::ConstraintEvaluatorRefV2;
596    use crate::v2::rate_reservation::V2RateReservation;
597    use crate::v2::receipt::StatusEvidenceEntryV2;
598    use crate::v2::release::{V2ReleaseRecord, V2ReleaseStatus};
599    use super::store::OutboxEntry;
600
601    let st: Value = serde_json::from_slice(state_json)
602        .map_err(|e| V2Error::plain(format!("v2reference: device state is not JSON: {e}")))?;
603    let (_, private) = crate::crypto::generate_hybrid_keypair();
604    let store = Store::new(1_800_000_000, 30, &text(&st, "log_id")?, &private)?;
605    {
606        let mut s = store.lock();
607        for c in items(&st, "claims")? {
608            let sc = field(c, "claim")?;
609            let mut evaluators = Vec::new();
610            for e in items(sc, "constraint_evaluators")? {
611                evaluators.push(ConstraintEvaluatorRefV2 { kind: text(e, "type")?, profile_digest: text(e, "profile_digest")? });
612            }
613            let mut rate_batch = Vec::new();
614            for r in items(sc, "rate_batch")? {
615                rate_batch.push(V2RateReservation {
616                    issuer_id: text(r, "issuer_id")?,
617                    cert_id: text(r, "cert_id")?,
618                    window_s: int(r, "window_s")?,
619                    limit: int(r, "limit")?,
620                });
621            }
622            let claim = V2ChallengeClaim {
623                claim_id: text(sc, "claim_id")?,
624                namespace: text(sc, "namespace")?,
625                replay_epoch: int(sc, "replay_epoch")?,
626                challenge_digest: text(sc, "challenge_digest")?,
627                proof_digest: text(sc, "proof_digest")?,
628                bundle_hash: text(sc, "bundle_hash")?,
629                issuer_ids: texts(sc, "issuer_ids")?,
630                required_scope: text(sc, "required_scope")?,
631                context_policy_digest: field(sc, "context_policy_digest")?.as_str().unwrap_or_default().to_string(),
632                verifier_id: text(sc, "verifier_id")?,
633                agent_id: text(sc, "agent_id")?,
634                requires_rate: flag(sc, "requires_rate")?,
635                rate_batch,
636                issued_at: int(sc, "issued_at")?,
637                expires_at: int(sc, "expires_at")?,
638                max_age_seconds: int(sc, "max_age_seconds")?,
639                clock_skew_seconds: int(sc, "clock_skew_seconds")?,
640                stream_id: opt_bytes(sc, "stream_id")?,
641                stream_seq: field(sc, "stream_seq")?.as_i64(),
642                constraint_evaluators: evaluators,
643            };
644            let p = field(c, "progress")?;
645            let mut evidence = Vec::new();
646            for e in items(p, "status_evidence_digests")? {
647                evidence.push(StatusEvidenceEntryV2 {
648                    issuer_id: text(e, "issuer_id")?,
649                    status_key_id: text(e, "status_key_id")?,
650                    sequence: int(e, "sequence")?,
651                    object_type: u16::try_from(int(e, "object_type_code")?)
652                        .map_err(|_| V2Error::plain("v2reference: device state: object type code out of range"))?,
653                    digest: text(e, "digest")?,
654                });
655            }
656            let progress = V2EvaluationProgress {
657                trust_assessment: text(p, "trust_assessment")?,
658                status_assessment: text(p, "status_assessment")?,
659                context_assessment: text(p, "context_assessment")?,
660                context_policy_digest: field(p, "context_policy_digest")?.as_str().map(str::to_string),
661                status_evidence: evidence,
662            };
663            let release = match field(c, "release")? {
664                Value::Null => None,
665                r => Some(V2ReleaseRecord {
666                    claim_id: text(r, "claim_id")?,
667                    entry_hash: bytes(r, "entry_hash")?,
668                    ack_timestamp: int(r, "ack_timestamp")?,
669                    outcome: match text(r, "outcome")?.as_str() {
670                        "released" => V2ReleaseStatus::Released,
671                        "withheld" => V2ReleaseStatus::Withheld,
672                        _ => return Err(V2Error::plain("v2reference: device state: unknown release outcome")),
673                    },
674                    reason: field(r, "reason")?.as_str().unwrap_or_default().to_string(),
675                }),
676            };
677            let owner = bytes(c, "owner_digest")?;
678            let owner_digest: [u8; 32] = owner
679                .try_into()
680                .map_err(|_| V2Error::plain("v2reference: device state: owner_digest is not 32 bytes"))?;
681            let outbox_index = match field(c, "log_sequence")?.as_i64() {
682                Some(n) if n >= 1 => Some((n - 1) as usize),
683                Some(_) => return Err(V2Error::plain("v2reference: device state: log_sequence starts at 1")),
684                None => None,
685            };
686            let state = match text(c, "state")?.as_str() {
687                "evaluating" => ClaimState::Evaluating,
688                "terminal" => ClaimState::Terminal,
689                other => return Err(V2Error::plain(format!("v2reference: device state: unknown claim state {other:?}"))),
690            };
691            s.claims.insert(
692                text(c, "claim_id")?,
693                ClaimRecord {
694                    claim,
695                    owner_digest,
696                    lease_expires_at: int(c, "lease_expires_at")?,
697                    state,
698                    terminal: bytes(c, "terminal_b64")?,
699                    receipt_body: bytes(c, "receipt_body_b64")?,
700                    allow_horizon: int(c, "allow_horizon")?,
701                    claimed_at: int(c, "claimed_at")?,
702                    finalized_at: int(c, "finalized_at")?,
703                    release,
704                    progress,
705                    abandoned: flag(c, "abandoned")?,
706                    outbox_index,
707                },
708            );
709        }
710        for x in items(&st, "streams")? {
711            s.streams.insert(
712                (text(x, "namespace")?, text(x, "agent_id")?, bytes(x, "stream_id")?),
713                int(x, "last_sequence")?,
714            );
715        }
716        for r in items(&st, "rate_counters")? {
717            let commits = items(r, "commits")?
718                .iter()
719                .map(|n| n.as_i64().ok_or_else(|| V2Error::plain("v2reference: device state: commit is not an integer")))
720                .collect::<V2Result<Vec<i64>>>()?;
721            s.rate_commits.insert((text(r, "issuer_id")?, text(r, "cert_id")?, int(r, "window_s")?), commits);
722        }
723        let log = field(&st, "receipt_log")?;
724        for e in items(log, "entries")? {
725            s.outbox.push(OutboxEntry {
726                claim_id: text(e, "claim_id")?,
727                body: bytes(e, "body_b64")?,
728                wire: None,
729                digest: bytes(e, "entry_hash")?,
730                ack: None,
731            });
732        }
733        s.log_frozen = flag(log, "frozen")?;
734    }
735    let journal_state = field(&st, "security_journal")?;
736    let generation = u64::try_from(int(journal_state, "generation")?)
737        .map_err(|_| V2Error::plain("v2reference: device state: negative journal generation"))?;
738    let snapshot = bytes(journal_state, "snapshot_b64")?;
739    let head = SecurityJournalHeadV2 {
740        generation,
741        digest: crate::v2::journal_snapshot::security_journal_snapshot_digest_v2(&snapshot),
742    };
743    let issuance = TestOnlyChallengeIssuanceStore::new();
744    let mut records = std::collections::BTreeMap::new();
745    for r in items(&st, "issuance_records")? {
746        let context_policy = match field(r, "context_policy")? {
747            Value::Null => None,
748            p => Some(V2ContextPolicy::new(
749                &text(p, "profile")?,
750                flag(p, "require_bound")?,
751                &texts(p, "required_fields")?,
752                &bytes(p, "expected_session_context")?,
753            )?),
754        };
755        let expected_agent_public_key = match field(r, "expected_agent_pub_key")? {
756            Value::Null => None,
757            k => Some(crate::types::HybridPublicKey { ed25519: bytes(k, "ed25519")?, ml_dsa_65: bytes(k, "ml_dsa_65")? }),
758        };
759        let record = ExpectedChallengeV2 {
760            value: bytes(r, "value")?,
761            issued_at: int(r, "issued_at")?,
762            expires_at: int(r, "expires_at")?,
763            verifier_namespace: text(r, "verifier_namespace")?,
764            replay_epoch: int(r, "replay_epoch")?,
765            verifier_id: text(r, "verifier_id")?,
766            expected_agent_id: text(r, "expected_agent_id")?,
767            expected_agent_public_key,
768            expected_receiver_id: text(r, "expected_receiver_id")?,
769            expected_session_context: opt_bytes(r, "expected_session_context")?,
770            context_policy,
771        };
772        let digest = crate::v2::operation_context::challenge_claim_digest_v2(&record.value)?;
773        records.insert(
774            super::challenges::issuance_key(&record.verifier_namespace, record.replay_epoch, &digest),
775            record,
776        );
777    }
778    issuance.set_records(records);
779    let store = Arc::new(store);
780    let log_id = store.lock().log_id.clone();
781    Ok(DevicePrimaryTestOnly::assemble(
782        store,
783        int(&st, "replay_epoch")?,
784        log_id,
785        JournalStore::from_anchored(head, snapshot),
786        issuance,
787    ))
788}
789
790/// The primary's anchored `SecurityJournalV2` store (Go
791/// `DeviceJournalTestOnly`).
792pub struct DeviceJournalTestOnly {
793    shared: Arc<PrimaryShared>,
794}
795
796impl std::fmt::Debug for DeviceJournalTestOnly {
797    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
798        f.debug_struct("DeviceJournalTestOnly").field("head", &self.head()).finish()
799    }
800}
801
802impl DeviceJournalTestOnly {
803    /// The journal's anchored head.
804    pub fn head(&self) -> SecurityJournalHeadV2 {
805        self.shared.journal.head()
806    }
807}
808
809impl SecurityJournalStoreV2 for DeviceJournalTestOnly {
810    fn load(&self, ctx: &V2Context) -> V2Result<(SecurityJournalV2, SecurityJournalHeadV2)> {
811        self.shared.journal.load(ctx)
812    }
813
814    /// The new journal state is anchored with the rest of the primary's
815    /// state.
816    fn compare_and_swap(
817        &self,
818        ctx: &V2Context,
819        expected: &SecurityJournalHeadV2,
820        next: &SecurityJournalV2,
821    ) -> Result<(), SecurityJournalStoreErrorV2> {
822        let journal = &self.shared.journal;
823        let (head, snapshot) = journal.anchored();
824        self.shared.change_other(
825            || journal.compare_and_swap(ctx, expected, next),
826            || journal.restore_anchored(head, snapshot),
827            SecurityJournalStoreErrorV2::Failed,
828        )
829    }
830}
831
832/// The primary's challenge issuance store (Go `DeviceIssuanceTestOnly`).
833pub struct DeviceIssuanceTestOnly {
834    shared: Arc<PrimaryShared>,
835}
836
837impl std::fmt::Debug for DeviceIssuanceTestOnly {
838    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
839        f.debug_struct("DeviceIssuanceTestOnly").finish_non_exhaustive()
840    }
841}
842
843impl V2ChallengeIssuanceStore for DeviceIssuanceTestOnly {
844    /// The new record is anchored with the rest of the primary's state.
845    fn persist_v2_challenge(&self, ctx: &V2Context, record: ExpectedChallengeV2) -> Result<(), V2StoreError> {
846        let issuance = &self.shared.issuance;
847        let saved = issuance.records();
848        self.shared.change_other(
849            || issuance.persist_v2_challenge(ctx, record),
850            || issuance.set_records(saved),
851            V2StoreError::Classified,
852        )
853    }
854
855    fn load_v2_challenge(
856        &self,
857        ctx: &V2Context,
858        namespace: &str,
859        replay_epoch: i64,
860        claim_digest: &[u8],
861    ) -> Result<ExpectedChallengeV2, V2StoreError> {
862        self.shared.issuance.load_v2_challenge(ctx, namespace, replay_epoch, claim_digest)
863    }
864}
865
866#[cfg(test)]
867mod tests {
868    use super::super::offline_device::{DeviceCheckpointTestOnly, DeviceErrorTestOnly, DeviceStartupStatus};
869    use super::super::store::OutboxEntry;
870    use super::*;
871    use crate::crypto::generate_hybrid_keypair;
872    use crate::v2::claim_store::{ClaimStoreV2, V2ChallengeClaim};
873    use crate::v2::journal::record_security_key_role_v2;
874    use crate::v2::release::{V2ReleaseRecord, V2ReleaseStatus};
875
876    const LOG_ID: &str = "dddddddddddddddddddddddddddddd01";
877
878    type TestDevice = (DevicePrimaryTestOnly, Arc<DeviceComponentTestOnly>, DeviceCheckpointTestOnly);
879
880    fn new_test_device(capacity: usize) -> TestDevice {
881        let (_, private) = generate_hybrid_keypair();
882        let store = Arc::new(Store::new(1_000, 30, LOG_ID, &private).unwrap());
883        store.set_acknowledgement_withheld(true);
884        let primary = DevicePrimaryTestOnly::new(store.clone(), 3).unwrap();
885        let component = Arc::new(DeviceComponentTestOnly::new(&[7; 32], capacity, store).unwrap());
886        let device = DeviceCheckpointTestOnly::new(&primary, component.clone(), &component.public_key()).unwrap();
887        device.provision().unwrap();
888        (primary, component, device)
889    }
890
891    fn test_challenge_record(b: u8) -> ExpectedChallengeV2 {
892        ExpectedChallengeV2 {
893            value: vec![b; 32],
894            issued_at: 990,
895            expires_at: 1_290,
896            verifier_namespace: "device-ns".into(),
897            replay_epoch: 3,
898            ..Default::default()
899        }
900    }
901
902    /// A test claim with the challenge digest of `label` and the claim ID
903    /// derived from its replay key, as the store requires (SPEC-v2 §7.3).
904    fn test_claim(label: &str) -> V2ChallengeClaim {
905        let digest = sha2::Sha384::digest(label.as_bytes());
906        V2ChallengeClaim {
907            claim_id: crate::v2::operation_context::protocol_claim_id_from_digest_v2("device-ns", 3, &digest).unwrap(),
908            challenge_digest: format!("sha384:{}", hex::encode(digest)),
909            namespace: "device-ns".into(),
910            replay_epoch: 3,
911            issued_at: 990,
912            expires_at: 1_290,
913            max_age_seconds: 300,
914            ..Default::default()
915        }
916    }
917
918    fn claim_1_id() -> String {
919        test_claim("claim-1").claim_id
920    }
921
922    fn release_record(entry: u8, at: i64) -> V2ReleaseRecord {
923        V2ReleaseRecord {
924            claim_id: claim_1_id(),
925            entry_hash: vec![entry; 48],
926            ack_timestamp: at,
927            outcome: V2ReleaseStatus::Released,
928            reason: String::new(),
929        }
930    }
931
932    /// A copy of `p` whose store state was changed by `mutate`.
933    fn with_store(p: &DevicePrimaryTestOnly, mutate: impl FnOnce(&mut StoreState)) -> DevicePrimaryTestOnly {
934        let copy = p.clone_primary();
935        mutate(&mut copy.store.lock());
936        copy
937    }
938
939    fn claim_1(s: &mut StoreState) -> &mut super::super::store::ClaimRecord {
940        s.claims.get_mut(&claim_1_id()).unwrap()
941    }
942
943    // Every member of the complete-state projection changes the digest on its
944    // own, so a rollback of any one durable record is detectable even when
945    // the receipt log and every other record are unchanged (SPEC-v2 §7.13).
946    #[test]
947    fn state_digest_covers_every_member() {
948        let ctx = V2Context::background();
949        let (primary, _, _) = new_test_device(4);
950        primary.store.claim_v2(&ctx, test_claim("claim-1")).unwrap();
951        let base = primary.complete_state_digest_test_only().unwrap();
952        let mut mutated: Vec<(&str, DevicePrimaryTestOnly)> = vec![
953            ("claim state", with_store(&primary, |s| claim_1(s).state = ClaimState::Terminal)),
954            ("claim lease", with_store(&primary, |s| claim_1(s).lease_expires_at += 1)),
955            ("claim progress", with_store(&primary, |s| claim_1(s).progress.trust_assessment = "trusted".into())),
956            ("claim abandoned", with_store(&primary, |s| claim_1(s).abandoned = true)),
957            ("claim removed", with_store(&primary, |s| drop(s.claims.remove(&claim_1_id())))),
958            ("release record", with_store(&primary, |s| claim_1(s).release = Some(release_record(1, 1_000)))),
959            ("stream sequence", with_store(&primary, |s| {
960                s.streams.insert(("ns".into(), "agent".into(), vec![7; 32]), 2);
961            })),
962            (
963                "rate counter",
964                with_store(&primary, |s| drop(s.rate_commits.insert(("issuer".into(), "cert".into(), 60), vec![1_000]))),
965            ),
966            (
967                "outbox entry",
968                with_store(&primary, |s| {
969                    s.outbox.push(OutboxEntry {
970                        claim_id: claim_1_id(),
971                        body: b"{}".to_vec(),
972                        wire: None,
973                        digest: Vec::new(),
974                        ack: None,
975                    })
976                }),
977            ),
978            ("log frozen", with_store(&primary, |s| s.log_frozen = true)),
979        ];
980        let copy = primary.clone_primary();
981        let (head, snapshot) = copy.shared.journal.anchored();
982        let issuance = TestOnlyChallengeIssuanceStore::new();
983        issuance.set_records(copy.shared.issuance.records());
984        mutated.push((
985            "replay epoch",
986            DevicePrimaryTestOnly::assemble(
987                copy.store.clone(),
988                copy.shared.replay_epoch + 1,
989                copy.shared.log_id.clone(),
990                JournalStore::from_anchored(head, snapshot),
991                issuance,
992            ),
993        ));
994        let issued = primary.clone_primary();
995        issued.shared.issuance.persist_v2_challenge(&ctx, test_challenge_record(9)).unwrap();
996        mutated.push(("issuance record", issued));
997        let journaled = primary.clone_primary();
998        let (public, _) = generate_hybrid_keypair();
999        record_security_key_role_v2(&ctx, &journaled.shared.journal, "verifier", &public).unwrap();
1000        mutated.push(("security journal", journaled));
1001        for (name, p) in mutated {
1002            assert_ne!(p.complete_state_digest_test_only().unwrap(), base, "changing the {name} does not change the digest");
1003        }
1004        // Every field of a release record is covered, not only its presence.
1005        let released = with_store(&primary, |s| claim_1(s).release = Some(release_record(1, 1_000)));
1006        let with_release = released.complete_state_digest_test_only().unwrap();
1007        let withheld = V2ReleaseRecord {
1008            outcome: V2ReleaseStatus::Withheld,
1009            reason: "challenge_expired".into(),
1010            ..release_record(1, 1_000)
1011        };
1012        for (name, record) in [
1013            ("release entry hash", release_record(2, 1_000)),
1014            ("release ack timestamp", release_record(1, 999)),
1015            ("release outcome", withheld),
1016        ] {
1017            let p = with_store(&released, |s| claim_1(s).release = Some(record));
1018            assert_ne!(p.complete_state_digest_test_only().unwrap(), with_release, "changing the {name} does not change the digest");
1019        }
1020        // Excluded by design: clock readings and checkpoint acknowledgements.
1021        let clock = with_store(&primary, |s| s.high_water += 100);
1022        assert_eq!(clock.complete_state_digest_test_only().unwrap(), base, "a clock reading changed the digest");
1023    }
1024
1025    // Journal and issuance changes are anchored like claim-store changes: a
1026    // restore that loses either is detected at startup, and a restored
1027    // primary cannot make a new change.
1028    #[test]
1029    fn journal_and_issuance_rollback_detected() {
1030        let ctx = V2Context::background();
1031        type Change = fn(&V2Context, &DevicePrimaryTestOnly) -> Option<V2ErrorClass>;
1032        let changes: [(&str, Change); 2] = [
1033            ("journal", |ctx, p| {
1034                let (public, _) = generate_hybrid_keypair();
1035                record_security_key_role_v2(ctx, &p.journal, "verifier", &public).err().map(|e| e.class)
1036            }),
1037            ("issuance", |ctx, p| {
1038                p.issuance
1039                    .persist_v2_challenge(ctx, test_challenge_record(1))
1040                    .err()
1041                    .map(|e| e.class().unwrap_or(V2ErrorClass::Malformed))
1042            }),
1043        ];
1044        for (name, change) in changes {
1045            let (primary, component, device) = new_test_device(4);
1046            let snapshot = primary.clone_primary();
1047            assert_eq!(change(&ctx, &primary), None, "{name}: anchored change");
1048            assert_eq!(device.startup(), DeviceStartupStatus::Ready, "{name}: after an anchored change");
1049            let restored = snapshot.clone_primary();
1050            let restored_device = DeviceCheckpointTestOnly::new(&restored, component.clone(), &component.public_key()).unwrap();
1051            assert_eq!(restored_device.startup(), DeviceStartupStatus::StateDigestMismatch, "{name}: after a rollback");
1052            let before = restored.complete_state_digest_test_only().unwrap();
1053            assert_eq!(
1054                change(&ctx, &restored),
1055                Some(V2ErrorClass::ClaimStoreUnavailable),
1056                "{name}: a rolled-back primary made a change"
1057            );
1058            assert_eq!(restored.complete_state_digest_test_only().unwrap(), before, "{name}: a refused change was not undone");
1059        }
1060    }
1061
1062    // A different entry at an acknowledged sequence freezes the component; a
1063    // frozen component anchors nothing more.
1064    #[test]
1065    fn component_freezes_on_fork() {
1066        let ctx = V2Context::background();
1067        let (primary, component, device) = new_test_device(4);
1068        let state = {
1069            let anchor = primary.shared.lock_anchor();
1070            primary.shared.compose(&anchor.last_store).unwrap()
1071        };
1072        let (zero, entry, other) = (vec![0u8; 48], vec![1u8; 48], vec![2u8; 48]);
1073        component.commit(&ctx, LOG_ID, 1, &zero, &entry, &state).unwrap();
1074        let ack = component.commit(&ctx, LOG_ID, 1, &zero, &entry, &state).unwrap();
1075        assert_eq!(ack.sequence, 1, "identical retry");
1076        assert_eq!(component.commit(&ctx, LOG_ID, 1, &zero, &other, &state), Err(DeviceErrorTestOnly::Frozen));
1077        assert_eq!(component.anchor_state(&state, &state), Err(DeviceErrorTestOnly::Frozen));
1078        assert_eq!(device.startup(), DeviceStartupStatus::CheckpointFrozen);
1079        assert!(component.provision_state(&state).is_err(), "a provisioned component was provisioned again");
1080    }
1081
1082    // An acknowledgement racing anchored state changes never sees a stale
1083    // anchored digest: the primary holds its anchor lock from composing the
1084    // digest through the component commit, so a concurrent claim anchors
1085    // either before or after it, never between (SPEC-v2 §7.13).
1086    #[test]
1087    fn acknowledgement_racing_claims_never_mismatches() {
1088        const ENTRIES: i64 = 16;
1089        const WORKERS: usize = 4;
1090        const CLAIMS_PER_ROUND: usize = 2;
1091        let ctx = V2Context::background();
1092        let (primary, _, device) = new_test_device(ENTRIES as usize);
1093        let store = &primary.store;
1094        for sequence in 1..=ENTRIES {
1095            // Append an entry through the anchored change path, then
1096            // acknowledge it while claim workers anchor new state concurrently.
1097            store
1098                .lock()
1099                .change_locked(|s| {
1100                    s.outbox.push(OutboxEntry {
1101                        claim_id: format!("entry-{sequence}"),
1102                        body: b"{}".to_vec(),
1103                        wire: Some(vec![1]),
1104                        digest: vec![sequence as u8; 48],
1105                        ack: None,
1106                    })
1107                })
1108                .unwrap_or_else(|e| panic!("append {sequence}: {e:?}"));
1109            let ack = std::thread::scope(|scope| {
1110                for worker in 0..WORKERS {
1111                    let ctx = &ctx;
1112                    scope.spawn(move || {
1113                        for n in 0..CLAIMS_PER_ROUND {
1114                            let id = format!("claim-{sequence}-{worker}-{n}");
1115                            store.claim_v2(ctx, test_claim(&id)).unwrap_or_else(|e| panic!("claim {id}: {e:?}"));
1116                        }
1117                    });
1118                }
1119                device.resubmit(&ctx, sequence)
1120            });
1121            ack.unwrap_or_else(|e| panic!("acknowledging sequence {sequence} while claims race: {e}"));
1122        }
1123        assert_eq!(device.startup(), DeviceStartupStatus::Ready, "startup after the race");
1124    }
1125}