managed

package
v0.7.35-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
const FetchInterval = time.Hour

FetchInterval is how old the last answer may be before a run asks the registry again.

View Source
const Route = "/api/v1/user/managed-settings"

Route is the registry's answer to the signed-in caller.

Variables

This section is empty.

Functions

func Applies

func Applies(id string) bool

Applies says this client applies the setting.

func CachePath

func CachePath(registryURL string) (string, error)

CachePath is where registryURL's verified document is kept.

func Dir

func Dir() (string, error)

Dir is the folder the cached documents live in.

func Forget

func Forget(registryURL string) error

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 SignedIn

func SignedIn(registryURL, accountID string) error

SignedIn records that accountID is now signed in to the registry. When another account was, its managed settings are deleted: they were never this account's. The same account's are kept, so a sign-in the registry cannot answer at that moment does not lift its organization's locks.

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) Narrowing

func (e Effective) Narrowing() *Narrowing

Narrowing is what e says of a run sent to another machine; nil when it says nothing.

func (Effective) Registry

func (e Effective) Registry(registryURL string) Effective

Registry is the part of e that is registryURL's.

func (Effective) RunRefusal

func (e Effective) RunRefusal() string

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) 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

func (e Effective) UnsafeModeRefusal() string

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.

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"`
}

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.

func (*Narrowing) Validate

func (n *Narrowing) Validate() error

Validate holds a Narrowing that arrived from another machine to what one can carry: a one-line refusal, organizations' handles, setting ids.

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 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

func Load(registryURL string) (*State, error)

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

func Refresh(ctx context.Context, hc *http.Client, registryURL, token string) (*State, error)

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.

func (*State) Applied

func (s *State) Applied() []string

Applied are the ids of the document's settings this client applies, sorted.

func (*State) Locked

func (s *State) Locked(id string) (string, bool)

Locked is the value of a setting the organization locked, and whether it is locked.

func (*State) Summary

func (s *State) Summary() string

Summary is how one line names the document: "managed by acme (version 7)".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL