spec

type APIKey struct {
	// Name is the in-container env var, set to a sentinel when
	// proxy-managed. Empty declares an inject-only credential: Inject
	// rules are then required, and no variable is created for it.
	Name string `json:"name" yaml:"name"`

	// ProxyManaged keeps the real value on the host. A named key's
	// variable carries a sentinel; an inject-only key (empty Name with
	// Inject rules) has no in-container presence at all. Outbound, the
	// boundary presents the real value either way.
	ProxyManaged bool `json:"proxyManaged,omitempty" yaml:"proxyManaged,omitempty"`

	// Inject lists the outbound domains the proxy rewrites.
	Inject []Inject `json:"inject,omitempty" yaml:"inject,omitempty"`
}

type AgentContext struct {
	// Directory overrides workspace-sibling placement for agents whose
	// startup discovery only reads a dedicated configuration directory.
	Directory string `json:"directory,omitempty" yaml:"directory,omitempty"`
	Filename  string `json:"filename,omitempty" yaml:"filename,omitempty"`
	// ContentFile points at the context body: a context-relative path in
	// the authored descriptor, rewritten by the frontend to the staged
	// in-image path in the published one.
	ContentFile string `json:"contentFile,omitempty" yaml:"contentFile,omitempty"`
	// Content carries small instruction content inline, for content-free
	// kits.
	Content string `json:"content,omitempty" yaml:"content,omitempty"`
}

type AgentSessions struct {
	Prompt   []string    `json:"prompt,omitempty" yaml:"prompt,omitempty"`
	Resume   []string    `json:"resume,omitempty" yaml:"resume,omitempty"`
	Continue []string    `json:"continue,omitempty" yaml:"continue,omitempty"`
	List     CommandLine `json:"list,omitempty" yaml:"list,omitempty"`
}

type AgentSkill struct {
	Path string `yaml:"path" json:"path"`
	Name string `yaml:"name,omitempty" json:"name,omitempty"`
}

type AgentSkillCapability struct {
	AgentSkill
	Optional    bool
	DisplayName string
	Description string
}

type AgentSkills struct {
	Path string `json:"path" yaml:"path"`
	// Mode is "readonly" (default) or "readwrite".
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type AgentSkillsCapability struct {
	AgentSkills
	Optional    bool
	Name        string
	Description string
}

type Arg struct {
	// Default is substituted when the caller supplies nothing. A nil
	// default with Required unset still means the arg is optional and
	// expands to the empty string only if referenced; declaring Required
	// alongside Default is an error.
	Default *string `json:"default,omitempty" yaml:"default,omitempty"`

	// Required marks a value the caller must supply.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Description is shown wherever a kit's inputs are listed.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Enum restricts the value to an exact set. Exclusive with Pattern.
	Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`

	// Pattern restricts the value to an RE2 regexp matched against the
	// whole value. Exclusive with Enum.
	Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// Env opts the resolved value into the container environment under
	// this variable name.
	Env string `json:"env,omitempty" yaml:"env,omitempty"`

	// BuildArg resolves the arg at build instead: the frontend validates
	// it, hands it to the companion dockerfile under this build-arg name,
	// and expands its references into the published descriptor.
	BuildArg string `json:"buildArg,omitempty" yaml:"buildArg,omitempty"`
}

type BuiltBy struct {
	// Name is the frontend's published image, e.g. docker/sandbox-kit.
	Name string `json:"name"`
	// Version is the frontend's release, or "dev" for a build no release
	// stamped.
	Version string `json:"version"`
	// Revision is the full commit the frontend was built from, omitted
	// when the build recorded none.
	Revision string `json:"revision,omitempty"`
}

type Capability struct {
	// Group is the alternative to an ordinary entry. It is not a capability
	// type and must be selected before typed accessors are used.
	Group *CapabilityGroup `json:"group,omitempty" yaml:"group,omitempty"`

	// Source preserves publisher attribution. It is untrusted diagnostic
	// metadata; the consuming artifact still determines trust.
	Source *CapabilitySource `json:"source,omitempty" yaml:"source,omitempty"`

	// Type names the capability and its config-schema version, e.g.
	// "com.docker.sandbox/network-policy@1".
	Type string `json:"type,omitempty" yaml:"type,omitempty"`

	// Name is a display label, not identity: duplicate labels are allowed
	// and renaming a request changes neither its grants nor its merge key.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Optional marks a capability the kit degrades gracefully without:
	// an unknown or unprovided optional capability is skipped and recorded,
	// while a required one fails resolution closed. For credentials this
	// subsumes the older per-credential required flag.
	Optional bool `json:"optional,omitempty" yaml:"optional,omitempty"`

	// Config is the type-specific request payload. Well-known types are
	// decoded strictly against the schema their version pins; unknown
	// types carry it opaquely. Part of the permission surface: config
	// changes gate like any widening.
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`

	// Description is shown wherever the request is listed or prompted.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// contains filtered or unexported fields
}

type CapabilityDecision struct {
	Accepted bool   `json:"accepted"`
	Message  string `json:"message,omitempty"`
}

type CapabilityGroup struct {
	Name         string       `json:"name,omitempty" yaml:"name,omitempty"`
	Description  string       `json:"description,omitempty" yaml:"description,omitempty"`
	Optional     bool         `json:"optional,omitempty" yaml:"optional,omitempty"`
	Capabilities []Capability `json:"capabilities" yaml:"capabilities"`
}

type CapabilityItem = Capability

type CapabilitySource struct {
	Kit  string `json:"kit" yaml:"kit"`
	Path string `json:"path" yaml:"path"`
}

type CommandLine []string

type Constraint struct {
	Op      ConstraintOp
	Version string
}

type ConstraintOp string

type ContextSource struct {
	// Reference names the contributor, for the staged body's heading and
	// for errors reading it.
	Reference string

	// Path is an in-image path to read the body from; empty when the
	// body is inline.
	Path string

	// Content is the inline body; empty when Path is set.
	Content string

	// Target is set when publication preserves a separately selectable body.
	Target string
}

type Contribution struct {
	// Reference is how the contribution is named in merge errors: a
	// listed kit's consumption reference, or the set's own descriptor.
	Reference string

	// Descriptor is the declarations this contribution brings. A
	// listed kit's is its published descriptor with its create-phase
	// args already resolved (KitArgValues, ExpandCreateArgs). Publication
	// preserves final-environment references; Compose requires those to be
	// expanded before reconciliation.
	Descriptor *Descriptor
}

type Credential struct {
	// Service is the identifier in the host credential store.
	Service string `json:"service" yaml:"service"`

	// Phase accepts one phase or a non-empty list of distinct phases.
	Phase Phases `json:"phase" yaml:"phase"`

	// APIKey configures header injection of an API key.
	APIKey *APIKey `json:"apiKey,omitempty" yaml:"apiKey,omitempty"`

	// OAuth configures proxy-managed OAuth token interception.
	OAuth *OAuth `json:"oauth,omitempty" yaml:"oauth,omitempty"`
}

type CredentialCapability struct {
	Credential

	// Required mirrors the entry's optionality: a required credential
	// fails preflight when no binding satisfies the service, an optional
	// one is skipped and recorded.
	Required bool

	// Name and Description are the entry's display label and explanation.
	Name        string
	Description string
}

type CredentialFile struct {
	Path string `json:"path" yaml:"path"`
	// Structure is a declarative nested map, encoded after placeholder
	// substitution in the encoding Format selects, so its output is
	// well-formed regardless of the values. Leaf strings may reference
	// {{.AccessToken}} and {{.RefreshToken}} (strings), {{.ExpiresAt}}
	// (a number), {{.Scopes}} (an array), and {{.PrimaryApiKey}} (a
	// string whose enclosing key is omitted when no key is captured);
	// each placeholder renders in the target encoding's own type.
	// Unknown placeholders are errors.
	Structure map[string]any `json:"structure,omitempty" yaml:"structure,omitempty"`
	// Format selects the encoding of the substituted structure: "json"
	// (the default when empty) or "toml", for agents that read TOML
	// credential files (devin). Encoding stays declarative either way —
	// nested maps become TOML tables, {{.ExpiresAt}} a TOML integer, and
	// {{.Scopes}} a TOML array.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
}

type Descriptor struct {

	// SchemaVersion must be "3".
	SchemaVersion string `json:"schemaVersion" yaml:"schemaVersion"`

	// DisplayName is what humans read; identity lives in the reference.
	DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty"`

	// Author is who published the kit, in the freeform
	// org.opencontainers.image.authors convention ("Name <email>", commas
	// for multiples). Display metadata only, exactly like DisplayName: a
	// self-asserted claim, never identity and never a trust input —
	// publisher identity lives in the reference's registry namespace and
	// in the signature.
	Author string `json:"author,omitempty" yaml:"author,omitempty"`

	// Description is a short human-readable summary.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// SourceURL points at the kit's source repository or documentation.
	SourceURL string `json:"sourceUrl,omitempty" yaml:"sourceUrl,omitempty"`

	// IconURL is an https URL to an image representing the kit in catalogs
	// and pickers. Display metadata like DisplayName, and self-asserted
	// the same way — but unlike the other display fields a consumer
	// fetches and renders it, so the scheme is constrained rather than
	// free text: https only keeps javascript:, data:, and file: out of
	// whatever surface ends up rendering it.
	//
	// A URL rather than staged content because the surfaces that want an
	// icon — a registry listing, a picker — have the manifest and not the
	// layers. An icon in a layer could not be shown without pulling the
	// kit, which is the moment the icon existed to inform.
	IconURL string `json:"iconUrl,omitempty" yaml:"iconUrl,omitempty"`

	// Version is the fallback version for unversioned provides entries,
	// for kits consumed by references that carry no version of their own:
	// a local directory, a git branch or commit. It never overrides the
	// consumption reference — an OCI tag or a version-shaped git ref wins,
	// so a stale Version cannot lie to the resolver — and an explicit
	// provides@version outranks both. May reference a build-phase arg
	// (`${{ kit.args.version }}`), expanded into the published descriptor
	// like provides.
	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	// Licenses lists SPDX license identifiers.
	Licenses []string `json:"licenses,omitempty" yaml:"licenses,omitempty"`

	// Kind is "workload" or "mixin". It names the role; the layer nature
	// follows from it, and it tells the frontend what to emit.
	Kind string `json:"kind" yaml:"kind"`

	// Provides lists capabilities this kit offers, optionally versioned as
	// name@version. Nothing is provided implicitly: a kit that wants to be
	// requirable by name states so here.
	Provides []string `json:"provides,omitempty" yaml:"provides,omitempty"`

	// Requires lists capabilities that must be satisfied by the resolved
	// set, as "name" or "name <op> version" (comma-AND'd constraints;
	// ops: >=, >, <=, <, =). Capability names resolve to nothing and
	// validate against something.
	Requires []string `json:"requires,omitempty" yaml:"requires,omitempty"`

	// Integrates lists capabilities the kit works with when present but
	// functions without, in the requires grammar. An absent provider is
	// fine; a PRESENT one that violates the stated constraints still fails
	// resolution — an integration that would break is incoherence, not an
	// option. A met entry orders like requires: the provider composes
	// before the kit that integrates with it.
	Integrates []string `json:"integrates,omitempty" yaml:"integrates,omitempty"`

	// Conflicts lists capability names that must be absent from the
	// resolved set.
	Conflicts []string `json:"conflicts,omitempty" yaml:"conflicts,omitempty"`

	// Capabilities declares everything the kit needs but cannot supply itself:
	// a list of typed, versioned capability requests, each answered —
	// granted, refused, or prompted — by the host. One model for every
	// capability: well-known types get strict config schemas, cross-entry
	// validation, and direction-aware gating; unknown types are the
	// extension point, refused by name when required, skipped and
	// recorded when optional. Everything the kit asks of its host lives
	// here — resource grants and engine-executed behaviors alike
	// (lifecycle hooks, agent context) — so a host answers the whole ask
	// through one mechanism, or refuses the parts it does not know.
	Capabilities []CapabilityItem `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	// Args declares installer-supplied values, keyed by arg name. Private
	// by default: an arg reaches the container only via env:, and the
	// build only via buildArg:.
	Args map[string]Arg `json:"args,omitempty" yaml:"args,omitempty"`

	// Build is the kit's content recipe inline: literal Dockerfile text,
	// the single-file alternative to the companion <stem>.dockerfile
	// (declaring both is an error). Full Dockerfile semantics apply —
	// multi-stage, mounts, even a foreign # syntax= first line — because
	// the frontend hands the block to the Dockerfile frontend verbatim;
	// nothing is transpiled. Build-phase args reach it as --build-arg
	// under their declared buildArg names, exactly like a companion.
	// The published descriptor carries the block, so the annotation also
	// records how the content was produced.
	Build string `json:"build,omitempty" yaml:"build,omitempty"`

	// Kits is this kit's content as a list of published kits rather than
	// Dockerfile text: the fourth authoring form, for an environment
	// assembled out of kits someone already published. Mutually
	// exclusive with Build and Dockerfile — a kit's content recipe lives
	// in exactly one place — and declared by kind: set, or beside the
	// kind the listed kits imply.
	//
	// The frontend resolves every one of them, merges their layers and
	// their declarations, and publishes one ordinary kit. The published
	// descriptor retains the list with each entry pinned by Digest, the
	// way it retains an inline Build block: the artifact still records
	// how its content was produced.
	Kits []Kit `json:"kits,omitempty" yaml:"kits,omitempty"`

	// Dockerfile names the companion recipe explicitly, as a path
	// relative to the descriptor's directory. Optional sugar over the
	// filename-stem convention (<stem>.dockerfile beside the
	// descriptor): stating it makes the pairing visible in the
	// descriptor and frees the recipe's name from the stem. Unlike the
	// conventional companion — whose absence just means a
	// declaration-only kit — a named recipe that does not exist is an
	// error: an explicit reference failing silently would build the
	// wrong kit. Mutually exclusive with build:.
	Dockerfile string `json:"dockerfile,omitempty" yaml:"dockerfile,omitempty"`
	// contains filtered or unexported fields
}

type FieldError struct {
	Path string
	// contains filtered or unexported fields
}

type File struct {
	Path    string `json:"path" yaml:"path"`
	Content string `json:"content" yaml:"content"`
	Mode    string `json:"mode,omitempty" yaml:"mode,omitempty"`
	// Overwrite defaults to true; nil means unset. overwrite: false skips
	// the write when the file already exists (e.g. on a persistent volume).
	Overwrite   *bool  `json:"overwrite,omitempty" yaml:"overwrite,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type HostMount struct {
	Path string `json:"path" yaml:"path"`
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type Inject struct {
	Domain string `json:"domain" yaml:"domain"`
	Header string `json:"header,omitempty" yaml:"header,omitempty"`
	// Format renders the credential into the header value, e.g. "Bearer %s".
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
	// Scheme selects a non-header presentation, e.g. "basic".
	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`
	// Username is the basic-auth username when Scheme is "basic".
	Username string `json:"username,omitempty" yaml:"username,omitempty"`
}

type InstallHook struct {
	Command     CommandLine `json:"command" yaml:"command"`
	User        string      `json:"user,omitempty" yaml:"user,omitempty"`
	Env         []string    `json:"env,omitempty" yaml:"env,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
}

type Kit struct {
	// Ref is the reference this kit is consumed by, and the identity it
	// is named by in every merge diagnostic. A registry reference: a
	// local directory or a git URL names a kit that is not published
	// yet, and a set's kits have to be resolvable from the manifest
	// alone.
	Ref string `json:"ref" yaml:"ref"`

	// Digest pins this kit's manifest. Optional in the authored form —
	// where a tag is how an author names a version — and required in
	// the published one, which the frontend fills in from the reference
	// it actually resolved.
	Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`

	// Args supplies this kit's create-phase args, keyed by its own arg
	// names. A literal value is expanded into the merged descriptor at
	// publish, which is what makes the set a pinned artifact. A value
	// that is itself a `${{ kit.args.* }}` reference re-exports the
	// input under the set's name: the reference lands where the
	// placeholder was, and the set's own declaration — signed with the
	// set — is what bounds the value an installer can supply.
	Args map[string]string `json:"args,omitempty" yaml:"args,omitempty"`
}

type Lifecycle struct {
	Install []InstallHook `json:"install,omitempty" yaml:"install,omitempty"`
	Startup []StartupHook `json:"startup,omitempty" yaml:"startup,omitempty"`
	Files   []File        `json:"files,omitempty" yaml:"files,omitempty"`

	// Interactive is the argv tail appended to the workload's launch
	// command for an interactive (TTY) session — the one piece of
	// runtime config the image config has no native slot for (Cmd is
	// single-valued). It lives in the lifecycle capability because the
	// engine consumes it the way it consumes the hooks: behavior across
	// the sandbox's life, not a grant.
	Interactive []string `json:"interactive,omitempty" yaml:"interactive,omitempty"`
}

type MergeOptions struct {
	// ContextPath is the in-image path the merged agent-context body
	// will be staged at, written into the merged entry's contentFile.
	// Required when any contribution declares context content.
	ContextPath string
}

type MergeResult struct {
	// Descriptor is the merged declaration set, under the derived kind.
	Descriptor *Descriptor

	// ContextSources are agent-context bodies in contribution order. Empty
	// when no contribution declared any context content. Sources with an
	// empty Target are concatenated into the merged entry's contentFile.
	// Each source with a Target must instead be staged separately at that
	// path, preserving its conditional selection boundary. The caller owns
	// reading and staging the bodies; this package only computes the paths.
	ContextSources []ContextSource
}

type NetworkEntry struct {
	// Hosts are the domain patterns this entry names. A bounded entry in
	// an Allow list names them literally, because a pattern cannot be
	// bounded and unbounded at once; Deny entries and unbounded entries
	// may name patterns.
	Hosts []string `json:"hosts" yaml:"hosts"`

	// Methods are uppercase HTTP method tokens, or the single entry
	// MethodAny. Stating any of them bounds the entry.
	Methods []string `json:"methods,omitempty" yaml:"methods,omitempty"`

	// Paths are globs matched against the request path. Stating one
	// requires stating Methods, so a path always says which methods it
	// bounds; omitted alongside methods, it means every path.
	Paths []string `json:"paths,omitempty" yaml:"paths,omitempty"`
}

type NetworkRules struct {
	Allow []string `json:"allow,omitempty" yaml:"allow,omitempty"`
	Deny  []string `json:"deny,omitempty" yaml:"deny,omitempty"`
}

type NetworkRulesV2 struct {
	Allow []NetworkEntry `json:"allow,omitempty" yaml:"allow,omitempty"`
	Deny  []NetworkEntry `json:"deny,omitempty" yaml:"deny,omitempty"`
}

type OAuth struct {
	TokenEndpoint  *TokenEndpoint  `json:"tokenEndpoint,omitempty" yaml:"tokenEndpoint,omitempty"`
	ResourceHosts  []string        `json:"resourceHosts,omitempty" yaml:"resourceHosts,omitempty"`
	Sentinels      *Sentinels      `json:"sentinels,omitempty" yaml:"sentinels,omitempty"`
	CredentialFile *CredentialFile `json:"credentialFile,omitempty" yaml:"credentialFile,omitempty"`
	ResponseFields *ResponseFields `json:"responseFields,omitempty" yaml:"responseFields,omitempty"`
	// Passthrough returns the real token to the container: a downgrade.
	Passthrough bool `json:"passthrough,omitempty" yaml:"passthrough,omitempty"`
}

type OwnedProvide struct {
	Provide
	Owner string
}

type Package struct {
	Name    string
	Version string
}

type PackageDatabase struct {
	Namespace string
	Path      string
	Read      func(io.Reader) ([]Package, error)
}

type PhasedNetwork struct {
	Install *NetworkRules `json:"install,omitempty" yaml:"install,omitempty"`
	Runtime *NetworkRules `json:"runtime,omitempty" yaml:"runtime,omitempty"`
}

type PhasedNetworkV2 struct {
	Install *NetworkRulesV2 `json:"install,omitempty" yaml:"install,omitempty"`
	Runtime *NetworkRulesV2 `json:"runtime,omitempty" yaml:"runtime,omitempty"`
}

type Phases []string

type Port struct {
	Name      string `json:"name,omitempty" yaml:"name,omitempty"`
	Container int    `json:"container" yaml:"container"`
	Transport string `json:"transport,omitempty" yaml:"transport,omitempty"`
}

type Position struct {
	Line      int
	Column    int
	EndLine   int
	EndColumn int
}

type Provide struct {
	Name    string
	Version string // empty when unversioned
}

type Require struct {
	Name        string
	Constraints []Constraint // empty when unconstrained
}

type Resources struct {
	CPU    float64 `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory string  `json:"memory,omitempty" yaml:"memory,omitempty"`
	GPU    string  `json:"gpu,omitempty" yaml:"gpu,omitempty"`
}

type ResponseFields struct {
	AccessToken  string `json:"accessToken,omitempty" yaml:"accessToken,omitempty"`
	RefreshToken string `json:"refreshToken,omitempty" yaml:"refreshToken,omitempty"`
	ExpiresIn    string `json:"expiresIn,omitempty" yaml:"expiresIn,omitempty"`
}

type SSHAgent struct {
	Phase SSHAgentPhases `json:"phase" yaml:"phase"`
	// Unrestricted defaults to true. False requires at least one bound.
	Unrestricted *bool    `json:"unrestricted,omitempty" yaml:"unrestricted,omitempty"`
	Sign         []string `json:"sign,omitempty" yaml:"sign,omitempty"`
	Authenticate []string `json:"authenticate,omitempty" yaml:"authenticate,omitempty"`
}

type SSHAgentCapability struct {
	SSHAgent
	Optional    bool
	Name        string
	Description string
}

type SSHAgentPhases = Phases

type SelectCapability func(context.Context, Descriptor, Capability) CapabilityDecision

type Selection struct {
	Capabilities []Capability      `json:"capabilities"`
	Selected     []SelectionRecord `json:"selected,omitempty"`
	Skipped      []SelectionRecord `json:"skipped,omitempty"`
}

type SelectionRecord struct {
	Path          string             `json:"path"`
	Name          string             `json:"name,omitempty"`
	Source        *CapabilitySource  `json:"source,omitempty"`
	Members       []string           `json:"members"`
	MemberSources []CapabilitySource `json:"memberSources,omitempty"`
	Rejected      []string           `json:"rejected,omitempty"`
	// Decisions follows Members order, including accepted members of skipped
	// groups. Older persisted records may omit it.
	Decisions []CapabilityDecision `json:"decisions,omitempty"`
}

type Sentinels struct {
	AccessToken  string `json:"accessToken,omitempty" yaml:"accessToken,omitempty"`
	RefreshToken string `json:"refreshToken,omitempty" yaml:"refreshToken,omitempty"`
}

type StartupHook struct {
	Command     CommandLine `json:"command" yaml:"command"`
	User        string      `json:"user,omitempty" yaml:"user,omitempty"`
	Background  bool        `json:"background,omitempty" yaml:"background,omitempty"`
	Env         []string    `json:"env,omitempty" yaml:"env,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
}

type Surface struct {
	NetworkInstallAllow []string `json:"networkInstallAllow,omitempty"`
	NetworkInstallDeny  []string `json:"networkInstallDeny,omitempty"`
	NetworkRuntimeAllow []string `json:"networkRuntimeAllow,omitempty"`
	NetworkRuntimeDeny  []string `json:"networkRuntimeDeny,omitempty"`

	// The HTTP lists are what may be done over the allowed connections,
	// one atomic entry per method, host, and path as "<METHOD>
	// <host><path>". A host with no allow rule bounding it appears under
	// every method, because that is what it grants. Kept apart from the
	// host lists because the two grant differently: a host list entry
	// opens a connection, while these bound what may be done over it, so
	// a gate naming both "network" could not say whether an update opened
	// a new host or widened an existing one.
	NetworkInstallHTTPAllow []string `json:"networkInstallHTTPAllow,omitempty"`
	NetworkInstallHTTPDeny  []string `json:"networkInstallHTTPDeny,omitempty"`
	NetworkRuntimeHTTPAllow []string `json:"networkRuntimeHTTPAllow,omitempty"`
	NetworkRuntimeHTTPDeny  []string `json:"networkRuntimeHTTPDeny,omitempty"`

	CredentialsInstall []string `json:"credentialsInstall,omitempty"`
	CredentialsRuntime []string `json:"credentialsRuntime,omitempty"`

	// SSHAgent holds what the SSH agent may sign, per phase: "<phase>"
	// for an unbounded grant, "<phase> sign <namespace>" and "<phase>
	// authenticate <[user@]host>" for a bounded one. Kept apart from
	// credentials because the agent grants more than one service: an
	// unbounded grant signs with every key it holds, for anything the
	// sandbox asks.
	SSHAgent []string `json:"sshAgent,omitempty"`

	StoragePaths []string `json:"storagePaths,omitempty"`

	// HostMountPaths grant access to host-shared directories. Keeping
	// them apart from sandbox storage makes a change to host sharing a
	// widening even when the in-container destination stays the same.
	HostMountPaths []string `json:"hostMountPaths,omitempty"`

	// SkillsPaths are the in-container paths the host's shared skills
	// store is asked for. Kept apart from StoragePaths because the two
	// grant different things: a volume is storage the sandbox is given,
	// while this is a host directory the user filled with `sbx skills
	// import` being handed to a kit. A gate naming both "storage" would
	// not say which one was gained.
	SkillsPaths []string `json:"skillsPaths,omitempty"`

	// SkillsWritePaths are the subset of SkillsPaths the kit asks to
	// write. Separate from the paths themselves so access cannot be
	// confused with a path: write is the larger grant, and a sandbox that
	// can rewrite the shared store affects every later one.
	SkillsWritePaths []string `json:"skillsWritePaths,omitempty"`
	Ports            []string `json:"ports,omitempty"`
	USB              []string `json:"usb,omitempty"`
	Privileged       bool     `json:"privileged,omitempty"`

	// Services holds one entry per requested runtime-provided service:
	// the type string, with a digest of the config when one is present,
	// so a config change moves the surface the way any widening does.
	// Optional requests are surfaced too — optional only changes what
	// happens when the host cannot provide the service, not what is
	// granted when it can.
	Services []string `json:"services,omitempty"`
}

type TokenEndpoint struct {
	Host string `json:"host" yaml:"host"`
	Path string `json:"path,omitempty" yaml:"path,omitempty"`
}

type USBDevice struct {
	VendorID  string `json:"vendorId,omitempty" yaml:"vendorId,omitempty"`
	ProductID string `json:"productId,omitempty" yaml:"productId,omitempty"`
	Class     string `json:"class,omitempty" yaml:"class,omitempty"`
}

type USBDeviceCapability struct {
	USBDevice

	Optional    bool
	Name        string
	Description string
}

type ValidationErrors []error

type Volume struct {
	Path string `json:"path" yaml:"path"`
	Size string `json:"size,omitempty" yaml:"size,omitempty"`
	// Tmpfs makes the path a tmpfs mount instead of a block volume.
	Tmpfs bool `json:"tmpfs,omitempty" yaml:"tmpfs,omitempty"`
	// Mode is an octal permission string, e.g. "1777".
	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type Widening struct {
	// Category names the permission class, e.g. "network.runtime.allow".
	Category string `json:"category"`
	// Detail is the specific grant being requested, human-readable.
	Detail string `json:"detail"`
}