NextIteration.SpectreConsole.Auth.Providers.GitHub 0.2.0

NextIteration.SpectreConsole.Auth.Providers.GitHub

GitHub credential provider for NextIteration.SpectreConsole.Auth.

Drops a ready-to-use GitHubCredential, GitHubToken, authentication service, a Spectre.Console accounts add collector that runs the OAuth device flow (the same flow gh auth login uses by default), and an accounts list display formatter into a CLI that already uses the core auth package.

Install

dotnet add package NextIteration.SpectreConsole.Auth.Providers.GitHub

Requires the core package (NextIteration.SpectreConsole.Auth) — NuGet pulls it in transitively.

Prerequisites

You need an OAuth App with device flow enabled:

1. Create an OAuth App under GitHub → Settings → Developer settings → OAuth Apps (or your org's settings).
2. Tick Enable Device Flow in the app's settings.
3. Note its Client ID — it's public (not a secret) and is what the collector prompts for.

No client secret is involved: the device flow authenticates the user, not the app's secret.

Quick start

using NextIteration.SpectreConsole.Auth;
using NextIteration.SpectreConsole.Auth.Providers.GitHub;

services.AddCredentialStore(opts =>
{
    opts.CredentialsDirectory = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
        ".my-cli", "credentials");
});

services.AddHttpClient();            // IHttpClientFactory is required
services.AddGitHubAuthProvider();

// ... then hook up the accounts branch in your Spectre.Console configurator
// (from the core package):
//
//   config.AddAccountsBranch();

From that point on:

my-cli accounts add        # prompts for GitHub (and any other registered providers)
my-cli accounts list       # shows the authenticated user, scopes, host, masked token
my-cli accounts select <id>
my-cli accounts delete <id>

Resolving a token in consumer code:

public sealed class GitHubClient(GitHubAuthenticationService auth, IHttpClientFactory http)
{
    public async Task<string> GetRepositoriesAsync()
    {
        var token = await auth.AuthenticateAsync();
        using var client = http.CreateClient();
        client.BaseAddress = token.BaseUrl;
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token.AccessToken);
        client.DefaultRequestHeaders.UserAgent.ParseAdd("my-cli/1.0");
        client.DefaultRequestHeaders.Accept.ParseAdd("application/vnd.github+json");
        return await client.GetStringAsync("user/repos");
    }
}

The accounts add flow

The collector runs the OAuth device flow end to end:

1. Prompts for the GitHub host (default github.com), the OAuth App client id, and the requested scopes (default repo read:org).
2. Requests a device code — POST {host}/login/device/code.
3. Shows you the user code and verification URL (e.g. https://github.com/login/device). Open it in a browser and enter the code.
4. Polls POST {host}/login/oauth/access_token honouring the server interval, the slow_down back-off, and authorization_pending, until you authorise (or the code expires).
5. Enriches the credential — GET {api}/user confirms "authenticated as X" and records your login/name for the list display.

What gets stored

Each accounts add run serialises a GitHubCredential into the encrypted keystore:

accounts list shows the account (login (name)), the granted scopes, the API host, and the token masked as xxxx...xxxx.

Authentication model

• Classic OAuth App (non-expiring tokens). The stored access token is used forever; GitHubAuthenticationService.AuthenticateAsync() is a straight pass-through. A revoked token surfaces as a 401 on first use.
• OAuth App with expiring user tokens. The device flow also returns a refresh token and expiry. When the stored access token is expired (with a 30-second clock-skew buffer), the auth service refreshes it via POST {host}/login/oauth/access_token (grant_type=refresh_token) before returning a fresh GitHubToken.

Known limitation

A refreshed access token is not written back to the keystore in this version — each authenticate call that needs a refresh performs one. Consumers that authenticate frequently against an expiring app should cache the returned GitHubToken for its lifetime. (Persisting the refreshed token would require an update API on the core credential store.)

GitHub Enterprise Server

Enter your instance host (e.g. ghe.example.com) at the host prompt. The provider derives the web base (https://ghe.example.com/) and the REST API base (https://ghe.example.com/api/v3/) automatically, and labels the environment Enterprise.

Named HttpClient

The collector and the refresh path resolve an HttpClient via IHttpClientFactory.CreateClient("GitHub Credential Validator"). Consumers who want to pre-configure it (proxies, retry handlers, custom user-agent) can:

services.AddHttpClient(GitHubCredentialCollector.HttpClientName, c =>
{
    c.Timeout = TimeSpan.FromSeconds(30);
    c.DefaultRequestHeaders.UserAgent.ParseAdd("my-cli/1.0");
});

The provider does not mutate BaseAddress or DefaultRequestHeaders on the client — every endpoint is passed as an absolute URI per request, and a User-Agent is set per request (GitHub rejects API calls without one).

Supported platforms

Whatever the core package supports (currently Windows, macOS, Linux on .NET 8 and .NET 10).

License

MIT © Stuart Meeks