[Usability issue] Notation login error message is confusing

[toddysm]

What is the areas you experience the issue in?

Notation CLI

What is not working as expected?

If somebody tries to sign in with invalid credentials, we are just passing through the registry error. This is not a very friendly experience.

notation login ghcr.io --username cloud-native-security --password ghp_EG6Dg2o6rHt1wdakjhfsfghiusdgfisdugfisfbv34hebrhwef
Error: GET "https://ghcr.io/v2/": GET "https://ghcr.io/token?scope=repository%3Auser%2Fimage%3Apull&service=ghcr.io": response status code 403: denied: denied

What did you expect to happen?

Provide a more friendly error message that removes the HTTP details.

How can we reproduce it?

Use the command above with wrong credentials.

Describe your environment

MacOS

What is the version of your Notation CLI or Notation Library?

notation version
Notation - a tool to sign and verify artifacts.

Version: 1.0.0-rc.4.230405
Go version: go1.20.2
Git commit: b008e79

[yizha1]

need design a friendly error message first

[Wwwsylvia]

How about something like:

[yizha1]

@toddysm could you check whether @Wwwsylvia proposal is good enough? Thanks.

[toddysm]

The error above is for not being able to connect to the registry, while the one I posted is not being authorized to access the registry. We should make sure that we provide the exact error to the user. The error should be helpful for the user to understand where the problem lies and how to troubleshoot.

• If it is authentication/authorization error, we should show something like:

  Error: Failed to login to <registry>. The user is not authorized to access the registry. 
  

• If it is a network error, we should show something like:

  Error: Failed to login to <registry>. Unable to connect to registry with DNS <registry>.
  

It is not one message fits all. We should identify all error conditions and reply with the right message based on the error condition.

[yizha1]

@toddysm I had a discussion with @Wwwsylvia and other maintainers. Currently it takes time to use specific error messages for each error condition like what you commented previously. Here are the improvements for v1 considering the timeline.

For notation login, there are two steps:

1. Validate the credentials
2. Store the credentials.

So my proposals for the error message:

1. Error messages for the failure of validate the credentials

Error: Failed to login to <registry>: Failed to validate the credentials: <details_thrown_from_library>

for example: (The two Get messages were from the called APIs, it takes time to translate each error code to a good specific message)

Error: Failed to login to <registry>: Failed to validate the credentials: GET "https://index.docker.io/v2/": GET "https://auth.docker.io/token?service=registry.docker.io": response status code 401: Unauthorized

2. Error message for the failure of store the credentials if credentials store is configured

Error: Failed to login to <registry>: Failed to store the credentials: <details_thrown_from_library>

3. Error message for the failure of store the credentials if credentials store is not configured

Error: Failed to login to <registry>: The credentials could not be saved because a credentials store is required to securely store the password. See https://notaryproject.dev/docs/how-to/registry-authentication

[FeynmanZhou]

The error message beginning is suggested to be revised to Error: Failed to log in to <registry>: .... Please note that the difference between login vs log in.