Feature Proposal: OAuth Integration

### 1. Summary

The purpose of this proposal is to enhance `harbor-cli` with OAuth 2.0 authentication support, enabling passwordless, token-based logins. By integrating with standards-based identity providers such as OIDC, GitHub, or GitLab, the CLI will offer a seamless experience for both interactive users and automated pipelines, eliminating the need for static credentials and improving overall security.

### 2. Motivation

Developers and CI/CD environments currently rely on database-stored usernames and passwords, which can lead to secrets management challenges and increased risk of credential leakage. Introducing OAuth support will allow users to leverage short-lived tokens and refresh flows, align with enterprise identity policies, and remove the burden of embedding passwords in scripts or pipeline definitions. Moreover, by adopting widely supported OAuth grant types, `harbor-cli` will interoperate smoothly with popular identity solutions such as Azure AD, Keycloak, and GitLab.

### 3. Goals

Our objectives are threefold: first, to implement the OAuth Device Code Flow for interactive terminal sessions, guiding users through a browser-based authorization step; second, to support non-interactive scenarios via JWT Bearer or Client Credentials flows, enabling automated tokens to be provided in CI environments; and third, to securely cache and transparently refresh tokens in the user’s configuration directory (`~/.config/harbor-cli`), falling back to traditional username/password behavior only when OAuth is not configured.

### 4. Scope and Non-Goals

This enhancement will rely on Harbor’s existing OIDC endpoints and does not aim to build a dedicated OAuth server or introduce graphical login interfaces. SAML-based or other proprietary federation mechanisms remain outside the scope of this project, and we will focus on standards-compliant, CLI-friendly grant types.

### 5. User Scenarios

In an interactive setting, a developer might type `harbor-cli login --sso` and follow the displayed device code and URL to authorize access. On the CI side, a pipeline can invoke `harbor-cli login --sso --token-file /path/to/jwt` to authenticate without requiring human intervention. Once authenticated, the CLI will automatically detect expired tokens and invoke the configured refresh flow, ensuring uninterrupted access during long-running operations.

### 6. Configuration Format

Users will define OAuth settings in `~/.config/harbor-cli/config.yaml` under each registry, specifying the issuer URL, client ID, client secret, required scopes, and token endpoint. While sensible defaults can be provided, CLI flags such as `--issuer-url`, `--client-id`, `--client-secret`, and `--scopes` will allow users to override configuration on a per-command basis.

### 7. Security Considerations

All token storage will default to restrictive file permissions (600), and token encryption at rest can be offered as an opt-in enhancement. HTTPS connections to the issuer and token endpoints will validate TLS certificates, and users will be encouraged to trust only well-known certificate authorities to prevent man-in-the-middle attacks.