Skip to main content

oak_core/sqlite/
file_inspect.rs

1//! Bounded local object evidence. No checkout reads, hydration, or database writes.
2use super::SqliteRepository;
3use crate::{hash_bytes, Commit, FileMode, Hash, OakError, Result, Tree, TreeEntryKind};
4use rusqlite::{Connection, OptionalExtension, MAIN_DB};
5use serde::Serialize;
6use std::{
7    cell::Cell,
8    io::{BufReader, Read},
9    rc::Rc,
10};
11
12pub const MAX_FILE_INSPECTION_BYTES: u64 = 256 * 1024 * 1024;
13const TREE_BYTES: u64 = 16 * 1024 * 1024;
14const PATH_TREE_BYTES: u64 = 64 * 1024 * 1024;
15const HEADER_BYTES: i64 = 64 * 1024;
16const REFERENCE_BYTES: i64 = 64 * 1024;
17const HEAD_PARENT_HOPS: usize = 128;
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
20#[serde(rename_all = "snake_case")]
21pub enum InspectionStatus {
22    Verified,
23    PathMissing,
24    ObjectMissing,
25    Corrupt,
26    BudgetExceeded,
27    Unsupported,
28    Unavailable,
29}
30
31#[derive(Debug, Serialize)]
32pub struct FileInspection {
33    pub requested_revision: String,
34    pub commit: Option<String>,
35    pub commit_verification: &'static str,
36    pub root_tree: Option<String>,
37    pub path: String,
38    pub tree: Option<String>,
39    pub blob: Option<String>,
40    pub mode: Option<FileMode>,
41    pub declared_size: Option<u64>,
42    pub verified_size: Option<u64>,
43    pub verified_trees: usize,
44    pub proof_scope: FileInspectionProofScope,
45    pub status: InspectionStatus,
46    pub reason: Option<String>,
47    pub max_bytes: u64,
48    /// SHA-256 of the verified logical bytes (never codec bytes). Present
49    /// only when `status` is `verified`; the Oak identity remains `blob`.
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub content_sha256: Option<String>,
52    /// How the local store holds this blob — codec and stored byte length.
53    /// Separate from logical identity: `declared_size`/`verified_size` and
54    /// `blob` always describe decoded logical bytes.
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub storage: Option<StorageRepresentation>,
57}
58
59/// Local stored representation of one blob, as distinct from its logical
60/// content. `stored_bytes` is the on-disk (possibly compressed) length.
61#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
62pub struct StorageRepresentation {
63    /// `sqlite_blob_row`, or `implicit_empty` for the canonical empty blob
64    /// that has no stored row.
65    pub representation: &'static str,
66    /// `none` (raw), `zstd`, or `unknown`.
67    pub codec: &'static str,
68    #[serde(skip_serializing_if = "Option::is_none")]
69    pub codec_id: Option<i64>,
70    pub stored_bytes: u64,
71}
72
73/// Result of one streamed, hash-verified blob read.
74#[derive(Debug, Clone)]
75pub(super) struct VerifiedBlob {
76    pub logical_size: u64,
77    pub sha256: String,
78    pub storage: StorageRepresentation,
79}
80
81#[derive(Debug, Serialize)]
82pub struct FileInspectionProofScope {
83    pub source: &'static str,
84    pub exclusions: [&'static str; 3],
85}
86
87#[derive(Debug)]
88pub(super) struct Failure(pub InspectionStatus, pub String);
89pub(super) type Checked<T> = std::result::Result<T, Failure>;
90pub(super) fn failure(status: InspectionStatus, reason: impl Into<String>) -> Failure {
91    Failure(status, reason.into())
92}
93pub(super) fn database(error: rusqlite::Error) -> Failure {
94    use rusqlite::{ffi::ErrorCode, Error};
95
96    let malformed = matches!(
97        &error,
98        Error::FromSqlConversionFailure(..)
99            | Error::IntegralValueOutOfRange(..)
100            | Error::Utf8Error(..)
101            | Error::InvalidColumnType(..)
102            | Error::BlobSizeError
103    ) || matches!(
104        &error,
105        Error::SqliteFailure(code, _)
106            if matches!(
107                code.code,
108                ErrorCode::DatabaseCorrupt
109                    | ErrorCode::NotADatabase
110                    | ErrorCode::TypeMismatch
111            )
112    );
113    failure(
114        if malformed {
115            InspectionStatus::Corrupt
116        } else {
117            InspectionStatus::Unavailable
118        },
119        error.to_string(),
120    )
121}
122pub(super) fn corrupt(error: impl std::fmt::Display) -> Failure {
123    failure(InspectionStatus::Corrupt, error.to_string())
124}
125pub(super) fn budget(reason: &str) -> Failure {
126    failure(InspectionStatus::BudgetExceeded, reason)
127}
128
129impl SqliteRepository {
130    /// Verify one path under one pinned commit. Requires `open_read_only` so
131    /// HEAD, commit metadata and every object belong to the same read snapshot.
132    /// V1 header verification binds the root tree, not the unhashed change list
133    /// or ancestor closure. File content is hashed as logical bytes, not codec bytes.
134    pub fn inspect_pinned_file(
135        &self,
136        revision: &str,
137        path: &str,
138        max_bytes: u64,
139    ) -> Result<FileInspection> {
140        self.inspect_pinned_file_into(revision, path, max_bytes, &mut std::io::sink())
141    }
142
143    /// [`Self::inspect_pinned_file`], streaming the decoded logical bytes
144    /// into `sink` as they are hashed. The sink sees unverified bytes: a
145    /// caller must discard them unless the returned status is `verified`
146    /// (see `oak file inspect --output`, which stages into a temp file and
147    /// publishes only after verification).
148    pub fn inspect_pinned_file_into(
149        &self,
150        revision: &str,
151        path: &str,
152        max_bytes: u64,
153        sink: &mut dyn std::io::Write,
154    ) -> Result<FileInspection> {
155        if max_bytes == 0 || max_bytes > MAX_FILE_INSPECTION_BYTES {
156            return Err(OakError::InvalidArgument(
157                "--max-bytes must be between 1 and 268435456".into(),
158            ));
159        }
160        if path.len() > 4096
161            || path.is_empty()
162            || path.contains('\\')
163            || (path.as_bytes().get(1) == Some(&b':') && path.as_bytes()[0].is_ascii_alphabetic())
164            || path
165                .split('/')
166                .any(|p| p.is_empty() || p == "." || p == "..")
167            || path.chars().any(char::is_control)
168        {
169            return Err(OakError::InvalidPath("PATH must be a slash-separated repo-relative file path without empty, dot, parent or control components".into()));
170        }
171        if path.split('/').count() > 128 {
172            return Err(OakError::InvalidArgument(
173                "PATH exceeds the 128-component inspection budget".into(),
174            ));
175        }
176        validate_revision(revision)?;
177        let conn = self.conn.lock().unwrap();
178        require_read_only(&conn, "file inspection")?;
179        let mut evidence = FileInspection {
180            requested_revision: revision.into(),
181            commit: None,
182            commit_verification: "not_verified",
183            root_tree: None,
184            path: path.into(),
185            tree: None,
186            blob: None,
187            mode: None,
188            declared_size: None,
189            verified_size: None,
190            verified_trees: 0,
191            proof_scope: FileInspectionProofScope {
192                source: "local_sqlite_snapshot",
193                exclusions: ["commit_files", "ancestor_closure", "remote_durability"],
194            },
195            status: InspectionStatus::Verified,
196            reason: None,
197            max_bytes,
198            content_sha256: None,
199            storage: None,
200        };
201        if let Err(Failure(status, reason)) = inspect(&conn, &mut evidence, sink) {
202            evidence.status = status;
203            evidence.reason = Some(reason);
204        }
205        Ok(evidence)
206    }
207}
208
209/// Refuse a writable connection: pinned inspections rely on the deferred
210/// read transaction `open_read_only` starts, so every read shares a snapshot.
211pub(super) fn require_read_only(conn: &Connection, what: &str) -> Result<()> {
212    if !conn
213        .is_readonly(MAIN_DB)
214        .map_err(|e| OakError::Database(e.to_string()))?
215    {
216        return Err(OakError::InvalidArgument(format!(
217            "{what} requires open_read_only"
218        )));
219    }
220    Ok(())
221}
222
223/// Validate the `--at` form shared by pinned inspections.
224pub(super) fn validate_revision(revision: &str) -> Result<()> {
225    if revision != "HEAD" && (revision.len() != 64 || Hash::from_hex(revision).is_err()) {
226        return Err(OakError::InvalidArgument(
227            "--at requires HEAD or a full 64-character hexadecimal commit hash".into(),
228        ));
229    }
230    Ok(())
231}
232
233/// Schema/hash-format preconditions shared by pinned object inspections.
234pub(super) fn check_inspectable_schema(conn: &Connection) -> Checked<()> {
235    for (table, column) in [("blobs", "codec"), ("trees", "content")] {
236        let exists: bool = conn
237            .query_row(
238                "SELECT EXISTS(SELECT 1 FROM pragma_table_info(?1) WHERE name=?2)",
239                [table, column],
240                |row| row.get(0),
241            )
242            .map_err(database)?;
243        if !exists {
244            return Err(failure(
245                InspectionStatus::Unsupported,
246                format!("local schema lacks {table}.{column}; inspection never migrates databases"),
247            ));
248        }
249    }
250    let hash_format = bounded_metadata_text(conn, "hash_format", "hash format metadata")?;
251    if !matches!(hash_format.as_deref(), None | Some("v1")) {
252        return Err(failure(
253            InspectionStatus::Unsupported,
254            "repository hash format is unsupported by V1 file inspection",
255        ));
256    }
257    Ok(())
258}
259
260fn inspect(
261    conn: &Connection,
262    out: &mut FileInspection,
263    sink: &mut dyn std::io::Write,
264) -> Checked<()> {
265    check_inspectable_schema(conn)?;
266    let revision = resolve_revision(conn, &out.requested_revision)?;
267    let hash = Hash::from_hex(&revision).map_err(corrupt)?;
268    out.commit = Some(hash.to_string());
269    let root = verified_commit_root(conn, &hash)?;
270    out.commit_verification = "verified_v1_header";
271    out.root_tree = Some(root.to_string());
272    let mut current = root;
273    let mut remaining = PATH_TREE_BYTES;
274    let components: Vec<_> = out.path.split('/').map(str::to_owned).collect();
275    for (i, name) in components.iter().enumerate() {
276        out.tree = Some(current.to_string());
277        let tree = verified_tree(conn, &current, &mut remaining)?;
278        out.verified_trees += 1;
279        let entry = tree.get(name).ok_or_else(|| {
280            failure(
281                InspectionStatus::PathMissing,
282                "path is absent from the verified tree",
283            )
284        })?;
285        if i + 1 == components.len() {
286            if entry.kind != TreeEntryKind::Blob {
287                return Err(failure(
288                    InspectionStatus::Unsupported,
289                    "path names a directory, not a file",
290                ));
291            }
292            out.blob = Some(entry.hash.to_string());
293            out.mode = Some(entry.mode);
294            let verified = verify_blob_into(
295                conn,
296                &entry.hash,
297                out.max_bytes,
298                &mut out.declared_size,
299                sink,
300            )?;
301            out.verified_size = Some(verified.logical_size);
302            out.content_sha256 = Some(verified.sha256);
303            out.storage = Some(verified.storage);
304            return Ok(());
305        }
306        if entry.kind != TreeEntryKind::Tree {
307            return Err(failure(
308                InspectionStatus::PathMissing,
309                "a parent component is a file; symlinks are not followed",
310            ));
311        }
312        current = entry.hash.clone();
313    }
314    unreachable!("validated nonempty path")
315}
316
317/// Resolve HEAD with the same attached/detached semantics as status, commit,
318/// and `oak hash`, while keeping every ref read in this inspection snapshot.
319pub(super) fn resolve_revision(conn: &Connection, requested: &str) -> Checked<String> {
320    if requested != "HEAD" {
321        return Ok(requested.to_string());
322    }
323
324    let current_branch = bounded_metadata_text(conn, "current_branch", "current branch metadata")?
325        .filter(|name| !name.is_empty());
326
327    let resolved = if let Some(mut branch) = current_branch {
328        let mut seen = std::collections::HashSet::new();
329        let mut resolved = None;
330        for _ in 0..HEAD_PARENT_HOPS {
331            if !seen.insert(branch.clone()) {
332                return Err(corrupt("HEAD branch parent chain contains a cycle"));
333            }
334            if let Some(head) = bounded_branch_head(conn, &branch)? {
335                resolved = Some(head);
336                break;
337            }
338            let Some(parent) = bounded_parent_branch(conn, &branch)? else {
339                return Err(failure(InspectionStatus::ObjectMissing, "HEAD is absent"));
340            };
341            branch = parent;
342        }
343        resolved.ok_or_else(|| budget("HEAD parent chain exceeds 128-hop verification budget"))?
344    } else {
345        bounded_metadata_text(conn, "head", "legacy HEAD metadata")?
346            .ok_or_else(|| failure(InspectionStatus::ObjectMissing, "HEAD is absent"))?
347    };
348
349    Ok(resolved)
350}
351
352pub(super) fn bounded_metadata_text(
353    conn: &Connection,
354    key: &str,
355    label: &str,
356) -> Checked<Option<String>> {
357    bounded_text(
358        conn,
359        "SELECT length(CAST(value AS BLOB)), \
360         CASE WHEN length(CAST(value AS BLOB))<=?2 THEN value END \
361         FROM metadata WHERE key=?1",
362        rusqlite::params![key, REFERENCE_BYTES],
363        label,
364    )
365}
366
367pub(super) fn bounded_branch_head(conn: &Connection, branch: &str) -> Checked<Option<String>> {
368    bounded_text(
369        conn,
370        "SELECT length(CAST(head_hash AS BLOB)), \
371         CASE WHEN length(CAST(head_hash AS BLOB))<=?2 THEN head_hash END \
372         FROM branch_heads WHERE branch_name=?1",
373        rusqlite::params![branch, REFERENCE_BYTES],
374        "branch head",
375    )
376}
377
378pub(super) fn bounded_parent_branch(conn: &Connection, branch: &str) -> Checked<Option<String>> {
379    bounded_text(
380        conn,
381        "SELECT coalesce(length(CAST(parent_branch AS BLOB)),0), \
382         CASE WHEN parent_branch IS NULL OR length(CAST(parent_branch AS BLOB))<=?2 \
383         THEN parent_branch END FROM branches WHERE name=?1",
384        rusqlite::params![branch, REFERENCE_BYTES],
385        "parent branch",
386    )
387}
388
389fn bounded_text(
390    conn: &Connection,
391    sql: &str,
392    params: impl rusqlite::Params,
393    label: &str,
394) -> Checked<Option<String>> {
395    let row = conn
396        .query_row(sql, params, |row| {
397            Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(1)?))
398        })
399        .optional()
400        .map_err(database)?;
401    match row {
402        None => Ok(None),
403        Some((length, _)) if length > REFERENCE_BYTES => Err(budget(&format!(
404            "{label} exceeds 64 KiB reference-field verification budget"
405        ))),
406        Some((_, value)) => Ok(value),
407    }
408}
409
410pub(super) fn verified_commit_root(conn: &Connection, hash: &Hash) -> Checked<Hash> {
411    let length: Option<i64> = conn.query_row(
412        "SELECT length(CAST(branch_name AS BLOB))+coalesce(length(CAST(parent_hash AS BLOB)),0)+coalesce(length(CAST(merge_parent_hash AS BLOB)),0)+length(CAST(manifest_hash AS BLOB))+length(CAST(author AS BLOB))+coalesce(length(CAST(message AS BLOB)),0)+length(CAST(timestamp AS BLOB)) FROM commits WHERE hash=?1", [hash.as_str()], |r| r.get(0)
413    ).optional().map_err(database)?;
414    let length = length.ok_or_else(|| {
415        failure(
416            InspectionStatus::ObjectMissing,
417            format!("commit {hash} is unavailable locally"),
418        )
419    })?;
420    if length > HEADER_BYTES {
421        return Err(budget("commit header exceeds 64 KiB verification budget"));
422    }
423    let (branch, parent, merge_parent, root, author, message, timestamp) = conn.query_row(
424        "SELECT branch_name,parent_hash,merge_parent_hash,manifest_hash,author,message,timestamp FROM commits WHERE hash=?1", [hash.as_str()],
425        |r| Ok((r.get::<_, String>(0)?, r.get::<_, Option<String>>(1)?, r.get::<_, Option<String>>(2)?, r.get::<_, String>(3)?, r.get::<_, String>(4)?, r.get::<_, Option<String>>(5)?, r.get::<_, String>(6)?))
426    ).map_err(database)?;
427    let root = Hash::from_hex(&root).map_err(corrupt)?;
428    let parent = parent
429        .map(|h| Hash::from_hex(&h))
430        .transpose()
431        .map_err(corrupt)?;
432    let merge_parent = merge_parent
433        .map(|h| Hash::from_hex(&h))
434        .transpose()
435        .map_err(corrupt)?;
436    let timestamp = chrono::DateTime::parse_from_rfc3339(&timestamp)
437        .map_err(corrupt)?
438        .with_timezone(&chrono::Utc);
439    Commit::rehydrate_verified(
440        hash,
441        branch,
442        parent,
443        merge_parent,
444        root.clone(),
445        author,
446        message,
447        vec![],
448        timestamp,
449    )
450    .map_err(corrupt)?;
451    Ok(root)
452}
453
454struct StorageReader<R> {
455    reader: R,
456    failed: Rc<Cell<bool>>,
457}
458impl<R: Read> Read for StorageReader<R> {
459    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
460        let result = self.reader.read(buf);
461        if result.is_err() {
462            self.failed.set(true);
463        }
464        result
465    }
466}
467struct LogicalReader<'a> {
468    reader: Box<dyn Read + 'a>,
469    storage_failed: Rc<Cell<bool>>,
470}
471impl LogicalReader<'_> {
472    fn read(&mut self, buf: &mut [u8]) -> Checked<usize> {
473        self.reader.read(buf).map_err(|error| {
474            if self.storage_failed.get() {
475                failure(
476                    InspectionStatus::Unavailable,
477                    format!("local storage read failed: {error}"),
478                )
479            } else {
480                decode_error(error)
481            }
482        })
483    }
484}
485
486fn decode_reader<'a>(reader: impl Read + 'a, codec: i64) -> Checked<LogicalReader<'a>> {
487    let storage_failed = Rc::new(Cell::new(false));
488    let reader = StorageReader {
489        reader,
490        failed: storage_failed.clone(),
491    };
492    let reader: Box<dyn Read + 'a> = match codec {
493        0 => Box::new(reader),
494        1 => {
495            let mut decoder =
496                zstd::stream::read::Decoder::new(BufReader::new(reader)).map_err(|error| {
497                    if storage_failed.get() {
498                        failure(InspectionStatus::Unavailable, error.to_string())
499                    } else {
500                        decode_error(error)
501                    }
502                })?;
503            decoder.window_log_max(23).map_err(corrupt)?;
504            Box::new(decoder)
505        }
506        _ => {
507            return Err(failure(
508                InspectionStatus::Unsupported,
509                format!("unsupported blob codec {codec}"),
510            ))
511        }
512    };
513    Ok(LogicalReader {
514        reader,
515        storage_failed,
516    })
517}
518
519fn decode_error(error: std::io::Error) -> Failure {
520    if error.to_string().contains("too much memory") {
521        budget("zstd frame exceeds the 8 MiB decoder window budget")
522    } else {
523        corrupt(error)
524    }
525}
526
527pub(super) fn verified_tree(conn: &Connection, hash: &Hash, remaining: &mut u64) -> Checked<Tree> {
528    if hash == &Tree::empty_hash() {
529        return Ok(Tree::empty());
530    }
531    let row = conn
532        .query_row(
533            "SELECT rowid,length(content) FROM trees WHERE hash=?1",
534            [hash.as_str()],
535            |r| Ok((r.get::<_, i64>(0)?, r.get::<_, Option<u64>>(1)?)),
536        )
537        .optional()
538        .map_err(database)?;
539    let (rowid, stored) = row.ok_or_else(|| {
540        failure(
541            InspectionStatus::ObjectMissing,
542            format!("tree {hash} is unavailable locally"),
543        )
544    })?;
545    let limit = TREE_BYTES.min(*remaining);
546    let raw = if let Some(stored) = stored {
547        if stored > TREE_BYTES {
548            return Err(budget("stored tree exceeds 16 MiB budget"));
549        }
550        let blob = conn
551            .blob_open(MAIN_DB, "trees", "content", rowid, true)
552            .map_err(database)?;
553        let mut raw = Vec::new();
554        let mut reader = decode_reader(blob, 1)?;
555        let mut buffer = [0u8; 64 * 1024];
556        while raw.len() as u64 <= limit {
557            let wanted = buffer.len().min((limit - raw.len() as u64 + 1) as usize);
558            let count = reader.read(&mut buffer[..wanted])?;
559            if count == 0 {
560                break;
561            }
562            raw.extend_from_slice(&buffer[..count]);
563        }
564        raw
565    } else {
566        let mut stmt = conn
567            .prepare(
568                "SELECT name,kind,hash,mode FROM tree_entries WHERE tree_hash=?1 ORDER BY name",
569            )
570            .map_err(database)?;
571        let mut rows = stmt.query([hash.as_str()]).map_err(database)?;
572        let mut raw = Vec::new();
573        while let Some(row) = rows.next().map_err(database)? {
574            // SQLite borrows row text here: check size before allocating it.
575            let mut fields = Vec::with_capacity(4);
576            for column in [1, 0, 2, 3] {
577                let value = row
578                    .get_ref(column)
579                    .map_err(database)?
580                    .as_str()
581                    .map_err(corrupt)?;
582                if value.len() as u64 > limit {
583                    return Err(budget("legacy tree entry exceeds tree budget"));
584                }
585                fields.push(value);
586            }
587            let addition =
588                fields.iter().map(|s| s.len()).sum::<usize>() + 3 + usize::from(!raw.is_empty());
589            if raw.len() as u64 + addition as u64 > limit {
590                return Err(budget("legacy tree exceeds path tree budget"));
591            }
592            if !raw.is_empty() {
593                raw.push(b'\n');
594            }
595            // Legacy rows store regular mode for directories; canonical bytes use tree.
596            if fields[0] == "tree" {
597                fields[3] = "tree";
598            }
599            raw.extend_from_slice(fields.join("\t").as_bytes());
600        }
601        raw
602    };
603    if raw.len() as u64 > limit {
604        return Err(budget(
605            "decoded tree exceeds per-tree or aggregate path budget",
606        ));
607    }
608    *remaining -= raw.len() as u64;
609    if hash_bytes(&raw) != *hash {
610        return Err(corrupt(format!("tree {hash} canonical hash mismatch")));
611    }
612    let tree = Tree::from_canonical_bytes(hash.clone(), &raw).map_err(corrupt)?;
613    let rebuilt = Tree::new(tree.entries.clone()).map_err(corrupt)?;
614    if rebuilt.canonical_bytes() != raw {
615        return Err(corrupt(
616            "tree entries are not canonical sorted unique entries",
617        ));
618    }
619    Ok(tree)
620}
621
622/// Stream one blob's decoded logical bytes into `sink` while hashing them.
623/// Verified only when the byte count equals the declared size and the BLAKE3
624/// digest equals `hash`; the sink may already hold bytes on failure.
625pub(super) fn verify_blob_into(
626    conn: &Connection,
627    hash: &Hash,
628    max_bytes: u64,
629    declared_size: &mut Option<u64>,
630    sink: &mut dyn std::io::Write,
631) -> Checked<VerifiedBlob> {
632    use sha2::Digest;
633
634    let row = conn
635        .query_row(
636            "SELECT rowid,size,codec,length(content) FROM blobs WHERE hash=?1",
637            [hash.as_str()],
638            |r| {
639                Ok((
640                    r.get::<_, i64>(0)?,
641                    r.get::<_, i64>(1)?,
642                    r.get::<_, i64>(2)?,
643                    r.get::<_, u64>(3)?,
644                ))
645            },
646        )
647        .optional()
648        .map_err(database)?;
649    let Some((rowid, size, codec, stored)) = row else {
650        if hash == &hash_bytes(&[]) {
651            *declared_size = Some(0);
652            return Ok(VerifiedBlob {
653                logical_size: 0,
654                sha256: hex_lower(&sha2::Sha256::digest([])),
655                storage: StorageRepresentation {
656                    representation: "implicit_empty",
657                    codec: "none",
658                    codec_id: None,
659                    stored_bytes: 0,
660                },
661            });
662        }
663        return Err(failure(
664            InspectionStatus::ObjectMissing,
665            format!("blob {hash} is unavailable locally"),
666        ));
667    };
668    let size = u64::try_from(size).map_err(corrupt)?;
669    *declared_size = Some(size);
670    if size > max_bytes || stored > max_bytes + 1024 * 1024 {
671        return Err(budget(
672            "blob exceeds logical or stored-byte verification budget",
673        ));
674    }
675    let storage = StorageRepresentation {
676        representation: "sqlite_blob_row",
677        codec: match codec {
678            0 => "none",
679            1 => "zstd",
680            _ => "unknown",
681        },
682        codec_id: Some(codec),
683        stored_bytes: stored,
684    };
685    let blob = conn
686        .blob_open(MAIN_DB, "blobs", "content", rowid, true)
687        .map_err(database)?;
688    let mut reader = decode_reader(blob, codec)?;
689    let mut digest = blake3::Hasher::new();
690    let mut sha = sha2::Sha256::new();
691    let mut count = 0u64;
692    let mut buffer = [0u8; 64 * 1024];
693    loop {
694        let wanted = buffer.len().min((max_bytes - count + 1) as usize);
695        let n = reader.read(&mut buffer[..wanted])?;
696        if n == 0 {
697            break;
698        }
699        count += n as u64;
700        if count > max_bytes {
701            return Err(budget(
702                "decoded blob exceeds logical-byte verification budget",
703            ));
704        }
705        digest.update(&buffer[..n]);
706        sha.update(&buffer[..n]);
707        sink.write_all(&buffer[..n]).map_err(|error| {
708            failure(
709                InspectionStatus::Unavailable,
710                format!("output write failed: {error}"),
711            )
712        })?;
713    }
714    if count != size {
715        return Err(corrupt(format!(
716            "blob size mismatch: metadata={size}, logical={count}"
717        )));
718    }
719    if digest.finalize().to_hex().as_str() != hash.as_str() {
720        return Err(corrupt(format!(
721            "blob {hash} logical content hash mismatch"
722        )));
723    }
724    Ok(VerifiedBlob {
725        logical_size: count,
726        sha256: hex_lower(&sha.finalize()),
727        storage,
728    })
729}
730
731pub(super) fn hex_lower(bytes: &[u8]) -> String {
732    use std::fmt::Write;
733    let mut out = String::with_capacity(bytes.len() * 2);
734    for byte in bytes {
735        let _ = write!(out, "{byte:02x}");
736    }
737    out
738}
739
740#[cfg(test)]
741mod tests {
742    use super::*;
743
744    struct FailingStorage;
745    impl Read for FailingStorage {
746        fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
747            Err(std::io::Error::other("storage temporarily unavailable"))
748        }
749    }
750
751    #[test]
752    fn storage_failure_is_not_content_corruption_through_either_codec() {
753        for codec in [0, 1] {
754            let result = match decode_reader(FailingStorage, codec) {
755                Ok(mut reader) => reader.read(&mut [0; 10]),
756                Err(error) => Err(error),
757            };
758            assert_eq!(result.unwrap_err().0, InspectionStatus::Unavailable);
759        }
760        let mut malformed = decode_reader(b"not zstd".as_slice(), 1).unwrap();
761        assert_eq!(
762            malformed.read(&mut [0; 10]).unwrap_err().0,
763            InspectionStatus::Corrupt
764        );
765    }
766}