security

type AccessDecisionManager ¶

type AccessDecisionManager interface {
	// Decide returns nil on grant, [ErrAccessDenied] on deny.
	// Wrapping callers add a short message indicating the strategy used.
	Decide(ctx context.Context, auth Authentication, attrs []Attribute) error
}

AccessDecisionManager combines the verdicts of multiple [Voter]s into a single decision. Three strategies are provided, mirroring Spring Security:

• Affirmative — a single DecisionGrant grants access; everything else denies. Abstentions are ignored. The strictest "fail closed by default" policy.
• Consensus — the majority wins. Ties default to deny; pass WithTieBreak(DecisionGrant) to flip the policy.
• Unanimous — every voter that does not abstain MUST grant. A single deny refuses; if every voter abstains, the result depends on WithAbstainFallback.

Implementations are safe for concurrent use.

func NewAffirmativeDecisionManager(voters ...Voter) AccessDecisionManager

func NewConsensusDecisionManager(voters []Voter, opts ...admOption) AccessDecisionManager

func NewUnanimousDecisionManager(voters []Voter, opts ...admOption) AccessDecisionManager

type Attribute ¶

type Attribute interface {
	// String returns a stable, log-friendly form of the attribute. It is used
	// by [AccessDecisionManager] for OTel attributes; it MUST NOT include
	// any secret or PII.
	String() string
}

Attribute is an opaque authorization predicate carried alongside a request. Voters opt-in via Voter.Supports and inspect the concrete type through type switches. Four concrete attributes are shipped below; applications can define their own (they just need to implement String()).

func Authority(name string) Attribute

func Permission(name string, predicate func(ctx context.Context, auth Authentication) bool) Attribute

func Role(name string) Attribute

func Scope(name string) Attribute

type Authentication ¶

type Authentication interface {
	// Principal returns the identity carried by this authentication.
	// MUST return [AnonymousPrincipal] for unauthenticated values and
	// MUST NOT return nil.
	Principal() Principal

	// Credentials returns the raw credentials presented by the principal.
	// For a token-based authentication this is typically the token string;
	// for username/password it is the cleartext password. Implementations
	// SHOULD zero or omit secret material once authentication has succeeded
	// to limit accidental leakage through logging or panics.
	//
	// The return type is intentionally any: typed accessors are provided by
	// each scheme module (basic.Password(), bearer.Token(), ...).
	Credentials() any

	// Authorities returns the authorities (roles, scopes, permissions) the
	// system has granted to this principal. The slice is read-only;
	// implementations SHOULD return the same backing slice across calls.
	Authorities() []string

	// IsAuthenticated reports whether the credentials have been validated by
	// an [Authenticator]. Voters use this to short-circuit denials before
	// inspecting authorities.
	IsAuthenticated() bool

	// Name returns a stable, log-friendly identifier for this authentication.
	// It is typically the principal subject; for client_credentials flows it
	// can be the client ID. It MUST be safe to include in structured logs
	// (no secrets, no high-cardinality values that are not the subject).
	Name() string
}

Authentication is an immutable snapshot of a security context: who is acting (the Principal), what proof was presented (the credentials), what authorities the system has granted them, and whether the proof has been verified.

Authentication values flow through three logical stages during a request:

1. An Extractor reads raw credentials from a Carrier and constructs an unauthenticated value (IsAuthenticated() == false).
2. A matching Authenticator validates the credentials and returns a NEW authenticated value (IsAuthenticated() == true). The original value MUST NOT be mutated.
3. Authorisation [Voter]s inspect the value to grant or deny access.

Implementations MUST be safe for concurrent reads. Because every state change goes through a fresh value, no synchronization is required for callers.

func Anonymous() Authentication

func FromContext(ctx context.Context) (Authentication, bool)

type Authenticator ¶

type Authenticator interface {
	Supports(auth Authentication) bool
	Authenticate(ctx context.Context, auth Authentication) (Authentication, error)
}

Authenticator validates an Authentication produced by an Extractor and returns a NEW authenticated value. It MUST NOT mutate its input — the Authentication is treated as immutable everywhere in the core.

Two-step contract:

• Supports reports whether the authenticator recognizes the credential type. Implementations MUST be cheap (a type switch); they MUST NOT perform I/O.
• Authenticate validates the credential and either returns the new, authenticated value or an error wrapping a security sentinel (ErrInvalidCredentials, ErrTokenExpired, ...). Returning (ErrUnsupportedCredential) is the canonical way to bail out at runtime when Supports returned true but the value was nonetheless out of scope.

Implementations MUST be safe for concurrent use.

type AuthenticatorFunc ¶

type AuthenticatorFunc func(ctx context.Context, auth Authentication) (Authentication, error)

AuthenticatorFunc adapts a function to the Authenticator interface. It reports Supports == true for every input; callers wanting selectivity should write a concrete type instead.

func (f AuthenticatorFunc) Authenticate(ctx context.Context, auth Authentication) (Authentication, error)

func (AuthenticatorFunc) Supports(Authentication) bool

type AuthorityAttribute ¶

type AuthorityAttribute string

AuthorityAttribute names a free-form authority string. Unlike RoleAttribute it carries no convention — the configured voter compares the value verbatim against Authentication.Authorities.

func (a AuthorityAttribute) String() string

type Carrier ¶

type Carrier interface {
	// Get returns the first value associated with the given key, or the
	// empty string if absent. Keys are case-insensitive in the HTTP sense.
	Get(key string) string

	// Values returns all values associated with the given key, or a nil
	// slice if absent. The caller MUST NOT mutate the returned slice.
	Values(key string) []string

	// Set replaces all values associated with the given key.
	Set(key, value string)

	// Add appends a value to the list associated with the given key.
	Add(key, value string)
}

Carrier abstracts a transport-level message (an HTTP request, gRPC metadata, a queue envelope) from which credentials can be read and security artifacts (challenges, cookies, headers) can be written.

The interface mimics http.Header semantics so that the HTTP adapter is a thin wrapper. For transports that do not naturally support multi-valued keys (e.g. websocket frames), implementations MAY collapse Values() to a single-element slice and treat Add() as Set().

Implementations MUST be safe for concurrent reads but MAY require external synchronization for writes — adapters are expected to wrap a request scope, which is serial by construction.

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock abstracts time.Now to make time-sensitive code (expiry checks, TTLs, token rotation windows) deterministic in tests. Implementations MUST be safe for concurrent use.

var DefaultClock Clock = SystemClock{}

type Decision ¶

type Decision int

Decision is the verdict returned by a Voter for a given authentication and attribute set. Three values are defined:

• DecisionGrant — the voter explicitly grants access.
• DecisionDeny — the voter explicitly denies access.
• DecisionAbstain — the voter has no opinion (e.g. it does not support any of the attributes presented). The AccessDecisionManager strategy decides what to do when every voter abstains.

const (
	DecisionDeny    Decision = -1
	DecisionAbstain Decision = 0
	DecisionGrant   Decision = 1
)

func (d Decision) String() string

type Engine ¶

type Engine interface {
	// Process runs extractors in order and consults the manager on the first
	// non-empty result. The returned context always carries an Authentication
	// (the anonymous one when nothing was extracted).
	Process(ctx context.Context, c Carrier) (context.Context, Authentication, error)
}

Engine is the high-level entry point: it drives a chain of [Extractor]s against a Carrier, hands the produced Authentication to its Manager, and returns a context enriched with the result so downstream handlers can call FromContext.

Engine is safe for concurrent use.

func NewEngine(m Manager, extractors ...Extractor) Engine

type Extractor ¶

type Extractor interface {
	Extract(ctx context.Context, c Carrier) (Authentication, error)
}

Extractor pulls raw, unauthenticated credentials from a Carrier and returns an Authentication that captures them. The returned value MUST have IsAuthenticated() == false: validation is the Authenticator's job.

Sentinel conventions:

• Return (nil, nil) when no credentials of the supported scheme are present. The Engine treats this as "this extractor does not apply" and consults the next one.
• Return (nil, err) wrapping a security sentinel when credentials were present but malformed (e.g. invalid base64 in Basic). The Engine surfaces err to the caller and stops; downstream authenticators are not invoked.

Implementations MUST be safe for concurrent use.

type Manager ¶

type Manager interface {
	Authenticate(ctx context.Context, auth Authentication) (Authentication, error)
}

Manager orchestrates a chain of [Authenticator]s with first-success-wins semantics:

• Authenticators are consulted in registration order.
• The first authenticator whose Supports() returns true is invoked.
• On success, the resulting Authentication is returned immediately; subsequent authenticators are NOT consulted.
• On error, the next supporting authenticator is tried; if every one fails, the joined error is wrapped in ErrAuthenticatorRefused.
• If no authenticator supports the credential, ErrUnsupportedCredential is returned. The Engine then surfaces it as a 400 in the HTTP adapter.

Manager is safe for concurrent use.

func NewManager(authenticators ...Authenticator) Manager

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/hyperscale-stack/security"
)

// userAuth is an example concrete Authentication produced by a fictional
// authenticator. The point of this example is the Engine wiring, so the type
// is kept minimal.
type userAuth struct {
	sub         string
	roles       []string
	credentials string
	verified    bool
}

func (u userAuth) Principal() security.Principal { return userPrincipal{sub: u.sub} }
func (u userAuth) Credentials() any              { return u.credentials }
func (u userAuth) Authorities() []string         { return u.roles }
func (u userAuth) IsAuthenticated() bool         { return u.verified }
func (u userAuth) Name() string                  { return u.sub }

type userPrincipal struct{ sub string }

func (p userPrincipal) Subject() string { return p.sub }

func main() {
	first := security.AuthenticatorFunc(func(_ context.Context, a security.Authentication) (security.Authentication, error) {
		return a, errors.New("first refuses")
	})
	second := security.AuthenticatorFunc(func(_ context.Context, a security.Authentication) (security.Authentication, error) {
		return userAuth{sub: "bob", verified: true}, nil
	})

	m := security.NewManager(first, second)

	auth, err := m.Authenticate(context.Background(), userAuth{sub: "bob"})
	fmt.Println(auth.Name(), err)
}

Output:
bob <nil>

type NamedAuthenticator ¶

type NamedAuthenticator interface {
	AuthenticatorName() string
}

NamedAuthenticator is an optional capability: when an Authenticator implements it, the Manager records the name in the OTel span so observability backends can attribute decisions per provider.

type PermissionAttribute ¶

type PermissionAttribute struct {
	// Name is the human-readable label of the permission. It populates the
	// OTel attributes; keep it stable across deployments.
	Name string
	// Predicate is invoked by the permission voter with the live
	// authentication. A nil predicate is treated as DecisionDeny.
	Predicate func(ctx context.Context, auth Authentication) bool
}

PermissionAttribute carries an arbitrary predicate evaluated by the permission voter. It is the escape hatch for application-specific authorization (ABAC, ownership checks, time-of-day windows, ...). The predicate MUST be pure (no I/O) and safe for concurrent use.

func (p PermissionAttribute) String() string

type Principal ¶

type Principal interface {
	// Subject returns the stable, unique identifier of the principal. It is
	// the value that authorisation checks key off (`sub` claim, user ID,
	// client ID, ...). Implementations MUST return the same value across
	// calls for the lifetime of a request.
	Subject() string
}

Principal identifies the subject of an Authentication. Implementations represent end users, service clients, devices, or any other authenticatable entity.

The interface is intentionally minimal: any authorisation-specific data (roles, scopes, claims, ...) is carried by Authentication.Authorities or by attaching a concrete implementation via [Authentication.Attribute]. This keeps the core decoupled from any user store schema.

var AnonymousPrincipal Principal = anonymousPrincipal{}

type RoleAttribute ¶

type RoleAttribute string

RoleAttribute names a role expected on the authenticated principal. Roles use the Spring Security "ROLE_" prefix at the wire level (in OTel attributes and in custom Authorities() slices) but the constructor accepts the bare name to keep usage idiomatic.

func (r RoleAttribute) Name() string

func (r RoleAttribute) String() string

type ScopeAttribute ¶

type ScopeAttribute string

ScopeAttribute names an OAuth2 scope expected on the authenticated principal. Scope names follow the RFC 6749 §3.3 grammar but this type stays format-agnostic.

func (s ScopeAttribute) Name() string

func (s ScopeAttribute) String() string

type SecurityError ¶

type SecurityError interface {
	error
	// contains filtered or unexported methods
}

SecurityError is the marker interface implemented by every error returned by this module's public API. Callers SHOULD use errors.Is/errors.As against the sentinel values exported here rather than relying on string matching.

The unexported method securityError() prevents foreign types from accidentally satisfying the interface.

type SystemClock ¶

type SystemClock struct{}

SystemClock is the default Clock returning time.Now().

func (SystemClock) Now() time.Time

type Voter ¶

type Voter interface {
	Supports(attr Attribute) bool
	Vote(ctx context.Context, auth Authentication, attrs []Attribute) Decision
}

Voter is the unit of authorisation logic. It inspects an Authentication against a set of [Attribute]s and returns a Decision. Voters MUST be pure (no I/O) and safe for concurrent use.

Supports is a fast-path filter: a voter that does not recognize any of the passed attributes SHOULD return false to short-circuit the call. When Supports returns false, the AccessDecisionManager records an abstention for the voter without invoking Vote.