TUF JavaScript Client

5.0.1 · active · verified Sun Apr 19

tuf-js is a robust JavaScript and TypeScript implementation of The Update Framework (TUF), providing secure software update mechanisms against various supply chain attacks, including rollback, mix-and-match, and freeze attacks. The package is currently at version 5.0.1 and is actively maintained, demonstrating a consistent release cadence with patches and minor updates, and major versions released to align with Node.js LTS cycles and critical dependency upgrades. It adheres directly to the TUF specification, offering a client-side library for cryptographic signature verification, secure metadata fetching, and managing trust anchors. Key differentiators include its strong focus on security, TypeScript support, and its role as a reference implementation for TUF within the JavaScript ecosystem, ensuring resilient and verifiable software distribution. It is designed for use in environments requiring robust integrity checks for updates, operating on Node.js versions 20.17.0 or higher, or 22.9.0 or higher.

Common errors

Warnings

Install

Imports

Quickstart

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();

view raw JSON →