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 and signed-cookie sessions, all on the Go standard library. It builds on the native RBAC guard machinery in runtime/auth, so pages and routes protected with guard role:... / guard permission:... / guard public resolve through a session-backed Provider.

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 hashing, 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 Principal
• type Provider
• type ProviderFunc
• type Sessions
  • func New(options Options) (*Sessions, error)
  • func (sessions *Sessions) Clear(writer http.ResponseWriter)
  • 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 (
	// 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
)

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
)

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
	// 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 is required; everything else has a working default.

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) 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.