gitcred

Documentation

Overview

Package gitcred answers git's credential-helper protocol from the records in a creds.Store, so a git operation against a connected forge authenticates with that connection's token.

It is the protocol and the origin matching alone. Registering the helper in git's configuration, the command line git runs it with, and where the store lives are the consumer's: its helper subcommand opens the store and hands Helper.Serve git's operation argument and its standard streams.

The helper never refreshes a token. It is a short-lived process reading a store the consumer's server rotates under a compare-and-swap, so a helper that rotated too would race that server and could spend a pair the server then overwrites. A token it finds expired is declined with one line saying why.

Index

• type Helper
  • func New(store creds.Store, opts ...forgeapi.Option) *Helper
  • func (h *Helper) Serve(ctx context.Context, action string, in io.Reader, out, diag io.Writer) error

Types

type Helper

type Helper struct {
	// contains filtered or unexported fields
}

Helper answers git's credential-helper protocol for the connections whose records a store holds, and is safe for concurrent use. A get answers the connection whose web base URL has the remote's scheme, host and effective port, the first by key where several do, with x-access-token as the username on GitHub, oauth2 on GitLab and the record's account on Gitea and Forgejo. One it cannot answer writes nothing for git, so later helpers and prompting still work, is counted through forgeapi.Counters.HelperDecline, and writes one line to diag unless no connection owns the origin.

func New

func New(store creds.Store, opts ...forgeapi.Option) *Helper

New builds the helper over store, reading the logger and the counters from opts. It reads nothing until Helper.Serve.

func (*Helper) Serve

func (h *Helper) Serve(ctx context.Context, action string, in io.Reader, out, diag io.Writer) error

Serve answers one git invocation: action is git's operation argument, in is the attribute block git writes, out is what git reads back, and diag is the one line a user sees when a credential is declined. An expired token is declined, never renewed here, and so is a record carrying a usability mark the server's refresh wrote, with the mark as the reason. A store is ignored; an erase keeps the connection and is counted through forgeapi.Counters.HelperErase; any other action is ignored, as git's protocol asks. A decline is not an error: Serve fails only where in exceeds its bound or cannot be read, or where out or diag cannot be written.