github

package
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package github provides chok's GitHub OAuth 2.0 implementation of account.AuthProvider.

Wire it via chok.yaml — chok bundles this provider through the account/providers/blessed curator, so applications need no Go code:

account:
  enabled: true
  oauth_callback_frontend_url: "https://app.example.com/auth/finish"
  providers:
    github:
      enabled: true
      client_id:     "${GITHUB_CLIENT_ID}"
      client_secret: "${GITHUB_CLIENT_SECRET}"
      redirect_url:  "https://app.example.com/auth/github/callback"
      enterprise_url: "https://github.company.com"   # optional

Protocol note: GitHub does NOT speak OIDC, so unlike the google provider we cannot validate an ID Token. Trust comes from HTTPS endpoint pinning + access-token-bound REST calls. The OAuth state parameter (Module-generated) is the CSRF defense.

GitHub's `/user` endpoint may return an empty email when the user has hidden their primary in privacy settings; we fall back to `/user/emails` to find a primary + verified address. Without the `user:email` scope (default) /user/emails returns 404, so requests MUST keep that scope present.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Factory

func Factory(rawCfg any) (account.AuthProvider, error)

Factory is the account.ProviderFactory implementation registered for "github". chok's parts.DefaultAccountBuilder / account.RegisterConfiguredProviders look it up via account.LookupProviderFactory("github") and invoke it with the per-provider yaml block.

func New

func New(opts Options) (account.AuthProvider, error)

New constructs a GitHub provider against the supplied options. Unlike the google provider there's no OIDC discovery — github.com endpoints are static, and Enterprise installs derive theirs from EnterpriseURL.

Types

type Options

type Options struct {
	// Enabled mirrors the kill switch in yaml. When false the factory
	// short-circuits before validating client_id/secret, so an
	// operator can keep `enabled: false` as a staging stanza.
	Enabled bool `mapstructure:"enabled"`

	// ClientID and ClientSecret come from a GitHub OAuth App
	// (Settings → Developer settings → OAuth Apps). Required when
	// Enabled is true. ClientSecret is masked by chok.config.Redact /
	// AccountOptions.GoString through the `*secret*` heuristic.
	ClientID     string `mapstructure:"client_id"`
	ClientSecret string `mapstructure:"client_secret"`

	// RedirectURL must match a callback URL registered against the
	// GitHub OAuth App byte-for-byte (scheme + host + path).
	RedirectURL string `mapstructure:"redirect_url"`

	// Scopes overrides the default set ("read:user", "user:email").
	// `user:email` is required for the email-fallback path against
	// /user/emails when /user.email is hidden. Removing it without
	// understanding the email-flow consequence breaks /login on any
	// account that has hidden its email — be very deliberate.
	Scopes []string `mapstructure:"scopes"`

	// EnterpriseURL points to a self-hosted GitHub Enterprise Server
	// install (e.g. "https://github.company.com"). When set, all
	// auth/token endpoints AND REST API calls are rooted there
	// instead of github.com / api.github.com. Empty = github.com.
	EnterpriseURL string `mapstructure:"enterprise_url"`
}

Options is the typed config decoded from chok.yaml's account.providers.github block.

func (*Options) Validate

func (o *Options) Validate() error

Validate enforces the minimum-viable config when the provider is enabled. Run pre-construction so a missing client_id surfaces as a startup failure, not a runtime auth one.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL