Documentation
¶
Overview ¶
Package sandbox is the declaration of what a program may hold: a named, stack-deployed bundle that says which secrets a piece of work is handed and under which names. A run grant (chassis/authn) names sandboxes; the chassis opens one when a rule starts a command with `WITH grant, sandbox` or when a program the work runs asks for it through `txco sandbox`. The program never picks a secret by name: it gets what the sandbox says.
A stack declares a sandbox as one small YAML file under the reserved SANDBOXES/ subtree, beside OUTLETS/ and DATASETS/:
OPS/<stack>/SANDBOXES/<name>.yaml
The file deploys with `txco apply` as a stack_files row (inline on a single node, fingerprint + CAS on the fleet — the OUTLETS/ treatment) and is validated at apply; nothing is released until a run grant that names the sandbox is opened.
This file is the leaf layer: the reserved-path vocabulary, with no dependency on stores, so the CLI, the admin producer and the control-event applier can import it cheaply.
Index ¶
- Constants
- Variables
- func DeclNames(decls map[string]*Decl) []string
- func DeclPath(name string) string
- func IsSandboxPath(p string) bool
- func Name(p string) string
- func ParseRef(s string) (kind, name string, err error)
- func ValidCapability(s string) bool
- func ValidName(s string) bool
- func ValidVar(s string) bool
- type Decl
Constants ¶
const ( // MaxEnv bounds the variables one sandbox sets. MaxEnv = 32 // MaxCapabilities bounds the capabilities one sandbox names. MaxCapabilities = 32 // MaxDescription bounds the free-text note. MaxDescription = 256 )
Ceilings on one declaration. A run grant holds at most a handful of sandboxes, each a handful of variables; chassis/authn bounds the row.
const ( Dir = "SANDBOXES" DeclExt = ".yaml" )
Reserved top-level directory and the declaration extension.
const KindSecret = "secret"
Reference kinds. A reference is `<kind>:<name>`; `secret:` is the one kind today, the secret store's name grammar (chassis/secrets).
const ReservedVarPrefix = "TXCO_"
ReservedVarPrefix names the variables the chassis sets itself when it starts a program under a run grant (TXCO_RUN, TXCO_RUN_GRANT, …). A sandbox may not set one.
Variables ¶
var ( // CapabilityRE is the grammar of a capability's name: lowercase words // joined by dots, such as `crm.lookup`. It is the one grammar for the // name everywhere it appears — here, in a standing grant and in a run // grant's allowlist (chassis/authn reads it from here). CapabilityRE = regexp.MustCompile(`^[a-z][a-z0-9_-]{0,63}(\.[a-z][a-z0-9_-]{0,63}){0,7}$`) )
var ErrNotDeclared = errors.New("sandbox: not declared")
ErrNotDeclared: the stack's active version has no SANDBOXES/<name>.yaml.
Functions ¶
func DeclNames ¶
DeclNames returns the keys of a declaration map, sorted — for "unknown sandbox X, have [a b c]" messages and deterministic validation order.
func IsSandboxPath ¶
IsSandboxPath reports whether a stack_files path lives under SANDBOXES/.
func Name ¶
Name returns the sandbox a declaration path belongs to: "SANDBOXES/github.yaml" → "github". It returns "" when the path is not under SANDBOXES/, is nested, has the wrong extension, or names an invalid sandbox — the same shape validateStackFilePath enforces at upload.
func ValidCapability ¶ added in v0.2.33
ValidCapability reports whether s is a capability name.
Types ¶
type Decl ¶
type Decl struct {
Description string `yaml:"description"`
Env map[string]string `yaml:"env"`
Capabilities []string `yaml:"capabilities"`
}
Decl is one SANDBOXES/<name>.yaml: what a program that opens the sandbox is handed, under which names, and what it may CALL. Only what the chassis enforces is declared here; a key it does not enforce is a deploy error, not a promise.
description: what a deploy step holds # optional env: GH_TOKEN: secret:GITHUB_PAT # variable: reference capabilities: # what a run may call on this - ai.chat # chassis, by bare name - card.note
A sandbox sets variables, names capabilities, or both; one that does neither is a deploy error. A capability is not handed over: a run grant that names the sandbox carries the names in its allowlist, and the call is decided when it is made (chassis/server/grantgw).
Parsed strictly: an unknown key is a deploy error, not a silent ignore.
func (*Decl) CapabilityNames ¶ added in v0.2.33
CapabilityNames is the sorted list of capabilities the sandbox names: what a run grant that names the sandbox may call.
Source Files