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 CheckEntry(key, value string) error
- func DeclNames(decls map[string]*Decl) []string
- func DeclPath(name string) string
- func IsSandboxPath(p string) bool
- func Name(p string) string
- func ParseEntry(key string) (kind, path string, ok bool)
- func ParseRef(s string) (kind, name string, err error)
- func ValidCapability(s string) bool
- func ValidName(s string) bool
- func ValidPath(p 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 // MaxFiles bounds the files one sandbox serves. MaxFiles = 8 // MaxPath bounds a file's path. MaxPath = 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 ( KindSecret = "secret" KindConnection = "connection" )
Reference kinds. A reference is `<kind>:<name>`: `secret:` names a tenant secret (the secret store's name grammar, chassis/secrets); `connection:` names a provider whose token the principal holds (chassis/connection), released as the token itself.
const ( FilePrefix = "file:" DotenvPrefix = "dotenv:" DotenvValue = "env" )
Entry keys. A run grant snapshots a sandbox as one map, entry → value: a variable by its name, a file as `file:<path>` (value: its reference) and the dotenv file as `dotenv:<path>` (value: DotenvValue). A variable name holds no colon, so the three never collide.
const ( EntryVar = "var" EntryFile = "file" EntryDotenv = "dotenv" )
Entry kinds, as a run grant's snapshot names them.
const ( Dir = "SANDBOXES" DeclExt = ".yaml" )
Reserved top-level directory and the declaration extension.
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 CheckEntry ¶ added in v0.2.51
CheckEntry validates one entry of a snapshot: a variable or a file with a reference, or the dotenv file with DotenvValue.
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 ParseEntry ¶ added in v0.2.51
ParseEntry reads one key of a snapshot: its kind and, for a file or the dotenv file, its path. ok is false for a key that is none of the three.
func ParseRef ¶
ParseRef reads a reference: `secret:GITHUB_PAT` → ("secret", "GITHUB_PAT"), `connection:github` → ("connection", "github").
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"`
Files map[string]string `yaml:"files"`
Dotenv string `yaml:"dotenv"`
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 GITHUB: connection:github # a principal's token at a provider files: # path: reference, served as a file ~/.ssh/id_ed25519: secret:DEPLOY_KEY dotenv: run.env # the env entries, also as a file capabilities: # what a run may call on this - ai.chat # chassis, by bare name - card.note
A sandbox sets variables, serves files, names capabilities, or any of them; one that does none is a deploy error. A file's value is the whole reference's value (a multi-line key is a file, not a variable); the program that opens the sandbox reads it at the path, relative to the directory it serves in, or under ~/. `dotenv` serves the env entries as NAME=value lines at that path, for a program that reads a .env file. 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.
func (*Decl) Entries ¶ added in v0.2.51
Entries is the sandbox as a run grant snapshots it: every variable by its name, every file as `file:<path>`, the dotenv file as `dotenv:<path>` (see FilePrefix).
Source Files