auth

README

go-auth

Small Go authentication interfaces and JWT-backed authenticator helpers.

Packages

• auth: generic token/authenticator interfaces and token value types
• authenticators: implementation notes for custom authenticators
• authenticators/memory: in-memory authenticator implementation
• jwt: minimal JWT signing and verification helpers

Memory Authenticator

The memory authenticator keeps refresh tokens in process memory only. Refresh tokens are lost when the authenticator is discarded or the process exits, so use it for tests, examples, and single-process applications rather than durable multi-instance deployments.

type Claims struct {
	Expires int64  `json:"expires_at,omitempty"`
	Role    string `json:"role,omitempty"`
	Sub     string `json:"sub"`
}

func (c *Claims) ExpiresAt() int64    { return c.Expires }
func (c *Claims) SetExpiresAt(v int64) { c.Expires = v }
func (c *Claims) Subject() string      { return c.Sub }

ctx := context.Background()

a, err := memory.NewAuthenticator[*Claims]("secret", 15*time.Minute, 24*time.Hour)
if err != nil {
	log.Fatal(err)
}

at, rt, err := a.Issue(ctx, &Claims{Sub: "user_123", Role: "admin"})
if err != nil {
	log.Fatal(err)
}

claims, err := a.Verify(ctx, at.Value)
if err != nil {
	log.Fatal(err)
}

at, rt, err = a.Refresh(ctx, rt.Value)
if err != nil {
	log.Fatal(err)
}

_ = claims
_ = at
_ = a.Revoke(ctx, rt.Value)

Expiration Behavior

Token.ExpiresAt and Claims.ExpiresAt use Unix timestamps in seconds. A zero expiration means no expiration is configured.

jwt.Tokener.Sign mutates the provided claims when the tokener has a positive TTL: it calls SetExpiresAt with the calculated Unix expiration timestamp before signing.

Examples

Run the complete example:

go run ./examples

Documentation

Overview

Package auth defines small authentication interfaces and credential types.

Index

• Variables
• type Authenticator
• type Identifier
• type Token

Variables

var (
	ErrInvalidIdentity error = errStr("invalid identity")
	ErrInvalidToken    error = errStr("invalid token")
	ErrExpiredToken    error = errStr("expired token")
)

Types

type Authenticator

type Authenticator[T Identifier] interface {
	// Issue creates a new token pair for the provided identity.
	Issue(ctx context.Context, identity T) (at, rt *Token, err error)
	// Refresh exchanges a token pair for a new token pair.
	Refresh(ctx context.Context, refreshToken string) (at, rt *Token, err error)
	// Verify validates an access token and returns its identity.
	Verify(ctx context.Context, accessToken string) (identity T, err error)
	// Revoke invalidates a single refresh token.
	Revoke(ctx context.Context, refreshToken string) (err error)
	// RevokeAll invalidates every refresh token associated with an identity.
	RevokeAll(ctx context.Context, identity T) (err error)
}

Authenticator issues, verifies, refreshes, and revokes credentials for an identity type.

type Identifier

type Identifier interface {
	Subject() string
}

Identifier exposes the stable subject identifier used in tokens.

type Token

type Token struct {
	Value     string
	ExpiresAt int64
}

Token contains a token value and its expiration time.

ExpiresAt is a Unix timestamp in seconds. A zero value means the token has no configured expiration.