Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TufClient
✓ import { TufClient } from 'tuf-js'
✗ const { TufClient } = require('tuf-js')
The primary class for interacting with a TUF repository. tuf-js has been ESM-first since v4; CommonJS `require()` is not supported.
RemoteFetcher
✓ import { RemoteFetcher } from 'tuf-js'
✗ import { Fetcher } from 'tuf-js' // Incorrect class name
A concrete implementation of the Fetcher interface, suitable for HTTP(S) network requests. Requires global `fetch` to be available (present in Node.js 18+).
Root
✓ import { Root } from '@tufjs/models'
✗ import { Root } from 'tuf-js' // Root model is in @tufjs/models
The Root metadata model, essential for bootstrapping the TUF client with its initial trust anchor. This type is provided by the `@tufjs/models` package, which is a peer dependency.
InMemoryStorage
✓ import { InMemoryStorage } from '@tufjs/client'
✗ import { InMemoryStorage } from 'tuf-js' // Not exported directly by tuf-js
A simple in-memory implementation of ClientStorage and TargetStorage, typically used for testing or simplified quickstarts. Available from the `@tufjs/client` package, which provides common client utilities.
This quickstart demonstrates how to initialize a `TufClient`, perform a metadata update, and then download a specific target file from a remote TUF repository using in-memory storage for simplicity.
import { TufClient, RemoteFetcher } from 'tuf-js';
import { Root } from '@tufjs/models';
import { InMemoryStorage } from '@tufjs/client'; // Provides simple in-memory storage
async function initializeAndDownloadTarget() {
const repoURL = 'https://example.com/tuf-repo/'; // Replace with your TUF repository base URL
// In a real application, you would bundle a trusted initial root.json.
// This is a minimal placeholder for demonstration purposes.
const initialRootJSON = JSON.stringify({
"_type": "root",
"spec_version": "1.0.0",
"version": 1,
"expires": "2030-01-01T00:00:00Z",
"keys": {},
"roles": {
"root": {"keyids": [], "threshold": 1},
"targets": {"keyids": [], "threshold": 1},
"snapshot": {"keyids": [], "threshold": 1},
"timestamp": {"keyids": [], "threshold": 1}
}
});
// Parse the initial root metadata
const initialRoot = Root.fromJSON(JSON.parse(initialRootJSON));
// Use in-memory storage for this example. In production, use persistent storage.
const client = new TufClient({
repoURL: repoURL,
root: initialRoot,
clientStorage: new InMemoryStorage(),
targetStorage: new InMemoryStorage(),
fetcher: new RemoteFetcher()
});
try {
console.log('Attempting to update TUF metadata...');
await client.update(); // Fetches and verifies the latest metadata
console.log('TUF metadata updated successfully.');
const targetName = 'path/to/my-app-binary-v1.0.0.zip'; // Replace with an actual target path
console.log(`Getting target info for: ${targetName}`);
const targetInfo = await client.getTargetInfo(targetName);
if (targetInfo) {
console.log(`Target '${targetName}' found. Downloading...`);
const targetContent = await client.downloadTarget(targetInfo);
console.log(`Downloaded ${targetContent.length} bytes for '${targetName}'.`);
// Here, targetContent (Uint8Array) can be saved to disk or processed.
} else {
console.log(`Target '${targetName}' not found in the repository.`);
}
} catch (error) {
console.error('TUF client operation failed:', error);
}
}
// To run this, ensure you have a global `fetch` (Node.js 18+ or polyfill)
// and install `@tufjs/client` and `@tufjs/models` alongside `tuf-js`.
initializeAndDownloadTarget();
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to import tuf-js (an ESM-first package) using CommonJS `require()` syntax.
fixMigrate your project to use ES Modules (ESM) syntax (`import ... from 'tuf-js'`) and ensure your Node.js environment or bundler correctly handles ESM.
Error: The client is configured for Node.js version X.Y.Z, which is not supported.
Running tuf-js v4.x or later on an unsupported Node.js version (e.g., Node.js 18 or older).
fixUpgrade your Node.js runtime environment to version 20.17.0, 22.9.0, or newer. Check the `engines` field in `package.json` for exact requirements.
Error: Signature verification failed for role 'root'
The initial `root.json` provided to the `TufClient` is invalid, corrupted, or does not match the repository's actual root metadata, leading to a failure in establishing the initial trust anchor.
fixVerify the `initialRoot` metadata provided to the `TufClient` constructor. Ensure it is the correct, cryptographically valid root metadata for your TUF repository.
Error: Target 'your-target-name' not found in repository metadata.
The specified target file name (`targetName`) does not exist in the latest verified `targets.json` metadata from the TUF repository, or the path is incorrect.
fixConfirm the exact `targetName` by inspecting your TUF repository's `targets.json` or related delegated role metadata. Ensure the target has been published and its metadata is signed and updated in the repository.
Audit
Dependencies
No dependency data recorded yet.