sandbox

package

v0.2.31 Latest Latest Go to latest Published: Sep 30, 2026 License: MPL-2.0 Imports: 7 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/loremlabs/thanks-computer

Links

Open Source Insights

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 ValidName(s string) bool
func ValidVar(s string) bool
type Decl
- func ParseDecl(data []byte) (*Decl, error)
- func (d *Decl) Secrets() []string
- func (d *Decl) Vars() []string

Constants ¶

View Source

const (
	// MaxEnv bounds the variables one sandbox sets.
	MaxEnv = 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.

View Source

const (
	Dir     = "SANDBOXES"
	DeclExt = ".yaml"
)

Reserved top-level directory and the declaration extension.

View Source

const KindSecret = "secret"

Reference kinds. A reference is `<kind>:<name>`; `secret:` is the one kind today, the secret store's name grammar (chassis/secrets).

View Source

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 ¶

View Source

var ErrNotDeclared = errors.New("sandbox: not declared")

ErrNotDeclared: the stack's active version has no SANDBOXES/<name>.yaml.

Functions ¶

func DeclNames ¶

func DeclNames(decls map[string]*Decl) []string

DeclNames returns the keys of a declaration map, sorted — for "unknown sandbox X, have [a b c]" messages and deterministic validation order.

func DeclPath ¶

func DeclPath(name string) string

DeclPath is the stack_files path of a sandbox's declaration.

func IsSandboxPath ¶

func IsSandboxPath(p string) bool

IsSandboxPath reports whether a stack_files path lives under SANDBOXES/.

func Name ¶

func Name(p string) string

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 ParseRef ¶

func ParseRef(s string) (kind, name string, err error)

ParseRef reads a reference: `secret:GITHUB_PAT` → ("secret", "GITHUB_PAT").

func ValidName ¶

func ValidName(s string) bool

ValidName reports whether s is an acceptable sandbox name.

func ValidVar ¶

func ValidVar(s string) bool

ValidVar reports whether s may name a variable a sandbox sets.

Types ¶

type Decl ¶

type Decl struct {
	Description string            `yaml:"description"`
	Env         map[string]string `yaml:"env"`
}

Decl is one SANDBOXES/<name>.yaml: what a program that opens the sandbox is handed, under which names. 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

Parsed strictly: an unknown key is a deploy error, not a silent ignore.

func ParseDecl ¶

func ParseDecl(data []byte) (*Decl, error)

ParseDecl strictly decodes and validates a declaration body.

func (*Decl) Secrets ¶

func (d *Decl) Secrets() []string

Secrets is the sorted, deduplicated list of secret names the sandbox releases: what a run grant that names the sandbox must be allowed to release.

func (*Decl) Vars ¶

func (d *Decl) Vars() []string

Vars is the sorted list of variables the sandbox sets.

Source Files ¶

View all Source files

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