From 7dca8d07b5b5a5f8efd36a4032a2e09544ffb201 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 26 Sep 2026 03:14:55 +1000 Subject: [PATCH] feat(kit): assemble a Kit container's launch from its plan and image Assemble turns an admitted Kit composition and the workload image's config into the harness spec (the image's user, never root; the image env plus the workspace, egress and credential sentinels; the launch argv and agent-sessions verbs), lifecycle hooks with their declared users and restricted environments (the image-derived baseline, egress settings, and only the runtime variables each hook declares), the Kit's files, and volume names stable per execution. --- internal/infrastructure/kit/launch.go | 185 +++++++++++++++++++++ internal/infrastructure/kit/launch_test.go | 157 +++++++++++++++++ 2 files changed, 342 insertions(+) create mode 100644 internal/infrastructure/kit/launch.go create mode 100644 internal/infrastructure/kit/launch_test.go diff --git a/internal/infrastructure/kit/launch.go b/internal/infrastructure/kit/launch.go new file mode 100644 index 000000000..7f0e210e0 --- /dev/null +++ b/internal/infrastructure/kit/launch.go @@ -0,0 +1,185 @@ +package kit + +import ( + "crypto/sha256" + "encoding/hex" + "regexp" + "slices" + "strings" + + "github.com/docker/sandbox-kit-spec/v3/spec" + + "github.com/samcharles93/archie-core/internal/agentexec" + "github.com/samcharles93/archie-core/internal/infrastructure/egress" +) + +const ( + // DefaultHarnessUser is the Kit agent user: the harness runs as it when + // the image names no user, or names root. + DefaultHarnessUser = "1000" + // WorkspaceDir is where a Kit container mounts the task worktree. + WorkspaceDir = "/workspace" + + installHookUser = "0" +) + +// hookBaseline is the platform baseline a hook sees besides its declared +// variables, taken from the image's environment, never the host's. +var hookBaseline = []string{"PATH", "HOME", "HOSTNAME", "TERM"} + +var unsafeVolumeChars = regexp.MustCompile(`[^a-zA-Z0-9_.-]`) + +// ImageConfig is the workload image's runtime contract. +type ImageConfig struct { + Entrypoint []string + Cmd []string + Env []string + User string +} + +// LaunchParams are the run-specific inputs to a Kit container. +type LaunchParams struct { + // Execution keys the Kit's volumes, so they survive retries of one + // WorkflowExecution and are never shared with another. + Execution string + ProxyToken string + CAPath string + // Bound lists the credential services the run credential carries. + Bound []string +} + +// Hook is one lifecycle hook, ready to exec in the container. +type Hook struct { + Argv []string + User string + Env []string + Background bool +} + +// Volume is one volume@1 path backed by a named volume. +type Volume struct { + Name string + Path string +} + +// Launch is everything archie needs to run a composed Kit for one run. +type Launch struct { + Harness agentexec.HarnessSpec + Install []Hook + Startup []Hook + Files []spec.File + Volumes []Volume +} + +// Assemble derives a Kit container's launch from its admitted plan and the +// workload image's config. The harness never runs as root, and no hook sees +// a variable it did not declare beyond the image-derived baseline and the +// egress settings every sandbox process needs. +func Assemble(p *Plan, img ImageConfig, params LaunchParams) (Launch, error) { + creds, err := spec.CredentialsOf(p.Capabilities) + if err != nil { + return Launch{}, err + } + lifecycle, err := spec.LifecycleOf(p.Capabilities) + if err != nil { + return Launch{}, err + } + volumes, err := spec.VolumesOf(p.Capabilities) + if err != nil { + return Launch{}, err + } + + proxyEnv := egress.ProxyEnv(params.ProxyToken, params.CAPath) + runtimeVars := map[string]string{"WORKSPACE_DIR": WorkspaceDir} + for _, c := range creds { + runtimeVars[credentialModeVar(c.Service)] = credentialMode(c, slices.Contains(params.Bound, c.Service)) + } + + l := Launch{Harness: agentexec.HarnessSpec{ + User: harnessUser(img.User), + Launch: slices.Concat(img.Entrypoint, img.Cmd), + Env: slices.Concat(img.Env, []string{"WORKSPACE_DIR=" + WorkspaceDir}, proxyEnv, egress.SentinelEnv(creds)), + }} + if s := p.Sessions; s != nil { + l.Harness.Prompt, l.Harness.Resume, l.Harness.Continue = s.Prompt, s.Resume, s.Continue + } + + baseline := slices.Concat(pick(img.Env, hookBaseline), proxyEnv) + if lifecycle != nil { + for _, h := range lifecycle.Install { + l.Install = append(l.Install, Hook{ + Argv: slices.Clone(h.Command), User: orDefault(h.User, installHookUser), + Env: slices.Concat(baseline, declared(h.Env, runtimeVars)), + }) + } + for _, h := range lifecycle.Startup { + l.Startup = append(l.Startup, Hook{ + Argv: slices.Clone(h.Command), User: orDefault(h.User, DefaultHarnessUser), + Env: slices.Concat(baseline, declared(h.Env, runtimeVars)), Background: h.Background, + }) + } + l.Files = lifecycle.Files + } + for _, v := range volumes { + l.Volumes = append(l.Volumes, Volume{Name: volumeName(params.Execution, v.Path), Path: v.Path}) + } + return l, nil +} + +func harnessUser(imageUser string) string { + name, _, _ := strings.Cut(imageUser, ":") + if name == "" || name == "root" || name == "0" { + return DefaultHarnessUser + } + return imageUser +} + +func credentialModeVar(service string) string { + return "SBX_CRED_" + strings.ToUpper(strings.ReplaceAll(service, "-", "_")) + "_MODE" +} + +func credentialMode(c spec.CredentialCapability, bound bool) string { + switch { + case !bound: + return "none" + case c.APIKey != nil: + return "apikey" + default: + return "oauth" + } +} + +// declared resolves a hook's declared variable names against the runtime +// variables archie provides; a name archie does not provide stays unset. +func declared(names []string, vars map[string]string) []string { + var env []string + for _, name := range names { + if v, ok := vars[name]; ok { + env = append(env, name+"="+v) + } + } + return env +} + +// pick returns the entries of env whose names are listed. +func pick(env, names []string) []string { + var out []string + for _, e := range env { + if name, _, _ := strings.Cut(e, "="); slices.Contains(names, name) { + out = append(out, e) + } + } + return out +} + +func orDefault(v, fallback string) string { + if v == "" { + return fallback + } + return v +} + +func volumeName(execution, path string) string { + sum := sha256.Sum256([]byte(path)) + return "archie-kit-" + unsafeVolumeChars.ReplaceAllString(execution, "_") + "-" + hex.EncodeToString(sum[:6]) +} diff --git a/internal/infrastructure/kit/launch_test.go b/internal/infrastructure/kit/launch_test.go new file mode 100644 index 000000000..afedbd5da --- /dev/null +++ b/internal/infrastructure/kit/launch_test.go @@ -0,0 +1,157 @@ +package kit + +import ( + "slices" + "strings" + "testing" + + "github.com/docker/sandbox-kit-spec/v3/spec" +) + +const launchKit = ` + - type: com.docker.sandbox/agent-sessions@1 + config: + prompt: [-p, "{{.Prompt}}"] + resume: [--resume, "{{.SessionID}}"] + - type: com.docker.sandbox/network-policy@1 + config: {install: {allow: [registry.example.com]}, 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"}]} + - type: com.docker.sandbox/volume@1 + config: {path: /home/agent/.cli/sessions, size: 1g} + - type: com.docker.sandbox/volume@1 + config: {path: /home/agent/.cli/history} + - type: com.docker.sandbox/lifecycle@1 + config: + install: + - command: echo "$WORKSPACE_DIR" > /etc/seeded + env: [WORKSPACE_DIR] + startup: + - command: [cli, warm-up] + env: [SBX_CRED_EXAMPLE_MODE, NOT_A_RUNTIME_VARIABLE] + - command: [cli, daemon] + user: "0" + background: true` + +func plan(t *testing.T) *Plan { + t.Helper() + p, err := Compose([]spec.Contribution{{Reference: "kit", Descriptor: descriptor(t, spec.KindWorkload, launchKit)}}) + if err != nil { + t.Fatalf("Compose: %v", err) + } + return p +} + +var image = ImageConfig{ + Entrypoint: []string{"/usr/local/bin/cli"}, + Cmd: []string{"--no-color"}, + Env: []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/agent", "IMAGE_ONLY=kept"}, + User: "agent", +} + +var params = LaunchParams{Execution: "exec-42", ProxyToken: "tok", CAPath: "/etc/archie/ca.pem", Bound: []string{"example"}} + +func TestAssembleHarness(t *testing.T) { + l, err := Assemble(plan(t), image, params) + if err != nil { + t.Fatal(err) + } + h := l.Harness + if !slices.Equal(h.Launch, []string{"/usr/local/bin/cli", "--no-color"}) { + t.Errorf("launch %v, want the image entrypoint then cmd", h.Launch) + } + if !slices.Equal(h.Prompt, []string{"-p", "{{.Prompt}}"}) || !slices.Equal(h.Resume, []string{"--resume", "{{.SessionID}}"}) { + t.Errorf("verbs prompt=%v resume=%v, want the Kit's agent-sessions verbs", h.Prompt, h.Resume) + } + if h.User != "agent" { + t.Errorf("user %q, want the image's user", h.User) + } + for _, want := range []string{ + "PATH=/usr/local/bin:/usr/bin:/bin", "IMAGE_ONLY=kept", + "WORKSPACE_DIR=/workspace", + "HTTPS_PROXY=http://archie:tok@archie-egress:3128", + "SSL_CERT_FILE=/etc/archie/ca.pem", + "EXAMPLE_KEY=archie-proxy-managed", + } { + if !slices.Contains(h.Env, want) { + t.Errorf("harness env lacks %q:\n%s", want, strings.Join(h.Env, "\n")) + } + } +} + +func TestAssembleNeverRunsTheHarnessAsRoot(t *testing.T) { + for _, user := range []string{"", "root", "0", "0:0"} { + img := image + img.User = user + l, err := Assemble(plan(t), img, params) + if err != nil { + t.Fatal(err) + } + if l.Harness.User != DefaultHarnessUser { + t.Errorf("image user %q gave harness user %q, want %q", user, l.Harness.User, DefaultHarnessUser) + } + } +} + +func TestAssembleHooks(t *testing.T) { + l, err := Assemble(plan(t), image, params) + if err != nil { + t.Fatal(err) + } + if len(l.Install) != 1 || len(l.Startup) != 2 { + t.Fatalf("install %d startup %d, want 1 and 2", len(l.Install), len(l.Startup)) + } + install := l.Install[0] + if !slices.Equal(install.Argv, []string{"sh", "-c", `echo "$WORKSPACE_DIR" > /etc/seeded`}) { + t.Errorf("a string command runs through the shell, as the Kit spec decodes it; got %v", install.Argv) + } + if install.User != "0" { + t.Errorf("install hook user %q, want root by default", install.User) + } + if !slices.Contains(install.Env, "WORKSPACE_DIR=/workspace") || !slices.Contains(install.Env, "HTTPS_PROXY=http://archie:tok@archie-egress:3128") { + t.Errorf("install env %v, want its declared variable and the egress baseline", install.Env) + } + warm := l.Startup[0] + if warm.User != DefaultHarnessUser { + t.Errorf("startup hook user %q, want the agent user by default", warm.User) + } + if !slices.Contains(warm.Env, "SBX_CRED_EXAMPLE_MODE=apikey") { + t.Errorf("startup env %v, want the bound credential's mode", warm.Env) + } + for _, e := range warm.Env { + if strings.HasPrefix(e, "NOT_A_RUNTIME_VARIABLE=") || strings.HasPrefix(e, "IMAGE_ONLY=") || strings.HasPrefix(e, "EXAMPLE_KEY=") { + t.Errorf("startup env carries %q, which it neither declared nor is baseline", e) + } + } + if daemon := l.Startup[1]; daemon.User != "0" || !daemon.Background { + t.Errorf("startup hook %+v, want its declared root user and background flag", daemon) + } +} + +func TestAssembleVolumesArePerExecution(t *testing.T) { + a, err := Assemble(plan(t), image, params) + if err != nil { + t.Fatal(err) + } + again, _ := Assemble(plan(t), image, params) + other := params + other.Execution = "exec-43" + b, _ := Assemble(plan(t), image, other) + if len(a.Volumes) != 2 { + t.Fatalf("volumes %v, want 2", a.Volumes) + } + if !slices.Equal(a.Volumes, again.Volumes) { + t.Error("volume names are not stable for one execution; a retry would lose its sessions") + } + if a.Volumes[0].Name == a.Volumes[1].Name { + t.Error("two paths share a volume") + } + for i := range a.Volumes { + if a.Volumes[i].Name == b.Volumes[i].Name { + t.Errorf("executions share volume %q", a.Volumes[i].Name) + } + } +}