operations-block-imaging

Forensic block capture: write-block-gated acquisition, capacity preflight, dual-digest signed manifest, and the CaptureReceipt/VerifiedCapture pair that is the only way to authorize what runs after a capture

What it is for

operations-block-imaging — forensic block capture, and the proof that authorizes everything downstream of it.

Two things live here, and the second is why the first is worth having.

Acquisition (capture) reads a suspect device in one fixed order: the write-block is confirmed, the destination is proven large enough, and only then is a byte read. Both gates refuse before the reader is touched — on a disk you are not allowed to write to, "it returned an error afterwards" is not the same guarantee. A capture that fails mid-stream keeps what it read and never publishes the final artifact name, because deleting a partial acquisition can destroy the only readable data a failing disk will ever give up.

Proof (CaptureReceipt and VerifiedCapture) is the ordering invariant expressed as a type rather than as a file on disk. verify, triage and reinstall are separate process invocations, so the thing that crosses between them is the signed, serializable CaptureReceipt; the VerifiedCapture token is reconstructed inside the consuming process by VerifiedCapture::from_receipt, which is its only constructor and which re-hashes the artifact for itself. A receipt assembled by hand, signed by an untrusted key, replayed from another case or another device, or covering an artifact that has since changed, yields no token — so a caller cannot hold one without the capture having actually happened, for this case, on this device.

What this does NOT claim: against code already running as root on the same host, no userspace mechanism here holds. The guarantee is detection through the signed digest, not prevention.

Testability

The device, the destination and the write-blocker are traits (SourceReader, ArtifactSink, WriteBlockCheck), so every refusal above is proven against fixtures without touching hardware — the same seam idiom operations-device-safety uses for operations_device_safety::DeviceResolver.

Capabilities

crate root

operations-block-imaging — forensic block capture, and the proof that authorizes

ArtifactReader

operations-block-imaging — forensic block capture, and the proof that authorizes

ArtifactSink

operations-block-imaging — forensic block capture, and the proof that authorizes

BlockImagingError

operations-block-imaging — forensic block capture, and the proof that authorizes

BlockdevWriteBlock

operations-block-imaging — forensic block capture, and the proof that authorizes

CaptureManifest

operations-block-imaging — forensic block capture, and the proof that authorizes

CaptureReceipt

operations-block-imaging — forensic block capture, and the proof that authorizes

CaptureSpec

operations-block-imaging — forensic block capture, and the proof that authorizes

DeviceReader

operations-block-imaging — forensic block capture, and the proof that authorizes

FileArtifactSink

operations-block-imaging — forensic block capture, and the proof that authorizes

SourceReader

operations-block-imaging — forensic block capture, and the proof that authorizes

VerifiedCapture

operations-block-imaging — forensic block capture, and the proof that authorizes

WriteBlockCheck

operations-block-imaging — forensic block capture, and the proof that authorizes

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

No public modules: the crate root is its whole surface.

Public surface

`crate root`

No pub use re-exports: every item above is declared in this crate.

Boundary

Reaches into foundation, infrastructure.

Shares tier operations with 40 other crates: operations-approval-workflow, operations-assessments, operations-boot-media, operations-browser-agent-worker, operations-camera-discovery, operations-camera-liveview, operations-camera-registry, operations-compliance, … (40 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_operations["operations"] --> n_foundation["foundation"]
  n_operations["operations"] --> n_infrastructure["infrastructure"]

Dependencies

Runtime, in this workspace.

Runtime, from outside the workspace.

Development, in this workspace.

Development, from outside the workspace.

Build. None.

Depended on by. 1 workspace crate.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_tools_ir_triage["tools-ir-triage"] -->|uses| SELF
  SELF["operations-block-imaging"]
  SELF -->|development| n_foundation_crypto_sign["foundation-crypto-sign"]
  SELF -->|runtime| n_foundation_audit_log["foundation-audit-log"]
  SELF -->|runtime| n_foundation_bounded_io["foundation-bounded-io"]
  SELF -->|runtime| n_foundation_crypto_sign["foundation-crypto-sign"]
  SELF -->|runtime| n_infrastructure_write_blocker["infrastructure-write-blocker"]
  SELF -->|runtime| n_operations_device_safety["operations-device-safety"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

Related capabilities

1 workspace crate depends on this one: tools-ir-triage.

Verification

Evidence by module. How often each public module is named by something executable.

What the tests establish, by name:

• a_device_reader_returns_exactly_the_bytes_and_the_size — tests/adapters.rs
• a_real_block_device_reports_its_true_size_not_zero — tests/adapters.rs
• a_sink_that_is_never_promoted_leaves_the_partial_and_no_final — tests/adapters.rs
• a_sink_writes_to_partial_and_the_final_name_does_not_exist_until_promoted — tests/adapters.rs
• free_bytes_comes_from_the_destination_filesystem_not_a_guess — tests/adapters.rs
• opening_a_source_that_does_not_exist_fails_rather_than_yielding_an_empty_capture — tests/adapters.rs
• a_capture_that_fails_mid_stream_never_publishes_the_final_artifact — tests/capture_order.rs
• a_clean_capture_promotes_and_reports_both_digests — tests/capture_order.rs
• an_unconfirmed_write_block_refuses_before_the_device_is_read — tests/capture_order.rs
• insufficient_capacity_refuses_before_the_device_is_read — tests/capture_order.rs
• a_receipt_assembled_by_hand_is_refused — tests/token.rs
• a_receipt_for_another_device_is_refused — tests/token.rs
• a_receipt_from_another_case_is_refused — tests/token.rs
• a_receipt_survives_serialization_because_that_is_what_it_is_for — tests/token.rs
• a_receipt_whose_artifact_was_altered_after_signing_is_refused — tests/token.rs
• an_honest_receipt_yields_a_token — tests/token.rs
• a_receipt_is_bound_to_the_key_that_signed_it — tests/verify_roundtrip.rs
• an_artifact_that_does_not_match_its_manifest_never_produces_a_receipt — tests/verify_roundtrip.rs
• capture_then_verify_yields_a_receipt_that_opens_the_token — tests/verify_roundtrip.rs
• a_blockdev_that_cannot_be_run_errors_rather_than_confirming — tests/write_block_adapter.rs
• a_verified_write_block_confirms — tests/write_block_adapter.rs
• a_write_block_that_did_not_take_effect_is_never_reported_as_confirmed — tests/write_block_adapter.rs
• a_source_plus_reserve_that_overflows_does_not_wrap_into_sufficiency — src/lib.rs
• capacity_must_cover_the_source_and_the_reserve_both — src/lib.rs

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 27
    "No rustdoc detected" : 7

Metrics

pie showData
    title Public API by kind
    "enum" : 1
    "function" : 4
    "method" : 18
    "struct" : 7
    "trait" : 4

pie showData
    title Rust source composition
    "Code" : 391
    "Blank or comment" : 263

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.