spec

Documentation

Overview

Package spec is the shared contract between the control plane and the agent: the typed action catalog, argument validation, task-claim signing, and secret redaction.

The action definition is the security boundary. It fixes the executable, the argv shape, and the argument schema; the model (or operator) selects from that contract — nobody supplies a command line. Both sides compile the same catalog and the agent refuses any dispatch whose catalog hash differs from its own.

Index

• Constants
• Variables
• func ArgsDigest(validated map[string]string) string
• func Redact(in []byte) ([]byte, int)
• func RenderArgv(a Action, validated map[string]string) []string
• func SignClaim(priv ed25519.PrivateKey, c TaskClaim) string
• func ValidateArgs(a Action, in map[string]any) (map[string]string, error)
• func VerifyClaim(pub ed25519.PublicKey, c TaskClaim, sigHex string, ...) error
• type Action
• type Arg
• type Catalog
  • func Builtin() Catalog
  • func (c Catalog) Find(id string) (Action, bool)
  • func (c Catalog) Hash() string
  • func (c Catalog) Validate() error
• type TaskClaim

Constants

const (
	RiskReadOnly = "read_only"
	RiskLow      = "low"
	RiskMedium   = "medium"
	RiskHigh     = "high"
)

Risk levels. Phase 1 ships read_only actions exclusively; the policy layer refuses anything else by default.

const ClaimVersion = 1

const Mask = "[REDACTED]"

Variables

var (
	ErrBadSignature = errors.New("signature does not verify")
	ErrExpired      = errors.New("claim expired")
	ErrNotYetValid  = errors.New("claim issued in the future")
	ErrWrongTarget  = errors.New("claim is bound to a different machine")
	ErrWrongCatalog = errors.New("claim references a foreign catalog")
	ErrBadVersion   = errors.New("unsupported claim version")
)

Functions

func ArgsDigest

func ArgsDigest(validated map[string]string) string

ArgsDigest is the canonical digest of the validated argument map, bound into the signed task claim.

func Redact

func Redact(in []byte) ([]byte, int)

Redact masks known secret shapes and returns the masked bytes plus the number of replacements made.

func RenderArgv

func RenderArgv(a Action, validated map[string]string) []string

RenderArgv substitutes validated arguments into the action's argv. An optional argument that was not supplied drops its token entirely.

func SignClaim

func SignClaim(priv ed25519.PrivateKey, c TaskClaim) string

SignClaim signs the canonical claim bytes with the control plane's key.

func ValidateArgs

func ValidateArgs(a Action, in map[string]any) (map[string]string, error)

ValidateArgs checks caller-supplied arguments against the action's schema and returns the normalized string values. Unknown arguments are rejected; missing required arguments are rejected; defaults are applied.

func VerifyClaim

func VerifyClaim(pub ed25519.PublicKey, c TaskClaim, sigHex string,
	localMachineID, localCatalogHash string, now time.Time, maxSkew time.Duration) error

VerifyClaim checks the signature and every binding against local facts. maxSkew tolerates clock drift on IssuedAt.

Types

type Action

type Action struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Risk    string `json:"risk"`
	Summary string `json:"summary"`
	// Binary is resolved on PATH by the agent; Argv is the fixed shape.
	// A token that entirely matches {{name}} substitutes the validated
	// argument of that name; every other token is a literal. Execution
	// never goes through a shell.
	Binary         string   `json:"binary"`
	Argv           []string `json:"argv"`
	Args           []Arg    `json:"args,omitempty"`
	TimeoutMS      int      `json:"timeout_ms"`       // hard ceiling per run
	MaxOutputBytes int      `json:"max_output_bytes"` // per stream cap
}

type Arg

type Arg struct {
	Name     string   `json:"name"`
	Type     string   `json:"type"` // "string" | "int"
	Required bool     `json:"required,omitempty"`
	Pattern  string   `json:"pattern,omitempty"` // anchored automatically
	Enum     []string `json:"enum,omitempty"`
	Min      int      `json:"min,omitempty"` // int type only
	Max      int      `json:"max,omitempty"` // int type only
	MaxLen   int      `json:"max_len,omitempty"`
	Default  string   `json:"default,omitempty"`
}

type Catalog

type Catalog struct {
	Version string   `json:"version"`
	Actions []Action `json:"actions"`
}

func Builtin

func Builtin() Catalog

Builtin returns the Phase 1 read-only action catalog. Both the control plane and the agent compile this in; the agent refuses dispatches whose catalog hash differs from its own build.

Curation rules: read-only diagnostics only, no arbitrary paths, no arbitrary URLs, no environment enumeration, bounded output everywhere.

func (Catalog) Find

func (c Catalog) Find(id string) (Action, bool)

Find returns the action with the given ID.

func (Catalog) Hash

func (c Catalog) Hash() string

Hash returns the canonical content hash of the catalog. Struct field order makes encoding/json deterministic, so equal catalogs hash equal.

func (Catalog) Validate

func (c Catalog) Validate() error

Validate checks catalog integrity: every argv placeholder must reference a declared argument, and every declared argument must be well-formed.

type TaskClaim

type TaskClaim struct {
	Version     int    `json:"v"`            // claim format version
	TaskID      string `json:"task_id"`      // server-generated, doubles as nonce
	MachineID   string `json:"machine_id"`   // target binding
	ActionID    string `json:"action_id"`    // catalog action
	ArgsSHA256  string `json:"args_sha256"`  // digest of validated args
	CatalogHash string `json:"catalog_hash"` // catalog the args were validated against
	Reason      string `json:"reason"`       // operator/model supplied intent
	IssuedAt    int64  `json:"issued_at"`    // unix seconds
	ExpiresAt   int64  `json:"expires_at"`   // unix seconds
}

TaskClaim is the signed execution intent for one dispatched task. The agent refuses any dispatch whose delivered facts differ from the signed claim: wrong machine, expired, replayed nonce, foreign catalog, or a tampered action/argument set.

Struct field order fixes the canonical byte encoding (encoding/json is deterministic for structs); both sides marshal the same way.