Verify JDK downloads with vendor checksums (#1167 )

* Verify JDK downloads with vendor checksums Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Handle missing vendor checksum values Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Preserve checksum error during cleanup failure Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Validate checksum metadata value types Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Clarify checksum documentation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Expand vendor checksum verification Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Accept SHA-256 or SHA-512 for JetBrains checksum sibling JetBrains publishes a single, generically-named ".checksum" sibling whose digest algorithm isn't disclosed by the filename. Older JBR 11 builds (e.g. jbrsdk_nomod-11_0_16-*-b2043.64.tar.gz) publish a SHA-256 digest there, while newer builds publish SHA-512. The JetBrains installer previously assumed SHA-512 unconditionally, so verification failed with "Malformed sha512 checksum metadata ... expected a 128-character hexadecimal digest" for those older builds, breaking the jetbrains 11 e2e job on macOS and Windows. fetchChecksum now accepts a list of candidate algorithms and infers the actual algorithm from the returned digest's length, preferring the strongest match. The JetBrains installer passes ['sha512', 'sha256']; all other callers are unaffected since they already pass a single, vendor-disclosed algorithm. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Use SapMachine archive checksum files Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d
Harden java-package validation (#1165 )
2026-08-27 11:03:19 +01:00 · 2026-07-29 04:43:56 -04:00 · 2026-07-29 00:50:01 -04:00 · 2026-07-29 00:36:12 -04:00 · 2026-07-29 00:09:37 -04:00 · 2026-07-28 23:33:41 -04:00
54 changed files with 3458 additions and 399 deletions
--- a/.github/workflows/e2e-versions.yml
+++ b/.github/workflows/e2e-versions.yml
@@ -83,6 +83,15 @@ jobs:
          - distribution: oracle
            os: ubuntu-latest
            version: 21
+          - distribution: oracle-openjdk
+            os: macos-15-intel
+            version: 21
+          - distribution: oracle-openjdk
+            os: windows-latest
+            version: 21
+          - distribution: oracle-openjdk
+            os: ubuntu-latest
+            version: 21
          - distribution: graalvm
            os: macos-latest
            version: 17.0.12
@@ -116,6 +125,25 @@ jobs:
        run: bash __tests__/verify-java.sh "$JAVA_VERSION" "$JAVA_PATH"
        shell: bash

+  setup-java-checksum-verification:
+    name: Corretto checksum verification - ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - *checkout_step
+      - name: setup-java with forced download
+        uses: ./
+        id: setup-java
+        with:
+          java-version: '21'
+          distribution: corretto
+          force-download: true
+      - name: Verify Java
+        env:
+          JAVA_VERSION: '21'
+          JAVA_PATH: ${{ steps.setup-java.outputs.path }}
+        run: bash __tests__/verify-java.sh "$JAVA_VERSION" "$JAVA_PATH"
+        shell: bash
+
  setup-java-alpine-linux:
    name: ${{ matrix.distribution }} ${{ matrix.version }} (jdk-${{ contains(matrix.os, 'macos') && !contains(matrix.os, 'intel') && 'arm64' || 'x64' }}) - alpine-linux - ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
--- a/README.md
+++ b/README.md
@@ -48,7 +48,7 @@ For more details,  see the full release notes on the [releases page](https://git

  - `distribution`: Java [distribution](#supported-distributions). Required unless `java-version-file` points to `.sdkmanrc` with a recognized distribution suffix (for example `java=21.0.5-tem`).

-  - `java-package`: The packaging variant of the chosen distribution. Possible values: `jdk`, `jre`, `jdk+fx`, `jre+fx`. For Azul Zulu, `jdk+crac` and `jre+crac` are also supported. For Eclipse Temurin 24 and later, `jdk+jmods` includes the separately packaged JMOD files. Default value: `jdk`.
+  - `java-package`: The packaging variant of the chosen distribution. Possible values across all distributions are `jdk`, `jre`, `jdk+fx`, `jre+fx`, `jdk+crac`, `jre+crac`, `jdk+jmods`, `jdk+jcef`, `jre+jcef`, `jdk+ft`, and `jre+ft`. Supported values vary by distribution; see the [package compatibility table](docs/advanced-usage.md#package-compatibility). Default value: `jdk`.

  - `architecture`: The target architecture of the package. Possible values: `x86`, `x64`, `armv7`, `aarch64`, `ppc64le`. Default value: Derived from the runner machine.

@@ -89,12 +89,20 @@ For more details,  see the full release notes on the [releases page](https://git

  - `gpg-passphrase-env-var`: Environment variable name for the GPG private key passphrase. Default is GPG\_PASSPHRASE.

-  - `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted.
+  - `mvn-toolchain-id`: Name of Maven Toolchain ID if the default name of `${distribution}_${java-version}` is not wanted. When supplied, the number of IDs must match the number of Java versions.

  - `mvn-toolchain-vendor`: Name of Maven Toolchain Vendor if the default name of `${distribution}` is not wanted.

  - `show-download-progress`: Set to `true` to keep Maven artifact download and transfer progress in build logs. Default value: `false`. By default, the action adds `-ntp` (`--no-transfer-progress`) to `MAVEN_ARGS`. This input has no effect on non-Maven builds. See [Maven transfer progress](docs/advanced-usage.md#maven-transfer-progress-download-logs) for more details.

+### Download integrity verification
+
+When a selected distribution publishes an authoritative checksum for an archive, `setup-java` automatically verifies each downloaded JDK, JRE, or JMOD archive before extraction and caching. No input is required. Automatic checksum verification is currently available for `temurin`, `semeru`, `adopt`, `corretto`, `dragonwell`, `kona`, `sapmachine`, `graalvm`, `graalvm-community`, `zulu`, `oracle`, `oracle-openjdk`, `microsoft`, and `jetbrains`.
+
+Distributions or individual releases without an authoritative checksum continue to install normally, with the omission reported only in debug logs. Archives resolved directly from the runner tool cache are not downloaded again and therefore are not reverified.
+
+Checksums detect corrupted or unexpectedly modified downloads before they are persisted in the runner tool cache.
+
 ### Basic Configuration

 #### Eclipse Temurin
--- a/tests/checksum.test.ts
+++ b/tests/checksum.test.ts
@@ -0,0 +1,130 @@
+import {afterEach, describe, expect, it, jest} from '@jest/globals';
+import {createHash} from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {calculateChecksum, verifyChecksum} from '../src/checksum.js';
+import type {ChecksumMetadata} from '../src/distributions/base-models.js';
+
+const temporaryPaths: string[] = [];
+
+async function temporaryFile(contents: string): Promise<string> {
+  const directory = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), 'setup-java-checksum-')
+  );
+  const file = path.join(directory, 'archive');
+  await fs.promises.writeFile(file, contents);
+  temporaryPaths.push(directory);
+  return file;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryPaths
+      .splice(0)
+      .map(item => fs.promises.rm(item, {recursive: true, force: true}))
+  );
+  jest.restoreAllMocks();
+});
+
+describe('verifyChecksum', () => {
+  it.each(['sha256', 'sha512'] as const)(
+    'verifies a matching %s digest',
+    async algorithm => {
+      const contents = `jdk archive for ${algorithm}`;
+      const file = await temporaryFile(contents);
+      const value = createHash(algorithm).update(contents).digest('hex');
+
+      await expect(
+        verifyChecksum(
+          file,
+          {algorithm, value: value.toUpperCase()},
+          {distribution: 'Test', version: '21.0.1'}
+        )
+      ).resolves.toBeUndefined();
+    }
+  );
+
+  it('reports mismatch context and both digests', async () => {
+    const file = await temporaryFile('corrupt archive');
+    const expected = 'a'.repeat(64);
+    const actual = await calculateChecksum(file, 'sha256');
+
+    await expect(
+      verifyChecksum(
+        file,
+        {algorithm: 'sha256', value: expected},
+        {distribution: 'Corretto', version: '21.0.8'}
+      )
+    ).rejects.toThrow(
+      `Checksum verification failed for Corretto version 21.0.8: sha256 expected ${expected}, actual ${actual}.`
+    );
+  });
+
+  it('rejects malformed digest metadata before reading the file', async () => {
+    await expect(
+      verifyChecksum(
+        '/missing/archive',
+        {algorithm: 'sha512', value: 'not-a-digest'},
+        {distribution: 'Test', version: '17'}
+      )
+    ).rejects.toThrow(
+      'Malformed sha512 checksum metadata: expected a 128-character hexadecimal digest.'
+    );
+  });
+
+  it.each([undefined, null, 123])(
+    'reports a malformed digest when the value is %p',
+    async value => {
+      const checksum = {
+        algorithm: 'sha256',
+        value
+      } as unknown as ChecksumMetadata;
+
+      await expect(
+        verifyChecksum('/missing/archive', checksum, {
+          distribution: 'Test',
+          version: '17'
+        })
+      ).rejects.toThrow(
+        'Malformed sha256 checksum metadata: expected a 64-character hexadecimal digest.'
+      );
+    }
+  );
+
+  it('rejects unsupported algorithms without leaking source query parameters', async () => {
+    const checksum = {
+      algorithm: 'md5',
+      value: 'a'.repeat(32),
+      source: 'https://vendor.example/checksum.txt?token=secret-value#private'
+    } as unknown as ChecksumMetadata;
+
+    let message = '';
+    try {
+      await verifyChecksum('/missing/archive', checksum, {
+        distribution: 'Test',
+        version: '17'
+      });
+    } catch (error) {
+      message = (error as Error).message;
+    }
+
+    expect(message).toContain(
+      "Unsupported checksum algorithm 'md5' from https://vendor.example/checksum.txt"
+    );
+    expect(message).not.toContain('secret-value');
+    expect(message).not.toContain('token=');
+    expect(message).not.toContain('#private');
+  });
+
+  it('surfaces file read errors', async () => {
+    await expect(
+      verifyChecksum(
+        '/missing/archive',
+        {algorithm: 'sha256', value: 'a'.repeat(64)},
+        {distribution: 'Test', version: '17'}
+      )
+    ).rejects.toMatchObject({code: 'ENOENT'});
+  });
+});
--- a/tests/distributors/adopt-installer.test.ts
+++ b/tests/distributors/adopt-installer.test.ts
@@ -357,6 +357,14 @@ describe('findPackageForDownload', () => {
    distribution['getAvailableVersions'] = async () => manifestData as any;
    const resolvedVersion = await distribution['findPackageForDownload'](input);
    expect(resolvedVersion.version).toBe(expected);
+    const vendorPackage = (manifestData as any[]).find(
+      item => item.version_data.semver === expected
+    ).binaries[0].package;
+    expect(resolvedVersion.checksum).toEqual({
+      algorithm: 'sha256',
+      value: vendorPackage.checksum,
+      source: vendorPackage.checksum_link
+    });
  });

  it('version is found but binaries list is empty', async () => {
--- a/tests/distributors/base-installer.test.ts
+++ b/tests/distributors/base-installer.test.ts
@@ -16,6 +16,9 @@ import type {

 import path from 'path';
 import * as semver from 'semver';
+import fs from 'fs';
+import {createHash} from 'crypto';
+import {HttpClient} from '@actions/http-client';

 import os from 'os';

@@ -117,6 +120,17 @@ class EmptyJavaBase extends JavaBase {
      url: `some/random_url/java/${availableVersion}`
    };
  }
+
+  public downloadRelease(javaRelease: JavaDownloadRelease): Promise<string> {
+    return this.downloadAndVerify(javaRelease);
+  }
+
+  public fetchChecksumForTest(
+    checksumUrl: string,
+    algorithm: 'sha256' | 'sha512' | ('sha256' | 'sha512')[]
+  ) {
+    return this.fetchChecksum(checksumUrl, algorithm);
+  }
 }

 describe('findInToolcache', () => {
@@ -605,6 +619,31 @@ describe('setupJava', () => {
    expect(spyCoreSetOutput).not.toHaveBeenCalled();
  });

+  it('should not repeat version resolution when downloadTool fails', async () => {
+    mockJavaBase = new EmptyJavaBase({
+      version: '11',
+      architecture: 'x86',
+      packageType: 'jdk',
+      checkLatest: false,
+      forceDownload: true
+    });
+    const findPackageForDownload = jest.fn(async () => ({
+      version: '11.0.9',
+      url: 'https://example.com/jdk.tar.gz'
+    }));
+    const downloadError = new Error('download failed');
+    const downloadTool = jest.fn(async () => {
+      throw downloadError;
+    });
+    mockJavaBase['findPackageForDownload'] = findPackageForDownload;
+    mockJavaBase['downloadTool'] = downloadTool;
+
+    await expect(mockJavaBase.setupJava()).rejects.toBe(downloadError);
+
+    expect(findPackageForDownload).toHaveBeenCalledTimes(1);
+    expect(downloadTool).toHaveBeenCalledTimes(1);
+  });
+
  it.each([
    [
      {
@@ -792,6 +831,306 @@ describe('setupJava', () => {
  });
 });

+describe('downloadAndVerify', () => {
+  const options: JavaInstallerOptions = {
+    version: '21',
+    architecture: 'x64',
+    packageType: 'jdk',
+    checkLatest: false
+  };
+  let temporaryDirectory: string;
+  let archivePath: string;
+
+  beforeEach(async () => {
+    temporaryDirectory = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), 'setup-java-base-')
+    );
+    archivePath = path.join(temporaryDirectory, 'archive');
+    await fs.promises.writeFile(archivePath, 'downloaded archive');
+    (tc.downloadTool as jest.Mock<any>).mockResolvedValue(archivePath);
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(temporaryDirectory, {recursive: true, force: true});
+    jest.resetAllMocks();
+  });
+
+  it('returns a download after successful verification', async () => {
+    const distribution = new EmptyJavaBase(options);
+    const result = await distribution.downloadRelease({
+      version: '21.0.8',
+      url: 'https://vendor.example/jdk.tar.gz',
+      checksum: {
+        algorithm: 'sha256',
+        value: createHash('sha256').update('downloaded archive').digest('hex')
+      }
+    });
+
+    expect(result).toBe(archivePath);
+    expect(fs.existsSync(archivePath)).toBe(true);
+    expect(core.debug).toHaveBeenCalledWith(
+      'Verified sha256 checksum for Empty version 21.0.8.'
+    );
+  });
+
+  it('removes the download after verification failure', async () => {
+    const distribution = new EmptyJavaBase(options);
+
+    await expect(
+      distribution.downloadRelease({
+        version: '21.0.8',
+        url: 'https://vendor.example/jdk.tar.gz?token=secret',
+        checksum: {algorithm: 'sha256', value: 'a'.repeat(64)}
+      })
+    ).rejects.toThrow('Checksum verification failed for Empty version 21.0.8');
+
+    expect(fs.existsSync(archivePath)).toBe(false);
+  });
+
+  it('preserves the verification error when removing the download fails', async () => {
+    const distribution = new EmptyJavaBase(options);
+    const cleanupError = new Error('cleanup failed');
+    jest.spyOn(fs.promises, 'rm').mockRejectedValueOnce(cleanupError);
+
+    const result = distribution.downloadRelease({
+      version: '21.0.8',
+      url: 'https://vendor.example/jdk.tar.gz',
+      checksum: {algorithm: 'sha256', value: 'a'.repeat(64)}
+    });
+
+    await expect(result).rejects.toMatchObject({
+      message: expect.stringContaining(
+        'Failed to remove the downloaded archive after verification failure: cleanup failed'
+      ),
+      cause: expect.objectContaining({
+        message: expect.stringContaining(
+          'Checksum verification failed for Empty version 21.0.8'
+        )
+      })
+    });
+  });
+
+  it('logs when authoritative checksum metadata is unavailable', async () => {
+    const distribution = new EmptyJavaBase(options);
+
+    await expect(
+      distribution.downloadRelease({
+        version: '21.0.8',
+        url: 'https://vendor.example/jdk.tar.gz'
+      })
+    ).resolves.toBe(archivePath);
+
+    expect(core.debug).toHaveBeenCalledWith(
+      'No authoritative checksum is available for Empty version 21.0.8; skipping checksum verification.'
+    );
+  });
+
+  it.each([undefined, '', '   '])(
+    'skips verification when the vendor digest is %p',
+    async value => {
+      const distribution = new EmptyJavaBase(options);
+
+      await expect(
+        distribution.downloadRelease({
+          version: '21.0.8',
+          url: 'https://vendor.example/jdk.tar.gz',
+          checksum: {
+            algorithm: 'sha256',
+            value
+          } as JavaDownloadRelease['checksum']
+        })
+      ).resolves.toBe(archivePath);
+
+      expect(core.debug).toHaveBeenCalledWith(
+        'No authoritative checksum is available for Empty version 21.0.8; skipping checksum verification.'
+      );
+    }
+  );
+});
+
+describe('fetchChecksum', () => {
+  const options: JavaInstallerOptions = {
+    version: '21',
+    architecture: 'x64',
+    packageType: 'jdk',
+    checkLatest: false
+  };
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  function mockGet(statusCode: number, body: string) {
+    return jest.spyOn(HttpClient.prototype, 'get').mockResolvedValue({
+      message: {statusCode},
+      readBody: async () => body
+    } as any);
+  }
+
+  it('parses a bare hex digest', async () => {
+    const digest = 'a'.repeat(64);
+    const spy = mockGet(200, digest);
+    const distribution = new EmptyJavaBase(options);
+
+    const checksum = await distribution.fetchChecksumForTest(
+      'https://vendor.example/jdk.tar.gz.sha256',
+      'sha256'
+    );
+
+    expect(spy).toHaveBeenCalledWith(
+      'https://vendor.example/jdk.tar.gz.sha256'
+    );
+    expect(checksum).toEqual({
+      algorithm: 'sha256',
+      value: digest,
+      source: 'https://vendor.example/jdk.tar.gz.sha256'
+    });
+  });
+
+  it('parses only the first token of a GNU-style checksum file', async () => {
+    const digest = 'b'.repeat(128);
+    mockGet(200, `${digest}  jbrsdk-21.0.3-linux-x64-b465.3.tar.gz\n`);
+    const distribution = new EmptyJavaBase(options);
+
+    const checksum = await distribution.fetchChecksumForTest(
+      'https://vendor.example/jdk.tar.gz.checksum',
+      'sha512'
+    );
+
+    expect(checksum).toEqual({
+      algorithm: 'sha512',
+      value: digest,
+      source: 'https://vendor.example/jdk.tar.gz.checksum'
+    });
+  });
+
+  it('trims surrounding whitespace and newlines', async () => {
+    const digest = 'c'.repeat(64);
+    mockGet(200, `\n  ${digest}  \n`);
+    const distribution = new EmptyJavaBase(options);
+
+    const checksum = await distribution.fetchChecksumForTest(
+      'https://vendor.example/jdk.tar.gz.sha256',
+      'sha256'
+    );
+
+    expect(checksum.value).toBe(digest);
+  });
+
+  it('skips verification when the sibling checksum is not published', async () => {
+    mockGet(404, 'Not Found');
+    const distribution = new EmptyJavaBase(options);
+
+    await expect(
+      distribution.fetchChecksumForTest(
+        'https://vendor.example/jdk.tar.gz.sha256',
+        'sha256'
+      )
+    ).resolves.toBeUndefined();
+    expect(core.debug).toHaveBeenCalledWith(
+      'No authoritative sha256 checksum is available for Empty from https://vendor.example/jdk.tar.gz.sha256; skipping checksum verification.'
+    );
+  });
+
+  it('surfaces unexpected HTTP failures without query parameters', async () => {
+    mockGet(500, 'Server Error');
+    const distribution = new EmptyJavaBase(options);
+
+    await expect(
+      distribution.fetchChecksumForTest(
+        'https://vendor.example/jdk.tar.gz.sha256?token=secret',
+        'sha256'
+      )
+    ).rejects.toThrow(
+      'Failed to fetch the authoritative sha256 checksum for Empty from https://vendor.example/jdk.tar.gz.sha256 (HTTP 500).'
+    );
+  });
+
+  it('rejects an empty successful checksum response', async () => {
+    mockGet(200, '  \n');
+    const distribution = new EmptyJavaBase(options);
+
+    await expect(
+      distribution.fetchChecksumForTest(
+        'https://vendor.example/jdk.tar.gz.sha256',
+        'sha256'
+      )
+    ).rejects.toThrow(
+      'Received an empty authoritative sha256 checksum for Empty from https://vendor.example/jdk.tar.gz.sha256.'
+    );
+  });
+
+  describe('with a list of candidate algorithms', () => {
+    it('infers sha512 when the digest is 128 hex characters', async () => {
+      const digest = 'd'.repeat(128);
+      mockGet(200, `${digest}  jbrsdk.tar.gz\n`);
+      const distribution = new EmptyJavaBase(options);
+
+      const checksum = await distribution.fetchChecksumForTest(
+        'https://vendor.example/jbrsdk.tar.gz.checksum',
+        ['sha512', 'sha256']
+      );
+
+      expect(checksum).toEqual({
+        algorithm: 'sha512',
+        value: digest,
+        source: 'https://vendor.example/jbrsdk.tar.gz.checksum'
+      });
+    });
+
+    it('infers sha256 when the digest is 64 hex characters, even though sha512 was preferred', async () => {
+      // Reproduces older JetBrains JBR builds (e.g. JBR 11), which publish a
+      // SHA-256 digest at the generic `.checksum` sibling instead of SHA-512.
+      const digest = 'e'.repeat(64);
+      mockGet(200, `${digest}  jbrsdk_nomod-11_0_16-osx-x64-b2043.64.tar.gz\n`);
+      const distribution = new EmptyJavaBase(options);
+
+      const checksum = await distribution.fetchChecksumForTest(
+        'https://vendor.example/jbrsdk_nomod-11_0_16-osx-x64-b2043.64.tar.gz.checksum',
+        ['sha512', 'sha256']
+      );
+
+      expect(checksum).toEqual({
+        algorithm: 'sha256',
+        value: digest,
+        source:
+          'https://vendor.example/jbrsdk_nomod-11_0_16-osx-x64-b2043.64.tar.gz.checksum'
+      });
+    });
+
+    it('falls back to the first candidate algorithm when the digest length matches none of them', async () => {
+      const digest = 'f'.repeat(40); // e.g. sha1, not supported
+      mockGet(200, `${digest}  jbrsdk.tar.gz\n`);
+      const distribution = new EmptyJavaBase(options);
+
+      const checksum = await distribution.fetchChecksumForTest(
+        'https://vendor.example/jbrsdk.tar.gz.checksum',
+        ['sha512', 'sha256']
+      );
+
+      // No candidate algorithm matches, so the first-listed one is kept;
+      // downstream verification will reject it as malformed.
+      expect(checksum.algorithm).toBe('sha512');
+      expect(checksum.value).toBe(digest);
+    });
+
+    it('reports the checksum as unavailable using a combined algorithm label on 404', async () => {
+      mockGet(404, 'Not Found');
+      const distribution = new EmptyJavaBase(options);
+
+      await expect(
+        distribution.fetchChecksumForTest(
+          'https://vendor.example/jbrsdk.tar.gz.checksum',
+          ['sha512', 'sha256']
+        )
+      ).resolves.toBeUndefined();
+      expect(core.debug).toHaveBeenCalledWith(
+        'No authoritative sha512 or sha256 checksum is available for Empty from https://vendor.example/jbrsdk.tar.gz.checksum; skipping checksum verification.'
+      );
+    });
+  });
+});
+
 describe('normalizeVersion', () => {
  const DummyJavaBase = JavaBase as any;

--- a/tests/distributors/corretto-installer.test.ts
+++ b/tests/distributors/corretto-installer.test.ts
@@ -202,6 +202,12 @@ describe('getAvailableVersions', () => {
        await distribution['findPackageForDownload'](version);
      expect(availableVersion).not.toBeNull();
      expect(availableVersion.url).toBe(expectedLink);
+      expect(availableVersion.checksum).toEqual({
+        algorithm: 'sha256',
+        value: expect.stringMatching(/^[a-f0-9]{64}$/),
+        source:
+          'https://corretto.github.io/corretto-downloads/latest_links/indexmap_with_checksum.json'
+      });
    });

    it('with latest resolves to the newest available major version', async () => {
--- a/tests/distributors/distribution-factory.test.ts
+++ b/tests/distributors/distribution-factory.test.ts
@@ -1,16 +1,114 @@
 import {getJavaDistribution} from '../../src/distributions/distribution-factory.js';
+import {RetryingHttpClient} from '../../src/retrying-http-client.js';
+import {
+  JAVA_PACKAGE_CAPABILITIES,
+  JavaDistribution
+} from '../../src/distributions/package-types.js';
+
+const installerOptions = (packageType: string, version = '25') => ({
+  version,
+  architecture: 'x64',
+  packageType,
+  checkLatest: false
+});

 describe('getJavaDistribution', () => {
+  it.each([
+    'adopt',
+    'adopt-hotspot',
+    'adopt-openj9',
+    'temurin',
+    'zulu',
+    'liberica',
+    'liberica-nik',
+    'microsoft',
+    'semeru',
+    'corretto',
+    'oracle',
+    'dragonwell',
+    'sapmachine',
+    'graalvm',
+    'graalvm-community',
+    'jetbrains',
+    'kona',
+    'oracle-openjdk'
+  ])('uses the shared retrying HTTP client for %s', distributionName => {
+    const distribution = getJavaDistribution(distributionName, {
+      version: '21',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+
+    expect(distribution).not.toBeNull();
+    expect(distribution!['http']).toBeInstanceOf(RetryingHttpClient);
+  });
+
+  it.each(
+    Object.entries(JAVA_PACKAGE_CAPABILITIES).flatMap(
+      ([distributionName, packageTypes]) =>
+        packageTypes.map(packageType => [distributionName, packageType])
+    )
+  )('accepts %s with java-package %s', (distributionName, packageType) => {
+    expect(
+      getJavaDistribution(
+        distributionName,
+        installerOptions(packageType as string)
+      )
+    ).not.toBeNull();
+  });
+
+  it.each(Object.entries(JAVA_PACKAGE_CAPABILITIES))(
+    'rejects unsupported java-package values for %s',
+    (distributionName, packageTypes) => {
+      expect(() =>
+        getJavaDistribution(distributionName, installerOptions('jdk+typo'))
+      ).toThrow(
+        `Java package 'jdk+typo' is not supported for distribution '${distributionName}'. Supported package types: ${packageTypes.join(', ')}.`
+      );
+    }
+  );
+
  it("rejects java-package 'jdk+jmods' for non-Temurin distributions", () => {
    expect(() =>
-      getJavaDistribution('zulu', {
-        version: '25',
-        architecture: 'x64',
-        packageType: 'jdk+jmods',
-        checkLatest: false
-      })
+      getJavaDistribution('zulu', installerOptions('jdk+jmods'))
    ).toThrow(
-      "java-package 'jdk+jmods' is only supported for distribution 'temurin'."
+      "Java package 'jdk+jmods' is not supported for distribution 'zulu'. Supported package types: jdk, jre, jdk+fx, jre+fx, jdk+crac, jre+crac."
    );
  });
+
+  it.each(['8', '23.x', '23.0.1.1', '<24'])(
+    "rejects Temurin java-package 'jdk+jmods' for version %s",
+    version => {
+      expect(() =>
+        getJavaDistribution(
+          JavaDistribution.Temurin,
+          installerOptions('jdk+jmods', version)
+        )
+      ).toThrow(
+        `Java package 'jdk+jmods' is not supported for distribution 'temurin'. Supported package types: jdk, jre, jdk+jmods. Package 'jdk+jmods' requires Java 24 or later; requested version '${version}'.`
+      );
+    }
+  );
+
+  it.each(['24', '24.0.1.1', '25-ea', '>=21', 'latest'])(
+    "accepts Temurin java-package 'jdk+jmods' for version %s",
+    version => {
+      expect(
+        getJavaDistribution(
+          JavaDistribution.Temurin,
+          installerOptions('jdk+jmods', version)
+        )
+      ).not.toBeNull();
+    }
+  );
+
+  it('preserves unsupported distribution handling', () => {
+    expect(
+      getJavaDistribution(
+        'not-a-distribution',
+        installerOptions('not-a-package')
+      )
+    ).toBeNull();
+  });
 });
--- a/tests/distributors/dragonwell-installer.test.ts
+++ b/tests/distributors/dragonwell-installer.test.ts
@@ -259,6 +259,10 @@ describe('getAvailableVersions', () => {
          await distribution['findPackageForDownload'](jdkVersion);
        expect(availableVersion).not.toBeNull();
        expect(availableVersion.url).toBe(expectedLink);
+        expect(availableVersion.checksum).toEqual({
+          algorithm: 'sha256',
+          value: expect.stringMatching(/^[a-f0-9]{64}$/)
+        });
      }
    );

--- a/tests/distributors/graalvm-installer.test.ts
+++ b/tests/distributors/graalvm-installer.test.ts
@@ -129,6 +129,14 @@ describe('GraalVMDistribution', () => {
    (distribution as any).http = mockHttpClient;
    (communityDistribution as any).http = mockHttpClient;

+    // Default checksum sibling response for `${url}.sha256` requests made by
+    // GraalVM (Oracle) and GraalVM EA. Individual tests override this when
+    // they need to assert the exact URL/digest contract.
+    mockHttpClient.get.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: jest.fn().mockResolvedValue('a'.repeat(64))
+    });
+
    (util.getDownloadArchiveExtension as jest.Mock<any>).mockReturnValue(
      'tar.gz'
    );
@@ -407,9 +415,16 @@ describe('GraalVMDistribution', () => {

        expect(result).toEqual({
          url: 'https://download.oracle.com/graalvm/17/archive/graalvm-jdk-17.0.5_linux-x64_bin.tar.gz',
-          version: '17.0.5'
+          version: '17.0.5',
+          checksum: {
+            algorithm: 'sha256',
+            value: 'a'.repeat(64),
+            source:
+              'https://download.oracle.com/graalvm/17/archive/graalvm-jdk-17.0.5_linux-x64_bin.tar.gz.sha256'
+          }
        });
        expect(mockHttpClient.head).toHaveBeenCalledWith(result.url);
+        expect(mockHttpClient.get).toHaveBeenCalledWith(`${result.url}.sha256`);
      });

      it('should construct correct URL for major version (latest)', async () => {
@@ -422,7 +437,13 @@ describe('GraalVMDistribution', () => {

        expect(result).toEqual({
          url: 'https://download.oracle.com/graalvm/21/latest/graalvm-jdk-21_linux-x64_bin.tar.gz',
-          version: '21'
+          version: '21',
+          checksum: {
+            algorithm: 'sha256',
+            value: 'a'.repeat(64),
+            source:
+              'https://download.oracle.com/graalvm/21/latest/graalvm-jdk-21_linux-x64_bin.tar.gz.sha256'
+          }
        });
      });

@@ -465,7 +486,13 @@ describe('GraalVMDistribution', () => {

          expect(result).toEqual({
            url: 'https://download.oracle.com/graalvm/25/latest/graalvm-jdk-25_linux-x64_bin.tar.gz',
-            version: '25'
+            version: '25',
+            checksum: {
+              algorithm: 'sha256',
+              value: 'a'.repeat(64),
+              source:
+                'https://download.oracle.com/graalvm/25/latest/graalvm-jdk-25_linux-x64_bin.tar.gz.sha256'
+            }
          });
        });

@@ -637,13 +664,20 @@ describe('GraalVMDistribution', () => {

        expect(result).toEqual({
          url: 'https://example.com/download/graalvm-jdk-23_linux-x64_bin.tar.gz',
-          version: '23-ea-20240716'
+          version: '23-ea-20240716',
+          checksum: {
+            algorithm: 'sha256',
+            value: 'a'.repeat(64),
+            source:
+              'https://example.com/download/graalvm-jdk-23_linux-x64_bin.tar.gz.sha256'
+          }
        });

        expect(mockHttpClient.getJson).toHaveBeenCalledWith(
          'https://api.github.com/repos/graalvm/oracle-graalvm-ea-builds/contents/versions/23-ea.json?ref=main',
          {Accept: 'application/json'}
        );
+        expect(mockHttpClient.get).toHaveBeenCalledWith(`${result.url}.sha256`);
      });

      it('should throw error when no latest EA version found', async () => {
@@ -876,8 +910,15 @@ describe('GraalVMDistribution', () => {
      expect(fetchEASpy).toHaveBeenCalledWith('23-ea');
      expect(result).toEqual({
        url: 'https://example.com/download/graalvm-jdk-23_linux-x64_bin.tar.gz',
-        version: '23-ea-20240716'
+        version: '23-ea-20240716',
+        checksum: {
+          algorithm: 'sha256',
+          value: 'a'.repeat(64),
+          source:
+            'https://example.com/download/graalvm-jdk-23_linux-x64_bin.tar.gz.sha256'
+        }
      });
+      expect(mockHttpClient.get).toHaveBeenCalledWith(`${result.url}.sha256`);

      // Verify debug logging
      expect(core.debug).toHaveBeenCalledWith('Searching for EA build: 23-ea');
@@ -976,7 +1017,13 @@ describe('GraalVMDistribution', () => {

      expect(result).toEqual({
        url: 'https://example.com/download/graalvm-jdk-23_linux-aarch64_bin.tar.gz',
-        version: '23-ea-20240716'
+        version: '23-ea-20240716',
+        checksum: {
+          algorithm: 'sha256',
+          value: 'a'.repeat(64),
+          source:
+            'https://example.com/download/graalvm-jdk-23_linux-aarch64_bin.tar.gz.sha256'
+        }
      });
    });

@@ -1151,6 +1198,80 @@ describe('GraalVMDistribution', () => {
          url: 'https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-21.0.2/graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz',
          version: '21.0.2'
        });
+        // The asset had no `digest` field, so no checksum should be attached,
+        // and the checksum sibling-URL fetch path (used by Oracle GraalVM)
+        // must not be consulted for GraalVM Community.
+        expect(result.checksum).toBeUndefined();
+        expect(mockHttpClient.get).not.toHaveBeenCalled();
+      });
+
+      it('strips the `sha256:` prefix from a GitHub release asset digest', async () => {
+        const digest = 'd'.repeat(64);
+        mockHttpClient.getJson.mockResolvedValue({
+          result: [
+            {
+              draft: false,
+              prerelease: false,
+              assets: [
+                {
+                  name: 'graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz',
+                  browser_download_url:
+                    'https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-21.0.2/graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz',
+                  digest: `sha256:${digest}`
+                }
+              ]
+            }
+          ],
+          statusCode: 200,
+          headers: {}
+        });
+
+        const result = await (
+          communityDistribution as any
+        ).findPackageForDownload('21.0.2');
+
+        expect(result.checksum).toEqual({
+          algorithm: 'sha256',
+          value: digest,
+          source:
+            'https://api.github.com/repos/graalvm/graalvm-ce-builds/releases?per_page=100'
+        });
+        // The digest came from the release listing itself, so no additional
+        // HTTP request should be made to resolve the checksum.
+        expect(mockHttpClient.get).not.toHaveBeenCalled();
+      });
+
+      it('safely skips a missing or malformed release asset digest', async () => {
+        mockHttpClient.getJson.mockResolvedValue({
+          result: [
+            {
+              draft: false,
+              prerelease: false,
+              assets: [
+                {
+                  name: 'graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz',
+                  browser_download_url:
+                    'https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-21.0.2/graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz',
+                  digest: 'md5:not-a-sha256-digest'
+                }
+              ]
+            }
+          ],
+          statusCode: 200,
+          headers: {}
+        });
+
+        const result = await (
+          communityDistribution as any
+        ).findPackageForDownload('21.0.2');
+
+        expect(result.checksum).toBeUndefined();
+        expect(mockHttpClient.get).not.toHaveBeenCalled();
+        expect(core.debug).toHaveBeenCalledWith(
+          expect.stringContaining(
+            'No authoritative sha256 digest is available for graalvm-community-jdk-21.0.2_linux-x64_bin.tar.gz'
+          )
+        );
      });

      it('should resolve the latest GraalVM Community release for a major version', async () => {
--- a/tests/distributors/jetbrains-installer.test.ts
+++ b/tests/distributors/jetbrains-installer.test.ts
@@ -9,7 +9,9 @@ import {
  afterAll
 } from '@jest/globals';
 import https from 'https';
-import {HttpClient} from '@actions/http-client';
+import {HttpClient, HttpClientResponse} from '@actions/http-client';
+import type {IncomingMessage} from 'http';
+import {Readable} from 'stream';

 import manifestData from '../data/jetbrains.json' with {type: 'json'};
 import os from 'os';
@@ -44,6 +46,18 @@ jest.unstable_mockModule('@actions/core', () => ({
 const core = await import('@actions/core');
 const {JetBrainsDistribution} =
  await import('../../src/distributions/jetbrains/installer.js');
+const {RetryingHttpClient} = await import('../../src/retrying-http-client.js');
+
+function response(
+  statusCode: number,
+  body = '',
+  headers: IncomingMessage['headers'] = {}
+): HttpClientResponse {
+  const message = Readable.from([Buffer.from(body)]) as IncomingMessage;
+  message.statusCode = statusCode;
+  message.headers = headers;
+  return new HttpClientResponse(message);
+}

 describe('getAvailableVersions', () => {
  let spyHttpClient: any;
@@ -95,9 +109,66 @@ describe('getAvailableVersions', () => {
      os.platform() === 'win32' ? manifestData.length : manifestData.length + 2;
    expect(availableVersions.length).toBe(length);
  }, 10_000);
+
+  it('retries a GitHub rate limit using Retry-After', async () => {
+    spyHttpClient.mockRestore();
+    const sleep = jest.fn(async () => undefined);
+    const requestRaw = jest
+      .spyOn(HttpClient.prototype, 'requestRaw')
+      .mockResolvedValueOnce(response(429, '', {'retry-after': '2'}))
+      .mockResolvedValueOnce(response(200, '[]'))
+      .mockResolvedValueOnce(response(200))
+      .mockResolvedValueOnce(response(200));
+    const distribution = new JetBrainsDistribution({
+      version: '17',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['http'] = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0
+    });
+
+    const availableVersions = await distribution['getAvailableVersions']();
+
+    expect(availableVersions).toHaveLength(2);
+    expect(requestRaw).toHaveBeenCalledTimes(4);
+    expect(requestRaw.mock.calls[0][0].options.path).toBe(
+      requestRaw.mock.calls[1][0].options.path
+    );
+    expect(requestRaw.mock.calls[0][0].options.path).toContain(
+      '/repos/JetBrains/JetBrainsRuntime/releases'
+    );
+    expect(sleep).toHaveBeenCalledWith(2000);
+    expect(core.info).toHaveBeenCalledWith(
+      'Request attempt 1 of 4 failed (HTTP 429); retrying in 2000 ms'
+    );
+  });
 });

 describe('findPackageForDownload', () => {
+  let spyHttpClientGet: any;
+
+  const JETBRAINS_CHECKSUM = 'c'.repeat(128);
+
+  beforeEach(() => {
+    // Every resolved release fetches `${url}.checksum` (sha512, GNU
+    // `<hex>  <filename>` format); stub it so tests never reach the real
+    // network, except the dedicated 'version %s can be downloaded' test
+    // below which intentionally exercises real HTTPS HEAD requests.
+    spyHttpClientGet = jest
+      .spyOn(HttpClient.prototype, 'get')
+      .mockResolvedValue({
+        message: {statusCode: 200},
+        readBody: async () => `${JETBRAINS_CHECKSUM}  jbrsdk.tar.gz\n`
+      } as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
  it.each([
    ['17', '17.0.11+1207.24'],
    ['11.0', '11.0.16+2043.64'],
@@ -181,4 +252,72 @@ describe('findPackageForDownload', () => {
      /No matching version found for SemVer */
    );
  });
+
+  it('fetches the authoritative sha512 checksum only for the resolved version', async () => {
+    const distribution = new JetBrainsDistribution({
+      version: '21',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData as any;
+
+    const result = await distribution['findPackageForDownload']('21');
+
+    expect(result.checksum).toEqual({
+      algorithm: 'sha512',
+      value: JETBRAINS_CHECKSUM,
+      source: `${result.url}.checksum`
+    });
+    // Only the single resolved/winning version's checksum is requested,
+    // not one per candidate considered during version resolution.
+    expect(spyHttpClientGet).toHaveBeenCalledWith(`${result.url}.checksum`);
+    expect(spyHttpClientGet).toHaveBeenCalledTimes(1);
+  });
+
+  it('parses only the first whitespace-delimited token from the GNU checksum payload', async () => {
+    spyHttpClientGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () => `${JETBRAINS_CHECKSUM}  jbrsdk-21.tar.gz\n`
+    } as any);
+
+    const distribution = new JetBrainsDistribution({
+      version: '21',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData as any;
+
+    const result = await distribution['findPackageForDownload']('21');
+
+    expect(result.checksum?.value).toBe(JETBRAINS_CHECKSUM);
+  });
+
+  it('falls back to a sha256 checksum for older JBR builds that only publish one', async () => {
+    // Older JBR 11 builds (e.g. jbrsdk_nomod-11_0_16-*-b2043.64.tar.gz) publish
+    // a SHA-256 digest at the generic `.checksum` sibling instead of SHA-512.
+    const sha256Checksum = 'a'.repeat(64);
+    spyHttpClientGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () =>
+        `${sha256Checksum}  jbrsdk_nomod-11_0_16-osx-x64-b2043.64.tar.gz\n`
+    } as any);
+
+    const distribution = new JetBrainsDistribution({
+      version: '21',
+      architecture: 'x64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData as any;
+
+    const result = await distribution['findPackageForDownload']('21');
+
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: sha256Checksum,
+      source: `${result.url}.checksum`
+    });
+  });
 });
--- a/tests/distributors/kona-installer.test.ts
+++ b/tests/distributors/kona-installer.test.ts
@@ -216,6 +216,15 @@ describe('Check findPackageForDownload', () => {
        await distribution['findPackageForDownload'](version);
      expect(availableRelease).not.toBeNull();
      expect(availableRelease.url).toBe(expectedUrl);
+      if (availableRelease.checksum) {
+        expect(availableRelease.checksum).toEqual({
+          algorithm: 'sha256',
+          value: expect.stringMatching(/^[a-f0-9]{64}$/),
+          source: 'https://tencent.github.io/konajdk/releases/kona-v1.json'
+        });
+      } else {
+        expect(version).toBe('8.0.20');
+      }
    }
  );
 });
--- a/tests/distributors/microsoft-installer.test.ts
+++ b/tests/distributors/microsoft-installer.test.ts
@@ -103,9 +103,12 @@ const util = await import('../../src/util.js');
 describe('findPackageForDownload', () => {
  let distribution: InstanceType<typeof MicrosoftDistributions>;
  let spyGetManifestFromRepo: any;
+  let spyHttpClientGet: any;
  let spyDebug: any;
  let spyCoreError: any;

+  const MICROSOFT_CHECKSUM = 'b'.repeat(64);
+
  beforeEach(() => {
    mockOsArch.mockReturnValue('x64');
    mockOsPlatform.mockReturnValue(process.platform);
@@ -124,6 +127,15 @@ describe('findPackageForDownload', () => {
      headers: {}
    });

+    // Every resolved release fetches `${download_url}.sha256sum.txt`; stub
+    // it with a GNU-style `<hex>  <filename>` payload so tests never reach
+    // the real network.
+    spyHttpClientGet = jest.spyOn(HttpClient.prototype, 'get');
+    spyHttpClientGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () => `${MICROSOFT_CHECKSUM}  microsoft-jdk.tar.gz\n`
+    });
+
    spyDebug = core.debug as jest.Mock;
    spyDebug.mockImplementation(() => {});

@@ -311,6 +323,34 @@ describe('findPackageForDownload', () => {
      'https://example.test/jdk.tar.gz.custom.sig'
    );
  });
+
+  it('fetches the authoritative sha256 checksum from the GNU-style sibling file', async () => {
+    mockOsPlatform.mockReturnValue(process.platform);
+
+    const result = await distribution['findPackageForDownload']('17.0.7');
+
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: MICROSOFT_CHECKSUM,
+      source: `${result.url}.sha256sum.txt`
+    });
+    expect(spyHttpClientGet).toHaveBeenCalledWith(
+      `${result.url}.sha256sum.txt`
+    );
+    expect(spyHttpClientGet).toHaveBeenCalledTimes(1);
+  });
+
+  it('parses only the first whitespace-delimited token from the GNU checksum payload', async () => {
+    spyHttpClientGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () =>
+        `${MICROSOFT_CHECKSUM}  microsoft-jdk-17.0.7-linux-x64.tar.gz\n`
+    });
+
+    const result = await distribution['findPackageForDownload']('17.0.7');
+
+    expect(result.checksum?.value).toBe(MICROSOFT_CHECKSUM);
+  });
 });

 describe('downloadTool', () => {
--- a/tests/distributors/openjdk-installer.test.ts
+++ b/tests/distributors/openjdk-installer.test.ts
@@ -50,6 +50,14 @@ const archivePage = `
  <th>9.0.4 (build 9.0.4+11)</th>
  <a href="https://download.java.net/java/GA/jdk9/9.0.4/binaries/openjdk-9.0.4_linux-x64_bin.tar.gz">tar.gz</a>
 `;
+const GA_CHECKSUM = 'c'.repeat(64);
+const EA_CHECKSUM = 'd'.repeat(64);
+const checksumPages: Record<string, string> = {
+  'https://download.java.net/java/GA/jdk26.0.2/hash/10/GPL/openjdk-26.0.2_linux-x64_bin.tar.gz.sha256':
+    GA_CHECKSUM,
+  'https://download.java.net/java/early_access/jdk27/32/GPL/openjdk-27-ea+32_linux-x64_bin.tar.gz.sha256':
+    EA_CHECKSUM
+};

 function createDistribution(
  version = '26',
@@ -82,8 +90,16 @@ describe('OpenJdkDistribution', () => {
          'https://jdk.java.net/27/': earlyAccessPage,
          'https://jdk.java.net/archive/': archivePage
        };
+        if (url in pages) {
+          return {
+            message: {statusCode: 200},
+            readBody: async () => pages[url]
+          } as Awaited<ReturnType<HttpClient['get']>>;
+        }
+        // Any other GET is a `${archiveUrl}.sha256` checksum sibling request.
        return {
-          readBody: async () => pages[url] ?? ''
+          message: {statusCode: 200},
+          readBody: async () => checksumPages[url] ?? 'e'.repeat(64)
        } as Awaited<ReturnType<HttpClient['get']>>;
      });
  });
@@ -97,8 +113,15 @@ describe('OpenJdkDistribution', () => {

    expect(result).toEqual({
      version: '26.0.2+10',
-      url: 'https://download.java.net/java/GA/jdk26.0.2/hash/10/GPL/openjdk-26.0.2_linux-x64_bin.tar.gz'
+      url: 'https://download.java.net/java/GA/jdk26.0.2/hash/10/GPL/openjdk-26.0.2_linux-x64_bin.tar.gz',
+      checksum: {
+        algorithm: 'sha256',
+        value: GA_CHECKSUM,
+        source:
+          'https://download.java.net/java/GA/jdk26.0.2/hash/10/GPL/openjdk-26.0.2_linux-x64_bin.tar.gz.sha256'
+      }
    });
+    expect(getSpy).toHaveBeenCalledWith(`${result.url}.sha256`);
  });

  it('resolves an archived GA release', async () => {
@@ -144,9 +167,16 @@ describe('OpenJdkDistribution', () => {

    expect(result).toEqual({
      version: '27.0.0+32',
-      url: 'https://download.java.net/java/early_access/jdk27/32/GPL/openjdk-27-ea+32_linux-x64_bin.tar.gz'
+      url: 'https://download.java.net/java/early_access/jdk27/32/GPL/openjdk-27-ea+32_linux-x64_bin.tar.gz',
+      checksum: {
+        algorithm: 'sha256',
+        value: EA_CHECKSUM,
+        source:
+          'https://download.java.net/java/early_access/jdk27/32/GPL/openjdk-27-ea+32_linux-x64_bin.tar.gz.sha256'
+      }
    });
    expect(getSpy).not.toHaveBeenCalledWith('https://jdk.java.net/archive/');
+    expect(getSpy).toHaveBeenCalledWith(`${result.url}.sha256`);
  });

  it('reports available versions when no release matches', async () => {
--- a/tests/distributors/oracle-installer.test.ts
+++ b/tests/distributors/oracle-installer.test.ts
@@ -47,8 +47,11 @@ describe('findPackageForDownload', () => {
  let distribution: InstanceType<typeof OracleDistribution>;
  let spyDebug: any;
  let spyHttpClient: any;
+  let spyHttpClientGet: any;
  let spyCoreError: any;

+  const ORACLE_CHECKSUM = 'f'.repeat(64);
+
  beforeEach(() => {
    distribution = new OracleDistribution({
      version: '',
@@ -63,6 +66,14 @@ describe('findPackageForDownload', () => {
    // Mock core.error to suppress error logs
    spyCoreError = core.error as jest.Mock;
    spyCoreError.mockImplementation(() => {});
+
+    // Every resolved release fetches its `${url}.sha256` sibling checksum;
+    // stub it so tests never reach the real network.
+    spyHttpClientGet = jest.spyOn(HttpClient.prototype, 'get');
+    spyHttpClientGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () => ORACLE_CHECKSUM
+    });
  });

  it.each([
@@ -133,6 +144,23 @@ describe('findPackageForDownload', () => {
    expect(result.url).toBe(url);
  });

+  it('fetches the authoritative sha256 checksum for the resolved archive', async () => {
+    spyHttpClient = jest.spyOn(HttpClient.prototype, 'head');
+    spyHttpClient.mockResolvedValue({message: {statusCode: 200}});
+
+    const result = await distribution['findPackageForDownload']('21');
+
+    jest.restoreAllMocks();
+
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: ORACLE_CHECKSUM,
+      source: `${result.url}.sha256`
+    });
+    expect(spyHttpClientGet).toHaveBeenCalledWith(`${result.url}.sha256`);
+    expect(spyHttpClientGet).toHaveBeenCalledTimes(1);
+  });
+
  it.each([
    ['amd64', 'x64'],
    ['arm64', 'aarch64']
@@ -196,6 +224,10 @@ describe('findPackageForDownload with latest', () => {
  it('resolves the newest major version from the Adoptium API', async () => {
    spyHttpClientHead = jest.spyOn(HttpClient.prototype, 'head');
    spyHttpClientHead.mockResolvedValue({message: {statusCode: 200}});
+    jest.spyOn(HttpClient.prototype, 'get').mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () => 'f'.repeat(64)
+    } as any);

    const distribution = new OracleDistribution({
      version: 'latest',
--- a/tests/distributors/sapmachine-installer.test.ts
+++ b/tests/distributors/sapmachine-installer.test.ts
@@ -52,8 +52,10 @@ const utils = await import('../../src/util.js');

 describe('getAvailableVersions', () => {
  let spyHttpClient: any;
+  let spyHttpGet: any;
  let spyUtilGetDownloadArchiveExtension: any;
  let spyCoreError: any;
+  const archiveChecksum = 'f'.repeat(64);

  beforeEach(() => {
    spyHttpClient = jest.spyOn(HttpClient.prototype, 'getJson');
@@ -62,6 +64,11 @@ describe('getAvailableVersions', () => {
      headers: {},
      result: manifestData
    });
+    spyHttpGet = jest.spyOn(HttpClient.prototype, 'get');
+    spyHttpGet.mockResolvedValue({
+      message: {statusCode: 200},
+      readBody: async () => `${archiveChecksum}  archive`
+    });

    spyUtilGetDownloadArchiveExtension =
      utils.getDownloadArchiveExtension as jest.Mock<any>;
@@ -282,9 +289,31 @@ describe('getAvailableVersions', () => {
          await distribution['findPackageForDownload'](normalizedVersion);
        expect(availableVersion).not.toBeNull();
        expect(availableVersion.url).toBe(expectedLink);
+        expect(availableVersion.checksum).toEqual({
+          algorithm: 'sha256',
+          value: archiveChecksum,
+          source: expectedLink.replace(/\.(?:tar\.gz|zip)$/, '.sha256.txt')
+        });
      }
    );

+    it('uses the checksum published beside the selected EA archive', async () => {
+      const distribution = new SapMachineDistribution({
+        version: '21-ea',
+        architecture: 'x64',
+        packageType: 'jdk',
+        checkLatest: false
+      });
+      mockPlatform(distribution, 'linux');
+
+      const release = await distribution['findPackageForDownload']('21');
+
+      expect(spyHttpGet).toHaveBeenCalledWith(
+        release.url.replace(/\.(?:tar\.gz|zip)$/, '.sha256.txt')
+      );
+      expect(release.checksum?.value).toBe(archiveChecksum);
+    });
+
    it.each([
      ['8', 'linux', 'x64'],
      ['8', 'macos', 'aarch64'],
--- a/tests/distributors/semeru-installer.test.ts
+++ b/tests/distributors/semeru-installer.test.ts
@@ -208,6 +208,14 @@ describe('findPackageForDownload', () => {
    distribution['getAvailableVersions'] = async () => manifestData as any;
    const resolvedVersion = await distribution['findPackageForDownload'](input);
    expect(resolvedVersion.version).toBe(expected);
+    const vendorPackage = (manifestData as any[]).find(
+      item => item.version_data.semver === expected
+    ).binaries[0].package;
+    expect(resolvedVersion.checksum).toEqual({
+      algorithm: 'sha256',
+      value: vendorPackage.checksum,
+      source: vendorPackage.checksum_link
+    });
  });

  it('version is found but binaries list is empty', async () => {
--- a/tests/distributors/temurin-installer.test.ts
+++ b/tests/distributors/temurin-installer.test.ts
@@ -347,6 +347,14 @@ describe('findPackageForDownload', () => {
    const resolvedVersion = await distribution['findPackageForDownload'](input);
    expect(resolvedVersion.version).toBe(expected);
    expect(resolvedVersion.signatureUrl).toBeDefined();
+    const vendorPackage = (manifestData as any[]).find(
+      item => item.version_data.semver === expected
+    ).binaries[0].package;
+    expect(resolvedVersion.checksum).toEqual({
+      algorithm: 'sha256',
+      value: vendorPackage.checksum,
+      source: vendorPackage.checksum_link
+    });
  });

  it('version "latest" is normalized to the newest available version', async () => {
--- a/tests/distributors/zulu-installer.test.ts
+++ b/tests/distributors/zulu-installer.test.ts
@@ -241,6 +241,26 @@ describe('getArchitectureOptions', () => {
 });

 describe('findPackageForDownload', () => {
+  let spyPackageDetails: any;
+
+  const ZULU_CHECKSUM = 'a'.repeat(64);
+
+  beforeEach(() => {
+    // The resolved winning package fetches sha256_hash from the Azul
+    // package-details endpoint; stub it so tests never reach the real
+    // network.
+    spyPackageDetails = jest.spyOn(HttpClient.prototype, 'getJson');
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {sha256_hash: ZULU_CHECKSUM}
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
  it.each([
    ['8', '8.0.282+8'],
    ['11.x', '11.0.10+9'],
@@ -279,6 +299,38 @@ describe('findPackageForDownload', () => {
    expect(result.url).toBe(
      'https://cdn.azul.com/zulu/bin/zulu11.35.15-ca-jdk11.0.5-macosx_x64.tar.gz'
    );
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: ZULU_CHECKSUM,
+      source: 'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-10933'
+    });
+    // Only the winning package's UUID triggers a details request.
+    expect(spyPackageDetails).toHaveBeenCalledWith(
+      'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-10933'
+    );
+    expect(spyPackageDetails).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips checksum verification when sha256_hash is missing or malformed', async () => {
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {sha256_hash: 'not-a-valid-digest'}
+    });
+
+    const distribution = new ZuluDistribution({
+      version: '',
+      architecture: 'x86',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData;
+    const result = await distribution['findPackageForDownload']('11.0.5');
+
+    expect(result.checksum).toBeUndefined();
+    expect(core.debug).toHaveBeenCalledWith(
+      expect.stringContaining('No authoritative sha256 checksum')
+    );
  });

  it('should throw an error', async () => {
--- a/tests/distributors/zulu-linux-installer.test.ts
+++ b/tests/distributors/zulu-linux-installer.test.ts
@@ -245,6 +245,26 @@ describe('getArchitectureOptions', () => {
 });

 describe('findPackageForDownload', () => {
+  let spyPackageDetails: any;
+
+  const ZULU_CHECKSUM = 'a'.repeat(64);
+
+  beforeEach(() => {
+    // The resolved winning package fetches sha256_hash from the Azul
+    // package-details endpoint; stub it so tests never reach the real
+    // network.
+    spyPackageDetails = jest.spyOn(HttpClient.prototype, 'getJson');
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {sha256_hash: ZULU_CHECKSUM}
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
  it.each([
    ['8', '8.0.282+8'],
    ['11.x', '11.0.10+9'],
@@ -283,6 +303,38 @@ describe('findPackageForDownload', () => {
    expect(result.url).toBe(
      'https://cdn.azul.com/zulu/bin/zulu21.32.17-ca-jdk21.0.2-linux_aarch64.tar.gz'
    );
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: ZULU_CHECKSUM,
+      source: 'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-12447'
+    });
+    // Only the winning package's UUID triggers a details request.
+    expect(spyPackageDetails).toHaveBeenCalledWith(
+      'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-12447'
+    );
+    expect(spyPackageDetails).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips checksum verification when sha256_hash is missing or malformed', async () => {
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {}
+    });
+
+    const distribution = new ZuluDistribution({
+      version: '',
+      architecture: 'arm64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData;
+    const result = await distribution['findPackageForDownload']('21.0.2');
+
+    expect(result.checksum).toBeUndefined();
+    expect(core.debug).toHaveBeenCalledWith(
+      expect.stringContaining('No authoritative sha256 checksum')
+    );
  });

  it('should throw an error', async () => {
--- a/tests/distributors/zulu-windows-installer.test.ts
+++ b/tests/distributors/zulu-windows-installer.test.ts
@@ -242,6 +242,26 @@ describe('getArchitectureOptions', () => {
 });

 describe('findPackageForDownload', () => {
+  let spyPackageDetails: any;
+
+  const ZULU_CHECKSUM = 'a'.repeat(64);
+
+  beforeEach(() => {
+    // The resolved winning package fetches sha256_hash from the Azul
+    // package-details endpoint; stub it so tests never reach the real
+    // network.
+    spyPackageDetails = jest.spyOn(HttpClient.prototype, 'getJson');
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {sha256_hash: ZULU_CHECKSUM}
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
  it.each([
    ['8', '8.0.282+8'],
    ['11.x', '11.0.10+9'],
@@ -280,6 +300,38 @@ describe('findPackageForDownload', () => {
    expect(result.url).toBe(
      'https://cdn.azul.com/zulu/bin/zulu17.48.15-ca-jdk17.0.10-windows_aarch64.zip'
    );
+    expect(result.checksum).toEqual({
+      algorithm: 'sha256',
+      value: ZULU_CHECKSUM,
+      source: 'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-12446'
+    });
+    // Only the winning package's UUID triggers a details request.
+    expect(spyPackageDetails).toHaveBeenCalledWith(
+      'https://api.azul.com/metadata/v1/zulu/packages/test-uuid-12446'
+    );
+    expect(spyPackageDetails).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips checksum verification when sha256_hash is missing or malformed', async () => {
+    spyPackageDetails.mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      result: {sha256_hash: '123'}
+    });
+
+    const distribution = new ZuluDistribution({
+      version: '',
+      architecture: 'arm64',
+      packageType: 'jdk',
+      checkLatest: false
+    });
+    distribution['getAvailableVersions'] = async () => manifestData;
+    const result = await distribution['findPackageForDownload']('17.0.10');
+
+    expect(result.checksum).toBeUndefined();
+    expect(core.debug).toHaveBeenCalledWith(
+      expect.stringContaining('No authoritative sha256 checksum')
+    );
  });

  it('should throw an error', async () => {
--- a/tests/java-package-contract.test.ts
+++ b/tests/java-package-contract.test.ts
@@ -0,0 +1,82 @@
+import fs from 'fs';
+import path from 'path';
+import {
+  JAVA_PACKAGE_CAPABILITIES,
+  JavaDistribution
+} from '../src/distributions/package-types.js';
+
+const repositoryRoot = process.cwd();
+const readRepositoryFile = (filePath: string) =>
+  fs.readFileSync(path.join(repositoryRoot, filePath), 'utf8');
+const allPackageTypes = [
+  ...new Set(Object.values(JAVA_PACKAGE_CAPABILITIES).flat())
+];
+
+describe('java-package published contract', () => {
+  it.each(['action.yml', 'README.md'])(
+    'documents every supported package type in %s',
+    filePath => {
+      const content = readRepositoryFile(filePath);
+      const contractLine =
+        filePath === 'action.yml'
+          ? content.match(/ {2}java-package:\n(?: {4}.+\n)+/)?.[0]
+          : content
+              .split('\n')
+              .find(line => line.includes('- `java-package`:'));
+
+      expect(contractLine).toBeDefined();
+      for (const packageType of allPackageTypes) {
+        expect(contractLine).toContain(`\`${packageType}\``);
+      }
+    }
+  );
+
+  it.each(Object.entries(JAVA_PACKAGE_CAPABILITIES))(
+    'keeps the advanced compatibility table aligned for %s',
+    (distributionName, packageTypes) => {
+      const advancedUsage = readRepositoryFile('docs/advanced-usage.md');
+      const compatibilityTable = advancedUsage.slice(
+        advancedUsage.indexOf('### Package compatibility')
+      );
+      const compatibilityRow = compatibilityTable
+        .split('\n')
+        .find(
+          line =>
+            line.startsWith('|') && line.includes(`\`${distributionName}\``)
+        );
+
+      expect(compatibilityRow).toBeDefined();
+      for (const packageType of packageTypes) {
+        expect(compatibilityRow).toContain(`\`${packageType}\``);
+      }
+    }
+  );
+
+  it('only exercises supported distribution/package combinations in E2E', () => {
+    const workflow = readRepositoryFile('.github/workflows/e2e-versions.yml');
+    const defaultMatrix = workflow.match(
+      /distribution:\s*\n\s*\[([^\]]+)\]\s*\n\s*java-package:\s*\['([^']+)'\]/
+    );
+    expect(defaultMatrix).not.toBeNull();
+
+    const defaultDistributions = [
+      ...defaultMatrix![1].matchAll(/'([^']+)'/g)
+    ].map(match => match[1]);
+    const defaultPackage = defaultMatrix![2];
+    for (const distributionName of defaultDistributions) {
+      expect(supportedPackagesFor(distributionName)).toContain(defaultPackage);
+    }
+
+    const includedPackages = workflow.matchAll(
+      /- distribution: '([^']+)'\s*\n\s*java-package: ([^\s]+)/g
+    );
+    for (const match of includedPackages) {
+      const [, distributionName, packageType] = match;
+      expect(supportedPackagesFor(distributionName)).toContain(packageType);
+    }
+  });
+});
+
+function supportedPackagesFor(distributionName: string): readonly string[] {
+  return JAVA_PACKAGE_CAPABILITIES[distributionName as JavaDistribution] ?? [];
+}
--- a/tests/retrying-http-client.test.ts
+++ b/tests/retrying-http-client.test.ts
@@ -0,0 +1,251 @@
+import {jest, describe, it, expect, beforeEach, afterEach} from '@jest/globals';
+import type {IncomingMessage} from 'http';
+
+jest.unstable_mockModule('@actions/core', () => ({
+  info: jest.fn()
+}));
+
+const core = await import('@actions/core');
+const httpm = await import('@actions/http-client');
+const {RetryingHttpClient, isRetryableNetworkError, parseRetryAfter} =
+  await import('../src/retrying-http-client.js');
+
+function response(
+  statusCode: number,
+  retryAfter?: string
+): httpm.HttpClientResponse {
+  return {
+    message: {
+      statusCode,
+      headers: retryAfter ? {'retry-after': retryAfter} : {}
+    } as IncomingMessage,
+    readBody: jest.fn(async () => '')
+  } as unknown as httpm.HttpClientResponse;
+}
+
+describe('RetryingHttpClient', () => {
+  let request: ReturnType<typeof jest.spyOn>;
+  let sleep: jest.Mock<(delayMs: number) => Promise<void>>;
+
+  beforeEach(() => {
+    request = jest.spyOn(httpm.HttpClient.prototype, 'request');
+    sleep = jest.fn(async () => undefined);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    jest.clearAllMocks();
+  });
+
+  it('uses exponential backoff with jitter for retryable responses', async () => {
+    request
+      .mockResolvedValueOnce(response(503))
+      .mockResolvedValueOnce(response(502))
+      .mockResolvedValueOnce(response(200));
+    const client = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0,
+      baseDelayMs: 1000,
+      maxDelayMs: 10000
+    });
+
+    await expect(client.get('https://example.com')).resolves.toBeDefined();
+
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenNthCalledWith(1, 500);
+    expect(sleep).toHaveBeenNthCalledWith(2, 1000);
+    expect(core.info).toHaveBeenNthCalledWith(
+      1,
+      'Request attempt 1 of 4 failed (HTTP 503); retrying in 500 ms'
+    );
+    expect(core.info).toHaveBeenNthCalledWith(
+      2,
+      'Request attempt 2 of 4 failed (HTTP 502); retrying in 1000 ms'
+    );
+  });
+
+  it('honors Retry-After delta-seconds over the client delay', async () => {
+    request
+      .mockResolvedValueOnce(response(429, '3'))
+      .mockResolvedValueOnce(response(200));
+    const client = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0
+    });
+
+    await client.get('https://example.com');
+
+    expect(sleep).toHaveBeenCalledWith(3000);
+  });
+
+  it('honors Retry-After HTTP dates over the client delay', async () => {
+    const now = Date.parse('2026-07-29T00:00:00Z');
+    request
+      .mockResolvedValueOnce(response(503, new Date(now + 5000).toUTCString()))
+      .mockResolvedValueOnce(response(200));
+    const client = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0,
+      now: () => now
+    });
+
+    await client.get('https://example.com');
+
+    expect(sleep).toHaveBeenCalledWith(5000);
+  });
+
+  it('caps Retry-After at the configured maximum delay', async () => {
+    request
+      .mockResolvedValueOnce(response(429, '60'))
+      .mockResolvedValueOnce(response(200));
+    const client = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0,
+      maxDelayMs: 10000
+    });
+
+    await client.get('https://example.com');
+
+    expect(sleep).toHaveBeenCalledWith(10000);
+  });
+
+  it.each([429, 502, 503, 504, 522])(
+    'retries HTTP %s responses',
+    async statusCode => {
+      request
+        .mockResolvedValueOnce(response(statusCode))
+        .mockResolvedValueOnce(response(200));
+      const client = new RetryingHttpClient('test', {
+        sleep,
+        random: () => 0
+      });
+
+      await client.get('https://example.com');
+
+      expect(request).toHaveBeenCalledTimes(2);
+    }
+  );
+
+  it.each(['ETIMEDOUT', 'ECONNRESET', 'ENOTFOUND', 'ECONNREFUSED'])(
+    'retries network errors with code %s',
+    async code => {
+      request
+        .mockRejectedValueOnce(Object.assign(new Error(code), {code}))
+        .mockResolvedValueOnce(response(200));
+      const client = new RetryingHttpClient('test', {
+        sleep,
+        random: () => 0
+      });
+
+      await client.get('https://example.com');
+
+      expect(request).toHaveBeenCalledTimes(2);
+    }
+  );
+
+  it('retries retryable aggregate network errors', async () => {
+    const aggregateError = Object.assign(new Error('connection failed'), {
+      errors: [Object.assign(new Error('timed out'), {code: 'ETIMEDOUT'})]
+    });
+    request
+      .mockRejectedValueOnce(aggregateError)
+      .mockResolvedValueOnce(response(200));
+    const client = new RetryingHttpClient('test', {
+      sleep,
+      random: () => 0
+    });
+
+    await client.get('https://example.com');
+
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledWith(500);
+  });
+
+  it('does not retry non-retryable responses or network errors', async () => {
+    request.mockResolvedValueOnce(response(500));
+    const client = new RetryingHttpClient('test', {sleep});
+
+    await expect(client.get('https://example.com')).resolves.toBeDefined();
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+
+    request.mockRejectedValueOnce(
+      Object.assign(new Error('certificate failed'), {code: 'CERT_HAS_EXPIRED'})
+    );
+    await expect(client.get('https://example.com')).rejects.toThrow(
+      'certificate failed'
+    );
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it('stops after the configured total attempt count', async () => {
+    request
+      .mockResolvedValueOnce(response(503))
+      .mockResolvedValueOnce(response(503));
+    const client = new RetryingHttpClient('test', {
+      maxAttempts: 2,
+      sleep,
+      random: () => 0
+    });
+
+    const finalResponse = await client.get('https://example.com');
+
+    expect(finalResponse.message.statusCode).toBe(503);
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it('propagates the final network error after exhausting attempts', async () => {
+    const finalError = Object.assign(new Error('still unavailable'), {
+      code: 'ECONNREFUSED'
+    });
+    request
+      .mockRejectedValueOnce(
+        Object.assign(new Error('unavailable'), {code: 'ECONNREFUSED'})
+      )
+      .mockRejectedValueOnce(finalError);
+    const client = new RetryingHttpClient('test', {
+      maxAttempts: 2,
+      sleep,
+      random: () => 0
+    });
+
+    await expect(client.get('https://example.com')).rejects.toBe(finalError);
+
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not retry write requests', async () => {
+    request.mockResolvedValueOnce(response(503));
+    const client = new RetryingHttpClient('test', {sleep});
+
+    await client.post('https://example.com', '{}');
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+});
+
+describe('retry classification', () => {
+  it('parses valid Retry-After values and ignores invalid or past values', () => {
+    const now = Date.parse('2026-07-29T00:00:00Z');
+
+    expect(parseRetryAfter('7', now)).toBe(7000);
+    expect(parseRetryAfter(new Date(now + 3000).toUTCString(), now)).toBe(3000);
+    expect(parseRetryAfter(new Date(now - 3000).toUTCString(), now)).toBe(
+      undefined
+    );
+    expect(parseRetryAfter('not-a-date', now)).toBe(undefined);
+  });
+
+  it('recognizes direct and nested retryable network error codes', () => {
+    expect(isRetryableNetworkError({code: 'ECONNRESET'})).toBe(true);
+    expect(
+      isRetryableNetworkError({errors: [{code: 'ENOTFOUND'}, {code: 'OTHER'}]})
+    ).toBe(true);
+    expect(isRetryableNetworkError({code: 'CERT_HAS_EXPIRED'})).toBe(false);
+    expect(isRetryableNetworkError(new Error('unknown'))).toBe(false);
+  });
+});
--- a/tests/setup-java.test.ts
+++ b/tests/setup-java.test.ts
@@ -0,0 +1,409 @@
+import {jest, describe, it, expect, beforeEach} from '@jest/globals';
+
+jest.unstable_mockModule('@actions/core', () => ({
+  info: jest.fn(),
+  warning: jest.fn(),
+  debug: jest.fn(),
+  error: jest.fn(),
+  notice: jest.fn(),
+  setFailed: jest.fn(),
+  setOutput: jest.fn(),
+  getInput: jest.fn(),
+  getBooleanInput: jest.fn(),
+  getMultilineInput: jest.fn(),
+  addPath: jest.fn(),
+  exportVariable: jest.fn(),
+  saveState: jest.fn(),
+  getState: jest.fn(),
+  setSecret: jest.fn(),
+  isDebug: jest.fn(() => false),
+  startGroup: jest.fn(),
+  endGroup: jest.fn(),
+  group: jest.fn((_name: string, fn: () => Promise<unknown>) => fn()),
+  toPlatformPath: jest.fn((value: string) => value),
+  toWin32Path: jest.fn((value: string) => value),
+  toPosixPath: jest.fn((value: string) => value)
+}));
+
+jest.unstable_mockModule('fs', () => ({
+  default: {
+    readFileSync: jest.fn()
+  }
+}));
+
+jest.unstable_mockModule('../src/util.js', () => ({
+  getBooleanInput: jest.fn(),
+  isCacheFeatureAvailable: jest.fn(),
+  getVersionFromFileContent: jest.fn()
+}));
+
+jest.unstable_mockModule('../src/toolchains.js', () => ({
+  validateToolchainIds: jest.fn(),
+  configureToolchains: jest.fn()
+}));
+
+jest.unstable_mockModule('../src/cache.js', () => ({
+  restore: jest.fn()
+}));
+
+jest.unstable_mockModule(
+  '../src/distributions/distribution-factory.js',
+  () => ({
+    getJavaDistribution: jest.fn()
+  })
+);
+
+jest.unstable_mockModule('../src/auth.js', () => ({
+  configureAuthentication: jest.fn()
+}));
+
+jest.unstable_mockModule('../src/maven-args.js', () => ({
+  configureMavenArgs: jest.fn()
+}));
+
+jest.unstable_mockModule('../src/problem-matcher.js', () => ({
+  configureProblemMatcher: jest.fn()
+}));
+
+const core = await import('@actions/core');
+const fs = (await import('fs')).default;
+const util = await import('../src/util.js');
+const toolchains = await import('../src/toolchains.js');
+const cache = await import('../src/cache.js');
+const factory = await import('../src/distributions/distribution-factory.js');
+const auth = await import('../src/auth.js');
+const mavenArgs = await import('../src/maven-args.js');
+const problemMatcher = await import('../src/problem-matcher.js');
+const {run} = await import('../src/setup-java.js');
+
+const inputCallsOnImport = (core.getInput as jest.Mock).mock.calls.length;
+const multilineInputCallsOnImport = (core.getMultilineInput as jest.Mock).mock
+  .calls.length;
+
+describe('setup action orchestration', () => {
+  const inputs = new Map<string, string>();
+  const multilineInputs = new Map<string, string[]>();
+  const booleanInputs = new Map<string, boolean>();
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    inputs.clear();
+    multilineInputs.clear();
+    booleanInputs.clear();
+
+    (core.getInput as jest.Mock).mockImplementation((name: unknown) => {
+      return inputs.get(name as string) ?? '';
+    });
+    (core.getMultilineInput as jest.Mock).mockImplementation(
+      (name: unknown) => {
+        return multilineInputs.get(name as string) ?? [];
+      }
+    );
+    (util.getBooleanInput as jest.Mock).mockImplementation(
+      (name: unknown, defaultValue: unknown) => {
+        return booleanInputs.get(name as string) ?? defaultValue;
+      }
+    );
+    (util.isCacheFeatureAvailable as jest.Mock).mockReturnValue(true);
+    (toolchains.configureToolchains as jest.Mock).mockResolvedValue(undefined);
+    (auth.configureAuthentication as jest.Mock).mockResolvedValue(undefined);
+    (cache.restore as jest.Mock).mockResolvedValue(undefined);
+  });
+
+  it('does not execute the action when imported', () => {
+    expect(inputCallsOnImport).toBe(0);
+    expect(multilineInputCallsOnImport).toBe(0);
+  });
+
+  it('requires java-version or java-version-file', async () => {
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith(
+      'java-version or java-version-file input expected'
+    );
+    expect(factory.getJavaDistribution).not.toHaveBeenCalled();
+    expect(problemMatcher.configureProblemMatcher).not.toHaveBeenCalled();
+  });
+
+  it('requires distribution when java-version is provided', async () => {
+    multilineInputs.set('java-version', ['21']);
+
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith(
+      'distribution input is required'
+    );
+    expect(factory.getJavaDistribution).not.toHaveBeenCalled();
+  });
+
+  it('requires distribution when it cannot be inferred from the version file', async () => {
+    inputs.set('java-version-file', '.java-version');
+    (fs.readFileSync as jest.Mock).mockReturnValue(Buffer.from('21'));
+    (util.getVersionFromFileContent as jest.Mock).mockReturnValue({
+      version: '21'
+    });
+
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith(
+      'distribution input is required when not specified in the version file'
+    );
+    expect(factory.getJavaDistribution).not.toHaveBeenCalled();
+  });
+
+  it('fails when the version file has no supported version', async () => {
+    inputs.set('java-version-file', '.java-version');
+    inputs.set('distribution', 'temurin');
+    (fs.readFileSync as jest.Mock).mockReturnValue(Buffer.from('invalid'));
+    (util.getVersionFromFileContent as jest.Mock).mockReturnValue(undefined);
+
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith(
+      'No supported version was found in file .java-version'
+    );
+    expect(factory.getJavaDistribution).not.toHaveBeenCalled();
+  });
+
+  it('uses the distribution inferred from a version file', async () => {
+    inputs.set('java-version-file', '.sdkmanrc');
+    inputs.set('architecture', 'x64');
+    inputs.set('java-package', 'jdk');
+    inputs.set('distribution', 'zulu');
+    inputs.set('jdk-file', '/tmp/java.tar.gz');
+    multilineInputs.set('mvn-toolchain-id', ['file-jdk']);
+    booleanInputs.set('check-latest', true);
+    booleanInputs.set('force-download', true);
+    booleanInputs.set('set-default', false);
+    booleanInputs.set('verify-signature', true);
+    inputs.set('verify-signature-public-key', 'public-key');
+    (fs.readFileSync as jest.Mock).mockReturnValue(
+      Buffer.from('java=21.0.5-tem')
+    );
+    (util.getVersionFromFileContent as jest.Mock).mockReturnValue({
+      version: '21.0.5',
+      distribution: 'temurin'
+    });
+    const setupJava = jest.fn(async () => ({
+      version: '21.0.5+11',
+      path: '/opt/java/21'
+    }));
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({setupJava});
+
+    await run();
+
+    expect(util.getVersionFromFileContent).toHaveBeenCalledWith(
+      'java=21.0.5-tem',
+      'zulu',
+      '.sdkmanrc'
+    );
+    expect(factory.getJavaDistribution).toHaveBeenCalledWith(
+      'temurin',
+      {
+        version: '21.0.5',
+        architecture: 'x64',
+        packageType: 'jdk',
+        checkLatest: true,
+        forceDownload: true,
+        setDefault: false,
+        verifySignature: true,
+        verifySignaturePublicKey: 'public-key'
+      },
+      '/tmp/java.tar.gz'
+    );
+    expect(toolchains.validateToolchainIds).toHaveBeenCalledWith(
+      [],
+      '.sdkmanrc',
+      ['file-jdk']
+    );
+    expect(toolchains.configureToolchains).toHaveBeenCalledWith(
+      '21.0.5',
+      'temurin',
+      '/opt/java/21',
+      'file-jdk'
+    );
+    expect(core.setFailed).not.toHaveBeenCalled();
+  });
+
+  it('installs multiple JDKs in order with matching toolchain IDs', async () => {
+    inputs.set('distribution', 'temurin');
+    inputs.set('architecture', 'x64');
+    inputs.set('java-package', 'jdk');
+    multilineInputs.set('java-version', ['17', '21']);
+    multilineInputs.set('mvn-toolchain-id', ['java-17', 'java-21']);
+
+    const setupJava17 = jest.fn(async () => ({
+      version: '17.0.12+7',
+      path: '/opt/java/17'
+    }));
+    const setupJava21 = jest.fn(async () => ({
+      version: '21.0.4+7',
+      path: '/opt/java/21'
+    }));
+    (factory.getJavaDistribution as jest.Mock)
+      .mockReturnValueOnce({setupJava: setupJava17})
+      .mockReturnValueOnce({setupJava: setupJava21});
+
+    await run();
+
+    expect(factory.getJavaDistribution).toHaveBeenNthCalledWith(
+      1,
+      'temurin',
+      expect.objectContaining({version: '17'}),
+      ''
+    );
+    expect(factory.getJavaDistribution).toHaveBeenNthCalledWith(
+      2,
+      'temurin',
+      expect.objectContaining({version: '21'}),
+      ''
+    );
+    expect(toolchains.configureToolchains).toHaveBeenNthCalledWith(
+      1,
+      '17',
+      'temurin',
+      '/opt/java/17',
+      'java-17'
+    );
+    expect(toolchains.configureToolchains).toHaveBeenNthCalledWith(
+      2,
+      '21',
+      'temurin',
+      '/opt/java/21',
+      'java-21'
+    );
+    expect(setupJava17.mock.invocationCallOrder[0]).toBeLessThan(
+      setupJava21.mock.invocationCallOrder[0]
+    );
+  });
+
+  it('uses the resolved version for the latest Maven toolchain', async () => {
+    inputs.set('distribution', 'temurin');
+    multilineInputs.set('java-version', ['latest']);
+    const setupJava = jest.fn(async () => ({
+      version: '24.0.2+12',
+      path: '/opt/java/24'
+    }));
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({setupJava});
+
+    await run();
+
+    expect(toolchains.configureToolchains).toHaveBeenCalledWith(
+      '24.0.2+12',
+      'temurin',
+      '/opt/java/24',
+      undefined
+    );
+  });
+
+  it('configures post-install collaborators in order and restores the cache last', async () => {
+    inputs.set('distribution', 'temurin');
+    inputs.set('cache', 'maven');
+    inputs.set('cache-dependency-path', '**/pom.xml');
+    multilineInputs.set('java-version', ['21']);
+    const setupJava = jest.fn(async () => ({
+      version: '21.0.4+7',
+      path: '/opt/java/21'
+    }));
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({setupJava});
+
+    await run();
+
+    expect(problemMatcher.configureProblemMatcher).toHaveBeenCalledWith(
+      expect.stringMatching(/\.github[/\\]java\.json$/)
+    );
+    expect(cache.restore).toHaveBeenCalledWith('maven', '**/pom.xml');
+    expect(
+      (toolchains.configureToolchains as jest.Mock).mock.invocationCallOrder[0]
+    ).toBeLessThan(
+      (problemMatcher.configureProblemMatcher as jest.Mock).mock
+        .invocationCallOrder[0]
+    );
+    expect(
+      (problemMatcher.configureProblemMatcher as jest.Mock).mock
+        .invocationCallOrder[0]
+    ).toBeLessThan(
+      (auth.configureAuthentication as jest.Mock).mock.invocationCallOrder[0]
+    );
+    expect(
+      (auth.configureAuthentication as jest.Mock).mock.invocationCallOrder[0]
+    ).toBeLessThan(
+      (mavenArgs.configureMavenArgs as jest.Mock).mock.invocationCallOrder[0]
+    );
+    expect(
+      (mavenArgs.configureMavenArgs as jest.Mock).mock.invocationCallOrder[0]
+    ).toBeLessThan((cache.restore as jest.Mock).mock.invocationCallOrder[0]);
+  });
+
+  it('skips cache restoration when the cache feature is unavailable', async () => {
+    inputs.set('distribution', 'temurin');
+    inputs.set('cache', 'maven');
+    multilineInputs.set('java-version', ['21']);
+    (util.isCacheFeatureAvailable as jest.Mock).mockReturnValue(false);
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({
+      setupJava: jest.fn(async () => ({
+        version: '21.0.4+7',
+        path: '/opt/java/21'
+      }))
+    });
+
+    await run();
+
+    expect(cache.restore).not.toHaveBeenCalled();
+  });
+
+  it('reports unsupported distributions through core.setFailed', async () => {
+    inputs.set('distribution', 'unsupported');
+    multilineInputs.set('java-version', ['21']);
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue(null);
+
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith(
+      'No supported distribution was found for input unsupported'
+    );
+    expect(toolchains.configureToolchains).not.toHaveBeenCalled();
+    expect(problemMatcher.configureProblemMatcher).not.toHaveBeenCalled();
+  });
+
+  it('reports collaborator failures and stops post-install configuration', async () => {
+    inputs.set('distribution', 'temurin');
+    multilineInputs.set('java-version', ['21']);
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({
+      setupJava: jest.fn(async () => {
+        throw new Error('download failed');
+      })
+    });
+
+    await run();
+
+    expect(core.setFailed).toHaveBeenCalledWith('download failed');
+    expect(toolchains.configureToolchains).not.toHaveBeenCalled();
+    expect(problemMatcher.configureProblemMatcher).not.toHaveBeenCalled();
+    expect(auth.configureAuthentication).not.toHaveBeenCalled();
+    expect(mavenArgs.configureMavenArgs).not.toHaveBeenCalled();
+    expect(cache.restore).not.toHaveBeenCalled();
+  });
+
+  it('reports post-install failures and skips later collaborators', async () => {
+    inputs.set('distribution', 'temurin');
+    inputs.set('cache', 'maven');
+    multilineInputs.set('java-version', ['21']);
+    (factory.getJavaDistribution as jest.Mock).mockReturnValue({
+      setupJava: jest.fn(async () => ({
+        version: '21.0.4+7',
+        path: '/opt/java/21'
+      }))
+    });
+    (auth.configureAuthentication as jest.Mock).mockRejectedValue(
+      new Error('authentication failed')
+    );
+
+    await run();
+
+    expect(problemMatcher.configureProblemMatcher).toHaveBeenCalled();
+    expect(core.setFailed).toHaveBeenCalledWith('authentication failed');
+    expect(mavenArgs.configureMavenArgs).not.toHaveBeenCalled();
+    expect(cache.restore).not.toHaveBeenCalled();
+  });
+});
--- a/tests/toolchains.test.ts
+++ b/tests/toolchains.test.ts
@@ -1007,3 +1007,67 @@ describe('toolchains tests', () => {
    expect((contents.match(/<toolchain>/g) || []).length).toBe(runs.length);
  }, 100000);
 });
+
+describe('validateToolchainIds', () => {
+  it.each([
+    {
+      name: 'uses generated IDs when no custom IDs are supplied',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: []
+    },
+    {
+      name: 'accepts one custom ID for a single Java version',
+      versions: ['21'],
+      versionFile: '',
+      toolchainIds: ['custom-21']
+    },
+    {
+      name: 'accepts one custom ID per Java version',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: ['custom-17', 'custom-21']
+    },
+    {
+      name: 'accepts one custom ID with java-version-file',
+      versions: [],
+      versionFile: '.java-version',
+      toolchainIds: ['custom-file-version']
+    }
+  ])('$name', ({versions, versionFile, toolchainIds}) => {
+    expect(() =>
+      toolchains.validateToolchainIds(versions, versionFile, toolchainIds)
+    ).not.toThrow();
+  });
+
+  it.each([
+    {
+      name: 'rejects fewer IDs than Java versions',
+      versions: ['17', '21'],
+      versionFile: '',
+      toolchainIds: ['custom-17'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (1) must match the number of Java versions (2)'
+    },
+    {
+      name: 'rejects extra IDs for a single Java version',
+      versions: ['21'],
+      versionFile: '',
+      toolchainIds: ['custom-21', 'custom-extra'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (2) must match the number of Java versions (1)'
+    },
+    {
+      name: 'rejects extra IDs with java-version-file',
+      versions: [],
+      versionFile: '.java-version',
+      toolchainIds: ['custom-file-version', 'custom-extra'],
+      expectedMessage:
+        'The number of Maven toolchain IDs (2) must match the number of Java versions (1)'
+    }
+  ])('$name', ({versions, versionFile, toolchainIds, expectedMessage}) => {
+    expect(() =>
+      toolchains.validateToolchainIds(versions, versionFile, toolchainIds)
+    ).toThrow(expectedMessage);
+  });
+});
--- a/tests/util.test.ts
+++ b/tests/util.test.ts
@@ -57,9 +57,73 @@ const {
  isCacheFeatureAvailable,
  isGhes,
  validatePaginationUrl,
-  getLatestMajorVersion
+  getLatestMajorVersion,
+  getBooleanInput
 } = await import('../src/util.js');

+describe('getBooleanInput', () => {
+  let inputs: Record<string, string>;
+
+  beforeEach(() => {
+    inputs = {};
+    (core.getInput as jest.Mock).mockImplementation(
+      (name: string) => inputs[name] ?? ''
+    );
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it.each([
+    ['true', true],
+    ['TRUE', true],
+    ['TrUe', true],
+    [' true ', true],
+    ['false', false],
+    ['FALSE', false],
+    ['FaLsE', false],
+    [' false ', false]
+  ])('parses %j as %s', (value: string, expected: boolean) => {
+    inputs['boolean-input'] = value;
+
+    expect(getBooleanInput('boolean-input')).toBe(expected);
+  });
+
+  it.each([
+    [undefined, false],
+    [false, false],
+    [true, true]
+  ])(
+    'uses the configured default %s when the input is omitted',
+    (defaultValue: boolean | undefined, expected: boolean) => {
+      expect(getBooleanInput('boolean-input', defaultValue)).toBe(expected);
+    }
+  );
+
+  it('uses the configured default for a whitespace-only input', () => {
+    inputs['boolean-input'] = '   ';
+
+    expect(getBooleanInput('boolean-input', true)).toBe(true);
+  });
+
+  it.each([
+    'check-latest',
+    'force-download',
+    'set-default',
+    'verify-signature',
+    'overwrite-settings',
+    'show-download-progress',
+    'problem-matcher'
+  ])('rejects an invalid value for %s', inputName => {
+    inputs[inputName] = 'ture';
+
+    expect(() => getBooleanInput(inputName)).toThrow(
+      `Invalid value 'ture' for boolean input '${inputName}'. Expected 'true' or 'false'.`
+    );
+  });
+});
+
 describe('isVersionSatisfies', () => {
  it.each([
    ['x', '11.0.0', true],
--- a/action.yml
+++ b/action.yml
@@ -13,7 +13,7 @@ inputs:
    description: 'Java distribution. See the list of supported distributions in README file. This input is required except when java-version-file points to .sdkmanrc with a recognized distribution suffix (e.g., java=21.0.5-tem).'
    required: false
  java-package:
-    description: 'The package type (jdk, jre, jdk+fx, jre+fx, jdk+crac, jre+crac, jdk+jmods)'
+    description: 'The package type (`jdk`, `jre`, `jdk+fx`, `jre+fx`, `jdk+crac`, `jre+crac`, `jdk+jmods`, `jdk+jcef`, `jre+jcef`, `jdk+ft`, or `jre+ft`). Supported values vary by distribution.'
    required: false
    default: 'jdk'
  architecture:
@@ -96,7 +96,7 @@ inputs:
    required: false
    default: ${{ github.server_url == 'https://github.com' && github.token || '' }}
  mvn-toolchain-id:
-    description: 'Name of Maven Toolchain ID if the default name of "${distribution}_${java-version}" is not wanted. See examples of supported syntax in Advanced Usage file'
+    description: 'Name of Maven Toolchain ID if the default name of "${distribution}_${java-version}" is not wanted. When supplied, the number of IDs must match the number of Java versions. See examples of supported syntax in Advanced Usage file'
    required: false
  mvn-toolchain-vendor:
    description: 'Name of Maven Toolchain Vendor if the default name of "${distribution}" is not wanted. See examples of supported syntax in Advanced Usage file'
--- a/dist/cleanup/index.js
+++ b/dist/cleanup/index.js
@@ -97365,7 +97365,18 @@ function getTempDir() {
    return tempDirectory;
 }
 function util_getBooleanInput(inputName, defaultValue = false) {
-    return ((core.getInput(inputName) || String(defaultValue)).toUpperCase() === 'TRUE');
+    const inputValue = core.getInput(inputName);
+    const normalizedValue = inputValue.trim().toLowerCase();
+    if (!normalizedValue) {
+        return defaultValue;
+    }
+    if (normalizedValue === 'true') {
+        return true;
+    }
+    if (normalizedValue === 'false') {
+        return false;
+    }
+    throw new Error(`Invalid value '${inputValue}' for boolean input '${inputName}'. Expected 'true' or 'false'.`);
 }
 function getVersionFromToolcachePath(toolPath) {
    if (toolPath) {
--- a/dist/setup/index.js
+++ b/dist/setup/index.js
--- a/docs/advanced-usage.md
+++ b/docs/advanced-usage.md
@@ -321,12 +321,10 @@ The package types have these meanings:
 | `graalvm-community` | `jdk` | Stable GraalVM Community releases for JDK 17 and later only. |
 | `jetbrains` | `jdk`, `jre`, `jdk+jcef`, `jre+jcef`, `jdk+ft`, `jre+ft` | JetBrains publishes selected LTS-based releases rather than every OpenJDK patch. JDK/JRE and JCEF bundles start with the Java 11 release family; FreeType bundles start with Java 17. Exact package, LTS family, patch, OS, and architecture availability is determined from release assets. |
 | `kona` | `jdk` | Stable Java 8, 11, 17, 21, and 25 releases only. |
-| `jdkfile` | `jdk` (recommended) | The package contents and version are supplied by `jdk-file`; `setup-java` does not validate them. `java-package` only separates the local archive's tool-cache entry, so use `jdk` unless separate cache namespaces are required. |
+| `jdkfile` | `jdk` | The package contents and version are supplied by `jdk-file`; `setup-java` validates the package type but does not inspect the archive contents. |

-Values outside this table are unsupported even when a distribution forwards the
-value to its vendor API instead of rejecting it immediately. In that case, the
-action normally fails with a version-not-found error because no matching
-artifact exists.
+Values outside this table are unsupported. The action rejects them before
+checking the tool cache or requesting a vendor catalog.

 ```yaml
 steps:
@@ -980,7 +978,7 @@ steps:
  - run: java --version
 ```

-In case you install multiple versions of Java at once you can use the same syntax as used in `java-versions`. Please note that you have to declare an ID for all Java versions that will be installed or the `mvn-toolchain-id` instruction will be skipped wholesale due to mapping ambiguities.
+When installing multiple Java versions, use the same multiline syntax as `java-version`. You must declare exactly one ID for every Java version that will be installed. The action fails before installing a JDK unless the number of `mvn-toolchain-id` entries matches the number of `java-version` entries, or is exactly one when `java-version-file` is used.

 ```yaml
 steps:
--- a/src/checksum.ts
+++ b/src/checksum.ts
@@ -0,0 +1,83 @@
+import {createHash, timingSafeEqual} from 'crypto';
+import {createReadStream} from 'fs';
+import {pipeline} from 'stream/promises';
+
+import {ChecksumMetadata} from './distributions/base-models.js';
+
+export interface ChecksumVerificationContext {
+  distribution: string;
+  version: string;
+}
+
+function sanitizedSource(source: string | undefined): string {
+  if (!source) {
+    return '';
+  }
+
+  try {
+    const url = new URL(source);
+    return ` from ${url.origin}${url.pathname}`;
+  } catch {
+    return ' from an invalid checksum source';
+  }
+}
+
+// Length, in hex characters, of a digest produced by each supported algorithm.
+// Exported so callers (e.g. fetchChecksum) can infer which algorithm a vendor
+// actually used when it doesn't disclose it via the checksum URL/filename.
+export function expectedDigestLength(
+  algorithm: ChecksumMetadata['algorithm']
+): number {
+  return algorithm === 'sha256' ? 64 : algorithm === 'sha512' ? 128 : 0;
+}
+
+function normalizeExpectedDigest(checksum: ChecksumMetadata): string {
+  const algorithm = checksum.algorithm;
+  const digest =
+    typeof checksum.value === 'string'
+      ? checksum.value.trim().toLowerCase()
+      : '';
+  const expectedLength = expectedDigestLength(algorithm);
+
+  if (expectedLength === 0) {
+    throw new Error(
+      `Unsupported checksum algorithm '${String(algorithm)}'${sanitizedSource(checksum.source)}. Supported algorithms are sha256 and sha512.`
+    );
+  }
+
+  if (!new RegExp(`^[a-f0-9]{${expectedLength}}$`).test(digest)) {
+    throw new Error(
+      `Malformed ${algorithm} checksum metadata${sanitizedSource(checksum.source)}: expected a ${expectedLength}-character hexadecimal digest.`
+    );
+  }
+
+  return digest;
+}
+
+export async function calculateChecksum(
+  filePath: string,
+  algorithm: ChecksumMetadata['algorithm']
+): Promise<string> {
+  const hash = createHash(algorithm);
+  await pipeline(createReadStream(filePath), hash);
+  return hash.digest('hex');
+}
+
+export async function verifyChecksum(
+  filePath: string,
+  checksum: ChecksumMetadata,
+  context: ChecksumVerificationContext
+): Promise<void> {
+  const expected = normalizeExpectedDigest(checksum);
+  const actual = await calculateChecksum(filePath, checksum.algorithm);
+  const matches = timingSafeEqual(
+    Buffer.from(expected, 'hex'),
+    Buffer.from(actual, 'hex')
+  );
+
+  if (!matches) {
+    throw new Error(
+      `Checksum verification failed for ${context.distribution} version ${context.version}: ${checksum.algorithm} expected ${expected}, actual ${actual}.`
+    );
+  }
+}
--- a/src/distributions/adopt/installer.ts
+++ b/src/distributions/adopt/installer.ts
@@ -105,7 +105,12 @@ export class AdoptDistribution extends JavaBase {
      .map(item => {
        return {
          version: item.version_data.semver,
-          url: item.binaries[0].package.link
+          url: item.binaries[0].package.link,
+          checksum: {
+            algorithm: 'sha256',
+            value: item.binaries[0].package.checksum,
+            source: item.binaries[0].package.checksum_link
+          }
        } as JavaDownloadRelease;
      });

@@ -133,7 +138,7 @@ export class AdoptDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/base-installer.ts
+++ b/src/distributions/base-installer.ts
@@ -10,12 +10,16 @@ import {
  isVersionSatisfies
 } from '../util.js';
 import {
+  ChecksumAlgorithm,
+  ChecksumMetadata,
  JavaDownloadRelease,
  JavaInstallerOptions,
  JavaInstallerResults
 } from './base-models.js';
 import {MACOS_JAVA_CONTENT_POSTFIX} from '../constants.js';
+import {RetryingHttpClient} from '../retrying-http-client.js';
 import os from 'os';
+import {expectedDigestLength, verifyChecksum} from '../checksum.js';

 export abstract class JavaBase {
  protected http: httpm.HttpClient;
@@ -34,10 +38,7 @@ export abstract class JavaBase {
    protected distribution: string,
    installerOptions: JavaInstallerOptions
  ) {
-    this.http = new httpm.HttpClient('actions/setup-java', undefined, {
-      allowRetries: true,
-      maxRetries: 3
-    });
+    this.http = new RetryingHttpClient('actions/setup-java');

    ({
      version: this.version,
@@ -63,6 +64,101 @@ export abstract class JavaBase {
    range: string
  ): Promise<JavaDownloadRelease>;

+  protected async downloadAndVerify(
+    javaRelease: JavaDownloadRelease
+  ): Promise<string> {
+    const archivePath = await tc.downloadTool(javaRelease.url);
+    const checksum = javaRelease.checksum;
+    if (!checksum || !checksum.value?.trim()) {
+      core.debug(
+        `No authoritative checksum is available for ${this.distribution} version ${javaRelease.version}; skipping checksum verification.`
+      );
+      return archivePath;
+    }
+
+    try {
+      await verifyChecksum(archivePath, checksum, {
+        distribution: this.distribution,
+        version: javaRelease.version
+      });
+      core.debug(
+        `Verified ${checksum.algorithm} checksum for ${this.distribution} version ${javaRelease.version}.`
+      );
+      return archivePath;
+    } catch (error) {
+      let cleanupError: unknown;
+      let cleanupFailed = false;
+      try {
+        await fs.promises.rm(archivePath, {force: true});
+      } catch (caughtCleanupError) {
+        cleanupError = caughtCleanupError;
+        cleanupFailed = true;
+      }
+      if (cleanupFailed) {
+        throw new Error(
+          `${(error as Error).message} Failed to remove the downloaded archive after verification failure: ${(cleanupError as Error).message}`,
+          {cause: error}
+        );
+      }
+      throw error;
+    }
+  }
+
+  protected async fetchChecksum(
+    checksumUrl: string,
+    algorithm: ChecksumAlgorithm | ChecksumAlgorithm[]
+  ): Promise<ChecksumMetadata | undefined> {
+    // Some vendors (e.g. JetBrains) publish a single, generically-named
+    // checksum sibling (`.checksum`) whose digest algorithm isn't disclosed
+    // by the URL and has changed across releases. Accepting a list of
+    // candidate algorithms lets callers pass every algorithm the vendor is
+    // known to use; the actual algorithm is then inferred from the length of
+    // the returned digest.
+    const algorithms = Array.isArray(algorithm) ? algorithm : [algorithm];
+    const algorithmLabel = algorithms.join(' or ');
+
+    const response = await this.http.get(checksumUrl);
+    const statusCode = response.message.statusCode;
+    const source = (() => {
+      try {
+        const url = new URL(checksumUrl);
+        return `${url.origin}${url.pathname}`;
+      } catch {
+        return 'an invalid checksum URL';
+      }
+    })();
+
+    if (statusCode === httpm.HttpCodes.NotFound) {
+      core.debug(
+        `No authoritative ${algorithmLabel} checksum is available for ${this.distribution} from ${source}; skipping checksum verification.`
+      );
+      return undefined;
+    }
+
+    if (statusCode !== httpm.HttpCodes.OK) {
+      throw new Error(
+        `Failed to fetch the authoritative ${algorithmLabel} checksum for ${this.distribution} from ${source} (HTTP ${statusCode}).`
+      );
+    }
+
+    const body = await response.readBody();
+    const value = body.trim().split(/\s+/, 1)[0] ?? '';
+    if (!value) {
+      throw new Error(
+        `Received an empty authoritative ${algorithmLabel} checksum for ${this.distribution} from ${source}.`
+      );
+    }
+
+    // Prefer the strongest algorithm whose digest length matches what was
+    // actually returned; fall back to the first candidate (preserving prior
+    // behavior/error messages) when the digest doesn't match any of them.
+    const resolvedAlgorithm =
+      algorithms.find(algo => value.length === expectedDigestLength(algo)) ??
+      algorithms[0];
+
+    return {algorithm: resolvedAlgorithm, value, source: checksumUrl};
+  }
+
  public async setupJava(): Promise<JavaInstallerResults> {
    if (this.verifySignature && !this.supportsSignatureVerification()) {
      throw new Error(
@@ -75,113 +171,19 @@ export abstract class JavaBase {
      core.info(`Resolved Java ${foundJava.version} from tool-cache`);
    } else {
      core.info('Trying to resolve the latest version from remote');
-      const MAX_RETRIES = 4;
-      const RETRY_DELAY_MS = 2000;
-      const retryableCodes = [
-        'ETIMEDOUT',
-        'ECONNRESET',
-        'ENOTFOUND',
-        'ECONNREFUSED'
-      ];
-      let retries = MAX_RETRIES;
-      while (retries > 0) {
-        try {
-          // Clear console timers before each attempt to prevent conflicts
-          if (retries < MAX_RETRIES && core.isDebug()) {
-            const consoleAny = console as any;
-            consoleAny._times?.clear?.();
-          }
-          const javaRelease = await this.findPackageForDownload(this.version);
-          core.info(`Resolved latest version as ${javaRelease.version}`);
-          if (
-            !this.forceDownload &&
-            foundJava?.version === javaRelease.version
-          ) {
-            core.info(`Resolved Java ${foundJava.version} from tool-cache`);
-          } else {
-            core.info('Trying to download...');
-            foundJava = await this.downloadTool(javaRelease);
-            core.info(`Java ${foundJava.version} was downloaded`);
-          }
-          break;
-        } catch (error: any) {
-          retries--;
-          // Check if error is retryable (including aggregate errors)
-          const isRetryable =
-            (error instanceof tc.HTTPError &&
-              error.httpStatusCode &&
-              [429, 502, 503, 504, 522].includes(error.httpStatusCode)) ||
-            retryableCodes.includes(error?.code) ||
-            (error?.errors &&
-              Array.isArray(error.errors) &&
-              error.errors.some((err: any) =>
-                retryableCodes.includes(err?.code)
-              ));
-          if (retries > 0 && isRetryable) {
-            core.debug(
-              `Attempt failed due to network or timeout issues, initiating retry... (${retries} attempts left)`
-            );
-            await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
-            continue;
-          }
-          if (error instanceof tc.HTTPError) {
-            if (error.httpStatusCode === 403) {
-              core.error('HTTP 403: Permission denied or access restricted.');
-            } else if (error.httpStatusCode === 429) {
-              core.warning(
-                'HTTP 429: Rate limit exceeded. Please retry later.'
-              );
-            } else {
-              core.error(`HTTP ${error.httpStatusCode}: ${error.message}`);
-            }
-          } else if (error && error.errors && Array.isArray(error.errors)) {
-            core.error(
-              `Java setup failed due to network or configuration error(s)`
-            );
-            if (error instanceof Error && error.stack) {
-              core.debug(error.stack);
-            }
-            for (const err of error.errors) {
-              const endpoint = err?.address || err?.hostname || '';
-              const port = err?.port ? `:${err.port}` : '';
-              const message = err?.message || 'Aggregate error';
-              const endpointInfo = !message.includes(endpoint)
-                ? ` ${endpoint}${port}`
-                : '';
-              const localInfo =
-                err.localAddress && err.localPort
-                  ? ` - Local (${err.localAddress}:${err.localPort})`
-                  : '';
-              const logMessage = `${message}${endpointInfo}${localInfo}`;
-              core.error(logMessage);
-              core.debug(`${err.stack || err.message}`);
-              Object.entries(err).forEach(([key, value]) => {
-                core.debug(`"${key}": ${JSON.stringify(value)}`);
-              });
-            }
-          } else {
-            const message =
-              error instanceof Error ? error.message : JSON.stringify(error);
-            core.error(`Java setup process failed due to: ${message}`);
-            if (typeof error?.code === 'string') {
-              core.debug(error.stack);
-            }
-            const errorDetails = {
-              name: error.name,
-              message: error.message,
-              ...Object.getOwnPropertyNames(error)
-                .filter(prop => !['name', 'message', 'stack'].includes(prop))
-                .reduce<{[key: string]: any}>((acc, prop) => {
-                  acc[prop] = error[prop];
-                  return acc;
-                }, {})
-            };
-            Object.entries(errorDetails).forEach(([key, value]) => {
-              core.debug(`"${key}": ${JSON.stringify(value)}`);
-            });
-          }
-          throw error;
+      try {
+        const javaRelease = await this.findPackageForDownload(this.version);
+        core.info(`Resolved latest version as ${javaRelease.version}`);
+        if (!this.forceDownload && foundJava?.version === javaRelease.version) {
+          core.info(`Resolved Java ${foundJava.version} from tool-cache`);
+        } else {
+          core.info('Trying to download...');
+          foundJava = await this.downloadTool(javaRelease);
+          core.info(`Java ${foundJava.version} was downloaded`);
        }
+      } catch (error: any) {
+        this.logSetupError(error);
+        throw error;
      }
    }
    if (!foundJava) {
@@ -209,6 +211,68 @@ export abstract class JavaBase {
    return foundJava;
  }

+  private logSetupError(error: any): void {
+    const httpStatusCode =
+      error instanceof tc.HTTPError
+        ? error.httpStatusCode
+        : error instanceof httpm.HttpClientError
+          ? error.statusCode
+          : undefined;
+
+    if (httpStatusCode) {
+      if (httpStatusCode === 403) {
+        core.error('HTTP 403: Permission denied or access restricted.');
+      } else if (httpStatusCode === 429) {
+        core.warning('HTTP 429: Rate limit exceeded. Please retry later.');
+      } else {
+        core.error(`HTTP ${httpStatusCode}: ${error.message}`);
+      }
+    } else if (error && error.errors && Array.isArray(error.errors)) {
+      core.error(`Java setup failed due to network or configuration error(s)`);
+      if (error instanceof Error && error.stack) {
+        core.debug(error.stack);
+      }
+      for (const err of error.errors) {
+        const endpoint = err?.address || err?.hostname || '';
+        const port = err?.port ? `:${err.port}` : '';
+        const message = err?.message || 'Aggregate error';
+        const endpointInfo = !message.includes(endpoint)
+          ? ` ${endpoint}${port}`
+          : '';
+        const localInfo =
+          err.localAddress && err.localPort
+            ? ` - Local (${err.localAddress}:${err.localPort})`
+            : '';
+        const logMessage = `${message}${endpointInfo}${localInfo}`;
+        core.error(logMessage);
+        core.debug(`${err.stack || err.message}`);
+        Object.entries(err).forEach(([key, value]) => {
+          core.debug(`"${key}": ${JSON.stringify(value)}`);
+        });
+      }
+    } else {
+      const message =
+        error instanceof Error ? error.message : JSON.stringify(error);
+      core.error(`Java setup process failed due to: ${message}`);
+      if (typeof error?.code === 'string') {
+        core.debug(error.stack);
+      }
+      const errorDetails = {
+        name: error.name,
+        message: error.message,
+        ...Object.getOwnPropertyNames(error)
+          .filter(prop => !['name', 'message', 'stack'].includes(prop))
+          .reduce<{[key: string]: any}>((acc, prop) => {
+            acc[prop] = error[prop];
+            return acc;
+          }, {})
+      };
+      Object.entries(errorDetails).forEach(([key, value]) => {
+        core.debug(`"${key}": ${JSON.stringify(value)}`);
+      });
+    }
+  }
+
  protected get toolcacheFolderName(): string {
    return `Java_${this.distribution}_${this.packageType}`;
  }
--- a/src/distributions/base-models.ts
+++ b/src/distributions/base-models.ts
@@ -14,8 +14,17 @@ export interface JavaInstallerResults {
  path: string;
 }

+export type ChecksumAlgorithm = 'sha256' | 'sha512';
+
+export interface ChecksumMetadata {
+  algorithm: ChecksumAlgorithm;
+  value: string;
+  source?: string;
+}
+
 export interface JavaDownloadRelease {
  version: string;
  url: string;
  signatureUrl?: string;
+  checksum?: ChecksumMetadata;
 }
--- a/src/distributions/corretto/installer.ts
+++ b/src/distributions/corretto/installer.ts
@@ -19,6 +19,9 @@ import {
  ICorrettoAvailableVersions
 } from './models.js';

+const CORRETTO_VERSIONS_URL =
+  'https://corretto.github.io/corretto-downloads/latest_links/indexmap_with_checksum.json';
+
 export class CorrettoDistribution extends JavaBase {
  constructor(installerOptions: JavaInstallerOptions) {
    super('Corretto', installerOptions);
@@ -30,7 +33,7 @@ export class CorrettoDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
@@ -86,7 +89,12 @@ export class CorrettoDistribution extends JavaBase {
      .map(item => {
        return {
          version: convertVersionToSemver(item.correttoVersion),
-          url: item.downloadLink
+          url: item.downloadLink,
+          checksum: {
+            algorithm: 'sha256',
+            value: item.checksum_sha256,
+            source: CORRETTO_VERSIONS_URL
+          }
        } as JavaDownloadRelease;
      });

@@ -110,16 +118,14 @@ export class CorrettoDistribution extends JavaBase {
      console.time('Retrieving available versions for Corretto took'); // eslint-disable-line no-console
    }

-    const availableVersionsUrl =
-      'https://corretto.github.io/corretto-downloads/latest_links/indexmap_with_checksum.json';
    const fetchCurrentVersions =
      await this.http.getJson<ICorrettoAllAvailableVersions>(
-        availableVersionsUrl
+        CORRETTO_VERSIONS_URL
      );
    const fetchedCurrentVersions = fetchCurrentVersions.result;
    if (!fetchedCurrentVersions) {
      throw Error(
-        `Could not fetch latest corretto versions from ${availableVersionsUrl}`
+        `Could not fetch latest corretto versions from ${CORRETTO_VERSIONS_URL}`
      );
    }

--- a/src/distributions/distribution-factory.ts
+++ b/src/distributions/distribution-factory.ts
@@ -22,42 +22,18 @@ import {
 import {JetBrainsDistribution} from './jetbrains/installer.js';
 import {KonaDistribution} from './kona/installer.js';
 import {OpenJdkDistribution} from './openjdk/installer.js';
-
-enum JavaDistribution {
-  Adopt = 'adopt',
-  AdoptHotspot = 'adopt-hotspot',
-  AdoptOpenJ9 = 'adopt-openj9',
-  Temurin = 'temurin',
-  Zulu = 'zulu',
-  Liberica = 'liberica',
-  LibericaNik = 'liberica-nik',
-  JdkFile = 'jdkfile',
-  Microsoft = 'microsoft',
-  Semeru = 'semeru',
-  Corretto = 'corretto',
-  Oracle = 'oracle',
-  Dragonwell = 'dragonwell',
-  SapMachine = 'sapmachine',
-  GraalVM = 'graalvm',
-  GraalVMCommunity = 'graalvm-community',
-  JetBrains = 'jetbrains',
-  Kona = 'kona',
-  OracleOpenJdk = 'oracle-openjdk'
-}
+import {JavaDistribution, validateJavaPackage} from './package-types.js';

 export function getJavaDistribution(
  distributionName: string,
  installerOptions: JavaInstallerOptions,
  jdkFile?: string
 ): JavaBase | null {
-  if (
-    installerOptions.packageType === 'jdk+jmods' &&
-    distributionName !== JavaDistribution.Temurin
-  ) {
-    throw new Error(
-      "java-package 'jdk+jmods' is only supported for distribution 'temurin'."
-    );
-  }
+  validateJavaPackage(
+    distributionName,
+    installerOptions.packageType,
+    installerOptions.version
+  );

  switch (distributionName) {
    case JavaDistribution.JdkFile:
--- a/src/distributions/dragonwell/installer.ts
+++ b/src/distributions/dragonwell/installer.ts
@@ -46,7 +46,13 @@ export class DragonwellDistribution extends JavaBase {
      .map(item => {
        return {
          version: item.jdk_version,
-          url: item.download_link
+          url: item.download_link,
+          checksum: item.checksum
+            ? {
+                algorithm: 'sha256',
+                value: item.checksum
+              }
+            : undefined
        } as JavaDownloadRelease;
      });

@@ -102,7 +108,7 @@ export class DragonwellDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/graalvm/installer.ts
+++ b/src/distributions/graalvm/installer.ts
@@ -43,6 +43,7 @@ type OsVersions = 'linux' | 'macos' | 'windows';
 interface GraalVMCommunityAsset {
  name: string;
  browser_download_url: string;
+  digest?: string;
 }

 interface GraalVMCommunityRelease {
@@ -66,7 +67,7 @@ export class GraalVMDistribution extends JavaBase {
      core.info(
        `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
      );
-      let javaArchivePath = await tc.downloadTool(javaRelease.url);
+      let javaArchivePath = await this.downloadAndVerify(javaRelease);

      core.info(`Extracting Java archive...`);
      const extension = getDownloadArchiveExtension();
@@ -145,7 +146,11 @@ export class GraalVMDistribution extends JavaBase {
    const response = await this.http.head(fileUrl);
    this.handleHttpResponse(response, range);

-    return {url: fileUrl, version: range};
+    return {
+      url: fileUrl,
+      version: range,
+      checksum: await this.fetchChecksum(`${fileUrl}.sha256`, 'sha256')
+    };
  }

  protected validateVersionRange(range: string): void {
@@ -284,7 +289,8 @@ export class GraalVMDistribution extends JavaBase {

    return {
      url: downloadUrl,
-      version: latestVersion.version
+      version: latestVersion.version,
+      checksum: await this.fetchChecksum(`${downloadUrl}.sha256`, 'sha256')
    };
  }

@@ -456,9 +462,22 @@ export class GraalVMCommunityDistribution extends GraalVMDistribution {
        for (const asset of release.assets ?? []) {
          const version = this.extractAssetVersion(asset.name, assetSuffix);
          if (version) {
+            const digest = asset.digest?.match(/^sha256:([a-f0-9]{64})$/i)?.[1];
+            if (!digest) {
+              core.debug(
+                `No authoritative sha256 digest is available for ${asset.name}; skipping checksum verification for this asset.`
+              );
+            }
            versions.set(version, {
              version,
-              url: asset.browser_download_url
+              url: asset.browser_download_url,
+              checksum: digest
+                ? {
+                    algorithm: 'sha256',
+                    value: digest,
+                    source: GRAALVM_COMMUNITY_RELEASES_URL
+                  }
+                : undefined
            });
          }
        }
--- a/src/distributions/jetbrains/installer.ts
+++ b/src/distributions/jetbrains/installer.ts
@@ -50,7 +50,17 @@ export class JetBrainsDistribution extends JavaBase {
      throw this.createVersionNotFoundError(range, availableVersionStrings);
    }

-    return resolvedFullVersion;
+    return {
+      ...resolvedFullVersion,
+      // JetBrains' `.checksum` sibling doesn't disclose its algorithm via the
+      // filename, and older JBR builds (e.g. JBR 11) publish a SHA-256 digest
+      // there while newer builds publish SHA-512. Accept either, preferring
+      // the stronger SHA-512 when the digest length is ambiguous.
+      checksum: await this.fetchChecksum(
+        `${resolvedFullVersion.url}.checksum`,
+        ['sha512', 'sha256']
+      )
+    };
  }

  protected async downloadTool(
@@ -60,7 +70,7 @@ export class JetBrainsDistribution extends JavaBase {
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );

-    const javaArchivePath = await tc.downloadTool(javaRelease.url);
+    const javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extractedJavaPath = await extractJdkFile(javaArchivePath, 'tar.gz');
--- a/src/distributions/kona/installer.ts
+++ b/src/distributions/kona/installer.ts
@@ -19,6 +19,9 @@ import {
  renameWinArchive
 } from '../../util.js';

+const KONA_RELEASES_URL =
+  'https://tencent.github.io/konajdk/releases/kona-v1.json';
+
 export class KonaDistribution extends JavaBase {
  constructor(installerOptions: JavaInstallerOptions) {
    super('Kona', installerOptions);
@@ -30,7 +33,7 @@ export class KonaDistribution extends JavaBase {
    core.info(
      `Downloading Kona JDK ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    const javaArchivePath = await tc.downloadTool(javaRelease.url);
+    const javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);

@@ -74,7 +77,14 @@ export class KonaDistribution extends JavaBase {
      .map(item => {
        return {
          version: item.version,
-          url: item.downloadUrl
+          url: item.downloadUrl,
+          checksum: item.checksum
+            ? {
+                algorithm: 'sha256',
+                value: item.checksum,
+                source: KONA_RELEASES_URL
+              }
+            : undefined
        } as JavaDownloadRelease;
      })
      .sort((a, b) => -semver.compareBuild(a.version, b.version));
@@ -115,16 +125,13 @@ export class KonaDistribution extends JavaBase {
  }

  private async fetchReleaseInfo(): Promise<IKonaReleaseInfo | null> {
-    const releasesInfoUrl =
-      'https://tencent.github.io/konajdk/releases/kona-v1.json';
-
    try {
-      core.debug(`Fetching Kona release info from URL: ${releasesInfoUrl}`);
-      return (await this.http.getJson<IKonaReleaseInfo>(releasesInfoUrl))
+      core.debug(`Fetching Kona release info from URL: ${KONA_RELEASES_URL}`);
+      return (await this.http.getJson<IKonaReleaseInfo>(KONA_RELEASES_URL))
        .result;
    } catch (err) {
      core.debug(
-        `Fetching Kona release info from the URL: ${releasesInfoUrl} failed with the error: ${
+        `Fetching Kona release info from the URL: ${KONA_RELEASES_URL} failed with the error: ${
          (err as Error).message
        }`
      );
--- a/src/distributions/liberica-nik/installer.ts
+++ b/src/distributions/liberica-nik/installer.ts
@@ -32,7 +32,7 @@ export class LibericaNikDistributions extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/liberica/installer.ts
+++ b/src/distributions/liberica/installer.ts
@@ -32,7 +32,7 @@ export class LibericaDistributions extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/microsoft/installer.ts
+++ b/src/distributions/microsoft/installer.ts
@@ -31,7 +31,7 @@ export class MicrosoftDistributions extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    if (this.verifySignature) {
      if (!javaRelease.signatureUrl) {
@@ -114,7 +114,11 @@ export class MicrosoftDistributions extends JavaBase {
    return {
      url: file.download_url,
      signatureUrl,
-      version: foundRelease.version
+      version: foundRelease.version,
+      checksum: await this.fetchChecksum(
+        `${file.download_url}.sha256sum.txt`,
+        'sha256'
+      )
    };
  }

--- a/src/distributions/openjdk/installer.ts
+++ b/src/distributions/openjdk/installer.ts
@@ -50,7 +50,11 @@ export class OpenJdkDistribution extends JavaBase {
      );
    }

-    return matchingReleases[0];
+    const release = matchingReleases[0];
+    return {
+      ...release,
+      checksum: await this.fetchChecksum(`${release.url}.sha256`, 'sha256')
+    };
  }

  protected async downloadTool(
@@ -59,7 +63,7 @@ export class OpenJdkDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = javaRelease.url.endsWith('.zip') ? 'zip' : 'tar.gz';
--- a/src/distributions/oracle/installer.ts
+++ b/src/distributions/oracle/installer.ts
@@ -32,7 +32,7 @@ export class OracleDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
@@ -112,7 +112,11 @@ export class OracleDistribution extends JavaBase {
      const response = await this.http.head(url);

      if (response.message.statusCode === HttpCodes.OK) {
-        return {url, version: range};
+        return {
+          url,
+          version: range,
+          checksum: await this.fetchChecksum(`${url}.sha256`, 'sha256')
+        };
      }

      if (response.message.statusCode !== HttpCodes.NotFound) {
--- a/src/distributions/package-types.ts
+++ b/src/distributions/package-types.ts
@@ -0,0 +1,135 @@
+import semver from 'semver';
+import {convertVersionToSemver} from '../util.js';
+
+export enum JavaDistribution {
+  Adopt = 'adopt',
+  AdoptHotspot = 'adopt-hotspot',
+  AdoptOpenJ9 = 'adopt-openj9',
+  Temurin = 'temurin',
+  Zulu = 'zulu',
+  Liberica = 'liberica',
+  LibericaNik = 'liberica-nik',
+  JdkFile = 'jdkfile',
+  Microsoft = 'microsoft',
+  Semeru = 'semeru',
+  Corretto = 'corretto',
+  Oracle = 'oracle',
+  Dragonwell = 'dragonwell',
+  SapMachine = 'sapmachine',
+  GraalVM = 'graalvm',
+  GraalVMCommunity = 'graalvm-community',
+  JetBrains = 'jetbrains',
+  Kona = 'kona',
+  OracleOpenJdk = 'oracle-openjdk'
+}
+
+export const JAVA_PACKAGE_CAPABILITIES = {
+  [JavaDistribution.Adopt]: ['jdk', 'jre'],
+  [JavaDistribution.AdoptHotspot]: ['jdk', 'jre'],
+  [JavaDistribution.AdoptOpenJ9]: ['jdk', 'jre'],
+  [JavaDistribution.Temurin]: ['jdk', 'jre', 'jdk+jmods'],
+  [JavaDistribution.Zulu]: [
+    'jdk',
+    'jre',
+    'jdk+fx',
+    'jre+fx',
+    'jdk+crac',
+    'jre+crac'
+  ],
+  [JavaDistribution.Liberica]: ['jdk', 'jre', 'jdk+fx', 'jre+fx'],
+  [JavaDistribution.LibericaNik]: ['jdk', 'jdk+fx'],
+  [JavaDistribution.JdkFile]: ['jdk'],
+  [JavaDistribution.Microsoft]: ['jdk'],
+  [JavaDistribution.Semeru]: ['jdk', 'jre'],
+  [JavaDistribution.Corretto]: ['jdk', 'jre'],
+  [JavaDistribution.Oracle]: ['jdk'],
+  [JavaDistribution.Dragonwell]: ['jdk'],
+  [JavaDistribution.SapMachine]: ['jdk', 'jre'],
+  [JavaDistribution.GraalVM]: ['jdk'],
+  [JavaDistribution.GraalVMCommunity]: ['jdk'],
+  [JavaDistribution.JetBrains]: [
+    'jdk',
+    'jre',
+    'jdk+jcef',
+    'jre+jcef',
+    'jdk+ft',
+    'jre+ft'
+  ],
+  [JavaDistribution.Kona]: ['jdk'],
+  [JavaDistribution.OracleOpenJdk]: ['jdk']
+} as const satisfies Record<JavaDistribution, readonly string[]>;
+
+export function validateJavaPackage(
+  distributionName: string,
+  packageType: string,
+  version: string
+): void {
+  if (!isJavaDistribution(distributionName)) {
+    return;
+  }
+
+  const supportedPackages: readonly string[] =
+    JAVA_PACKAGE_CAPABILITIES[distributionName];
+  if (!supportedPackages.includes(packageType)) {
+    throw createUnsupportedPackageError(
+      distributionName,
+      packageType,
+      supportedPackages
+    );
+  }
+
+  if (
+    distributionName === JavaDistribution.Temurin &&
+    packageType === 'jdk+jmods' &&
+    !canResolveTemurinJmods(version)
+  ) {
+    throw createUnsupportedPackageError(
+      distributionName,
+      packageType,
+      supportedPackages,
+      `Package 'jdk+jmods' requires Java 24 or later; requested version '${version}'.`
+    );
+  }
+}
+
+function isJavaDistribution(value: string): value is JavaDistribution {
+  return Object.prototype.hasOwnProperty.call(JAVA_PACKAGE_CAPABILITIES, value);
+}
+
+function canResolveTemurinJmods(version: string): boolean {
+  const normalizedVersion = version.trim().toLowerCase();
+  if (normalizedVersion === 'latest') {
+    return true;
+  }
+
+  let normalizedRange = normalizedVersion
+    .replace(/-ea$/, '')
+    .replace('-ea.', '+');
+  if (/^\d+(\.\d+){3,}$/.test(normalizedRange)) {
+    normalizedRange = convertVersionToSemver(normalizedRange);
+  }
+  if (!semver.validRange(normalizedRange)) {
+    // JavaBase owns general version validation and its targeted error messages.
+    return true;
+  }
+
+  return semver.intersects(normalizedRange, '>=24.0.0', {
+    includePrerelease: true
+  });
+}
+
+function createUnsupportedPackageError(
+  distributionName: JavaDistribution,
+  packageType: string,
+  supportedPackages: readonly string[],
+  detail?: string
+): Error {
+  const message = [
+    `Java package '${packageType}' is not supported for distribution '${distributionName}'.`,
+    `Supported package types: ${supportedPackages.join(', ')}.`
+  ];
+  if (detail) {
+    message.push(detail);
+  }
+  return new Error(message.join(' '));
+}
--- a/src/distributions/sapmachine/installer.ts
+++ b/src/distributions/sapmachine/installer.ts
@@ -56,7 +56,14 @@ export class SapMachineDistribution extends JavaBase {
    }

    const resolvedVersion = matchedVersions[0];
-    return resolvedVersion;
+    const checksumUrl = resolvedVersion.url.replace(
+      /\.(?:tar\.gz|zip)$/,
+      '.sha256.txt'
+    );
+    return {
+      ...resolvedVersion,
+      checksum: await this.fetchChecksum(checksumUrl, 'sha256')
+    };
  }

  private async getAvailableVersions(): Promise<ISapMachineVersions[]> {
@@ -104,7 +111,7 @@ export class SapMachineDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/semeru/installer.ts
+++ b/src/distributions/semeru/installer.ts
@@ -69,7 +69,12 @@ export class SemeruDistribution extends JavaBase {
          : item.version_data.semver.replace('-beta+', '+');
        return {
          version: formattedVersion,
-          url: item.binaries[0].package.link
+          url: item.binaries[0].package.link,
+          checksum: {
+            algorithm: 'sha256',
+            value: item.binaries[0].package.checksum,
+            source: item.binaries[0].package.checksum_link
+          }
        } as JavaDownloadRelease;
      });

@@ -104,7 +109,7 @@ export class SemeruDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/temurin/installer.ts
+++ b/src/distributions/temurin/installer.ts
@@ -69,7 +69,12 @@ export class TemurinDistribution extends JavaBase {
        return {
          version: formattedVersion,
          url: item.binaries[0].package.link,
-          signatureUrl: item.binaries[0].package.signature_link
+          signatureUrl: item.binaries[0].package.signature_link,
+          checksum: {
+            algorithm: 'sha256',
+            value: item.binaries[0].package.checksum,
+            source: item.binaries[0].package.checksum_link
+          }
        } as JavaDownloadRelease;
      });

@@ -132,7 +137,7 @@ export class TemurinDistribution extends JavaBase {
  }

  private async downloadPackage(release: JavaDownloadRelease): Promise<string> {
-    const archivePath = await tc.downloadTool(release.url);
+    const archivePath = await this.downloadAndVerify(release);

    if (this.verifySignature) {
      if (!release.signatureUrl) {
--- a/src/distributions/zulu/installer.ts
+++ b/src/distributions/zulu/installer.ts
@@ -6,7 +6,7 @@ import fs from 'fs';
 import semver from 'semver';

 import {JavaBase} from '../base-installer.js';
-import {IZuluVersions} from './models.js';
+import {IZuluPackageDetails, IZuluVersions} from './models.js';
 import {
  extractJdkFile,
  getDownloadArchiveExtension,
@@ -20,6 +20,15 @@ import {
  JavaInstallerResults
 } from '../base-models.js';

+// The Azul Metadata API only reports the sha256 checksum on the
+// package-details endpoint, keyed by package_uuid, so the resolved candidate
+// must retain its UUID after sorting until the single follow-up request is made.
+interface ZuluResolvedRelease {
+  version: string;
+  url: string;
+  packageUuid: string;
+}
+
 export class ZuluDistribution extends JavaBase {
  constructor(installerOptions: JavaInstallerOptions) {
    super('Zulu', installerOptions);
@@ -40,7 +49,8 @@ export class ZuluDistribution extends JavaBase {
      return {
        version: convertVersionToSemver(javaVersion),
        url: item.download_url,
-        zuluVersion: convertVersionToSemver(item.distro_version)
+        zuluVersion: convertVersionToSemver(item.distro_version),
+        packageUuid: item.package_uuid
      };
    });

@@ -54,12 +64,11 @@ export class ZuluDistribution extends JavaBase {
          -semver.compareBuild(a.zuluVersion, b.zuluVersion)
        );
      })
-      .map(item => {
-        return {
-          version: item.version,
-          url: item.url
-        } as JavaDownloadRelease;
-      });
+      .map((item): ZuluResolvedRelease => ({
+        version: item.version,
+        url: item.url,
+        packageUuid: item.packageUuid
+      }));

    const resolvedFullVersion =
      satisfiedVersions.length > 0 ? satisfiedVersions[0] : null;
@@ -70,7 +79,29 @@ export class ZuluDistribution extends JavaBase {
      throw this.createVersionNotFoundError(version, availableVersionStrings);
    }

-    return resolvedFullVersion;
+    const packageDetailsUrl = `https://api.azul.com/metadata/v1/zulu/packages/${resolvedFullVersion.packageUuid}`;
+    const packageDetails = (
+      await this.http.getJson<IZuluPackageDetails>(packageDetailsUrl)
+    ).result;
+    const digest = packageDetails?.sha256_hash?.match(/^[a-f0-9]{64}$/i)?.[0];
+
+    if (!digest) {
+      core.debug(
+        `No authoritative sha256 checksum is available for Zulu version ${resolvedFullVersion.version} from ${packageDetailsUrl}; skipping checksum verification.`
+      );
+    }
+
+    return {
+      version: resolvedFullVersion.version,
+      url: resolvedFullVersion.url,
+      checksum: digest
+        ? {
+            algorithm: 'sha256',
+            value: digest,
+            source: packageDetailsUrl
+          }
+        : undefined
+    };
  }

  protected async downloadTool(
@@ -79,7 +110,7 @@ export class ZuluDistribution extends JavaBase {
    core.info(
      `Downloading Java ${javaRelease.version} (${this.distribution}) from ${javaRelease.url} ...`
    );
-    let javaArchivePath = await tc.downloadTool(javaRelease.url);
+    let javaArchivePath = await this.downloadAndVerify(javaRelease);

    core.info(`Extracting Java archive...`);
    const extension = getDownloadArchiveExtension();
--- a/src/distributions/zulu/models.ts
+++ b/src/distributions/zulu/models.ts
@@ -10,3 +10,7 @@ export interface IZuluVersions {
  latest: boolean;
  availability_type: string;
 }
+
+export interface IZuluPackageDetails {
+  sha256_hash?: string;
+}
--- a/src/retrying-http-client.ts
+++ b/src/retrying-http-client.ts
@@ -0,0 +1,166 @@
+import * as core from '@actions/core';
+import * as httpm from '@actions/http-client';
+import type {OutgoingHttpHeaders} from 'http';
+
+const RETRYABLE_HTTP_STATUS_CODES = new Set([429, 502, 503, 504, 522]);
+const RETRYABLE_NETWORK_ERROR_CODES = new Set([
+  'ETIMEDOUT',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'ECONNREFUSED'
+]);
+const RETRYABLE_HTTP_VERBS = new Set(['OPTIONS', 'GET', 'DELETE', 'HEAD']);
+
+export interface HttpRetryOptions {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  sleep?: (delayMs: number) => Promise<void>;
+  random?: () => number;
+  now?: () => number;
+}
+
+export class RetryingHttpClient extends httpm.HttpClient {
+  private readonly maxAttempts: number;
+  private readonly baseDelayMs: number;
+  private readonly maxDelayMs: number;
+  private readonly sleep: (delayMs: number) => Promise<void>;
+  private readonly random: () => number;
+  private readonly now: () => number;
+
+  constructor(userAgent?: string, retryOptions: HttpRetryOptions = {}) {
+    super(userAgent, undefined, {allowRetries: false});
+    this.maxAttempts = retryOptions.maxAttempts ?? 4;
+    this.baseDelayMs = retryOptions.baseDelayMs ?? 1000;
+    this.maxDelayMs = retryOptions.maxDelayMs ?? 10000;
+    this.sleep =
+      retryOptions.sleep ??
+      (delayMs => new Promise(resolve => setTimeout(resolve, delayMs)));
+    this.random = retryOptions.random ?? Math.random;
+    this.now = retryOptions.now ?? Date.now;
+
+    if (this.maxAttempts < 1) {
+      throw new Error('maxAttempts must be at least 1');
+    }
+    if (this.baseDelayMs < 0 || this.maxDelayMs < this.baseDelayMs) {
+      throw new Error(
+        'baseDelayMs must be non-negative and no greater than maxDelayMs'
+      );
+    }
+  }
+
+  public override async request(
+    verb: string,
+    requestUrl: string,
+    data: string | NodeJS.ReadableStream | null,
+    headers?: OutgoingHttpHeaders
+  ): Promise<httpm.HttpClientResponse> {
+    if (!RETRYABLE_HTTP_VERBS.has(verb)) {
+      return super.request(verb, requestUrl, data, headers);
+    }
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      try {
+        const response = await super.request(verb, requestUrl, data, headers);
+        const statusCode = response.message.statusCode;
+        if (
+          !statusCode ||
+          !RETRYABLE_HTTP_STATUS_CODES.has(statusCode) ||
+          attempt === this.maxAttempts
+        ) {
+          return response;
+        }
+
+        const delayMs = this.getDelayMs(
+          attempt,
+          response.message.headers['retry-after']
+        );
+        await response.readBody();
+        this.logRetry(attempt, delayMs, `HTTP ${statusCode}`);
+        await this.sleep(delayMs);
+      } catch (error) {
+        if (!isRetryableNetworkError(error) || attempt === this.maxAttempts) {
+          throw error;
+        }
+
+        const delayMs = this.getDelayMs(attempt);
+        this.logRetry(attempt, delayMs, getErrorMessage(error));
+        await this.sleep(delayMs);
+      }
+    }
+
+    throw new Error('HTTP retry attempts exhausted unexpectedly');
+  }
+
+  private getDelayMs(
+    failedAttempt: number,
+    retryAfter?: string | string[]
+  ): number {
+    const exponentialDelay = Math.min(
+      this.maxDelayMs,
+      this.baseDelayMs * 2 ** (failedAttempt - 1)
+    );
+    const jitteredDelay = Math.floor(
+      exponentialDelay / 2 + this.random() * (exponentialDelay / 2)
+    );
+    const retryAfterDelay = parseRetryAfter(retryAfter, this.now());
+    return Math.min(
+      this.maxDelayMs,
+      Math.max(jitteredDelay, retryAfterDelay ?? 0)
+    );
+  }
+
+  private logRetry(
+    failedAttempt: number,
+    delayMs: number,
+    reason: string
+  ): void {
+    core.info(
+      `Request attempt ${failedAttempt} of ${this.maxAttempts} failed (${reason}); retrying in ${delayMs} ms`
+    );
+  }
+}
+
+export function parseRetryAfter(
+  value: string | string[] | undefined,
+  nowMs: number
+): number | undefined {
+  const retryAfter = Array.isArray(value) ? value[0] : value;
+  if (!retryAfter) {
+    return undefined;
+  }
+
+  if (/^\d+$/.test(retryAfter.trim())) {
+    return Number(retryAfter) * 1000;
+  }
+
+  const retryAt = Date.parse(retryAfter);
+  if (Number.isNaN(retryAt) || retryAt <= nowMs) {
+    return undefined;
+  }
+  return retryAt - nowMs;
+}
+
+export function isRetryableNetworkError(error: unknown): boolean {
+  if (!isErrorRecord(error)) {
+    return false;
+  }
+  if (
+    typeof error.code === 'string' &&
+    RETRYABLE_NETWORK_ERROR_CODES.has(error.code)
+  ) {
+    return true;
+  }
+  return (
+    Array.isArray(error.errors) &&
+    error.errors.some(nestedError => isRetryableNetworkError(nestedError))
+  );
+}
+
+function isErrorRecord(error: unknown): error is Record<string, unknown> {
+  return typeof error === 'object' && error !== null;
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'network error';
+}
--- a/src/setup-java.ts
+++ b/src/setup-java.ts
@@ -16,7 +16,7 @@ import {JavaInstallerOptions} from './distributions/base-models.js';
 import {configureMavenArgs} from './maven-args.js';
 import {configureProblemMatcher} from './problem-matcher.js';

-async function run() {
+export async function run() {
  try {
    const versions = core.getMultilineInput(constants.INPUT_JAVA_VERSION);
    let distributionName = core.getInput(constants.INPUT_DISTRIBUTION);
@@ -40,18 +40,18 @@ async function run() {
    );
    const verifySignaturePublicKey =
      core.getInput(constants.INPUT_VERIFY_SIGNATURE_PUBLIC_KEY) || undefined;
-    let toolchainIds = core.getMultilineInput(constants.INPUT_MVN_TOOLCHAIN_ID);
+    const toolchainIds = core.getMultilineInput(
+      constants.INPUT_MVN_TOOLCHAIN_ID
+    );

    core.startGroup('Installed distributions');

-    if (versions.length !== toolchainIds.length) {
-      toolchainIds = [];
-    }
-
    if (!versions.length && !versionFile) {
      throw new Error('java-version or java-version-file input expected');
    }

+    toolchains.validateToolchainIds(versions, versionFile, toolchainIds);
+
    if (!versions.length) {
      core.debug(
        'java-version input is empty, looking for java-version-file input'
@@ -139,7 +139,12 @@ async function run() {
  }
 }

-run();
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  run();
+} else {
+  // https://nodejs.org/api/modules.html#modules_accessing_the_main_module
+  core.info('the script is loaded as a module, so skipping the execution');
+}

 function getJdkFileInput(): string {
  const jdkFile = core.getInput(constants.INPUT_JDK_FILE);
--- a/src/toolchains.ts
+++ b/src/toolchains.ts
@@ -14,6 +14,23 @@ interface JdkInfo {
  jdkHome: string;
 }

+export function validateToolchainIds(
+  versions: string[],
+  versionFile: string,
+  toolchainIds: string[]
+) {
+  if (!toolchainIds.length) {
+    return;
+  }
+
+  const versionCount = versions.length || (versionFile ? 1 : 0);
+  if (versionCount !== toolchainIds.length) {
+    throw new Error(
+      `The number of Maven toolchain IDs (${toolchainIds.length}) must match the number of Java versions (${versionCount})`
+    );
+  }
+}
+
 export async function configureToolchains(
  version: string,
  distributionName: string,
--- a/src/util.ts
+++ b/src/util.ts
@@ -20,8 +20,21 @@ export function getTempDir() {
 }

 export function getBooleanInput(inputName: string, defaultValue = false) {
-  return (
-    (core.getInput(inputName) || String(defaultValue)).toUpperCase() === 'TRUE'
+  const inputValue = core.getInput(inputName);
+  const normalizedValue = inputValue.trim().toLowerCase();
+
+  if (!normalizedValue) {
+    return defaultValue;
+  }
+  if (normalizedValue === 'true') {
+    return true;
+  }
+  if (normalizedValue === 'false') {
+    return false;
+  }
+
+  throw new Error(
+    `Invalid value '${inputValue}' for boolean input '${inputName}'. Expected 'true' or 'false'.`
  );
 }
Author	SHA1	Message	Date
Bruno Borges	27f2c62824	Verify JDK downloads with vendor checksums (#1167 ) * Verify JDK downloads with vendor checksums Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Handle missing vendor checksum values Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Preserve checksum error during cleanup failure Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Validate checksum metadata value types Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Clarify checksum documentation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Expand vendor checksum verification Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d * Accept SHA-256 or SHA-512 for JetBrains checksum sibling JetBrains publishes a single, generically-named ".checksum" sibling whose digest algorithm isn't disclosed by the filename. Older JBR 11 builds (e.g. jbrsdk_nomod-11_0_16--b2043.64.tar.gz) publish a SHA-256 digest there, while newer builds publish SHA-512. The JetBrains installer previously assumed SHA-512 unconditionally, so verification failed with "Malformed sha512 checksum metadata ... expected a 128-character hexadecimal digest" for those older builds, breaking the jetbrains 11 e2e job on macOS and Windows. fetchChecksum now accepts a list of candidate algorithms and infers the actual algorithm from the returned digest's length, preferring the strongest match. The JetBrains installer passes ['sha512', 'sha256']; all other callers are unaffected since they already pass a single, vendor-disclosed algorithm. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d Use SapMachine archive checksum files Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a800a031-600e-4d28-b23e-be309555d38d	2026-07-29 04:43:56 -04:00
Bruno Borges	19c23b379e	Harden java-package validation (#1165 ) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 10b8fe1e-18f4-42cb-8672-11215715a713	2026-07-29 00:50:01 -04:00
Bruno Borges	6e26972896	Add setup orchestration tests (#1163 ) Make the setup entrypoint import-safe and cover its validation, installation sequencing, post-install collaborators, caching, and failure handling directly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a5ba8975-a9ac-4d2c-b41d-97c99689d1bd	2026-07-29 00:36:12 -04:00
Bruno Borges	5894ef6b27	Consolidate JDK metadata retry handling (#1162 ) * Consolidate JDK metadata retries Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a5e2549a-0d89-4c8f-b7f3-411ad21c8a06 * Expand distribution retry coverage Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a5e2549a-0d89-4c8f-b7f3-411ad21c8a06 --------- Copilot-Session: a5e2549a-0d89-4c8f-b7f3-411ad21c8a06	2026-07-29 00:09:37 -04:00
Bruno Borges	e1ce3a3428	Fail on mismatched Maven toolchain ID counts (#1161 ) * Fail on mismatched Maven toolchain IDs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c821981-7b21-45fe-9463-5bb375d7dce4 * Clarify Maven toolchain ID version counts Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c821981-7b21-45fe-9463-5bb375d7dce4 --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8c821981-7b21-45fe-9463-5bb375d7dce4	2026-07-28 23:33:41 -04:00
Bruno Borges	ce75feb3d3	Reject invalid boolean input values (#1160 ) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c6daa6b5-31f5-46b2-a994-b8320b50a50d	2026-07-28 22:43:39 -04:00