contract

type AccessDecisionManager ¶

type AccessDecisionManager interface {
	DecideAll(token Token, attributes []string, subject any) error

	DecideAny(token Token, attributes []string, subject any) error
}

type AccessDeniedHandler ¶

type AccessDeniedHandler interface {
	Handle(runtimeInstance runtimecontract.Runtime, request httpcontract.Request, decisionErr error) (httpcontract.Response, error)
}

type Actor ¶ added in v3.9.0

type Actor interface {
	Identifier() string

	/* Type reports the kind of originating actor; one of ActorTypeUser, ActorTypeApiClient or ActorTypeSystem. */
	Type() string

	Roles() []string

	Attributes() map[string]string
}

Actor is the originating principal that started an action upstream (for example the human user or client that called service A), distinct from the authenticated transport principal that is carrying the request now (service B). It is optional context attached to a Token through the ActorAware interface; an absent actor means the token behaves exactly as before.

type ActorAware ¶ added in v3.9.0

type ActorAware interface {
	OnBehalfOf() (Actor, bool)
}

ActorAware is implemented by tokens that can carry an originating actor. Consumers (voters, audit) type-assert a Token to ActorAware rather than the core Token interface being widened, so existing Token implementations keep compiling.

type ActorData ¶ added in v3.9.0

type ActorData struct {
	Identifier   string            `json:"Identifier"`
	Type         string            `json:"Type"`
	Roles        []string          `json:"Roles,omitempty"`
	Attributes   map[string]string `json:"Attributes,omitempty"`
	Impersonator *ActorData        `json:"Impersonator,omitempty"`
}

ActorData is the serializable carrier for an originating actor inside Claims. The Actor interface itself does not round-trip through JSON, so transports (JWT claims, the HMAC envelope) encode this struct and it is rebuilt into a concrete Actor when a token is constructed. Impersonator, when set, is the admin acting behind this actor, so an impersonation's accountable principal and its roles propagate across services.

type ActorImpersonating ¶ added in v3.9.0

type ActorImpersonating interface {
	Impersonator() (Actor, bool)
}

ActorImpersonating is implemented by an Actor an impersonator is acting behind. Consumers type-assert it (rather than widening Actor) to read the accountable impersonator a propagated originating actor carries, so an impersonation started in one service stays auditable in the next.

type Authenticator ¶

type Authenticator interface {
	Supports(request httpcontract.Request) bool

	Authenticate(request httpcontract.Request) (Token, error)
}

type Claims ¶ added in v3.7.0

type Claims struct {
	UserIdentifier string   `json:"UserIdentifier"`
	Roles          []string `json:"Roles"`

	Scope map[string]any `json:"Scope,omitempty"`

	Attributes map[string]any `json:"Attributes,omitempty"`

	OriginatingActor *ActorData `json:"OriginatingActor,omitempty"`
}

type DecisionStrategy ¶

type DecisionStrategy int

const (
	DecisionStrategyAffirmative DecisionStrategy = iota
	DecisionStrategyConsensus
	DecisionStrategyUnanimous
)

type EntryPoint ¶

type EntryPoint interface {
	Start(runtimeInstance runtimecontract.Runtime, request httpcontract.Request) (httpcontract.Response, error)
}

type Firewall ¶

type Firewall interface {
	Name() string

	LoginPath() string

	LogoutPath() string

	Login(
		runtimeInstance runtimecontract.Runtime,
		request httpcontract.Request,
		input LoginInput,
	) (*LoginResult, error)

	Logout(
		runtimeInstance runtimecontract.Runtime,
		request httpcontract.Request,
		input LogoutInput,
	) (*LogoutResult, error)
}

type FirewallManager ¶

type FirewallManager interface {
	Firewall(name string) (Firewall, error)
}

type ImpersonatedUserResolver ¶ added in v3.9.0

type ImpersonatedUserResolver interface {
	ResolveImpersonatedUser(runtimeInstance runtimecontract.Runtime, identifier string) (Token, error)
}

ImpersonatedUserResolver resolves the token of the user an admin is switching to. It is supplied by the application because only the application knows its user store. Returning a nil or unauthenticated token (or an error) denies the switch, and the admin's own token is used unchanged.

type Impersonating ¶ added in v3.9.0

type Impersonating interface {
	Impersonator() (Token, bool)
}

Impersonating is implemented by a token whose visible principal is an impersonated user while a different principal (the admin who initiated the switch) is actually authenticated. Consumers type-assert it to read who is acting behind the impersonated identity, so both identities can be audited. As with ActorAware, the core Token interface is not widened.

type LoginHandler ¶

type LoginHandler interface {
	Login(runtimeInstance runtimecontract.Runtime, request httpcontract.Request, input LoginInput) (*LoginResult, error)
}

type LoginInput ¶

type LoginInput struct {
	Token Token
}

type LoginResult ¶

type LoginResult struct {
	Token    Token
	Response httpcontract.Response
}

type LogoutHandler ¶

type LogoutHandler interface {
	Logout(runtimeInstance runtimecontract.Runtime, request httpcontract.Request, input LogoutInput) (*LogoutResult, error)
}

type LogoutInput ¶

type LogoutInput struct{}

type LogoutResult ¶

type LogoutResult struct {
	Response httpcontract.Response
}

type Matcher ¶

type Matcher interface {
	Matches(request httpcontract.Request) bool
}

type NonceGuard ¶ added in v3.9.0

type NonceGuard interface {
	Remember(runtimeInstance runtimecontract.Runtime, nonce string, ttl time.Duration) (bool, error)
}

NonceGuard provides replay protection for single-use values (the nonce carried by the internal-auth envelope). Remember atomically records a nonce for the given time-to-live and reports whether it had already been recorded and not yet expired; a true result means the nonce is a replay and the request must be rejected. Implementations are expected to be safe for concurrent use and, in a multi-instance deployment, to share state (for example through Redis).

type RevocableTokenStore ¶ added in v3.7.0

type RevocableTokenStore interface {
	TokenStore
	Put(tokenString string, claims Claims)
	PutWithTtl(tokenString string, claims Claims, ttl time.Duration)
	Delete(tokenString string)
	DeleteByUser(userIdentifier string) int
	PurgeExpired() int
}

type Rule ¶

type Rule interface {
	Applies(request httpcontract.Request) bool

	Check(request httpcontract.Request) error
}

type Token ¶

type Token interface {
	IsAuthenticated() bool

	UserIdentifier() string

	Roles() []string

	Scope() map[string]any

	Attributes() map[string]any
}

type TokenEnricher ¶ added in v3.7.0

type TokenEnricher interface {
	Enrich(runtimeInstance runtimecontract.Runtime, claims Claims) (Claims, error)
}

type TokenResolver ¶

type TokenResolver func(request httpcontract.Request) Token

type TokenSource ¶

type TokenSource interface {
	Name() string

	Resolve(runtimeInstance runtimecontract.Runtime, request httpcontract.Request) (Token, error)
}

type TokenStore ¶ added in v3.7.0

type TokenStore interface {
	Lookup(runtimeInstance runtimecontract.Runtime, tokenString string) (Claims, bool, error)
}

type TokenValidator ¶ added in v3.7.0

type TokenValidator interface {
	Validate(runtimeInstance runtimecontract.Runtime, tokenString string) (Claims, error)
}

type TwoFactorEnrollmentStore ¶ added in v3.9.0

type TwoFactorEnrollmentStore interface {
	FindTotpSecret(runtimeInstance runtimecontract.Runtime, userIdentifier string) (secret string, enrolled bool, err error)
}

TwoFactorEnrollmentStore reports whether a user has a second factor configured and, if so, returns the TOTP secret to verify against. It is supplied by the application because only the application knows where enrollments live (typically an encrypted column). Returning enrolled=false means the user has no second factor and primary authentication stands on its own.

type TwoFactorPending ¶ added in v3.9.0

type TwoFactorPending interface {
	PendingUserIdentifier() string
}

TwoFactorPending is implemented by the token returned when a primary credential has been accepted but a required second factor (a TOTP code) has not yet been supplied or did not verify. The token is deliberately not authenticated; the application inspects this interface to know it should prompt for a code rather than treating the request as anonymous.

type TwoFactorRecoveryStore ¶ added in v3.9.0

type TwoFactorRecoveryStore interface {
	RedeemRecoveryCode(runtimeInstance runtimecontract.Runtime, userIdentifier string, code string) (redeemed bool, err error)
}

TwoFactorRecoveryStore is an optional companion to TwoFactorEnrollmentStore: when the enrollment store also implements it, TotpSecondFactorAuthenticator accepts a single-use recovery code (on its recovery header) as an alternative to a TOTP code. RedeemRecoveryCode must atomically verify the code is one of the user's currently-unused recovery codes and consume it — remove it so a second presentation of the same code cannot succeed — returning redeemed=true only when a previously-unused code was consumed. A store that does not implement this interface simply makes recovery codes unavailable; TOTP verification is unaffected. The atomic check-and-consume (a transaction or a conditional update) is the store's responsibility, mirroring how FindTotpSecret owns enrollment storage.

type VoteResult ¶

type VoteResult int

const (
	VoteAbstain VoteResult = iota
	VoteDenied
	VoteGranted
)

type Voter ¶

type Voter interface {
	Supports(attribute string, subject any) bool

	Vote(token Token, attribute string, subject any) VoteResult
}