placement

package
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package placement is the leaf package behind local placement (0.9, OD-8 and OD-12): the placement request types, the capacity a runner advertises, the refusal vocabulary, the credential classification of every credential-bearing SandboxSpec and ProxyConfig field, and the credential delivery policy shape. Everything here is pure; store-backed facts are passed in by the callers.

Index

Constants

View Source 
const (
	ActionRunnerTokenCreate       = "runner.token.create"
	ActionRunnerTokenRevoke       = "runner.token.revoke"
	ActionRunnerEnrol             = "runner.enrol"
	ActionRunnerClaim             = "runner.claim"
	ActionRunnerRevoke            = "runner.revoke"
	ActionRunnerConnect           = "runner.connect"
	ActionRunnerDisconnect        = "runner.disconnect"
	ActionRunnerActionRequest     = "runner.action.request"
	ActionRunnerActionApply       = "runner.action.apply"
	ActionRunnerActionRefuse      = "runner.action.refuse"
	ActionRunnerPostureRecord     = "runner.posture.record"
	ActionRunnerResidentErase     = "runner.resident.erase"
	ActionCredentialDeliveryWrite = "credential.delivery.write"
	ActionSSHSyncTransfer         = "ssh.sync.transfer"
	ActionRunnersEnabledSet       = "runners.enabled.set"
	ActionRunnerInventoryHold     = "runner.inventory.hold"
	ActionRunnerUpdate            = "runner.update"
	ActionRunnerTrustWrite        = "runner.trust.write"
	// ActionRunnerRecoveryRequest: a revive queued recover_containment for a run its runner held contained.
	ActionRunnerRecoveryRequest = "runner.recovery.request"
)

Audit action names the runner lanes emit (design §12.2). The rows are added to docs/AUDIT-ACTIONS.md by the lane that first emits each one.

View Source 
const (
	StructSandboxSpec = "SandboxSpec"
	StructProxyConfig = "ProxyConfig"
	// StructGrantKind names grant kinds with no SandboxSpec field, minted
	// through the proxy's local mint route.
	StructGrantKind = "GrantKind"
)

The structs the table covers.

View Source 
const (
	ClassOAuthSubscription = "oauth_subscription"
	ClassAPIKey            = "api_key"
	ClassBedrockBearer     = "bedrock_bearer"
	ClassAWSSSOBearer      = "aws_sso_bearer"
	ClassAzureFoundryToken = "azure_foundry_token"
	ClassBedrockRoleCreds  = "bedrock_role_credentials"
	ClassEnvSecret         = "env_secret"
	ClassFileSecret        = "file_secret"
	ClassSSHKey            = "ssh_key"
	ClassGitPATBroker      = "git_pat_broker"
	ClassGitPATHelper      = "git_pat_helper"
	ClassGitHubToken       = "github_token"
	ClassADOMintedPAT      = "ado_minted_pat"
	ClassCloudSTS          = "cloud_sts"
)

Class keys of the delivery policy: the closed set of design §7.2.

Variables

View Source 
var AuditActions = []string{
	ActionRunnerTokenCreate, ActionRunnerTokenRevoke, ActionRunnerEnrol, ActionRunnerClaim, ActionRunnerRevoke,
	ActionRunnerConnect, ActionRunnerDisconnect, ActionRunnerActionRequest, ActionRunnerActionApply, ActionRunnerActionRefuse,
	ActionRunnerPostureRecord, ActionRunnerResidentErase, ActionCredentialDeliveryWrite,
	ActionSSHSyncTransfer, ActionRunnersEnabledSet, ActionRunnerInventoryHold, ActionRunnerUpdate,
	ActionRunnerTrustWrite, ActionRunnerRecoveryRequest,
}

AuditActions lists them all.

View Source 
var ErrInvalidPolicy = errors.New("placement: invalid credential delivery policy")

ErrInvalidPolicy marks a delivery policy a writer must refuse (a 400).

View Source 
var ErrInvalidRequest = errors.New("placement: invalid request")

ErrInvalidRequest marks a Request that is malformed on its face, before any eligibility is looked at.

View Source 
var Table = []Entry{}/* 102 elements not displayed */

Table is the one classification table. Create, dispatch and revive all read it; a field not named here fails TestDispatchPlanFieldsClassified.

Functions

func CredentialPaths 

func CredentialPaths(s runner.SandboxSpec) []string

CredentialPaths enumerates every present value of a field the table classifies as credential-bearing, plus grant eligibility (approval-gated grants are absent from Injection). Sorted keys make refusals stable.

func CredentialProxyField 

func CredentialProxyField(field string) bool

CredentialProxyField reports whether the table classifies a ProxyConfig field as credential-bearing: the only fields a runner fills a resident value into.

func DeliveryClasses 

func DeliveryClasses() []string

DeliveryClasses lists every class key, sorted.

func NestedUnclassified 

func NestedUnclassified() []string

NestedUnclassified checks types even when the current value is nil or empty.

func OrgComponentConfigKeys 

func OrgComponentConfigKeys(orgDefs []types.ComponentDefinition) []string

OrgComponentConfigKeys is the sorted set of environment variable names the config of org components (never a person's own) dispatches.

func PostureUnmet 

func PostureUnmet(req *PostureRequirement, p *types.RunnerPosture) string

PostureUnmet names the first field of req that p does not meet; "" when p meets it. A runner that never reported posture meets no requirement, and an os_min names every OS a runner may run: an unlisted OS does not meet it.

func ResidentGrantID 

func ResidentGrantID(v string) (uuid.UUID, bool)

ResidentGrantID reads a placeholder back; false when v is not one.

func ResidentPlaceholder 

func ResidentPlaceholder(grantID uuid.UUID) string

ResidentPlaceholder is what a dispatched spec carries in place of a runner_resident value: it names the grant, never the secret.

func RunnerRefPrefix 

func RunnerRefPrefix(runnerID string) string

RunnerRefPrefix prefixes every ref a runner returns, so ref routing never falls back to the sole substrate for one.

func RunnerSubstrateName 

func RunnerSubstrateName(runnerID string) string

RunnerSubstrateName is the name an Orchestrator registers a runner's substrate under, and the prefix of every ref it creates.

func SchemaUnclassified 

func SchemaUnclassified(t reflect.Type, path string, additional map[reflect.Type][]string, opaque map[string]string) []string

SchemaUnclassified shares the closed schema with private control-plane dispatch metadata. The additional entries are explicitly reviewed field manifests; nil marks an opaque scalar such as time.Time, never a parent exemption for future fields.

func StripOrgComponentConfig 

func StripOrgComponentConfig(env map[string]string, orgKeys []string) (kept map[string]string, dropped []string)

StripOrgComponentConfig returns env without the variables an org component's config set, and the names it left out, sorted. An org component's config is operator-authored and dispatched as plain Env, so nothing but its position says a value is not meant for a laptop; the laptop-bound copy of a spec loses it, as it loses every other operator-class value (design §6.3). env is not modified. Callers pass the keys from OrgComponentConfigKeys, and audit what was dropped as run.component_config.drop does.

func TrustClassesByRank added in v0.9.3 

func TrustClassesByRank() []types.RunnerTrustClass

TrustClassesByRank is the closed trust set, highest rank first.

func Unclassified 

func Unclassified() []string

Unclassified lists the exported fields of runner.SandboxSpec and runner.ProxyConfig, and the top-level fields of ProxyConfig.Policy, that the table does not name, as "Struct.Field" or "ProxyConfig.Policy.Field".

func ViaOrgGrant 

func ViaOrgGrant(origin CredentialOrigin, policy DeliveryPolicy, trust types.RunnerTrustClass) bool

ViaOrgGrant reports whether an org-held grant of origin is delivered via_org under policy on a runner of trust class trust: the same table rows and gate LocalEligibility applies to it.

func Writable 

func Writable(class string) bool

Writable reports whether a policy may configure the class.

Types

type Capacity 

type Capacity struct {
	CPUMillisMax int64 `json:"cpu_millis_max"`
	MemoryMiBMax int64 `json:"memory_mib_max"`
}

Capacity is what one local run may use on a runner, asserted by the runner.

func (Capacity) Fits 

func (c Capacity) Fits(cpuMillis, memoryMiB int64) bool

Fits reports whether a request for cpuMillis and memoryMiB is within the advertised capacity; a zero request means the driver's default and always fits.

type Class 

type Class string

Class is the credential class of a dispatched field (design §6.3). 

const (
	ClassOwn      Class = "own"      // the launching principal's own material
	ClassOperator Class = "operator" // the operator namespace, a shared component secret, or org network configuration
	ClassBrokered Class = "brokered" // minted by the org's broker from an org-held identity
	ClassPlatform Class = "platform" // minted for this run by the platform
	ClassExempt   Class = "exempt"   // not credential-bearing
	// ClassComposite marks a field that holds a classified struct of its own.
	ClassComposite Class = "composite"
)

type ClassPolicy 

type ClassPolicy struct {
	Mode           Mode                `json:"mode"`
	RequirePosture *PostureRequirement `json:"require_posture,omitempty"`
}

ClassPolicy is one class's configured mode.

type CredentialIntent 

type CredentialIntent struct {
	Field  string
	Origin CredentialOrigin
}

CredentialIntent records a resolved credential-producing configuration before mint. Its Field uses the same canonical paths as an actual SandboxSpec value.

type CredentialOrigin 

type CredentialOrigin struct {
	Class        Class
	Delivery     string
	GrantKind    types.GrantKind
	Stored       bool
	OwnNamespace bool
	OwnerOnly    bool
	// ResidentOptIn is an Azure DevOps connection's admin opt-in to
	// runner_resident (types.ADOEntraConfig.RunnerResident); off by default.
	ResidentOptIn bool
}

CredentialOrigin is control-plane provenance for one actual dispatch field. The caller resolves it from admitted owner/provider/grant snapshots, never from runner assertions. Stored credentials require proof of the own namespace.

type DeliveryPolicy 

type DeliveryPolicy struct {
	Classes map[string]ClassPolicy                 `json:"classes"`
	ByTrust map[types.RunnerTrustClass]TrustPolicy `json:"by_trust,omitempty"`
}

DeliveryPolicy is the `local_credential_delivery` governance document. A class absent from it means refuse. ByTrust overrides a class for runners of one trust class (types.RunnerTrustClass, stored and written only by a security operator); a class it does not name falls back to Classes, for every trust class.

func (DeliveryPolicy) ForTrust added in v0.9.3 

func (p DeliveryPolicy) ForTrust(class string, trust types.RunnerTrustClass) ClassPolicy

ForTrust is a class's policy on a runner of trust class trust: the trust class's override when it names the class, else the global row, else refuse. A class the global row delivers via_org is the same on every runner (Validate keeps overrides off it); any other class on an unknown trust class refuses.

func (DeliveryPolicy) Validate 

func (p DeliveryPolicy) Validate() error

Validate checks every class key and mode against design §7.2 and §7.5, and each trust class's overrides against the same bounds. via_org is never trust-gated: its credential never reaches the runner, so an override may neither deliver a class via_org nor override a class the global row delivers via_org. require_posture under org_cluster is refused: posture is a laptop's self-report.

type Entry 

type Entry struct {
	Struct   string
	Field    string
	Path     string // dotted path under Field, "" for the field itself
	Variant  string // which case of the field this row covers
	Class    Class
	Rule     Rule
	Delivery string
	Reason   Reason // set when the rule refuses
	ViaOrg   bool
}

Entry is one row of the classification table. Delivery names the OD-12 class key a refusal or mode applies to, when one does. ViaOrg marks a delivery row whose variant has the via_org shape (design §7.3): the organisation's egress can serve it, so the class's configured via_org mode admits it.

func Entries 

func Entries(structName, field string) []Entry

Entries returns the rows covering one field of a struct.

type EvidenceSource 

type EvidenceSource = types.RunEvidenceSource

EvidenceSource records who vouches for the evidence a run produces: its confinement, decisions, recordings, exit codes and capabilities. It is not the run's `confinement_source` (`requested` or `defaulted`, written by run.create): that says who chose the class, this says who can attest it. Declared in internal/types with the run row that carries it; aliased here. 

const (
	EvidenceSubstrate      EvidenceSource = types.RunEvidenceSubstrate      // the organisation's own substrate
	EvidenceRunnerAsserted EvidenceSource = types.RunEvidenceRunnerAsserted // the runner said so; nobody can verify it
)

func EvidenceFor 

func EvidenceFor(p Placement) EvidenceSource

EvidenceFor is the evidence source a placement records.

type LocalPlan 

type LocalPlan struct {
	Spec                       runner.SandboxSpec
	Origins                    map[string]CredentialOrigin
	CredentialIntents          []CredentialIntent
	OrgConfigKeys              []string
	VerifiedLocalPaths         map[string]bool
	UpstreamProxySecretRef     string
	TrustedOutput              bool
	SelfDefinedComponents      []string
	LocalSelfDefinedComponents bool
	Delivery                   DeliveryPolicy
	// Posture is the candidate runner's stored, self-reported posture; nil when
	// it never reported one.
	Posture *types.RunnerPosture
	// Trust is the candidate runner's stored trust class, which Delivery is read
	// at (DeliveryPolicy.ForTrust); "" (unknown) refuses every class but via_org.
	Trust types.RunnerTrustClass
	// ConfinementFloor is the run's blast-radius floor
	// (composer.RequiredConfinementFloor); "" when there is none.
	ConfinementFloor types.ConfinementClass
}

LocalPlan includes the final spec and the non-wire authoring facts a spec alone cannot prove. Origins keys are the paths returned by CredentialPaths. Missing provenance refuses, including fields added by late dispatch phases.

type Mode 

type Mode string

Mode is how an org-held credential reaches a local run (OD-12). 

const (
	ModeOwn            Mode = "own"             // the person's own material, wherever it already lives
	ModeViaOrg         Mode = "via_org"         // only in the org; used through the org's egress for the run's life
	ModeRunnerResident Mode = "runner_resident" // in the runner's OS keystore, then the local proxy or sandbox
	ModeRefuse         Mode = "refuse"          // nowhere; the default for every org-held class
)

func AllowedModes 

func AllowedModes(class string) []Mode

AllowedModes is the set of modes a class may be delivered under; nil for an unknown class.

type Placement 

type Placement = types.Placement

Placement says where a run's sandbox lives. A run row carries it, so the canonical declaration is internal/types (which cannot import this package); this alias and the two constants keep the name and the values callers here already use. 

const (
	Remote Placement = types.PlacementRemote // the organisation's own executor
	Local  Placement = types.PlacementLocal  // a registered runner on the person's laptop
)

type PostureRequirement 

type PostureRequirement struct {
	MDMManaged    bool              `json:"mdm_managed,omitempty"`
	DiskEncrypted bool              `json:"disk_encrypted,omitempty"`
	OSMin         map[string]string `json:"os_min,omitempty"` // per-OS minimum version
}

PostureRequirement is what a runner's reported posture (types.RunnerPosture, self-reported) must meet for a runner_resident class: only on that mode.

type Reason 

type Reason string

Reason is a machine-readable refusal reason of local placement and the runner link (design §12.3). The set is closed. 

const (
	ReasonPlacementUnavailable         Reason = "placement_unavailable"
	ReasonPlacementDenied              Reason = "placement_denied"
	ReasonPlacementCredential          Reason = "placement_credential"
	ReasonPlacementTrustedOutput       Reason = "placement_trusted_output"
	ReasonPlacementComponentSelfDefine Reason = "placement_component_self_defined"
	ReasonPlacementCapability          Reason = "placement_capability"
	ReasonPlacementLocalPath           Reason = "placement_local_path"
	ReasonRunnerOffline                Reason = "runner_offline"
	ReasonRunnerAtCapacity             Reason = "runner_at_capacity"
	ReasonRunnerLimitsUnset            Reason = "runner_limits_unset"
	ReasonRunnerAmbiguous              Reason = "runner_ambiguous"
	ReasonRunnerNotFound               Reason = "runner_not_found"
	ReasonRunnerUnclaimed              Reason = "runner_unclaimed"
	ReasonRunnerRevoked                Reason = "runner_revoked"
	ReasonRunnerTokenInvalid           Reason = "runner_token_invalid"
	ReasonRunnerClaimMismatch          Reason = "runner_claim_mismatch"
	ReasonRunnerPostureUnmet           Reason = "runner_posture_unmet"
	ReasonRunnerTrustChanged           Reason = "runner_trust_changed"
	ReasonRunnerKeystoreUnavailable    Reason = "runner_keystore_unavailable"
	ReasonRunnerActionPending          Reason = "runner_action_pending"
	// ReasonRunnerRecordingOff: the organisation or the pool requires recording, and no runner that
	// could take the run records it (--recording-store off, or a runner older than per-run recording).
	ReasonRunnerRecordingOff Reason = "runner_recording_off"
	// ReasonRecordingStoreOff: the organisation or the pool requires recording, and the organisation
	// keeps no session recordings; also the refusal to save a required setting while it keeps none.
	ReasonRecordingStoreOff        Reason = "recording_store_off"
	ReasonRelayRunnerMismatch      Reason = "relay_runner_mismatch"
	ReasonRelayRequired            Reason = "relay_required"
	ReasonRelayRouteRefused        Reason = "relay_route_refused"
	ReasonDeliveryViaOrg           Reason = "delivery_via_org"
	ReasonDeliveryRunnerResident   Reason = "delivery_runner_resident"
	ReasonDeliveryNotViaOrg        Reason = "delivery_not_via_org"
	ReasonViaOrgDestinationRefused Reason = "via_org_destination_refused"
	ReasonViaOrgCapExceeded        Reason = "via_org_cap_exceeded"
)

func Reasons 

func Reasons() []Reason

Reasons lists the closed set, unordered.

func (Reason) Status 

func (r Reason) Status() int

Status is the HTTP status the reason answers with; 0 for a reason outside the set.

func (Reason) Valid 

func (r Reason) Valid() bool

Valid reports whether r is in the closed set.

type Refusal 

type Refusal struct {
	Reason Reason
	Field  string
	Detail string
}

Refusal names the actual field that makes local execution ineligible.

func LocalEligibility 

func LocalEligibility(p LocalPlan) (runner.SandboxSpec, *Refusal)

LocalEligibility classifies the complete resolved plan with the canonical table. It does not select placement. An org-held class is admitted only by a configured via_org mode on a row of the via_org shape; runner_resident (H13) still refuses. The returned spec is a copy with operator network/inspection/ config removed and each via_org grant reduced to its ViaOrgRoutes entry.

func ResidentAdmits added in v0.9.3 

func ResidentAdmits(origin CredentialOrigin, p LocalPlan, path string) *Refusal

ResidentAdmits is the runner_resident gate (OD-12, design §7.4, Q7) for a credential of origin, whose delivery class is origin.Delivery: the class is delivered runner_resident under p's policy and may be, an Azure DevOps connection opted in, the run has no blast-radius floor (a runner-asserted class never satisfies one for a value the runner holds), and the runner's posture meets the class's requirement. LocalEligibility applies it at create, dispatch and revive; the org's delivery applies it again to each value, against the policy and posture of that moment. path names the refused field.

func ResidentGrant added in v0.9.3 

func ResidentGrant(origin CredentialOrigin, policy DeliveryPolicy, trust types.RunnerTrustClass, floor types.ConfinementClass) (resident bool, ref *Refusal)

ResidentGrant reports whether an org-held grant of origin is delivered runner_resident under policy on a runner of trust class trust, for a run whose blast-radius floor is floor (a floor refuses it here, at create, not first at dispatch), mirroring ViaOrgGrant: resident is true when the policy delivers its class runner_resident and the table admits its grant record; ref is the refusal when the policy delivers it so but the record is refused (a class not built, a posture requirement, the class's bounds). Both are zero for a class the policy does not deliver runner_resident.

func (*Refusal) Error 

func (r *Refusal) Error() string

type Request 

type Request struct {
	Placement Placement `json:"placement,omitempty"`
	RunnerID  string    `json:"runner_id,omitempty"`
}

Request is the placement a caller asked for (#116's shape). The zero value asks for no placement, which the resolver fills only when exactly one is eligible.

func (Request) Validate 

func (r Request) Validate() error

Validate checks the request's shape: a known placement, and a runner id only with local placement, as a UUID.

type Rule 

type Rule string

Rule is what local placement does with a field. 

const (
	RuleAllow         Rule = "allow"
	RuleDelivery      Rule = "delivery"       // OD-12: the class's configured mode, else refuse
	RuleViaOrgRefuse  Rule = "via_org_refuse" // via_org or refuse, never runner_resident
	RuleRefuse        Rule = "refuse"         // refused with Entry.Reason
	RuleBound         Rule = "bound"          // allowed only bound to this runner and inside its roots
	RuleNotSent       Rule = "not_sent"       // never dispatched; the runner's own configuration applies
	RuleStrip         Rule = "strip"          // dropped or narrowed in the laptop-bound copy
	RuleExempt        Rule = "exempt"         // sent as dispatched
	RuleOwnerOnlyOwn  Rule = "owner_only_own" // allowed, persisted OwnerOnly=true
	RuleNotConfigured Rule = "not_configured" // refused, and not a configurable class
)

type TrustPolicy added in v0.9.3 

type TrustPolicy struct {
	Classes map[string]ClassPolicy `json:"classes"`
}

TrustPolicy is one trust class's overrides of the global classes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.