From 547d4414d9dc97293910b6c5a84850dd3185584a Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 17:30:00 -0700 Subject: [PATCH 1/2] Add Hashing section to Packages chapter --- book/src/packages.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index 1f501ebf..702931da 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -14,6 +14,16 @@ by checking that a package was signed by a trusted public key. Filepack packages may include machine-readable metadata in a file named `metadata.filemeta` in the package root. +A package may be stored in forms other than as a directory tree and manifest. +For example, the Filepack server stores files and serialized directories by +hash in a flat directory, alongside a database recording package fingerprints. +This allows the Filepack server to deduplicate files that appear in multiple +packages, and allows clients to skip uploading files that are already present +on the server, regardless of which package contains them. + +Hashing +------- + A Filepack package is a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree). The root hash of the tree is the hash of the serialized root directory of the package. Serialized @@ -42,13 +52,6 @@ being hashed, broken into 1 KiB chunks. This allows files to be streamed and verified incrementally using compact proofs that downloaded file chunks are included in the BLAKE3 Merkle tree. -A package may be stored in forms other than as a directory tree and manifest. -For example, the Filepack server stores files and serialized directories by -hash in a flat directory, alongside a database recording package fingerprints. -This allows the Filepack server to deduplicate files that appear in multiple -packages, and allows clients to skip uploading files that are already present -on the server, regardless of which package contains them. - Serialization ------------- From 764277caa56caa1e80f128370c228e11373efd3b Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 17:45:42 -0700 Subject: [PATCH 2/2] Add less technical introduction to the packages chapter --- book/src/packages.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index 702931da..da637e0b 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -4,15 +4,24 @@ Packages A Filepack package is a directory containing a manifest named `manifest.filepack`, which records the names, sizes, and [BLAKE3 hashes](https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE3) of all -files in the directory and its subdirectories. +files in the directory and its subdirectories, and which may be signed using +[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519). + +Packages can be identified by fingerprint, a hash that uniquely identifies the +content of the package: + +``` +package12186aa6cefc1ae2f427b90e61a3ab91c88573f6f6719ca0188098d681b6c80ca +``` -A Filepack manifest contains all the information needed to verify the contents -of a package. Additionally, packages may be signed using -[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519), allowing verification -by checking that a package was signed by a trusted public key. +The authenticity of a package can be verified by manifest, fingerprint, or +signature, guaranteeing that the contents of the package have not been +accidentally modified or intentionally tampered with. Filepack packages may include machine-readable metadata in a file named -`metadata.filemeta` in the package root. +`metadata.filemeta` in the package root, which includes information about the +package, the packager, its media content, and assets such as package artwork +and image thumbnails. A package may be stored in forms other than as a directory tree and manifest. For example, the Filepack server stores files and serialized directories by @@ -31,16 +40,10 @@ directories contain the names, sizes, hashes, and types of their children, which may be files or subdirectories. The root hash of a package Merkle tree is called the package fingerprint, and -is represented as [tagged hex](hex.md): - -``` -package12186aa6cefc1ae2f427b90e61a3ab91c88573f6f6719ca0188098d681b6c80ca -``` - -A package fingerprint uniquely identifies the content of a package. Any change -to the content of a package results in a completely different fingerprint, and -it is computationally infeasible, assuming that BLAKE3 is collision-resistant, -to create two packages with different content, but with the same fingerprint. +uniquely identifies the content of a package. Any change to the content of a +package results in a completely different fingerprint, and it is +computationally infeasible, assuming that BLAKE3 is collision-resistant, to +create two packages with different content but the same fingerprint. Filepack's use of Merkle trees allows for efficient sharing and verification of packages over the internet, for example using the [Filepack server](server.md).