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
- Variables
- func Seal(d Document) ([]byte, error)
- func SealDelivery(publicKey []byte, d Delivery, value []byte) ([]byte, error)
- func ValidateSettings(settings map[string]Setting) error
- type Assignment
- type Delivery
- type DeliveryKey
- type Document
- type Envelope
- type KeyRef
- type Kind
- type Members
- type Model
- type Preset
- type Row
- type Server
- type Setting
- type Source
- type Sources
- type UnknownSetting
Constants ¶
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.
const ( MaxAgentNameLength = 64 MaxPersonalityLength = 4000 MaxAgentServers = 20 MaxAgentPacks = 20 )
The bounds of an agent configuration's rows.
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.
const ( MaxAssignments = 100 MaxPresetInputs = 32 MaxInputBytes = 4096 )
The bounds of a quickagents value.
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.
const ( SignInSubscription = "subscription" SignInClaude = "claude-signin" SignInChatGPT = "chatgpt-plan" SignInCopilot = "copilot-signin" )
Members of ModelSignIns: the subscriptions and plans a run may spend.
const ( SourceMember = "member" SourceAgentryCredits = "agentry-credits" SourceOrganizationKey = "organization-key" SourceOff = "off" )
Values of the source rows, from the most open to none.
const ( SearchBrave = "brave" SearchTavily = "tavily" SearchExa = "exa" SearchPerplexity = "perplexity" SearchYouCom = "youcom" )
Providers of WebSearchSource.
const ( CodingClaudeCode = "claude-code" CodingCodex = "codex" CodingCopilot = "copilot" )
Members of CodingToolsAllowed: the coding tools whose harnesses a run may use.
const ( UnsafeModeAllowed = "allowed" UnsafeModeForbidden = "forbidden" Allowed = "allowed" Forbidden = "forbidden" )
Values of the allowed-or-forbidden choices, UnsafeMode's among them.
const ( MalwareCheckOptional = "optional" MalwareCheckRequired = "required" )
Values of MalwareCheck.
const ( WhereLocal = "local" WhereHosted = "hosted" WhereRunhost = "runhost" WhereTargetHost = "target-host" )
Members of RunWhere.
const ( DestinationFolder = "folder" DestinationWebhook = "webhook" DestinationS3 = "s3" )
Members of DeliverablesDestinations.
const ( SourcesAny = "any" SourcesOrganizationBuiltIns = "organization-and-built-ins" )
Scopes of InstallSources.
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.
const (
EndpointsHTTPSOnly = "https-only"
)
Values of ModelCustomEndpoints.
const MaxDeliveredKey = 8192
MaxDeliveredKey is the longest key a seal carries.
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 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.
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 ¶
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 ¶
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
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 ¶
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 ¶
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
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.
type Envelope ¶
type Envelope = attest.DSSEEnvelope
Envelope is a signed document as the registry serves it.
type KeyRef ¶ added in v0.7.11
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
BindMembers binds a document to accounts (their ids, as the registry names them) under a new random salt.
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.
type Server ¶ added in v0.7.15
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.
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 ¶
UnknownSetting is a setting whose id this version's catalogue does not know: a row a newer registry added.