# manifest Writes, reads and checks `hf-release.json`, the release manifest: an index of every file of one built artifact by path, size and SHA-256, under the artifact's name and version. A name and a version can be built twice into different bytes, so the SHA-256 of the manifest file is what identifies the content of a release. This entry reads the disk and hashes with `node:crypto`, so it runs on Node.js only. ```ts import { writeFileSync } from 'node:fs' import { join } from 'node:path' import { RELEASE_MANIFEST_FILENAME, createReleaseManifest, serializeReleaseManifest } from '@hyperfrontend/server/manifest' const root = 'dist/shell' const manifest = createReleaseManifest({ root, name: '@acme/clock-shell', version: '1.4.0', }) writeFileSync(join(root, RELEASE_MANIFEST_FILENAME), serializeReleaseManifest(manifest)) ``` ## Usage [`createReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-createReleaseManifest) indexes every regular file below the root, dotfiles included, and leaves out the manifest file at the root, since a manifest never lists itself. It throws when the directory holds a symbolic link or anything else that is neither a regular file nor a directory, naming each one, the manifest file included, and when it holds no file at all. What it returns has passed the validator. To check a directory against its manifest, parse the file and verify the directory: ```ts import { readFileSync } from 'node:fs' import { join } from 'node:path' import { RELEASE_MANIFEST_FILENAME, parseReleaseManifest, releaseManifestDigest, verifyRelease } from '@hyperfrontend/server/manifest' const root = 'node_modules/@acme/clock-shell' const source = join(root, RELEASE_MANIFEST_FILENAME) const bytes = readFileSync(source) const digest = releaseManifestDigest(bytes) const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) const issues = verifyRelease(root, parseReleaseManifest(text, source)) // [] when the directory holds exactly the listed bytes and nothing else ``` Decode the file strictly, as above: a decoder that replaces a malformed byte or drops a byte order mark gives one text for several byte sequences, and the digest is of the bytes. A manifest is not a signature. Whoever can replace a file of the directory can replace the manifest beside it, so an empty result says only that the directory agrees with the manifest it carries. To pin a release, compare the digest with one obtained from somewhere you trust: [`verifyRelease`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-verifyRelease) does not check it. Two parts of the workspace rely on the file. `hf build` in [`@hyperfrontend/features`](https://www.hyperfrontend.dev/docs/libraries/features.md) writes one into every shell it builds, and lists it in the package's files so it is published with them. [`runService`](https://www.hyperfrontend.dev/docs/libraries/server/#api-runService) reads the one beside a built service's main before the service starts: it requires the canonical form, verifies the directory, refuses to boot on any issue, and prints the digest in its started line. The three file-system operations are replaceable through [`ReleaseFileSystem`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseFileSystem), which is how a spec runs either function over a directory that exists only in memory. A replacement for its [`list`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseFileSystem-prop-list) answers one [`ReleaseEntry`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseEntry) for each entry below the root that is no directory: the path below the root, written with the separators of the platform, and whether a regular file is there. ## Format ```json { "schema": 1, "name": "@acme/clock-shell", "version": "1.4.0", "files": [ { "path": "index.mjs", "size": 3, "sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" } ] } ``` | Member | Rule | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | [`schema`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseManifest-prop-schema) | The number 1. A reader that meets any other value reports that alone, because nothing else can be judged under unknown rules | | [`name`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseManifest-prop-name) | The artifact's own name, for a shell its package name: non-empty text with no whitespace, control character or U+FFFD | | [`version`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseManifest-prop-version) | A semantic version, 2.0.0 grammar, with no leading `v` | | [`files`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-ReleaseManifest-prop-files) | At least one entry, in ascending order of path compared code point by code point, so no path repeats | | `files[].path` | Relative to the manifest's directory and separated by `/`, with no empty, `.` or `..` segment, backslash, control character or U+FFFD | | `files[].size` | The length in bytes, a whole number from 0 to 9007199254740991 | | `files[].sha256` | The SHA-256 of the bytes, as 64 lowercase hexadecimal characters | The member sets are exact: a manifest or a file entry that holds any other member is refused. Paths are compared as written, with no case folding and no Unicode normalisation. The path `hf-release.json` at the root is reserved and never listed. U+FFFD is what a lossy decoder leaves of a malformed byte, so a file whose name on disk is not valid UTF-8 cannot be listed: indexing a directory that holds one fails, and verification reports it as unlisted. Each file is read whole to be hashed, so a release cannot hold a file of 2 GiB or more, whatever size an entry could state: indexing and verifying such a file both throw. The file has one canonical form: UTF-8 with no byte order mark, holding exactly what `JSON.stringify(manifest, null, 2)` writes with the members in the order above, closed by one line feed. [`serializeReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-serializeReleaseManifest) writes it and [`parseReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-parseReleaseManifest) refuses any other spelling of the same content, such as other spacing, another member order, a repeated key or `3.0` for `3`. One content therefore has one byte sequence, and one digest. ## Problems [`checkReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-checkReleaseManifest) returns every problem of a value at once, each with a stable code, the place it was found and a full sentence. [`validateReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-validateReleaseManifest) and [`parseReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-parseReleaseManifest) throw them as one error: the path of the source file, then a line per problem. No message repeats a value or a key of the file, since both are text the author of an untrusted file chose. A member the schema does not define is reported by the object that holds it, once, however many such members there are. | Code | Reported when | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `manifest-not-json` | The text is not JSON; reported alone, by [`parseReleaseManifest`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-parseReleaseManifest) only | | `manifest-not-object` | The value is no object; reported alone | | `schema-missing` | The schema member is absent; reported alone | | `schema-unsupported` | The schema number is anything but 1; reported alone | | `member-unknown` | The manifest or a file entry holds a member schema 1 does not define | | `name-invalid` | The name breaks its rule or is absent | | `version-invalid` | The version breaks its rule or is absent | | `files-not-array` | The file list is no array or is absent | | `files-empty` | The file list is empty | | `file-not-object` | An entry of the file list is no object | | `file-path-invalid` | A path breaks its rule or is absent | | `file-path-reserved` | A path names the manifest itself | | `file-path-order` | A path does not sort after the well-formed path before it | | `file-size-invalid` | A size breaks its rule or is absent | | `file-sha256-invalid` | A digest breaks its rule or is absent | | `manifest-not-canonical` | The content is sound and the text is not its canonical form; by parsing only | After a malformed path the order comparison starts again, so one bad path is reported once and not again for the entry that follows it. ## Verification [`verifyRelease`](https://www.hyperfrontend.dev/docs/libraries/server/manifest/#api-verifyRelease) has no lenient mode. It reports a manifest file at the root that is no regular file, checks each listed file in manifest order and reports it at most once, then reports every other entry below the root, in code point order. | Code | Reported when | | ---------------------- | --------------------------------------------------------------------------------------------------------- | | `manifest-not-file` | The entry `hf-release.json` at the root is a symbolic link or anything else that is no regular file | | `file-missing` | No regular file is at a listed path: nothing, a directory, or a symbolic link, which is not followed | | `file-size-mismatch` | The file's size differs from the listed one; the file is not read | | `file-sha256-mismatch` | The size agrees and the bytes hash to another digest | | `file-unlisted` | An entry below the root is not listed; the manifest file at the root is the one entry that is not counted | The message of an unlisted entry opens with its path as it is when a manifest could list that path, and otherwise with the path as a quoted string in which every control character is escaped, so a name from disk never starts a line of its own. The `path` member holds the name unchanged. A failure to read the disk is thrown, never turned into a verdict, and so is a manifest that does not pass the validator, before the disk is touched. A symbolic link to a directory is an entry of its own and is reported as unlisted, whatever lies behind it. A directory that holds nothing is not an entry, so an empty directory beside the listed files changes no result. ## API Reference ### Functions #### checkReleaseManifest ```typescript function checkReleaseManifest(value: unknown): unknown ``` Collects every problem of an unknown value as a ReleaseManifest, where validateReleaseManifest throws them. A value that is no object, a missing schema and a schema other than 1 are each reported alone, because nothing else can be judged under unknown rules. Otherwise every problem is reported, in the order the schema lists the members. No message repeats a value or a key of the document. **Parameters** | Name | Type | Description | | --- | --- | --- | | `value` | `unknown` | The parsed content of a manifest file. | **Returns** `unknown`: The problems, each with a stable code, a path and a full sentence; empty when the manifest is sound. **Example: Listing what a tool should report about a manifest** ```typescript checkReleaseManifest({ schema: 1, name: 'clock-shell', version: 'v1.0.0', files: [] }).map((issue) => issue.message) // => ['version must be a semantic version such as 1.2.3, with no leading "v".', 'files must list at least one file.'] ``` #### createReleaseManifest ```typescript function createReleaseManifest(input: CreateReleaseManifestInput, fileSystem?: ReleaseFileSystem): ReleaseManifest ``` Indexes a directory as a release: every regular file below it, dotfiles included, with its size and SHA-256. The manifest file at the root is left out, since a manifest never lists itself. Each file is read once and whole, so a file of 2 GiB or more cannot be indexed, and its size is the length of the bytes read. The result has passed validateReleaseManifest, so it is ready for `serializeReleaseManifest`. **Parameters** | Name | Type | Description | | --- | --- | --- | | `input` | `CreateReleaseManifestInput` | The directory to index and the identity to stamp on the manifest. | | `fileSystem?` | `ReleaseFileSystem` | Replacements for the listing and the read; the disk when left out. | **Returns** `ReleaseManifest`: The manifest, its files in ascending code point order of their paths. **Example: Writing the manifest of a built package** ```typescript import { writeFileSync } from 'node:fs' import { join } from 'node:path' import { RELEASE_MANIFEST_FILENAME, createReleaseManifest, serializeReleaseManifest } from '@hyperfrontend/server/manifest' const manifest = createReleaseManifest({ root: 'dist/shell', name: '@acme/clock-shell', version: '1.4.0' }) writeFileSync(join('dist/shell', RELEASE_MANIFEST_FILENAME), serializeReleaseManifest(manifest)) ``` #### parseReleaseManifest ```typescript function parseReleaseManifest(text: string, sourcePath: string): ReleaseManifest ``` Parses the text of an `hf-release.json` file into a validated ReleaseManifest. A file is valid only in canonical form, so one content has one byte sequence: text that parses to a sound manifest but differs from serializeReleaseManifest of that manifest is refused. That covers other spacing, another member order, a repeated key and another spelling of a number. **Parameters** | Name | Type | Description | | --- | --- | --- | | `text` | `string` | The content of the file, decoded as UTF-8 by a decoder that refuses a malformed sequence and keeps a byte order mark, so that no two byte sequences give one text. | | `sourcePath` | `string` | The file the text came from, used to open the error message. | **Returns** `ReleaseManifest`: The validated content of the file. **Example: Reading a manifest from disk** ```typescript import { readFileSync } from 'node:fs' const strict = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }) const manifest = parseReleaseManifest(strict.decode(readFileSync('shell/hf-release.json')), 'shell/hf-release.json') ``` #### releaseManifestDigest ```typescript function releaseManifestDigest(serialized: string | Uint8Array): string ``` Computes the digest that identifies a release manifest: the SHA-256 of the bytes of its file. A manifest file is valid only in canonical form, so the digest of a file equals the digest of the serialisation of its content, and one manifest content has one digest. Name and version do not identify the bytes of an artifact; this digest does. **Parameters** | Name | Type | Description | | --- | --- | --- | | `serialized` | `string \| Uint8Array` | The bytes of an `hf-release.json` file, or its text, which is hashed as UTF-8. | **Returns** `string`: The digest as 64 lowercase hexadecimal characters. **Example: Pinning a release by the digest of its manifest** ```typescript import { createReleaseManifest, releaseManifestDigest, serializeReleaseManifest } from '@hyperfrontend/server/manifest' const manifest = createReleaseManifest({ root: 'dist/shell', name: '@acme/clock-shell', version: '1.4.0' }) const digest = releaseManifestDigest(serializeReleaseManifest(manifest)) ``` #### serializeReleaseManifest ```typescript function serializeReleaseManifest(manifest: ReleaseManifest): string ``` Writes a manifest in its one canonical form: two-space JSON with the members in schema order, closed by one line feed. The UTF-8 encoding of the result is what `hf-release.json` holds. A member the schema does not define is left out. **Parameters** | Name | Type | Description | | --- | --- | --- | | `manifest` | `ReleaseManifest` | The manifest to write. | **Returns** `string`: The text of the manifest file. **Example: Writing the text of a manifest file** ```typescript const files = [{ path: 'package.json', size: 505, sha256: 'c21e68ff1da3dac9ce83d330899a9513b1c8f52670bd880af3c00d23877a5889' }] serializeReleaseManifest({ schema: 1, name: 'clock-shell', version: '0.3.0', files }) // => '{\n "schema": 1,\n "name": "clock-shell",\n ... }\n' ``` #### validateReleaseManifest ```typescript function validateReleaseManifest(value: unknown, sourcePath: string): ReleaseManifest ``` Validates an unknown value as a ReleaseManifest. **Parameters** | Name | Type | Description | | --- | --- | --- | | `value` | `unknown` | The parsed content of a manifest file. | | `sourcePath` | `string` | The file the content came from, used to open the error message. | **Returns** `ReleaseManifest`: The same value, typed as a manifest. **Example: Validating a manifest built in memory** ```typescript const files = [{ path: 'package.json', size: 505, sha256: 'c21e68ff1da3dac9ce83d330899a9513b1c8f52670bd880af3c00d23877a5889' }] validateReleaseManifest({ schema: 1, name: 'clock-shell', version: '0.3.0', files }, 'shell/hf-release.json') ``` #### verifyRelease ```typescript function verifyRelease(root: string, manifest: ReleaseManifest, fileSystem?: ReleaseFileSystem): unknown ``` Compares a directory with a release manifest, exactly: an empty result means the directory holds the listed bytes and nothing else. A manifest file at the root that is no regular file is reported first. Each listed file is then checked in manifest order, and reported at most once: as missing when no regular file is at its path, by size without being read, or by its SHA-256. A symbolic link at a listed path is not followed: it is a missing file. Every other entry below the root, the manifest file at the root excepted, is then reported as unlisted, in code point order; a symbolic link to a directory is such an entry, whatever lies behind it. A name that is not valid UTF-8 is never a listed one. A file whose size matches is read whole, so a release cannot hold a file of 2 GiB or more. The digest of the manifest itself is not checked: a caller that pins a release compares `releaseManifestDigest` of the file with the digest it trusts before relying on this result. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The directory the manifest describes. | | `manifest` | `ReleaseManifest` | The manifest to hold the directory to. | | `fileSystem?` | `ReleaseFileSystem` | Replacements for the listing, the read and the size lookup; the disk when left out. | **Returns** `unknown`: The differences found; empty when there are none. **Example: Verifying an installed package against its manifest** ```typescript import { readFileSync } from 'node:fs' import { join } from 'node:path' import { RELEASE_MANIFEST_FILENAME, parseReleaseManifest, verifyRelease } from '@hyperfrontend/server/manifest' const root = 'node_modules/@acme/clock-shell' const source = join(root, RELEASE_MANIFEST_FILENAME) const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(readFileSync(source)) const issues = verifyRelease(root, parseReleaseManifest(text, source)) // => [] when the package holds exactly the listed bytes ``` ### Interfaces #### CreateReleaseManifestInput What a release manifest is made from. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly root` | `string` | The directory to index, which is the directory the manifest file belongs in. | | `readonly name` | `string` | The artifact's own name; for a shell, its package name. | | `readonly version` | `string` | The artifact's version, canonical semver 2.0.0, no leading "v". | #### ReleaseEntry One entry found below the root of a release. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly path` | `string` | Path relative to the root, with the separators of the platform. | | `readonly kind` | `"file" \| "other"` | `file` for a regular file; `other` for anything else that is no directory, a symbolic link included. | #### ReleaseFile One file of a release. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly path` | `string` | Path relative to the manifest's directory, "/" separated. | | `readonly size` | `number` | Length in bytes. | | `readonly sha256` | `string` | SHA-256 of the bytes: 64 lowercase hexadecimal characters. | #### ReleaseFileSystem The file system a release is read through. A function left out is the one that reads the disk, so a spec replaces only what it observes. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly list?` | `(root: string) => unknown` | Lists every entry below a root that is no directory, descending into directories and following no symbolic link. | | `readonly read?` | `(path: string) => Uint8Array` | Reads the bytes of the file at a path, which is the root joined with an entry's path by the platform's separator. | | `readonly size?` | `(path: string) => number` | Answers the size in bytes of the regular file at such a path, following no symbolic link, or `null` when no regular file is there. | #### ReleaseManifest Schema 1 of `hf-release.json`: an index of the bytes of one artifact. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly schema` | `1` | The number of the schema the manifest is written in. | | `readonly name` | `string` | The artifact's own name; for a shell, its package name. | | `readonly version` | `string` | The artifact's version, canonical semver 2.0.0, no leading "v". | | `readonly files` | `unknown` | Every regular file under the manifest's directory except the manifest. | #### ReleaseManifestIssue One problem found in a release manifest, located and worded without repeating any value or key of the file. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly code` | `ReleaseManifestIssueCode` | The kind of problem. | | `readonly path` | `string` | Where the problem sits, such as `files[2].path`; empty when the manifest as a whole is at fault. | | `readonly message` | `string` | The whole sentence a tool prints, which names the place itself. | #### ReleaseVerificationIssue One difference between a directory and the manifest that describes it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly code` | `"manifest-not-file" \| "file-missing" \| "file-size-mismatch" \| "file-sha256-mismatch" \| "file-unlisted"` | The kind of difference, stable across releases so a tool can branch on it. | | `readonly path` | `string` | The path of the file below the root, "/" separated, as the disk gave it: unlike the message, it is not quoted. | | `readonly message` | `string` | The whole sentence a tool prints, which opens with the path, quoted when it is one no manifest can list. | ### Types #### ReleaseManifestIssueCode What kind of problem a ReleaseManifestIssue reports, stable across releases so a tool can branch on it. ```typescript type ReleaseManifestIssueCode = "manifest-not-json" | "manifest-not-object" | "schema-missing" | "schema-unsupported" | "member-unknown" | "name-invalid" | "version-invalid" | "files-not-array" | "files-empty" | "file-not-object" | "file-path-invalid" | "file-path-reserved" | "file-path-order" | "file-size-invalid" | "file-sha256-invalid" | "manifest-not-canonical" ``` ### Variables #### RELEASE_MANIFEST_FILENAME File name of a release manifest, at the root of the artifact it describes. ```typescript const RELEASE_MANIFEST_FILENAME: "hf-release.json" ``` **Value** `'hf-release.json'` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/server/manifest/ This file: https://www.hyperfrontend.dev/docs/libraries/server/manifest.md Documentation index: https://www.hyperfrontend.dev/llms.txt