feat(kit): admit Kit v3 descriptors against archie's capability support

Decodes published descriptors from the manifest annotation, composes one
workload with its mixins through the Kit spec package, and applies the
runtime's support table: unsupported required capabilities refuse the
launch, optional ones are skipped and recorded, and forge or passthrough
credentials are refused. A composition must carry a headless prompt verb.
This commit is contained in:
sam committed 2026-09-26 02:23:11 +10:00
1 parent 2e07de667d
commit ad575879ee
4 files changed
+416 -1

No files matched your search

+2 -1
View File
@@ -17,12 +17,13 @@ require (
github.com/containerd/errdefs v1.0.0 // indirect
github.com/containerd/errdefs/pkg v0.3.0 // indirect
github.com/containerd/log v0.2.0 // indirect
github.com/containerd/platforms v0.2.1 // indirect
github.com/containerd/platforms v1.0.0-rc.5 // indirect
github.com/cpuguy83/dockercfg v0.3.2 // indirect
github.com/davidmz/go-pageant v1.0.2 // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/go-connections v0.8.1 // indirect
github.com/docker/go-units v0.5.0 // indirect
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6 // indirect
github.com/dustin/go-humanize v1.1.0 // indirect
github.com/ebitengine/purego v0.11.1 // indirect
github.com/emirpasic/gods v1.18.1 // indirect
+4
View File
@@ -107,6 +107,8 @@ github.com/containerd/log v0.2.0 h1:BewD/umNgVnoczglOpX8eRMyEy5t5iPlu5AIpnWDONc=
github.com/containerd/log v0.2.0/go.mod h1:/M7L7CXKcPTfNC74XzaK+5H5KbO5+4lJVpuVI6vRLoM=
github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
github.com/containerd/platforms v1.0.0-rc.5 h1:vXd569rDrz8LeMXzAnBsy6LADV5YtsD8oyaRarxdmSU=
github.com/containerd/platforms v1.0.0-rc.5/go.mod h1:lKlMXyLybmBedS/JJm11uDofzI8L2v0J2ZbYvNsbq1A=
github.com/containerd/typeurl/v2 v2.2.0/go.mod h1:8XOOxnyatxSWuG8OfsZXVnAF4iZfedjS/8UHSPJnX4g=
github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
@@ -130,6 +132,8 @@ github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUE
github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6 h1:co7vn6GgImYEGO/KPlhPRJT9i5EPWgOKcB9q7bNJlFQ=
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6/go.mod h1:MrWO4PN3/VYC5xF8eyI8U82Nv/agTHcN4IUzheqA90c=
github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
github.com/ebitengine/purego v0.11.1 h1:2zpWRSQNVKN4eKsKO9eM1ILDgWfYMY9GwqRmK6XeQ/0=
+173
View File
@@ -0,0 +1,173 @@
// Package kit decides whether archie can run a harness packaged as Kit v3
// images, and what it runs with. Descriptor grammar, validation and
// composition belong to the Kit spec package; this package owns only the
// runtime's half of the contract: which capability types archie implements,
// and the refusals that keep the host's guarantees intact.
package kit
import (
"errors"
"fmt"
"strings"
"github.com/docker/sandbox-kit-spec/v3/spec"
)
const (
typeCredential = "com.docker.sandbox/credential@1"
typeAgentSessions = "com.docker.sandbox/agent-sessions@1"
// contextPath is where the composed agent-context body is staged.
contextPath = "/usr/share/archie/agent-context.md"
)
// supported is every capability type archie provides. Anything else is
// refused when required and skipped when optional: approximating a type
// archie does not implement would grant a Kit something nobody reviewed.
var supported = map[string]bool{
typeCredential: true,
"com.docker.sandbox/network-policy@1": true,
"com.docker.sandbox/volume@1": true,
"com.docker.sandbox/lifecycle@1": true,
typeAgentSessions: true,
"com.docker.sandbox/agent-skills@1": true,
"com.docker.sandbox/agent-context@1": true,
"com.docker.sandbox/resources@1": true,
}
// forgeServices are credential services a harness never receives: the model
// never runs git, so it never holds a credential that could push.
var forgeServices = map[string]bool{
"github": true,
"gitlab": true,
"gitea": true,
"forgejo": true,
"bitbucket": true,
}
// Skip is an optional capability archie does not provide, recorded so the
// step that ran without it can say so.
type Skip struct {
Type string
Reason string
}
// Refusal is a required capability archie will not provide.
type Refusal struct {
Type string
Reason string
}
// RefusedError carries every refusal, so an operator fixes a Kit in one pass.
type RefusedError struct {
Refusals []Refusal
}
func (e *RefusedError) Error() string {
parts := make([]string, len(e.Refusals))
for i, r := range e.Refusals {
parts[i] = r.Type + ": " + r.Reason
}
return "kit refused: " + strings.Join(parts, "; ")
}
// Plan is what archie launches: the composed descriptor, the capabilities
// it provides, and what it skipped.
type Plan struct {
Descriptor *spec.Descriptor
Capabilities []spec.Capability
Skipped []Skip
Sessions *spec.AgentSessions
ContextSources []spec.ContextSource
}
// DecodePublished reads the descriptor from an image's manifest annotations
// and holds it to the published form: strict decoding, full validation, and
// no unexpanded build-phase args.
func DecodePublished(annotations map[string]string) (*spec.Descriptor, error) {
raw, ok := annotations[spec.AnnotationDescriptor]
if !ok {
return nil, fmt.Errorf("image is not a kit: no %s annotation", spec.AnnotationDescriptor)
}
d, err := spec.Decode([]byte(raw))
if err != nil {
return nil, err
}
if _, err := spec.ValidatePublished([]byte(raw), d); err != nil {
return nil, err
}
return d, nil
}
// Admit applies archie's capability support to one descriptor. Every
// required capability archie will not provide is collected into a
// RefusedError; optional ones are skipped.
func Admit(d *spec.Descriptor) (*Plan, error) {
plan := &Plan{Descriptor: d}
var refusals []Refusal
for _, c := range d.Capabilities {
reason, err := refusalReason(c)
if err != nil {
return nil, err
}
switch {
case reason == "":
plan.Capabilities = append(plan.Capabilities, c)
case c.Optional:
plan.Skipped = append(plan.Skipped, Skip{Type: c.Type, Reason: reason})
default:
refusals = append(refusals, Refusal{Type: c.Type, Reason: reason})
}
}
if len(refusals) > 0 {
return nil, &RefusedError{Refusals: refusals}
}
return plan, nil
}
// Compose merges one workload Kit and its mixins, in the order given, and
// admits the result. archie drives a harness headlessly, so the composition
// must carry an agent-sessions prompt verb.
func Compose(contributions []spec.Contribution) (*Plan, error) {
merged, err := spec.Merge(contributions, spec.MergeOptions{ContextPath: contextPath})
if err != nil {
return nil, err
}
if merged.Descriptor.Kind != spec.KindWorkload {
return nil, errors.New("kit composition has no workload: a harness needs exactly one base kit")
}
plan, err := Admit(merged.Descriptor)
if err != nil {
return nil, err
}
sessions, err := spec.AgentSessionsOf(plan.Capabilities)
if err != nil {
return nil, err
}
if sessions == nil || len(sessions.Prompt) == 0 {
return nil, fmt.Errorf("kit composition declares no %s prompt verb: archie cannot run it headlessly", typeAgentSessions)
}
plan.Sessions = sessions
plan.ContextSources = merged.ContextSources
return plan, nil
}
func refusalReason(c spec.Capability) (string, error) {
if !supported[c.Type] {
return "not provided by archie", nil
}
if c.Type != typeCredential {
return "", nil
}
var cred spec.Credential
if err := spec.DecodeCapabilityConfig(c, &cred); err != nil {
return "", err
}
if forgeServices[cred.Service] {
return fmt.Sprintf("service %q is a forge credential; harnesses never hold one", cred.Service), nil
}
if cred.OAuth != nil && cred.OAuth.Passthrough {
return fmt.Sprintf("service %q asks for OAuth passthrough; real tokens never enter the container", cred.Service), nil
}
return "", nil
}
+237
View File
@@ -0,0 +1,237 @@
package kit
import (
"errors"
"slices"
"strings"
"testing"
"github.com/docker/sandbox-kit-spec/v3/spec"
)
const sessions = `
- type: com.docker.sandbox/agent-sessions@1
config:
prompt: [-p, "{{.Prompt}}"]
resume: [--resume, "{{.SessionID}}"]`
func descriptor(t *testing.T, kind, capabilities string) *spec.Descriptor {
t.Helper()
d, err := spec.Decode([]byte("schemaVersion: \"3\"\nkind: " + kind + "\ncapabilities:" + capabilities + "\n"))
if err != nil {
t.Fatalf("fixture does not decode: %v", err)
}
return d
}
func refusedTypes(t *testing.T, err error) []string {
t.Helper()
var refused *RefusedError
if !errors.As(err, &refused) {
t.Fatalf("want *RefusedError, got %v", err)
}
var types []string
for _, r := range refused.Refusals {
types = append(types, r.Type)
}
return types
}
func TestAdmit(t *testing.T) {
tests := []struct {
name string
capabilities string
wantRefused []string
wantSkipped []string
wantAdmitted int
}{
{
name: "every supported type is admitted",
capabilities: sessions + `
- type: com.docker.sandbox/network-policy@1
config: {runtime: {allow: [api.example.com:443]}}
- type: com.docker.sandbox/credential@1
config:
service: example
phase: runtime
apiKey: {name: EXAMPLE_KEY, proxyManaged: true, inject: [{domain: api.example.com, header: Authorization, format: "Bearer %s"}]}
- type: com.docker.sandbox/volume@1
config: {path: /home/agent/.state, size: 1g}
- type: com.docker.sandbox/lifecycle@1
config: {startup: [{command: [true]}]}
- type: com.docker.sandbox/agent-skills@1
config: {path: /home/agent/.skills}
- type: com.docker.sandbox/agent-context@1
config: {content: be terse}
- type: com.docker.sandbox/resources@1
config: {memory: 2g}`,
wantAdmitted: 8,
},
{
name: "a required unsupported type refuses the launch",
capabilities: sessions + "\n - type: com.docker.sandbox/privileged@1",
wantRefused: []string{"com.docker.sandbox/privileged@1"},
},
{
name: "an optional unsupported type is skipped and recorded",
capabilities: sessions + `
- type: com.docker.sandbox/port@1
optional: true
config: {port: 8080}`,
wantSkipped: []string{"com.docker.sandbox/port@1"},
wantAdmitted: 1,
},
{
name: "network-policy@2 is refused",
capabilities: sessions + `
- type: com.docker.sandbox/network-policy@2
config: {runtime: {allow: [api.example.com]}}`,
wantRefused: []string{"com.docker.sandbox/network-policy@2"},
},
{
name: "a host-specific type archie does not know is refused",
capabilities: sessions + `
- type: example.com/gpu-broker@1
config: {pool: a}`,
wantRefused: []string{"example.com/gpu-broker@1"},
},
{
name: "a credential with passthrough is refused",
capabilities: sessions + `
- type: com.docker.sandbox/network-policy@1
config: {runtime: {allow: [api.example.com]}}
- type: com.docker.sandbox/credential@1
config:
service: example
phase: runtime
oauth: {tokenEndpoint: {host: api.example.com}, passthrough: true}`,
wantRefused: []string{"com.docker.sandbox/credential@1"},
},
{
name: "an optional forge credential is skipped, never bound",
capabilities: sessions + `
- type: com.docker.sandbox/network-policy@1
config: {runtime: {allow: [api.github.com]}}
- type: com.docker.sandbox/credential@1
optional: true
config:
service: github
phase: runtime
apiKey: {name: GH_TOKEN, proxyManaged: true, inject: [{domain: api.github.com, header: Authorization, format: "Bearer %s"}]}`,
wantSkipped: []string{"com.docker.sandbox/credential@1"},
wantAdmitted: 2,
},
{
name: "every refusal is reported, not only the first",
capabilities: sessions + `
- type: com.docker.sandbox/privileged@1
- type: com.docker.sandbox/long-running@1`,
wantRefused: []string{"com.docker.sandbox/privileged@1", "com.docker.sandbox/long-running@1"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
plan, err := Admit(descriptor(t, spec.KindWorkload, tt.capabilities))
if tt.wantRefused != nil {
if got := refusedTypes(t, err); !slices.Equal(got, tt.wantRefused) {
t.Fatalf("refused %v, want %v", got, tt.wantRefused)
}
return
}
if err != nil {
t.Fatalf("Admit: %v", err)
}
var skipped []string
for _, s := range plan.Skipped {
skipped = append(skipped, s.Type)
}
if !slices.Equal(skipped, tt.wantSkipped) {
t.Fatalf("skipped %v, want %v", skipped, tt.wantSkipped)
}
if len(plan.Capabilities) != tt.wantAdmitted {
t.Fatalf("admitted %d capabilities, want %d", len(plan.Capabilities), tt.wantAdmitted)
}
})
}
}
func TestRefusalNamesTheCapability(t *testing.T) {
_, err := Admit(descriptor(t, spec.KindWorkload, sessions+"\n - type: com.docker.sandbox/usb-device@1\n config: {class: hid}"))
if err == nil || !strings.Contains(err.Error(), "com.docker.sandbox/usb-device@1") {
t.Fatalf("error %v does not name the refused capability", err)
}
}
func TestCompose(t *testing.T) {
workload := spec.Contribution{Reference: "workload", Descriptor: descriptor(t, spec.KindWorkload, sessions)}
mixin := spec.Contribution{Reference: "mixin", Descriptor: descriptor(t, spec.KindMixin, `
- type: com.docker.sandbox/network-policy@1
config: {runtime: {allow: [api.example.com]}}
- type: com.docker.sandbox/credential@1
config:
service: example
phase: runtime
apiKey: {name: EXAMPLE_KEY, proxyManaged: true, inject: [{domain: api.example.com, header: x-api-key, format: "%s"}]}`)}
bareWorkload := spec.Contribution{Reference: "bare", Descriptor: descriptor(t, spec.KindWorkload, `
- type: com.docker.sandbox/resources@1
config: {memory: 1g}`)}
t.Run("a workload and its mixins compose into one plan", func(t *testing.T) {
plan, err := Compose([]spec.Contribution{workload, mixin})
if err != nil {
t.Fatalf("Compose: %v", err)
}
if !spec.HasCapability(plan.Capabilities, typeCredential) {
t.Fatal("the mixin's credential did not reach the plan")
}
if plan.Sessions == nil || len(plan.Sessions.Prompt) == 0 {
t.Fatal("the plan carries no headless prompt verb")
}
})
tests := []struct {
name string
contributions []spec.Contribution
want string
}{
{"no workload", []spec.Contribution{mixin}, "no workload"},
{"no headless prompt verb", []spec.Contribution{bareWorkload}, "agent-sessions"},
{"two workloads", []spec.Contribution{workload, bareWorkload}, "workload"},
}
for _, tt := range tests {
t.Run(tt.name+" is refused", func(t *testing.T) {
_, err := Compose(tt.contributions)
if err == nil || !strings.Contains(err.Error(), tt.want) {
t.Fatalf("error %v, want one mentioning %q", err, tt.want)
}
})
}
}
func TestDecodePublished(t *testing.T) {
published := "schemaVersion: \"3\"\nkind: workload\ncapabilities:" + sessions + "\n"
tests := []struct {
name string
annotations map[string]string
wantErr string
}{
{"a published descriptor decodes", map[string]string{spec.AnnotationDescriptor: published}, ""},
{"an image without the annotation is not a kit", map[string]string{"org.opencontainers.image.title": "x"}, "not a kit"},
{"an unknown field is an error", map[string]string{spec.AnnotationDescriptor: published + "surprise: true\n"}, "surprise"},
{"an unexpanded build arg is not a published form", map[string]string{spec.AnnotationDescriptor: "schemaVersion: \"3\"\nkind: workload\nversion: \"${{ kit.args.version }}\"\n"}, "version"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
d, err := DecodePublished(tt.annotations)
if tt.wantErr == "" {
if err != nil || d == nil {
t.Fatalf("DecodePublished: %v", err)
}
return
}
if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
t.Fatalf("error %v, want one mentioning %q", err, tt.wantErr)
}
})
}
}