Skip to content

OAUTH_AUTHENTICATION.md

Latest commit

 

History

History
144 lines (129 loc) · 6.84 KB

OAUTH_AUTHENTICATION.md

File metadata and controls

144 lines (129 loc) · 6.84 KB

GitNapse OAuth Authentication

Contents

Overview

GitNapse supports multiple authentication paths and now includes OAuth device login implemented with octocrab. The implementation is optimized for terminal UX and avoids embedding user credentials in CLI history.

Current Login Modes in GitNapse

Mode How it Works Best For Storage
Environment token Reads GITHUB_TOKEN at runtime CI/CD and ephemeral sessions Not persisted by app
Manual token gitnapse auth set stores a token Local personal workflow User config directory, secure file permissions on UNIX
OAuth device flow gitnapse auth oauth login ... uses browser authorization and exchanges token via octocrab Safer interactive sign-in without pasting long tokens Stored in OS keyring when available; secure file fallback otherwise

OAuth Device Flow with octocrab

  1. GitNapse requests a device code from GitHub using octocrab against https://github.com.
  2. GitNapse tries to open verification_uri in your default browser automatically.
  3. If auto-open is unavailable, the terminal shows a clickable OSC8 hyperlink (when terminal supports it) plus the plain URL.
  4. User authorizes in browser with GitHub account.
  5. GitNapse polls token endpoint using octocrab's recommended flow logic, respecting interval and slow_down responses.
  6. The resulting OAuth access token is stored securely and then validated against /user.

GitHub Configuration

To use OAuth login, you need an OAuth App in GitHub settings.

  • Create an OAuth App in GitHub developer settings.
  • Copy the Client ID from the app.
  • For terminal device flow, no local redirect listener is required.
  • Use minimum scopes first (recommended: read:user), then add repo only if private repository access is needed.

GitNapse accepts either GITNAPSE_GITHUB_OAUTH_CLIENT_ID or compatibility fallback GITHUB_CLIENT_ID as Client ID source, and includes a built-in default Client ID for the official GitNapse OAuth app.

If you currently have a GitHub App but not an OAuth App, create the OAuth App as a separate credential set for user login.

Commands

One-time login with explicit Client ID:

gitnapse auth oauth login --client-id YOUR_OAUTH_CLIENT_ID --scope read:user --scope repo

Use environment for Client ID:

export GITNAPSE_GITHUB_OAUTH_CLIENT_ID=YOUR_OAUTH_CLIENT_ID
gitnapse auth oauth login --scope read:user --scope repo

Compatibility environment variable:

export GITHUB_CLIENT_ID=YOUR_OAUTH_CLIENT_ID
gitnapse auth oauth login --scope read:user

TUI shortcut:

# Inside the app, press:
o

The app performs a quick OAuth/authentication status check and prints guidance to use CLI login.

Short timeout tuning:

gitnapse auth oauth login --client-id YOUR_OAUTH_CLIENT_ID --timeout-secs 1200

Check OAuth state:

gitnapse auth oauth status

TUI Behavior

  • OAuth interactive login is CLI-first for reliability across terminal multiplexers and alternate screen modes.
  • Use gitnapse auth oauth login in normal terminal mode for device flow URL/code interaction.
  • Inside TUI, key o is intentionally reduced to quick status/help behavior.

Security Notes

  • Client secret is intentionally not required for this terminal device flow implementation.
  • OAuth access token is never printed back to terminal output.
  • Primary storage is OS keyring (Credential Manager on Windows, Keychain on macOS, Secret Service/libsecret on Linux when available).
  • WSL and no-keyring environments automatically fallback to local file storage with strict UNIX permissions (0600).
  • OAuth session metadata is persisted separately (expiry, refresh token, scopes, client id) to support safer session lifecycle handling.
  • If GITNAPSE_GITHUB_OAUTH_CLIENT_SECRET or GITHUB_CLIENT_SECRET is present, GitNapse attempts refresh-token exchange when access token is near expiry.
  • Prefer least-privilege scopes and rotate/revoke tokens when no longer needed.
  • For shared machines, prefer environment-based or ephemeral auth over persistent local token storage.
  • On logout (gitnapse auth clear), GitNapse removes credentials from keyring and also deletes fallback file if present.

Session Storage Recommendation

Current implementation uses OS keyring when available and falls back to secure local file storage in unsupported environments (for example WSL/headless Linux sessions without keyring service).

OAuth Troubleshooting

  • If you previously saw a rustls CryptoProvider panic, update to this build; GitNapse now installs a rustls provider explicitly before OAuth login.
  • .env is loaded at startup, so GITHUB_CLIENT_ID and related auth vars are available without manual export.
  • If browser auto-open does not work in your terminal/session, copy the displayed URL and open it manually.