Documentation
¶
Overview ¶
Package stepup implements governance R4b — the STEP_UP authorization decision.
Where DENY refuses an action outright and MODIFY rewrites it, a STEP_UP result says "this specific action requires a fresher, higher-assurance authentication than the caller currently has." The runtime aborts the tool call and returns an RFC 9470 challenge:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="step_up_required",
acr_values="<required-acr>"
The caller's SDK / browser is expected to re-authenticate with a method that satisfies the acr requirement (an MFA prompt, a hardware-key ceremony, etc.) and retry the original request. On retry, the auth middleware validates the presented token now carries the required `acr` claim; the runtime admits the call.
Fail-loud: an operator who lists a tool in `security.step_up.tools` but no caller identity has an `acr` claim gets a 401 with the required-acr embedded. This is intentional — the policy is that the tool needs step-up, and the caller not carrying acr is the exact case step-up is designed to catch.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Enabled is a master switch. When false, RequirementFor always
// returns "" and Check is a no-op that returns nil.
Enabled bool
// Tools maps tool name → required acr value. Absent tools have
// no step-up requirement.
Tools map[string]string
// AcrHierarchy is an optional ordered list, lowest-assurance
// first. When present, comparison is "index-of-actual >=
// index-of-required". When empty, comparison is strict-equal.
AcrHierarchy []string
}
Config carries the per-tool step-up requirements.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine evaluates step-up requirements per tool call. Immutable after construction — no locking needed.
func (*Engine) Check ¶
Check evaluates the step-up requirement for the given tool against the caller's identity. Returns nil when either:
- The tool has no step-up requirement.
- The identity presents an acr satisfying the requirement.
Returns a *RequiredError when a step-up is required. The runner unwraps this to produce the RFC 9470 challenge response.
A nil identity is treated as "no acr" — step-up fails closed. The caller MUST authenticate before the runtime evaluates step-up.
func (*Engine) Enabled ¶
Enabled reports whether the engine is armed. Runners short-circuit hook registration on unconfigured deployments.
func (*Engine) KnownAcrValues ¶
KnownAcrValues returns the acrs declared in the hierarchy (or the distinct set from Tools when no hierarchy is set). Used by the startup log so operators can confirm which levels are wired.
func (*Engine) RequirementFor ¶
RequirementFor returns the required acr value for the given tool, or "" when no step-up requirement applies. Callers can use this to skip the identity lookup when the tool doesn't need step-up.
type RequiredError ¶
type RequiredError struct {
Tool string
RequiredAcr string
PresentedAcr string // may be "" when the caller had no acr claim
Reason string
}
RequiredError is the typed error a step-up check returns when the caller's identity doesn't meet the requirement. The runner unpacks it via errors.As to produce the RFC 9470 challenge:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="step_up_required",
acr_values="<RequiredAcr>"
The audit event uses the same fields so the SIEM can join on tool + required_acr.
func AsRequiredError ¶
func AsRequiredError(err error) (*RequiredError, bool)
AsRequiredError is a convenience for callers that want to check whether an error carries step-up semantics without importing the errors package at every call site. Returns (*RequiredError, true) on match or (nil, false) otherwise.
func (*RequiredError) Error ¶
func (e *RequiredError) Error() string
Source Files