fcb 0.1.0

Forensic Case Bundle (FCB) codec — container, passphrase crypto, compression, evidence model
Documentation

fcb-rs

ci license: ECL-2.0

FCB(Forensic Case Bundle)協定的權威 Rust 實作。 說穿了,它就是一個 codec:把證物(evidence)封裝成可攜、加密、又能驗證的 .case / .casework 檔。這套程式碼原本長在 browser-arena 數位鑑識教學平台裡,後來抽出來自成一個獨立 repo。

同一份 codec,編兩個目標。native 那一側餵的是出題 CLI 和教師審閱平台,WASM 那一側則跑在瀏覽器 workbench。核心相依清一色純 Rust——ruzstd、argon2、chacha20poly1305、sha2——一個 C FFI 都沒有,所以它才編得到 wasm32。

FCB 是什麼?

  • .case(KIND=case)是教師端出的題目。裡頭塞著 N 條具型別的證物 stream(syslog、netflow、json 等等),外加一份 task spec——而且這份 spec 不含答案。
  • 學生交回來的作答則是 .casework(KIND=work),裝著筆記、報告和活動紀錄。它靠 case_id 加 bundle_hash 綁回某一道題、某一個證物版本,跑不掉。

容器長這樣:magic ‖ KIND ‖ container_version ‖ header(明文 CBOR) ‖ payload(= AEAD(zstd(明文)))。金鑰是拿 passphrase 過一遍 Argon2id 派生出來的。想看逐位元、不留模糊空間的權威定義,翻 docs/fcb-wire-format.md 和 docs/fcb-reference.md。

Repo 結構

路徑 內容
crates/fcb codec 本體:container、crypto、compression、evidence/stream 模型、task、submission、case(pack_case)。
crates/fcb-wasm WASM / JS bridge,也就是瀏覽器 workbench 的進出口(peekHeader、openCase、packSubmission 等)。
docs/ 協定的權威文件:fcb-wire-format、fcb-data-model、fcb-reference、docs/README。
openspec/ Spectra 規格(specs/)與變更提案(changes/)。

Quickstart

Rust(相依本 crate)

# Cargo.toml
[dependencies]
fcb = "0.1.0"

下面這段一次走完兩端:producer 打包一份 .case,consumer 再把它開封。

use ciborium::value::Value;
use fcb::case::{pack_case, CaseInput, CasePayload};
use fcb::evidence::{StreamData, StreamManifest};

// 1) manifest 宣告每條 stream 的 id / type / 筆數;payload 帶記錄。
//    這裡用一個第三方範例 type;內建 type(fcb.syslog.v1 等)的記錄 schema 見 docs/fcb-data-model.md §3。
let manifest = vec![StreamManifest {
    id: "s0".into(), stream_type: "example.note.v1".into(), records: 1,
}];
let payload = CasePayload {
    streams: vec![StreamData {
        id: "s0".into(),
        records: vec![Value::Text("an event".into())],
    }],
};
// 2) pack_case:自動算 canonical bundle_hash、組 meta、封裝。
let input = CaseInput { case_id: "demo".into(), manifest, task: None, payload };
let bytes = pack_case(&input, "passphrase").unwrap();

// 3) 開封。
let (kind, header, _payload) = fcb::bundle::open_bytes(&bytes, "passphrase").unwrap();
assert_eq!(kind, fcb::container::BundleKind::Case);
assert_eq!(header.case_id, "demo");

想要更完整、而且真的會過測試的範例,去看 docs/README.md 和 crates/fcb/tests/。

WASM / JS(瀏覽器或 Node)

wasm-pack build crates/fcb-wasm --target web      # 或 --target nodejs / bundler

build 完的 pkg/ 會把這幾支匯出去:peekHeader(bytes)、openCase(bytes, passphrase)、openSubmission(bytes, passphrase)、packSubmission(submission, passphrase)、packCase(caseObject, passphrase)、computeBundleHash(bytes)、verifyBinding(...) 還有 workKey(caseId)。出錯時它不會只丟個含糊的錯誤,而是回一個你認得出來的 error kind——bad-magic、wrong-passphrase、corrupt 之類的。整合上的細節都在 crates/fcb-wasm/src/lib.rs。

Build / Test

cargo build --workspace
cargo test --workspace      # 含 golden vectors 與 round-trip 套件
cargo clippy --all-targets --all-features -- -D warnings
wasm-pack build crates/fcb-wasm --target nodejs

CI 設定在 .github/workflows/ci.yml。每次 push 進 main、每個 PR,它都會跑一遍 cargo test --workspace,再加一道 wasm32 build smoke 把關。

文件入口

貢獻與安全

  • 想送 PR,先看 CONTRIBUTING.md 把流程和品質關卡摸熟;和大家相處的那一套規矩寫在 CODE_OF_CONDUCT.md。
  • 發現安全漏洞,請走 SECURITY.md 列的私密管道回報,千萬別開成 public issue。

授權

本專案採 Educational Community License, Version 2.0(ECL-2.0),完整條款在 LICENSE。© 2026 The fcb-rs Authors。