managedsettings

package
v0.7.17-dev.2 Latest Latest
Warning

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

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

	QuickAgents = "quickagents"

	AgentsAssistantName        = "agents.assistant.name"
	AgentsAssistantPersonality = "agents.assistant.personality"
	AgentsAssistantRunOnStart  = "agents.assistant.runOnStart"
	AgentsAssistantServers     = "agents.assistant.servers"
	AgentsAssistantKnowledge   = "agents.assistant.knowledge"
	AgentsCodingAgentServers   = "agents.codingAgent.servers"
	AgentsCodingAgentKnowledge = "agents.codingAgent.knowledge"
	CodingToolsModels          = "codingTools.models"
	AgentsUnreviewed           = "agents.unreviewed"
)

The catalogue's ids.

View Source
const (
	MaxAgentNameLength   = 64
	MaxPersonalityLength = 4000
	MaxAgentServers      = 20
	MaxAgentPacks        = 20
)

The bounds of an agent configuration's rows.

View Source
const (
	// AssignRequired is installed on every member's signed-in client, and
	// cannot be uninstalled while the organization requires it.
	AssignRequired = "required"
	// AssignOffered is listed for the member, who installs it on demand.
	AssignOffered = "offered"
	// VersionLatest follows the newest version the member could install.
	VersionLatest = "latest"
)

An assignment's modes and its version that follows the newest release.

View Source
const (
	MaxAssignments  = 100
	MaxPresetInputs = 32
	MaxInputBytes   = 4096
)

The bounds of a quickagents value.

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 DeliverySuite = "hpke-mlkem768x25519-hkdfsha256-chacha20poly1305"

DeliverySuite names the HPKE suite a delivered key is sealed with: ML-KEM-768 with X25519 (X-Wing), HKDF-SHA256 and ChaCha20-Poly1305.

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

Values of ModelCustomEndpoints.

View Source
const MaxDeliveredKey = 8192

MaxDeliveredKey is the longest key a seal carries.

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 the document's shape when every member of the organization receives it alike. A client refuses a document whose schema it does not know; SchemaMembers is the other shape.

View Source
const SchemaMembers = "managed-settings/2"

SchemaMembers names the document's shape when it is bound to the accounts it is for. A registry that signs several documents for one organization at one version (one for each combination of teams with settings) binds each to its members, so a member who holds another member's document cannot put it in place of their own: the client refuses a bound document that does not name its account. A document that every member of the organization receives alike keeps Schema.

Variables

View Source
var ErrNotForAccount = errors.New("this document was signed for other members of the organization, not for the signed-in account")

ErrNotForAccount is a bound document that does not name the account a client is signed in as.

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

func SealDelivery(publicKey []byte, d Delivery, value []byte) ([]byte, error)

SealDelivery seals value, an organization's key, to the client's public key for d. A public key that is not one of DeliverySuite's is refused before anything is sealed.

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 Assignment added in v0.7.13

type Assignment struct {
	// Ref is the release, "namespace/name".
	Ref string `json:"ref"`
	// Version is "X.Y.Z" to pin it, or VersionLatest.
	Version string `json:"version"`
	// Mode is AssignRequired or AssignOffered.
	Mode string `json:"mode"`
	// Preset is the run settings a member would otherwise choose.
	Preset *Preset `json:"preset,omitempty"`
	// PresetLocked makes the preset a lock rather than a default.
	PresetLocked bool `json:"presetLocked,omitempty"`
}

Assignment is one QuickAgent an organization gives its members.

type Delivery added in v0.7.11

type Delivery struct {
	// Registry is the registry's origin, as the document names it.
	Registry string `json:"registry"`
	// Org is the organization's handle.
	Org string `json:"org"`
	// Account is the member's account id.
	Account string `json:"account"`
	// Key and Rev are the document's KeyRef.
	Key string `json:"key"`
	Rev int64  `json:"rev"`
}

Delivery is what one delivered key answers. Every field is bound into the seal.

type DeliveryKey added in v0.7.11

type DeliveryKey struct {
	// contains filtered or unexported fields
}

DeliveryKey is a client's key pair for one delivery. Its private half stays in memory and is dropped after the one Open.

func NewDeliveryKey added in v0.7.11

func NewDeliveryKey() (*DeliveryKey, error)

NewDeliveryKey makes a fresh key pair for one delivery.

func (*DeliveryKey) Open added in v0.7.11

func (k *DeliveryKey) Open(d Delivery, sealed []byte) ([]byte, error)

Open opens a sealed key made for d with this key pair.

func (*DeliveryKey) PublicKey added in v0.7.11

func (k *DeliveryKey) PublicKey() []byte

PublicKey is the public half the client sends with its request.

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"`
	// Members binds the document to the accounts it is for. A document
	// of SchemaMembers has it; one of Schema, which every member of the
	// organization receives alike, has none.
	Members *Members `json:"members,omitempty"`
}

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, Version or Members: the caller compares them with the registry it is signed in to, the organization it is a member of, the last version it accepted, and the account it is signed in as (For).

func (Document) For added in v0.7.16

func (d Document) For(account string) error

For checks that the document applies to account (the signed-in account's id): a document every member receives alike applies to any, and a bound one only to the accounts it names. A client calls it after Open, with the account it signed in as, before it applies or keeps the document.

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"
	// KindQuickAgents is a list of Assignment: the QuickAgents an
	// organization gives its members, each required or offered, pinned to a
	// version or following the latest, with an optional preset of run
	// settings. It is only ever locked: the list is the organization's.
	KindQuickAgents Kind = "quickAgents"
	// KindText is a JSON string of at most the row's MaxLength characters,
	// with no control characters but newlines: a preference such as an
	// agent's name, which grants nothing.
	KindText Kind = "text"
	// KindToggle is a JSON boolean: a preference such as whether an agent
	// starts with Agentry, which grants nothing.
	KindToggle Kind = "toggle"
	// KindServers is a list of Server: remote MCP servers put on an agent's
	// roster. The member still consents to them at the agent's next start,
	// and the runner's own server rules still apply to them.
	KindServers Kind = "servers"
	// KindPacks is a list of the organization's shared knowledge packs by
	// name, put on an agent's roster; the member still consents to them.
	KindPacks Kind = "packs"
	// KindToolModels maps a coding tool of the row's Values to the model id
	// it uses.
	KindToolModels Kind = "toolModels"
)

type Members added in v0.7.16

type Members struct {
	// Salt is 16 random bytes, base64 (standard, padded).
	Salt string `json:"salt"`
	// Digests are memberDigest of each account's id, lowercase hex,
	// sorted, without repeats.
	Digests []string `json:"digests"`
}

Members binds a document to the accounts it is for. It lists a digest of each account's id under a salt drawn for the document, so the document names its members to a client that knows its own account and to no one else.

func BindMembers added in v0.7.16

func BindMembers(accounts []string) (*Members, error)

BindMembers binds a document to accounts (their ids, as the registry names them) under a new random salt.

func (Members) Includes added in v0.7.16

func (m Members) Includes(account string) bool

Includes reports whether account is one of the members.

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 Preset added in v0.7.13

type Preset struct {
	Model          *Model            `json:"model,omitempty"`
	TimeoutSeconds int               `json:"timeoutSeconds,omitempty"`
	MaxTurns       int               `json:"maxTurns,omitempty"`
	Where          string            `json:"where,omitempty"`
	Inputs         map[string]string `json:"inputs,omitempty"`
}

Preset is the run settings of an assignment's runs: each a default the member may change, or, with Assignment.PresetLocked, fixed. A field left out is the member's to choose.

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
	// MaxLength is the most characters a text row takes.
	MaxLength int
	// 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 Server added in v0.7.15

type Server struct {
	Name string `json:"name"`
	URL  string `json:"url"`
	Auth string `json:"auth"`
}

Server is one remote MCP server of a KindServers row: a name it is shown by, its https address, and how it is signed in to: "oauth" (the member's connection, or the organization's identity provider for a server the organization manages) or "none". The organization delivers no secret for it.

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