Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 29 additions & 23 deletions book/src/packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,34 @@ 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).

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.
Packages can be identified by fingerprint, a hash that uniquely identifies the
content of the package:

```
package12186aa6cefc1ae2f427b90e61a3ab91c88573f6f6719ca0188098d681b6c80ca
```

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
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
Expand All @@ -21,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).
Expand All @@ -42,13 +55,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
-------------

Expand Down
Loading