auth

Documentation

Overview

Package auth is the batteries-included GOWDK authentication addon. It enables the auth feature and ships a working, dependency-free identity implementation: PBKDF2 password hashing, a PasswordHasher replacement point, and signed-cookie sessions, all on the Go standard library. It builds on the native RBAC guard machinery in runtime/auth. Pages and routes protected with guard role:... or guard permission:... resolve through a session-backed Provider; guard public remains intentionally unauthenticated.

GOWDK still does not own your user store. Look users up however you like, then hand the addon a Principal to issue a session for; the addon owns default hashing helpers, session signing, and request-time principal resolution.

Index

• Constants
• Variables
• func Addon() gowdk.Addon
• func HashPassword(password string) (string, error)
• func HashPasswordWithIterations(password string, iterations int) (string, error)
• func VerifyPassword(password, encoded string) bool
• type Options
• type PBKDF2Hasher
  • func (hasher PBKDF2Hasher) HashPassword(password string) (string, error)
  • func (hasher PBKDF2Hasher) VerifyPassword(password, encoded string) bool
• type PasswordHasher
• type Principal
• type Provider
• type ProviderFunc
• type Sessions
  • func New(options Options) (*Sessions, error)
  • func (sessions *Sessions) Clear(writer http.ResponseWriter)
  • func (sessions *Sessions) ClearCookie() http.Cookie
  • func (sessions *Sessions) Cookie(principal Principal) (http.Cookie, error)
  • func (sessions *Sessions) Issue(writer http.ResponseWriter, principal Principal) error
  • func (sessions *Sessions) Principal(request *http.Request) (*Principal, error)
  • func (sessions *Sessions) Provider() Provider

Constants

const (
	// DefaultIterations is the PBKDF2 iteration count for new password hashes.
	// It is encoded into each hash so stored credentials remain verifiable if
	// this default later increases.
	DefaultIterations = 600000
	// MinIterations is the minimum accepted PBKDF2 iteration count for new and
	// stored hashes. Keep this separate from DefaultIterations so existing
	// stored hashes remain verifiable if the default later increases.
	MinIterations = 600000
)

const (
	// DefaultSessionCookie is the cookie name used for signed sessions.
	DefaultSessionCookie = "gowdk_session"
	// DefaultSessionTTL is how long an issued session remains valid.
	DefaultSessionTTL = 24 * time.Hour
	// DefaultSessionSecretEnv is the recommended runtime environment variable
	// for session signing secrets.
	DefaultSessionSecretEnv = "GOWDK_AUTH_SESSION_SECRET"
	// MinSessionSecretBytes is the minimum accepted session signing secret
	// length.
	MinSessionSecretBytes = 32
)

const ImportPath = "github.com/cssbruno/gowdk/addons/auth"

ImportPath is the canonical Go import path for the auth addon.

Variables

var ErrInvalidHash = errors.New("gowdk auth: invalid password hash")

ErrInvalidHash reports that an encoded password hash is malformed.

var ErrNoSession = errors.New("gowdk auth: no session")

ErrNoSession reports that a request carries no readable session cookie.

Functions

func Addon

func Addon() gowdk.Addon

Addon enables session-backed authentication and native RBAC guards.

func HashPassword

func HashPassword(password string) (string, error)

HashPassword derives a PBKDF2-HMAC-SHA256 hash of password using a fresh random salt and the default iteration count. The returned value is self-describing and safe to store: pbkdf2-sha256$<iter>$<b64salt>$<b64hash>.

func HashPasswordWithIterations

func HashPasswordWithIterations(password string, iterations int) (string, error)

HashPasswordWithIterations is HashPassword with an explicit work factor.

func VerifyPassword

func VerifyPassword(password, encoded string) bool

VerifyPassword reports whether password matches encoded. Comparison is constant-time. A malformed encoding returns false rather than an error so callers cannot distinguish "wrong password" from "corrupt record" by timing or control flow.

Types

type Options

type Options struct {
	// Secret signs session payloads with HMAC-SHA256. It must be non-empty and
	// should be high-entropy and stable across instances.
	Secret []byte
	// SecretEnv names the environment variable to read instead of Secret. Error
	// messages include this name, never the secret value.
	SecretEnv string
	// CookieName overrides DefaultSessionCookie.
	CookieName string
	// TTL overrides DefaultSessionTTL.
	TTL time.Duration
	// Insecure drops the Secure cookie flag for local HTTP development. Leave
	// false in production so the cookie is only sent over HTTPS.
	Insecure bool
	// Now overrides the clock, for tests.
	Now func() time.Time
}

Options configures a Sessions manager. Secret or SecretEnv is required; everything else has a working default.

type PBKDF2Hasher

type PBKDF2Hasher struct {
	Iterations int
}

PBKDF2Hasher is the default dependency-free password hasher used by this addon. Iterations defaults to DefaultIterations when omitted.

func (PBKDF2Hasher) HashPassword

func (hasher PBKDF2Hasher) HashPassword(password string) (string, error)

HashPassword derives a PBKDF2-HMAC-SHA256 hash of password using a fresh random salt.

func (PBKDF2Hasher) VerifyPassword

func (hasher PBKDF2Hasher) VerifyPassword(password, encoded string) bool

VerifyPassword reports whether password matches encoded.

type PasswordHasher

type PasswordHasher interface {
	HashPassword(password string) (string, error)
	VerifyPassword(password, encoded string) bool
}

PasswordHasher hashes and verifies stored password credentials.

type Principal

type Principal = auth.Principal

Principal is the application identity visible to native RBAC guards. It is re-exported from runtime/auth so callers of this addon need only one import.

type Provider

type Provider = auth.Provider

Provider resolves the current principal for a request. Register the value returned by Sessions.Provider with the generated RegisterAuthProvider hook.

type ProviderFunc

type ProviderFunc = auth.ProviderFunc

ProviderFunc adapts a function into a Provider.

type Sessions

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

Sessions issues and reads signed-cookie sessions and resolves the current Principal for a request. The zero value is not usable; construct one with New. Sessions implements Provider.

func New

func New(options Options) (*Sessions, error)

New creates a Sessions manager. It returns an error when no secret is set.

func (*Sessions) Clear

func (sessions *Sessions) Clear(writer http.ResponseWriter)

Clear writes an immediately-expired session cookie, logging the request out.

func (*Sessions) ClearCookie

func (sessions *Sessions) ClearCookie() http.Cookie

ClearCookie creates an immediately-expired session cookie.

func (*Sessions) Cookie

func (sessions *Sessions) Cookie(principal Principal) (http.Cookie, error)

Cookie creates a signed session cookie for principal.

func (*Sessions) Issue

func (sessions *Sessions) Issue(writer http.ResponseWriter, principal Principal) error

Issue writes a signed session cookie for principal to the response.

func (*Sessions) Principal

func (sessions *Sessions) Principal(request *http.Request) (*Principal, error)

Principal resolves the current principal from the request's session cookie. A request with no cookie, or a tampered or expired one, yields a nil principal and no error, meaning unauthenticated.

func (*Sessions) Provider

func (sessions *Sessions) Provider() Provider

Provider returns sessions typed as a Provider for registration with the generated RegisterAuthProvider hook.