Security Context

The core package defines the fundamental types shared across all modules: Authentication, Authority, context helpers, and sentinel errors.

Import

import "github.com/thuongh2/go-security/core"

Authentication

Authentication is the central interface representing the security state of a request — either a credential-carrying request token (unauthenticated) or a verified principal token (authenticated).

type Authentication interface {
    Principal() any
    Name() string
    Authorities() []Authority
    Authenticated() bool
    Details() map[string]any
}

Implementations

Type	Usage
`*UsernamePasswordToken`	Created from login form/JSON (unauthenticated request token); also the result token returned by `NewAuthenticatedToken` (authenticated, scrubbed credentials)
`*AnonymousToken`	Injected by the Anonymous middleware for unauthenticated requests

// Build a request token (before authentication)
token := core.NewUsernamePasswordToken("alice", "s3cret")

// Build a result token (after authentication)
result := core.NewAuthenticatedToken("alice", "alice", core.Roles("USER"))

NewAuthenticatedToken(principal any, name string, authorities []Authority) returns a *UsernamePasswordToken with Authenticated() == true — there is no separate AuthenticatedToken type.

Sanitized

func (t *UsernamePasswordToken) Sanitized() *UsernamePasswordToken

Returns a copy with the plaintext password zeroed out. The manager sanitizes tokens before publishing failure events so passwords never appear in audit logs.

Authority

An Authority is a defined string type representing a granted permission. Roles are authorities with the ROLE_ prefix (core.RolePrefix).

type Authority string

func (a Authority) String() string   // the raw value
func (a Authority) IsRole() bool     // true if it carries RolePrefix
func (a Authority) RoleName() string // value with RolePrefix trimmed

Helpers

// Single authority, no prefixing
core.Authority("read:reports")            // → "read:reports"
core.Authorities("read:reports", "write") // → []Authority{"read:reports", "write"}

// Role shorthand — adds ROLE_ prefix automatically (idempotent)
core.RoleAuthority("ADMIN")               // → "ROLE_ADMIN"

// Multiple roles
core.Roles("ADMIN", "USER")               // → ["ROLE_ADMIN", "ROLE_USER"]

// Membership checks
core.HasAuthority(result.Authorities(), core.RoleAuthority("ADMIN"))
core.HasAnyAuthority(result.Authorities(), core.RoleAuthority("ADMIN"), core.RoleAuthority("USER"))

HasRole and HasAnyRole in the authz package auto-prefix with ROLE_, so HasRole("ADMIN") checks for "ROLE_ADMIN".

The current authentication is stored on context.Context. The middleware chain places it there before your handlers execute.

// Place authentication on a context (done by middleware, rarely manual)
ctx = core.WithAuthentication(ctx, auth)

// Read — returns zero value + false if absent
auth, ok := core.AuthenticationFrom(ctx)

// Read — never returns nil; falls back to a fresh AnonymousToken if absent
auth := core.MustAuthentication(ctx)

// Convenience check
if core.IsAuthenticated(ctx) {
    // ctx carries an Authentication whose Authenticated() is true
}

When to use MustAuthentication

MustAuthentication never panics: if no Authentication is on the context it returns a fresh *AnonymousToken (Authenticated() == false), so downstream authorization code can always call methods on the result without a nil check. Use AuthenticationFrom when you need to distinguish “no authentication was ever set” from “set but not authenticated.” Use IsAuthenticated as a shorthand when all you need is the boolean.

Sentinel Errors

All authentication and authorization failures wrap one of these sentinels. Match them with errors.Is:

auth, err := manager.Authenticate(ctx, token)
switch {
case errors.Is(err, core.ErrBadCredentials):
    // Wrong password
case errors.Is(err, core.ErrAccountLocked):
    // Account locked by lockout policy
case errors.Is(err, core.ErrAccountDisabled):
    // Account administratively disabled
}

Sentinel	Meaning
`core.ErrUnauthenticated`	No valid authentication presented
`core.ErrBadCredentials`	Wrong password or invalid token
`core.ErrAccountDisabled`	`User.Disabled == true`
`core.ErrAccountLocked`	`User.Locked == true`
`core.ErrAccountExpired`	`User.AccountExpired == true`
`core.ErrCredentialsExpired`	`User.CredentialsExpired == true`
`core.ErrAccessDenied`	Authenticated but insufficient authorities
`core.ErrProviderNotFound`	No provider supports the token type

Events

core/event defines the Publisher interface for authentication lifecycle hooks. See observe for integration with metrics and audit logs.

import "github.com/thuongh2/go-security/core/event"

type Publisher interface {
    PublishAuthSuccess(ctx context.Context, auth core.Authentication)
    PublishAuthFailure(ctx context.Context, auth core.Authentication, err error)
}

FuncPublisher adapts plain functions — either field can be left nil:

publisher := event.FuncPublisher{
    OnSuccess: func(ctx context.Context, auth core.Authentication) {
        log.Printf("login: user=%s", auth.Name())
    },
    OnFailure: func(ctx context.Context, auth core.Authentication, err error) {
        log.Printf("login failure: user=%s err=%v", auth.Name(), err)
    },
}

NopPublisher discards every event — the safe zero-config default.

Authorization events

AuthzPublisher is the parallel interface for authorization decisions (granted/denied), deliberately kept separate from Publisher so implementing one doesn’t force implementing the other:

type AuthzPublisher interface {
    PublishAuthorizationGranted(ctx context.Context, auth core.Authentication, target any, reason string)
    PublishAuthorizationDenied(ctx context.Context, auth core.Authentication, target any, reason string)
}

FuncAuthzPublisher{OnGranted, OnDenied} and NopAuthzPublisher mirror the authentication-event helpers above.

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Security Context

Import

Authentication

Implementations

Sanitized

Authority

Helpers