guard

package
v1.234.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package guard supplies dependency-free pre-I/O hooks to configuration loaders. The policy admission adapter installs the evaluator; collectors never import CI.

Index

Constants

View Source
const OperationTemplateDatasource = "template.datasource"

OperationTemplateDatasource names a source read through a template datasource.

Variables

This section is empty.

Functions

func ActiveProfiles

func ActiveProfiles() []string

ActiveProfiles returns a copy of the recorded profile names; it is never nil.

func Authenticate

func Authenticate(ctx context.Context, input AuthInput) error

Authenticate checks the complete chain before credential acquisition or cache access.

func CanonicalFunction

func CanonicalFunction(name string) string

CanonicalFunction returns the name a policy rule sees for a YAML function.

func Enabled

func Enabled(kind string) (bool, error)

Enabled reports whether this invocation has rules for a capability.

func Function

func Function(ctx context.Context, name, engine string, origin Origin) error

Function gates the actual handler invocation.

func FunctionAt

func FunctionAt(ctx context.Context, name, file string) error

FunctionAt checks a YAML function with its parser-provided source file. It lives in guard rather than admission so that low-level packages such as pkg/utils can admit functions without importing the CI reporting that admission pulls in, which would form an import cycle.

func FunctionValue

func FunctionValue(ctx context.Context, name, value string) error

FunctionValue checks lazy YAML functions using conservative parse-time attribution.

func IsPolicyError

func IsPolicyError(err error) bool

IsPolicyError identifies failures which optional imports must never suppress.

func Plugin

func Plugin(ctx context.Context, input *PluginInput) error

Plugin admits a plugin operation through the same evaluator as other capabilities.

func RegisterRemote

func RegisterRemote(path, source string)

RegisterRemote associates cached files/directories with their remote origin.

func RememberNode

func RememberNode(node *yaml.Node, origin Origin)

RememberNode retains attribution for every scalar of a spliced YAML document before its next evaluation pass. Spliced includes keep their tags instead of decoding to Go values, so their function arguments need the same origin RememberTree records for decoded includes.

func RememberTree

func RememberTree(value any, origin Origin)

RememberTree retains attribution for included scalar values before their next evaluation pass.

func RememberValue

func RememberValue(value string, origin Origin)

RememberValue conservatively retains remote attribution through merges and lazy evaluation. Identical values from multiple sources take the more restrictive provenance.

func ResetOrigins

func ResetOrigins()

ResetOrigins isolates source attribution between CLI invocations.

func SaveHooks

func SaveHooks() func()

SaveHooks captures the installed capability lookup and evaluator and returns a function that reinstalls them. Tests that replace the hooks with fakes use it to restore the wiring they found.

func SetActiveProfiles

func SetActiveProfiles(names []string)

SetActiveProfiles records the profiles the loaded configuration applied, for plugin policy input. Blank names are dropped and duplicates keep their first position. Passing nil clears the list.

func SetEnabled

func SetEnabled(enabled func(string) (bool, error))

SetEnabled installs the capability lookup used to preserve unconfigured behavior.

func SetEvaluator

func SetEvaluator(evaluate func(context.Context, string, json.RawMessage) error)

SetEvaluator connects collectors to admission without introducing dependency cycles.

func Source

func Source(ctx context.Context, operation, raw, sourceFile string) error

Source checks a destination before credentials, cache reuse, or I/O.

Types

type AuthInput

type AuthInput struct {
	Identity   string   `json:"identity"`
	Provider   string   `json:"provider"`
	Identities []string `json:"identities"`
}

AuthInput identifies the resolved credential chain without exposing credentials.

type FunctionInput

type FunctionInput struct {
	Name   string `json:"name"`
	Engine string `json:"engine"`
	Origin
}

FunctionInput identifies a YAML or template function without its secret arguments.

type Origin

type Origin struct {
	Provenance string `json:"provenance"`
	SourceFile string `json:"source_file"`
}

Origin records execution provenance, independently of the optional display provenance.

func FileOrigin

func FileOrigin(file string) Origin

FileOrigin never infers that an unattributed value was authored locally.

func ValueOrigin

func ValueOrigin(value string) Origin

ValueOrigin retrieves attribution retained while parsing, or reports unknown.

type PluginInput

type PluginInput struct {
	Operation    string   `json:"operation"`
	Phase        string   `json:"phase"`
	Origin       string   `json:"origin"`
	Source       string   `json:"source"`
	Registry     string   `json:"registry"`
	Repository   string   `json:"repository"`
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Digest       string   `json:"digest"`
	Runtime      string   `json:"runtime"`
	Capabilities []string `json:"capabilities"`
	Development  bool     `json:"development"`
	// Path is the plugin directory of a local build (origin development): a forward-slash path
	// relative to the project directory when it lies inside it, otherwise absolute. It never contains
	// `..`, so a relative allow-root cannot match a directory outside the project. Empty for every
	// other origin and for a build whose directory is unknown.
	Path string `json:"path"`
	// Profiles lists the active profile names exactly as typed, without duplicates, in activation
	// order; it is an empty list when none is active. Names are chosen by the developer and a rule
	// keyed on one can be avoided by renaming the profile, so gate trust on origin and path instead.
	Profiles []string `json:"profiles"`
}

PluginInput contains non-secret plugin provenance and statically inspected metadata. Source checks precede remote access; package checks precede installation or activation. Empty metadata in the source phase is unknown, never an assertion of compatibility.

type SourceInput

type SourceInput struct {
	Operation    string `json:"operation"`
	Scheme       string `json:"scheme"`
	Host         string `json:"host"`
	Path         string `json:"path"`
	Remote       bool   `json:"remote"`
	PathResolved bool   `json:"path_resolved"`
	Origin
}

SourceInput describes the actual destination immediately before a read or download.

func DescribeSource

func DescribeSource(operation, raw, sourceFile string) (SourceInput, error)

DescribeSource normalizes transport syntax without fetching or exposing credentials.

Jump to

Keyboard shortcuts

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