From 2cbaf3b175fd32c24d23af7714e06810479c9a03 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 24 Oct 2026 15:06:08 -0700 Subject: [PATCH 01/10] Rename `Design` chapter to `Packages` --- book/src/SUMMARY.md | 2 +- book/src/{design.md => packages.md} | 4 ++-- crates/generate/templates/summary.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename book/src/{design.md => packages.md} (99%) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index d90dd430..554e1d4e 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -9,6 +9,7 @@ Summary - [Quickstart](quickstart.md) # Guide +- [Packages](packages.md) - [Configuration](configuration.md) - [Authoring Metadata](authoring-metadata.md) - [Server](server.md) @@ -16,7 +17,6 @@ Summary # Background - [Why is metadata important?](why-metadata.md) - [Alternatives and Prior Art](alternatives.md) -- [Design](design.md) # Reference - [Commands](commands.md) diff --git a/book/src/design.md b/book/src/packages.md similarity index 99% rename from book/src/design.md rename to book/src/packages.md index 9ec8f8c5..e4377ba2 100644 --- a/book/src/design.md +++ b/book/src/packages.md @@ -1,5 +1,5 @@ -Design -====== +Packages +======== Manifest Format --------------- diff --git a/crates/generate/templates/summary.md b/crates/generate/templates/summary.md index 43888de4..62c06141 100644 --- a/crates/generate/templates/summary.md +++ b/crates/generate/templates/summary.md @@ -9,6 +9,7 @@ Summary - [Quickstart](quickstart.md) # Guide +- [Packages](packages.md) - [Configuration](configuration.md) - [Authoring Metadata](authoring-metadata.md) - [Server](server.md) @@ -16,7 +17,6 @@ Summary # Background - [Why is metadata important?](why-metadata.md) - [Alternatives and Prior Art](alternatives.md) -- [Design](design.md) # Reference - [Commands](commands.md) From 3fb21f8005be98accfbc95a811bb3aad795a54e5 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 24 Oct 2026 15:26:23 -0700 Subject: [PATCH 02/10] Use package root instead of root directory --- README.md | 2 +- book/src/server.md | 2 +- book/src/why-metadata.md | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c9795914..ef28a854 100644 --- a/README.md +++ b/README.md @@ -267,7 +267,7 @@ Please feel free to open issues requesting new lints. ### Creating a Package with Metadata To create a package with metadata describing the package, create a file named -`metadata.yaml` in the package directory, for example: +`metadata.yaml` in the package root, for example: ```yaml title: The Necronomicon diff --git a/book/src/server.md b/book/src/server.md index c7e77b11..45397e23 100644 --- a/book/src/server.md +++ b/book/src/server.md @@ -148,7 +148,7 @@ replacement, and update. After successfully creating, replacing, or updating a package on the server, the new package head for that server is recorded to `.filepack/state.json` in -the package root directory. +the package root. ### Package Creation diff --git a/book/src/why-metadata.md b/book/src/why-metadata.md index c08cff05..c0d03927 100644 --- a/book/src/why-metadata.md +++ b/book/src/why-metadata.md @@ -36,10 +36,10 @@ content. Filepack seeks to rectify this by standardizing machine-readable metadata that can be included with folder-of-files content. -Filepack metadata is stored in a file, `metadata.filemeta`, in the root of a -filepack package as well as in the `manifest.filepack` archive, and contains -information related to what the package contains, which files in the package -contain the package content and their file formats, and who created the -package. This metadata can serve as a base for the creation of rich local and -distributed applications and services, with user experiences that compete with -and exceed those of closed centralized alternatives. +Filepack metadata is stored in a file, `metadata.filemeta`, in the package root +as well as in the `manifest.filepack` archive, and contains information related +to what the package contains, which files in the package contain the package +content and their file formats, and who created the package. This metadata can +serve as a base for the creation of rich local and distributed applications and +services, with user experiences that compete with and exceed those of closed +centralized alternatives. From a8009d8bb5c9daf35efc1f74a5e1bb06b5617b37 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 24 Oct 2026 17:21:02 -0700 Subject: [PATCH 03/10] Move readme content into book --- README.md | 111 --------------------- book/src/packages.md | 224 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 185 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index ef28a854..069e1cb8 100644 --- a/README.md +++ b/README.md @@ -45,104 +45,6 @@ See [installation](https://filepack.com/book/installation.html) and [Why is metadata important?](https://filepack.com/book/why-metadata.html) for some of the higher-level ideas behind filepack. -Manifest --------- - -`filepack` manifests are named `manifest.filepack` and are placed alongside the -files they reference. - -Manifests are encoded with deco, a compact binary serialization format, and may -be converted to JSON for inspection or manipulation with `filepack manifest`. - -Manifests, when converted to JSON, are an object with three mandatory keys, -`embedded`, `package`, and `signatures`. - -### `embedded` - -The value of the mandatory `embedded` key is an object mapping BLAKE3 hashes to -hex-encoded file contents. The `package` object only includes file names, -hashes, and sizes, but files may be embedded in the manifest archive in the -`embedded` map. - -This is currently only used to embed `metadata.filemeta`. - -### `package` - -The value of the mandatory `package` key is an object mapping path components -to directory entries. Directory entries may be subdirectories or files. Files -are objects with two fields: `hash`, the tagged hex BLAKE3 hash of the file, -and `size`, the length of the file in bytes. - -Path components are UTF-8 and may not be `.` or `..`, contain the path -separators `/` or `\`, contain control characters, or begin with a Windows -drive prefix, such as `C:`. - -### `signatures` - -The value of the mandatory `signatures` key is an array of signatures. -Signatures are tagged hex strings that include an Ed25519 key, the package -fingerprint the signature is made over, an optional timestamp, and the -signature itself. - -Public keys are Curve25519 points and signatures are Ed25519 signatures made -over the hash of a serialized deco byte string containing the package -fingerprint, which commits to the content of `package`, and an optional -timestamp. - -### Example - -A manifest converted to JSON over a directory containing the files `README.md` -and `src/main.rs`, with a signature: - -```json -{ - "embedded": {}, - "package": { - "README.md": { - "hash": "hash1fc253b84551ce6b00e820a826ac18054dc7f63a318ce62f3175315f5c467a62a", - "size": 11883 - }, - "src": { - "main.rs": { - "hash": "hash11fa48b95ed335369d45b91af8138bdccd1413364bcdbfa6e9034e8a2cfd6e17f", - "size": 33 - } - } - }, - "signatures": ["…"] -} -``` - -The signature is elided for brevity. Signatures are tagged hex strings -containing a public key and signature. - -Metadata --------- - -Filepack packages may contain a file named `metadata.filemeta` describing the -package and its contents. If present, `metadata.filemeta` is also embedded in -the `manifest.filepack` archive. - -Metadata is authored by creating a file named `metadata.yaml` in the root of a -new package. `filepack create` then loads `metadata.yaml` if present, checks -for validity and unknown fields, and writes the deco serialization to -`metadata.filemeta` in the package root. - -`metadata.yaml` is retained as a human-readable reference and for amending -metadata, but `metadata.filemeta` is the authoritative source of metadata. For -consumption by scripts and tools, `filepack metadata` prints the contents of -`metadata.filemeta` as JSON. - -Filepack metadata is intended to be a broadly useful machine and human readable -description of the contents of a package, covering personal, distribution, and -archival use-cases. - -Metadata follows a fixed schema and is not user-extensible. Future versions of -`filepack` may define new metadata fields, causing verification errors if those -fields are present and invalid according to the new schema. - -Please feel free to open an issue with ideas for new metadata fields. - Lints ----- @@ -220,19 +122,6 @@ filepack verify --key PUBLIC_KEY Which will fail if a valid signature for `PUBLIC_KEY` over the manifest contents is not present. -Fingerprints ------------- - -Filepack signatures are made over the package fingerprint, which is the hash of -a deco object which commits to the files and directories contained in the -manifest. - -Fingerprints are BLAKE3 hashes, constructed such that it is impossible to -produce packages which are different but which have the same fingerprint. - -Fingerprints may be used as a globally unique identifier. If two packages have -the same fingerprint, they have the same content. - Guide ----- diff --git a/book/src/packages.md b/book/src/packages.md index e4377ba2..d710e14f 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -1,51 +1,197 @@ Packages ======== -Manifest Format ---------------- +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. -A filepack manifest contains all information needed to verify the contents of a -directory. The `package` key of the manifest is a directory object mapping -filenames to directory entries, which may themselves be directories, or files, -in which case they contain the hash of the file contents, as well as the length -of the file. +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 length of the file is not strictly necessary for verification, but is -included so that truncated, empty, and overlong files can be identified, which -may help in understanding verification failures. +Filepack packages may include machine-readable metadata in a file named +`metadata.filemeta` in the package root. -File contents may be embedded in the `manifest.filepack` archive under the -`embedded` key. +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, called the package +root. Serialized directories contain the names, sizes, hashes, and types of +their children, which may be files or subdirectories. -File Hashes ------------ +The root hash of a package Merkle tree is called the package fingerprint, and +is represented in using [tagged hex](hex.md): -The contents of files are hashed with -[BLAKE3](https://github.com/BLAKE3-team/BLAKE3) using the official Rust -implementation. BLAKE3 was chosen both for its speed, and for the fact that it -utilizes a Merkle tree construction. A Merkle tree allows for verified file -streaming and subrange inclusion proofs, which both seem useful in the context -of file hashing and verification. +``` +package1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 +``` + +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. + +BLAKE3 is itself a Merkle tree hash, whose leaves are the contents of the file +being hashed, broken into 1 KiB chunks. + +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). +A client, starting with a package fingerprint, first requests and verifies the +serialized package root directory, followed by each subdirectory, and file. + +Because file hashes are Merkle tree roots, files can be streamed and verified +incrementally, with the server providing the client of a compact proof that +downloaded file chunks are included in the BLAKE3 Merkle tree> + +Because filepack packages are trees of directories, they are composable. A +filepack package may contain other packages, with the directory entry of each +subpackage containing the subpackage fingerprint. + +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 +------------- + +Package directories, `manifest.filepack` manifests, and `metadata.filemeta` +metadata are serialized as deco, a compact, canonical, schema-driven binary +serialization format. + +The [deco](deco.md) chapter includes a description of deco itself, as well as +the schemas of all types serialized as deco. + +A package fingerprint is the BLAKE3 hash of the deco-encoded package root +[directory](deco.md/directory.md), containing [entries](deco/entry.md) for each +child. Each entry contains the hash, name, and size of the child, along with +its [type and additional info](deco/entry-info.md). For directories, this +additional info includes [totals](deco/totals.md), the total number of files +and subdirectories, as well as their aggregate file size. + +Filepack uses three other serialization formats, aside from deco: + +- [Tagged hex](hex.md), a text format wrapping a hex-encoded deco payload. Used + for fingerprints, hashes, public keys, private keys, and signatures. + +- [YAML](yaml.md), a human-readable and writable text format, used for + hand-authored files, namely `metadata.yaml`, the template from which a + package's `metadata.filemeta` is generated. + +- [JSON](json.md), a simple text format, used for command input and output, and + machine-authored files. + +Manifests +--------- + +Manifests are serialized with [deco](deco.md), a compact, binary serialization +format, and stored in a file named `manifest.filepack` in the package root +directory. + +A `manifest.filepack` file is called a manifest archive, and is a +content-addressed format, containing a root hash, which is not the package +fingerprint, but instead to hash of an intermediate directory, and a map of +hashes to file contents. See [Archive](deco/archive.md) for the manifest +archive schema. + +The manifest can be traversed by reading the root hash, reading the entry for +the root hash in the files map, deserializing the contents as a [deco +directory](deco/directory.md), and repeating the process for subdirectories. + +The manifest archive root directory contains two subdirectories, `package` and +`signatures`. + +The `package` directory is the package root, and the `signatures` directory +contains signatures over the package root. Each signature is stored as a file +whose name is the hash of the serialized signature. + +All other subdirectory names are reserved for use by future versions of +Filepack. Unrecognized subdirectories of the manifest archive root are ignored +but preserved. + +Manifest archives do not contain package files, only serialized directories. +The only exception to this is `metadata.filemeta`, which is included in the +archive if present. This allows the manifest archive to serve as a convenient, +single-file reference for a package, including both file hashes and sizes, as +well as metadata. + +Manifests can be converted to JSON with `filepack manifest` for inspection and +manipulation. A JSON manifest can be converted to a deco manifest archive with +`filepack archive`. See [Manifest](json/manifest.md) for the JSON schema. + +Filenames +--------- + +Path components in manifest directories are UTF-8 and may not be `.` or `..`, +contain the path separators `/` or `\`, contain control characters, or begin +with a Windows drive prefix, such as `C:`. + +This ensures that file paths assembled from path components work on Windows and +Unix, and cannot escape the package root. Symbolic links are not supported. Signatures ---------- -Filepack allows for the creation of Ed25519 signatures over the contents of a -manifest, which thus commit to the contents of the directory covered by the -manifest. Signatures are made over a statement containing a "fingerprint" hash -of a canonical deco serialization of the manifest's `package` directory. This -keeps signatures independent of the manifest format, avoids the need for a -canonical serialization of the manifest as a whole, avoids hash loops due to -the inclusion of signatures in the manifest itself, and allows proving the -inclusion of files covered by a signature. - -Fingerprints ------------- - -Package fingerprints are the BLAKE3 hash of a canonical deco serialization of -the manifest's `package` directory. Fingerprints are constructed to be unique, -meaning that it is impossible for two different packages with different -contents to have the same fingerprint. - -Currently, no fingerprint test vectors exist, and the best documentation is the -code itself. +Filepack allows for the creation of +[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) signatures over +a package fingerprint, which commits to the content of a package. + +Signatures are made over a deco-encoded [Statement](deco/statement.md) +containing the package fingerprint, as well as an optional integer timestamp of +seconds since the Unix epoch. + +Signatures are stored as files named after their hash in the the manifest +archive `signatures` directory. + +Signatures are encoded as [tagged-hex](hex/signature.md), whose payload is a +deco-encoded [Signature object containing the signed +Statement](deco/signature-statement.md). + +Before signing, and when verifying, the serialized statement is wrapped in an +[Envelope](deco/envelope-statement.md), which performs domain separation by +committing to the [application](deco/application.md) and +[context](deco/context.md). + +The same signature scheme, with a different context and inner +[Claims](deco/claims.md) object, is used for server authorization bearer +tokens. + +Metadata +-------- + +Filepack packages may contain a file named `metadata.filemeta` describing the +package and its contents. If present, `metadata.filemeta` is also embedded in +the `manifest.filepack` archive. + +Metadata is authored by creating a file named `metadata.yaml` in the root of a +new package. `filepack create` then loads `metadata.yaml` if present, checks +for validity and unknown fields, and writes the deco serialization to +`metadata.filemeta` in the package root. + +`metadata.yaml` is retained as a human-readable reference and for amending +metadata, but `metadata.filemeta` is the authoritative source of metadata. For +consumption by scripts and tools, `filepack metadata` prints the contents of +`metadata.filemeta` as JSON. + +Metadata follows a fixed schema and is not user-extensible, with fields +describing the package contents, the package itself, and the media content of +the package. Future versions of `filepack` may define new metadata fields, +causing verification errors if those fields are present and invalid according +to the new schema. + +Metadata allows for the attractive presentation of packages, including +browsing, viewing, search, and conversion. See +[filepack.com](https://filepack.com) for a selection of example packages, +covering a variety of media types. All metadata served by the demo server, +including package artwork, video placeholders, thumbnail images, and media +information, is sourced from package metadata. + +See [Metadata](deco/metadata.md) for the deco schema, [Authoring +Metadata](authoring-metadata) for a description of `metadata.yaml`, the +template file used to generate package metadata. + +Please feel free to [open an issue](https://github.com/casey/filepack/issues) +with ideas for new metadata fields. From ea40d42d07a83f0f742d031f53850f2933bd9738 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Sat, 24 Oct 2026 17:21:53 -0700 Subject: [PATCH 04/10] Fix typos --- book/src/packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index d710e14f..e5644546 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -66,7 +66,7 @@ The [deco](deco.md) chapter includes a description of deco itself, as well as the schemas of all types serialized as deco. A package fingerprint is the BLAKE3 hash of the deco-encoded package root -[directory](deco.md/directory.md), containing [entries](deco/entry.md) for each +[directory](deco/directory.md), containing [entries](deco/entry.md) for each child. Each entry contains the hash, name, and size of the child, along with its [type and additional info](deco/entry-info.md). For directories, this additional info includes [totals](deco/totals.md), the total number of files @@ -190,7 +190,7 @@ including package artwork, video placeholders, thumbnail images, and media information, is sourced from package metadata. See [Metadata](deco/metadata.md) for the deco schema, [Authoring -Metadata](authoring-metadata) for a description of `metadata.yaml`, the +Metadata](authoring-metadata.md) for a description of `metadata.yaml`, the template file used to generate package metadata. Please feel free to [open an issue](https://github.com/casey/filepack/issues) From 20bbef613b5bc53876de8042d728320a1920548b Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 14:19:38 -0700 Subject: [PATCH 05/10] Fix issues --- book/src/packages.md | 60 +++++++++++++++++++++++++------------------- 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index e5644546..a33e78ca 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -21,7 +21,7 @@ root. Serialized 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 in using [tagged hex](hex.md): +is represented as [tagged hex](hex.md): ``` package1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 @@ -41,8 +41,8 @@ A client, starting with a package fingerprint, first requests and verifies the serialized package root directory, followed by each subdirectory, and file. Because file hashes are Merkle tree roots, files can be streamed and verified -incrementally, with the server providing the client of a compact proof that -downloaded file chunks are included in the BLAKE3 Merkle tree> +incrementally, with the server providing the client with a compact proof that +downloaded file chunks are included in the BLAKE3 Merkle tree. Because filepack packages are trees of directories, they are composable. A filepack package may contain other packages, with the directory entry of each @@ -70,7 +70,7 @@ A package fingerprint is the BLAKE3 hash of the deco-encoded package root child. Each entry contains the hash, name, and size of the child, along with its [type and additional info](deco/entry-info.md). For directories, this additional info includes [totals](deco/totals.md), the total number of files -and subdirectories, as well as their aggregate file size. +and subdirectories, as well as their aggregate sizes. Filepack uses three other serialization formats, aside from deco: @@ -93,7 +93,7 @@ directory. A `manifest.filepack` file is called a manifest archive, and is a content-addressed format, containing a root hash, which is not the package -fingerprint, but instead to hash of an intermediate directory, and a map of +fingerprint, but instead the hash of an intermediate directory, and a map of hashes to file contents. See [Archive](deco/archive.md) for the manifest archive schema. @@ -108,9 +108,8 @@ The `package` directory is the package root, and the `signatures` directory contains signatures over the package root. Each signature is stored as a file whose name is the hash of the serialized signature. -All other subdirectory names are reserved for use by future versions of -Filepack. Unrecognized subdirectories of the manifest archive root are ignored -but preserved. +All other entry names are reserved for use by future versions of Filepack. +Unrecognized entries in the manifest archive root are ignored but preserved. Manifest archives do not contain package files, only serialized directories. The only exception to this is `metadata.filemeta`, which is included in the @@ -125,35 +124,44 @@ manipulation. A JSON manifest can be converted to a deco manifest archive with Filenames --------- -Path components in manifest directories are UTF-8 and may not be `.` or `..`, -contain the path separators `/` or `\`, contain control characters, or begin -with a Windows drive prefix, such as `C:`. +Filenames in manifest directories are non-empty UTF-8 strings and may not +contain control characters. + +Furthermore, they may not be `.` or `..`, contain `/` or `\`, or begin with a +Windows drive prefix, such as `C:`. This ensures that file paths assembled from path components work on Windows and -Unix, and cannot escape the package root. Symbolic links are not supported. +Unix and cannot escape the package root. Symbolic links are not supported. + +The filenames `manifest.filepack` and `.filepack`, with any case, are reserved +in the package root. Signatures ---------- -Filepack allows for the creation of -[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) signatures over -a package fingerprint, which commits to the content of a package. +Packages may be signed with +[Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519). -Signatures are made over a deco-encoded [Statement](deco/statement.md) +To sign a package, the signer constructs a [statement](deco/statement.md), containing the package fingerprint, as well as an optional integer timestamp of seconds since the Unix epoch. -Signatures are stored as files named after their hash in the the manifest -archive `signatures` directory. +The signature is made over the BLAKE3 hash of a deco-encoded +[envelope](deco/envelope-statement.md) containing the statement, which performs +domain separation by committing to the [application](deco/application.md) and +[context](deco/context.md). -Signatures are encoded as [tagged-hex](hex/signature.md), whose payload is a -deco-encoded [Signature object containing the signed -Statement](deco/signature-statement.md). +For transport, the raw Ed25519 signature, statement, and public key are stored +in a [signature object](deco/signature-statement.md). -Before signing, and when verifying, the serialized statement is wrapped in an -[Envelope](deco/envelope-statement.md), which performs domain separation by -committing to the [application](deco/application.md) and -[context](deco/context.md). +Signatures are serialized as deco and stored as files named after their hash in +the manifest archive `signatures` directory, and are represented in text as +[tagged-hex](hex/signature.md). + +To verify a package, first the package is verified against the statement +fingerprint, then the statement is wrapped in an envelope, serialized, hashed, +and the raw Ed25519 signature over the heash is verified against the public +key. The same signature scheme, with a different context and inner [Claims](deco/claims.md) object, is used for server authorization bearer @@ -189,7 +197,7 @@ covering a variety of media types. All metadata served by the demo server, including package artwork, video placeholders, thumbnail images, and media information, is sourced from package metadata. -See [Metadata](deco/metadata.md) for the deco schema, [Authoring +See [Metadata](deco/metadata.md) for the deco schema and [Authoring Metadata](authoring-metadata.md) for a description of `metadata.yaml`, the template file used to generate package metadata. From bc99246f3e25a50b0d249273b2a1d2925de3647d Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 14:27:35 -0700 Subject: [PATCH 06/10] Fix issues --- book/src/packages.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index a33e78ca..60fe8d1f 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -24,7 +24,7 @@ The root hash of a package Merkle tree is called the package fingerprint, and is represented as [tagged hex](hex.md): ``` -package1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262 +package12186aa6cefc1ae2f427b90e61a3ab91c88573f6f6719ca0188098d681b6c80ca ``` A package fingerprint uniquely identifies the content of a package. Any change @@ -156,12 +156,11 @@ in a [signature object](deco/signature-statement.md). Signatures are serialized as deco and stored as files named after their hash in the manifest archive `signatures` directory, and are represented in text as -[tagged-hex](hex/signature.md). +[tagged hex](hex/signature.md). -To verify a package, first the package is verified against the statement -fingerprint, then the statement is wrapped in an envelope, serialized, hashed, -and the raw Ed25519 signature over the heash is verified against the public -key. +To verify a signature, the statement is wrapped in an envelope, serialized, +hashed, and the raw Ed25519 signature over the hash is verified against the +public key. The same signature scheme, with a different context and inner [Claims](deco/claims.md) object, is used for server authorization bearer From c1e4d39fd96d8f510d8e8a4d2701d6dfd63594d4 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 14:32:26 -0700 Subject: [PATCH 07/10] Fix capitalization --- README.md | 12 ++++++------ bin/package | 2 +- book/src/configuration.md | 6 +++--- book/src/introduction.md | 4 ++-- book/src/packages.md | 12 ++++++------ book/src/quickstart.md | 2 +- book/src/server.md | 2 +- crates/generate/templates/authoring-metadata.md | 4 ++-- crates/generate/templates/deco.md | 2 +- crates/generate/templates/json.md | 2 +- crates/generate/templates/routes.md | 2 +- metadata.yaml | 2 +- src/error.rs | 2 +- src/manifest.rs | 2 +- src/subcommand.rs | 10 +++++----- static/install.sh | 2 +- tests/completions.rs | 2 +- 17 files changed, 35 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 069e1cb8..4d9e3856 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Documentation is available at [filepack.com/book/](https://filepack.com/book/). See [installation](https://filepack.com/book/installation.html) and [quickstart](https://filepack.com/book/quickstart.html) to get started, and [Why is metadata important?](https://filepack.com/book/why-metadata.html) for -some of the higher-level ideas behind filepack. +some of the higher-level ideas behind Filepack. Lints ----- @@ -88,7 +88,7 @@ filepack keygen ``` Which creates `master.public` and `master.private` files in the `keychain` -subdirectory of the filepack data directory. +subdirectory of the Filepack data directory. ### Public Key Printing @@ -130,7 +130,7 @@ defaults to the current directory. ### Creating a Package -To create a filepack manifest: +To create a Filepack manifest: ```shell filepack create [DIRECTORY] @@ -188,9 +188,9 @@ filepack keygen ``` This creates a new public key, `master.public`, with corresponding private key, -`master.private`, in the filepack keychain directory. +`master.private`, in the Filepack keychain directory. -The `filepack info` command will print the path to the filepack data directory, +The `filepack info` command will print the path to the Filepack data directory, keychain directory, and any public keys in the keychain directory. Your public key can be printed with: @@ -273,7 +273,7 @@ keys. ### Detecting Accidental Corruption -Create a filepack manifest with: +Create a Filepack manifest with: ```shell filepack create diff --git a/bin/package b/bin/package index c33f10da..07422672 100755 --- a/bin/package +++ b/bin/package @@ -45,7 +45,7 @@ cp -r \ metadata.yaml \ dist -echo "Creating filepack manifest..." +echo "Creating Filepack manifest..." cargo run create --deny distribution dist echo "Creating release archive..." diff --git a/book/src/configuration.md b/book/src/configuration.md index 68115f23..e7a7cf30 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -4,14 +4,14 @@ Configuration Data Directory -------------- -Filepack stores local data, including private keys, in the filepack data +Filepack stores local data, including private keys, in the Filepack data directory, located in `~/.filepack`, or `$XDG_DATA_HOME/filepack` if `$XDG_DATA_HOME` is set and non-empty. -Filepack stores private keys in the `keychain` subdirectory of the filepack +Filepack stores private keys in the `keychain` subdirectory of the Filepack data directory, by default in `~/.filepack/keychain`. -The location of the filepack data directory used by a command can be overridden +The location of the Filepack data directory used by a command can be overridden with the `--data-dir` option or the `FILEPACK_DATA_DIR` environment variable. Logging diff --git a/book/src/introduction.md b/book/src/introduction.md index dc30f6d0..e5d0203a 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -5,7 +5,7 @@ Introduction See [installation](installation.md) to get started and [Why is metadata important?](why-metadata.md) for some of the higher-level ideas behind -filepack. +Filepack. Why Filepack? ------------- @@ -41,6 +41,6 @@ files](https://en.wikipedia.org/wiki/Simple_file_verification): Additionally, errors can be detected and recovered from by transmitting only those parts of the file which are corrupted. -- Packages may contain machine readable metadata following a filepack-defined +- Packages may contain machine readable metadata following a Filepack-defined schema, allowing packages to be searched, indexed, and exposed through rich, featureful interfaces. diff --git a/book/src/packages.md b/book/src/packages.md index 60fe8d1f..0be92c32 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -1,12 +1,12 @@ Packages ======== -A filepack package is a directory containing a manifest named +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. -A filepack manifest contains all the information needed to verify the contents +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. @@ -14,7 +14,7 @@ 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 filepack package is a [Merkle +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, called the package root. Serialized directories contain the names, sizes, hashes, and types of @@ -44,14 +44,14 @@ Because file hashes are Merkle tree roots, files can be streamed and verified incrementally, with the server providing the client with a compact proof that downloaded file chunks are included in the BLAKE3 Merkle tree. -Because filepack packages are trees of directories, they are composable. A -filepack package may contain other packages, with the directory entry of each +Because Filepack packages are trees of directories, they are composable. A +Filepack package may contain other packages, with the directory entry of each subpackage containing the subpackage fingerprint. 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 +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. diff --git a/book/src/quickstart.md b/book/src/quickstart.md index 3dc92aa0..1292d1e3 100644 --- a/book/src/quickstart.md +++ b/book/src/quickstart.md @@ -70,7 +70,7 @@ filesystems; quality issues, like inclusion of junk files; and metadata issues, like missing or incomplete metadata. Creating a package with all lints enabled and fixing them is a great way to -learn more about filepack and package metadata. +learn more about Filepack and package metadata. Verifying Packages ------------------ diff --git a/book/src/server.md b/book/src/server.md index 45397e23..50c1e947 100644 --- a/book/src/server.md +++ b/book/src/server.md @@ -17,7 +17,7 @@ convenient shortcuts. Authorization ------------- -By default, the filepack server does not require authorization. Anyone can +By default, the Filepack server does not require authorization. Anyone can upload, download, and browse packages. Running `filepack serve` without any flags listens on port 80 on all interfaces, not just localhost. diff --git a/crates/generate/templates/authoring-metadata.md b/crates/generate/templates/authoring-metadata.md index 4e38a5ce..2ddfe562 100644 --- a/crates/generate/templates/authoring-metadata.md +++ b/crates/generate/templates/authoring-metadata.md @@ -13,7 +13,7 @@ See the schema of `metadata.yaml` in [Metadata](yaml/metadata.md), and an example below. The `media` field may optionally contain metadata describing the package media. -Packages with `media` metadata are displayed by the filepack server with the +Packages with `media` metadata are displayed by the Filepack server with the ability to browse and play the audio, image, or video items that they contain. See [Media Formats](media-formats.md) for supported media item file formats. @@ -28,7 +28,7 @@ package, with the required entry point `static/index.html`. The `homepage` URLs are of course anachronistic, as the World Wide Web was created in 1989, some years after Egon first packaged Tobin's Spirit Guide for -filepack. +Filepack. %% for variant in &self.example.variants { diff --git a/crates/generate/templates/deco.md b/crates/generate/templates/deco.md index f6d6894a..2cff89e9 100644 --- a/crates/generate/templates/deco.md +++ b/crates/generate/templates/deco.md @@ -14,7 +14,7 @@ type. Deco is mostly canonical. With some exceptions, there is only one way to serialize a given value. Types which are designed to be extended are not guaranteed to have a canonical serialization, since they must accept and ignore -data produced by newer versions of filepack. +data produced by newer versions of Filepack. Byte Strings ------------ diff --git a/crates/generate/templates/json.md b/crates/generate/templates/json.md index f2806f5d..c91eb4cb 100644 --- a/crates/generate/templates/json.md +++ b/crates/generate/templates/json.md @@ -2,7 +2,7 @@ JSON ==== Filepack uses JSON for command input and output. This chapter includes the -schemas of all filepack types which have JSON representations, including +schemas of all Filepack types which have JSON representations, including [Manifest](json/manifest.md), which is read by `filepack archive` and written by `filepack manifest`. diff --git a/crates/generate/templates/routes.md b/crates/generate/templates/routes.md index b1bcdcdd..cdda21ef 100644 --- a/crates/generate/templates/routes.md +++ b/crates/generate/templates/routes.md @@ -1,7 +1,7 @@ Routes ====== -The filepack server responds to the following API routes: +The Filepack server responds to the following API routes: | method | path | description | |--------|------|-------------| diff --git a/metadata.yaml b/metadata.yaml index ab0fcf84..151442fe 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -1,4 +1,4 @@ -title: filepack +title: Filepack creator: Casey Rodarmor description: Content-addressed packages. homepage: https://filepack.com diff --git a/src/error.rs b/src/error.rs index 03a25ec3..da6faa0a 100644 --- a/src/error.rs +++ b/src/error.rs @@ -271,7 +271,7 @@ pub enum Error { path: DisplayPath, source: XmpError, }, - #[snafu(display("internal error, this may indicate a bug in filepack: {message}"))] + #[snafu(display("internal error, this may indicate a bug in Filepack: {message}"))] Internal { backtrace: Option, message: String, diff --git a/src/manifest.rs b/src/manifest.rs index b54916a9..7fec9e00 100644 --- a/src/manifest.rs +++ b/src/manifest.rs @@ -12,7 +12,7 @@ pub struct Manifest { /// Signatures over the package fingerprint. #[serde_as(as = "SetPreventDuplicates")] pub signatures: BTreeSet>, - /// Entries in the manifest archive not recognized by this version of filepack. + /// Entries in the manifest archive not recognized by this version of Filepack. #[serde(default, skip_serializing_if = "DirectoryTree::is_empty")] pub unknown: DirectoryTree, } diff --git a/src/subcommand.rs b/src/subcommand.rs index 3cc6161b..e108ede9 100644 --- a/src/subcommand.rs +++ b/src/subcommand.rs @@ -66,15 +66,15 @@ pub(crate) enum Subcommand { Contains(contains::Contains), #[command(about = "Create manifest")] Create(create::Create), - #[command(about = "Delete package from a filepack server")] + #[command(about = "Delete package from a Filepack server")] Delete(delete::Delete), - #[command(about = "Download package or file from a filepack server")] + #[command(about = "Download package or file from a Filepack server")] Download(download::Download), #[command(about = "List manifest files")] Files(files::Files), #[command(about = "Print package fingerprint")] Fingerprint(fingerprint::Fingerprint), - #[command(about = "Delete unreferenced data on a filepack server")] + #[command(about = "Delete unreferenced data on a Filepack server")] Gc(gc::Gc), #[command(about = "Print file hash")] Hash(hash::Hash), @@ -96,7 +96,7 @@ pub(crate) enum Subcommand { Metadata(metadata::Metadata), #[command(about = "Print reference")] Reference, - #[command(about = "Start a filepack server")] + #[command(about = "Start a Filepack server")] Serve(serve::Serve), #[command(about = "Sign manifest")] Sign(sign::Sign), @@ -104,7 +104,7 @@ pub(crate) enum Subcommand { Signatures(signatures::Signatures), #[command(about = "Print manifest totals")] Size(size::Size), - #[command(about = "Upload package or file to a filepack server")] + #[command(about = "Upload package or file to a Filepack server")] Upload(upload::Upload), #[command(about = "Verify manifest")] Verify(verify::Verify), diff --git a/static/install.sh b/static/install.sh index fb8dcbd3..4534eeb9 100755 --- a/static/install.sh +++ b/static/install.sh @@ -12,7 +12,7 @@ fi help() { cat <<'EOF' -Install a binary release of a filepack hosted on GitHub +Install a binary release of filepack hosted on GitHub USAGE: install.sh [options] diff --git a/tests/completions.rs b/tests/completions.rs index 8f346981..64dae3c1 100644 --- a/tests/completions.rs +++ b/tests/completions.rs @@ -34,6 +34,6 @@ fn subcommands() { Test::new() .env("FILEPACK_COMPLETE", "fish") .args(["--", "filepack", "ser"]) - .stdout("serve\tStart a filepack server\n") + .stdout("serve\tStart a Filepack server\n") .success(); } From 8faf6afcf7bff9bb4d382894bae15ea7f103fa2b Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 14:47:11 -0700 Subject: [PATCH 08/10] More fixes --- book/src/packages.md | 51 +++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 29 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index 0be92c32..fabf7b7c 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -16,9 +16,9 @@ Filepack packages may include machine-readable metadata in a file named 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, called the package -root. Serialized directories contain the names, sizes, hashes, and types of -their children, which may be files or subdirectories. +the hash of the serialized root directory of the package. Serialized +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): @@ -32,21 +32,15 @@ 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. -BLAKE3 is itself a Merkle tree hash, whose leaves are the contents of the file -being hashed, broken into 1 KiB chunks. - 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). A client, starting with a package fingerprint, first requests and verifies the -serialized package root directory, followed by each subdirectory, and file. +serialized package root directory, followed by each subdirectory and file. -Because file hashes are Merkle tree roots, files can be streamed and verified -incrementally, with the server providing the client with a compact proof that -downloaded file chunks are included in the BLAKE3 Merkle tree. - -Because Filepack packages are trees of directories, they are composable. A -Filepack package may contain other packages, with the directory entry of each -subpackage containing the subpackage fingerprint. +BLAKE3 is itself a Merkle tree hash, whose leaves are the contents of the file +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 @@ -67,10 +61,10 @@ the schemas of all types serialized as deco. A package fingerprint is the BLAKE3 hash of the deco-encoded package root [directory](deco/directory.md), containing [entries](deco/entry.md) for each -child. Each entry contains the hash, name, and size of the child, along with -its [type and additional info](deco/entry-info.md). For directories, this -additional info includes [totals](deco/totals.md), the total number of files -and subdirectories, as well as their aggregate sizes. +child. Directories map child names to entries containing the hash and size of +the child, along with its [type and additional info](deco/entry-info.md). For +directories, this additional info includes [totals](deco/totals.md), the total +number of files and subdirectories, as well as their aggregate sizes. Filepack uses three other serialization formats, aside from deco: @@ -87,9 +81,8 @@ Filepack uses three other serialization formats, aside from deco: Manifests --------- -Manifests are serialized with [deco](deco.md), a compact, binary serialization -format, and stored in a file named `manifest.filepack` in the package root -directory. +Manifests are serialized with [deco](deco.md) and stored in a file named +`manifest.filepack` in the package root directory. A `manifest.filepack` file is called a manifest archive, and is a content-addressed format, containing a root hash, which is not the package @@ -105,17 +98,17 @@ The manifest archive root directory contains two subdirectories, `package` and `signatures`. The `package` directory is the package root, and the `signatures` directory -contains signatures over the package root. Each signature is stored as a file -whose name is the hash of the serialized signature. +contains signatures over the package fingerprint. Each signature is stored as a +file whose name is the hash of the serialized signature. All other entry names are reserved for use by future versions of Filepack. Unrecognized entries in the manifest archive root are ignored but preserved. -Manifest archives do not contain package files, only serialized directories. -The only exception to this is `metadata.filemeta`, which is included in the -archive if present. This allows the manifest archive to serve as a convenient, -single-file reference for a package, including both file hashes and sizes, as -well as metadata. +Manifest archives do not contain package files, only serialized directories and +signatures. The only exception to this is `metadata.filemeta`, which is +included in the archive if present. This allows the manifest archive to serve +as a convenient, single-file reference for a package, including both file +hashes and sizes, as well as signatures and metadata. Manifests can be converted to JSON with `filepack manifest` for inspection and manipulation. A JSON manifest can be converted to a deco manifest archive with @@ -185,7 +178,7 @@ consumption by scripts and tools, `filepack metadata` prints the contents of Metadata follows a fixed schema and is not user-extensible, with fields describing the package contents, the package itself, and the media content of -the package. Future versions of `filepack` may define new metadata fields, +the package. Future versions of Filepack may define new metadata fields, causing verification errors if those fields are present and invalid according to the new schema. From 6f4b39e5c72333a5e5805c620a56ae907a8a1bed Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 15:14:06 -0700 Subject: [PATCH 09/10] Amend --- README.md | 10 ++++++---- book/src/introduction.md | 7 ++++--- book/src/packages.md | 29 +++++++++++++++-------------- 3 files changed, 25 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4d9e3856..2ee8bf44 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,12 @@ may change at any time. Documentation is available at [filepack.com/book/](https://filepack.com/book/). -See [installation](https://filepack.com/book/installation.html) and -[quickstart](https://filepack.com/book/quickstart.html) to get started, and -[Why is metadata important?](https://filepack.com/book/why-metadata.html) for -some of the higher-level ideas behind Filepack. +See [Installation](https://filepack.com/book/installation.html) and +[Quickstart](https://filepack.com/book/quickstart.html) to get started, +[Packages](https://filepack.com/book/packages.html) for an overview of Filepack +packages, and [Why is metadata +important?](https://filepack.com/book/why-metadata.html) for some of the +higher-level ideas behind Filepack. Lints ----- diff --git a/book/src/introduction.md b/book/src/introduction.md index e5d0203a..4c88951a 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -3,9 +3,10 @@ Introduction {{#include ../../README.md:introduction}} -See [installation](installation.md) to get started and [Why is metadata -important?](why-metadata.md) for some of the higher-level ideas behind -Filepack. +See [Installation](installation.md) and [Quickstart](quickstart.md) to get +started, [Packages](packages.md) for an overview of Filepack packages, and [Why +is metadata important?](why-metadata.md) for some of the higher-level ideas +behind Filepack. Why Filepack? ------------- diff --git a/book/src/packages.md b/book/src/packages.md index fabf7b7c..25914eb9 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -53,8 +53,8 @@ Serialization ------------- Package directories, `manifest.filepack` manifests, and `metadata.filemeta` -metadata are serialized as deco, a compact, canonical, schema-driven binary -serialization format. +metadata are serialized as deco, a compact, mostly canonical, schema-driven +binary serialization format. The [deco](deco.md) chapter includes a description of deco itself, as well as the schemas of all types serialized as deco. @@ -69,7 +69,7 @@ number of files and subdirectories, as well as their aggregate sizes. Filepack uses three other serialization formats, aside from deco: - [Tagged hex](hex.md), a text format wrapping a hex-encoded deco payload. Used - for fingerprints, hashes, public keys, private keys, and signatures. + for display of things like hashes, keys, and signatures. - [YAML](yaml.md), a human-readable and writable text format, used for hand-authored files, namely `metadata.yaml`, the template from which a @@ -81,14 +81,12 @@ Filepack uses three other serialization formats, aside from deco: Manifests --------- -Manifests are serialized with [deco](deco.md) and stored in a file named -`manifest.filepack` in the package root directory. +Manifests are serialized with [deco](deco.md) as a manifest +[archive](deco/archive.md) named named `manifest.filepack` in the package root. -A `manifest.filepack` file is called a manifest archive, and is a -content-addressed format, containing a root hash, which is not the package -fingerprint, but instead the hash of an intermediate directory, and a map of -hashes to file contents. See [Archive](deco/archive.md) for the manifest -archive schema. +Archives are a content-addressed storage format, containing the hash of of an +intermediate directory containing the package root directory and a map of +hashes to file contents. The manifest can be traversed by reading the root hash, reading the entry for the root hash in the files map, deserializing the contents as a [deco @@ -144,6 +142,13 @@ The signature is made over the BLAKE3 hash of a deco-encoded domain separation by committing to the [application](deco/application.md) and [context](deco/context.md). +To verify a signature, the statement is wrapped in an envelope, serialized, +hashed, and the raw Ed25519 signature over the hash is verified against the +public key. + +The fingerprint from the verified signature object can then be used to verify +the package itself. + For transport, the raw Ed25519 signature, statement, and public key are stored in a [signature object](deco/signature-statement.md). @@ -151,10 +156,6 @@ Signatures are serialized as deco and stored as files named after their hash in the manifest archive `signatures` directory, and are represented in text as [tagged hex](hex/signature.md). -To verify a signature, the statement is wrapped in an envelope, serialized, -hashed, and the raw Ed25519 signature over the hash is verified against the -public key. - The same signature scheme, with a different context and inner [Claims](deco/claims.md) object, is used for server authorization bearer tokens. From cd463abb9785494db5fea2e1e3687d26bb464f1c Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Mon, 26 Oct 2026 15:19:46 -0700 Subject: [PATCH 10/10] Tweak --- book/src/packages.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/book/src/packages.md b/book/src/packages.md index 25914eb9..1f501ebf 100644 --- a/book/src/packages.md +++ b/book/src/packages.md @@ -82,14 +82,13 @@ Manifests --------- Manifests are serialized with [deco](deco.md) as a manifest -[archive](deco/archive.md) named named `manifest.filepack` in the package root. +[archive](deco/archive.md) named `manifest.filepack` in the package root. -Archives are a content-addressed storage format, containing the hash of of an -intermediate directory containing the package root directory and a map of -hashes to file contents. +Archives are a content-addressed storage format. They contain the hash of a +root directory and a map of hashes to file contents. -The manifest can be traversed by reading the root hash, reading the entry for -the root hash in the files map, deserializing the contents as a [deco +An archive can be traversed by reading the root hash, reading the entry for the +root hash in the files map, deserializing the contents as a [deco directory](deco/directory.md), and repeating the process for subdirectories. The manifest archive root directory contains two subdirectories, `package` and @@ -97,7 +96,8 @@ The manifest archive root directory contains two subdirectories, `package` and The `package` directory is the package root, and the `signatures` directory contains signatures over the package fingerprint. Each signature is stored as a -file whose name is the hash of the serialized signature. +file whose name is the [tagged hex hash](hex/hash.md) of the serialized +signature. All other entry names are reserved for use by future versions of Filepack. Unrecognized entries in the manifest archive root are ignored but preserved. @@ -144,7 +144,8 @@ domain separation by committing to the [application](deco/application.md) and To verify a signature, the statement is wrapped in an envelope, serialized, hashed, and the raw Ed25519 signature over the hash is verified against the -public key. +public key. Public keys which are non-canonical or small order points are +rejected. The fingerprint from the verified signature object can then be used to verify the package itself.