ghkeys

README

go-ghkeys

Fetch a GitHub user's SSH public keys and turn the supported ones into age recipients. FetchRecipients GETs https://github.com/<username>.keys through a caller-supplied HTTPClient (so the transport is injectable and fully testable), parses the authorized-keys response, and skips — with a logged warning — any key age cannot represent. Depends only on the standard library plus filippo.io/age.

Install

go get github.com/gomatic/go-ghkeys

Usage

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/gomatic/go-ghkeys"
)

func main() {
	rcpts, err := ghkeys.FetchRecipients(context.Background(), http.DefaultClient, "octocat")
	if err != nil {
		panic(err)
	}
	fmt.Printf("fetched %d age recipients\n", len(rcpts))
}

HTTPClient is any type with Do(*http.Request) (*http.Response, error) — *http.Client satisfies it directly, and tests inject a stub.

Errors

Every failure wraps a sentinel matchable with errors.Is:

• ghkeys.ErrFetchKeys — the request could not be built or sent, returned a non-200 status, or its body could not be read.
• ghkeys.ErrNoValidKeys — the response contained no key parseable into an age recipient.

Build & test

The Makefile, .golangci.yaml, .editorconfig, .gitignore, and .github/ are the canonical gomatic Go toolchain, owned and distributed by nicerobot/tools.repository — do not edit them in-tree; per-repo changes belong in a Makefile.local. Run the full gate (lint, staticcheck, govulncheck, 100% coverage) with make check.

Documentation

Overview

Package ghkeys fetches a GitHub user's SSH public keys and converts the supported ones into age recipients. FetchRecipients GETs https://github.com/<username>.keys through a caller-supplied HTTPClient (so the transport is injectable and testable), parses the authorized-keys body, and skips — with a warning logged to an injectable Logger — any key age cannot represent. Failures carry a sentinel (ErrFetchKeys or ErrNoValidKeys) recoverable with errors.Is.

Index

• func FetchRecipients(ctx context.Context, client HTTPClient, username Username, options ...Option) ([]age.Recipient, error)
• type Error
  • func (e Error) Error() string
• type HTTPClient
• type Logger
  • func (o Logger) Apply(c *config)
• type Option
• type Username

Functions

func FetchRecipients

func FetchRecipients(ctx context.Context, client HTTPClient, username Username, options ...Option) ([]age.Recipient, error)

FetchRecipients fetches SSH public keys for a GitHub user and returns age recipients.

Types

type Error

type Error string

Error is ghkeys's sentinel-error type. Every error the package can emit is declared as a const of this type, so each one is matchable with errors.Is rather than by string comparison. It follows the same shape as the rest of the ecosystem's sentinel-error helpers.

const (
	// ErrFetchKeys is the leading sentinel wrapped when the GitHub keys endpoint
	// cannot be requested, returns a non-200 status, or its body cannot be read.
	ErrFetchKeys Error = "failed to fetch keys"
	// ErrNoValidKeys is returned when the response contains no SSH public key
	// that could be parsed into an age recipient.
	ErrNoValidKeys Error = "no valid keys found"
)

func (Error) Error

func (e Error) Error() string

Error returns the constant's text, implementing the error interface.

type HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient is the interface for making HTTP requests.

type Logger

type Logger struct{ *slog.Logger }

Logger is an Option that routes the skip warning (emitted for keys age cannot represent) to a specific slog.Logger instead of slog.Default.

func (Logger) Apply

func (o Logger) Apply(c *config)

Apply sets the injected logger on the call config.

type Option

type Option interface {
	Apply(*config)
}

Option configures a FetchRecipients call. Options are type-based so the compiler verifies each one and the public surface stays additive.

type Username

type Username string

Username is the GitHub login whose .keys endpoint is fetched.