Documentation
¶
Overview ¶
Package managed is a client's copy of the managed settings an organization's admins set for its members: the registry's signed document (github.com/blaktron/agentry/pkg/managedsettings), fetched with the account's own token, verified against the keys pinned for that registry at sign-in, held to that registry and to the organization the account is an active member of, and kept in the config directory so that it still applies offline.
Every load verifies the cached copy again: the cache is the signed envelope as the registry served it, never a decoded copy, so an edit to it is refused. A record beside it says what the registry last answered, so a document that was accepted and is now missing is noticed rather than read as "none apply". A document only ever narrows what a member could choose, so the engine applies every verified document it holds, whichever registry a run comes from.
Index ¶
- Constants
- Variables
- func AgentOf(ref string, builtIn, persistent bool) string
- func Applies(id string) bool
- func AppliesSetting(id string, locked bool) bool
- func CachePath(registryURL string) (string, error)
- func Dir() (string, error)
- func Enforce(ids ...string)
- func Forget(registryURL string) error
- func Hold(p *policy.Policy) *policy.Policy
- func KeyAccount(org, provider string) string
- func ModelRefusal(m RunModel) string
- func SignedIn(registryURL, accountID string) error
- type Effective
- func (e Effective) AcceptRiskRefusal(consent string) string
- func (e Effective) Budgets(b spec.Budgets) spec.Budgets
- func (e Effective) DeliveredKey(setting, provider string) (value string, found bool, err error)
- func (e Effective) DestinationRefusal(kind string) string
- func (e Effective) Forbidden(id string) string
- func (e Effective) Hold(p *policy.Policy) *policy.Policy
- func (e Effective) KeySourceOf(id string) KeySource
- func (e Effective) ModelRefusal(m RunModel) string
- func (e Effective) Narrowing() *Narrowing
- func (e Effective) PolicyBudgets(b policy.Budgets) policy.Budgets
- func (e Effective) PolicyHeld() policy.Held
- func (e Effective) Refusal(r Run) string
- func (e Effective) Registry(registryURL string) Effective
- func (e Effective) RunRefusal() string
- func (e Effective) ServiceKey(id, provider, own string) (key string, ok bool, err error)
- func (e Effective) SetupModel() SetupModel
- func (e Effective) SourceRefusal(namespace string) string
- func (e Effective) Specs() []spec.ManagedSpec
- func (e Effective) UnsafeModeRefusal() string
- func (e Effective) VersionRefusal() string
- func (e Effective) WhereRefusal(where string) string
- type KeySource
- type Narrowing
- type Problem
- type Run
- type RunModel
- type SetupModel
- type State
Constants ¶
const ( AgentAssistant = "assistant" AgentCoder = "coder" )
Persistent built-ins a document may forbid, by name.
const BuiltInNamespace = "agentry"
BuiltInNamespace is the namespace of the QuickAgents built into Agentry, which an install source list always admits.
const FetchInterval = time.Hour
FetchInterval is how old the last answer may be before a run asks the registry again.
const Route = "/api/v1/user/managed-settings"
Route is the registry's answer to the signed-in caller.
Variables ¶
var ClientRows = []string{managedsettings.RunWhere, managedsettings.BugReports}
ClientRows are the rows the runner cannot apply alone, because a client has paths of its own that they govern: where runs may go (the runner holds runs on this computer, on a runhost and to target hosts; a client that starts runs In Agentry holds those) and bug reports, which a client sends. A client adds them with Enforce once every path it has obeys them.
Functions ¶
func AgentOf ¶ added in v0.7.42
AgentOf is the persistent built-in a release is, by its reference (ns/name or ns/name@version), or "": only Agentry's own built-ins, run as persistent agents, are one.
func AppliesSetting ¶ added in v0.7.46
AppliesSetting says this client applies the setting as a document sets it: a lock of an applied row, or a default this client acts on.
func Enforce ¶ added in v0.7.42
func Enforce(ids ...string)
Enforce adds rows this client applies through its own paths beside the runner's. It is called once, as the client starts, before any run.
func Forget ¶
Forget deletes the registry's cached document at sign-out. The newest version accepted from each organization is kept, so an older copy cannot be put back later.
func Hold ¶ added in v0.7.42
Hold is p held to the managed settings documents cached on this computer.
func KeyAccount ¶ added in v0.7.46
KeyAccount is the keychain account an organization's delivered key for provider is kept under.
func ModelRefusal ¶ added in v0.7.46
ModelRefusal is the refusal of a run on m by the managed settings cached on this computer, or "".
Types ¶
type Effective ¶
type Effective struct {
// Documents are the verified documents, by registry.
Documents []State
// Problems are what could not be verified. While there is one, no run
// starts: what it held is unknown, and it may lock anything.
Problems []Problem
}
Effective is every cached document together, as the engine applies them.
func Current ¶
func Current() Effective
Current loads every registry's managed settings and verifies each again. It never fails: what cannot be read or verified is a Problem.
func (Effective) AcceptRiskRefusal ¶ added in v0.7.42
AcceptRiskRefusal is the refusal of admitting a release by a member's acceptance of its risk (the consent, --allow-unsigned or --allow-unscanned), or "" when every document lets it or no risk was accepted.
func (Effective) Budgets ¶ added in v0.7.42
Budgets are b held to the documents' locked caps: a budget above a cap, or unlimited (0), becomes the cap, and one below it stays. A cap never lifts a member's own lower limit.
func (Effective) DeliveredKey ¶ added in v0.7.46
DeliveredKey is the organization's key for provider delivered under setting by the documents this computer holds, read from the keychain: found is false when no document names one. An error says why a named key is not here.
func (Effective) DestinationRefusal ¶ added in v0.7.42
DestinationRefusal is the refusal of a run delivering to a destination of the kind (folder, webhook, s3), or "" when every document lets it.
func (Effective) Forbidden ¶ added in v0.7.42
Forbidden is the refusal of what a document locks off by an allowed-or-forbidden row, or "" when none does.
func (Effective) Hold ¶ added in v0.7.42
Hold is p held to e's documents (PolicyHeld). The result is a view for checks and runs, never saved.
func (Effective) KeySourceOf ¶ added in v0.7.46
KeySourceOf reads id (review.source or webSearch.source) from the first document that sets it.
func (Effective) ModelRefusal ¶ added in v0.7.46
ModelRefusal is the refusal of a run on m, in the organization's name and the setting's, or "" when the documents allow it.
func (Effective) Narrowing ¶
Narrowing is what e says of a run sent to another machine; nil when it says nothing.
func (Effective) PolicyBudgets ¶ added in v0.7.42
PolicyBudgets are a runner policy's budgets with the documents' organization defaults filled in where the file sets none of its own (the fresh policy's value), then held to their locked caps.
func (Effective) PolicyHeld ¶ added in v0.7.42
PolicyHeld is what the documents hold the runner policy to: a refusal for each row a document locks to forbidden, an organization default that turns a field off where the file leaves it unset, and the malware check a document requires.
func (Effective) Refusal ¶ added in v0.7.42
Refusal is why the run may not start, or "": everything RunRefusal refuses, then where it goes, where its release comes from, a risk the member accepted for it, and the persistent built-in it is.
func (Effective) RunRefusal ¶
RunRefusal is why no run may start at all, or "": a document locks a setting this client does not know, so it cannot hold the member to it, or managed settings this client holds cannot be verified.
func (Effective) ServiceKey ¶ added in v0.7.46
ServiceKey is the key a service runs with on this computer under the documents, given the member's own (own, "" for none): ok false means the member's own key stands. A lock to off, or to a source this version cannot pay with, is a refusal naming the organization and the setting.
func (Effective) SetupModel ¶ added in v0.7.46
func (e Effective) SetupModel() SetupModel
SetupModel reads model.source and model.default, locked or default: an organization that pays with its own key or its credits sets the Agentry provider; otherwise model.default names the provider and the model.
func (Effective) SourceRefusal ¶ added in v0.7.42
SourceRefusal is the refusal of installing or running a release of the namespace, or "" when every document lets it. A document whose source list is the organization's and the built-ins' admits its own organization's namespace, the built-ins' and the namespaces it lists.
func (Effective) Specs ¶
func (e Effective) Specs() []spec.ManagedSpec
Specs are the documents as a plan and a receipt record them: the organization, the version and the ids of the settings this client applies, never a value.
func (Effective) UnsafeModeRefusal ¶
UnsafeModeRefusal is why Unsafe Mode may not be turned on, or "" when it may: a document that locks run.unsafeMode to forbidden, or managed settings this client holds that cannot be verified, which might.
func (Effective) VersionRefusal ¶ added in v0.7.42
VersionRefusal is the refusal of every run by a client older than a document's minimum version, naming the update, or "".
func (Effective) WhereRefusal ¶ added in v0.7.42
WhereRefusal is the refusal of a run going where (one of the run.where members), or "" when every document lets it.
type KeySource ¶ added in v0.7.46
KeySource is what the documents say pays for a service: a delivering row's source, its strength, the provider an organization's key is for, and the organization. Decided is false when no document sets the row.
type Narrowing ¶
type Narrowing struct {
// UnsafeModeRefusal is the device's refusal of Unsafe Mode, empty when
// the device allows it.
UnsafeModeRefusal string `json:"unsafeModeRefusal,omitempty"`
// Documents are the device's documents as the run's plan and receipt
// record them.
Documents []spec.ManagedSpec `json:"documents,omitempty"`
// Refused are the device's locks on the runner policy's checks, by
// the id the policy knows them by (policy.Held), each with the
// sentence that refuses it.
Refused map[string]string `json:"refused,omitempty"`
// MalwareCheck is the organization whose lock requires the malware
// check on the device, or "".
MalwareCheck string `json:"malwareCheck,omitempty"`
// Caps are the device's locked budget caps; a zero field caps nothing.
Caps *spec.Budgets `json:"caps,omitempty"`
}
Narrowing is what a device's managed settings say of a run it sends to another machine (a runhost), which has its own sign-in and its own documents. It can only refuse, so the machine that runs it applies it as sent: a forged one could do no more than stop the run.
type Problem ¶
type Problem struct {
// Registry is the registry's normalised address, or the file's name
// when the file names none.
Registry string
Err error
}
Problem is managed settings this client holds and cannot apply: a cached copy that does not verify, one that is older than a version already applied, or one that was accepted and is no longer there.
type Run ¶ added in v0.7.42
type Run struct {
// Ref is the release's ns/name@version.
Ref string
// BuiltIn says the release is built into Agentry.
BuiltIn bool
// Local says the run starts on this computer, rather than arriving
// from another device that judged where it goes.
Local bool
// TargetHosts says the run reaches target hosts.
TargetHosts bool
// AcceptedRisk is the member's consent that admitted a release with no
// attestation or no scan (--allow-unsigned, --allow-unscanned), or "".
AcceptedRisk string
// Agent is the persistent built-in the run is, by name ("assistant",
// "coder"), or "".
Agent string
}
Run is what the managed settings judge of a run before it starts.
type RunModel ¶ added in v0.7.46
type RunModel struct {
// Provider is the saved model's provider: a vendor's name, or
// custom-<slug> for an endpoint of the member's own.
Provider string
// Model is the model id the provider is asked for.
Model string
// KeyKind is the credential's kind (policy.Model.APIKeyKind).
KeyKind string
// BaseURL is the endpoint of the member's own, if any.
BaseURL string
// Adapter is the harness the run uses.
Adapter string
}
RunModel is a run's model as the rows judge it.
type SetupModel ¶ added in v0.7.46
type SetupModel struct {
Provider string
Model string
// Locked says the member cannot choose otherwise; the step is skipped.
Locked bool
// Line says what was set and by whom.
Line string
}
SetupModel is what the documents pre-fill, or lock, in setup's model step: the provider (and model) a member's runs use, and the sentence that says why. A zero SetupModel leaves the step as it is.
type State ¶
type State struct {
// Registry is the registry's normalised address.
Registry string
// Document is the verified document, bound to Registry.
Document managedsettings.Document
// FetchedAt is when this client last read it from the registry.
FetchedAt time.Time
}
State is one registry's verified managed settings.
func Load ¶
Load reads registryURL's cached document and verifies it again: the signature with a key pinned for the registry, the document's binding to the registry, that it is not older than a version already applied, and that a document the registry last answered is still there. It returns nil with no error when none apply, and an error when what is held cannot be verified.
func Refresh ¶
Refresh asks the registry for the signed-in account's managed settings with the account's token, and keeps what it answers: a document that verifies, is bound to this registry, is the settings of the organization the account is an active member of, and is not older than the newest one accepted from that organization replaces the cache; 204 (none apply) or 404 (no longer a member) deletes it. It returns nil when none apply. When the token is another account's than the last one's, the last one's settings are deleted first (SignedIn). On any other answer, or a document that is refused, the cache is left as it was and the error says why.
func Sync ¶
func Sync(ctx context.Context, hc *http.Client, registryURL, token string, maxAge time.Duration) (*State, error)
Sync is the refresh a run makes: when the registry answered within maxAge and what it answered still verifies, the cached copy (or none) stands; otherwise it asks the registry. When the registry cannot be asked, the last verified copy applies and is returned beside the error.