@tufjs/models 3.0.1: Key, MetaFile, Metadata

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40tufjs/models@3.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40tufjs/models@3.0.1

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c12ccc4003d779a19515204cd55bd4b634fccb8cb4eaf4125a0339960e4b857f","contract":["Root, Targets, Snapshot, and Timestamp metadata models serialize via toJSON() and deserialize via Metadata.fromJSON() with equal inner models.","Root.isExpired(referenceTime) returns false before expires and true after expires.","MetaFile constructor throws ValueError when version \u003c= 0."],"goal":"verify pkg:npm/%40tufjs/models@3.0.1","kind":"HOW","packages":["pkg:npm/%40tufjs/models@3.0.1"],"schemaVersion":1,"symbols":["Key","MetaFile","Metadata","MetadataKind","Root","Snapshot","TargetFile","Targets","Timestamp","ValueError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40tufjs/models@3.0.1"],"schemaVersion":1,"subject":"pkg:npm/%40tufjs/models@3.0.1","symbols":["Key","MetaFile","Metadata","MetadataKind","Root","Snapshot","TargetFile","Targets","Timestamp","ValueError"],"verifierAdapter":"node-typescript@1"}

import {
  Key,
  Metadata,
  MetadataKind,
  MetaFile,
  Root,
  Snapshot,
  TargetFile,
  Targets,
  Timestamp,
  ValueError,
} from "@tufjs/models";

export function buildAndRoundtripMetadata() {
  const key = new Key({
    keyID: "a1b2c3d4",
    keyType: "ed25519",
    scheme: "ed25519",
    keyVal: { public: "0123456789abcdef" },
  });

  const root = new Root({
    version: 1,
    specVersion: "1.0.0",
    expires: "2030-01-01T00:00:00Z",
    consistentSnapshot: true,
  });
  root.addKey(key, "root");
  root.addKey(key, "targets");
  root.addKey(key, "snapshot");
  root.addKey(key, "timestamp");

  const rootMetadata = new Metadata(root);
  const rootJson = rootMetadata.toJSON();
  const parsedRoot = Metadata.fromJSON(MetadataKind.Root, rootJson);
  const parsedRootAgain = Metadata.fromJSON(MetadataKind.Root, parsedRoot.toJSON());

  const targetFile = new TargetFile({
    length: 11,
    path: "artifact.txt",
    hashes: { sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" },
  });
  const targets = new Targets({
    version: 1,
    specVersion: "1.0.0",
    expires: "2030-01-01T00:00:00Z",
  });
  targets.addTarget(targetFile);
  const targetsMetadata = new Metadata(targets);
  const parsedTargets = Metadata.fromJSON(
    MetadataKind.Targets,
    targetsMetadata.toJSON()
  );

  const metaFile = new MetaFile({
    version: 1,
    length: 128,
    hashes: { sha256: "abcdef0123456789" },
  });
  const snapshot = new Snapshot({
    version: 1,
    specVersion: "1.0.0",
    expires: "2030-01-01T00:00:00Z",
    meta: { "targets.json": metaFile },
  });
  const snapshotMetadata = new Metadata(snapshot);
  const parsedSnapshot = Metadata.fromJSON(
    MetadataKind.Snapshot,
    snapshotMetadata.toJSON()
  );

  const timestamp = new Timestamp({
    version: 1,
    specVersion: "1.0.0",
    expires: "2030-01-01T00:00:00Z",
    snapshotMeta: metaFile,
  });
  const timestampMetadata = new Metadata(timestamp);
  const parsedTimestamp = Metadata.fromJSON(
    MetadataKind.Timestamp,
    timestampMetadata.toJSON()
  );

  return {
    rootJson,
    parsedRootJson: parsedRoot.toJSON(),
    parsedRootEqual: parsedRoot.equals(parsedRootAgain),
    keyEqual: key.equals(parsedRoot.signed.keys["a1b2c3d4"]),
    targetEqual: targetFile.equals(parsedTargets.signed.targets["artifact.txt"]),
    metaEqual: metaFile.equals(parsedSnapshot.signed.meta["targets.json"]),
    timestampMetaEqual: metaFile.equals(parsedTimestamp.signed.snapshotMeta),
    isExpiredPast: root.isExpired(new Date("2025-01-01T00:00:00Z")),
    isExpiredFuture: root.isExpired(new Date("2035-01-01T00:00:00Z")),
    ValueError,
  };
}

{
  "name": "sample-tufjs-models",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tufjs-models",
      "version": "1.0.0",
      "dependencies": {
        "@tufjs/models": "3.0.1"
      }
    },
    "node_modules/@tufjs/canonical-json": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/@tufjs/canonical-json/-/canonical-json-2.0.0.tgz",
      "integrity": "sha512-yVtV8zsdo8qFHe+/3kw81dSLyF7D576A5cCFCi4X7B39tWT7SekaEFUnvnWJHz+9qO7qJTah1JbrDjWKqFtdWA==",
      "license": "MIT",
      "engines": {
        "node": "^16.14.0 || >=18.0.0"
      }
    },
    "node_modules/@tufjs/models": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/@tufjs/models/-/models-3.0.1.tgz",
      "integrity": "sha512-UUYHISyhCU3ZgN8yaear3cGATHb3SMuKHsQ/nVbHXcmnBf+LzQ/cQfhNG+rfaSHgqGKNEm2cOCLVLELStUQ1JA==",
      "license": "MIT",
      "dependencies": {
        "@tufjs/canonical-json": "2.0.0",
        "minimatch": "^9.0.5"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/balanced-match": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
      "license": "MIT"
    },
    "node_modules/brace-expansion": {
      "version": "2.1.7",
      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.7.tgz",
      "integrity": "sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==",
      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0"
      }
    },
    "node_modules/minimatch": {
      "version": "9.0.9",
      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
      "license": "ISC",
      "dependencies": {
        "brace-expansion": "^2.0.2"
      },
      "engines": {
        "node": ">=16 || 14 >=14.17"
      },
      "funding": {
        "url": "https://github.com/sponsors/isaacs"
      }
    }
  }
}

{
  "name": "sample-tufjs-models",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@tufjs/models": "3.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40tufjs/models@3.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40tufjs/models@3.0.1"
  ]
}

import assert from "node:assert/strict";
import { MetaFile, ValueError } from "@tufjs/models";
import { buildAndRoundtripMetadata } from "../index.mjs";

const res = buildAndRoundtripMetadata();

assert.deepStrictEqual(res.rootJson, res.parsedRootJson, "Root JSON should match after roundtrip");
assert.equal(res.parsedRootEqual, true, "Parsed Root Metadata should equal re-parsed Root Metadata");
assert.equal(res.keyEqual, true, "Key should roundtrip through Root JSON");
assert.equal(res.targetEqual, true, "TargetFile should roundtrip through Targets JSON");
assert.equal(res.metaEqual, true, "MetaFile should roundtrip through Snapshot JSON");
assert.equal(res.timestampMetaEqual, true, "MetaFile should roundtrip through Timestamp JSON");
assert.equal(res.isExpiredPast, false, "Should not be expired before expiry date");
assert.equal(res.isExpiredFuture, true, "Should be expired after expiry date");

const buf = Buffer.from("hello world", "utf8");
const meta = new MetaFile({
  version: 1,
  length: buf.length,
});
meta.verify(buf);

assert.throws(
  () => new MetaFile({ version: 0 }),
  ValueError,
  "MetaFile constructor should throw ValueError when version <= 0"
);