token

type Config ¶

type Config struct {
	// JWT configures the JWT token implementation.
	//
	// When Kind == "jwt", this configuration is consumed by token/jwt.
	JWT *jwt.Config `yaml:"jwt,omitempty" json:"jwt,omitempty" toml:"jwt,omitempty" validate:"required_if=Kind jwt"`

	// Paseto configures the PASETO token implementation.
	//
	// When Kind == "paseto", this configuration is consumed by token/paseto.
	Paseto *paseto.Config `yaml:"paseto,omitempty" json:"paseto,omitempty" toml:"paseto,omitempty" validate:"required_if=Kind paseto"`

	// SSH configures the SSH token implementation.
	//
	// When Kind == "ssh", this configuration is consumed by token/ssh.
	SSH *ssh.Config `yaml:"ssh,omitempty" json:"ssh,omitempty" toml:"ssh,omitempty" validate:"required_if=Kind ssh"`

	// Kind selects the token implementation to use.
	//
	// Supported values: "jwt", "paseto", "ssh".
	Kind string `yaml:"kind,omitempty" json:"kind,omitempty" toml:"kind,omitempty" validate:"required,oneof=jwt paseto ssh"`
}

Config configures token generation and verification for a go-service application.

This type is typically embedded into a larger service configuration and consumed by the top-level token facade (see NewToken), which delegates to the configured token implementation.

Enablement model ¶

Enablement is modeled by presence:

• A nil *Config means "token support disabled" at the top level.
• When enabled, Kind must select a supported implementation and that implementation's nested configuration must be present.

Selecting an implementation (Kind) ¶

Kind selects the token implementation used by the token facade. Supported kinds are:

• "jwt": JSON Web Tokens (see package token/jwt)
• "paseto": PASETO v4 public tokens (see package token/paseto)
• "ssh": SSH-style signed tokens (see package token/ssh)

The selected implementation's nested configuration must be provided in the corresponding field (JWT/Paseto/SSH).

Config validation rejects unknown Kind values. If validation is bypassed, the token facade treats the configuration as invalid and Token.Generate/Token.Verify return github.com/alexfalkowski/go-service/v2/token/errors.ErrInvalidConfig.

func (c *Config) IsEnabled() bool

type Generator ¶

type Generator interface {
	// Generate creates a new token for the given audience and subject.
	//
	// Implementations should treat aud/sub as logical identity inputs and produce
	// a token suitable for later validation by a corresponding Verifier.
	Generate(aud, sub string) ([]byte, error)
}

Generator generates authentication tokens for a given audience and subject.

This interface represents the "issuance" side of a token system. Concrete implementations may generate different token formats depending on configuration (for example JWT, PASETO, or other schemes).

Parameters ¶

Generate accepts two identity inputs:

• aud: the intended audience for the token (who the token is meant for).
• sub: the subject identifier (who/what the token represents).

In claim-based token formats (for example JWT/PASETO), aud and sub are typically encoded into standard claims.

Some token kinds may ignore one or both parameters (for example formats that do not carry claims or that encode identity differently). Callers should consult the concrete implementation's documentation for exact semantics.

Return value ¶

Generate returns the serialized token bytes. For text-based token formats, these bytes are typically UTF-8 encoded.

Errors ¶

Generate returns an error when token issuance fails (for example invalid configuration, missing key material, signing failures, or serialization errors).

type Token ¶

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

Token is a facade that generates and verifies tokens using the implementation selected by configuration.

It standardizes the call sites for token issuance and validation, while allowing the actual token format and crypto scheme to be chosen by configuration.

func NewToken(cfg *Config, fs *os.FS, gen id.Generator) *Token

func (t *Token) Generate(aud, sub string) ([]byte, error)

func (t *Token) Verify(tkn []byte, aud string) (string, error)

type Verifier ¶

type Verifier interface {
	// Verify validates token for the given audience and returns the subject identifier.
	Verify(token []byte, aud string) (string, error)
}

Verifier verifies authentication tokens for an expected audience and returns the subject identifier.

This interface represents the "verification" side of a token system. Concrete implementations may verify different token formats (for example JWT, PASETO, or other schemes) and may impose additional checks such as issuer matching, algorithm constraints, key ID matching, or time validity.

Parameters ¶

Verify accepts:

• token: the serialized token bytes to verify.
• aud: the expected audience value for which the token must be valid.

In claim-based token formats (for example JWT/PASETO), aud is typically validated against an "aud" claim. Some token kinds may ignore aud entirely (for example formats without claims). Callers should consult the concrete implementation's documentation for exact semantics.

Return value ¶

On success, Verify returns the subject identifier represented by the token (commonly the "sub" claim). If the token kind does not carry a subject claim, the implementation may return an alternate identifier.

Errors ¶

Verify returns an error when validation fails (for example malformed token, signature mismatch, wrong issuer/audience, expired/not-yet-valid token, key mismatch, or missing key material). When an error is returned, the subject return value should not be trusted.