token

type Config ¶

type Config struct {
	// Access configures access control policy used by token/access.
	//
	// This is used to answer authorization checks (for example "user has permission X")
	// and is typically used in addition to authentication (token verification).
	Access *access.Config `yaml:"access,omitempty" json:"access,omitempty" toml:"access,omitempty"`

	// 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"`

	// 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"`

	// 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"`

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

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 token.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, individual token implementations may still be disabled if their nested configuration is nil (for example JWT == nil while Kind == "jwt").

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 should typically be provided in the corresponding field (JWT/Paseto/SSH).

If Kind is unknown, the token facade treats the configuration as invalid and Generate/Verify return token/errors.ErrInvalidConfig.

Access control (Access) ¶

Access configures optional access-control policy wiring (see package token/access). It is orthogonal to the token kind: some services may use token verification to establish identity (subject) and then evaluate permissions via Access.

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(name env.Name, cfg *Config, fs *os.FS, sig *ed25519.Signer, ver *ed25519.Verifier, gen id.Generator) *Token

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

func (t *Token) Verify(token []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.