Documentation
¶
Overview ¶
Package writpolicy evaluates supplied user and host facts against a compiled Writ policy, with registries of requirement handlers, flag sources, and notify targets.
The registries are the plugin seam. A name in policy text (`require oncall`, `when freeze`, `notify "security-alerts"`) is a configured instance bound to that name here; policy referencing an unregistered name fails at load, never at request time. The initial registry is empty — the subprocess plugin mechanism that will populate it is future work, but the contract is fixed now.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator evaluates supplied facts against a compiled writ policy. The policy is immutable after construction — reload is a process restart.
func New ¶
New builds an evaluator, validating every require/when/notify reference against the registry (unknown names fail here, at startup) and collecting non-blocking warnings: an allow whose `until` is already past matches nothing, which is safe, so it warns rather than bricking a restart.
func (*Evaluator) Evaluate ¶
func (e *Evaluator) Evaluate(ctx context.Context, conn wire.Connection, facts *wire.PolicyFacts) (*wire.PolicyResponse, error)
Evaluate decides certificate access and parameters using supplied facts. Policy denials return 403; pending requirements return 202.
type FactRequest ¶
type FactRequest struct {
Requirement string
User eval.User
Host eval.Host
Account string
Connection wire.Connection
RuleLabel string
}
FactRequest is the context a requirement handler judges.
type FactResult ¶
type FactResult struct {
Status FactStatus
Message string
RetryAfter time.Duration
Expires time.Time
}
FactResult is one requirement check's outcome. Message surfaces in 202 responses ("waiting on approval: https://..."); RetryAfter hints the client's next poll; Expires bounds how long a settled answer may be cached.
type FactStatus ¶
type FactStatus int
FactStatus is a requirement handler's three-state answer.
const ( Satisfied FactStatus = iota Unsatisfied Pending )
type FlagSource ¶
FlagSource answers `when` flags: synchronous, two-state, never pending.
type Latency ¶
type Latency int
Latency is a requirement handler's declared latency class. Fast handlers resolve inline; Human handlers (an approval, a page) are triggered only when they are the last thing between the user and a cert.
type Notifier ¶
type Notifier interface {
Events() []string
Notify(ctx context.Context, ev NotifyEvent)
}
Notifier is one registered notify target. Events is the target's registered `on` set; Notify must never gate the decision.
type NotifyEvent ¶
type NotifyEvent struct {
Event string
Identity string
Account string
Host string
Connection wire.Connection
RuleLabel string
}
NotifyEvent is a fire-and-forget notification. Event is "issued" or "denied"; RuleLabel names the rule that fired (label, or short content id when unlabeled).
type Options ¶
type Options struct {
// DefaultTTL is the cert expiration when no satisfied rule sets a
// ttl. Zero falls back to defaultExpiration().
DefaultTTL time.Duration
// Extensions go into every issued cert. Nil falls back to
// defaultExtensions().
Extensions map[string]string
// Clock is the evaluation time source; nil means time.Now.
Clock func() time.Time
}
Options carries the deployment-level certificate parameters. Writ controls TTL only; extensions are deployment config by design.
type Registry ¶
type Registry struct {
Requirements map[string]RequirementHandler
Flags map[string]FlagSource
Notifiers map[string]Notifier
}
Registry binds the names policy text may reference to their configured instances.
func (*Registry) ValidateReferences ¶
ValidateReferences checks every require/when/notify name in pol against the registry (SPEC §7 apply-time error 14). All unknown names are reported at once, each naming the rule that uses it, so an operator fixes the whole policy in one pass.
type RequirementHandler ¶
type RequirementHandler interface {
Latency() Latency
SideEffects() bool
Check(ctx context.Context, req FactRequest) (FactResult, error)
}
RequirementHandler resolves one named `require` fact. The future subprocess implementation (JSON over stdin/stdout, one exec per check) implements this interface; latency class and side-effect-ness are declared at registration, never in the policy grammar.
Source Files