Skip to content

auth.md

Latest commit

 

History

History
206 lines (147 loc) · 6.54 KB

auth.md

File metadata and controls

206 lines (147 loc) · 6.54 KB

CLI: auth

Overview

The auth command group manages credentials for OCI registries. It provides login and logout subcommands that persist credentials locally (via the Docker credential store or ~/.docker/config.json) and verify them against the registry before storing.

All other regshape commands resolve credentials automatically using the credential resolution chain (see Credential Resolution).

Usage

regshape auth login  [OPTIONS] --registry <registry>
regshape auth logout [OPTIONS] --registry <registry>

Subcommands

Subcommand Description
login Authenticate against a registry and persist credentials
logout Remove persisted credentials for a registry

auth login

Options

Option Short Type Default Description
--registry -r string required Registry hostname (e.g., registry.example.com)
--username -u string prompt Username (overrides global --username)
--password -p string prompt (hidden) Password (overrides global --password)
--password-stdin flag false Read password from stdin instead of prompting
--docker-config path none Alternate Docker config file path
--time-methods flag false Print execution time for individual method calls
--time-scenarios flag false Print execution time for multi-step workflows
--debug-calls flag false Print request/response headers for each HTTP call

Behavior

  1. Resolve credentials from flags (or prompt interactively if omitted).
  2. Issue GET /v2/ using a direct HTTP request with the requests library so that the full Bearer challenge/401-retry cycle is executed automatically (required for Docker Hub and other token-based registries).

    Note: This will migrate to RegistryClient (via AuthMiddleware) once the libs/transport/ layer is implemented.

  3. If the final response is 200 or 401 on retry, treat as credential failure.
  4. On success, persist credentials:
    • If the registry has a credHelpers entry in ~/.docker/config.json, use dockercredstore.store().
    • Otherwise, write Base64-encoded username:password into the auths section of ~/.docker/config.json.

Exit Codes

Code Meaning
0 Login successful
1 Authentication failed (wrong credentials or registry unreachable)

Examples

# Interactive prompt for credentials
regshape auth login -r registry.example.com

# Explicit credentials
regshape auth login -r registry.example.com -u alice -p s3cr3t

# Read password from stdin (e.g., from a secrets manager)
echo "$MY_TOKEN" | regshape auth login -r registry.example.com -u alice --password-stdin

# JSON output
regshape --json auth login -r registry.example.com -u alice -p s3cr3t

# Telemetry: log scenario timing and HTTP call details
regshape auth login -r registry.example.com --time-scenarios --debug-calls

Output Format

Plain text (default)

Login succeeded.

JSON (--json)

{"status": "success", "registry": "registry.example.com"}

Error (plain text)

Error: Login failed for registry.example.com: <reason>

auth logout

Options

Option Short Type Default Description
--registry -r string required Registry hostname
--docker-config path none Alternate Docker config file path
--time-methods flag false Print execution time for individual method calls
--time-scenarios flag false Print execution time for multi-step workflows
--debug-calls flag false Print request/response headers for each HTTP call

Behavior

  1. If the registry has a credHelpers entry in ~/.docker/config.json, call dockercredstore.erase().
  2. Otherwise, remove the registry's entry from the auths section of ~/.docker/config.json.
  3. If no credentials are found for the registry, exit 0 with an informational message (idempotent).

Exit Codes

Code Meaning
0 Logout successful (or no credentials to remove)
1 Error removing credentials

Examples

regshape auth logout -r registry.example.com
regshape --json auth logout -r registry.example.com

Output Format

Plain text (default)

Removing login credentials for registry.example.com.

or, if no stored credentials:

Not logged in to registry.example.com.

JSON (--json)

{"status": "success", "registry": "registry.example.com"}

Credential Resolution

All regshape commands (not just auth) resolve credentials using the following priority chain implemented in libs/auth/credentials.resolve_credentials():

Priority Source Notes
1 --username / --password global flags Explicit always wins
2 Docker credHelpers for the registry dockercredstore.get()
3 ~/.docker/config.json auths section dockerconfig.load_config()
4 Anonymous username=None, password=None

Anonymous credentials still work with registries such as Docker Hub because AuthMiddleware completes the Bearer challenge exchange without credentials, which those registries accept for public repositories.

Implementation

File Role
src/regshape/libs/auth/credentials.py resolve_credentials() helper
src/regshape/cli/auth.py Click auth group + login / logout commands
src/regshape/cli/main.py Top-level group; registers auth group; calls resolve_credentials()

Error Messages

Scenario Message
Wrong credentials Error: Login failed for <registry>: authentication rejected
Registry unreachable Error: Login failed for <registry>: <connection error>
No cred helper found Falls back to docker config file silently
Credential store error Error: Could not store credentials: <reason>

Open Questions

  • Should login validate the token scope (e.g., push/pull) or just /v2/ reachability?
  • Should auth status <registry> be added to display current credential source?