diff --git a/go.mod b/go.mod index 9d11a61b5..d4483503b 100644 --- a/go.mod +++ b/go.mod @@ -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 diff --git a/go.sum b/go.sum index 2b3f9f19c..845daa065 100644 --- a/go.sum +++ b/go.sum @@ -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= diff --git a/internal/infrastructure/kit/kit.go b/internal/infrastructure/kit/kit.go new file mode 100644 index 000000000..6615beb25 --- /dev/null +++ b/internal/infrastructure/kit/kit.go @@ -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 +} diff --git a/internal/infrastructure/kit/kit_test.go b/internal/infrastructure/kit/kit_test.go new file mode 100644 index 000000000..9623c105a --- /dev/null +++ b/internal/infrastructure/kit/kit_test.go @@ -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) + } + }) + } +}