cijwt

Documentation

Overview

Package cijwt provides an http.RoundTripper that authenticates outbound requests on a per-host basis with a JWT, sourcing the token from a CI/CD platform's OIDC integration or signing it locally.

Each configured host gets its token one of three ways:

• WithHostAudience mints an OIDC ID token for the given audience from the GitHub/Forgejo Actions token endpoint (see the actionsoidc package), caching it for the first 50% of its lifetime and reminting on demand.
• WithHostToken sends a static JWT as-is, e.g. a GitLab CI id_token injected into the job environment.
• WithHostJWK signs a fresh, short-lived JWT with a private key from a JWK, issuing a new token for every request rather than caching it.

Requests to hosts that were not configured are forwarded unchanged, so a request to a registry the JWT is not meant for keeps its existing authentication.

Index

• type Option
  • func WithHostAudience(host, audience string) Option
  • func WithHostJWK(host, jwk, iss, aud, sub string) Option
  • func WithHostToken(host, token string) Option
  • func WithInner(rt http.RoundTripper) Option
• type Transport
  • func NewTransport(opts ...Option) (*Transport, error)
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Types

type Option

type Option func(*options)

Option configures a Transport.

func WithHostAudience

func WithHostAudience(host, audience string) Option

WithHostAudience configures host to be authenticated with an OIDC ID token minted for the given audience from the GitHub/Forgejo Actions token endpoint, cached for the first 50% of its lifetime and reminted on demand.

func WithHostJWK

func WithHostJWK(host, jwk, iss, aud, sub string) Option

WithHostJWK configures host to be authenticated with a JWT signed locally using a private key parsed from jwk (a single JSON Web Key holding an Ed25519 or ECDSA private key; the signing algorithm is derived from the key type, see the jwt package). Each request gets a freshly signed, 60-second-lived token carrying iss, aud, and sub as given and the signing key's id in the "kid" header. Unlike WithHostAudience, the token is never cached.

func WithHostToken

func WithHostToken(host, token string) Option

WithHostToken configures host to be authenticated with the given static JWT, sent as-is (e.g. a GitLab CI id_token).

func WithInner

func WithInner(rt http.RoundTripper) Option

WithInner sets the underlying RoundTripper that requests are forwarded to. Defaults to http.DefaultTransport.

type Transport

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

Transport is an http.RoundTripper that stamps Authorization: Bearer <jwt> on requests whose URL host was configured with WithHostToken, WithHostAudience, or WithHostJWK. Any existing Authorization header on a configured host is overwritten; requests to other hosts pass through untouched.

func NewTransport

func NewTransport(opts ...Option) (*Transport, error)

NewTransport returns a Transport configured by opts. At least one host must be configured. It returns an error if the same host is configured more than once, whether via WithHostToken, WithHostAudience, WithHostJWK, or a mix of them, or if a WithHostJWK key fails to parse.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.