placement

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: Apache-2.0 Imports: 15 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"
)

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

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{

	{Struct: StructSandboxSpec, Field: "SecretEnv", Variant: "env_secret grant, OwnerOnly", Class: ClassOwn, Rule: RuleOwnerOnlyOwn, Delivery: ClassEnvSecret},
	{Struct: StructSandboxSpec, Field: "SecretEnv", Variant: "env_secret grant, not OwnerOnly", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassEnvSecret, Reason: ReasonPlacementCredential},
	{Struct: StructSandboxSpec, Field: "SecretEnv", Variant: "Bedrock role credentials, the person's own bedrock_sso: they sign in-process, so own is still runner_resident or refuse", Class: ClassOwn, Rule: RuleDelivery, Delivery: ClassBedrockRoleCreds, Reason: ReasonPlacementCredential},
	{Struct: StructSandboxSpec, Field: "SecretEnv", Variant: "Bedrock role credentials, otherwise", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassBedrockRoleCreds, Reason: ReasonPlacementCredential},
	{Struct: StructSandboxSpec, Field: "ManagedFiles", Variant: "managed settings", Class: ClassPlatform, Rule: RuleAllow},
	{Struct: StructSandboxSpec, Field: "ManagedFiles", Variant: "AgentOwned file_secret, OwnerOnly", Class: ClassOwn, Rule: RuleOwnerOnlyOwn, Delivery: ClassFileSecret},
	{Struct: StructSandboxSpec, Field: "ManagedFiles", Variant: "AgentOwned file_secret, not OwnerOnly", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassFileSecret, Reason: ReasonPlacementCredential},
	{Struct: StructSandboxSpec, Field: "Mounts", Variant: "operator-authored, including host-mode ~/.aws", Class: ClassOperator, Rule: RuleRefuse, Reason: ReasonPlacementCapability},
	{Struct: StructSandboxSpec, Field: "Mounts", Variant: "MemberAuthored local_dir", Class: ClassOwn, Rule: RuleBound, Reason: ReasonPlacementLocalPath},
	{Struct: StructSandboxSpec, Field: "Drives", Variant: "host_path", Class: ClassOwn, Rule: RuleBound, Reason: ReasonPlacementLocalPath},
	{Struct: StructSandboxSpec, Field: "Drives", Variant: "k8s_pvc, k8s_pvc_static, the org's docker_volume", Class: ClassOperator, Rule: RuleRefuse, Reason: ReasonPlacementCapability},
	{Struct: StructSandboxSpec, Field: "Image", Variant: "any, including a workspace image in the org registry; pulled with the runner's own registry credentials, never the org's pull secrets", Class: ClassOwn, Rule: RuleAllow, Reason: ReasonPlacementCapability},
	{Struct: StructSandboxSpec, Field: "Env", Variant: "platform variables and the person's own or self-defined component config", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructSandboxSpec, Field: "Env", Variant: "an org component's config: operator-authored, so a value there may be a secret the org never meant to send", Class: ClassOperator, Rule: RuleStrip},
	{Struct: StructSandboxSpec, Field: "Labels", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructSandboxSpec, Field: "UserMountRoots", Class: ClassExempt, Rule: RuleExempt, Variant: "re-checked against allowed_roots"},
	{Struct: StructSandboxSpec, Field: "RunID", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructSandboxSpec, Field: "RunnerID", Class: ClassExempt, Rule: RuleExempt, Variant: "routing carrier"},
	{Struct: StructSandboxSpec, Field: "RunnerMaxRuns", Class: ClassExempt, Rule: RuleExempt, Variant: "runner limit carrier"},
	{Struct: StructSandboxSpec, Field: "ConfinementClass", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructSandboxSpec, Field: "Resources", Class: ClassExempt, Rule: RuleExempt, Variant: "checked against the advertised capacity"},
	{Struct: StructSandboxSpec, Field: "Interactive", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructSandboxSpec, Field: "OnWaiting", Class: ClassExempt, Rule: RuleNotSent, Variant: "a callback; waiting events replace it"},
	{Struct: StructSandboxSpec, Field: "ExecOutput", Class: ClassExempt, Rule: RuleNotSent, Variant: "a writer; the output stream replaces it"},
	{Struct: StructSandboxSpec, Field: "ProxyConfig", Class: ClassComposite, Rule: RuleStrip, Variant: "classified field by field under ProxyConfig"},

	{Struct: StructProxyConfig, Field: "RunToken", Class: ClassPlatform, Rule: RuleAllow, Variant: "bounded by the runner_id binding"},
	{Struct: StructProxyConfig, Field: "ControlPlaneCAPEM", Class: ClassPlatform, Rule: RuleAllow, Variant: "public"},
	{Struct: StructProxyConfig, Field: "MITMCACertPEM", Class: ClassPlatform, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "MITMCAKeyPEM", Class: ClassPlatform, Rule: RuleAllow, Variant: "per run; gains MITM of one's own sandbox only"},
	{Struct: StructProxyConfig, Field: "Injection", Variant: "stored api_key, own namespace", Class: ClassOwn, Rule: RuleOwnerOnlyOwn},
	{Struct: StructProxyConfig, Field: "Injection", Variant: "operator namespace or shared component; via_org replaces it with a ViaOrgRoutes entry", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassAPIKey, Reason: ReasonPlacementCredential, ViaOrg: true},
	{Struct: StructProxyConfig, Field: "Injection", Variant: "the person's model-provider key or own Claude sign-in", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "Injection", Variant: "captured AWS SSO, credential_source per_user", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "Injection", Variant: "captured AWS SSO shared", Class: ClassBrokered, Rule: RuleDelivery, Delivery: ClassAWSSSOBearer, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "GitGrants", Variant: "GitHub App installation token; via_org keeps the repo allowlist and routes /wardyn/gh/ to the organisation", Class: ClassBrokered, Rule: RuleViaOrgRefuse, Delivery: ClassGitHubToken, Reason: ReasonPlacementCredential, ViaOrg: true},
	{Struct: StructProxyConfig, Field: "PATGrants", Variant: "per_user stored PAT", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "PATGrants", Variant: "shared CredentialSource", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassGitPATBroker, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "BrokeredPATGrantIDs", Variant: "follows per_user PATGrants", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "BrokeredPATGrantIDs", Variant: "follows shared PATGrants", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassGitPATBroker, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "ADOGrant", Variant: "minted PAT or bearer from a captured Entra sign-in; runner_resident only on a connection that opted in", Class: ClassBrokered, Rule: RuleDelivery, Delivery: ClassADOMintedPAT, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "ADOGrant", Variant: "own_pat token mode", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "AzureGates", Variant: "Azure Foundry, the person's own Entra sign-in", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructProxyConfig, Field: "AzureGates", Variant: "Azure Foundry, any shared capture", Class: ClassBrokered, Rule: RuleDelivery, Delivery: ClassAzureFoundryToken, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "GitHubAPI", Variant: "the organisation's GitHub App installation token, for the GitHub CLI", Class: ClassBrokered, Rule: RuleRefuse, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "AzureARM", Variant: "the Azure CLI's Resource Manager token, redeemed by the organisation from the person's Entra sign-in", Class: ClassBrokered, Rule: RuleRefuse, Reason: ReasonPlacementCredential},
	{Struct: StructProxyConfig, Field: "UpstreamProxyURL", Class: ClassOperator, Rule: RuleNotSent, Variant: "the runner's own upstream-proxy config applies"},
	{Struct: StructProxyConfig, Field: "TrustedCAPEM", Class: ClassOperator, Rule: RuleNotSent, Variant: "org network; destinations needing it take via_org"},
	{Struct: StructProxyConfig, Field: "InternalHosts", Class: ClassOperator, Rule: RuleNotSent, Variant: "org network"},
	{Struct: StructProxyConfig, Field: "UpstreamProxyNoProxy", Class: ClassOperator, Rule: RuleNotSent, Variant: "org network"},
	{Struct: StructProxyConfig, Field: "LLMUpstreams", Class: ClassOperator, Rule: RuleNotSent, Variant: "org network"},
	{Struct: StructProxyConfig, Field: "MITMHosts", Class: ClassOperator, Rule: RuleStrip, Variant: "only hosts of own and runner_resident injections and every via_org destination; operator-only hosts dropped"},
	{Struct: StructProxyConfig, Field: "Policy", Path: "EligibleGrants", Class: ClassOperator, Rule: RuleStrip, Variant: "grants not delivered own or runner_resident dropped; a via_org grant keeps only its grant_id and host"},
	{Struct: StructProxyConfig, Field: "Policy", Path: "LLMInspection.WorkspaceSecretValues", Class: ClassOperator, Rule: RuleStrip, Variant: "resolved inspection corpus never sent to a runner"},
	{Struct: StructProxyConfig, Field: "Policy", Path: "LLMInspection.WorkspaceSecretNames", Class: ClassOperator, Rule: RuleStrip, Variant: "resolved values stripped; the org-side via_org scan may still use them"},
	{Struct: StructProxyConfig, Field: "Policy", Path: "AllowedDomains", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "DeniedDomains", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "AllowAllEgress", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "FirstUseApproval", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "FirstUseHoldSeconds", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "MaxHolds", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "AllowedMethods", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "MinConfinementClass", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "AutoStopAfterSec", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "WorkspaceMounts", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "WorkspaceRepos", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "UIApps", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "Resources", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "ToolRules", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "GitPushAnyBranch", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "PushRules", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "AzureDevOpsCapabilities", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "GitHubCapabilities", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Policy", Path: "LLMInspection", Class: ClassExempt, Rule: RuleExempt, Variant: "the rest of LLMInspection; its resolved secret names are the strip row above"},
	{Struct: StructProxyConfig, Field: "ControlPlaneURL", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "MITMLLM", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "LLMChannelHosts", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "LLMUnavailableDetail", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Unattended", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "Attribution", Class: ClassExempt, Rule: RuleExempt},
	{Struct: StructProxyConfig, Field: "PushRuleBase", Class: ClassExempt, Rule: RuleExempt, Variant: "the run's push rules after the ceiling, for an entry with no set; policy content, no credential"},
	{Struct: StructProxyConfig, Field: "PushRuleSets", Class: ClassExempt, Rule: RuleExempt, Variant: "push content rules per SCM entry; policy content, no credential"},
	{Struct: StructProxyConfig, Field: "HarnessCredentials", Class: ClassExempt, Rule: RuleExempt, Variant: "SHA-256 of each harness's approval credential; a digest, never the plaintext, which goes to that harness's own process as secret env"},
	{Struct: StructProxyConfig, Field: "HarnessToolRules", Class: ClassExempt, Rule: RuleExempt, Variant: "tool rules per included harness; policy content, no credential"},
	{Struct: StructProxyConfig, Field: "ViaOrgRoutes", Class: ClassExempt, Rule: RuleExempt, Variant: "grant id and destination host of each via_org grant; no credential, and the organisation re-checks both"},
	{Struct: StructProxyConfig, Field: "MCPServers", Class: ClassExempt, Rule: RuleExempt, Variant: "key, URL and the grant id of each MCP server's header credential; no credential, which the broker resolves from the control plane per request"},
	{Struct: StructProxyConfig, Field: "MCPBindings", Class: ClassExempt, Rule: RuleExempt, Variant: "SHA-256 of each harness's MCP token and its server keys; a digest, never the token"},

	{Struct: StructGrantKind, Field: "api_key", Variant: "own namespace", Class: ClassOwn, Rule: RuleOwnerOnlyOwn},
	{Struct: StructGrantKind, Field: "api_key", Variant: "operator/shared", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassAPIKey, Reason: ReasonPlacementCredential, ViaOrg: true},
	{Struct: StructGrantKind, Field: "env_secret", Variant: "own namespace", Class: ClassOwn, Rule: RuleOwnerOnlyOwn},
	{Struct: StructGrantKind, Field: "env_secret", Variant: "operator/shared", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassEnvSecret, Reason: ReasonPlacementCredential},
	{Struct: StructGrantKind, Field: "file_secret", Variant: "own namespace", Class: ClassOwn, Rule: RuleOwnerOnlyOwn},
	{Struct: StructGrantKind, Field: "file_secret", Variant: "operator/shared", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassFileSecret, Reason: ReasonPlacementCredential},
	{Struct: StructGrantKind, Field: "github_token", Class: ClassBrokered, Rule: RuleViaOrgRefuse, Delivery: ClassGitHubToken, Reason: ReasonPlacementCredential, ViaOrg: true},

	{Struct: StructGrantKind, Field: "ssh_key", Variant: "own key", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructGrantKind, Field: "ssh_key", Variant: "operator key", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassSSHKey, Reason: ReasonPlacementCredential},
	{Struct: StructGrantKind, Field: "git_pat", Variant: "helper shape, own", Class: ClassOwn, Rule: RuleAllow},
	{Struct: StructGrantKind, Field: "git_pat", Variant: "helper shape, operator", Class: ClassOperator, Rule: RuleDelivery, Delivery: ClassGitPATHelper, Reason: ReasonPlacementCredential},
	{Struct: StructGrantKind, Field: "cloud_sts", Class: ClassBrokered, Rule: RuleNotConfigured, Delivery: ClassCloudSTS, Reason: ReasonPlacementCredential},
}

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

ViaOrgGrant reports whether an org-held grant of origin is delivered via_org under policy: 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"`
}

DeliveryPolicy is the `local_credential_delivery` governance document. A class absent from it means refuse.

func (DeliveryPolicy) For 

func (p DeliveryPolicy) For(class string) ClassPolicy

For is the configured policy of a class: refuse when absent.

func (DeliveryPolicy) Validate 

func (p DeliveryPolicy) Validate() error

Validate checks every class key and mode against design §7.2 and §7.5.

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
	// 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"
	ReasonRunnerKeystoreUnavailable    Reason = "runner_keystore_unavailable"
	ReasonRunnerActionPending          Reason = "runner_action_pending"
	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 (*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
)

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.