Skip to main content

qualia_core_db/did_qi/
method.rs

1//! Create / read / update / deactivate for `did:qi` (spec §11–§14).
2//!
3//! Controller signatures are Ed25519 over `did:qi:document:v1` || 0x00 ||
4//! unsignedDigest. The DID is SHA-256 of the QCDE-1 genesis payload.
5//! Generation 0 is Create. Further updates after deactivate fail closed.
6
7use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
8
9use super::document::{
10    encode_signed, encode_unsigned, genesis_digest, proof_message, sha256_32, QiDocument,
11    MAX_CANONICAL, MAX_SIGNED,
12};
13use super::document_decode::{decode_canonical, extract_proof_sig};
14use super::git_object::MAX_RECORD;
15use super::id::DidQi;
16use super::service::check_relay_only;
17use super::{QiError, QiStore};
18
19const SIG_LEN: usize = 64;
20
21fn public_from_secret(sk: &[u8; 32]) -> [u8; 32] {
22    SigningKey::from_bytes(sk).verifying_key().to_bytes()
23}
24
25fn bind_controller(doc: &QiDocument, sk: &[u8; 32]) -> Result<QiDocument, QiError> {
26    let pk = public_from_secret(sk);
27    let mut out = *doc;
28    if out.controller_pk == [0u8; 32] {
29        out.controller_pk = pk;
30    } else if out.controller_pk != pk {
31        return Err(QiError::ControllerMismatch);
32    }
33    Ok(out)
34}
35
36fn sign_unsigned(sk: &[u8; 32], unsigned: &[u8]) -> Result<[u8; SIG_LEN], QiError> {
37    let digest = sha256_32(unsigned);
38    let mut msg = [0u8; 64];
39    let n = proof_message(&digest, &mut msg)?;
40    Ok(SigningKey::from_bytes(sk).sign(&msg[..n]).to_bytes())
41}
42
43fn verify_unsigned(
44    pk: &[u8; 32],
45    unsigned: &[u8],
46    signature: &[u8; SIG_LEN],
47) -> Result<(), QiError> {
48    let digest = sha256_32(unsigned);
49    let mut msg = [0u8; 64];
50    let n = proof_message(&digest, &mut msg)?;
51    let vk = VerifyingKey::from_bytes(pk).map_err(|_| QiError::InvalidKey)?;
52    let sig = Signature::from_bytes(signature);
53    vk.verify(&msg[..n], &sig)
54        .map_err(|_| QiError::BadSignature)
55}
56
57fn write_signed<S: QiStore>(
58    store: &mut S,
59    id: &DidQi,
60    generation: u64,
61    doc: &QiDocument,
62    signature: &[u8; SIG_LEN],
63) -> Result<u64, QiError> {
64    let mut signed = [0u8; MAX_SIGNED];
65    let n = encode_signed(id, doc, signature, &mut signed)?;
66    store.put(id, generation, &signed[..n])?;
67    Ok(generation)
68}
69
70fn sync_service_generation(doc: &mut QiDocument) {
71    let mut i = 0;
72    while i < doc.service_count as usize {
73        doc.services[i].generation = doc.generation;
74        i += 1;
75    }
76}
77
78/// Creates a `did:qi` document in `store`; returns the new generation.
79pub fn create<S: QiStore>(
80    store: &mut S,
81    controller_sk: &[u8; 32],
82    doc: &QiDocument,
83) -> Result<DidQi, QiError> {
84    let mut doc = bind_controller(doc, controller_sk)?;
85    if doc.deactivated {
86        return Err(QiError::Deactivated);
87    }
88    doc.generation = 0;
89    doc.has_previous = false;
90    sync_service_generation(&mut doc);
91    check_relay_only(doc.services_slice())?;
92    let id = DidQi(genesis_digest(&doc)?);
93    let mut canonical = [0u8; MAX_CANONICAL];
94    let n = encode_unsigned(&id, &doc, &mut canonical)?;
95    let sig = sign_unsigned(controller_sk, &canonical[..n])?;
96    write_signed(store, &id, 0, &doc, &sig)?;
97    Ok(id)
98}
99
100/// Reads the document for `id` into `out`; returns its generation.
101pub fn read<S: QiStore>(store: &S, id: &DidQi, out: &mut QiDocument) -> Result<u64, QiError> {
102    let mut rec = [0u8; MAX_RECORD];
103    let (slot_gen, n) = store.get(id, &mut rec)?;
104    decode_canonical(&rec[..n], out)?;
105    let sig = extract_proof_sig(&rec[..n])?;
106    let mut unsigned = [0u8; MAX_CANONICAL];
107    let un = encode_unsigned(id, out, &mut unsigned)?;
108    verify_unsigned(&out.controller_pk, &unsigned[..un], &sig)?;
109    Ok(slot_gen)
110}
111
112/// Spec §12.7: an older signed generation presented as current is stale.
113pub fn read_generation<S: QiStore>(
114    store: &S,
115    id: &DidQi,
116    claimed: u64,
117    out: &mut QiDocument,
118) -> Result<u64, QiError> {
119    let gen = read(store, id, out)?;
120    if claimed != gen {
121        return Err(QiError::StaleGeneration);
122    }
123    Ok(gen)
124}
125
126/// Applies an update to `id`, bumping the generation.
127pub fn update<S: QiStore>(
128    store: &mut S,
129    controller_sk: &[u8; 32],
130    id: &DidQi,
131    doc: &QiDocument,
132) -> Result<u64, QiError> {
133    let mut current = QiDocument::empty();
134    let gen = read(store, id, &mut current)?;
135    if current.deactivated {
136        return Err(QiError::Deactivated);
137    }
138    let mut doc = bind_controller(doc, controller_sk)?;
139    if doc.deactivated {
140        return Err(QiError::Deactivated);
141    }
142    if public_from_secret(controller_sk) != current.controller_pk {
143        return Err(QiError::ControllerMismatch);
144    }
145    let (prev, _) = load_canonical_digest(store, id)?;
146    doc.generation = current.generation + 1;
147    doc.created_unix = current.created_unix;
148    doc.has_previous = true;
149    doc.previous_digest = prev;
150    sync_service_generation(&mut doc);
151    check_relay_only(doc.services_slice())?;
152    let mut canonical = [0u8; MAX_CANONICAL];
153    let n = encode_unsigned(id, &doc, &mut canonical)?;
154    let sig = sign_unsigned(controller_sk, &canonical[..n])?;
155    write_signed(store, id, gen + 1, &doc, &sig)
156}
157
158/// Tombstones `id`.
159pub fn deactivate<S: QiStore>(
160    store: &mut S,
161    controller_sk: &[u8; 32],
162    id: &DidQi,
163) -> Result<u64, QiError> {
164    let mut current = QiDocument::empty();
165    let gen = read(store, id, &mut current)?;
166    if current.deactivated {
167        return Err(QiError::Deactivated);
168    }
169    if public_from_secret(controller_sk) != current.controller_pk {
170        return Err(QiError::ControllerMismatch);
171    }
172    let (prev, _) = load_canonical_digest(store, id)?;
173    current.deactivated = true;
174    current.service_count = 0;
175    current.has_hostname_alias = false;
176    current.hostname_did_web = super::document::AkaEntry {
177        bytes: [0u8; super::document::MAX_AKA_LEN],
178        len: 0,
179    };
180    current.aka_count = 0;
181    current.generation += 1;
182    current.has_previous = true;
183    current.previous_digest = prev;
184    let mut canonical = [0u8; MAX_CANONICAL];
185    let n = encode_unsigned(id, &current, &mut canonical)?;
186    let sig = sign_unsigned(controller_sk, &canonical[..n])?;
187    write_signed(store, id, gen + 1, &current, &sig)
188}
189
190/// Loads the canonical digest for `id` from `store`.
191pub(crate) fn load_canonical_digest<S: QiStore>(
192    store: &S,
193    id: &DidQi,
194) -> Result<([u8; 32], u64), QiError> {
195    let mut rec = [0u8; MAX_RECORD];
196    let (generation, n) = store.get(id, &mut rec)?;
197    let mut doc = QiDocument::empty();
198    decode_canonical(&rec[..n], &mut doc)?;
199    let mut unsigned = [0u8; MAX_CANONICAL];
200    let un = encode_unsigned(id, &doc, &mut unsigned)?;
201    Ok((sha256_32(&unsigned[..un]), generation))
202}
203
204#[cfg(test)]
205mod tests {
206    use super::super::document::{genesis_digest, AkaEntry};
207    use super::super::git_object::GitObjectStore;
208    use super::super::service::{CscpMailbox, Disclosure};
209    use super::super::{format_did, parse_did};
210    use super::*;
211
212    fn sk() -> [u8; 32] {
213        [7u8; 32]
214    }
215
216    fn sample_doc() -> QiDocument {
217        let mut doc = QiDocument::empty();
218        doc.services[0] =
219            CscpMailbox::mailbox(public_from_secret(&sk()), Disclosure::ApprovedRelaysOnly);
220        doc.service_count = 1;
221        doc
222    }
223
224    #[test]
225    fn create_then_read_round_trip() {
226        let mut store = GitObjectStore::new();
227        let doc = sample_doc();
228        let id = create(&mut store, &sk(), &doc).unwrap();
229        let mut did = [0u8; 64];
230        let n = format_did(&id, &mut did).unwrap();
231        assert!(did[..n].starts_with(b"did:qi:z"));
232        assert_eq!(parse_did(&did[..n]).unwrap(), id);
233        let mut out = QiDocument::empty();
234        let gen = read(&store, &id, &mut out).unwrap();
235        assert_eq!(gen, 0);
236        assert_eq!(out.controller_pk, public_from_secret(&sk()));
237        assert!(!out.deactivated);
238        let mut bound = sample_doc();
239        bound.controller_pk = public_from_secret(&sk());
240        assert_eq!(genesis_digest(&bound).unwrap(), id.0);
241    }
242
243    #[test]
244    fn update_bumps_generation_old_is_stale() {
245        let mut store = GitObjectStore::new();
246        let mut doc = sample_doc();
247        let id = create(&mut store, &sk(), &doc).unwrap();
248        doc.aka[0] = AkaEntry::from_slice(b"did:web:example.invalid").unwrap();
249        doc.aka_count = 1;
250        let g1 = update(&mut store, &sk(), &id, &doc).unwrap();
251        assert_eq!(g1, 1);
252        let mut out = QiDocument::empty();
253        assert_eq!(read(&store, &id, &mut out).unwrap(), 1);
254        assert_eq!(out.generation, 1);
255        assert_eq!(out.aka_count, 1);
256        assert_eq!(
257            &out.aka[0].bytes[..out.aka[0].len as usize],
258            b"did:web:example.invalid"
259        );
260        assert!(out.has_previous);
261        assert_eq!(out.service_count, 1);
262        assert_eq!(out.services[0].contact_key, public_from_secret(&sk()));
263        assert!(store.is_stale(&id, 0).unwrap());
264        assert!(!store.is_stale(&id, 1).unwrap());
265        let mut stale = QiDocument::empty();
266        assert_eq!(
267            read_generation(&store, &id, 0, &mut stale),
268            Err(QiError::StaleGeneration)
269        );
270        assert_eq!(read_generation(&store, &id, 1, &mut stale).unwrap(), 1);
271    }
272
273    #[test]
274    fn deactivate_then_update_fails_closed() {
275        let mut store = GitObjectStore::new();
276        let doc = sample_doc();
277        let id = create(&mut store, &sk(), &doc).unwrap();
278        let g = deactivate(&mut store, &sk(), &id).unwrap();
279        assert_eq!(g, 1);
280        let mut out = QiDocument::empty();
281        read(&store, &id, &mut out).unwrap();
282        assert!(out.deactivated);
283        assert_eq!(out.service_count, 0);
284        assert_eq!(out.aka_count, 0);
285        assert!(!out.has_hostname_alias);
286        assert_eq!(
287            update(&mut store, &sk(), &id, &doc),
288            Err(QiError::Deactivated)
289        );
290        assert_eq!(
291            deactivate(&mut store, &sk(), &id),
292            Err(QiError::Deactivated)
293        );
294    }
295
296    #[test]
297    fn empty_store_read_fails_closed() {
298        let store = GitObjectStore::new();
299        let mut out = QiDocument::empty();
300        assert_eq!(
301            read(&store, &DidQi([4u8; 32]), &mut out),
302            Err(QiError::NotFound)
303        );
304    }
305
306    #[test]
307    fn create_relay_only_direct_locator_rejected() {
308        let mut store = GitObjectStore::new();
309        let mut doc = sample_doc();
310        doc.services[0] = CscpMailbox::direct([1u8; 32], Disclosure::ApprovedRelaysOnly);
311        assert_eq!(
312            create(&mut store, &sk(), &doc),
313            Err(QiError::DirectLocatorForbidden)
314        );
315    }
316
317    #[test]
318    fn wrong_controller_cannot_update() {
319        let mut store = GitObjectStore::new();
320        let doc = sample_doc();
321        let id = create(&mut store, &sk(), &doc).unwrap();
322        assert_eq!(
323            update(&mut store, &[9u8; 32], &id, &doc),
324            Err(QiError::ControllerMismatch)
325        );
326    }
327}