🔄 refactor(registries): route to credentialed instance + fail loud on rejected creds

- Stop seeding anonymous '<provider>.public' default when the user has
  configured at least one credentialed instance (any of token, password,
  auth, clientemail, privatekey, accesskeyid, secretaccesskey) — the
  credentialed instance handles all traffic for that provider.
- Replace non-deterministic Object.values().find() image-to-registry
  routing with explicit priority: credentialed beats anonymous, alpha
  tie-break within tier. Log routing decisions at debug.
- Remove silent anonymous fallback in authenticateBearerFromAuthUrlWithPublicFallback
  when credentials are rejected with 401/403. Now throws an actionable
  error so the UI's existing 'Check failed' badge surfaces the auth
  problem instead of cascading into anonymous-tier 429s.

Root cause of issue #342: a default '.public' instance plus the
credentialed instance both registered for the same provider, with
JS-engine insertion order picking the winner. When the anonymous
instance won, all traffic hit the anonymous-tier rate limit despite
the user having a valid PAT, and credential rejection failures were
swallowed silently so the user had no way to diagnose.

Fixes: GH-342

Author: s-b-e-n-s-o-n

app/registries/BaseRegistry.test.ts

@@ -433,16 +433,10 @@ test('authenticateBearerFromAuthUrl should throw when token is missing', async (
   ).rejects.toThrow('token endpoint response does not contain token');
 });
 
-test('authenticateBearerFromAuthUrlWithPublicFallback should retry without credentials and honor providerLabel', async () => {
+test('authenticateBearerFromAuthUrlWithPublicFallback should throw actionable error (not silently retry) when credentials are rejected with 401', async () => {
   const authenticateSpy = vi
     .spyOn(baseRegistry as any, 'authenticateBearerFromAuthUrl')
-    .mockRejectedValueOnce(new Error('token request failed (Request failed with status code 401)'))
-    .mockResolvedValueOnce({
-      headers: {
-        Authorization: 'Bearer public-token',
-      },
-    });
-  const warnSpy = vi.spyOn(baseRegistry.log, 'warn').mockImplementation(() => undefined);
+    .mockRejectedValueOnce(new Error('token request failed (Request failed with status code 401)'));
 
   await expect(
     (baseRegistry as any).authenticateBearerFromAuthUrlWithPublicFallback(
@@ -453,31 +447,12 @@ test('authenticateBearerFromAuthUrlWithPublicFallback should retry without crede
         providerLabel: 'Docker Hub',
       },
     ),
-  ).resolves.toEqual({
-    headers: {
-      Authorization: 'Bearer public-token',
-    },
-  });
-
-  expect(authenticateSpy).toHaveBeenNthCalledWith(
-    1,
-    { headers: {}, url: 'https://registry.example.com/v2/library/nginx/manifests/latest' },
-    'https://registry.example.com/token',
-    'dXNlcjpwYXNz',
-    undefined,
-    undefined,
-  );
-  expect(authenticateSpy).toHaveBeenNthCalledWith(
-    2,
-    { headers: {}, url: 'https://registry.example.com/v2/library/nginx/manifests/latest' },
-    'https://registry.example.com/token',
-    undefined,
-    undefined,
-    undefined,
-  );
-  expect(warnSpy).toHaveBeenCalledWith(
-    expect.stringContaining('Docker Hub credentials were rejected for registry'),
+  ).rejects.toThrow(
+    /Authentication failed for registry.*HTTP 401.*Docker Hub credentials were rejected/,
   );
+
+  // Must NOT retry anonymously — only one call
+  expect(authenticateSpy).toHaveBeenCalledTimes(1);
 });
 
 test('getRejectedCredentialStatus should use RE2JS for status matching', () => {
@@ -567,34 +542,21 @@ test('authenticateBearerFromAuthUrlWithPublicFallback should rethrow when reject
   ).rejects.toBe(error);
 });
 
-test('authenticateBearerFromAuthUrlWithPublicFallback should default providerLabel to registry id', async () => {
+test('authenticateBearerFromAuthUrlWithPublicFallback should use registry id as provider label when none is supplied', async () => {
   baseRegistry.type = 'registry';
   baseRegistry.name = 'base';
-  const authenticateSpy = vi
-    .spyOn(baseRegistry as any, 'authenticateBearerFromAuthUrl')
-    .mockRejectedValueOnce(new Error('token request failed (Request failed with status code 403)'))
-    .mockResolvedValueOnce({
-      headers: {
-        Authorization: 'Bearer public-token',
-      },
-    });
-  const warnSpy = vi.spyOn(baseRegistry.log, 'warn').mockImplementation(() => undefined);
+  vi.spyOn(baseRegistry as any, 'authenticateBearerFromAuthUrl').mockRejectedValueOnce(
+    new Error('token request failed (Request failed with status code 403)'),
+  );
 
   await expect(
     (baseRegistry as any).authenticateBearerFromAuthUrlWithPublicFallback(
       { headers: {}, url: 'https://registry.example.com/v2/library/nginx/manifests/latest' },
       'https://registry.example.com/token',
       'dXNlcjpwYXNz',
     ),
-  ).resolves.toEqual({
-    headers: {
-      Authorization: 'Bearer public-token',
-    },
-  });
-
-  expect(authenticateSpy).toHaveBeenCalledTimes(2);
-  expect(warnSpy).toHaveBeenCalledWith(
-    'registry.base credentials were rejected for registry registry.base (status 403); retrying token request without credentials for public image checks',
+  ).rejects.toThrow(
+    /Authentication failed for registry registry\.base.*HTTP 403.*registry\.base credentials were rejected/,
   );
 });
 

app/registries/BaseRegistry.ts

@@ -434,6 +434,22 @@ class BaseRegistry<
     return match.find() ? match.group(1) : undefined;
   }
 
+  /**
+   * Bearer-token auth via the registry's token endpoint.
+   *
+   * - When `credentials` is undefined (the instance is registered as
+   *   anonymous), this is a single unauthenticated token request.
+   * - When `credentials` is supplied (the instance is registered as
+   *   credentialed) and the token endpoint rejects them with one of
+   *   `rejectedCredentialStatuses`, this throws an actionable error instead
+   *   of silently falling back to anonymous. Silent anonymous fallback for
+   *   credentialed instances was the root cause of authenticated users still
+   *   hitting per-IP anonymous rate limits (issue #342).
+   *
+   * The historical `WithPublicFallback` suffix in the name is retained for
+   * caller stability; the semantic it referred to (silent retry without
+   * credentials on rejection) is intentionally removed.
+   */
   protected async authenticateBearerFromAuthUrlWithPublicFallback(
     requestOptions: RegistryRequestOptions,
     authUrl: string,
@@ -461,17 +477,12 @@ class BaseRegistry<
         throw error;
       }
 
+      // Credentials were supplied but rejected — throw a clear, actionable
+      // error instead of silently falling back to anonymous. The anonymous
+      // tier would cause 429s that are harder to diagnose than a clean failure.
       const providerLabel = options.providerLabel || this.getId();
-      this.log.warn(
-        `${providerLabel} credentials were rejected for registry ${this.getId()} (status ${rejectedStatus}); retrying token request without credentials for public image checks`,
-      );
-
-      return this.authenticateBearerFromAuthUrl(
-        requestOptions,
-        authUrl,
-        undefined,
-        options.tokenExtractor,
-        options.tokenFailureMessage,
+      throw new Error(
+        `Authentication failed for registry ${this.getId()} (HTTP ${rejectedStatus}): ${providerLabel} credentials were rejected. Check the configured token/login/password and their scopes.`,
       );
     }
   }

app/registries/providers/gcr/Gcr.test.ts

@@ -118,19 +118,20 @@ test('authenticate should return unchanged options when no clientemail configure
   expect(result).toEqual({ headers: {} });
 });
 
-test('authenticate should retry anonymously when configured credentials are rejected with 403', async () => {
+test('authenticate should throw actionable error when configured credentials are rejected with 403', async () => {
   const { default: axios } = await import('axios');
   const gcrWithCreds = new Gcr();
   await gcrWithCreds.register('registry', 'gcr', 'test', {
     clientemail: TEST_CLIENT_EMAIL,
     privatekey: TEST_PRIVATE_KEY,
   });
-  axios
-    .mockRejectedValueOnce(new Error('Request failed with status code 403'))
-    .mockResolvedValueOnce({ data: { token: 'anon-token' } });
-  const warnSpy = vi.spyOn(gcrWithCreds.log, 'warn');
+  axios.mockRejectedValueOnce(new Error('Request failed with status code 403'));
 
-  const result = await gcrWithCreds.authenticate({ name: 'project/image' }, { headers: {} });
+  await expect(
+    gcrWithCreds.authenticate({ name: 'project/image' }, { headers: {} }),
+  ).rejects.toThrow(
+    /Authentication failed for registry gcr\.test \(HTTP 403\): GCR credentials were rejected/,
+  );
 
   const expectedBasic = Buffer.from(
     `_json_key:${JSON.stringify({
@@ -139,29 +140,15 @@ test('authenticate should retry anonymously when configured credentials are reje
     })}`,
     'utf-8',
   ).toString('base64');
-  expect(axios).toHaveBeenNthCalledWith(1, {
+  expect(axios).toHaveBeenCalledTimes(1);
+  expect(axios).toHaveBeenCalledWith({
     method: 'GET',
     url: 'https://gcr.io/v2/token?scope=repository:project/image:pull',
     headers: {
       Accept: 'application/json',
       Authorization: `Basic ${expectedBasic}`,
     },
   });
-  expect(axios).toHaveBeenNthCalledWith(2, {
-    method: 'GET',
-    url: 'https://gcr.io/v2/token?scope=repository:project/image:pull',
-    headers: {
-      Accept: 'application/json',
-    },
-  });
-  expect(warnSpy).toHaveBeenCalledWith(
-    expect.stringContaining('GCR credentials were rejected for registry gcr.test (status 403)'),
-  );
-  expect(result).toEqual({
-    headers: {
-      Authorization: 'Bearer anon-token',
-    },
-  });
 });
 
 test('authenticate should throw when gcr token is missing', async () => {

app/registries/providers/ghcr/Ghcr.test.ts

@@ -86,39 +86,29 @@ describe('GitHub Container Registry', () => {
     expect(result.headers.Authorization).toBe('Bearer registry-token');
   });
 
-  test('should retry anonymously when configured credentials are rejected with 403', async () => {
+  test('should throw actionable error when configured credentials are rejected with 403', async () => {
     ghcr.configuration = { username: 'test-user', token: 'test-token' };
     axios.mockRejectedValueOnce(new Error('Request failed with status code 403'));
-    axios.mockResolvedValueOnce({ data: { token: 'anon-token' } });
     const image = { name: 'user/repo' };
     const requestOptions = {
       headers: {},
       url: 'https://ghcr.io/v2/user/repo/manifests/latest',
     };
-    const warnSpy = vi.spyOn(ghcr.log, 'warn');
 
-    const result = await ghcr.authenticate(image, requestOptions);
+    await expect(ghcr.authenticate(image, requestOptions)).rejects.toThrow(
+      /Authentication failed for registry ghcr\.test \(HTTP 403\): GHCR credentials were rejected/,
+    );
 
     const expectedBasic = Buffer.from('test-user:test-token', 'utf-8').toString('base64');
-    expect(axios).toHaveBeenNthCalledWith(1, {
+    expect(axios).toHaveBeenCalledTimes(1);
+    expect(axios).toHaveBeenCalledWith({
       method: 'GET',
       url: 'https://ghcr.io/token?service=ghcr.io&scope=repository%3Auser%2Frepo%3Apull',
       headers: {
         Accept: 'application/json',
         Authorization: `Basic ${expectedBasic}`,
       },
     });
-    expect(axios).toHaveBeenNthCalledWith(2, {
-      method: 'GET',
-      url: 'https://ghcr.io/token?service=ghcr.io&scope=repository%3Auser%2Frepo%3Apull',
-      headers: {
-        Accept: 'application/json',
-      },
-    });
-    expect(warnSpy).toHaveBeenCalledWith(
-      expect.stringContaining('GHCR credentials were rejected for registry ghcr.test (status 403)'),
-    );
-    expect(result.headers.Authorization).toBe('Bearer anon-token');
   });
 
   test('should not retry anonymously when no credentials are configured', async () => {

app/registries/providers/hub/Hub.test.ts

@@ -158,41 +158,28 @@ describe('Docker Hub Registry', () => {
     expect(result.headers.Authorization).toBe('Bearer public-token');
   });
 
-  test('should retry anonymously when configured credentials are rejected with 401', async () => {
+  test('should throw actionable error when configured credentials are rejected with 401', async () => {
     const { default: axios } = await import('axios');
-    axios
-      .mockRejectedValueOnce(new Error('Request failed with status code 401'))
-      .mockResolvedValueOnce({ data: { token: 'public-token' } });
+    axios.mockRejectedValueOnce(new Error('Request failed with status code 401'));
 
     hub.getAuthCredentials = vi.fn().mockReturnValue('base64credentials');
-    const warnSpy = vi.spyOn(hub.log, 'warn');
 
     const image = { name: 'library/nginx' };
     const requestOptions = { headers: {} };
 
-    const result = await hub.authenticate(image, requestOptions);
+    await expect(hub.authenticate(image, requestOptions)).rejects.toThrow(
+      /Authentication failed for registry hub\.test \(HTTP 401\): Docker Hub credentials were rejected/,
+    );
 
-    expect(axios).toHaveBeenNthCalledWith(1, {
+    expect(axios).toHaveBeenCalledTimes(1);
+    expect(axios).toHaveBeenCalledWith({
       method: 'GET',
       url: 'https://auth.docker.io/token?service=registry.docker.io&scope=repository%3Alibrary%2Fnginx%3Apull&grant_type=password',
       headers: {
         Accept: 'application/json',
         Authorization: 'Basic base64credentials',
       },
     });
-    expect(axios).toHaveBeenNthCalledWith(2, {
-      method: 'GET',
-      url: 'https://auth.docker.io/token?service=registry.docker.io&scope=repository%3Alibrary%2Fnginx%3Apull&grant_type=password',
-      headers: {
-        Accept: 'application/json',
-      },
-    });
-    expect(warnSpy).toHaveBeenCalledWith(
-      expect.stringContaining(
-        'Docker Hub credentials were rejected for registry hub.test (status 401)',
-      ),
-    );
-    expect(result.headers.Authorization).toBe('Bearer public-token');
   });
 
   test('should fetch published date from Docker Hub tag metadata', async () => {

app/registries/providers/quay/Quay.test.ts

@@ -159,7 +159,7 @@ test('authenticate should not populate header with base64 bearer when anonymous'
   );
 });
 
-test('authenticate should retry anonymously when configured credentials are rejected with 403', async () => {
+test('authenticate should throw actionable error when configured credentials are rejected with 403', async () => {
   const quayInstance = new Quay();
   await quayInstance.register('registry', 'quay', 'test', {
     namespace: 'namespace',
@@ -168,39 +168,25 @@ test('authenticate should retry anonymously when configured credentials are reje
   });
   quayInstance.log = log;
   axios.mockRejectedValueOnce(new Error('Request failed with status code 403'));
-  axios.mockResolvedValueOnce({ data: { token: 'anon-token' } });
-  const warnSpy = vi.spyOn(quayInstance.log, 'warn');
 
-  const result = await quayInstance.authenticate(
-    { name: 'test/image' },
-    { headers: {}, url: 'https://quay.io/v2/test/image/manifests/latest' },
+  await expect(
+    quayInstance.authenticate(
+      { name: 'test/image' },
+      { headers: {}, url: 'https://quay.io/v2/test/image/manifests/latest' },
+    ),
+  ).rejects.toThrow(
+    /Authentication failed for registry quay\.test \(HTTP 403\): Quay credentials were rejected/,
   );
 
-  expect(axios).toHaveBeenNthCalledWith(1, {
+  expect(axios).toHaveBeenCalledTimes(1);
+  expect(axios).toHaveBeenCalledWith({
     method: 'GET',
     url: 'https://quay.io/v2/auth?service=quay.io&scope=repository:test/image:pull',
     headers: {
       Accept: 'application/json',
       Authorization: 'Basic bmFtZXNwYWNlK2FjY291bnQ6dG9rZW4=',
     },
   });
-  expect(axios).toHaveBeenNthCalledWith(2, {
-    method: 'GET',
-    url: 'https://quay.io/v2/auth?service=quay.io&scope=repository:test/image:pull',
-    headers: {
-      Accept: 'application/json',
-    },
-  });
-  expect(warnSpy).toHaveBeenCalledWith(
-    expect.stringContaining('Quay credentials were rejected for registry quay.test (status 403)'),
-  );
-  expect(result).toEqual(
-    expect.objectContaining({
-      headers: {
-        Authorization: 'Bearer anon-token',
-      },
-    }),
-  );
 });
 
 test('authenticate should throw when token request fails', async () => {