Artifactory validation steps in Global Config pages

content/chainguard/libraries/java/global-configuration.md

@@ -300,6 +300,41 @@ Use this setup for initial testing with Chainguard Libraries for Java. For
 production usage add the `java-chainguard` repository to your production virtual
 repository.
 
+### Validate the remote repository
+
+After creating the `java-chainguard` remote repository, validate that Artifactory is successfully proxying through to Chainguard before proceeding. Because Artifactory falls back to Maven Central when a connection to a remote repository fails, a misconfigured repository may silently resolve packages from Mavel Central rather than Chainguard — and the build will succeed without any visible error.
+
+Common sources of misconfiguration include invalid or expired credentials, or an incorrect or incomplete repository URL. The Artifactory **Test** button on the repository configuration screen is not a reliable indicator; it may fail for a correctly configured repository, and may pass for an incorrectly configured one. Instead, use the following steps to verify that fetching an artifact through Artifactory produces the same checksum as fetching it directly from `libraries.cgr.dev`.
+
+1. Fetch the artifact directly from Chainguard and compute its checksum. This example uses `junit-4.13.2.jar`. You can substitute any artifact you know to be available.
+
+```bash
+curl -sSf -L \
+  -u "${CHAINGUARD_JAVA_IDENTITY_ID}:${CHAINGUARD_JAVA_TOKEN}" \
+  https://libraries.cgr.dev/java/junit/junit/4.13.2/junit-4.13.2.jar \
+  | sha256sum
+```
+
+2. Fetch the same artifact through the Artifactory remote repository and compute its checksum:
+
+```bash
+curl -sSf -L \
+  -u "${ARTIFACTORY_USER}:${ARTIFACTORY_TOKEN}" \
+  https://<artifactory-host>/artifactory/java-chainguard/junit/junit/4.13.2/junit-4.13.2.jar \
+  | sha256sum
+```
+Replace `artifactory-host` with your Artifactory instance hostname.
+
+The checksums returned by the commands must match. 
+
+If the checksum from the Artifactory remote repository differs from the direct fetch, or if the Artifactory fetch fails entirely, review the following before proceeding:
+
+* URL: The remote repository URL must be set to `https://libraries.cgr.dev/java/`. 
+* Credentials: You may need to regenerate your pull token with `chainctl auth pull-token --repository=java` and update the Artifactory repository credentials. Expired tokens fail silently.
+* Advanced configuration: Ensure all recommended Advanced settings from the [remote repository configuration steps](#initial-configuration-2) have been applied.
+
+Do not proceed to virtual repository setup or build configuration until the checksums match.
+
 ### Build tool access
 
 The following steps allow you to determine the URL and authentication details

content/chainguard/libraries/javascript/global-configuration.md

@@ -221,6 +221,51 @@ To prevent this:
     - Alternatively, you could delete specific corrupted `.tgz` artifacts from
       the remote cache, rather than deleting all, before re-running the install.
 
+### Validate the remote repository
+
+After creating and configuring the `javascript-chainguard` remote repository, validate that Artifactory is successfully proxying through to Chainguard before proceeding. Because Artifactory falls back to the upstream npm registry when a connection to a remote repository fails, a misconfigured repository may silently resolve packages from npm rather than Chainguard — and the build will succeed without any visible error.
+
+Common sources of misconfiguration include invalid or expired credentials, an incorrect or incomplete URL, and mosconfigured [settings in the Advanced tab](#advanced-settings-for-redirect-handling). The Artifactory **Test** button on the repository configuration screen is not a reliable indicator; it may fail for a correctly configured repository, and may pass for an incorrectly configured one. Instead, use the following steps to verify that fetching an artifact through Artifactory produces the same checksum as fetching it directly from `libraries.cgr.dev`.
+
+1. Fetch the artifact directly from Chainguard and compute its checksum, using the same credentials you configured in Artifactory. This example uses `picocolors-1.1.1`. You can substitute any artifact you know to be available.
+
+```bash
+curl -sSf -L \
+  -u "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" \
+  https://libraries.cgr.dev/javascript/picocolors/-/picocolors-1.1.1.tgz \
+  | openssl dgst -sha512 -binary | base64
+```
+
+2. Fetch the same artifact through the Artifactory remote repository and compute its checksum:
+
+```bash
+curl -sSf -L \
+  -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \
+  https://<artifactory-host>/artifactory/api/npm/javascript-chainguard/picocolors/-/picocolors-1.1.1.tgz \
+  | openssl dgst -sha512 -binary | base64
+```
+Replace `artifactory-host` with your Artifactory instance hostname, and replace `${ARTIFACTORY_TOKEN}` with your Artifactory identity token.
+
+3. If your configuration includes a virtual repository combining `javascript-chainguard` with a public npm fallback, test that as well:
+
+```bash
+curl -sSf -L \
+  -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \
+  https://<artifactory-host>/artifactory/api/npm/javascript-all/picocolors/-/picocolors-1.1.1.tgz \
+  | openssl dgst -sha512 -binary | base64
+```
+
+The checksums returned by the commands must match. 
+
+If the checksum from the Artifactory remote or virtual repository differ from the direct fetch, or if the Artifactory fetch fails entirely, review the following before proceeding:
+
+* URL: The remote repository URL must be set to `https://libraries.cgr.dev/javascript/`. 
+* Credentials: You may need to regenerate your pull token with `chainctl auth pull-token --repository=javascript` and update the Artifactory repository credentials. Expired tokens fail silently.
+* [Advanced tab settings](#advanced-settings-for-redirect-handling): Confirm that **Bypass HEAD Requests** is enabled and **Lenient Host Authentication** is disabled. 
+
+Do not proceed to virtual repository setup or build configuration until the checksums match.
+
+
 ### Build tool access
 
 The following steps allow you to determine the URL and authentication details

content/chainguard/libraries/python/global-configuration.md

@@ -265,6 +265,50 @@ optionally including remediated versions, with your chosen tools. This setup
 falls back to the public PyPI index in cases where a package is not available in
 Chainguard's index.
 
+### Validate the remote repository
+
+After creating the `python-chainguard` remote repository, validate that Artifactory is successfully proxying through to Chainguard before proceeding. Because Artifactory falls back to the public PyPI index when a connection to a remote repository fails, a misconfigured repository may silently resolve packages from PyPI rather than Chainguard — and the build will succeed without any visible error.
+
+Common sources of misconfiguration include invalid or expired credentials, or an incorrect or incomplete repository URL. The Artifactory **Test** button on the repository configuration screen is not a reliable indicator; it may fail for a correctly configured repository, and may pass for an incorrectly configured one. Instead, use the following steps to verify that fetching an artifact through Artifactory produces the same checksum as fetching it directly from `libraries.cgr.dev`.
+
+1. Find the direct URL for a specific package wheel from the Chainguard index. This example uses `urllib3`. You can substitute any artifact you know to be available.
+
+```bash
+curl -sSf \
+  -u "${CHAINGUARD_PYTHON_IDENTITY_ID}:${CHAINGUARD_PYTHON_TOKEN}" \
+  https://libraries.cgr.dev/python/simple/urllib3/ \
+  | grep -o 'https://[^"]*\.whl' | head -1
+```
+
+2. Fetch a package file directly from `libraries.cgr.dev` and compute its checksum:
+
+```bash
+curl -sSf -L \
+  -u "${CHAINGUARD_PYTHON_IDENTITY_ID}:${CHAINGUARD_PYTHON_TOKEN}" \
+  <url-from-step-1> \
+  | sha256sum
+```
+
+3. Fetch the same file through the Artifactory remote repository and compute its checksum:
+
+```bash
+curl -sSfL \
+  -u "${ARTIFACTORY_USERNAME}:${ARTIFACTORY_TOKEN}" \
+  "https://<artifactory-host>/artifactory/<python-remote-repository>/${path-to-wheel}" \
+  | sha256sum
+```
+Replace `artifactory-host` with your Artifactory instance hostname and replace `python-remote-repository` with your remote repository name. Replace `path-to-wheel` with the path component of the URL from step 1 (for example: `/files/15f7d141c3b76b85/37e321caa85a8f41/urllib3/urllib3-1.26.9-py2.py3-none-any.whl`)
+
+The checksums returned by the commands must match. 
+
+If the checksum from the Artifactory remote repository differs from the direct fetch, or if the Artifactory fetch fails entirely, review the following before proceeding:
+
+* URL: The remote repository URL must be set to `https://libraries.cgr.dev/python/`. 
+* Credentials: You may need to regenerate your pull token with `chainctl auth pull-token --repository=python` and update the Artifactory repository credentials. Expired tokens fail silently.
+* Advanced Configuration: Ensure all recommended Advanced settings from the [initial configuration steps](#initial-configuration-2) have been applied.
+
+Do not proceed to virtual repository setup or build configuration until the checksums match.
+
 ### Build tool access
 
 See the page on [build tool configuration for Chainguard Libraries for