authcore

type AuthCore ¶

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

AuthCore is the central object of the library. It holds shared configuration, the logger, and the key manager, and is the entry point for all authentication sub-modules.

Create one instance per application; it is safe for concurrent use.

func New(cfg Config) (*AuthCore, error)

// Minimal — all defaults apply.
auth, err := authcore.New(authcore.DefaultConfig())

// Custom keys directory (useful in containers or tests).
cfg := authcore.DefaultConfig()
cfg.KeysDir = "/run/secrets/authcore"
auth, err := authcore.New(cfg)

package main

import (
	"fmt"
	"os"

	"github.com/Glyndor/authcore"
)

func main() {
	dir, _ := os.MkdirTemp("", "authcore-example-")
	defer func() { _ = os.RemoveAll(dir) }()

	cfg := authcore.DefaultConfig()
	cfg.EnableLogs = false
	cfg.KeysDir = dir

	auth, err := authcore.New(cfg)
	if err != nil {
		panic(err)
	}
	fmt.Println(auth.Keys() != nil)
}

Output:
true

func (a *AuthCore) Config() Config

func (a *AuthCore) Keys() Keys

func (a *AuthCore) Logger() Logger

type Config ¶

type Config struct {
	// EnableLogs controls whether the library emits log output.
	// Defaults to true.
	EnableLogs bool

	// Timezone is used for any time-sensitive operations inside the library.
	// Defaults to time.UTC.
	Timezone *time.Location

	// Logger allows callers to inject a custom logging backend
	// (e.g. slog, zap, zerolog). When set, EnableLogs is ignored.
	// If nil and EnableLogs is true, a default stdlib logger is used.
	Logger Logger

	// KeysDir is the directory where authcore creates and stores cryptographic
	// key files (ed25519_private.pem, ed25519_public.pem, refresh_secret.key).
	//
	// Defaults to ".authcore" relative to the current working directory.
	// Use an absolute path in containerised or restricted environments.
	//
	// The directory is created automatically on first use. A .gitignore is
	// written inside it to prevent accidental commits of key material.
	//
	// Ignored when KeyStore is set.
	KeysDir string

	// KeyStore optionally overrides where cryptographic keys come from. When
	// nil (the default), authcore uses the disk store under KeysDir. Set it to
	// source keys from a secret manager, environment, or KMS instead — see
	// NewKeyStoreFromKeys and NewKeyStoreFromPEM. When set, KeysDir is ignored.
	KeyStore KeyStore
}

Config holds the top-level configuration for an AuthCore instance. Zero values are replaced by safe defaults via DefaultConfig or applyDefaults.

func DefaultConfig() Config

cfg := authcore.DefaultConfig()
cfg.EnableLogs = false          // disable logs for tests
auth, err := authcore.New(cfg)

package main

import (
	"fmt"

	"github.com/Glyndor/authcore"
)

func main() {
	cfg := authcore.DefaultConfig()
	fmt.Println(cfg.KeysDir)
}

Output:
.authcore

type KeyStore ¶ added in v1.6.0

type KeyStore interface {
	// Load returns the key material, or an error if it cannot be obtained or
	// fails validation.
	Load() (Keys, error)
}

KeyStore sources authcore's cryptographic key material (the Ed25519 signing pair and the HMAC refresh secret).

The default is disk: New generates and loads PEM files under Config.KeysDir. Set Config.KeyStore to override that — for example to source keys from a secret manager, environment variables, or KMS, which is the right fit for serverless or disk-averse deployments where a mounted volume is awkward.

Implementations are consulted once, at New time. The returned Keys must be stable for the lifetime of the AuthCore instance.

func NewKeyStoreFromKeys(priv ed25519.PrivateKey, pub ed25519.PublicKey, refreshSecret []byte) (KeyStore, error)

func NewKeyStoreFromPEM(privatePEM, publicPEM, refreshSecret []byte) (KeyStore, error)

type Keys ¶

type Keys interface {
	// PrivateKey returns the Ed25519 private key used for signing tokens.
	// The caller must not modify the returned slice.
	PrivateKey() ed25519.PrivateKey

	// PublicKey returns the Ed25519 public key used for signature verification.
	// The caller must not modify the returned slice.
	PublicKey() ed25519.PublicKey

	// RefreshSecret returns the 32-byte HMAC-SHA256 key used to hash refresh
	// tokens before they are stored in a database.
	// The caller must not modify the returned slice.
	RefreshSecret() []byte

	// KeyID returns the stable identifier for the current signing key.
	// It is derived from the public key and embedded in the "kid" JOSE header
	// of every issued token so that verifiers can select the correct key when
	// multiple keys are in circulation (e.g. during key rotation).
	KeyID() string
}

Keys provides read-only access to authcore's managed cryptographic material.

The concrete implementation is *keymanager.KeyManager (internal). Sub-modules receive Keys through the Provider interface and must not cache or copy the raw key bytes — always call the accessor methods.

type Logger ¶

type Logger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

Logger is the logging interface used throughout authcore. Implement this interface to plug in any logging backend (slog, zap, zerolog, etc.).

type Module ¶

type Module interface {
	// Name returns the unique, lowercase identifier of this module.
	// It must be stable across releases because callers may use it as a key.
	// Examples: "jwt", "apikey", "oauth"
	Name() string
}

Module is the minimal contract every authcore authentication sub-module must implement. It acts as a marker interface today and will grow as shared lifecycle requirements (e.g. Close, HealthCheck) are identified.

Available implementations and their concrete constructors:

auth/jwt      — JSON Web Token authentication (EdDSA / Ed25519)
                  jwt.New[T any](p authcore.Provider, cfg ...jwt.Config) (*jwt.JWT[T], error)
auth/password — Argon2id password hashing
                  password.New(p authcore.Provider, cfg ...password.Config) (*password.Password, error)
auth/email    — email validation, normalization, DNS MX verification
                  email.New(p authcore.Provider) (*email.Email, error)
auth/username — username validation, normalization, reserved name blocklist
                  username.New(p authcore.Provider) (*username.Username, error)
auth/apikey   — opaque API key generation, hashing, and verification
                  apikey.New(p authcore.Provider, cfg ...apikey.Config) (*apikey.APIKey, error)
auth/oauth    — OpenID Connect client (login with Google / Microsoft / OIDC)
                  oauth.New(p authcore.Provider, cfg oauth.Config) (*oauth.Client, error)

Conventions shared by every module:

1. The first argument is always an authcore.Provider (never a concrete *AuthCore).
2. Where a module takes a Config, it is variadic-optional: omit it, or pass a zero-value Config, to apply safe production defaults via applyDefaults. The email and username modules need no Config. Construct any module and use it — none requires cleanup.
3. Constructors return a pointer receiver; concrete types are safe for concurrent use across goroutines after construction completes.

type Provider ¶

type Provider interface {
	// Config returns a copy of the active library configuration.
	Config() Config

	// Logger returns the active logger shared across the library.
	// Modules must use this logger rather than creating their own so that
	// all output flows through a single, user-configured sink.
	Logger() Logger

	// Keys returns the library's managed cryptographic material.
	// Sub-modules must call this to obtain signing keys and the refresh secret.
	Keys() Keys
}

Provider is the narrow interface that *AuthCore satisfies.

Sub-modules must accept a Provider rather than *AuthCore directly. This decouples each module from the concrete library type, which has two important consequences:

1. Testability — unit tests can inject a stub Provider without constructing a real AuthCore or touching the file system / network.

2. Stability — if AuthCore gains new methods in a future release, existing module code is unaffected because it only depends on the methods below.

Guaranteed implementation: *AuthCore.