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 ¶
const ( UnsafeModeAllowed = "allowed" UnsafeModeForbidden = "forbidden" )
Values of UnsafeMode.
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.
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.
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 ¶
Seal encodes a valid document as the payload a signer signs. The returned bytes are what the envelope carries.
func ValidateSettings ¶
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 ¶
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.
type Envelope ¶
type Envelope = attest.DSSEEnvelope
Envelope is a signed document as the registry serves it.
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.
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.
type UnknownSetting ¶
UnknownSetting is a setting whose id this version's catalogue does not know: a row a newer registry added.