extension

package
v0.7.14-dev.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

agentryd is the Agentry server binary: a modular monolith whose role is selected at start: `agentryd api|git|worker|all`. The entry point is parameterised by extensions: the core build is Main() with none, an extended build is Main(theirs...).

Package extension is the seam an extended build uses to add to the server without forking it: routes under /api/v1/x/<name>/, migrations in the extension's own schema, an entitlements resolver, hooks on the events the core commits, and worker jobs. cmd/agentryd is Main with no extensions; an extended build's main is Main with its own.

The types an extension speaks are aliases of the core's, so a module outside this one can implement the interface without importing internal packages.

Index

Constants

View Source
const (
	NamespaceUser = entitlements.NamespaceUser
	NamespaceOrg  = entitlements.NamespaceOrg
)

The two namespace kinds a Subject carries.

View Source
const (
	AccountErased      = api.AccountErased
	AccountDataCleared = api.AccountDataCleared
)

The two account clears.

View Source
const (
	KeyOwnerUser = knowledge.OwnerUser
	KeyOwnerOrg  = knowledge.OwnerOrg
)

The owners a knowledge pack can have.

View Source
const (
	KnowledgeEmpty    = knowledge.StateEmpty
	KnowledgeScanning = knowledge.StateScanning
	KnowledgeReady    = knowledge.StateReady
	KnowledgeFailed   = knowledge.StateFailed
)

The states a knowledge pack is in.

View Source
const (
	ModelInputOpScan   = api.ModelInputOpScan
	ModelInputOpSearch = api.ModelInputOpSearch
	ModelInputOpCheck  = api.ModelInputOpCheck
)

The model-input operations a call can be: a scan, a search, and the check of a finished draft.

View Source
const (
	VoiceSourceBuild  = voice.SourceBuild
	VoiceSourceAIEdit = voice.SourceAIEdit
)

The sources a Voice Writer run In Agentry proposes with.

View Source
const (
	ScopeRunRead        = auth.ScopeRunRead
	ScopeRunWrite       = auth.ScopeRunWrite
	ScopeKnowledgeRead  = auth.ScopeKnowledgeRead
	ScopeKnowledgeWrite = auth.ScopeKnowledgeWrite
	// ScopeSecretWrite lets a token set and delete the caller's
	// hosted-run secrets; the vault extension requires it.
	ScopeSecretWrite = auth.ScopeSecretWrite
	// ScopeCreditsSession lets a token open, renew and end a credits
	// session and nothing else. An extension that serves credits
	// sessions accepts it there; every other route, the core's and every
	// extension's, must refuse a token carrying only it, which
	// ScopeAllows does for any other scope.
	ScopeCreditsSession = auth.ScopeCreditsSession
)

The scopes an extension route may require.

View Source
const (
	// EventAccountErased is heard once an account's erasure has committed,
	// with UserID, the Identities it signed in with and the Email it held:
	// what an extension that keeps a copy of the person elsewhere (a
	// directory's account) needs to erase it there. It is best-effort like
	// every hook, so an extension that must not miss one enqueues a Job
	// from it and retries there.
	EventAccountErased = api.EventAccountErased
	// EventStaffChanged is heard a few seconds after the registry changed
	// someone's platform staff standing. It names nobody: read the whole
	// set (Deps.Staff), which also catches up on a change missed.
	EventStaffChanged = api.EventStaffChanged
)

The identity events.

View Source
const (
	ActorUser   = audit.ActorUser
	ActorPAT    = audit.ActorPAT
	ActorSystem = audit.ActorSystem
)

The actor kinds an extension's events carry.

View Source
const (
	DirectoryLookupByID          = api.DirectoryLookupByID
	DirectoryLookupByUID         = api.DirectoryLookupByUID
	DirectoryLookupByAddress     = api.DirectoryLookupByAddress
	DirectoryLookupAddressShared = api.DirectoryLookupAddressShared
	DirectoryLookupIDMismatch    = api.DirectoryLookupIDMismatch
	DirectoryLookupSuperuser     = api.DirectoryLookupSuperuser
)

The rules a directory lookup ends by; the last three left an account the person may hold in place, which erasure reports as unresolved.

View Source
const (
	CallbackRateNone = api.RateNone
	CallbackRateAnon = api.RateAnon
)

The rate classes a callback mount may draw from: none, for a caller that speaks for everyone signing in, or the anonymous bucket per address.

View Source
const (
	DirectoryErasureDeleted       = api.DirectoryErasureDeleted
	DirectoryErasureNotFound      = api.DirectoryErasureNotFound
	DirectoryErasureUnresolved    = api.DirectoryErasureUnresolved
	DirectoryErasureNotConfigured = api.DirectoryErasureNotConfigured
	DirectoryErasureFailed        = api.DirectoryErasureFailed
	DirectoryErasurePending       = api.DirectoryErasurePending
)

The outcomes EraseErased may return; any other is left off the response.

View Source
const EventAgentDependencyAlert = webhook.EventAgentDependencyAlert

EventAgentDependencyAlert is the catalog event a dependency alert is fanned out as. It is what the hook hears as Event.Kind, and what an extension routing the alert delivers it as, so the destination it names reads the same event a subscription would have given it.

View Source
const EventRunEnded = webhook.EventRunEnded

EventRunEnded is the catalog event a hosted run's end is delivered as: an organization's endpoint subscribes to it by this name, and the extension that runs QuickAgents In Agentry delivers it to each subscribed endpoint through Webhooks.Deliver. The core emits none itself.

View Source
const QueueAPI = "api"

QueueAPI is the queue the api role drains, for a Job that must reach a service only the api may reach: an admin API behind a network policy that admits the api alone, kept from the worker because the worker opens untrusted archives. The worker neither registers nor enqueues such a job; the single-process `all` role drains this queue beside its worker's. A job here runs beside the api's requests, so it should be light.

Variables

View Source
var (
	ErrKnowledgeUnconfigured = knowledge.ErrUnconfigured
	ErrKnowledgeNotFound     = knowledge.ErrNotFound
	ErrKnowledgeScanning     = knowledge.ErrScanning
	ErrKnowledgeChanged      = knowledge.ErrChanged
	ErrKnowledgeName         = knowledge.ErrName
	ErrKnowledgeNameTaken    = knowledge.ErrNameTaken
	ErrKnowledgeTree         = knowledge.ErrTree
	ErrKnowledgeTooLarge     = knowledge.ErrTooLarge
)

The knowledge seam's refusals.

View Source
var (
	ErrVoiceUnconfigured = voice.ErrUnconfigured
	ErrVoiceNotFound     = voice.ErrNotFound
	ErrVoiceTooLarge     = voice.ErrTooLarge
)

The voice seam's refusals.

View Source
var (
	ErrOrgNotProvisionable = api.ErrOrgNotProvisionable
	ErrAddressUnproven     = api.ErrAddressUnproven
	ErrAccountSuspended    = api.ErrAccountSuspended
	ErrStaffOrgDomain      = registry.ErrStaffOrgDomain
)

The refusals of Members.Provision.

View Source
var (
	ErrActorNotStaff = api.ErrActorNotStaff
	ErrActorSession  = api.ErrActorSession
	ErrSelfAct       = api.ErrSelfAct
	ErrNoAccount     = api.ErrNoAccount
	ErrAccountErased = api.ErrAccountErased
	ErrReasonLength  = api.ErrReasonLength
	ErrLastAdmin     = api.ErrLastAdmin

	ErrAlreadyActivated = api.ErrAlreadyActivated
	ErrNoAddress        = api.ErrNoAddress
	ErrNotActive        = api.ErrNotActive
)

The refusals of Accounts.

View Source
var ErrKeyNotOwner = knowledge.ErrNotOwner

ErrKeyNotOwner is what a KeyWrapper's Unwrap answers for a wrapped key that does not open for the owner presenting it; the routes answer it as a key that is not there.

View Source
var ErrNoSecondFactor = api.ErrNoSecondFactor

ErrNoSecondFactor is SignIn.RememberBrowser's refusal of a sign-in whose token shows no second factor answered just now.

View Source
var ErrReportDesignsFull = api.ErrReportDesignsFull

ErrReportDesignsFull is a create past the library's bound of ten.

Functions

func Main

func Main(exts ...Extension)

Main runs agentryd with the given extensions: the `api | git | worker | all` roles, `migrate`, and the git hook shim.

func Run

func Run(ctx context.Context, cfgPath, role string, exts ...Extension) error

Run is one role of agentryd until ctx ends.

func RunWith

func RunWith(ctx context.Context, cfgPath, role string, opts Options, exts ...Extension) error

RunWith is Run with Options.

func ScopeAllows

func ScopeAllows(p *Principal, s Scope) bool

ScopeAllows is how the core reads a scope for a route: an anonymous caller never passes; a session passes, having the account's full authority (the route still checks who the account is); a PAT passes only when it was minted with the scope, and a schedule's credential (ScheduleCredentials.ForSchedule) only when the scope is one of auth.ScheduleScopes; a principal from Principals.ForUser, which is no caller, never passes. An extension route calls this with the principal and the scope it requires and refuses on false.

Types

type AccountChange added in v0.6.1000

type AccountChange = api.AccountChange

AccountChange is what an Accounts act did.

type AccountErasure added in v0.6.1000

type AccountErasure = api.AccountErasure

AccountErasure is what Accounts.Erase did.

type AccountErasureKind

type AccountErasureKind = api.AccountErasureKind

AccountErasureKind says which account clear an EraseAccount call is part of; its values are the audit actions that record them.

type AccountFacts added in v0.6.1000

type AccountFacts = api.AccountFacts

AccountFacts is what Accounts.Facts reads of an account.

type AccountOrg added in v0.6.1000

type AccountOrg = api.AccountOrg

AccountOrg, AccountSession and AccountToken are its parts.

type AccountSession added in v0.6.1000

type AccountSession = api.AccountSession

AccountOrg, AccountSession and AccountToken are its parts.

type AccountToken added in v0.6.1000

type AccountToken = api.AccountToken

AccountOrg, AccountSession and AccountToken are its parts.

type Accounts added in v0.6.1000

type Accounts interface {
	// Facts reads the account, the actor's own included: its state,
	// standing, memberships, live sessions by client and time, and live
	// tokens by name and scope. Never a secret.
	Facts(ctx context.Context, actor *Principal, userID uuid.UUID) (AccountFacts, error)
	// Suspend suspends the account and revokes every session, token, SSH
	// key, remembered browser and unused desktop sign-in code; it is no
	// longer platform staff. Changed is false when it was already
	// suspended.
	Suspend(ctx context.Context, actor *Principal, userID uuid.UUID, reason string) (AccountChange, error)
	// Reinstate makes a suspended account active again and revokes every
	// credential once more, so nothing from before comes back. Changed is
	// false when it was already active.
	Reinstate(ctx context.Context, actor *Principal, userID uuid.UUID, reason string) (AccountChange, error)
	// SignOut ends every session and forgets every remembered browser;
	// tokens and SSH keys keep working. Changed is false when there was
	// nothing to end.
	SignOut(ctx context.Context, actor *Principal, userID uuid.UUID, reason string) (AccountChange, error)
	// TellSecondFactorsRemoved mails the person a security notice that
	// staff removed removed (at least one) of their second factors at
	// the directory, after the extension removed them and audited it.
	// The actor is checked as for a change; there is no reason, as
	// nothing in the registry changes. It reports whether a notice went:
	// false with no error is an unconfirmed address.
	TellSecondFactorsRemoved(ctx context.Context, actor *Principal, userID uuid.UUID, removed int) (bool, error)
	// Erase erases the account as the person's own erasure does, the
	// directory's half and its retries included, with its published
	// public versions yanked; the person is mailed at a confirmed address.
	// An organization's last admin is refused (ErrLastAdmin, with the
	// organization in a LastAdminError). r is the request the extension
	// acts in.
	Erase(r *http.Request, actor *Principal, userID uuid.UUID, reason string) (AccountErasure, error)
	// ResendActivation sends an unactivated account a new activation link
	// under the person's own limits, and returns when another may go.
	// Refused for an activated account (ErrAlreadyActivated), one with no
	// address (ErrNoAddress), one not active (ErrNotActive), and inside
	// the limits (ActivationTooSoonError).
	ResendActivation(ctx context.Context, actor *Principal, userID uuid.UUID, reason string) (time.Time, error)
}

Accounts is the core's door for platform staff acting on a person's account from an extension's console: reading what the account is and holds, suspending, reinstating, signing out or erasing it, resending its activation link, and telling the person that their second factors were removed at the directory. The extension decides whom and when, and hands over the principal of the staff member acting; what each act does stays the core's, and the core checks the actor again itself: an active platform-staff account, and for a change a signed-in session acting on someone else. Each change takes a reason of at most 500 characters, is audited with the actor and the reason under the extension's name, and mails the person at a confirmed address.

type ActivationTooSoonError added in v0.6.1000

type ActivationTooSoonError = api.ActivationTooSoonError

LastAdminError and ActivationTooSoonError carry what a refusal of Accounts.Erase and Accounts.ResendActivation names.

type ActorKind

type ActorKind = audit.ActorKind

AuditEvent, AuditAction and ActorKind are the core's audit types.

type Admission

type Admission = registry.Admission

Admitter, Admission, Ticket and Refusal are the core's admission types.

type Admits

type Admits interface {
	Admitter() Admitter
}

The admission seam: an extension that implements Admits is asked once per submission, after every core gate and before anything is stored, and may refuse it. Optional: an extension without it admits everything, and the core build has none.

type AdmitsKnowledge

type AdmitsKnowledge interface {
	KnowledgeAdmitter() KnowledgeAdmitter
}

AdmitsKnowledge is the optional interface for an extension that admits, and may charge for, the scan an upload of a knowledge pack's tree queues (PUT …/knowledge/packs/{id}/tree, an account's or an organization's). AI Review is 1 credit an operation; the core charges nothing. It is asked after the core has read the tree and checked it against the owner's allocation, and before anything is stored; a refusal is answered in its own status and words, and a ticket is voided when the core then stores nothing. A ticket whose tree the core stored is recorded in the core's admitted_stores table (kind "knowledge") in the transaction that stores it, so a ticket with no row stored nothing even where its void failed or never ran. An upload of the tree the pack already holds queues no scan and is never asked about, nor is a pack an extension builds and stores through Knowledge.

type AdmitsModelInput

type AdmitsModelInput interface {
	ModelInputCallers() ModelInputCallers
}

AdmitsModelInput is the optional interface for an extension that admits hosted jobs to the model-input routes: AI Review of text a model is about to read, and web search brokered by the registry. A sandbox host presents the credential the extension minted for one job in X-Agentry-Job-Token; the core asks AdmitModelInput which job it names, and whether the call fits the job (a draft past its searches is refused), then records what the call spent with RecordModelInput. The use is a count for the record, never a price: AI Review is 1 credit an operation, however many scans it makes. Without it only platform staff reach the routes.

type AdmitsVoice

type AdmitsVoice interface {
	VoiceAdmitter() VoiceAdmitter
}

AdmitsVoice is the optional interface for an extension that admits, and may charge for, the review of a Writing Voice a route asks for: an edit saved on the web, a client's upload, a Restore of a version reviewed under another question set. AI Review is 1 credit an operation; the core charges nothing. A refusal is answered in its own status and words before anything is stored, and a ticket is voided when nothing was. A ticket whose version the core stored is recorded in the core's admitted_stores table (kind "voice") in the transaction that stores it, so a ticket with no row stored nothing even where its void failed or never ran. A Voice Writer run In Agentry puts its output through Voice.Propose, whose review is inside the build's price and is not admitted here.

type Admitter

type Admitter = registry.Admitter

Admitter, Admission, Ticket and Refusal are the core's admission types.

type AgentOrigin

type AgentOrigin struct {
	AgentID       uuid.UUID
	NamespaceID   uuid.UUID
	NamespaceKind NamespaceKind
}

AgentOrigin is a fork's origin as the seams name it: ids, never a path, and the namespace's kind so an extension can tell a person's from an organization's.

type AgentRef

type AgentRef struct {
	ID            uuid.UUID
	NamespaceID   uuid.UUID
	NamespaceKind NamespaceKind
	Public        bool
	// ForkedFrom is the origin of a fork, nil otherwise: the agent it
	// was forked from and that agent's namespace, its publisher, for
	// the earnings a fork's runs owe the origin. A fork is private, so
	// Public is false on every agent that has one.
	ForkedFrom *AgentOrigin
}

AgentRef is what the core says of an agent a principal may read: its id, the owning namespace's id and kind (NamespaceUser or NamespaceOrg — an organization's, for an organization's agent), and whether it is public. Readable says nothing of what else the caller may do with it: an agent of an organization in its decommission hold reads and is not written.

type Agents

type Agents interface {
	// Readable reports whether p may read the agent at namespace/name,
	// and what the core knows of it when they may. An agent that does not
	// exist and one p may not read are the same false with no error: the
	// seam gives no way to tell a private agent's existence that the
	// core's routes would not give.
	Readable(ctx context.Context, p *Principal, namespace, name string) (AgentRef, bool, error)
	// Maintainable reports whether p may maintain the agent at
	// namespace/name as the core's own routes decide it: the maintain
	// role over the namespace or a grant, a personal access token's
	// org:admin, and the owning organization's gate for a write (an
	// organization in its decommission hold reads and is not
	// maintained). An agent that does not exist, one p may not read,
	// one p reads and may not maintain, and one the gate holds are the
	// same false with no error.
	Maintainable(ctx context.Context, p *Principal, namespace, name string) (AgentRef, bool, error)
	// Publishable reports whether p may add a version to the agent at
	// namespace/name as the core's own routes decide it: the publish
	// role over the namespace or a grant, a personal access token's
	// agent:publish, and the owning organization's gate for a write.
	// The publish role ranks above maintain, so a session caller who
	// may publish also maintains; a token may publish without
	// org:admin, as the desktop's and the CLI's sign-in grant does.
	// Absent, unreadable, not publishable and held by the gate are one
	// false with no error, as Maintainable's are.
	Publishable(ctx context.Context, p *Principal, namespace, name string) (AgentRef, bool, error)
}

Agents answers whether a principal may read an agent the way the core's own routes decide it — the effective role over the namespace and the grants, a personal access token's agent:read, the owning organization's state — so an extension that names a release (a hosted run of it, say) admits exactly whom the core would and mirrors none of the rule in SQL.

type Allowance deprecated

type Allowance = entitlements.Cap

Allowance is the old name of Cap: kept so an extension built against it still compiles until it adopts Cap.

Deprecated: use Cap. It goes with the next breaking change to this package.

type AuditAction

type AuditAction = audit.Action

AuditEvent, AuditAction and ActorKind are the core's audit types.

type AuditEvent

type AuditEvent = audit.Event

AuditEvent, AuditAction and ActorKind are the core's audit types.

type AuditWriter

type AuditWriter interface {
	Write(ctx context.Context, e AuditEvent) error
	WriteIn(ctx context.Context, tx pgx.Tx, e AuditEvent) error
}

AuditWriter writes one audit event; see Deps. Write lands it in a transaction of its own; WriteIn joins the caller's, so a mutation and its audit row commit or roll back together, as the core's own do.

type Audits

type Audits interface {
	AuditActions() []AuditAction
}

Audits is the optional interface for an extension that writes audit events of its own: the actions it names are added to the catalog at start-up under the extension's own name, "<name>.<verb>", so a Deps.Audit write of any of them is accepted.

type Binds

type Binds interface {
	Bind(Deps)
}

Binds is the optional interface for an extension that needs Deps.

type BlobStore

type BlobStore = registry.BlobStore

BlobStore is the core's object store: put (write-once per key, so an extension keys its objects uniquely), get, exists, delete.

type Callbacks

type Callbacks = api.ExtensionCallbacks

Callbacks is an extension's callback mount.

type Cap

type Cap = entitlements.Cap

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type Deps

type Deps struct {
	DB    *pgxpool.Pool
	Log   *slog.Logger
	Audit AuditWriter
	// Blobs is the deployment's object storage — the archive store the
	// core runs on (a local directory or S3) — for an extension to keep
	// its own objects under its own key prefix (a hosted run's inputs,
	// outputs and receipts). nil when the server runs without a
	// database, as DB is.
	Blobs BlobStore
	// Entitlements is the resolver the server uses with no extension —
	// the deployment's configured limits — for an extension's own
	// resolver to embed and answer Features over.
	Entitlements Resolver
	// Orgs is the core's organization store as an extension may act on
	// it. nil when the server runs without a database.
	Orgs Orgs
	// OrgGate is the core's organization-state gate as an extension may
	// ask it: whether an organization is there to be read or acted on.
	// A route that names an organization asks it before it answers, so a
	// suspended or erased organization is absent to an extension as it is
	// to the core's own routes. Principal.OrgRoles is a person's
	// memberships and says nothing of the organization's state. nil when
	// the server runs without a database.
	OrgGate OrgGate
	// Agents is the core's read of an agent as an extension may ask it.
	// nil when the server runs without a database.
	Agents Agents
	// Versions is the core's read of one version of an agent: its status
	// and the advisories that name it. nil when the server runs without a
	// database.
	Versions Versions
	// Principals loads the principal the core would hold for a user,
	// for asking Agents about someone the extension holds by id rather
	// than by a live request. nil when the server runs without a
	// database.
	Principals Principals
	// ScheduleCredentials mints the credential a schedule's fire starts
	// a run with, its owner's narrow token in all but name. nil when
	// the server runs without a database.
	ScheduleCredentials ScheduleCredentials
	// Notifier carries a message an extension composed to a person,
	// under the core's rules and through the core's transport. nil when
	// the server runs without a database, as DB is.
	Notifier Notifier
	// Webhooks delivers an event to one of an organization's webhook
	// endpoints through the core's transport. nil when the server runs
	// without a database, as DB is.
	Webhooks Webhooks
	// Knowledge is the core's knowledge store. nil when the server runs
	// without a database, as DB is; while the store is off (no key
	// wrapper yet) its calls answer ErrKnowledgeUnconfigured.
	Knowledge Knowledge
	// Voice is the core's store of Writing Voices. nil when the server
	// runs without a database; while the store is off its calls answer
	// ErrVoiceUnconfigured.
	Voice Voice
	// ReportDesigns is the core's store of report design libraries. nil
	// when the server runs without a database.
	ReportDesigns ReportDesigns
	// ReportSettings is the default design as a version-2 document, for a
	// reader of version 2 alone. nil when the server runs without a database.
	ReportSettings ReportSettings
	// Meter is the server's meter under the extension's own scope: an
	// instrument created on it is scraped from /metrics beside the
	// core's, with the same resource labels, and leaves through OTLP
	// when that is configured. Never nil: a no-op meter when the server
	// runs without metrics or without a database.
	//
	// Name an instrument the way the core does (a CloudWatch-style
	// PascalCase name such as RunsHostedTokens, not a dotted one), and
	// begin it with the extension's own name so it cannot take one of the
	// core's: a series whose name the core already uses is dropped from
	// the scrape, and the core's is kept, but the OTLP export carries both
	// under their scopes, and a backend that ignores the scope (CloudWatch
	// EMF) would merge them. An attribute named like a resource label
	// (service.name, agentry.role, deployment.environment) is dropped from
	// the scrape. Label values must be bounded —
	// a run kind, a tier, an outcome — never a run id, a handle, a user or
	// anything a caller chooses, because every distinct value is a series
	// kept for the life of the process.
	Meter metric.Meter
	// Staff reads platform staff. nil when the server runs without a
	// database.
	Staff Staff
	// Members is the core's membership door for an extension that
	// provisions people on a directory's word. nil when the server runs
	// without a database.
	Members Members
	// Accounts is the core's door for platform staff acting on a person's
	// account through an extension's own console. nil when the server
	// runs without a database.
	Accounts Accounts
	// RememberedBrowsers mints and checks remembered browsers under the
	// core's rules, audited under the extension's name. nil when the
	// server runs without a database.
	RememberedBrowsers RememberedBrowsers
	// Sealer seals and opens small values under a key derived from the
	// server's sealing key (auth.sealingKey) for this extension alone
	// (authenticated encryption), for an extension that must keep a
	// personal value at rest in a row, as a queued erasure keeps the
	// address it erases. It opens none of the server's own sealed values
	// and none of another extension's. Never nil.
	Sealer Sealer
	// ErasedAddressKey is an address's key as RemembersErasedAddresses
	// is given it: the address normalized (lowercase, trimmed, without a
	// +tag, and for Gmail without the local part's dots, on gmail.com),
	// then keyed with HMAC-SHA256 under a key derived from the server's
	// sealing key for this purpose alone, hex. Every form of one mailbox
	// has one key, and it cannot be turned back into the address without
	// the sealing key. Never nil.
	ErasedAddressKey func(email string) string
	// BaseURL is the deployment's public origin, the address the core's
	// own links are built on (config baseURL, or AGENTRY_BASE_URL over
	// it), without a trailing slash: for an extension that must name an
	// address of its own to a third party, such as an OAuth callback.
	// Empty when the deployment names none.
	BaseURL string
	// ManagedSettings signs organizations' managed settings. It is nil in
	// a process that holds no signing key (the api and git roles) or knows
	// no base URL: sign in a job the worker runs.
	ManagedSettings ManagedSettingsSigner
}

Deps is what the core hands an extension at start-up, once per process, before its routes mount and its jobs register. DB is the pool the core uses, under the core's own database role: the convention — not yet enforced by a role or a grant — is that an extension writes only its own schema (ent_<name>) and reads core tables, never alters them; the extension's own seam test is where that is proven. Log is tagged with the extension's name. Audit writes the extension's events through the core's writer (the month partition, the archive stream, the refusal of an unregistered action); the event's actor kind, IP and user agent are the extension's to fill, since no request built it. DB is nil when the server runs without a database (limited dev mode).

type Directory

type Directory = api.Directory

Directory and the types it speaks are the core's directory port.

type DirectoryAccount

type DirectoryAccount = api.DirectoryAccount

Directory and the types it speaks are the core's directory port.

type DirectoryDevice

type DirectoryDevice = api.DirectoryDevice

Directory and the types it speaks are the core's directory port.

type DirectoryErasure

type DirectoryErasure = api.DirectoryErasure

DirectoryErasure is the optional interface for an extension's Directory that carries out the directory half of an erasure itself, retries included (api.DirectoryErasure): the core calls EraseErased once after the registry's erasure commits, in place of its own attempt and retry job, and reports the outcome it returns on the erasure's response.

type DirectoryLink = api.DirectoryLink

Directory and the types it speaks are the core's directory port.

type DirectoryLookup

type DirectoryLookup = api.DirectoryLookup

Directory and the types it speaks are the core's directory port.

type DirectorySignInFacts

type DirectorySignInFacts = api.DirectorySignInFacts

Directory and the types it speaks are the core's directory port.

type DirectorySource

type DirectorySource = api.DirectorySource

Directory and the types it speaks are the core's directory port.

type DraftClaim

type DraftClaim = scan.DraftClaim

DraftProvenance and DraftClaim are the seam's types: the question carries the run, the account, the agent, the baseline and the proof, and never a tier or a balance.

type DraftProvenance

type DraftProvenance = scan.DraftProvenance

DraftProvenance and DraftClaim are the seam's types: the question carries the run, the account, the agent, the baseline and the proof, and never a tier or a balance.

type ErasedAccount

type ErasedAccount = api.ErasedAccount

ErasedAccount is what EraseErased is told of the erased account.

type ErasesAccounts

type ErasesAccounts interface {
	EraseAccount(ctx context.Context, tx ErasureTx, userID uuid.UUID, kind AccountErasureKind) (int64, error)
}

ErasesAccounts is the optional interface for an extension that keeps rows about a person which must go with the person's account: the core calls EraseAccount inside the transaction of POST /user/delete (kind AccountErased) and of POST /user/clear-data (kind AccountDataCleared), after its own steps and before its audit event, so the extension's delete commits or rolls back with the core's. tx carries statements only: the core ends the transaction. The extension writes only its own schema through it, and is quick: the request waits on it. The count it returns is recorded in the user.delete or user.data_clear event's detail under the extension's name. An error fails the erasure or the clear — the account is not erased, the caller gets a 500 — so the extension's rows never outlive an erased account through a failed delete of its own.

Hooks.Event hears user.data_cleared after the commit, best-effort; this is for what may not wait or fail on its own.

type ErasureTx

type ErasureTx = api.ErasureTx

ErasureTx is the core's erasure transaction as an eraser may use it: Exec, Query and QueryRow, never Commit or Rollback.

type Event

type Event = api.Event

Event is one committed event the core fans out (api.Event): the webhook kinds (version.published, agent.quarantined, org.member_added, …) with the owning org, plus user.registered, user.email_verified (the account's address was confirmed, once, by its activation link or an invitation at an organization's domain; an account created verified hears only user.registered, with emailVerified true), user.data_cleared (clear what the extension holds for that user), account.erased, staff.changed and org.created.

type Extension

type Extension interface {
	// Name is the extension's short id (lower-case letters, digits, dashes):
	// its routes live under /api/v1/x/<name>/, its migrations in the schema
	// ent_<name>, and GET /meta lists it under `extensions`.
	Name() string
	// Routes registers the extension's handlers on a mux rooted at
	// /api/v1/x/<name>/ (patterns are relative: "GET /status"). The server
	// has already resolved the caller — PAT or session, CSRF on mutations,
	// the per-class rate limits — so a handler reads it with Principal.
	Routes(mux *http.ServeMux)
	// Migrations are goose SQL migrations applied after the core's, under
	// the extension's own version table (ent_<name>_goose_version). The SQL
	// owns its schema (CREATE SCHEMA IF NOT EXISTS ent_<name>); nil = none.
	Migrations() fs.FS
	// Entitlements replaces the core's config-based resolver; nil keeps it.
	Entitlements() Resolver
	// Hooks receive the events the core commits (see Event); zero = none.
	Hooks() Hooks
	// Jobs are async handlers the worker registers on its queue.
	Jobs() []Job
}

Extension is what an extended build adds. Every method may return the zero value: an extension that only has routes returns nil migrations, a nil resolver, empty hooks and no jobs.

type Features

type Features = entitlements.Features

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type HearsSignIn

type HearsSignIn interface {
	SignedIn(ctx context.Context, in SignIn)
}

HearsSignIn is the optional interface for an extension that hears every sign-in through an individual provider that the callback gives a session, with every claim of the ID token, once the account is resolved and before the session is issued: a cookie it sets rides the session's response, SignIn.RememberBrowser mints a remembered browser from this sign-in's own evidence, and SignIn.AssertSSO says the sign-in came through an organization's own single sign-on, so that the session satisfies the organization's enforced SSO. It cannot refuse the sign-in, and it runs in the callback, so it is quick.

type Hooks

type Hooks struct {
	Event func(ctx context.Context, ev Event)
}

Hooks are called after the core has committed the change; they are best-effort and must not block — an extension that needs durability enqueues a Job from the hook.

type Job

type Job struct {
	Kind    string
	Queue   string
	Handler queue.Handler
	Every   time.Duration
}

Job is a queue handler registered under Kind. Queue names the queue it is claimed from: "core" unless the work is untrusted content ("sandbox") or must run in the api role (QueueAPI). A positive Every makes the role that drains the queue enqueue Kind on that period, and once at start-up, the way the core's own watchdog and sweep run. Every replica enqueues on its own clock and the queue's claim runs each row once, so the handler must be idempotent — a cycle closer that finds nothing to close does nothing.

type KeyOwner

type KeyOwner = knowledge.Owner

KeyWrapper, KeyOwner and WrappedKey are the knowledge store's key types.

type KeyWrapper

type KeyWrapper = knowledge.KeyWrapper

KeyWrapper, KeyOwner and WrappedKey are the knowledge store's key types.

type Knowledge

type Knowledge interface {
	// Create makes an empty pack named name for owner, under a data key
	// the core makes and wraps for owner. ErrKnowledgeName for a name
	// that is not a pack's, ErrKnowledgeNameTaken for one owner already
	// uses.
	Create(ctx context.Context, owner KeyOwner, name string) (KnowledgePack, error)
	// Pack reads one of owner's packs; ErrKnowledgeNotFound for another
	// owner's and for none, one answer.
	Pack(ctx context.Context, owner KeyOwner, id uuid.UUID) (KnowledgePack, error)
	// Tree is one of owner's packs' tree decrypted, as the canonical tar
	// whose SHA-256 is the pack's digest: ErrKnowledgeScanning while it
	// is scanned, ErrKnowledgeNotFound for an empty pack. It is plaintext
	// in memory; the caller keeps it no longer than it must.
	Tree(ctx context.Context, owner KeyOwner, id uuid.UUID) (KnowledgePack, []byte, error)
	// Replace makes files the tree of one of owner's packs if the pack
	// still holds the tree whose digest is from ("" for an empty pack),
	// else ErrKnowledgeChanged with nothing stored. A tree past the
	// pool's cap is a *KnowledgeAllocationError, one that is not a pack's
	// ErrKnowledgeTree or ErrKnowledgeTooLarge. A tree the pack already
	// holds is not stored again, changed false, whatever from is, so a
	// replace retried after it landed is not a conflict.
	Replace(ctx context.Context, owner KeyOwner, id uuid.UUID, from string, files []KnowledgeFile) (pack KnowledgePack, changed bool, err error)
	// Usage is owner's meter: what counts against its allocation and the
	// cap (0 is none).
	Usage(ctx context.Context, owner KeyOwner) (KnowledgeUsage, error)
}

Knowledge is the core's knowledge store as an extension may act on it: the hosted build of the built-in Creator makes a pack, stages its tree for the sandbox host, and puts back the tree the build made. The data key stays in the core: an extension hands over plaintext files and reads metadata, and a tree it puts back is sealed under the pack's own key and stored through the same path as an upload through the routes: opened and checked, counted against its pool under the pool's lock, the tree it replaces deleted, its scan queued. Every call answers ErrKnowledgeUnconfigured while the store is off. Deps.Knowledge is nil without a database.

type KnowledgeAdmission

type KnowledgeAdmission = api.KnowledgeAdmission

KnowledgeAdmitter and KnowledgeAdmission are the knowledge upload's admission types.

type KnowledgeAdmitter

type KnowledgeAdmitter = api.KnowledgeAdmitter

KnowledgeAdmitter and KnowledgeAdmission are the knowledge upload's admission types.

type KnowledgeAllocationError

type KnowledgeAllocationError = knowledge.AllocationError

KnowledgePack, KnowledgeFile, KnowledgeUsage and KnowledgeAllocationError are the knowledge store's types as the seam speaks them.

type KnowledgeFile

type KnowledgeFile = scan.PackFile

KnowledgePack, KnowledgeFile, KnowledgeUsage and KnowledgeAllocationError are the knowledge store's types as the seam speaks them.

type KnowledgePack

type KnowledgePack = knowledge.Info

KnowledgePack, KnowledgeFile, KnowledgeUsage and KnowledgeAllocationError are the knowledge store's types as the seam speaks them.

type KnowledgePool

type KnowledgePool = knowledge.Pool

PoolsKnowledge is the knowledge store's allocation seam: an extension's resolver that also implements it names the KnowledgePool an owner's packs draw on — the lock every upload into it is reserved under, the owners it counts, and its cap — as a paid organization pools its seats across its members. Every owner a pool lists must be answered with that same pool.

type KnowledgeState

type KnowledgeState = knowledge.State

KnowledgePack, KnowledgeFile, KnowledgeUsage and KnowledgeAllocationError are the knowledge store's types as the seam speaks them.

type KnowledgeUsage

type KnowledgeUsage = knowledge.Usage

KnowledgePack, KnowledgeFile, KnowledgeUsage and KnowledgeAllocationError are the knowledge store's types as the seam speaks them.

type LastAdminError added in v0.6.1000

type LastAdminError = api.LastAdminError

LastAdminError and ActivationTooSoonError carry what a refusal of Accounts.Erase and Accounts.ResendActivation names.

type Limits

type Limits = entitlements.Limits

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type ManagedSettingsEnvelope added in v0.7.9

type ManagedSettingsEnvelope = managedsettings.Envelope

ManagedSettingsEnvelope is a signed managed settings document.

type ManagedSettingsSigner added in v0.7.9

type ManagedSettingsSigner = api.ManagedSettingsSigner

ManagedSettingsSigner signs an organization's managed settings: it validates them against the catalogue, binds them to the registry and the organization, and signs them with the registry's signing key.

type ManagesDirectory

type ManagesDirectory interface {
	Directory() Directory
}

ManagesDirectory is the optional interface for an extension that is the deployment's directory: the service that holds people's sign-in accounts. Its Directory is what the registry asks of a directory (api.Directory): erasure, and the superseded-account check. The rules stay the core's, the records the directory's. One extension at most; a nil Directory leaves the deployment without one. The directory's own sign-in work (its claims, remembered browsers, the checks its flows make, a staff mirror) is the extension's, through HearsSignIn, ReceivesCallbacks and EventStaffChanged.

type ManagesSettings added in v0.7.9

type ManagesSettings interface {
	ManagedSettings(ctx context.Context, user uuid.UUID) (*ManagedSettingsEnvelope, error)
}

ManagesSettings is the optional interface for an extension that keeps the managed settings an organization's admins set for its members, which GET /user/managed-settings serves. ManagedSettings returns the envelope signed for the person's organization's current version, or nil when none apply to them; it reads membership at the call. The extension stores what Deps.ManagedSettings signed (in the role that holds the signing key, typically a worker job run when an admin saves). The core checks each envelope against the keys the registry advertises before it serves it. A deployment has one such extension: a second panics at start-up.

type Members

type Members interface {
	// Provision makes the person a pending member of orgID: the account at
	// their address, or a new one with the address taken as verified on
	// the extension's word, so name only addresses the organization's
	// identity provider may vouch for. An existing membership, pending or
	// active, is left as it is. ErrOrgNotProvisionable for an organization
	// that is unknown, suspended or being decommissioned;
	// ErrAddressUnproven when the account at the address has not proved
	// it; ErrAccountSuspended when that account is suspended;
	// ErrStaffOrgDomain for an address the staff organization does not
	// admit.
	Provision(ctx context.Context, orgID uuid.UUID, p ProvisionedMember) (userID uuid.UUID, err error)
	// Deprovision takes userID's membership of orgID away and revokes
	// their org-bound tokens for orgID, every session and every
	// remembered browser, in one transaction, audited. The organization's
	// last admin keeps the membership and those credentials are revoked
	// all the same; kept says so.
	// Idempotent.
	Deprovision(ctx context.Context, orgID, userID uuid.UUID) (kept bool, err error)
}

Members is the core's membership door for an extension that learns from a directory whom an organization's identity provider provisioned and deprovisioned. The extension decides whom to name; what provisioning and deprovisioning do stays the core's: a provisioned person is only ever a pending member, whom an admin approves (seats count then), and a deprovisioned one loses the membership and every live credential at once.

type ModelInputCall

type ModelInputCall = api.ModelInputCall

ModelInputCallers, ModelInputCall, ModelInputUse and ModelInputOp are the model-input routes' admission types.

type ModelInputCallers

type ModelInputCallers = api.ModelInputCallers

ModelInputCallers, ModelInputCall, ModelInputUse and ModelInputOp are the model-input routes' admission types.

type ModelInputOp

type ModelInputOp = api.ModelInputOp

ModelInputCallers, ModelInputCall, ModelInputUse and ModelInputOp are the model-input routes' admission types.

type ModelInputUse

type ModelInputUse = api.ModelInputUse

ModelInputCallers, ModelInputCall, ModelInputUse and ModelInputOp are the model-input routes' admission types.

type NamespaceKind

type NamespaceKind = entitlements.NamespaceKind

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type Notifier

type Notifier interface {
	// Send delivers subject and text to the person, if the core's rules
	// allow it. It reports whether the message went: false with no error
	// is a suppression — an unverified address, or the kind switched off
	// — which is not the extension's failure and not a state it must
	// react to. An error is a delivery failure the extension may retry.
	// A kind the core does not know is refused: an extension may not
	// send as a class it was not given.
	Send(ctx context.Context, userID uuid.UUID, kind NotifyKind, subject, text string) (bool, error)
	// OrgAdmins names the active administrators of an organization, so
	// a message about the organization's subscription reaches the people
	// who manage it. Pending administrators are not among them: they hold
	// nothing of the organization yet.
	OrgAdmins(ctx context.Context, orgID uuid.UUID) ([]uuid.UUID, error)
}

Notifier lets an extension tell a person something by mail without owning a transport, an address book or the rule about who may be written to. The core keeps all three: the address must be verified (nothing is ever sent to an unverified one) and the person's preference for the message's kind must be on. An extension composes the words; the core decides whether they go and frames them with the registry's name and the settings link. An extension's own copy therefore stays outside this repository, and this repository's rule about addresses cannot be bypassed by an extension that holds one.

type NotifyKind

type NotifyKind string

NotifyKind names the class a message is sent as, which is the switch a person turns off. Only the kinds the core lists here may be used: a message about billing is what the person's billing switch governs, and a dependency alert routed to them is what their dependency-alert switch governs, wherever it came from; a notice about one of their schedules is what their schedules switch governs; a notice that a bug report they filed is fixed is what their bug-report switch governs; and a hosted run's outcome is what their two run switches govern, one for a failure and one for a completion.

const (
	// NotifyBilling is the hosted build's billing mail: a checkout
	// confirmed, a payment failed, an organization restricted, seats
	// reached, "your organization covers you".
	NotifyBilling NotifyKind = "billing"
	// NotifyDependencyAlert is a dependency alert an extension routes
	// to the person an organization chose for it: the same news the
	// core mails the author, under the same switch.
	NotifyDependencyAlert NotifyKind = "dependency_alert"
	// NotifySchedule is the hosted build's schedule mail: a scheduled
	// run in Agentry failed, or the schedule paused (three refusals in
	// a row, an entitlement that lapsed). Never a success.
	NotifySchedule NotifyKind = "schedule"
	// NotifyBugReport is the hosted build's bug-report mail: platform
	// staff marked a bug report the person filed complete, "Reported
	// bug fixed", quoting the report and any note staff added. Never
	// sent for a report closed without a fix.
	NotifyBugReport NotifyKind = "bug_report"
	// NotifyRunFailure is the hosted build's mail for a run that failed
	// after it started or was refused by the queue: a run, a draft, a
	// knowledge build or a scheduled fire. The person's switch for it is
	// off until they turn it on.
	NotifyRunFailure NotifyKind = "run_failure"
	// NotifyRunFinished is the hosted build's mail for a run that
	// completed. Its switch is off until the person turns it on.
	NotifyRunFinished NotifyKind = "run_finished"
)

type Options

type Options struct {
	// Queues are the queues a worker drains (core, sandbox); nil means both.
	Queues []string
}

Options are the per-invocation choices a role takes beside its config.

type OrgGate

type OrgGate interface {
	// Readable reports whether the organization is there to be read: it is
	// active or in its decommission hold. A suspended organization, an
	// erased one and one that does not exist are the same false with no
	// error, and a route answers each as not found, as the core's do. An
	// error is a fault to answer as one, never as an absence.
	Readable(ctx context.Context, orgID uuid.UUID) (bool, error)
	// Writable reports whether an act that changes the organization or
	// spends what it holds is permitted: only an active organization
	// permits it. One in its decommission hold is readable and not
	// writable; a suspended, erased or unknown one is neither.
	Writable(ctx context.Context, orgID uuid.UUID) (bool, error)
}

OrgGate answers for an organization's state the way the core's own routes do, so that an extension mirrors none of the rule in SQL. The core enforces an organization's state in one place (registry.OrgGate) for its API, listings, SCIM and git; an extension's routes never pass through the core's authorization, so they ask here. An organization is active, suspended by platform staff, in its decommission hold (read-only for the configured period) or erased.

type Orgs

type Orgs interface {
	// Activate marks the organization activated. Idempotent: it reports
	// whether this call did it, and an unknown org is false with no error.
	Activate(ctx context.Context, orgID uuid.UUID) (bool, error)
	// Decommission starts the organization's decommission hold the way
	// an admin's request does: read-only for the configured hold, then
	// erased, its handle and domain released; the core fires
	// org.decommissioning now and org.decommissioned after the erasure.
	// The hosted product's pending-payment sweep calls it for an
	// organization nobody paid for. Idempotent: it reports whether this
	// call did it; an organization that is not active, or unknown, is
	// false with no error.
	Decommission(ctx context.Context, orgID uuid.UUID, reason string) (bool, error)
}

Orgs holds the acts on an organization the core owns and an extension triggers. Where an admission extension runs, an organization is created awaiting activation and its creator may not create another until it is activated; the extension that owns the org's standing activates it when the subscription starts.

type OwnTokens added in v0.6.1000

type OwnTokens struct {
	// Prefix starts every such token: "agy", one to four lowercase letters
	// and an underscore, none of the core's own (agy_, agys_, agyi_, agyv_,
	// agyd_) and none another extension claims. A wrong one panics at
	// start-up.
	Prefix string
	// Resolve says whose a token is, or false for one the extension does
	// not know (never issued, expired, ended). An error answers 500.
	Resolve func(ctx context.Context, token string) (userID uuid.UUID, ok bool, err error)
}

OwnTokens is an extension's bearer token kind.

type PoolsKnowledge

type PoolsKnowledge = knowledge.Pools

PoolsKnowledge is the knowledge store's allocation seam: an extension's resolver that also implements it names the KnowledgePool an owner's packs draw on — the lock every upload into it is reserved under, the owners it counts, and its cap — as a paid organization pools its seats across its members. Every owner a pool lists must be answered with that same pool.

type Principal

type Principal = auth.Principal

Principal is the resolved caller; Principal(ctx) reads it in a route.

func PrincipalFromContext

func PrincipalFromContext(ctx context.Context) *Principal

Principal returns the caller the server resolved for this request: Anonymous when none.

type Principals

type Principals interface {
	// ForUser is the principal for userID with no credential: the
	// account's standing and its organization roles as they are now, as
	// a session would carry them, with Via "user", no scopes and no
	// session. Put it to Agents: Readable, Maintainable and Publishable
	// answer it on the role alone, which never exceeds what the person's
	// own session would be answered, so a role kept since an earlier check
	// is answered as before and a role taken away is gone. An account that
	// does not exist, or is not active (suspended, deleted), is false with
	// no error. It is not a credential: auth.Check and ScopeAllows refuse
	// it, as does every route that needs a session, and an extension must
	// never act for the user with it beyond asking. It satisfies no
	// organization's enforced SSO, but the agent seams do not ask for SSO
	// (only git does), so this is no SSO gate. Its answer is the role
	// alone, without the scopes of the credential an earlier request
	// carried: ask it only to re-check what that request already checked.
	ForUser(ctx context.Context, userID uuid.UUID) (*Principal, bool, error)
}

Principals answers who a user is now, as the core would resolve them, for an extension that must re-ask a role later than the request that gave it one: a hosted revision's release fetch asks again whether the run's owner may still maintain or publish to the QuickAgent. The extension rebuilds none of the rule (memberships, roles, the account's standing): the core loads them.

type ProvesDrafts

type ProvesDrafts interface {
	DraftProvenance() DraftProvenance
}

ProvesDrafts is the optional interface for an extension that records hosted drafts and can answer whether a version is one of them. An upload may claim the draft it was published from; the scan computes the proof of the submitted files (pkg/draftproof) and asks DraftProvenance whether the submitter ran that draft against the agent's S9 baseline and recorded that proof. A yes makes the version a drafter-revision, which S9 reads with the benefit of the doubt; the client is never believed. Without it no version is one.

type ProvisionedMember

type ProvisionedMember = api.ProvisionedMember

ProvisionedMember is a person an organization's identity provider provisioned: their address, the name the provider calls them by (a seed for a new account's handle) and a display name.

type QueueJob

type QueueJob = queue.Job

QueueJob is the job envelope a Handler receives.

type ReceivesCallbacks

type ReceivesCallbacks interface {
	Callbacks() Callbacks
}

ReceivesCallbacks is the optional interface for an extension that serves calls from a service of its own, such as its directory's sign-in flow asking whether a browser is remembered. They are mounted under /internal/x/<name>/, outside /api/, where no edge shipped with the registry routes, and the core holds the gate (api.ExtensionCallbacks): the secret as a bearer token, 404 to a request that came through a proxy or while the secret is unset, the declared rate class. A handler there has no Principal: its caller is infrastructure, not a person.

type Refusal

type Refusal = registry.Refusal

Admitter, Admission, Ticket and Refusal are the core's admission types.

type RememberedBrowsers

type RememberedBrowsers interface {
	// Use reports whether token is a live remembered browser of userID's,
	// recording the use first. An error means the store could not answer:
	// treat it as no.
	Use(r *http.Request, userID uuid.UUID, token string) (bool, error)
}

RememberedBrowsers is the core's remembered-browser credential as an extension may use it: a browser that answered the second factor at its directory may skip it there next time. One is minted only at a sign-in, by SignIn.RememberBrowser, from the verified token's own evidence (`amr` naming a second factor, `auth_time` minutes old), so no extension can mint one for an account on its own word. The core keeps the rules: stored only as its SHA-256, bound to one active account, an absolute lifetime, every use audited before it is granted.

type RemembersErasedAddresses added in v0.6.1000

type RemembersErasedAddresses interface {
	ErasedAddress(ctx context.Context, tx ErasureTx, userID uuid.UUID, addressKey string) error
}

RemembersErasedAddresses is the optional interface for an extension that must know an address again after its account is erased: a free allowance or a trial that erasing an account and signing up again would otherwise renew. The core calls ErasedAddress inside the transaction of POST /user/delete, before the extensions' erasers, with the erased account's address key (Deps.ErasedAddressKey of the address it held). It is never called for a data clear, which keeps the account. The address itself is never given: the extension keeps the key, and only for as long as it needs it, and compares a later account's key to it. tx is the erasure's, as an eraser's is; an error fails the erasure.

type ReportDesign added in v0.7.4

type ReportDesign struct {
	ID uuid.UUID
	// Default says a run takes this design when the person picks none.
	Default bool
	// Org is the handle of the organization whose house design this is,
	// read through ForMember; empty for a person's own design.
	Org string
	// Name is the design's name, which a run names a house design by.
	Name string
	// Document is the canonical theme document version 3 that
	// pkg/reportdesign validated (Parse it to read it), without its
	// images.
	Document []byte
	// DocumentWithAssets is Document with every image the design has:
	// its logo, cover image and custom cover. Hand it only to a reader
	// that draws them.
	DocumentWithAssets []byte
	// Version2 is the design's version-2 projection, a canonical
	// version-2 document that keeps its look, for a reader that reads
	// only version 2; without the logo.
	Version2 []byte
	// they have one, for a version-2 reader that draws logos.
	Version2WithLogo []byte
}

ReportDesign is one design of a person's library as an extension reads it: the document in each form a reader may take.

type ReportDesigns added in v0.7.4

type ReportDesigns interface {
	// Default is the person's default design, or nil when they have
	// none, which is not Plain: the reader decides what nothing means.
	Default(ctx context.Context, user uuid.UUID) (*ReportDesign, error)
	// ByID is one of the person's designs, or nil when the id is not one
	// of theirs.
	ByID(ctx context.Context, user, id uuid.UUID) (*ReportDesign, error)
	// ForMember is one of an organization's house designs, by the
	// organization's handle and the design's name (compared without
	// regard to case), for a run of the person's: nil when there is no
	// such organization, when the person is not an active member of it,
	// or when it has no design of that name. Membership is read at the
	// call, so a former member is refused the design at their next run
	// and goes on in their own default.
	ForMember(ctx context.Context, user uuid.UUID, org, name string) (*ReportDesign, error)
	// Create adds a design to the person's library from a document that
	// may carry its images, never as the default: the person picks it. An
	// invalid document is a *reportdesign.FieldError; a full library is
	// ErrReportDesignsFull.
	Create(ctx context.Context, user uuid.UUID, document []byte) (*ReportDesign, error)
}

ReportDesigns is the core's store of report design libraries, a person's own and an organization's house designs, as an extension reads it: the hosted runs read the design a run picked, or the account's default, and hand it to the sandbox host, whose CLI lays the run's PDFs out in it. Read-only but for Create, through which the hosted Report Designer saves what it made. Deps.ReportDesigns is nil without a database.

type ReportSettings

type ReportSettings interface {
	// Design is the version-2 projection of the person's default design,
	// or nil when they have none, which is not Plain.
	Design(ctx context.Context, user uuid.UUID) ([]byte, error)
	// design has one, for a reader that draws logos.
	DesignWithLogo(ctx context.Context, user uuid.UUID) ([]byte, error)
}

ReportSettings is the person's default design as a version-2 document, for a reader that reads only version 2; a reader of version 3 takes ReportDesigns. Deps.ReportSettings is nil without a database.

type Resolver

type Resolver = entitlements.Resolver

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type ScheduleCredentials

type ScheduleCredentials interface {
	// ForSchedule is the credential for one fire of the schedule
	// scheduleID that userID owns: the account's standing and roles as
	// they are now, as ForUser loads them, with Via "schedule",
	// ScheduleID set, and auth.ScheduleScopes as its scopes, so
	// ScopeAllows, auth.Check and the Agents seam read it as they read a
	// token minted with exactly those scopes. It carries no session, no
	// token, no SSO freshness and no platform-staff standing: a schedule
	// acts as its owner's narrow token would, never as their session. An
	// account that does not exist or is not active is false with no
	// error, so a schedule of a suspended account does not fire. A nil
	// scheduleID is an error: the credential must name what it is.
	//
	// What it reaches in the extension that holds it is that
	// extension's rule; the vault's is that a schedule sets no secret,
	// so a run it starts resolves kept secrets only. Mint one per fire
	// and keep none: the account's standing is read at the moment of
	// the fire, so an entitlement that lapsed is seen.
	ForSchedule(ctx context.Context, userID, scheduleID uuid.UUID) (*Principal, bool, error)
}

ScheduleCredentials mints the credential of a run a schedule starts on its owner's behalf, with no live request to carry one. Every hosted run is created from a principal the runs extension authorizes the way it authorizes a request, and a fire must go through that same create path, so the fire needs a principal that is a credential: ForUser's is not one, and must not become one. This is a separate seam from Principals, so an extension that only asks about people never holds the means to act for them.

type Scope

type Scope = auth.Scope

Scope is a PAT scope as the core spells it; those an extension may require are the hosted-run scopes, the knowledge scopes, for a route that writes into a person's knowledge through the Knowledge seam, the vault's secret:write and credits:session, for a credits session. A session carries no scopes and the account's full authority; a PAT carries what it was minted with, flat: no scope implies another.

type Sealer

type Sealer interface {
	Seal(plaintext []byte) ([]byte, error)
	Open(sealed []byte) ([]byte, error)
}

Sealer is the server's sealer as an extension uses it. Open refuses a value sealed under another key or changed since it was sealed.

type ServesCreditsSessions added in v0.7.0

type ServesCreditsSessions interface {
	CreditsSessionRoutes() []string
}

ServesCreditsSessions is the optional interface for an extension that opens, renews and ends credits sessions, the sessions a run pays for its model with from the account's credits. The routes are "METHOD /path" relative to the mount, with "{name}" wildcards allowed as whole segments ("POST /sessions/{id}/renew"). They are the only paths in the registry where a token carrying ScopeCreditsSession reaches a handler: the core refuses such a token everywhere else, its own routes, this extension's other routes and every other extension's included. The handler still requires the scope with ScopeAllows.

type SignIn

type SignIn = api.SignIn

SignIn is a sign-in as HearsSignIn hears it.

type Staff

type Staff interface {
	// Members lists every active account that is platform staff with a
	// verified address, by handle.
	Members(ctx context.Context) ([]StaffMember, error)
}

Staff is the read side of platform staff, which the registry alone decides (the staff organization's rule): for an extension that mirrors it somewhere else, on EventStaffChanged and on its own period.

type StaffMember

type StaffMember = api.StaffMember

StaffMember is one member of platform staff: account, handle, verified address (lower-cased).

type Subject

type Subject = entitlements.Subject

Resolver, Subject, Limits, Features and Cap are the core's entitlements types. A resolver an extension supplies usually wraps the core's (entitlements.NewConfigResolver) and answers Features by tier.

type TakesOwnTokens added in v0.6.1000

type TakesOwnTokens interface {
	OwnTokens() OwnTokens
}

TakesOwnTokens is an extension that mints bearer tokens of its own for its own routes: a credential narrower than a token of the account's, for a caller that can present nothing but `Authorization: Bearer`, such as a model client inside a run's container. The core accepts such a token under /api/v1/x/<name>/ alone and asks Resolve whose it is; the principal it becomes has Via "extension", the user's id, no scopes and no roles, so no route of the core's would admit it even if it reached one. On every other path, the core's routes and other extensions' mounts included, the token is "not recognized" (401).

type Ticket

type Ticket = registry.Ticket

Admitter, Admission, Ticket and Refusal are the core's admission types.

type Unthrottles

type Unthrottles interface {
	UnthrottledRoutes() []string
}

Unthrottles is the optional interface for an extension whose receiver of signed callbacks must never be refused by the anonymous rate class (a payment provider's webhook). The routes are "METHOD /path" relative to the mount, exact; each still passes the principal middleware and authorizes on its own signature.

type VersionAdvisory added in v0.6.1003

type VersionAdvisory struct {
	ID       uuid.UUID
	Severity string
	Summary  string
	// AffectedVersions is the range as the advisory states it.
	AffectedVersions string
	PublishedAt      time.Time
	// FixedIn is the lowest published version above this one, on its
	// channel, that the range leaves out; empty while none is published.
	FixedIn string
	// RangeUnreadable is true when the range is not a semver constraint
	// the core can read. Such an advisory is counted as naming every
	// version and names no fix.
	RangeUnreadable bool
}

VersionAdvisory is one advisory that names a version.

type VersionRef added in v0.6.1003

type VersionRef struct {
	// Agent is the agent as Agents.Readable says it.
	Agent AgentRef
	// Version is the version as the core stores it, without a leading v.
	Version string
	// Status is the version's lifecycle state: submitted, scanning,
	// needs_review, published, rejected, yanked, quarantined or blocked.
	// Only published runs; a yanked version stays pinnable with a warning.
	Status string
	// AgentQuarantine is the agent's own state beside its versions':
	// empty, quarantined or blocked. A blocked agent resolves to nothing.
	AgentQuarantine string
	// Advisories are the published advisories whose range names this
	// version, newest first.
	Advisories []VersionAdvisory
}

VersionRef is what Versions says of one version.

type Versions added in v0.6.1003

type Versions interface {
	// Version reports what the core knows of version of the agent at
	// namespace/name, answered to p as the core's own version route
	// answers a reader. An agent p may not read, an agent that does not
	// exist and a version that does not exist are the same false with no
	// error, as Agents.Readable's are.
	Version(ctx context.Context, p *Principal, namespace, name, version string) (VersionRef, bool, error)
}

Versions answers what the core knows of one version of an agent a principal may read: whether it is published, yanked, quarantined or still on its way through the pipeline, whether the agent itself is quarantined or blocked, and the advisories whose range names that version, each with the first published version that fixes it. An extension that pins a version (a schedule runs one version until its owner changes it) asks it to tell the owner that the pinned version can no longer run, or that a newer one fixes an advisory against it, without preparing a run to read the refusal.

type Voice

type Voice interface {
	// Live is a person's live version, the one a run attaches, its text
	// opened; ErrVoiceNotFound when they have none. A pending or
	// flagged version is never answered here.
	Live(ctx context.Context, user uuid.UUID) (*VoiceVersion, error)
	// State is a person's voice: the always-attach flag and every
	// version, texts opened, a pending or flagged one included, for a
	// Voice Writer run to improve or edit; ErrVoiceNotFound when they
	// have none. A run attaches what Live answers, never this.
	State(ctx context.Context, user uuid.UUID) (VoiceState, error)
	// Propose makes text a person's pending version from a Voice Writer
	// run In Agentry (source VoiceSourceBuild or VoiceSourceAIEdit) and
	// queues its review; it is live only once the review passes it. Text
	// that is not a voice is a *VoiceInvalidError or ErrVoiceTooLarge.
	Propose(ctx context.Context, user uuid.UUID, text []byte, source VoiceSource) (VoiceState, error)
}

Voice is the core's store of Writing Voices as an extension may act on it: the hosted Voice Writer reads the live voice it improves or edits and puts back the voice it wrote, and a hosted run reads the live voice it attaches. The data key stays in the core: an extension reads and hands over text. Every call answers ErrVoiceUnconfigured while the store is off. Deps.Voice is nil without a database.

type VoiceAdmission

type VoiceAdmission = api.VoiceAdmission

VoiceAdmitter and VoiceAdmission are the voice routes' admission types.

type VoiceAdmitter

type VoiceAdmitter = api.VoiceAdmitter

VoiceAdmitter and VoiceAdmission are the voice routes' admission types.

type VoiceInvalidError

type VoiceInvalidError = voice.InvalidError

VoiceVersion, VoiceState and VoiceSource are the voice store's types as the seam speaks them; VoiceInvalidError is Propose's answer for text that is not a voice, with the reason.

type VoiceSource

type VoiceSource = voice.Source

VoiceVersion, VoiceState and VoiceSource are the voice store's types as the seam speaks them; VoiceInvalidError is Propose's answer for text that is not a voice, with the reason.

type VoiceState

type VoiceState = voice.State

VoiceVersion, VoiceState and VoiceSource are the voice store's types as the seam speaks them; VoiceInvalidError is Propose's answer for text that is not a voice, with the reason.

type VoiceVersion

type VoiceVersion = voice.Version

VoiceVersion, VoiceState and VoiceSource are the voice store's types as the seam speaks them; VoiceInvalidError is Propose's answer for text that is not a voice, with the reason.

type WebhookEndpointRef

type WebhookEndpointRef = api.WebhookEndpointRef

WebhookEndpointRef is an endpoint as the seam describes it: its id, its URL, the events it subscribes to and whether it is active. No secret.

type Webhooks

type Webhooks interface {
	// Endpoints lists the organization's endpoints as an extension may
	// name one, active or not. An organization that does not exist has
	// none, not an error.
	Endpoints(ctx context.Context, orgID uuid.UUID) ([]WebhookEndpointRef, error)
	// Deliver records one delivery of event with data to the endpoint
	// and queues it, the way the core's own emit does for a subscribed
	// endpoint. It reports whether a delivery was recorded: false with
	// no error means the endpoint is not the organization's or is
	// switched off — a destination gone stale, which the extension may
	// report but cannot repair. An event outside the core's catalog is
	// refused: what a consumer is told to expect is the core's promise.
	Deliver(ctx context.Context, orgID, endpointID uuid.UUID, event string, data any) (bool, error)
}

Webhooks lets an extension deliver an event to one of an organization's webhook endpoints — a destination the organization named for the extension's purpose, not one chosen by its subscriptions — through the core's transport: the delivery ledger the endpoint's log reads, the signed request, the retries, the SSRF guard. The endpoint's secret and the transport stay the core's; an extension holds an endpoint by id.

type WrappedKey

type WrappedKey = knowledge.WrappedKey

KeyWrapper, KeyOwner and WrappedKey are the knowledge store's key types.

type WrapsKeys

type WrapsKeys interface {
	KeyWrapper() KeyWrapper
}

WrapsKeys is the optional interface for an extension that wraps the data keys of knowledge packs itself: the hosted build's wrapper seals each key to its owner's own certificate. The core's wrapper, the deployment's knowledge sealing key, is replaced and nothing else changes: the store, the routes, the scan and the erasure stay the core's. A nil KeyWrapper leaves the core's in place.

Jump to

Keyboard shortcuts

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