auth

README

Auth Package

The auth package provides modular authentication strategies for the remote client.

Authenticator Interface

All strategies implement the Authenticator interface, allowing them to be easily injected into any remote.Client.

type Authenticator interface {
    Apply(req *http.Request) error
}

Construction

There are two ways to build an authenticator:

1. From config — auth.Build(authType, options) parses the JSON options for a strategy, resolves any secret references (see Secret References) once, and returns the authenticator. This is what the remote Manager uses when it loads services.json. A reference that cannot be resolved is a loud error.

   authn, err := auth.Build("oauth2", optionsJSON)
   

2. Directly — the New* constructors take already-resolved plain values. They are pure: no I/O, no error.

   auth.NewAPIKey("X-Custom-Key", "my-secret-key")
   auth.NewBearer("my-jwt-token")
   auth.NewOAuth2("https://identity.example.com/oauth2/token", "my-client-id", "my-client-secret", []string{"read", "write"})
   

Supported Strategies

API Key Authentication

Uses a custom header (e.g., X-API-Key) with a fixed value.

Bearer Token Authentication

Uses the standard Authorization: Bearer <token> header.

OAuth2 Client Credentials Flow

Implements the OAuth2 Client Credentials flow with the following features:

• Automatic token caching.
• Expiry handling with a 1-minute safety buffer.
• Synchronized token updates to prevent race conditions.
• Scope support.

Secret References

Secret-bearing config fields (value, token, client_secret) are a SecretRef. A SecretRef is a parsed string that is either a literal value or a reference whose scheme prefix names where the value comes from:

Form	Meaning
"plain-value"	A literal value (the default — backward compatible).
"env:NAME"	Read from environment variable NAME.
"file:/path/to/file"	Read from a file; trailing whitespace is trimmed.
"literal:env:foo"	Explicit literal escape hatch, for a literal that begins with a scheme name.

This lets non-sensitive configuration (URLs, scopes, header names) live alongside references to credentials that are provided out-of-band, so the two are no longer fused into one sensitive blob.

In services.json, the same applies per field:

{
  "auth": {
    "type": "oauth2",
    "options": {
      "token_url": "https://identity.example.com/oauth2/token",
      "client_id": "my-client",
      "client_secret": "env:CLIENT_SECRET",
      "scopes": ["read", "write"]
    }
  }
}

References are resolved once, at startup — when Manager.LoadServices loads the file, or via auth.Build. A missing env var or an unreadable/empty file is a loud error — a reference never silently resolves to the empty string. Resolution is not repeated per request; if a referenced value changes, restart the process to pick it up.

Only the single prefixed-string form is supported; there is intentionally no object form. To add a new source (e.g. vault:), register a resolver in secret.go — no other code changes.

Strategy Configuration

APIKeyConfig

Used when the authentication type is "api_key".

Field	Type	Description
key	string	The HTTP header name (e.g., "X-API-Key").
value	SecretRef	The key value — a literal or a reference (see Secret References).

BearerConfig

Used when the authentication type is "bearer".

Field	Type	Description
token	SecretRef	The bearer token — a literal or a reference (see Secret References).

OAuth2Config

Used when the authentication type is "oauth2".

Field	Type	Description
token_url	string	The OAuth2 token endpoint URL.
client_id	string	The client identifier.
client_secret	SecretRef	The client secret — a literal or a reference (see Secret References).
scopes	[]string	Optional list of requested scopes.
insecure_skip_tls_verify	bool	Optional. Skips TLS certificate verification on the token request only. For local development against a self-signed identity provider — never enable in production. Defaults to false.

Documentation

Index

• type APIKey
  • func NewAPIKey(key, value string) *APIKey
  • func (a *APIKey) Apply(req *http.Request) error
• type APIKeyConfig
• type Authenticator
  • func Build(authType string, options json.RawMessage) (Authenticator, error)
• type Bearer
  • func NewBearer(token string) *Bearer
  • func (a *Bearer) Apply(req *http.Request) error
• type BearerConfig
• type OAuth2
  • func NewOAuth2(tokenURL, clientID, clientSecret string, scopes []string) *OAuth2
  • func (a *OAuth2) Apply(req *http.Request) error
  • func (a *OAuth2) SetInsecureSkipTLSVerify(skip bool)
• type OAuth2Config
• type SecretRef
  • func (s SecretRef) Resolve() (string, error)

Types

type APIKey

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

func NewAPIKey

func NewAPIKey(key, value string) *APIKey

NewAPIKey builds an API-key authenticator from already-resolved values.

func (*APIKey) Apply

func (a *APIKey) Apply(req *http.Request) error

type APIKeyConfig

type APIKeyConfig struct {
	Key   string    `json:"key"`
	Value SecretRef `json:"value"`
}

type Authenticator

type Authenticator interface {
	Apply(req *http.Request) error
}

Authenticator defines an interface for applying authentication to outgoing requests.

func Build

func Build(authType string, options json.RawMessage) (Authenticator, error)

Build constructs an authenticator for the given auth type from its raw JSON options. It is the single entry point callers (e.g. the remote Manager) use, so they need not know about individual strategies. Secret references are resolved here, once; an unresolvable reference is a loud error.

type Bearer

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

func NewBearer

func NewBearer(token string) *Bearer

NewBearer builds a bearer-token authenticator from an already-resolved token.

func (*Bearer) Apply

func (a *Bearer) Apply(req *http.Request) error

type BearerConfig

type BearerConfig struct {
	Token SecretRef `json:"token"`
}

type OAuth2

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

func NewOAuth2

func NewOAuth2(tokenURL, clientID, clientSecret string, scopes []string) *OAuth2

NewOAuth2 builds an OAuth2 client-credentials authenticator from already-resolved values.

func (*OAuth2) Apply

func (a *OAuth2) Apply(req *http.Request) error

func (*OAuth2) SetInsecureSkipTLSVerify

func (a *OAuth2) SetInsecureSkipTLSVerify(skip bool)

SetInsecureSkipTLSVerify controls whether the OAuth2 token request client skips certificate verification. This is intended for local development with self-signed identity-provider certificates only.

type OAuth2Config

type OAuth2Config struct {
	TokenURL              string    `json:"token_url"`
	ClientID              string    `json:"client_id"`
	ClientSecret          SecretRef `json:"client_secret"`
	Scopes                []string  `json:"scopes,omitempty"`
	InsecureSkipTLSVerify bool      `json:"insecure_skip_tls_verify,omitempty"`
}

type SecretRef

type SecretRef string

SecretRef is a secret-bearing configuration value: a literal, or a reference whose scheme prefix names where the value comes from. It is the raw string as written in config — it unmarshals from and marshals to a plain JSON string, so only the single prefixed-string form is supported; there is intentionally no object form.

"plain-value"        // literal (the default, backward compatible)
"env:NAME"           // read from environment variable NAME
"file:/path/to/file" // read from a file (trailing whitespace trimmed)
"literal:env:foo"    // explicit literal escape hatch

A value whose prefix is not a known scheme (including one with no colon at all) is treated as a literal. Resolution — the I/O — is a separate step; see Resolve.

func (SecretRef) Resolve

func (s SecretRef) Resolve() (string, error)

Resolve reads the concrete value for the reference. This is the single I/O seam: the only place that reads env/files and the only place that can fail. A missing env var or an unreadable/empty file is a loud error — a reference never silently resolves to the empty string. A literal is returned as-is; an empty literal (or the zero value) is allowed for backward compatibility.