managedsettings

package
v0.7.9 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package managedsettings is the format of a managed settings document: the values an organization's admins set for its members' Agentry clients. The registry signs one document per organization and version as a DSSE envelope with its release-signing key, and serves it to each active member. A client opens it only with a key it already trusts for that registry, and only for the organization it is a member of.

A setting is either locked, which the member cannot change, or a default, which applies until the member chooses otherwise. Every setting is a row of the catalogue below, and a row's values only ever narrow what a member could choose for themselves: a document can forbid something, and it can never switch on something the member has not.

Index

Constants

View Source
const (
	UnsafeModeAllowed   = "allowed"
	UnsafeModeForbidden = "forbidden"
)

Values of UnsafeMode.

View Source
const PayloadType = "application/vnd.agentry.managed-settings+json"

PayloadType is the DSSE payload type of a managed settings document. The signature covers it, so an envelope of another type (a release's attestation) never opens as a document, and a verifier that checks the payload type refuses a document as an attestation.

View Source
const Schema = "managed-settings/1"

Schema names this version of the document's shape. A client refuses a document whose schema it does not know.

View Source
const (
	// UnsafeMode decides whether a member may turn on Unsafe Mode, which
	// lets a local run use commands this machine has not catalogued. It
	// is "allowed" (the member decides, behind the client's own consent)
	// or "forbidden" (the client refuses to turn it on, and the runner
	// refuses an unsafe run). No value turns it on.
	UnsafeMode = "run.unsafeMode"
)

The catalogue's ids.

Variables

This section is empty.

Functions

func Seal

func Seal(d Document) ([]byte, error)

Seal encodes a valid document as the payload a signer signs. The returned bytes are what the envelope carries.

func ValidateSettings

func ValidateSettings(settings map[string]Setting) error

ValidateSettings checks every setting against the catalogue: a known id, and a value the row takes. It is what a registry checks before it stores or signs settings: a registry signs only rows it knows.

Types

type Document

type Document struct {
	// Schema is always the Schema constant.
	Schema string `json:"schema"`
	// Registry is the base URL of the registry that signed the document.
	// A client accepts it only from that registry.
	Registry string `json:"registry"`
	// Org is the handle of the organization whose settings these are. A
	// client accepts the document only while the signed-in account is an
	// active member of that organization; a person belongs to one.
	Org string `json:"org"`
	// Version increases with every change the organization's admins make.
	// A client refuses a version lower than the last it accepted from the
	// same organization, so an older copy cannot be replayed to it.
	Version int64 `json:"version"`
	// IssuedAt is when the registry signed this version.
	IssuedAt time.Time `json:"issuedAt"`
	// Settings maps a catalogue id to its value.
	Settings map[string]Setting `json:"settings"`
}

Document is one member's managed settings.

func Open

func Open(env Envelope, publicKeyPEM string) (Document, error)

Open verifies an envelope against a public key the caller already trusts for the registry, then decodes and validates the document. It refuses another payload type, another schema, a field the format does not have, and a known row with a value it does not take. A row whose id this catalogue does not know is kept, for the caller to judge through Unknown: a newer registry may add rows. It does not check Registry, Org or Version: the caller compares them with the registry it is signed in to, the organization it is a member of, and the last version it accepted.

func (Document) Unknown

func (d Document) Unknown() []UnknownSetting

Unknown lists the document's settings whose ids the catalogue does not know, sorted by id. A client cannot apply them: a locked one means the organization holds the member to something this client cannot enforce, so the client should refuse to run until it is updated; a default one can be passed over.

func (Document) Validate

func (d Document) Validate() error

Validate checks a whole document as a registry signs it: its schema, its binding fields, and settings that are all rows of the catalogue.

type Envelope

type Envelope = attest.DSSEEnvelope

Envelope is a signed document as the registry serves it.

func Wrap

func Wrap(payload []byte, sig attest.DSSESignature) Envelope

Wrap puts a payload and its signature into an envelope.

type Row

type Row struct {
	// ID is the setting's name in a document.
	ID string
	// Values are the values the row takes, from the most open to the most
	// restrictive.
	Values []string
	// Summary says in one sentence what the row decides, for consoles and
	// for the client's own listing.
	Summary string
}

Row is one entry of the catalogue.

func Catalogue

func Catalogue() []Row

Catalogue is every row a document may carry, sorted by id.

func Lookup

func Lookup(id string) (Row, bool)

Lookup is the row with the id, or false.

type Setting

type Setting struct {
	// Value is the row's value, a JSON string for an enumerated row.
	Value json.RawMessage `json:"value"`
	// Locked says the member cannot change it. A setting that is not
	// locked is an organization default.
	Locked bool `json:"locked"`
}

Setting is one managed value.

func (Setting) String

func (s Setting) String() string

String reads an enumerated setting's value, or "" when it is not a JSON string.

type UnknownSetting

type UnknownSetting struct {
	ID     string
	Locked bool
}

UnknownSetting is a setting whose id this version's catalogue does not know: a row a newer registry added.

Jump to

Keyboard shortcuts

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