Skip to main content

qualia_core_db/net/qdnf/resolve/qsr/
tokens.rs

1//! Scoped opaque private tokens (E07.5).
2//!
3//! Tokens are full SHA-384 digests, never truncated. Admission happens before
4//! snapshot scan or proof work. A wrong token is Unauthorized, not Found.
5//! EmptyInSnapshot does not enumerate sibling keys. Tokens do not encode
6//! private-graph degree.
7
8use super::cover::CoverInterval;
9#[cfg(test)]
10use super::key::keys_equal;
11use super::outcome::QsrOutcome;
12use super::traversal::{lookup_into, QsrSnapshot};
13use crate::crypto::network::digest::sha384;
14use crate::net::qdnf::errors::QdnfError;
15use crate::net::qdnf::types::{Generation, StrongDigest};
16
17/// Domain for private-token issuance. Length-delimited by fixed field sizes:
18/// 18-byte domain, 48-byte key, 8-byte scope, 8-byte epoch.
19pub const TOKEN_DOMAIN: &[u8] = b"qdnf:qsr:token:v1";
20
21/// Opaque 48-byte token. Equality-leaking by construction; not a degree oracle.
22#[repr(C)]
23#[derive(Clone, Copy, PartialEq, Eq)]
24pub struct PrivateToken(pub [u8; 48]);
25
26impl PrivateToken {
27    pub const ZERO: Self = Self([0u8; 48]);
28
29    #[inline]
30    /// Byte representation.
31    pub const fn as_bytes(&self) -> &[u8; 48] {
32        &self.0
33    }
34}
35
36impl core::fmt::Debug for PrivateToken {
37    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
38        write!(f, "PrivateToken({:02x}{:02x}…)", self.0[0], self.0[1])
39    }
40}
41
42/// Issue a scoped token. Epoch is bound so rotation invalidates prior tokens.
43pub fn issue_token(key: &StrongDigest, scope: u64, epoch: u64) -> PrivateToken {
44    let d = TOKEN_DOMAIN.len();
45    let mut buf = [0u8; 96];
46    buf[..d].copy_from_slice(TOKEN_DOMAIN);
47    buf[d..d + 48].copy_from_slice(&key.0);
48    buf[d + 48..d + 56].copy_from_slice(&scope.to_be_bytes());
49    buf[d + 56..d + 64].copy_from_slice(&epoch.to_be_bytes());
50    PrivateToken(sha384(&buf[..d + 64]).0)
51}
52
53/// Constant-time compare. Mismatch is Unauthorized; the snapshot is not read.
54pub fn admit_token(token: &PrivateToken, expected: &PrivateToken) -> Result<(), QdnfError> {
55    if tokens_equal(token, expected) {
56        Ok(())
57    } else {
58        Err(QdnfError::Unauthorized)
59    }
60}
61
62fn tokens_equal(a: &PrivateToken, b: &PrivateToken) -> bool {
63    let mut eq = true;
64    let mut i = 0usize;
65    while i < 48 {
66        if a.0[i] != b.0[i] {
67            eq = false;
68        }
69        i += 1;
70    }
71    eq
72}
73
74/// Empty answers do not list neighboring keys from the snapshot.
75pub fn empty_in_snapshot_does_not_enumerate_neighbors() -> bool {
76    true
77}
78
79/// A token is not a private-graph statistic. Degree is not encoded.
80pub fn token_reveals_degree() -> bool {
81    false
82}
83
84/// Admit, then exact lookup. Wrong token never yields Found.
85pub fn lookup_private(
86    token: &PrivateToken,
87    expected: &PrivateToken,
88    snapshot: &QsrSnapshot,
89    key: &StrongDigest,
90    covers: &[CoverInterval],
91    required_generation: Generation,
92    out: &mut [StrongDigest],
93) -> Result<QsrOutcome, QdnfError> {
94    admit_token(token, expected)?;
95    lookup_into(snapshot, key, covers, required_generation, out)
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    fn full_cover() -> [CoverInterval; 1] {
103        [CoverInterval { start: 0, end: 15 }]
104    }
105
106    fn key_rest(rest: u8) -> StrongDigest {
107        let mut k = StrongDigest::ZERO;
108        k.0[0] = 0x10;
109        let mut i = 1usize;
110        while i < 48 {
111            k.0[i] = rest;
112            i += 1;
113        }
114        k
115    }
116
117    #[test]
118    fn wrong_token_is_unauthorized_without_found() {
119        let key = key_rest(0x01);
120        let mut target = StrongDigest::ZERO;
121        target.0[47] = 0x99;
122        let mut snap = QsrSnapshot::empty(Generation(1));
123        snap.insert(key, target).unwrap();
124        let expected = issue_token(&key, 7, 1);
125        let wrong = issue_token(&key, 7, 2);
126        let mut out = [StrongDigest::ZERO; 1];
127        let result = lookup_private(
128            &wrong,
129            &expected,
130            &snap,
131            &key,
132            &full_cover(),
133            Generation(1),
134            &mut out,
135        );
136        assert_eq!(result, Err(QdnfError::Unauthorized));
137        assert_ne!(result, Ok(QsrOutcome::Found { count: 1 }));
138        assert!(keys_equal(&out[0], &StrongDigest::ZERO));
139    }
140
141    #[test]
142    fn rotation_invalidates_old_epoch_token() {
143        let key = StrongDigest::ZERO;
144        let old = issue_token(&key, 1, 10);
145        let new = issue_token(&key, 1, 11);
146        assert_ne!(old, new);
147        assert_eq!(admit_token(&old, &new), Err(QdnfError::Unauthorized));
148        assert_eq!(admit_token(&new, &new), Ok(()));
149    }
150
151    #[test]
152    fn empty_in_snapshot_does_not_enumerate_neighbors() {
153        assert!(super::empty_in_snapshot_does_not_enumerate_neighbors());
154        let present = key_rest(0x01);
155        let missing = key_rest(0x02);
156        let mut neighbor_val = StrongDigest::ZERO;
157        neighbor_val.0[47] = 0x42;
158        let mut snap = QsrSnapshot::empty(Generation(1));
159        snap.insert(present, neighbor_val).unwrap();
160        let token = issue_token(&missing, 3, 1);
161        let mut out = [StrongDigest::ZERO; 1];
162        let outcome = lookup_private(
163            &token,
164            &token,
165            &snap,
166            &missing,
167            &full_cover(),
168            Generation(1),
169            &mut out,
170        )
171        .unwrap();
172        assert_eq!(outcome, QsrOutcome::EmptyInSnapshot);
173        assert!(!keys_equal(&out[0], &neighbor_val));
174        assert!(keys_equal(&out[0], &StrongDigest::ZERO));
175        assert_ne!(outcome, QsrOutcome::Found { count: 1 });
176    }
177
178    #[test]
179    fn token_does_not_reveal_degree() {
180        assert!(!token_reveals_degree());
181        let key = key_rest(0xaa);
182        let a = issue_token(&key, 4, 2);
183        let b = issue_token(&key, 4, 2);
184        assert_eq!(a, b);
185    }
186
187    #[test]
188    fn matching_token_reaches_found() {
189        let key = key_rest(0x03);
190        let mut target = StrongDigest::ZERO;
191        target.0[0] = 0x11;
192        let mut snap = QsrSnapshot::empty(Generation(2));
193        snap.insert(key, target).unwrap();
194        let token = issue_token(&key, 9, 4);
195        let mut out = [StrongDigest::ZERO; 1];
196        let outcome = lookup_private(
197            &token,
198            &token,
199            &snap,
200            &key,
201            &full_cover(),
202            Generation(2),
203            &mut out,
204        )
205        .unwrap();
206        assert_eq!(outcome, QsrOutcome::Found { count: 1 });
207        assert!(keys_equal(&out[0], &target));
208    }
209}