Documentation
¶
Overview ¶
Package auth provides password hashing with Argon2id and cryptographically-secure token generation.
Index ¶
- Variables
- func CheckPassword(password, encodedHash string) (bool, error)
- func GenerateToken() (string, error)
- func GenerateTokenN(n int) (string, error)
- func HashPassword(password string) (string, error)
- func HashPasswordWithConfig(password string, cfg HashConfig) (string, error)
- func NeedsRehash(encodedHash string) (bool, error)
- func SessionMetadata[T any](s *Session) (T, error)
- type HashConfig
- type Session
- type SessionManager
- func (m *SessionManager) CookieDomain() string
- func (m *SessionManager) CookieName() string
- func (m *SessionManager) CookiePath() string
- func (m *SessionManager) CookieSecure() bool
- func (m *SessionManager) CreateSession(ctx context.Context, subjectID string, metadata any) (*Session, error)
- func (m *SessionManager) DeleteSession(ctx context.Context, id string) error
- func (m *SessionManager) DeleteSubjectSessions(ctx context.Context, subjectID string) error
- func (m *SessionManager) Duration() time.Duration
- func (m *SessionManager) SameSite() http.SameSite
- func (m *SessionManager) ValidateSession(ctx context.Context, token string) (*Session, error)
- type SessionOption
- func WithCookieDomain(domain string) SessionOption
- func WithCookieName(name string) SessionOption
- func WithCookiePath(path string) SessionOption
- func WithCookieSecure(secure bool) SessionOption
- func WithDuration(d time.Duration) SessionOption
- func WithSameSite(ss http.SameSite) SessionOption
- func WithSlidingRefresh(threshold time.Duration) SessionOption
- type SessionStore
- type SessionToucher
Constants ¶
This section is empty.
Variables ¶
var DefaultHashConfig = HashConfig{
Time: 3,
Memory: 64 * 1024,
Parallelism: 2,
KeyLength: 32,
SaltLength: 16,
}
DefaultHashConfig is a sensible default for production use.
Functions ¶
func CheckPassword ¶
CheckPassword verifies password against an Argon2id PHC-format encoded hash. It returns (true, nil) on match, (false, nil) on mismatch, or an error if the encoded hash cannot be parsed.
func GenerateToken ¶
GenerateToken returns a 32-byte cryptographically-secure random token encoded with base64 raw-URL encoding.
func GenerateTokenN ¶
GenerateTokenN returns an n-byte cryptographically-secure random token encoded with base64 raw-URL encoding.
func HashPassword ¶
HashPassword hashes password using DefaultHashConfig.
func HashPasswordWithConfig ¶
func HashPasswordWithConfig(password string, cfg HashConfig) (string, error)
HashPasswordWithConfig hashes password with the given Argon2id parameters and returns a PHC-format encoded string.
func NeedsRehash ¶
NeedsRehash reports whether the encoded hash was created with parameters that differ from DefaultHashConfig. When true the caller should re-hash the password and update the stored hash. Returns an error if the encoded string cannot be parsed.
func SessionMetadata ¶
SessionMetadata extracts session metadata into the target type T. It handles both in-memory stores (direct type assertion) and database stores (json.RawMessage unmarshal) transparently.
Types ¶
type HashConfig ¶
type HashConfig struct {
Time uint32
Memory uint32
Parallelism uint8
KeyLength uint32
SaltLength uint32
}
HashConfig holds the tuneable parameters for Argon2id hashing.
type Session ¶
type Session struct {
ID string
SubjectID string
Token string
ExpiresAt time.Time
CreatedAt time.Time
// contains filtered or unexported fields
}
Session represents a user session.
func (*Session) RawMetadata ¶
RawMetadata returns the raw metadata value without type conversion.
func (*Session) SetMetadata ¶
SetMetadata sets the session metadata. This is intended for use by SessionStore implementations when populating a Session from the database.
type SessionManager ¶
type SessionManager struct {
// contains filtered or unexported fields
}
SessionManager manages session lifecycle on top of a SessionStore.
func NewSessionManager ¶
func NewSessionManager(store SessionStore, opts ...SessionOption) *SessionManager
NewSessionManager returns a SessionManager with sensible defaults.
func (*SessionManager) CookieDomain ¶
func (m *SessionManager) CookieDomain() string
CookieDomain returns the configured Domain attribute.
func (*SessionManager) CookieName ¶
func (m *SessionManager) CookieName() string
CookieName returns the configured cookie name.
func (*SessionManager) CookiePath ¶
func (m *SessionManager) CookiePath() string
CookiePath returns the configured cookie path.
func (*SessionManager) CookieSecure ¶
func (m *SessionManager) CookieSecure() bool
CookieSecure returns the configured Secure flag.
func (*SessionManager) CreateSession ¶
func (m *SessionManager) CreateSession(ctx context.Context, subjectID string, metadata any) (*Session, error)
CreateSession creates a new session for the given subject.
func (*SessionManager) DeleteSession ¶
func (m *SessionManager) DeleteSession(ctx context.Context, id string) error
DeleteSession removes a session by ID.
func (*SessionManager) DeleteSubjectSessions ¶
func (m *SessionManager) DeleteSubjectSessions(ctx context.Context, subjectID string) error
DeleteSubjectSessions removes all sessions for a subject.
func (*SessionManager) Duration ¶
func (m *SessionManager) Duration() time.Duration
Duration returns the configured session duration.
func (*SessionManager) SameSite ¶
func (m *SessionManager) SameSite() http.SameSite
SameSite returns the configured SameSite attribute.
func (*SessionManager) ValidateSession ¶
ValidateSession looks up a session by token and checks its expiry. Expired sessions are deleted. Returns (nil, nil) for expired or not-found.
type SessionOption ¶
type SessionOption func(*SessionManager)
SessionOption configures a SessionManager.
func WithCookieDomain ¶
func WithCookieDomain(domain string) SessionOption
WithCookieDomain sets the Domain attribute on the session cookie. Empty (default) scopes the cookie to the exact host.
func WithCookieName ¶
func WithCookieName(name string) SessionOption
WithCookieName sets the session cookie name.
func WithCookiePath ¶
func WithCookiePath(path string) SessionOption
WithCookiePath sets the session cookie path.
func WithCookieSecure ¶
func WithCookieSecure(secure bool) SessionOption
WithCookieSecure sets the Secure flag on the session cookie.
func WithDuration ¶
func WithDuration(d time.Duration) SessionOption
WithDuration sets the session lifetime.
func WithSameSite ¶
func WithSameSite(ss http.SameSite) SessionOption
WithSameSite sets the SameSite attribute on the session cookie.
func WithSlidingRefresh ¶
func WithSlidingRefresh(threshold time.Duration) SessionOption
WithSlidingRefresh sets the threshold after which a validated session's expiry is automatically extended. When the session age exceeds threshold, the store is type-asserted to SessionToucher and, if implemented, Touch is called to push the expiry forward by the configured duration.
type SessionStore ¶
type SessionStore interface {
Create(ctx context.Context, s *Session) error
GetByToken(ctx context.Context, token string) (*Session, error)
Delete(ctx context.Context, id string) error
DeleteBySubjectID(ctx context.Context, subjectID string) error
}
SessionStore is the persistence interface for sessions. GetByToken returns (nil, nil) when the token is not found.
Source Files