Atlas discovery: use the Admin API access-list endpoints to give better connection and API error diagnostics

Summary

Atlas failures caused by IP access lists are currently reported with whatever text the API or the driver produced. We can do much better, because the Atlas Admin API can tell us exactly what the access lists contain. This is deliberately deferred as future work: the immediate PR (#813) keeps the messaging generic on purpose, because guessing a cause and getting it wrong is worse than saying less.

Background

There are two distinct access lists in Atlas, and confusing them is the main source of trouble:

List	Scope	What it gates
API access list	Per API Key / per Service Account	Calls to the Atlas Administration API
Project IP access list (Network Access)	Per project	Client connections to clusters on port 27017

Two documented behaviours make this genuinely confusing in practice:

• The API access list is per credential and all-or-nothing. Per Get Started with the Atlas Administration API: "you can make API requests from any address on the internet as long as the IP access list is empty. Once you add an IP access list entry, only requests originating from that IP address can make requests." So one credential can be working while another fails from the same machine at the same moment, which reads like flakiness.
• The list is enforced when a Service Account token is used, not when it is created: "You can generate a token from any IP address, but you can only use it to call the API if your IP address is on the access list." The log therefore shows a token minted successfully, immediately followed by 403 on every call with it.

Proposed enhancement

1. Surface the project IP access list on a failed cluster connection

GET /api/atlas/v2/groups/{groupId}/accessList (Return All Project IP Access List Entries) returns the entries that gate cluster connections. When a cluster connection fails, we already know the projectId and we already have a credential that owns the project, so we could fetch the list and show it instead of speculating:

This project's IP access list allows: 203.0.113.5/32 (office), 10.0.0.0/8.

Notable details:

• Requires the Project Read Only role. Degrade silently to the current message when the credential lacks it, rather than stacking a second error on the first.
• Paginated (itemsPerPage max 500, pageNum), so the existing requestAllPages helper covers it.
• Documents application/vnd.atlas.2023-01-01+json; the client currently sends 2023-02-01 for every request, so this may need a per-endpoint version override.
• Entries carry ipAddress / cidrBlock / awsSecurityGroup, plus an optional deleteAfterDate. An expired temporary entry is its own good explanation for "it worked yesterday" and worth calling out.
• If 0.0.0.0/0 is present, say so: it immediately rules the access list out and points elsewhere.

2. Surface the per-credential API access list in the credential manager

GET /api/atlas/v2/orgs/{orgId}/apiKeys/{apiUserId}/accessList (and the Service Account equivalent) would let the credential-management QuickPick show why one credential is refused while its sibling works. Today the user has to infer this.

3. Guess the cause where we can, but only where it is defensible

This is the part that needs care. We can classify confidently when Atlas tells us the answer:

• errorCode: IP_ADDRESS_NOT_ON_ACCESS_LIST on the Admin API is unambiguous, and the detail even contains the rejected IP verbatim. Combined with the access-list contents, this could become a precise, fully actionable message.

We cannot currently classify the cluster-side TLS failure:

Error: 00B92AFAC07A0000:error:0A000438:SSL routines:ssl3_read_bytes:tlsv1 alert internal error:
../deps/openssl/openssl/ssl/record/rec_layer_s3.c:918:SSL alert number 80

MongoDB documents that the project IP access list gates client connections and that a blocked address fails an end-to-end TCP test on port 27017, but nowhere documents that a blocked address surfaces as this alert. A paused or provisioning cluster and a TLS version or cipher mismatch are equally undocumented for the same signature. Fetching the access list would let us decide it factually rather than guess.

4. Optional, needs a separate decision: determine the client's public IP

Comparing our own address against the list would make the diagnosis exact, but that means an outbound call to a third-party IP echo service. That is a new network dependency with privacy implications and should not be added without an explicit decision. Without it, showing the list and letting the user compare by eye is already a large improvement.

Current state (for context)

Landed in #813, so the groundwork is there:

• The full Atlas error envelope (errorCode, reason, detail, parameters) is parsed, traced, and carried on AtlasApiError, so errorCode is available to branch on.
• Failed responses trace retry-after and the x-ratelimit-* headers, so throttling is distinguishable.
• Deep links exist to the credential's Atlas access settings and to the project's Network Access page (atlasDeepLinks.ts).
• atlasConnectionErrors.ts detects the TLS signature and the modal deliberately lists things to check rather than naming a cause.

Acceptance criteria

• A failed cluster connection can show the project's actual IP access list entries when the owning credential has Project Read Only.
• Missing permission degrades silently to the existing message.
• 0.0.0.0/0 and expired deleteAfterDate entries are called out explicitly.
• IP_ADDRESS_NOT_ON_ACCESS_LIST on the Admin API produces a precise message naming the rejected IP and the credential.
• No claim of a cause that is not supported by an Atlas errorCode or by the access-list contents.

Read atlasConnectionErrors.ts and atlasDeepLinks.ts, then trace the requestAllPages helper and AtlasApiError handling introduced in PR #813. Map the cluster-connection and credential-manager entry points before fitting the documented Atlas endpoints into the existing flows. Done means the acceptance criteria are met without claiming unsupported causes.