guard

package

v0.1.0 Latest Latest Go to latest Published: Oct 12, 2026 License: MIT Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/plexusone/keyforge

Links

Open Source Insights

Documentation ¶

Overview ¶

Package guard defines the veto a host application holds over retiring and destroying keys.

Destroying a key is irreversible, and whether it is safe depends on things keyforge cannot see: a legal hold, a retention duty, an export or snapshot in the inline mode that no registry record points at, a backup that must stay restorable. The host knows. A Guard is how it says so.

A guard is consulted before a version is retired and again before it is destroyed. It may allow, deny with a reason, or answer that an approval is still outstanding. Only an allow advances the state; anything else leaves the key usable.

Index ¶

Constants
Variables
type Action
type Decision
type Func
- func (f Func) Check(ctx context.Context, req Request) (Decision, error)
type Guard
type Outcome
- func (o Outcome) String() string
type Request

Constants ¶

View Source

const ErrNoGuard = "no destroy guard is configured"

ErrNoGuard is the reason recorded when no guard is configured. With none, nothing is retired or destroyed: the absence of a veto is not consent.

Variables ¶

View Source

var ErrBadDecision = errors.New("guard: not a valid decision")

ErrBadDecision is returned when a guard answers with an outcome that is not one of the three.

Functions ¶

This section is empty.

Types ¶

type Action ¶

type Action string

Action is what is being asked.

const (
	// Retire asks to move a version from retire-requested to retired.
	Retire Action = "retire"
	// Destroy asks to destroy a retired version's material at the provider.
	Destroy Action = "destroy"
)

Actions.

type Decision ¶

type Decision struct {
	Outcome Outcome
	// Reason is recorded in the audit trail. It must not name key material.
	Reason string
}

Decision is a guard's answer and why.

func Allow ¶

func Allow() Decision

Allow returns a decision that lets the action proceed.

func AwaitApproval ¶

func AwaitApproval(reason string) Decision

AwaitApproval returns a decision that says an approval is outstanding.

func Deny ¶

func Deny(reason string) Decision

Deny returns a decision that refuses with a reason.

type Func ¶

type Func func(ctx context.Context, req Request) (Decision, error)

Func adapts a function to a Guard.

func (Func) Check ¶

func (f Func) Check(ctx context.Context, req Request) (Decision, error)

Check implements Guard.

type Guard ¶

type Guard interface {
	Check(ctx context.Context, req Request) (Decision, error)
}

Guard decides whether a retirement or destruction may proceed.

An error is not an answer: a guard that cannot decide returns it, and the action does not proceed.

func All ¶

func All(guards ...Guard) Guard

All combines guards: every one is consulted, a denial from any refuses, and otherwise a pending answer from any is pending; the action proceeds only if all allow. An error from any guard is an error. With no guards it denies.

func AllowAll ¶

func AllowAll() Guard

AllowAll returns a guard that allows everything. Use it only where nothing is held: it is the absence of a veto.

func DenyAll ¶

func DenyAll(reason string) Guard

DenyAll returns a guard that refuses everything with a reason.

type Outcome ¶

type Outcome uint8

Outcome is a guard's answer.

const (
	// Allowed lets the action proceed.
	Allowed Outcome = iota + 1
	// Denied refuses the action. The key stays usable.
	Denied
	// Pending says an approval is outstanding. The key stays usable and the
	// guard is asked again later.
	Pending
)

func (Outcome) String ¶

func (o Outcome) String() string

String returns the outcome's name.

type Request ¶

type Request struct {
	Action  Action
	Purpose keyforge.Purpose
	KEKID   envelope.ID
	Version uint32
	// DEKID names the data key when the request is about one, in place of a
	// KEK version.
	DEKID envelope.ID
	// Actor is who asked, as the host named them, if anyone.
	Actor string
	// References is how many data keys in the registry are still wrapped under
	// the version. It is zero when retirement completes; it says nothing about
	// data outside the registry, which only the host knows about.
	References int
	// Emergency is true during an emergency rotation. The guard is consulted and
	// its answer is recorded, but it cannot block the procedure.
	Emergency bool
}

Request describes what the guard is asked to decide.

Source Files ¶

View all Source files

guard.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL