managedsettings

package
v0.7.11-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 12 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 (
	// 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"

	InstallSources           = "install.sources"
	InstallAcceptRisk        = "install.acceptRisk"
	RunWhere                 = "run.where"
	RunTimeout               = "run.timeout"
	RunMaxTurns              = "run.maxTurns"
	RunMaxCost               = "run.maxCost"
	EgressWildcard           = "egress.wildcard"
	BrowserPublicWeb         = "browser.publicWeb"
	MCPAllowVulnerable       = "mcpServers.allowVulnerable"
	DesktopApplications      = "desktop.applications"
	DesktopScreen            = "desktop.screen"
	DesktopCustomServers     = "desktop.customServers"
	Messengers               = "messengers"
	PersistentReleases       = "persistentReleases"
	AgentsCodingAgent        = "agents.codingAgent"
	AgentsAssistant          = "agents.assistant"
	Schedules                = "schedules"
	DeliverablesDestinations = "deliverables.destinations"
	MalwareCheck             = "malwareCheck"
	UpdatesMinimumVersion    = "updates.minimumVersion"
	BugReports               = "bugReports"

	ModelProviders       = "model.providers"
	ModelDefault         = "model.default"
	ModelSource          = "model.source"
	ModelSignIns         = "model.signIns"
	ModelCustomEndpoints = "model.customEndpoints"
	ReviewSource         = "review.source"
	WebSearchSource      = "webSearch.source"
	CodingToolsAllowed   = "codingTools.allowed"
)

The catalogue's ids.

View Source
const (
	ProviderAnthropic   = "anthropic"
	ProviderOpenAI      = "openai"
	ProviderGoogle      = "google"
	ProviderVultr       = "vultr"
	ProviderOpenRouter  = "openrouter"
	ProviderPoe         = "poe"
	ProviderHuggingFace = "huggingface"
	ProviderCopilot     = "copilot"
	ProviderAgentry     = "agentry"
	ProviderCustom      = "custom"
)

Members of ModelProviders and providers of ModelDefault: the model providers a run may use. ProviderAgentry is the registry's own endpoint, paid from credits or by the organization's key; ProviderCustom is any endpoint of the member's own.

View Source
const (
	SignInSubscription = "subscription"
	SignInClaude       = "claude-signin"
	SignInChatGPT      = "chatgpt-plan"
	SignInCopilot      = "copilot-signin"
)

Members of ModelSignIns: the subscriptions and plans a run may spend.

View Source
const (
	SourceMember          = "member"
	SourceAgentryCredits  = "agentry-credits"
	SourceOrganizationKey = "organization-key"
	SourceOff             = "off"
)

Values of the source rows, from the most open to none.

View Source
const (
	SearchBrave      = "brave"
	SearchTavily     = "tavily"
	SearchExa        = "exa"
	SearchPerplexity = "perplexity"
	SearchYouCom     = "youcom"
)

Providers of WebSearchSource.

View Source
const (
	CodingClaudeCode = "claude-code"
	CodingCodex      = "codex"
	CodingCopilot    = "copilot"
)

Members of CodingToolsAllowed: the coding tools whose harnesses a run may use.

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

	Allowed   = "allowed"
	Forbidden = "forbidden"
)

Values of the allowed-or-forbidden choices, UnsafeMode's among them.

View Source
const (
	MalwareCheckOptional = "optional"
	MalwareCheckRequired = "required"
)

Values of MalwareCheck.

View Source
const (
	WhereLocal      = "local"
	WhereHosted     = "hosted"
	WhereRunhost    = "runhost"
	WhereTargetHost = "target-host"
)

Members of RunWhere.

View Source
const (
	DestinationFolder  = "folder"
	DestinationWebhook = "webhook"
	DestinationS3      = "s3"
)

Members of DeliverablesDestinations.

View Source
const (
	SourcesAny                  = "any"
	SourcesOrganizationBuiltIns = "organization-and-built-ins"
)

Scopes of InstallSources.

View Source
const (
	EndpointsHTTPSOnly = "https-only"
)

Values of ModelCustomEndpoints.

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.

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 KeyRef added in v0.7.11

type KeyRef struct {
	ID  string `json:"id"`
	Rev int64  `json:"rev"`
}

KeyRef names an organization's key and its revision. It is a reference a client exchanges for the key, never the key.

type Kind added in v0.7.10

type Kind string

Kind is how a row's value is written and how it narrows.

const (
	// KindChoice is one of the row's Values, which run from the most open
	// to the most restrictive. No row has a value that switches anything
	// on.
	KindChoice Kind = "choice"
	// KindSet is a JSON array of the row's Values with no repeats and at
	// least one member: the members still allowed. A lock never adds a
	// member the row does not list.
	KindSet Kind = "set"
	// KindCap is a positive JSON number (an integer where the row says
	// so). A lock is the highest value a member may use; a default is the
	// value used when the member set none. A cap never lifts a member's
	// own lower limit.
	KindCap Kind = "cap"
	// KindSources is {"scope": "any"} or {"scope":
	// "organization-and-built-ins", "namespaces": [...]}: where a member
	// may install from.
	KindSources Kind = "sources"
	// KindMinimumVersion is a version "X.Y.Z": a client older than it
	// refuses runs and names the update.
	KindMinimumVersion Kind = "minimumVersion"
	// KindModel is {"provider": …, "model": …}: a provider of the row's
	// Values and a model id. Locked, it is the only model members' runs
	// use; as a default, the one a member who chose none runs on.
	KindModel Kind = "model"
	// KindSource is {"source": …} with one of the row's Values: what pays
	// for a service, from the member's own key (the most open) to none at
	// all. A row that delivers keys (Delivers) carries, with
	// organization-key and only then, {"key": {"id", "rev"}}: a reference
	// to the organization's key, never its value. A row with Providers
	// names the service's provider with organization-key.
	KindSource Kind = "source"
)

type Model added in v0.7.11

type Model struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
}

Model is the value of a KindModel row.

type Row

type Row struct {
	// ID is the setting's name in a document.
	ID string
	// Kind says how the value is written and how it narrows.
	Kind Kind
	// Values are a choice's values, from the most open to the most
	// restrictive, or a set's members.
	Values []string
	// Integer says a cap is a whole number.
	Integer bool
	// Max is the largest cap a registry accepts.
	Max float64
	// LockOnly says the row is only ever locked: a default would have
	// nothing to apply (a set, a source list, a version floor).
	LockOnly bool
	// AllowEmpty says a set may have no member: nothing of it allowed.
	AllowEmpty bool
	// Delivers says a source row's organization-key carries a key
	// reference, which a client exchanges for the key itself; a row that
	// does not deliver never carries one.
	Delivers bool
	// Providers are the providers a source row's organization-key may
	// name; empty when the row names none.
	Providers []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.

func (Row) Check added in v0.7.10

func (r Row) Check(s Setting) error

Check says whether s is a value this row takes: its shape, and for a row that is only ever locked, its lock.

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 Source added in v0.7.11

type Source struct {
	Source   string  `json:"source"`
	Provider string  `json:"provider,omitempty"`
	Key      *KeyRef `json:"key,omitempty"`
}

Source is the value of a KindSource row.

type Sources added in v0.7.10

type Sources struct {
	Scope      string   `json:"scope"`
	Namespaces []string `json:"namespaces,omitempty"`
}

Sources is the value of an InstallSources row.

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