Skip to main content

qualia_core_db/q42/app_manifest/
codec.rs

1//! Deterministic binary codec for [`PortableAppManifest`].
2
3use super::error::AppManifestError;
4use super::manifest::{
5    AppAuthor, AppIdentity, Compatibility, EntryProjection, Integrity, PortableAppManifest,
6    ProjectionKind, RequiredAsset, RequiredCapability, StateSchema, UpdateChannel,
7    APP_MANIFEST_VERSION, MAX_MANIFEST_BYTES,
8};
9use super::permissions::{PermissionIntent, PermissionKind, PresentationHint};
10
11/// Wire magic: `Q42APP\0\0`.
12pub const APP_MANIFEST_MAGIC: [u8; 8] = *b"Q42APP\0\0";
13
14fn write_u16(buf: &mut Vec<u8>, value: u16) {
15    buf.extend_from_slice(&value.to_le_bytes());
16}
17
18fn write_str(buf: &mut Vec<u8>, value: &str) -> Result<(), AppManifestError> {
19    let bytes = value.as_bytes();
20    let len = u16::try_from(bytes.len()).map_err(|_| AppManifestError::Oversize)?;
21    write_u16(buf, len);
22    buf.extend_from_slice(bytes);
23    Ok(())
24}
25
26fn write_str_list(buf: &mut Vec<u8>, values: &[String]) -> Result<(), AppManifestError> {
27    let len = u16::try_from(values.len()).map_err(|_| AppManifestError::Oversize)?;
28    write_u16(buf, len);
29    for value in values {
30        write_str(buf, value)?;
31    }
32    Ok(())
33}
34
35fn read_u16(bytes: &[u8], cursor: &mut usize) -> Result<u16, AppManifestError> {
36    if *cursor + 2 > bytes.len() {
37        return Err(AppManifestError::Truncated);
38    }
39    let value = u16::from_le_bytes(bytes[*cursor..*cursor + 2].try_into().unwrap());
40    *cursor += 2;
41    Ok(value)
42}
43
44fn read_bytes32(bytes: &[u8], cursor: &mut usize) -> Result<[u8; 32], AppManifestError> {
45    if *cursor + 32 > bytes.len() {
46        return Err(AppManifestError::Truncated);
47    }
48    let mut out = [0u8; 32];
49    out.copy_from_slice(&bytes[*cursor..*cursor + 32]);
50    *cursor += 32;
51    Ok(out)
52}
53
54fn read_str(bytes: &[u8], cursor: &mut usize) -> Result<String, AppManifestError> {
55    let len = read_u16(bytes, cursor)? as usize;
56    if *cursor + len > bytes.len() {
57        return Err(AppManifestError::Truncated);
58    }
59    let slice = &bytes[*cursor..*cursor + len];
60    *cursor += len;
61    std::str::from_utf8(slice)
62        .map(|s| s.to_string())
63        .map_err(|_| AppManifestError::InvalidUtf8)
64}
65
66fn read_str_list(bytes: &[u8], cursor: &mut usize) -> Result<Vec<String>, AppManifestError> {
67    let count = read_u16(bytes, cursor)? as usize;
68    let mut out = Vec::with_capacity(count);
69    for _ in 0..count {
70        out.push(read_str(bytes, cursor)?);
71    }
72    Ok(out)
73}
74
75impl PortableAppManifest {
76    /// Deterministic little-endian encode. Fails if validation or size budget fails.
77    pub fn encode(&self) -> Result<Vec<u8>, AppManifestError> {
78        self.validate()?;
79        let mut buf = Vec::with_capacity(512);
80        buf.extend_from_slice(&APP_MANIFEST_MAGIC);
81        write_u16(&mut buf, APP_MANIFEST_VERSION);
82        write_u16(&mut buf, 0); // reserved
83        write_str(&mut buf, &self.identity.app_id)?;
84        write_str(&mut buf, &self.identity.version)?;
85        write_str(&mut buf, &self.identity.author.name)?;
86        write_str(&mut buf, &self.identity.author.did)?;
87
88        let entry_len =
89            u16::try_from(self.entries.len()).map_err(|_| AppManifestError::Oversize)?;
90        write_u16(&mut buf, entry_len);
91        for entry in &self.entries {
92            buf.push(entry.projection as u8);
93            buf.push(0); // pad
94            write_u16(&mut buf, 0); // reserved
95            write_str(&mut buf, &entry.entry_id)?;
96            write_str(&mut buf, &entry.relative_path)?;
97        }
98
99        let cap_len = u16::try_from(self.required_capabilities.len())
100            .map_err(|_| AppManifestError::Oversize)?;
101        write_u16(&mut buf, cap_len);
102        for cap in &self.required_capabilities {
103            write_str(&mut buf, &cap.id)?;
104            write_str(&mut buf, &cap.min_version)?;
105        }
106
107        let asset_len =
108            u16::try_from(self.required_assets.len()).map_err(|_| AppManifestError::Oversize)?;
109        write_u16(&mut buf, asset_len);
110        for asset in &self.required_assets {
111            write_str(&mut buf, &asset.asset_id)?;
112            buf.extend_from_slice(&asset.expected_sha256);
113        }
114
115        write_str(&mut buf, &self.state_schema.schema_id)?;
116        write_str(&mut buf, &self.state_schema.schema_version)?;
117
118        let perm_len =
119            u16::try_from(self.permission_intents.len()).map_err(|_| AppManifestError::Oversize)?;
120        write_u16(&mut buf, perm_len);
121        for intent in &self.permission_intents {
122            buf.push(intent.kind as u8);
123            buf.push(u8::from(intent.optional));
124            write_u16(&mut buf, 0); // reserved
125            write_str(&mut buf, &intent.scope)?;
126        }
127
128        let hint_len =
129            u16::try_from(self.presentation_hints.len()).map_err(|_| AppManifestError::Oversize)?;
130        write_u16(&mut buf, hint_len);
131        for hint in &self.presentation_hints {
132            write_str(&mut buf, &hint.key)?;
133            write_str(&mut buf, &hint.value)?;
134        }
135
136        write_str(&mut buf, &self.compatibility.min_engine_version)?;
137        write_str(&mut buf, &self.compatibility.max_engine_version)?;
138        write_str_list(&mut buf, &self.compatibility.required_features)?;
139
140        buf.extend_from_slice(&self.integrity.package_sha256);
141
142        write_str(&mut buf, &self.update_channel.channel_id)?;
143        write_str(&mut buf, &self.update_channel.relative_feed)?;
144
145        if buf.len() > MAX_MANIFEST_BYTES {
146            return Err(AppManifestError::Oversize);
147        }
148        Ok(buf)
149    }
150
151    /// Decode and re-validate. Unknown versions and permissions fail closed.
152    pub fn decode(bytes: &[u8]) -> Result<Self, AppManifestError> {
153        if bytes.len() < 12 {
154            return Err(AppManifestError::Truncated);
155        }
156        if bytes.len() > MAX_MANIFEST_BYTES {
157            return Err(AppManifestError::Oversize);
158        }
159        if bytes[0..8] != APP_MANIFEST_MAGIC {
160            return Err(AppManifestError::InvalidMagic);
161        }
162        let mut cursor = 8;
163        let version = read_u16(bytes, &mut cursor)?;
164        if version != APP_MANIFEST_VERSION {
165            return Err(AppManifestError::UnsupportedVersion);
166        }
167        let _reserved = read_u16(bytes, &mut cursor)?;
168
169        let identity = AppIdentity {
170            app_id: read_str(bytes, &mut cursor)?,
171            version: read_str(bytes, &mut cursor)?,
172            author: AppAuthor {
173                name: read_str(bytes, &mut cursor)?,
174                did: read_str(bytes, &mut cursor)?,
175            },
176        };
177
178        let entry_count = read_u16(bytes, &mut cursor)? as usize;
179        let mut entries = Vec::with_capacity(entry_count);
180        for _ in 0..entry_count {
181            if cursor + 4 > bytes.len() {
182                return Err(AppManifestError::Truncated);
183            }
184            let projection = ProjectionKind::from_u8(bytes[cursor])?;
185            cursor += 1;
186            let _pad = bytes[cursor];
187            cursor += 1;
188            let _entry_reserved = read_u16(bytes, &mut cursor)?;
189            entries.push(EntryProjection {
190                projection,
191                entry_id: read_str(bytes, &mut cursor)?,
192                relative_path: read_str(bytes, &mut cursor)?,
193            });
194        }
195
196        let cap_count = read_u16(bytes, &mut cursor)? as usize;
197        let mut required_capabilities = Vec::with_capacity(cap_count);
198        for _ in 0..cap_count {
199            required_capabilities.push(RequiredCapability {
200                id: read_str(bytes, &mut cursor)?,
201                min_version: read_str(bytes, &mut cursor)?,
202            });
203        }
204
205        let asset_count = read_u16(bytes, &mut cursor)? as usize;
206        let mut required_assets = Vec::with_capacity(asset_count);
207        for _ in 0..asset_count {
208            required_assets.push(RequiredAsset {
209                asset_id: read_str(bytes, &mut cursor)?,
210                expected_sha256: read_bytes32(bytes, &mut cursor)?,
211            });
212        }
213
214        let state_schema = StateSchema {
215            schema_id: read_str(bytes, &mut cursor)?,
216            schema_version: read_str(bytes, &mut cursor)?,
217        };
218
219        let perm_count = read_u16(bytes, &mut cursor)? as usize;
220        let mut permission_intents = Vec::with_capacity(perm_count);
221        for _ in 0..perm_count {
222            if cursor + 4 > bytes.len() {
223                return Err(AppManifestError::Truncated);
224            }
225            let kind = PermissionKind::from_u8(bytes[cursor])?;
226            let optional = bytes[cursor + 1] != 0;
227            cursor += 2;
228            let _perm_reserved = read_u16(bytes, &mut cursor)?;
229            permission_intents.push(PermissionIntent {
230                kind,
231                optional,
232                scope: read_str(bytes, &mut cursor)?,
233            });
234        }
235
236        let hint_count = read_u16(bytes, &mut cursor)? as usize;
237        let mut presentation_hints = Vec::with_capacity(hint_count);
238        for _ in 0..hint_count {
239            presentation_hints.push(PresentationHint {
240                key: read_str(bytes, &mut cursor)?,
241                value: read_str(bytes, &mut cursor)?,
242            });
243        }
244
245        let compatibility = Compatibility {
246            min_engine_version: read_str(bytes, &mut cursor)?,
247            max_engine_version: read_str(bytes, &mut cursor)?,
248            required_features: read_str_list(bytes, &mut cursor)?,
249        };
250
251        let integrity = Integrity {
252            package_sha256: read_bytes32(bytes, &mut cursor)?,
253        };
254
255        let update_channel = UpdateChannel {
256            channel_id: read_str(bytes, &mut cursor)?,
257            relative_feed: read_str(bytes, &mut cursor)?,
258        };
259
260        if cursor != bytes.len() {
261            return Err(AppManifestError::Truncated);
262        }
263
264        let manifest = Self {
265            identity,
266            entries,
267            required_capabilities,
268            required_assets,
269            state_schema,
270            permission_intents,
271            presentation_hints,
272            compatibility,
273            integrity,
274            update_channel,
275        };
276        manifest.validate()?;
277        Ok(manifest)
278    }
279
280    /// Deterministic SHA-256 of the encoded canonical bytes.
281    pub fn manifest_digest(&self) -> Result<[u8; 32], AppManifestError> {
282        let encoded = self.encode()?;
283        Ok(super::manifest::sha256_of(&encoded))
284    }
285}