Add the require-checksums input (#1139)

Adds `require-checksums`, which enforces the "intrinsic or explicitly
provided checksum" idea. See #1032.

<details>
<summary>Automated notes</summary>

Add the opt-in input `require-checksums`. When enabled, setup-uv
verifies the archive against the workflow's `checksum` input or the
digest bundled for the resolved uv version, architecture, and platform.
If neither is available, setup fails before downloading the archive. By
default, setup-uv continues to accept manifest checksums as it does
today.

The setting also applies to custom manifests, which can still supply
download URLs. On persistent runners, strict mode keys tool-cache
entries by the expected archive digest so a previous manifest-verified
installation cannot bypass the check.

Closes #1032. Builds on #1033.

## Validation

- `npm ci --ignore-scripts` and `npm run all` passed under Node 24 (182
tests).
- The packaged-action regression test installs a custom build into a
temporary runner tool cache. It checks that strict mode rejects a
manifest-only version even with a warm cache, reuses a verified
installation for the same digest, and rejects a changed digest or a
custom build that conflicts with the bundled digest.

</details>

---------

Signed-off-by: William Woodruff <william@yossarian.net>
This commit is contained in:
William Woodruff authored and GitHub committed 2026-11-16 22:24:53 +01:00
1 parent fc0acc2d6f
commit de938e707d
16 files changed
+235 -43

No files matched your search

+1 -5
View File
@@ -23,11 +23,7 @@ export async function validateChecksum(
: (knownChecksum ?? (hasManifestChecksum ? manifestChecksum : undefined));
if (checksumToUse === undefined) {
if (manifestChecksum !== undefined) {
throw new Error(`No checksum found for ${key} in manifest.`);
}
core.debug(`No checksum found for ${key}.`);
return;
throw new Error(`No checksum found for ${key} in manifest.`);
}
const checksumSource = hasProvidedChecksum
+25 -8
View File
@@ -11,22 +11,40 @@ import {
import * as log from "../utils/logging";
import type { Architecture, Platform } from "../utils/platforms";
import { validateChecksum } from "./checksum/checksum";
import { KNOWN_CHECKSUMS } from "./checksum/known-checksums";
import { getArtifact } from "./manifest";
export { resolveVersion } from "../version/resolve";
export function getIntrinsicChecksum(
key: string,
providedChecksum: string,
): string {
const checksum = providedChecksum || KNOWN_CHECKSUMS[key];
if (!checksum) {
throw new Error(
`No bundled checksum for ${key}. With require-checksums enabled, update setup-uv or provide the checksum input for this archive.`,
);
}
if (!/^[a-f0-9]{64}$/.test(checksum)) {
throw new Error(`Expected a SHA-256 checksum for ${key}.`);
}
return checksum;
}
export function tryGetFromToolCache(
arch: Architecture,
version: string,
toolCacheName = TOOL_CACHE_NAME,
): { version: string; installedPath: string | undefined } {
core.debug(`Trying to get uv from tool cache for ${version}...`);
const cachedVersions = tc.findAllVersions(TOOL_CACHE_NAME, arch);
const cachedVersions = tc.findAllVersions(toolCacheName, arch);
core.debug(`Cached versions: ${cachedVersions}`);
let resolvedVersion = tc.evaluateVersions(cachedVersions, version);
if (resolvedVersion === "") {
resolvedVersion = version;
}
const installedPath = tc.find(TOOL_CACHE_NAME, resolvedVersion, arch);
const installedPath = tc.find(toolCacheName, resolvedVersion, arch);
return { installedPath, version: resolvedVersion };
}
@@ -38,6 +56,7 @@ export async function downloadVersion(
githubToken: string,
manifestUrl?: string,
downloadFromAstralMirror = true,
toolCacheName = TOOL_CACHE_NAME,
): Promise<{ version: string; cachedToolDir: string }> {
const artifact = await getArtifact(version, arch, platform, manifestUrl);
@@ -71,6 +90,7 @@ export async function downloadVersion(
resolvedChecksum,
manifestChecksum,
githubTokenForUrl(downloadUrl, githubToken),
toolCacheName,
);
} catch (err) {
if (mirrorUrl === undefined) {
@@ -90,6 +110,7 @@ export async function downloadVersion(
resolvedChecksum,
manifestChecksum,
githubTokenForUrl(artifact.downloadUrl, githubToken),
toolCacheName,
);
}
}
@@ -128,6 +149,7 @@ async function downloadArtifact(
checksum: string | undefined,
manifestChecksum: string | undefined,
githubToken: string | undefined,
toolCacheName: string,
): Promise<{ version: string; cachedToolDir: string }> {
log.info(`Downloading uv from "${downloadUrl}" ...`);
const downloadPath = await tc.downloadTool(
@@ -165,12 +187,7 @@ async function downloadArtifact(
uvDir = path.join(extractedDir, artifactName);
}
const cachedToolDir = await tc.cacheDir(
uvDir,
TOOL_CACHE_NAME,
version,
arch,
);
const cachedToolDir = await tc.cacheDir(uvDir, toolCacheName, version, arch);
return { cachedToolDir, version };
}
+23 -3
View File
@@ -5,9 +5,14 @@ import * as exec from "@actions/exec";
import { restoreCache } from "./cache/restore-cache";
import {
downloadVersion,
getIntrinsicChecksum,
tryGetFromToolCache,
} from "./download/download-version";
import { STATE_UV_PATH, STATE_UV_VERSION } from "./utils/constants";
import {
STATE_UV_PATH,
STATE_UV_VERSION,
TOOL_CACHE_NAME,
} from "./utils/constants";
import { CacheLocalSource, loadInputs, type SetupInputs } from "./utils/inputs";
import * as log from "./utils/logging";
import {
@@ -147,7 +152,21 @@ async function setupUv(
versionFile: inputs.versionFile,
workingDirectory: inputs.workingDirectory,
});
const toolCacheResult = tryGetFromToolCache(arch, resolvedVersion);
let checksum = inputs.checksum;
let toolCacheName = TOOL_CACHE_NAME;
if (inputs.requireChecksums) {
checksum = getIntrinsicChecksum(
`${arch}-${platform}-${resolvedVersion}`,
inputs.checksum,
);
// A regular tool-cache entry may have been verified using a manifest checksum.
toolCacheName = `${TOOL_CACHE_NAME}-${checksum}`;
}
const toolCacheResult = tryGetFromToolCache(
arch,
resolvedVersion,
toolCacheName,
);
if (toolCacheResult.installedPath) {
log.info(`Found uv in tool-cache for ${toolCacheResult.version}`);
return {
@@ -160,10 +179,11 @@ async function setupUv(
platform,
arch,
resolvedVersion,
inputs.checksum,
checksum,
inputs.githubToken,
inputs.manifestFile,
inputs.downloadFromAstralMirror,
toolCacheName,
);
return {
+3
View File
@@ -30,6 +30,7 @@ export interface SetupInputs {
noProject: boolean;
venvPath: string;
checksum: string;
requireChecksums: boolean;
enableCache: boolean;
restoreCache: boolean;
saveCache: boolean;
@@ -63,6 +64,7 @@ export function loadInputs(): SetupInputs {
const noProject = core.getBooleanInput("no-project");
const venvPath = getVenvPath(workingDirectory, activateEnvironment);
const checksum = core.getInput("checksum");
const requireChecksums = core.getBooleanInput("require-checksums");
const enableCache = getEnableCache();
const restoreCache = core.getInput("restore-cache") === "true";
const saveCache = getSaveCache();
@@ -110,6 +112,7 @@ export function loadInputs(): SetupInputs {
pythonDir,
pythonVersion,
quiet,
requireChecksums,
resolutionStrategy,
restoreCache,
saveCache,